cache: move coverage cache to disk for all windows/sources

Author: jackharrhy

src/where_the_plow/cache.py

@@ -1,17 +1,18 @@
 # src/where_the_plow/cache.py
-"""Simple file-based cache for coverage trail responses.
+"""Disk cache for coverage trail responses.
 
-Stores JSON in /tmp/where-the-plow-cache/ keyed by a hash of the
-(since, until) time range.  Only caches queries whose `until` is
-before today (i.e. fully historical, immutable data).  Uses LRU
-eviction by file access time when total cache size exceeds a budget.
+Stores JSON in /tmp/where-the-plow-cache/ keyed by a hash of
+(since, until, source). Each entry carries an absolute expiry time.
+Uses LRU-style eviction by file access time when total cache size
+exceeds a budget.
 """
 
 import hashlib
 import json
 import logging
 import os
 import tempfile
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -20,21 +21,29 @@
 CACHE_DIR = Path(tempfile.gettempdir()) / "where-the-plow-cache"
 MAX_CACHE_BYTES = 200 * 1024 * 1024  # 200 MB
 
+# Cache policy tuned for coverage endpoint
+RECENT_TTL_SECONDS = 5 * 60  # 5 minutes for live-ish windows
+HISTORICAL_TTL_SECONDS = 24 * 60 * 60  # 1 day for immutable historical windows
 
-def _cache_key(since: datetime, until: datetime) -> str:
-    raw = f"{since.isoformat()}|{until.isoformat()}"
-    return hashlib.sha256(raw.encode()).hexdigest()[:16]
 
+def _cache_key(since: datetime, until: datetime, source: str | None) -> str:
+    raw = f"{since.isoformat()}|{until.isoformat()}|{source or ''}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:24]
 
-def _is_cacheable(until: datetime) -> bool:
-    """Only cache if the entire window is in the past (before today UTC)."""
+
+def _is_historical(until: datetime) -> bool:
+    """Return True if window is fully in the past (before today UTC)."""
     today_start = datetime.now(timezone.utc).replace(
         hour=0, minute=0, second=0, microsecond=0
     )
     until_utc = until if until.tzinfo else until.replace(tzinfo=timezone.utc)
     return until_utc < today_start
 
 
+def _ttl_for(until: datetime) -> int:
+    return HISTORICAL_TTL_SECONDS if _is_historical(until) else RECENT_TTL_SECONDS
+
+
 def _ensure_dir():
     CACHE_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -48,7 +57,6 @@ def _evict_if_needed():
         total = sum(f.stat().st_size for f in files)
         if total <= MAX_CACHE_BYTES:
             return
-        # Sort by access time, oldest first
         files.sort(key=lambda f: f.stat().st_atime)
         for f in files:
             if total <= MAX_CACHE_BYTES:
@@ -61,32 +69,48 @@ def _evict_if_needed():
         pass
 
 
-def get(since: datetime, until: datetime) -> list[dict] | None:
-    """Return cached trails or None if not cached."""
-    if not _is_cacheable(until):
-        return None
-    path = CACHE_DIR / f"{_cache_key(since, until)}.json"
+def _delete_if_expired(path: Path, expires_at: float) -> bool:
+    if time.time() <= expires_at:
+        return False
+    try:
+        path.unlink(missing_ok=True)
+    except OSError:
+        pass
+    return True
+
+
+def get(since: datetime, until: datetime, source: str | None = None) -> list[dict] | None:
+    """Return cached trails or None."""
+    path = CACHE_DIR / f"{_cache_key(since, until, source)}.json"
     if not path.exists():
         return None
     try:
-        # Touch access time for LRU
+        payload = json.loads(path.read_text())
+        expires_at = float(payload.get("expires_at", 0))
+        trails = payload.get("trails")
+        if not isinstance(trails, list):
+            return None
+        if _delete_if_expired(path, expires_at):
+            return None
         os.utime(path)
-        data = json.loads(path.read_text())
         logger.debug("cache hit: %s", path.name)
-        return data
-    except (OSError, json.JSONDecodeError):
+        return trails
+    except (OSError, ValueError, json.JSONDecodeError):
         return None
 
 
-def put(since: datetime, until: datetime, trails: list[dict]):
-    """Store trails in cache if the query is cacheable."""
-    if not _is_cacheable(until):
-        return
+def put(since: datetime, until: datetime, trails: list[dict], source: str | None = None):
+    """Store trails in disk cache with endpoint-specific TTL policy."""
     _ensure_dir()
     _evict_if_needed()
-    path = CACHE_DIR / f"{_cache_key(since, until)}.json"
+    path = CACHE_DIR / f"{_cache_key(since, until, source)}.json"
+    ttl = _ttl_for(until)
+    payload = {
+        "expires_at": time.time() + ttl,
+        "trails": trails,
+    }
     try:
-        path.write_text(json.dumps(trails))
-        logger.debug("cache put: %s (%d trails)", path.name, len(trails))
+        path.write_text(json.dumps(payload))
+        logger.debug("cache put: %s (%d trails, ttl=%ds)", path.name, len(trails), ttl)
     except OSError:
         pass

src/where_the_plow/routes.py

@@ -42,40 +42,6 @@ def is_limited(self, key: str) -> bool:
 )  # 6 searches per min per IP
 
 
-# ── In-memory coverage cache for recent (non-historical) queries ──────
-
-_COVERAGE_TTL = 5 * 60  # 5 minutes — matches frontend rounding interval
-_COVERAGE_MAX = 20  # max entries before evicting oldest
-
-# key = (since_iso, until_iso, source|None)  ->  (expires_at_monotonic, trails)
-_coverage_cache: dict[tuple, tuple[float, list[dict]]] = {}
-
-
-def _coverage_cache_get(
-    since: datetime, until: datetime, source: str | None
-) -> list[dict] | None:
-    key = (since.isoformat(), until.isoformat(), source)
-    entry = _coverage_cache.get(key)
-    if entry is None:
-        return None
-    expires_at, trails = entry
-    if time.monotonic() > expires_at:
-        del _coverage_cache[key]
-        return None
-    return trails
-
-
-def _coverage_cache_put(
-    since: datetime, until: datetime, source: str | None, trails: list[dict]
-) -> None:
-    key = (since.isoformat(), until.isoformat(), source)
-    # Evict oldest if full
-    if len(_coverage_cache) >= _COVERAGE_MAX and key not in _coverage_cache:
-        oldest_key = min(_coverage_cache, key=lambda k: _coverage_cache[k][0])
-        del _coverage_cache[oldest_key]
-    _coverage_cache[key] = (time.monotonic() + _COVERAGE_TTL, trails)
-
-
 # ── Nominatim search proxy with in-memory cache ──────
 
 NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
@@ -368,21 +334,13 @@ def get_coverage(
     if until is None:
         until = now
 
-    # 1. In-memory cache (short TTL, works for recent/live queries)
-    trails = _coverage_cache_get(since, until, source)
+    # Disk cache for all windows/sources (short TTL for recent, longer for historical)
+    trails = cache.get(since, until, source=source)
     if trails is None:
-        # 2. File cache (historical queries only, no source filter)
-        if source is None:
-            trails = cache.get(since, until)
-        if trails is None:
-            trails = db.get_coverage_trails(
-                since=since, until=until, **({"source": source} if source else {})
-            )
-            # Populate file cache for historical queries
-            if source is None:
-                cache.put(since, until, trails)
-        # Populate in-memory cache for all queries
-        _coverage_cache_put(since, until, source, trails)
+        trails = db.get_coverage_trails(
+            since=since, until=until, **({"source": source} if source else {})
+        )
+        cache.put(since, until, trails, source=source)
 
     features = [
         CoverageFeature(