cache-sync 0.3.1__py3-none-any.whl

cache_sync/providers/redis/invalidation_bus.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+import uuid
+from collections.abc import Mapping
+from contextlib import suppress
+from typing import cast
+
+from redis.asyncio import Redis
+from redis.exceptions import ResponseError
+from redis.typing import EncodableT, FieldT
+
+from cache_sync.invalidation import (
+    ClearLocal,
+    InvalidationAction,
+    InvalidationMessage,
+    RemoveLocal,
+)
+
+type RedisFields = Mapping[bytes | str, bytes | str]
+type RedisMessage = tuple[bytes | str, RedisFields]
+type RedisStreamResponse = list[tuple[bytes | str, list[RedisMessage]]]
+
+
+class RedisStreamsInvalidationBus:
+    """Invalidation bus backed by Redis Streams consumer groups."""
+
+    def __init__(
+        self,
+        redis: Redis,
+        *,
+        stream_name: str = "cache-sync:invalidations",
+        node_name: str | None = None,
+        max_length: int = 10_000,
+    ) -> None:
+        """Create a Redis Streams invalidation bus."""
+
+        self._redis = redis
+        self._stream_name = stream_name
+        self._source_id = str(uuid.uuid4())
+        self._node_name = node_name or f"{socket.gethostname()}-{self._source_id}"
+        self._group_name = f"cache-sync-node:{self._node_name}"
+        self._consumer_name = self._node_name
+        self._max_length = max_length
+        self._remove_local: RemoveLocal | None = None
+        self._clear_local: ClearLocal | None = None
+        self._listener_task: asyncio.Task[None] | None = None
+        self._stopped = asyncio.Event()
+
+    async def start(
+        self,
+        *,
+        remove_local: RemoveLocal,
+        clear_local: ClearLocal,
+    ) -> None:
+        """Create the consumer group if needed and start the listener task."""
+
+        if self._listener_task is not None:
+            return
+
+        self._remove_local = remove_local
+        self._clear_local = clear_local
+        self._stopped.clear()
+        await self._ensure_group()
+        self._listener_task = asyncio.create_task(self._listen())
+
+    async def stop(self) -> None:
+        """Cancel the listener task and clear local callbacks."""
+
+        self._stopped.set()
+
+        if self._listener_task is None:
+            return
+
+        self._listener_task.cancel()
+
+        with suppress(asyncio.CancelledError):
+            await self._listener_task
+
+        self._listener_task = None
+        self._remove_local = None
+        self._clear_local = None
+
+    async def invalidate(self, key: str) -> None:
+        """Publish a key-removal message to the stream."""
+
+        await self._publish(InvalidationMessage.remove(key))
+
+    async def clear(self) -> None:
+        """Publish a clear-all message to the stream."""
+
+        await self._publish(InvalidationMessage.clear())
+
+    async def _publish(self, message: InvalidationMessage) -> None:
+        fields: dict[FieldT, EncodableT] = {
+            "action": message.action,
+            "source_id": self._source_id,
+        }
+
+        if message.key is not None:
+            fields["key"] = message.key
+
+        await self._redis.xadd(
+            self._stream_name,
+            fields,
+            maxlen=self._max_length,
+            approximate=True,
+        )
+
+    async def _ensure_group(self) -> None:
+        try:
+            await self._redis.xgroup_create(
+                self._stream_name,
+                self._group_name,
+                id="$",
+                mkstream=True,
+            )
+        except ResponseError as ex:
+            if "BUSYGROUP" not in str(ex):
+                raise
+
+    async def _listen(self) -> None:
+        while not self._stopped.is_set():
+            response = cast(
+                RedisStreamResponse,
+                await self._redis.xreadgroup(
+                    groupname=self._group_name,
+                    consumername=self._consumer_name,
+                    streams={self._stream_name: ">"},
+                    count=25,
+                    block=5_000,
+                ),
+            )
+
+            for _, messages in response:
+                for message_id, fields in messages:
+                    await self._process_message(message_id, fields)
+
+    async def _process_message(
+        self,
+        message_id: bytes | str,
+        fields: RedisFields,
+    ) -> None:
+        source_id = self._get_field(fields, "source_id")
+
+        if source_id != self._source_id:
+            self._apply_message(self._to_message(fields))
+
+        await self._redis.xack(
+            self._stream_name,
+            self._group_name,
+            message_id,
+        )
+
+    def _apply_message(self, message: InvalidationMessage) -> None:
+        if message.action == "remove" and message.key is not None:
+            remove_local = self._remove_local
+            if remove_local is not None:
+                remove_local(message.key)
+            return
+
+        if message.action == "clear":
+            clear_local = self._clear_local
+            if clear_local is not None:
+                clear_local()
+
+    def _to_message(self, fields: RedisFields) -> InvalidationMessage:
+        action = cast(InvalidationAction, self._get_field(fields, "action"))
+
+        if action == "remove":
+            return InvalidationMessage.remove(self._get_field(fields, "key"))
+
+        return InvalidationMessage.clear()
+
+    def _get_field(self, fields: RedisFields, key: str) -> str:
+        value = fields.get(key)
+        if value is None:
+            value = fields[key.encode("utf-8")]
+
+        return value.decode("utf-8") if isinstance(value, bytes) else value

