Initial commit

This commit is contained in:
2026-11-15 18:15:03 -05:00
commit b76aea2899
36 changed files with 9424 additions and 0 deletions

157
app/cache.py Normal file
View 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)