Add cache age tracking for staleness warnings

- cache.py: age_seconds(key) returns seconds since cache entry was written
- search.py: cache_age_seconds field on SearchReport and ScoredSearchReport,
  populated when results come from cache (max age across providers)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: federicodeponte

src/opensky/cache.py

@@ -93,6 +93,24 @@ def put(key: str, value: Any, ttl: int = _DEFAULT_TTL) -> None:
         tmp.replace(path)
 
 
+def age_seconds(key: str) -> int | None:
+    """Return seconds since this cache entry was written, or None if not cached/expired."""
+    path = _CACHE_DIR / f"{key}.json"
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        expires_at = data.get("expires_at")
+        if not expires_at:
+            return None
+        age = int(_DEFAULT_TTL - (expires_at - time.time()))
+        if age < 0:
+            return None  # entry expired
+        return age
+    except Exception:
+        return None
+
+
 def clear() -> None:
     _ensure_cache_dir()
     with _cache_lock:

src/opensky/search.py

@@ -40,13 +40,15 @@ class SearchReport:
     results: list[FlightResult]
     successful_providers: list[str] = field(default_factory=list)
     failed_providers: list[ProviderFailure] = field(default_factory=list)
+    cache_age_seconds: int | None = None
 
 
 @dataclass
 class ScoredSearchReport:
     results: list[ScoredFlight]
     successful_providers: list[str] = field(default_factory=list)
     failed_providers: list[ProviderFailure] = field(default_factory=list)
+    cache_age_seconds: int | None = None
 
 
 @dataclass
@@ -162,6 +164,7 @@ def search_one_report(
         all_results: list[FlightResult] = []
         successful_providers: list[str] = []
         failed_providers: list[ProviderFailure] = []
+        max_cache_age: int | None = None
 
         for provider in self._providers:
             ck = cache.cache_key(
@@ -175,6 +178,9 @@ def search_one_report(
                 if cached is not None:
                     successful_providers.append(provider.name)
                     all_results.extend(cached)
+                    age = cache.age_seconds(ck)
+                    if age is not None:
+                        max_cache_age = max(max_cache_age or 0, age)
                     continue
 
             try:
@@ -210,6 +216,7 @@ def search_one_report(
             results=all_results,
             successful_providers=successful_providers,
             failed_providers=failed_providers,
+            cache_age_seconds=max_cache_age,
         )
 
     def search_scored(
@@ -282,6 +289,7 @@ def search_scored_report(
             results=scored,
             successful_providers=search_report.successful_providers,
             failed_providers=search_report.failed_providers,
+            cache_age_seconds=search_report.cache_age_seconds,
         )
 
     def search_round_trip(