cache_sync/py.typed

@@ -0,0 +1 @@
+

cache_sync/serializers.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+import pickle
+from collections.abc import Callable
+from typing import Generic, Protocol, TypeVar, cast
+
+T = TypeVar("T")
+
+
+class Serializer(Protocol):
+    """Protocol for converting distributed-cache values to and from bytes."""
+
+    def dumps(self, value: object) -> bytes: ...
+
+    def loads(self, value: bytes) -> object: ...
+
+
+class PickleSerializer:
+    """Serialize arbitrary trusted Python objects with pickle."""
+
+    def dumps(self, value: object) -> bytes:
+        """Serialize a Python object to bytes."""
+
+        return pickle.dumps(value)
+
+    def loads(self, value: bytes) -> object:
+        """Deserialize bytes into a Python object."""
+
+        return pickle.loads(value)
+
+
+class JsonSerializer:
+    """Serialize JSON-compatible values as UTF-8 JSON bytes."""
+
+    def dumps(self, value: object) -> bytes:
+        """Serialize a JSON-compatible value to bytes."""
+
+        return json.dumps(value).encode("utf-8")
+
+    def loads(self, value: bytes) -> object:
+        """Deserialize UTF-8 JSON bytes."""
+
+        return json.loads(value.decode("utf-8"))
+
+
+class PydanticSerializer(Generic[T]):
+    """Serialize and deserialize Pydantic model instances."""
+
+    def __init__(self, model_type: type[T]) -> None:
+        """Create a serializer for the supplied Pydantic model type."""
+
+        self._model_type = model_type
+
+    def dumps(self, value: object) -> bytes:
+        """Serialize a Pydantic model instance to JSON bytes."""
+
+        model_dump_json = getattr(value, "model_dump_json", None)
+        if callable(model_dump_json):
+            return cast(Callable[[], str], model_dump_json)().encode("utf-8")
+
+        json_method = getattr(value, "json", None)
+        if callable(json_method):
+            return cast(Callable[[], str], json_method)().encode("utf-8")
+
+        msg = "PydanticSerializer can only dump Pydantic model instances"
+        raise TypeError(msg)
+
+    def loads(self, value: bytes) -> T:
+        """Deserialize JSON bytes into the configured Pydantic model type."""
+
+        raw = value.decode("utf-8")
+
+        model_validate_json = getattr(self._model_type, "model_validate_json", None)
+        if callable(model_validate_json):
+            return cast(Callable[[str], T], model_validate_json)(raw)
+
+        parse_raw = getattr(self._model_type, "parse_raw", None)
+        if callable(parse_raw):
+            return cast(Callable[[str], T], parse_raw)(raw)
+
+        msg = "PydanticSerializer requires a Pydantic model type"
+        raise TypeError(msg)

