"""Bounded in-memory TTL cache with per-key single-flight. The server keeps nothing on disk, which means every navigation click and every download is backed by a live FreshRSS API call. An OPDS reader browses a tree and re-requests feeds freely, so without a cache a single reader produces a small burst of API traffic per tap. This cache absorbs that burst and nothing more: entries expire on a short TTL and are evicted when the cache is full. Single-flight matters as much as caching here. Readers often open several connections at once (browsing navigation feeds in parallel, or prefetching cover requests), and without it a cold cache would issue the same FreshRSS request several times over. ``get_or_compute`` guarantees one in-flight computation per key while still letting unrelated keys run concurrently. """ from __future__ import annotations import logging import threading import time from collections.abc import Callable from typing import Any LOGGER = logging.getLogger(__name__) class TTLCache: """A thread-safe, size-bounded cache of values with a per-entry TTL.""" def __init__(self, max_entries: int = 512) -> None: # Config validation guarantees an int here, so no defensive coercion. self._max_entries = max(1, max_entries) self._lock = threading.Lock() self._values: dict[str, tuple[float, Any]] = {} self._key_locks: dict[str, threading.Lock] = {} self.hits = 0 self.misses = 0 self.evictions = 0 def get(self, key: str, *, now: float | None = None) -> Any | None: """Return a live value, or None when missing or expired.""" moment = time.monotonic() if now is None else now with self._lock: entry = self._values.get(key) if entry is None: self.misses += 1 return None expires_at, value = entry if expires_at <= moment: del self._values[key] self.misses += 1 return None # Re-insert so the newest entries sit at the end of the ordering and # the eviction below drops genuinely cold keys first. del self._values[key] self._values[key] = (expires_at, value) self.hits += 1 return value def set(self, key: str, value: Any, ttl_seconds: float) -> None: """Store a value, evicting the coldest entry if the cache is full.""" if ttl_seconds <= 0: return expires_at = time.monotonic() + ttl_seconds with self._lock: self._values.pop(key, None) self._values[key] = (expires_at, value) while len(self._values) > self._max_entries: oldest, _ = next(iter(self._values.items())) del self._values[oldest] self.evictions += 1 def get_or_compute(self, key: str, ttl_seconds: float, compute: Callable[[], Any]) -> Any: """Return a cached value, computing it at most once per key at a time. Exceptions from ``compute`` are never cached, so a transient FreshRSS failure is retried on the next request instead of being remembered. """ cached = self.get(key) if cached is not None: return cached with self._lock: key_lock = self._key_locks.get(key) if key_lock is None: key_lock = threading.Lock() self._key_locks[key] = key_lock with key_lock: # Another thread may have filled the key while this one waited. cached = self.get(key) if cached is not None: return cached value = compute() self.set(key, value, ttl_seconds) return value def invalidate(self, prefix: str = "") -> int: """Drop every key starting with ``prefix`` (all keys when empty).""" with self._lock: if not prefix: removed = len(self._values) self._values.clear() else: doomed = [key for key in self._values if key.startswith(prefix)] for key in doomed: del self._values[key] removed = len(doomed) # Collapse the lock table too: keys are unbounded over a long uptime # and a stale lock object is pure dead weight. if not prefix or removed: self._key_locks.clear() return removed def stats(self) -> dict[str, int]: """Return a snapshot for the diagnostics endpoint.""" with self._lock: return { "entries": len(self._values), "max_entries": self._max_entries, "hits": self.hits, "misses": self.misses, "evictions": self.evictions, } class FailureLatch: """Suppress a repeated failing optional call for a bounded period. Unread counts and upstream search are enhancements: when one of them is unsupported by the FreshRSS build in front of us, retrying on every request would add latency to every page load for no benefit. The latch remembers the failure for a TTL, reports it once on the way in, and then stays quiet. """ def __init__(self, ttl_seconds: float = 300.0) -> None: self._ttl = ttl_seconds self._locked_until: dict[str, float] = {} self._lock = threading.Lock() def is_open(self, key: str) -> bool: """True when calls for ``key`` should be attempted again.""" with self._lock: until = self._locked_until.get(key, 0.0) return time.monotonic() >= until def trip(self, key: str) -> bool: """Mark ``key`` failed; return True the first time within the window.""" with self._lock: now = time.monotonic() first = now >= self._locked_until.get(key, 0.0) self._locked_until[key] = now + self._ttl return first def clear(self, key: str) -> None: with self._lock: self._locked_until.pop(key, None)