cachefence 0.1.0__py3-none-any.whl

cachefence/__init__.py

@@ -0,0 +1,32 @@
+"""cachefence — cache-aside for Redis without the stampede.
+
+When a hot key expires, naive cache-aside lets every concurrent request miss at
+once and hammer your database to rebuild the same value. cachefence prevents that
+with two cooperating mechanisms:
+
+1. Probabilistic early recomputation (XFetch): a single worker is nudged to
+   refresh the value *before* it actually expires, so the key rarely goes cold.
+2. A distributed lock: if the value is gone, exactly one worker rebuilds it while
+   everyone else briefly waits or serves the stale value.
+
+Basic usage::
+
+    from redis.asyncio import Redis
+    from cachefence import CacheFence
+
+    redis = Redis()
+    cache = CacheFence(redis)
+
+    async def get_user(user_id: int) -> dict:
+        return await cache.get_or_set(
+            key=f"user:{user_id}",
+            ttl=60,
+            recompute=lambda: load_user_from_db(user_id),
+        )
+"""
+
+from .cache import CacheFence
+from .errors import CacheFenceError, RecomputeError
+
+__all__ = ["CacheFence", "CacheFenceError", "RecomputeError"]
+__version__ = "0.1.0"

cachefence/cache.py

@@ -0,0 +1,270 @@
+"""Core CacheFence implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import math
+import random
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar, cast
+
+from redis.asyncio import Redis
+
+from .errors import RecomputeError
+
+T = TypeVar("T")
+Recompute = Callable[[], "Awaitable[T] | T"]
+Serializer = Callable[[object], bytes]
+Deserializer = Callable[[bytes], object]
+
+# Compare-and-delete: release the lock only if we still own it. Prevents a worker
+# whose lock already expired from deleting a lock another worker now holds. Runs as
+# a Lua script by default; if the server rejects scripting at runtime we fall back
+# to a WATCH/MULTI transaction, which gives the same atomic guarantee.
+_RELEASE_LOCK = """
+if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+else
+    return 0
+end
+"""
+
+# Field names inside the cache hash. The value field is the one read on every
+# hit, so it gets a one-byte name; the metadata fields stay spelled out.
+_F_VALUE = b"v"
+_F_DELTA = b"delta"
+_F_EXPIRY = b"expiry"
+
+
+def _default_serializer(value: object) -> bytes:
+    return json.dumps(value).encode()
+
+
+def _default_deserializer(raw: bytes) -> object:
+    return json.loads(raw)
+
+
+@dataclass(frozen=True, slots=True)
+class _Entry:
+    """A value read back from the cache, with the metadata XFetch needs."""
+
+    value: object
+    delta: float   # seconds the last recompute took
+    expiry: float  # absolute unix time at which the value goes stale
+
+
+class CacheFence(Generic[T]):
+    """Cache-aside helper for Redis with built-in stampede protection.
+
+    Parameters
+    ----------
+    redis:
+        A ``redis.asyncio.Redis`` client. It is used in raw-bytes mode
+        internally, so ``decode_responses`` on the client is irrelevant.
+    beta:
+        XFetch aggressiveness. Higher refreshes earlier. ``1.0`` is the value
+        from the original paper and a sensible default.
+    lock_timeout:
+        Seconds a rebuild lock is held before it auto-expires, so a crashed
+        worker cannot block rebuilds forever.
+    wait_for_lock:
+        Maximum seconds a worker waits for another worker's rebuild before
+        rebuilding the value itself.
+    serializer / deserializer:
+        Convert values to/from the ``bytes`` stored in Redis. Defaults to JSON.
+    namespace:
+        Optional prefix applied to every key.
+    """
+
+    __slots__ = (
+        "_redis", "_beta", "_lock_timeout", "_wait_for_lock",
+        "_dumps", "_loads", "_ns", "_release", "_lua_ok",
+    )
+
+    def __init__(
+        self,
+        redis: Redis[bytes],
+        *,
+        beta: float = 1.0,
+        lock_timeout: float = 10.0,
+        wait_for_lock: float = 5.0,
+        serializer: Serializer = _default_serializer,
+        deserializer: Deserializer = _default_deserializer,
+        namespace: str = "",
+    ) -> None:
+        self._redis = redis
+        self._beta = beta
+        self._lock_timeout = lock_timeout
+        self._wait_for_lock = wait_for_lock
+        self._dumps = serializer
+        self._loads = deserializer
+        self._ns = namespace
+        self._release = redis.register_script(_RELEASE_LOCK)
+        self._lua_ok = True  # flips to False if the server rejects scripting
+
+    def _key(self, key: str) -> str:
+        return f"{self._ns}{key}" if self._ns else key
+
+    @staticmethod
+    def _lock_key(rkey: str) -> str:
+        return f"{rkey}:lock"
+
+    async def get_or_set(
+        self,
+        key: str,
+        ttl: float,
+        recompute: Recompute[T],
+        *,
+        beta: float | None = None,
+    ) -> T:
+        """Return the cached value for ``key``, recomputing it if needed.
+
+        ``recompute`` may be sync or async. ``ttl`` is the fresh lifetime in
+        seconds. At most one worker recomputes at a time; the rest serve the
+        still-valid cached value or wait briefly, never stampeding the backing
+        store.
+        """
+        rkey = self._key(key)
+        beta = self._beta if beta is None else beta
+
+        entry = await self._read(rkey)
+        if entry is not None:
+            if not self._should_refresh_early(entry, beta):
+                return cast(T, entry.value)
+            # Near expiry: one worker wins the lock and refreshes ahead of time
+            # while everyone else keeps serving the value that is still valid.
+            token = await self._acquire(rkey)
+            if token is None:
+                return cast(T, entry.value)
+            try:
+                return await self._recompute_and_store(rkey, ttl, recompute)
+            finally:
+                await self._release_lock(rkey, token)
+
+        # Hard miss: the value is gone. Exactly one worker rebuilds it.
+        return await self._rebuild_on_miss(rkey, ttl, recompute)
+
+    async def invalidate(self, key: str) -> None:
+        """Delete a cached key so the next read recomputes it."""
+        await self._redis.delete(self._key(key))
+
+    # --- internals ---------------------------------------------------------
+
+    async def _read(self, rkey: str) -> _Entry | None:
+        data: dict[bytes, bytes] = await self._redis.hgetall(rkey)
+        raw = data.get(_F_VALUE)
+        if raw is None:
+            return None
+        return _Entry(
+            value=self._loads(raw),
+            delta=float(data[_F_DELTA]),
+            expiry=float(data[_F_EXPIRY]),
+        )
+
+    def _should_refresh_early(self, entry: _Entry, beta: float) -> bool:
+        # XFetch (Vattani et al., VLDB 2015): -ln(uniform(0,1]) is exponentially
+        # distributed; scaling it by delta*beta makes expensive-to-rebuild keys
+        # refresh earlier, spreading recomputes out instead of bunching them at
+        # expiry. The gap widens as we approach expiry, so the trigger probability
+        # rises smoothly toward 1.
+        gap = entry.delta * beta * -math.log(random.random() or 1e-12)
+        return time.time() + gap >= entry.expiry
+
+    async def _acquire(self, rkey: str) -> str | None:
+        """Try to take the rebuild lock. Return the ownership token, or None."""
+        token = uuid.uuid4().hex
+        acquired = await self._redis.set(
+            self._lock_key(rkey),
+            token,
+            nx=True,
+            px=int(self._lock_timeout * 1000),
+        )
+        return token if acquired else None
+
+    async def _release_lock(self, rkey: str, token: str) -> None:
+        lock_key = self._lock_key(rkey)
+        if self._lua_ok:
+            try:
+                await self._release(keys=[lock_key], args=[token])
+                return
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001
+                message = str(exc).lower()
+                if "evalsha" in message or "unknown command" in message:
+                    self._lua_ok = False  # server lacks scripting; use fallback
+                else:
+                    return  # never fail a request because unlock hiccuped
+        await self._release_lock_fallback(lock_key, token)
+
+    async def _release_lock_fallback(self, lock_key: str, token: str) -> None:
+        """Compare-and-delete via an optimistic WATCH/MULTI transaction."""
+        wanted = token.encode()
+        try:
+            async with self._redis.pipeline(transaction=True) as pipe:
+                await pipe.watch(lock_key)
+                if await pipe.get(lock_key) == wanted:
+                    pipe.multi()
+                    pipe.delete(lock_key)
+                    await pipe.execute()
+                else:
+                    await pipe.reset()
+        except asyncio.CancelledError:
+            raise
+        except Exception:  # noqa: BLE001
+            pass  # the lock's own TTL will clean it up
+
+    async def _recompute_and_store(
+        self, rkey: str, ttl: float, recompute: Recompute[T]
+    ) -> T:
+        start = time.monotonic()
+        try:
+            result = recompute()
+            if inspect.isawaitable(result):
+                result = await result
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            raise RecomputeError(str(exc)) from exc
+
+        value = cast(T, result)
+        delta = time.monotonic() - start
+        async with self._redis.pipeline(transaction=True) as pipe:
+            pipe.hset(rkey, mapping={
+                _F_VALUE: self._dumps(value),
+                _F_DELTA: delta,
+                _F_EXPIRY: time.time() + ttl,
+            })
+            pipe.pexpire(rkey, int(ttl * 1000))
+            await pipe.execute()
+        return value
+
+    async def _rebuild_on_miss(
+        self, rkey: str, ttl: float, recompute: Recompute[T]
+    ) -> T:
+        token = await self._acquire(rkey)
+        if token is not None:
+            try:
+                return await self._recompute_and_store(rkey, ttl, recompute)
+            finally:
+                await self._release_lock(rkey, token)
+
+        # Another worker holds the lock. Wait for the value to appear, backing
+        # off so we don't busy-poll Redis.
+        deadline = time.monotonic() + self._wait_for_lock
+        delay = 0.02
+        while time.monotonic() < deadline:
+            await asyncio.sleep(delay)
+            entry = await self._read(rkey)
+            if entry is not None:
+                return cast(T, entry.value)
+            delay = min(delay * 1.5, 0.2)
+
+        # The holder crashed or is pathologically slow. Rebuild ourselves rather
+        # than hang the request indefinitely.
+        return await self._recompute_and_store(rkey, ttl, recompute)

cachefence/errors.py

@@ -0,0 +1,14 @@
+"""Exception types raised by cachefence."""
+
+
+class CacheFenceError(Exception):
+    """Base class for all cachefence errors."""
+
+
+class RecomputeError(CacheFenceError):
+    """Raised when the user-supplied recompute callable fails.
+
+    The error always propagates: cachefence does not fall back to a stale
+    value, even during an early refresh where one is still available. The
+    original exception is available via ``__cause__``.
+    """

cachefence-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: cachefence
+Version: 0.1.0
+Summary: Cache-aside for Redis without the stampede. Probabilistic early refresh + distributed lock, so a hot key expiring never hammers your database.
+Project-URL: Homepage, https://github.com/bourne44/cachefence
+Project-URL: Issues, https://github.com/bourne44/cachefence/issues
+Author: Bourne
+License: MIT
+License-File: LICENSE
+Keywords: async,cache,redis,stampede,thundering-herd,xfetch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: redis>=4.2
+Provides-Extra: dev
+Requires-Dist: fakeredis; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-redis; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: fakeredis; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cachefence
+
+**Cache-aside for Redis without the stampede.**
+
+When a hot cache key expires, naive cache-aside lets *every* concurrent request
+miss at the same instant and pile onto your database to rebuild the same value.
+That's a cache stampede (a.k.a. thundering herd), and it's one of the most common
+ways a cache makes things *worse* under load.
+
+cachefence stops it:
+
+```
+500 concurrent requests hit a cold key (each DB query takes 50ms)
+
+naive cache-aside      DB hits:  500
+with cachefence        DB hits:    1
+```
+
+Same workload, one extra import: **500 database queries become 1.**
+
+## Install
+
+```bash
+pip install cachefence
+```
+
+Requires Python 3.11+ and a Redis server (4.2+).
+
+## Usage
+
+```python
+from redis.asyncio import Redis
+from cachefence import CacheFence
+
+redis = Redis()
+cache = CacheFence(redis)
+
+async def get_user(user_id: int) -> dict:
+    return await cache.get_or_set(
+        key=f"user:{user_id}",
+        ttl=60,                                  # fresh for 60 seconds
+        recompute=lambda: load_user_from_db(user_id),
+    )
+```
+
+`recompute` can be sync or async. It runs at most once per refresh, no matter how
+many requests arrive together. Invalidate manually when the underlying data
+changes:
+
+```python
+await cache.invalidate(f"user:{user_id}")
+```
+
+## How it works
+
+cachefence layers two mechanisms so a key almost never goes cold *and* a cold key
+is never rebuilt more than once:
+
+1. **Probabilistic early refresh (XFetch).** Each read rolls a weighted dice; as
+   the key nears expiry, one lucky request is nudged to refresh it *ahead of
+   time* while everyone else keeps serving the still-valid cached value. The
+   weighting uses how long the last recompute took, so expensive keys refresh
+   earlier. Based on Vattani, Chierichetti & Lowenstein, *"Optimal Probabilistic
+   Cache Stampede Prevention"* (VLDB 2015).
+
+2. **Distributed rebuild lock.** On a true miss, workers race for a short-lived
+   Redis lock. The winner rebuilds; the rest wait briefly and pick up the fresh
+   value the moment it lands, with a bounded fallback so a crashed rebuilder
+   never hangs requests forever.
+
+The lock is released with a compare-and-delete (Lua when the server supports it,
+an optimistic `WATCH`/`MULTI` transaction otherwise) so a worker can never delete
+a lock it no longer owns.
+
+## Configuration
+
+```python
+cache = CacheFence(
+    redis,
+    beta=1.0,          # XFetch aggressiveness; higher = refresh earlier
+    lock_timeout=10.0, # seconds before a rebuild lock auto-expires
+    wait_for_lock=5.0, # max seconds a waiter blocks before rebuilding itself
+    namespace="app:",  # optional key prefix
+)
+```
+
+Custom serialization (default is JSON):
+
+```python
+import pickle
+cache = CacheFence(redis, serializer=pickle.dumps, deserializer=pickle.loads)
+# serializer returns bytes, deserializer takes bytes
+```
+
+## A note on connection pools
+
+Under a genuine burst (hundreds of simultaneous coroutines), the default
+`redis-py` pool can raise `MaxConnectionsError` because waiters don't block for a
+free connection. Use a blocking pool sized for your concurrency:
+
+```python
+from redis.asyncio import BlockingConnectionPool, Redis
+
+pool = BlockingConnectionPool(max_connections=30, timeout=15)
+redis = Redis(connection_pool=pool)
+```
+
+## Run the demo
+
+```bash
+git clone https://github.com/bourne44/cachefence
+cd cachefence
+pip install -e ".[test]"
+python examples/stampede_demo.py
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The test suite includes a 100-way concurrent-miss test asserting the recompute
+runs exactly once — the core guarantee of the library.
+
+## License
+
+MIT

cachefence-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cachefence/__init__.py,sha256=YBkDsLaYNZulzrlKcjDdBZvqazqrhz__xd0La7Rvr6E,1077
+cachefence/cache.py,sha256=qVaP7PXpOMRqK0eOzUnZRnDitUdp1ebxONXWvZwZZCs,9640
+cachefence/errors.py,sha256=28n7Or0soJLZBTbj6vCXAdzsoCbjpKRhdHEVQQuwQi4,444
+cachefence/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachefence-0.1.0.dist-info/METADATA,sha256=l0eU889HYWj9fwkFROyg93H2Pv8vVG0qm4tX5kcrFAI,4989
+cachefence-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cachefence-0.1.0.dist-info/licenses/LICENSE,sha256=pSct4FJDg-bJmTBQ9bSEXmpuNqYh3dGvrt-lOO3S0LI,1063
+cachefence-0.1.0.dist-info/RECORD,,

cachefence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cachefence-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bourne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.