cache_sync-0.3.1.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.3
+Name: cache-sync
+Version: 0.3.1
+Summary: Async hybrid Python cache with in-memory L1, distributed L2 providers, pluggable invalidation, stampede protection, and typed decorators.
+Keywords: async,cache,redis,invalidation,stampede-protection
+Author: Peter Cinibulk
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: redis>=5.0.0 ; extra == 'all'
+Requires-Dist: aio-pika>=9.0.0 ; extra == 'all'
+Requires-Dist: aiokafka>=0.10.0 ; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0 ; extra == 'all'
+Requires-Dist: pydantic>=1.10.0 ; extra == 'all'
+Requires-Dist: aiokafka>=0.10.0 ; extra == 'kafka'
+Requires-Dist: asyncpg>=0.29.0 ; extra == 'postgres'
+Requires-Dist: pydantic>=1.10.0 ; extra == 'pydantic'
+Requires-Dist: aio-pika>=9.0.0 ; extra == 'rabbitmq'
+Requires-Dist: redis>=5.0.0 ; extra == 'redis'
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/petercinibulk/cache-sync/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://petercinibulk.github.io/cache-sync/
+Project-URL: Issues, https://github.com/petercinibulk/cache-sync/issues
+Project-URL: Repository, https://github.com/petercinibulk/cache-sync
+Provides-Extra: all
+Provides-Extra: kafka
+Provides-Extra: postgres
+Provides-Extra: pydantic
+Provides-Extra: rabbitmq
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# cache-sync
+
+Async hybrid Python cache with in-memory L1 caching, optional Redis L2 caching, pluggable invalidation, stampede protection, fail-safe stale values, and typed decorators.
+
+## Features
+
+- Async-first API for Python 3.12 and newer.
+- Fast in-process L1 cache with optional Redis-backed L2 storage.
+- Pluggable invalidation buses for Redis Streams, RabbitMQ, Kafka, and PostgreSQL.
+- Request stampede protection with per-key refresh coordination.
+- Fail-safe stale reads for short backend outages.
+- Typed decorators that preserve the wrapped function signature.
+- Serializer choices for JSON, pickle, and Pydantic models.
+
+## Documentation
+
+The end-user documentation is published at <https://petercinibulk.github.io/cache-sync/> and is built from [`docs/`](docs/index.md) with Zensical.
+
+## Install
+
+```bash
+uv add cache-sync
+```
+
+Install optional providers only when your application uses them:
+
+```bash
+uv add "cache-sync[redis]"
+uv add "cache-sync[rabbitmq]"
+uv add "cache-sync[kafka]"
+uv add "cache-sync[postgres]"
+uv add "cache-sync[all]"
+```
+
+| Extra | Installs | Use when |
+| --- | --- | --- |
+| `redis` | `redis` | You need Redis L2 storage or Redis Streams invalidation. |
+| `rabbitmq` | `aio-pika` | You use RabbitMQ as the invalidation bus. |
+| `kafka` | `aiokafka` | You use Kafka as the invalidation bus. |
+| `postgres` | `asyncpg` | You use PostgreSQL `LISTEN`/`NOTIFY` for invalidation. |
+| `pydantic` | `pydantic` | You want Pydantic model serialization helpers. |
+| `all` | all provider dependencies | You want every optional provider available. |
+
+## Quick Start
+
+```python
+from cache_sync import CacheOptions, CacheSync
+
+cache = CacheSync(
+    options=CacheOptions(
+        ttl_seconds=60,
+        fail_safe_seconds=300,
+        hard_timeout_seconds=5,
+        jitter_seconds=5,
+    ),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda user_id: f"user:{user_id}")
+async def get_user(user_id: str) -> dict[str, str]:
+    return {"id": user_id, "name": "Peter"}
+
+
+user = await get_user("123")
+await get_user.remove_cached("123")
+await cache.stop()
+```
+
+## Redis L2 Example
+
+```python
+from redis.asyncio import Redis
+
+from cache_sync import CacheOptions, CacheSync, RedisDistributedCache
+
+redis = Redis.from_url("redis://localhost:6379/0")
+
+cache = CacheSync(
+    distributed_cache=RedisDistributedCache(redis),
+    options=CacheOptions(ttl_seconds=60, fail_safe_seconds=300),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda product_id: f"product:{product_id}")
+async def get_product(product_id: str) -> dict[str, str]:
+    return {"id": product_id}
+```
+
+For a complete walkthrough with shared values and cross-instance invalidation, see the [get started tutorial](https://petercinibulk.github.io/cache-sync/tutorials/get-started/).
+
+## Project
+
+- License: MIT
+- Source: <https://github.com/petercinibulk/cache-sync>
+- Issues: <https://github.com/petercinibulk/cache-sync/issues>

cache_sync-0.3.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+cache_sync/__init__.py,sha256=av8jQbh1cKp0hXgxrBg8cJ_o3nEswH7OZ4M6xcshdd0,2272
+cache_sync/core.py,sha256=XPBSn4cBfjeT-UXgs_4j6-TJXLbu2VLPgZ8cMdonLw4,7964
+cache_sync/decorators.py,sha256=EbZkDiertdt5RYHO4dKe643-RDjme0RldqREBtkiAB4,2917
+cache_sync/distributed_cache.py,sha256=x6US0OCJXNpJBvLGrVAQDGonekI3RcEjWF_AK-Zr5So,481
+cache_sync/invalidation.py,sha256=vhYvpWstVXRCbDhKcHGSSjHnve7DYMDD3mciitgBJhw,3308
+cache_sync/providers/__init__.py,sha256=vFj6aHry3F1rSqDOAUzlo_weG-ymXsXTPalNMhU4PMQ,47
+cache_sync/providers/kafka/__init__.py,sha256=PGhdXK_FMLKKrJeq0zvIOxcvFuwvnXzgH-SgSsjU_XI,151
+cache_sync/providers/kafka/invalidation_bus.py,sha256=LiNIzdomR50gPDxcTrCTDaX9UEhWG9mmsTIU4oOEXFE,5620
+cache_sync/providers/postgres/__init__.py,sha256=10deqZGvUbRUQ3EZfsHMTq0Vb-Lp5TlNOWy0cX-sFSk,177
+cache_sync/providers/postgres/invalidation_bus.py,sha256=D2XwceJvHJXOj58cnXhLu_BlZTbMSSODlnjrKfzjU78,3803
+cache_sync/providers/rabbitmq/__init__.py,sha256=RmdeHVqoRqDaQil6tjMG0heV3htgxgzgaUYNwAvbUhA,163
+cache_sync/providers/rabbitmq/invalidation_bus.py,sha256=X57JkfMHU3FjBslLT5aYKPnTwh0xrpsRVBeJvoH_T2E,5613
+cache_sync/providers/redis/__init__.py,sha256=L5HFwdqHdjURLjR0rx4r_FleFiLaIedZ6KjIC1SlKeA,261
+cache_sync/providers/redis/cache.py,sha256=cl7Q12vydsKLy_LfK26eqjS0bsFOxY1caELX6Lb2L00,1467
+cache_sync/providers/redis/invalidation_bus.py,sha256=XDO6NdgIXhxsUOsZF7j0BmuBzn0faOWQjWWCW-MdvKA,5523
+cache_sync/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+cache_sync/serializers.py,sha256=Ga3VzqVmMIK_dSYhF4YyQZhQDOup93wrnB1ZrBgHLbM,2552
+cache_sync-0.3.1.dist-info/WHEEL,sha256=oBsDExVIEya4llboy9Ce1l6on8xt3GrtT29y6pYVypw,81
+cache_sync-0.3.1.dist-info/METADATA,sha256=kcyDd3_fKmINbSNwUGOXHyXUYHQ16VbWIG8nAbmdAVo,4732
+cache_sync-0.3.1.dist-info/RECORD,,

cache_sync-0.3.1.dist-info/WHEEL

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