158 lines
6.0 KiB
Python
158 lines
6.0 KiB
Python
"""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)
|