diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b54b974f..1aa3327b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -559,3 +559,28 @@ jobs: cd /tmp /tmp/smoke-sdist/bin/python -c "import fastapi_cache, importlib.metadata, pathlib; p=str(pathlib.Path(fastapi_cache.__file__).resolve()); assert 'site-packages' in p, p; assert importlib.metadata.version('fastapi-cache-stable'); print(p)" /tmp/smoke-sdist/bin/pip check + + bounded-inmemory-scalability: + name: Bounded InMemory 10k/100k write scaling (Python ${{ matrix.python }}) + runs-on: ubuntu-24.04 + timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + python: ["3.8", "3.12"] + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 + with: + python-version: ${{ matrix.python }} + - name: Install project with bounded runtime profile + run: | + python -m pip install --upgrade pip + if [ "${{ matrix.python }}" = "3.8" ]; then + python -m pip install -e . "fastapi==0.111.1" "pydantic==1.10.27" + else + python -m pip install -e . + fi + python -m pip check + - name: Enforce sublinear 10k/100k write scaling + run: python scripts/benchmark_bounded_inmemory.py --assert-scaling diff --git a/changelog.d/54.feature.md b/changelog.d/54.feature.md new file mode 100644 index 00000000..bb12ffb1 --- /dev/null +++ b/changelog.d/54.feature.md @@ -0,0 +1 @@ +Add an optional `InMemoryBackend(max_entries=...)` capacity limit with per-instance least-recently-used eviction, expired-entry cleanup before eviction, and no behavior change when omitted. The bound counts entries rather than payload bytes and does not synchronize separate worker processes. diff --git a/fastapi_cache/backends/inmemory.py b/fastapi_cache/backends/inmemory.py index 00a7dc69..460103fe 100644 --- a/fastapi_cache/backends/inmemory.py +++ b/fastapi_cache/backends/inmemory.py @@ -1,7 +1,14 @@ +"""In-process cache with optional bounded, per-instance LRU capacity. + +Unbounded default preserves historical lazy-expiration semantics. +Bounded writes use an indexed min-heap for expiry and an OrderedDict +for recency: O(log capacity), no full-store scans on ordinary writes. +""" + import time from asyncio import Lock from dataclasses import dataclass -from typing import Dict, Optional, Tuple +from typing import Dict, List, Optional, OrderedDict, Tuple from fastapi_cache.types import Backend @@ -12,11 +19,104 @@ class Value: ttl_ts: Optional[int] -class InMemoryBackend(Backend): +class _ExpirationIndex: + """Exact (no stale entries) indexed min-heap of (expiry, key). + + Unlike a lazy heap with generation tombstones, this needs at most + one heap entry per live cache key; overwrites and evictions remove + the old expiry in O(log n), without periodic O(n) heap compaction. + """ + def __init__(self) -> None: + self._heap: List[Tuple[int, str]] = [] + self._positions: Dict[str, int] = {} + + def __len__(self) -> int: + return len(self._heap) + + def _swap(self, left: int, right: int) -> None: + items = self._heap + items[left], items[right] = items[right], items[left] + self._positions[items[left][1]] = left + self._positions[items[right][1]] = right + + def _sift_up(self, index: int) -> None: + while index: + parent = (index - 1) // 2 + if self._heap[parent] <= self._heap[index]: + return + self._swap(parent, index) + index = parent + + def _sift_down(self, index: int) -> None: + length = len(self._heap) + while True: + left = index * 2 + 1 + if left >= length: + return + right = left + 1 + smallest = left + if right < length and self._heap[right] < self._heap[left]: + smallest = right + if self._heap[index] <= self._heap[smallest]: + return + self._swap(index, smallest) + index = smallest + + def discard(self, key: str) -> None: + index = self._positions.pop(key, None) + if index is None: + return + last = self._heap.pop() + if index == len(self._heap): + return + self._heap[index] = last + self._positions[last[1]] = index + if index and self._heap[index] < self._heap[(index - 1) // 2]: + self._sift_up(index) + else: + self._sift_down(index) + + def update(self, key: str, expires_at: Optional[int]) -> None: + self.discard(key) + if expires_at is None: + return + index = len(self._heap) + self._heap.append((expires_at, key)) + self._positions[key] = index + self._sift_up(index) + + def oldest_expired(self, now: int) -> Optional[str]: + if self._heap and self._heap[0][0] < now: + return self._heap[0][1] + return None + + +class InMemoryBackend(Backend): + def __init__(self, *, max_entries: Optional[int] = None) -> None: + if max_entries is not None and ( + isinstance(max_entries, bool) + or not isinstance(max_entries, int) + or max_entries < 1 + ): + raise ValueError("max_entries must be a positive integer or None") + # Capacity is fixed at construction: runtime resizing would require + # coordinated eviction and index rebuilding under the async lock. + self._max_entries = max_entries self._store: Dict[str, Value] = {} + self._recency: Optional[OrderedDict[str, None]] = ( + OrderedDict() if max_entries is not None else None + ) + self._expiry_index: Optional[_ExpirationIndex] = ( + _ExpirationIndex() if max_entries is not None else None + ) self._lock: Optional[Lock] = None + @property + def max_entries(self) -> Optional[int]: + """Immutable per-instance entry cap, or None for legacy unbounded mode.""" + return self._max_entries + def _get_lock(self) -> Lock: if self._lock is None: self._lock = Lock() @@ -26,12 +126,21 @@ def _get_lock(self) -> Lock: def _now(self) -> int: return int(time.time()) + def _discard(self, key: str) -> None: + self._store.pop(key, None) + if self._recency is not None: + self._recency.pop(key, None) + if self._expiry_index is not None: + self._expiry_index.discard(key) + def _get(self, key: str) -> Optional[Value]: v = self._store.get(key) if v: if v.ttl_ts is not None and v.ttl_ts < self._now: - del self._store[key] + self._discard(key) else: + if self._recency is not None: + self._recency.move_to_end(key) return v return None @@ -54,7 +163,23 @@ async def get(self, key: str) -> Optional[bytes]: async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None: async with self._get_lock(): ttl_ts = None if expire is None else self._now + expire + if self._recency is not None and self.max_entries is not None: + # Each new key needs at most ONE freed slot. Reclaim the + # earliest expired entry first, not an arbitrary live LRU + # entry. No scan and no unbounded cleanup under the lock. + if key not in self._store and len(self._store) >= self.max_entries: + assert self._expiry_index is not None # noqa: S101 + expired = self._expiry_index.oldest_expired(self._now) + if expired is not None: + self._discard(expired) + else: + self._discard(next(iter(self._recency))) self._store[key] = Value(value, ttl_ts) + if self._recency is not None: + self._recency[key] = None + self._recency.move_to_end(key) + if self._expiry_index is not None: + self._expiry_index.update(key, ttl_ts) async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int: count = 0 @@ -64,10 +189,10 @@ async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None keys = list(self._store.keys()) for cache_key in keys: if cache_key.startswith(boundary): - del self._store[cache_key] + self._discard(cache_key) count += 1 elif key: if key in self._store: - del self._store[key] + self._discard(key) count += 1 return count diff --git a/scripts/benchmark_bounded_inmemory.py b/scripts/benchmark_bounded_inmemory.py new file mode 100644 index 00000000..c227fb0b --- /dev/null +++ b/scripts/benchmark_bounded_inmemory.py @@ -0,0 +1,102 @@ +"""Bounded InMemory scaling gate: fill, full-capacity LRU and TTL reclaim. + +Run on both legacy Python 3.8 and supported modern Python. This test +benchmarks pure backend operations (not real request latency). +""" + +import argparse +import asyncio +import json +import sys +import time +from typing import Dict, Tuple + +from fastapi_cache.backends.inmemory import InMemoryBackend + + +class _FixedClockBackend(InMemoryBackend): + """Deterministic TTL benchmark: no real-time sleep or machine clock drift.""" + + def __init__(self, capacity: int) -> None: + super().__init__(max_entries=capacity) + self.now = 1000 + + @property + def _now(self) -> int: + return self.now + + +async def measure(capacity: int) -> Tuple[Dict[str, float], Dict[str, int]]: + value = b"small-payload" + backend = _FixedClockBackend(capacity) + start = time.perf_counter() + for i in range(capacity): + await backend.set("initial:" + str(i), value, expire=600) + fill = time.perf_counter() - start + + # Run a complete second capacity worth of NEW keys after the cache + # fills: every write MUST evict the least-recently-used live key. + start = time.perf_counter() + for i in range(capacity): + await backend.set("churn:" + str(i), value, expire=600) + churn = time.perf_counter() - start + if len(backend._store) != capacity: # pyright: ignore[reportPrivateUsage] + raise AssertionError("capacity violated during full LRU churn") + + expired_backend = _FixedClockBackend(capacity) + for i in range(capacity): + await expired_backend.set("stale:" + str(i), value, expire=1) + expired_backend.now = 1002 # All old entries have expired. + start = time.perf_counter() + for i in range(capacity): + await expired_backend.set("reclaimed:" + str(i), value, expire=600) + expiry_reclaim = time.perf_counter() - start + if len(expired_backend._store) != capacity: # pyright: ignore[reportPrivateUsage] + raise AssertionError("capacity violated during TTL reclaim") + if await expired_backend.get("stale:0") is not None: + raise AssertionError("expired keys were not reclaimed") + + return ( + {"fill": fill, "full_lru_churn": churn, "full_expiry_reclaim": expiry_reclaim}, + {"fill": capacity, "full_lru_churn": capacity, "full_expiry_reclaim": capacity}, + ) + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--assert-scaling", action="store_true") + args = parser.parse_args() + + asyncio.run(measure(300)) # Warm up imports/loop and code paths. + results = {} + for capacity in (10_000, 100_000): + durations, counts = asyncio.run(measure(capacity)) + results[capacity] = { + "seconds": durations, + "ms_per_write": { + key: durations[key] * 1000 / counts[key] for key in durations + }, + } + growth = { + key: results[100_000]["ms_per_write"][key] / + results[10_000]["ms_per_write"][key] + for key in ("fill", "full_lru_churn", "full_expiry_reclaim") + } + print(json.dumps({ + "python": sys.version.split()[0], + "capacity": [10_000, 100_000], + "measurements": results, + "per_write_growth_100k_vs_10k": growth, + "note": "CI microbenchmark, not endpoint latency or payload-byte bound", + }, indent=2)) + if args.assert_scaling: + for operation, ratio in growth.items(): + if ratio > 4.5: + raise AssertionError( + f"{operation} grew {ratio:.2f}x per write from 10k to 100k; " + "an O(N) scan or regression is likely." + ) + + +if __name__ == "__main__": + main() diff --git a/tests/test_bounded_inmemory.py b/tests/test_bounded_inmemory.py new file mode 100644 index 00000000..0a6f5e95 --- /dev/null +++ b/tests/test_bounded_inmemory.py @@ -0,0 +1,287 @@ +"""Opt-in bounded InMemory regression contract (#54). + +No change is allowed to the unbounded default, cache key format or +per-instance scoping. All tests run against the public Backend protocol. +""" + +import asyncio +from typing import Dict, Generator + +import pytest +from fastapi import FastAPI +from starlette.testclient import TestClient + +from fastapi_cache import FastAPICache +from fastapi_cache.backends.inmemory import InMemoryBackend +from fastapi_cache.decorator import cache + + +@pytest.fixture(autouse=True) +def _reset_cache() -> Generator[None, None, None]: + FastAPICache.reset() + yield + FastAPICache.reset() + + +@pytest.mark.parametrize("invalid", [0, -1, True, False, 1.5, "3", object()]) +def test_invalid_max_entries_fails_closed(invalid: object) -> None: + with pytest.raises(ValueError, match="max_entries must be"): + InMemoryBackend(max_entries=invalid) # type: ignore[arg-type] + + +@pytest.mark.parametrize("initial", [None, 2]) +@pytest.mark.parametrize("attempt", [None, 0, 1, 2, 5, -1, True, "3"]) +def test_max_entries_is_read_only_after_initialization( + initial: object, attempt: object +) -> None: + """Neither shrinking, disabling nor replacing the validated cap is legal.""" + backend = InMemoryBackend(max_entries=initial) # type: ignore[arg-type] + with pytest.raises(AttributeError): + setattr(backend, "max_entries", attempt) # noqa: B010 - test descriptor + assert backend.max_entries == initial + + +def test_mutation_attempt_cannot_violate_bounded_lru_capacity() -> None: + """The auditor's shrink-to-one reproduction must now fail closed.""" + async def run() -> None: + backend = InMemoryBackend(max_entries=2) + await backend.set("a", b"a") + await backend.set("b", b"b") + with pytest.raises(AttributeError): + backend.max_entries = 1 # type: ignore[misc] + with pytest.raises(AttributeError): + backend.max_entries = None # type: ignore[misc] + with pytest.raises(AttributeError): + backend.max_entries = -1 # type: ignore[misc] + await backend.set("c", b"c") + assert backend.max_entries == 2 + assert list(backend._store) == ["b", "c"] # pyright: ignore[reportPrivateUsage] + assert await backend.get("a") is None + assert await backend.get("b") == b"b" + assert await backend.get("c") == b"c" + assert len(backend._store) == 2 # pyright: ignore[reportPrivateUsage] + assert backend._recency is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._recency) == 2 # pyright: ignore[reportPrivateUsage] + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 0 # pyright: ignore[reportPrivateUsage] + + asyncio.run(run()) + + +def test_default_remains_unbounded_and_backward_compatible() -> None: + async def run() -> None: + backend = InMemoryBackend() + assert backend.max_entries is None + for i in range(101): + await backend.set("demo:" + str(i), str(i).encode(), expire=None) + for i in range(101): + assert await backend.get("demo:" + str(i)) == str(i).encode() + assert len(backend._store) == 101 # pyright: ignore[reportPrivateUsage] + assert backend._recency is None # pyright: ignore[reportPrivateUsage] + assert await backend.get_with_ttl("demo:1") == (-1, b"1") + asyncio.run(run()) + + +def test_capacity_evicts_least_recently_read_or_updated() -> None: + async def run() -> None: + backend = InMemoryBackend(max_entries=2) + await backend.set("app:a", b"A", expire=100) + await backend.set("app:b", b"B", expire=100) + assert await backend.get("app:a") == b"A" # LRU: b, a + await backend.set("app:c", b"C", expire=100) + assert await backend.get("app:b") is None + assert await backend.get("app:a") == b"A" + assert await backend.get("app:c") == b"C" + # Replacing an existing key refreshes its recency without extra slots. + await backend.set("app:a", b"A2", expire=None) + await backend.set("app:d", b"D", expire=None) + assert await backend.get("app:c") is None + assert await backend.get("app:a") == b"A2" + assert await backend.get("app:d") == b"D" + assert len(backend._store) == 2 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_ttl_reclaims_expired_unvisited_keys_before_eviction( + monkeypatch: pytest.MonkeyPatch, +) -> None: + now = [1000] + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: now[0]) + + async def run() -> None: + backend = InMemoryBackend(max_entries=2) + await backend.set("n:live", b"keep", expire=50) + assert await backend.get_with_ttl("n:live") == (50, b"keep") + # The expiring entry is *newer* than the live one: a naive + # LRU-only eviction would drop live data and keep the stale key. + await backend.set("n:expired", b"old", expire=5) + now[0] = 1006 + await backend.set("n:new", b"new", expire=50) + assert await backend.get("n:expired") is None + assert await backend.get("n:live") == b"keep" + assert await backend.get("n:new") == b"new" + assert len(backend._store) == 2 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_expire_none_and_scoped_clear_keep_lru_consistent() -> None: + async def run() -> None: + backend = InMemoryBackend(max_entries=3) + await backend.set("app:a:1", b"one", expire=None) + await backend.set("app:a:2", b"two", expire=None) + await backend.set("app:ab:3", b"three", expire=None) + assert await backend.clear(namespace="app:a") == 2 + assert await backend.get("app:ab:3") == b"three" + await backend.set("app:a:4", b"four", expire=None) + assert await backend.clear(key="app:ab:3") == 1 + await backend.set("app:a:5", b"five", expire=None) + await backend.set("app:a:6", b"six", expire=None) + assert await backend.get_with_ttl("app:a:4") == (-1, b"four") + assert await backend.get("app:a:5") == b"five" + assert await backend.get("app:a:6") == b"six" + assert len(backend._store) == 3 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_instances_keep_independent_capacity_and_evictions() -> None: + async def run() -> None: + first = InMemoryBackend(max_entries=1) + second = InMemoryBackend(max_entries=1) + await first.set("app:a", b"first", expire=None) + await second.set("app:a", b"second", expire=None) + await first.set("app:b", b"b", expire=None) + assert await first.get("app:a") is None + assert await second.get("app:a") == b"second" + assert await second.get("app:b") is None + asyncio.run(run()) + + +def test_concurrent_writes_and_reads_respect_max_entries() -> None: + async def run() -> None: + backend = InMemoryBackend(max_entries=7) + + async def write_and_read(i: int) -> None: + key = "n:" + str(i) + await backend.set(key, str(i).encode(), expire=60) + await backend.get_with_ttl(key) + + await asyncio.gather(*(write_and_read(i) for i in range(180))) + assert len(backend._store) <= 7 # pyright: ignore[reportPrivateUsage] + assert backend._recency is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._recency) == len(backend._store) # pyright: ignore[reportPrivateUsage] + for key in list(backend._store): # pyright: ignore[reportPrivateUsage] + assert await backend.get(key) is not None + + asyncio.run(run()) + + +def test_fastapi_http_lru_miss_hit_and_eviction() -> None: + backend = InMemoryBackend(max_entries=1) + FastAPICache.init(backend, prefix="http-test") + app = FastAPI() + calls = {"n": 0} + + @app.get("/value/{value}") + @cache(expire=60) + async def value(value: str) -> Dict[str, str]: + calls["n"] += 1 + return {"value": value, "count": str(calls["n"])} + + with TestClient(app) as client: + first = client.get("/value/a") + hit = client.get("/value/a") + other = client.get("/value/b") + evicted = client.get("/value/a") + assert [r.headers["X-FastAPI-Cache"] for r in + (first, hit, other, evicted)] == ["MISS", "HIT", "MISS", "MISS"] + assert first.json() == hit.json() + assert first.json() != evicted.json() + assert other.json()["value"] == "b" + + +def test_expiry_heap_does_not_accumulate_stale_entries_after_overwrites() -> None: + async def run() -> None: + backend = InMemoryBackend(max_entries=3) + for i in range(2000): + await backend.set("app:repeat", str(i).encode(), expire=3600) + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 1 # pyright: ignore[reportPrivateUsage] + assert len(backend._store) == 1 # pyright: ignore[reportPrivateUsage] + await backend.set("app:repeat", b"forever", expire=None) + assert len(backend._expiry_index) == 0 # pyright: ignore[reportPrivateUsage] + assert await backend.get("app:repeat") == b"forever" + await backend.set("app:a", b"a", expire=30) + await backend.set("app:b", b"b", expire=30) + await backend.set("app:c", b"c", expire=30) + assert len(backend._expiry_index) == 3 # pyright: ignore[reportPrivateUsage] + assert len(backend._store) == 3 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_expiration_index_updates_and_clear_delete_correct_entries( + monkeypatch: pytest.MonkeyPatch, +) -> None: + now = [1000] + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: now[0]) + + async def run() -> None: + backend = InMemoryBackend(max_entries=2) + await backend.set("app:a", b"a", expire=2) + await backend.set("app:b", b"b", expire=12) + # Overwriting changes an existing TTL; old heap record must disappear. + await backend.set("app:a", b"fresh", expire=100) + now[0] = 1003 + await backend.set("app:c", b"c", expire=100) + assert await backend.get("app:a") == b"fresh" + assert await backend.get("app:b") is None + assert await backend.get("app:c") == b"c" + assert await backend.clear(namespace="app") == 2 + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 0 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_bounded_entries_remain_bounded_during_key_churn() -> None: + async def run() -> None: + backend = InMemoryBackend(max_entries=64) + for i in range(5000): + await backend.set(f"stress:{i}", b"x", expire=60) + assert len(backend._store) == 64 # pyright: ignore[reportPrivateUsage] + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 64 # pyright: ignore[reportPrivateUsage] + assert backend._recency is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._recency) == 64 # pyright: ignore[reportPrivateUsage] + asyncio.run(run()) + + +def test_expiry_heap_rebalances_upward_after_middle_key_removal( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Removing a non-tail expiry can move the heap tail above its parent.""" + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: 1000) + + async def run() -> None: + backend = InMemoryBackend(max_entries=7) + # In insertion order these expire at: + # 1 + # 10 2 + # 20 30 3 4 + # Removing the 20 moves 4 below 10: it must sift UP, not down. + for index, ttl in enumerate((1, 10, 2, 20, 30, 3, 4)): + await backend.set(f"heap:{index}", str(index).encode(), expire=ttl) + assert await backend.clear(key="heap:3") == 1 + assert await backend.get("heap:3") is None + assert await backend.get("heap:6") == b"6" + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 6 # pyright: ignore[reportPrivateUsage] + + # A later expiry reclaim must still select the earliest actual TTL. + now = 1003 # ttl=1 expired, ttl=4 still valid + monkeypatch.setattr( + "fastapi_cache.backends.inmemory.time.time", lambda: now + ) + await backend.set("heap:new", b"new", expire=30) + assert await backend.get("heap:0") is None + assert await backend.get("heap:6") is not None + + asyncio.run(run()) diff --git a/tests/test_bounded_inmemory_adversarial.py b/tests/test_bounded_inmemory_adversarial.py new file mode 100644 index 00000000..61d203ce --- /dev/null +++ b/tests/test_bounded_inmemory_adversarial.py @@ -0,0 +1,125 @@ +"""Independent adversarial regressions for #85's indexed heap and lock. + +These tests exercise invariants beyond the seed/state machine in the original +feature branch. No external cache, clock sleeps, or additional dependencies. +""" + +import asyncio +import random +from typing import Dict, Optional + +import pytest + +from fastapi_cache.backends.inmemory import InMemoryBackend, _ExpirationIndex + + +@pytest.mark.parametrize("seed", range(12)) +def test_indexed_heap_exactness_under_direct_arbitrary_mutations(seed: int) -> None: + """Compare all heap positions and expiry minima against a simple oracle.""" + rng = random.Random(seed) # noqa: S311 - deterministic invariant testing + index = _ExpirationIndex() + expected: Dict[str, int] = {} + names = [f"key:{i}" for i in range(47)] + + for _ in range(1800): + name = rng.choice(names) + action = rng.randrange(100) + if action < 55: + expiry: Optional[int] = rng.choice( + [None, -10, -1, 0, 0, 0, 1, 1, 3, 10, 100] + ) + index.update(name, expiry) + expected.pop(name, None) + if expiry is not None: + expected[name] = expiry + elif action < 80: + index.discard(name) + expected.pop(name, None) + else: + now = rng.choice([-10, -1, 0, 1, 2, 10, 100, 101]) + earliest = min( + ((expiry, key) for key, expiry in expected.items()), + default=None, + ) + actual = index.oldest_expired(now) + wanted = ( + earliest[1] + if earliest is not None and earliest[0] < now + else None + ) + assert actual == wanted + + heap = index._heap # pyright: ignore[reportPrivateUsage] + positions = index._positions # pyright: ignore[reportPrivateUsage] + assert len(index) == len(expected) + assert len(heap) == len(positions) == len(expected) + assert {key: expiry for expiry, key in heap} == expected + assert set(positions) == set(expected) + for position, (expiry, key) in enumerate(heap): + assert positions[key] == position + if position: + assert heap[(position - 1) // 2] <= (expiry, key) + + +def test_get_with_ttl_updates_lru_order_without_changing_expiry( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """get_with_ttl is a successful access and must protect the read key.""" + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: 1000) + + async def run() -> None: + backend = InMemoryBackend(max_entries=2) + await backend.set("cache:a", b"a", expire=9) + await backend.set("cache:b", b"b", expire=9) + assert await backend.get_with_ttl("cache:a") == (9, b"a") + await backend.set("cache:c", b"c", expire=9) + assert await backend.get("cache:a") == b"a" + assert await backend.get("cache:b") is None + assert await backend.get("cache:c") == b"c" + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 2 # pyright: ignore[reportPrivateUsage] + + asyncio.run(run()) + + +def test_cancelled_waiter_cannot_modify_heap_or_store() -> None: + """A task cancelled while awaiting the lock does not partly write.""" + async def run() -> None: + backend = InMemoryBackend(max_entries=1) + await backend.set("n:keep", b"keep", expire=30) + async with backend._get_lock(): # pyright: ignore[reportPrivateUsage] + waiting = asyncio.create_task(backend.set("n:cancel", b"x", expire=1)) + await asyncio.sleep(0) + waiting.cancel() + with pytest.raises(asyncio.CancelledError): + await waiting + + assert await backend.get("n:keep") == b"keep" + assert await backend.get("n:cancel") is None + assert len(backend._store) == 1 # pyright: ignore[reportPrivateUsage] + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 1 # pyright: ignore[reportPrivateUsage] + assert backend._recency is not None # pyright: ignore[reportPrivateUsage] + assert list(backend._recency) == ["n:keep"] # pyright: ignore[reportPrivateUsage] + + asyncio.run(run()) + + +def test_same_second_ttl_boundary_matches_existing_contract( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Exact TTL timestamp is still accessible, then expires one second later.""" + now = [1000] + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: now[0]) + + async def run() -> None: + backend = InMemoryBackend(max_entries=1) + await backend.set("n:edge", b"edge", expire=0) + assert await backend.get_with_ttl("n:edge") == (0, b"edge") + now[0] = 1001 + assert await backend.get("n:edge") is None + assert len(backend._store) == 0 # pyright: ignore[reportPrivateUsage] + assert backend._expiry_index is not None # pyright: ignore[reportPrivateUsage] + assert len(backend._expiry_index) == 0 # pyright: ignore[reportPrivateUsage] + + asyncio.run(run()) diff --git a/tests/test_bounded_inmemory_fuzz.py b/tests/test_bounded_inmemory_fuzz.py new file mode 100644 index 00000000..718dfd61 --- /dev/null +++ b/tests/test_bounded_inmemory_fuzz.py @@ -0,0 +1,122 @@ +"""Seeded state-machine regression for the indexed TTL heap and LRU (#54).""" + +import asyncio +import random +from collections import OrderedDict +from typing import Dict, Optional, Tuple +from typing import OrderedDict as OrderedDictType + +import pytest + +from fastapi_cache.backends.inmemory import InMemoryBackend + +Entry = Tuple[bytes, Optional[int]] + + +@pytest.mark.parametrize("seed", range(20)) +def test_seeded_bounded_inmemory_fuzz( + seed: int, monkeypatch: pytest.MonkeyPatch +) -> None: + """20 deterministic seeds × 2,000 reads/writes/TTL/clears, no Hypothesis dep.""" + now = [1000] + monkeypatch.setattr("fastapi_cache.backends.inmemory.time.time", lambda: now[0]) + rng = random.Random(seed) # noqa: S311 - deterministic test data, not security + capacity = 1 + seed % 17 + reference: OrderedDictType[str, Entry] = OrderedDict() + + def reference_get(key: str) -> Optional[Entry]: + val = reference.get(key) + if val is not None: + if val[1] is not None and val[1] < now[0]: + del reference[key] + return None + reference.move_to_end(key) + return val + + def reference_set(key: str, value: bytes, expire: Optional[int]) -> None: + if key not in reference and len(reference) >= capacity: + candidates = sorted( + (ttl, k) + for k, (_, ttl) in reference.items() + if ttl is not None and ttl < now[0] + ) + if candidates: + del reference[candidates[0][1]] + else: + reference.popitem(last=False) + reference[key] = (value, None if expire is None else now[0] + expire) + reference.move_to_end(key) + + def reference_clear(namespace: Optional[str] = None, key: Optional[str] = None) -> int: + if namespace: + keys = [k for k in reference if k.startswith(namespace + ":")] + for k in keys: + del reference[k] + return len(keys) + if key and key in reference: + del reference[key] + return 1 + return 0 + + def assert_invariants(backend: InMemoryBackend) -> None: + store = backend._store # pyright: ignore[reportPrivateUsage] + recency = backend._recency # pyright: ignore[reportPrivateUsage] + index = backend._expiry_index # pyright: ignore[reportPrivateUsage] + assert recency is not None + assert index is not None + assert len(store) <= capacity + assert list(recency) == list(reference) + assert set(store) == set(reference) + for key, val in reference.items(): + assert store[key].data == val[0] + assert store[key].ttl_ts == val[1] + heap = index._heap # pyright: ignore[reportPrivateUsage] + positions: Dict[str, int] = index._positions # pyright: ignore[reportPrivateUsage] + expected_expiry = { + k: ttl for k, (_, ttl) in reference.items() if ttl is not None + } + assert len(heap) == len(positions) == len(expected_expiry) + assert set(positions) == set(expected_expiry) + for position, (ttl, key) in enumerate(heap): + assert positions[key] == position + assert ttl == expected_expiry[key] + if position: + assert heap[(position - 1) // 2] <= heap[position] + + async def run() -> None: + backend = InMemoryBackend(max_entries=capacity) + names = [ + f"{namespace}:{index}" for namespace in ("a", "ab", "b") + for index in range(30) + ] + for i in range(2000): + action = rng.randrange(100) + key = rng.choice(names) + if action < 48: + ttl = rng.choice([None, 0, 1, 2, 5, 12, 100]) + value = f"{seed}:{i}".encode() + reference_set(key, value, ttl) + await backend.set(key, value, expire=ttl) + elif action < 68: + item = reference_get(key) + assert await backend.get(key) == (None if item is None else item[0]) + elif action < 82: + item = reference_get(key) + expected_ttl = ( + (0, None) + if item is None + else ((-1, item[0]) if item[1] is None else (item[1] - now[0], item[0])) + ) + assert await backend.get_with_ttl(key) == expected_ttl + elif action < 90: + expected_n = reference_clear(key=key) + assert await backend.clear(key=key) == expected_n + elif action < 96: + namespace = rng.choice(["a", "ab", "b"]) + expected_n = reference_clear(namespace=namespace) + assert await backend.clear(namespace=namespace) == expected_n + else: + now[0] += rng.randrange(1, 7) + assert_invariants(backend) + + asyncio.run(run())