Initial commit
This commit is contained in:
157
app/cache.py
Normal file
157
app/cache.py
Normal file
@@ -0,0 +1,157 @@
|
||||
"""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)
|
||||
Reference in New Issue
Block a user