cache-sync 0.3.1__py3-none-any.whl

cache_sync/__init__.py

@@ -0,0 +1,80 @@
+"""Public API for cache-sync."""
+
+from typing import TYPE_CHECKING, Any
+
+from cache_sync.core import CacheOptions, CacheSync
+from cache_sync.decorators import CachedFunction
+from cache_sync.distributed_cache import DistributedCache
+from cache_sync.invalidation import (
+    InvalidationBus,
+    InvalidationHandler,
+    InvalidationMessage,
+    InvalidationTransport,
+    TransportInvalidationBus,
+)
+from cache_sync.serializers import (
+    JsonSerializer,
+    PickleSerializer,
+    PydanticSerializer,
+    Serializer,
+)
+
+if TYPE_CHECKING:
+    from cache_sync.providers.kafka import KafkaInvalidationBus
+    from cache_sync.providers.postgres import PostgresNotifyInvalidationBus
+    from cache_sync.providers.rabbitmq import RabbitMQInvalidationBus
+    from cache_sync.providers.redis import (
+        RedisDistributedCache,
+        RedisStreamsInvalidationBus,
+    )
+
+__all__ = [
+    "CacheOptions",
+    "CacheSync",
+    "CachedFunction",
+    "DistributedCache",
+    "InvalidationBus",
+    "InvalidationHandler",
+    "InvalidationMessage",
+    "InvalidationTransport",
+    "JsonSerializer",
+    "KafkaInvalidationBus",
+    "PickleSerializer",
+    "PostgresNotifyInvalidationBus",
+    "PydanticSerializer",
+    "RabbitMQInvalidationBus",
+    "RedisDistributedCache",
+    "RedisStreamsInvalidationBus",
+    "Serializer",
+    "TransportInvalidationBus",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "RedisDistributedCache":
+        from cache_sync.providers.redis import RedisDistributedCache
+
+        return RedisDistributedCache
+
+    if name == "RedisStreamsInvalidationBus":
+        from cache_sync.providers.redis import RedisStreamsInvalidationBus
+
+        return RedisStreamsInvalidationBus
+
+    if name == "RabbitMQInvalidationBus":
+        from cache_sync.providers.rabbitmq import RabbitMQInvalidationBus
+
+        return RabbitMQInvalidationBus
+
+    if name == "KafkaInvalidationBus":
+        from cache_sync.providers.kafka import KafkaInvalidationBus
+
+        return KafkaInvalidationBus
+
+    if name == "PostgresNotifyInvalidationBus":
+        from cache_sync.providers.postgres import PostgresNotifyInvalidationBus
+
+        return PostgresNotifyInvalidationBus
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

cache_sync/core.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, ParamSpec, TypeVar, cast
+
+from cache_sync.distributed_cache import DistributedCache
+from cache_sync.invalidation import InvalidationBus
+
+T = TypeVar("T")
+P = ParamSpec("P")
+_CACHE_OPTION_DEFAULTS = {
+    "ttl_seconds": 60.0,
+    "fail_safe_seconds": 300.0,
+    "hard_timeout_seconds": 5.0,
+    "jitter_seconds": 0.0,
+}
+
+
+class _Unset:
+    __slots__ = ()
+
+
+_UNSET = _Unset()
+
+if TYPE_CHECKING:
+    from cache_sync.decorators import CachedFunction
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class CacheOptions:
+    """Runtime policy for cache freshness, factory timeouts, and TTL jitter."""
+
+    ttl_seconds: float = 60
+    fail_safe_seconds: float = 300
+    hard_timeout_seconds: float = 5
+    jitter_seconds: float = 0
+    _supplied: frozenset[str] = field(
+        default_factory=frozenset,
+        repr=False,
+        compare=False,
+    )
+
+    def __init__(
+        self,
+        ttl_seconds: float | _Unset = _UNSET,
+        fail_safe_seconds: float | _Unset = _UNSET,
+        hard_timeout_seconds: float | _Unset = _UNSET,
+        jitter_seconds: float | _Unset = _UNSET,
+    ) -> None:
+        values = {
+            "ttl_seconds": ttl_seconds,
+            "fail_safe_seconds": fail_safe_seconds,
+            "hard_timeout_seconds": hard_timeout_seconds,
+            "jitter_seconds": jitter_seconds,
+        }
+        supplied = frozenset(name for name, value in values.items() if value is not _UNSET)
+
+        for name, default in _CACHE_OPTION_DEFAULTS.items():
+            value = values[name]
+            object.__setattr__(self, name, default if value is _UNSET else value)
+
+        object.__setattr__(self, "_supplied", supplied)
+
+    def merge_over(self, defaults: CacheOptions) -> CacheOptions:
+        """Return this option object's supplied fields over cache defaults."""
+
+        values = {
+            name: getattr(self if name in self._supplied else defaults, name)
+            for name in _CACHE_OPTION_DEFAULTS
+        }
+        return CacheOptions(**values)
+
+
+@dataclass(slots=True)
+class CacheEntry:
+    """In-memory cache entry with freshness and fail-safe deadlines."""
+
+    value: object
+    expires_at: float
+    fail_safe_until: float
+
+    @property
+    def is_fresh(self) -> bool:
+        return time.monotonic() < self.expires_at
+
+    @property
+    def is_fail_safe_available(self) -> bool:
+        return time.monotonic() < self.fail_safe_until
+
+
+class CacheSync:
+    """Async two-level cache with optional distributed storage and invalidation."""
+
+    def __init__(
+        self,
+        *,
+        distributed_cache: DistributedCache | None = None,
+        invalidation_bus: InvalidationBus | None = None,
+        options: CacheOptions | None = None,
+    ) -> None:
+        """Create a cache using optional L2 storage and invalidation providers."""
+
+        self._memory: dict[str, CacheEntry] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._distributed_cache = distributed_cache
+        self._invalidation_bus = invalidation_bus
+        self._options = options or CacheOptions()
+
+    async def start(self) -> None:
+        """Start the configured invalidation bus, if any."""
+
+        if self._invalidation_bus is None:
+            return
+
+        await self._invalidation_bus.start(
+            remove_local=self.remove_local,
+            clear_local=self.clear_memory,
+        )
+
+    async def stop(self) -> None:
+        """Stop the configured invalidation bus, if any."""
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.stop()
+
+    def cached(
+        self,
+        key: str | Callable[..., str] | None = None,
+        *,
+        options: CacheOptions | None = None,
+    ) -> Callable[[Callable[P, Awaitable[T]]], CachedFunction[P, T]]:
+        """Decorate an async function using this cache instance."""
+
+        from cache_sync.decorators import CachedFunction
+
+        def decorator(func: Callable[P, Awaitable[T]]) -> CachedFunction[P, T]:
+            return CachedFunction(self, func, key, options)
+
+        return decorator
+
+    async def get_or_set(
+        self,
+        key: str,
+        factory: Callable[[], Awaitable[T]],
+        *,
+        options: CacheOptions | None = None,
+    ) -> T:
+        """Return a cached value or compute, store, and return a new value."""
+
+        opts = self._effective_options(options)
+        entry = self._memory.get(key)
+
+        if entry and entry.is_fresh:
+            return cast(T, entry.value)
+
+        lock = self._locks.setdefault(key, asyncio.Lock())
+
+        async with lock:
+            entry = self._memory.get(key)
+            if entry and entry.is_fresh:
+                return cast(T, entry.value)
+
+            if self._distributed_cache is not None:
+                cached_value = await self._distributed_cache.get(key)
+                if cached_value is not None:
+                    self._set_memory(key, cached_value, opts)
+                    return cast(T, cached_value)
+
+            stale = entry if entry and entry.is_fail_safe_available else None
+
+            try:
+                value = await asyncio.wait_for(
+                    factory(),
+                    timeout=opts.hard_timeout_seconds,
+                )
+                await self.set(key, value, options=opts, publish_invalidation=False)
+                return value
+            except Exception:
+                if stale is not None:
+                    return cast(T, stale.value)
+                raise
+
+    async def set(
+        self,
+        key: str,
+        value: object,
+        *,
+        options: CacheOptions | None = None,
+        publish_invalidation: bool = True,
+    ) -> None:
+        """Store a value in local memory and optional distributed storage."""
+
+        opts = self._effective_options(options)
+        self._set_memory(key, value, opts)
+
+        if self._distributed_cache is not None:
+            await self._distributed_cache.set(
+                key,
+                value,
+                ttl_seconds=self._ttl_with_jitter(opts),
+            )
+
+        if publish_invalidation and self._invalidation_bus is not None:
+            await self._invalidation_bus.invalidate(key)
+
+    async def remove(self, key: str) -> None:
+        """Remove a key locally, from distributed storage, and from peer nodes."""
+
+        self.remove_local(key)
+
+        if self._distributed_cache is not None:
+            await self._distributed_cache.delete(key)
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.invalidate(key)
+
+    async def clear(self) -> None:
+        """Clear all local entries and publish a clear message to peer nodes."""
+
+        self.clear_memory()
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.clear()
+
+    def remove_local(self, key: str) -> None:
+        """Remove a key from only this process's in-memory cache."""
+
+        self._memory.pop(key, None)
+
+    def clear_memory(self) -> None:
+        """Clear only this process's in-memory cache."""
+
+        self._memory.clear()
+
+    def _effective_options(self, options: CacheOptions | None) -> CacheOptions:
+        if options is None:
+            return self._options
+        return options.merge_over(self._options)
+
+    def _set_memory(self, key: str, value: object, opts: CacheOptions) -> None:
+        ttl = self._ttl_with_jitter(opts)
+        now = time.monotonic()
+        self._memory[key] = CacheEntry(
+            value=value,
+            expires_at=now + ttl,
+            fail_safe_until=now + ttl + opts.fail_safe_seconds,
+        )
+
+    def _ttl_with_jitter(self, opts: CacheOptions) -> float:
+        if opts.jitter_seconds <= 0:
+            return opts.ttl_seconds
+        return opts.ttl_seconds + random.uniform(0, opts.jitter_seconds)

cache_sync/decorators.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Generic, ParamSpec, TypeVar
+
+from cache_sync.core import CacheOptions
+
+if TYPE_CHECKING:
+    from cache_sync.core import CacheSync
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class CachedFunction(Generic[P, T]):
+    """Callable wrapper returned by `CacheSync.cached` with cache helpers."""
+
+    def __init__(
+        self,
+        cache: CacheSync,
+        func: Callable[P, Awaitable[T]],
+        key: str | Callable[..., str] | None,
+        options: CacheOptions | None,
+    ) -> None:
+        self._cache = cache
+        self._func = func
+        self._key = key
+        self._options = options
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+        """Return the cached result for this call or invoke the wrapped function."""
+
+        return await self._cache.get_or_set(
+            self.cache_key(*args, **kwargs),
+            lambda: self._func(*args, **kwargs),
+            options=self._options,
+        )
+
+    async def remove_cached(self, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Remove the cached value associated with this call's cache key."""
+
+        await self._cache.remove(self.cache_key(*args, **kwargs))
+
+    def cache_key(self, *args: P.args, **kwargs: P.kwargs) -> str:
+        """Build the cache key for the supplied function arguments."""
+
+        if isinstance(self._key, str):
+            return self._key
+        if self._key is None:
+            return default_cache_key(self._func, *args, **kwargs)
+        return self._key(*args, **kwargs)
+
+
+def default_cache_key(func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> str:
+    """Build a deterministic key from a function and call arguments."""
+
+    signature = inspect.signature(func)
+    bound = signature.bind(*args, **kwargs)
+    bound.apply_defaults()
+    arguments = ",".join(
+        f"{name}={_stable_key_part(value)}" for name, value in bound.arguments.items()
+    )
+    module = getattr(func, "__module__", type(func).__module__)
+    qualname = getattr(func, "__qualname__", type(func).__qualname__)
+
+    return f"{module}.{qualname}({arguments})"
+
+
+def _stable_key_part(value: Any) -> str:
+    if isinstance(value, dict):
+        items = sorted(
+            (_stable_key_part(key), _stable_key_part(item_value))
+            for key, item_value in value.items()
+        )
+        return "{" + ",".join(f"{key}:{item_value}" for key, item_value in items) + "}"
+
+    if isinstance(value, (list, tuple)):
+        opener, closer = ("[", "]") if isinstance(value, list) else ("(", ")")
+        return opener + ",".join(_stable_key_part(item) for item in value) + closer
+
+    if isinstance(value, (set, frozenset)):
+        items = sorted(_stable_key_part(item) for item in value)
+        return "{" + ",".join(items) + "}"
+
+    return repr(value)

cache_sync/distributed_cache.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from cache_sync.serializers import PickleSerializer as PickleSerializer
+from cache_sync.serializers import Serializer as Serializer
+
+
+class DistributedCache(Protocol):
+    """Protocol for optional shared L2 cache storage."""
+
+    async def get(self, key: str) -> object | None: ...
+
+    async def set(self, key: str, value: object, ttl_seconds: float) -> None: ...
+
+    async def delete(self, key: str) -> None: ...

cache_sync/invalidation.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+type InvalidationAction = Literal["remove", "clear"]
+type RemoveLocal = Callable[[str], None]
+type ClearLocal = Callable[[], None]
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidationMessage:
+    """Message sent between cache nodes to remove keys or clear local memory."""
+
+    action: InvalidationAction
+    key: str | None = None
+
+    @classmethod
+    def remove(cls, key: str) -> InvalidationMessage:
+        """Create a message that removes one key from peer local caches."""
+
+        return cls(action="remove", key=key)
+
+    @classmethod
+    def clear(cls) -> InvalidationMessage:
+        """Create a message that clears peer local caches."""
+
+        return cls(action="clear")
+
+
+type InvalidationHandler = Callable[[InvalidationMessage], Awaitable[None]]
+
+
+class InvalidationTransport(Protocol):
+    """Low-level transport used by `TransportInvalidationBus`."""
+
+    async def start(self, handler: InvalidationHandler) -> None: ...
+
+    async def stop(self) -> None: ...
+
+    async def publish(self, message: InvalidationMessage) -> None: ...
+
+
+class InvalidationBus(Protocol):
+    """Protocol for publishing and receiving cache invalidation events."""
+
+    async def start(
+        self,
+        *,
+        remove_local: RemoveLocal,
+        clear_local: ClearLocal,
+    ) -> None: ...
+
+    async def stop(self) -> None: ...
+
+    async def invalidate(self, key: str) -> None: ...
+
+    async def clear(self) -> None: ...
+
+
+class TransportInvalidationBus:
+    """Adapt an `InvalidationTransport` into the `InvalidationBus` protocol."""
+
+    def __init__(self, transport: InvalidationTransport) -> None:
+        """Create an invalidation bus backed by a generic transport."""
+
+        self._transport = transport
+        self._remove_local: RemoveLocal | None = None
+        self._clear_local: ClearLocal | None = None
+
+    async def start(
+        self,
+        *,
+        remove_local: RemoveLocal,
+        clear_local: ClearLocal,
+    ) -> None:
+        """Start listening for remote invalidation messages."""
+
+        self._remove_local = remove_local
+        self._clear_local = clear_local
+        await self._transport.start(self._handle_message)
+
+    async def stop(self) -> None:
+        """Stop listening and release local callbacks."""
+
+        await self._transport.stop()
+        self._remove_local = None
+        self._clear_local = None
+
+    async def invalidate(self, key: str) -> None:
+        """Publish a message instructing peers to remove one key."""
+
+        await self._transport.publish(InvalidationMessage.remove(key))
+
+    async def clear(self) -> None:
+        """Publish a message instructing peers to clear local memory."""
+
+        await self._transport.publish(InvalidationMessage.clear())
+
+    async def _handle_message(self, message: InvalidationMessage) -> None:
+        remove_local = self._remove_local
+        clear_local = self._clear_local
+
+        if message.action == "remove" and message.key is not None:
+            if remove_local is not None:
+                remove_local(message.key)
+            return
+
+        if message.action == "clear" and clear_local is not None:
+            clear_local()

cache_sync/providers/__init__.py

@@ -0,0 +1 @@
+"""Provider implementations for cache-sync."""

cache_sync/providers/kafka/__init__.py

@@ -0,0 +1,7 @@
+"""Kafka provider exports."""
+
+from cache_sync.providers.kafka.invalidation_bus import KafkaInvalidationBus
+
+__all__ = [
+    "KafkaInvalidationBus",
+]