async-redis-client 0.1.0__py3-none-any.whl

async_redis_client/__init__.py

@@ -0,0 +1,52 @@
+"""
+Ports-and-adapters cache library: Redis-backed adapters with Fernet + Pydantic JSON.
+
+Application code should depend on :class:`~async_redis_client.ports.sync_cache_port.CacheSyncPort`
+or :class:`~async_redis_client.ports.async_cache_port.CacheAsyncPort` only; compose Redis adapters
+in your bootstrap layer.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("async-redis-client")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from async_redis_client.adapters.memory import (
+    MemoryCacheAsyncAdapter,
+    MemoryCacheSyncAdapter,
+)
+from async_redis_client.adapters.redis import (
+    RedisCacheAsyncAdapter,
+    RedisCacheSyncAdapter,
+)
+from async_redis_client.errors import (
+    CacheClosedError,
+    CacheError,
+    CacheKeyNotFoundError,
+    DecryptionError,
+    SerializationError,
+)
+from async_redis_client.ports.async_cache_port import CacheAsyncPort
+from async_redis_client.ports.sync_cache_port import CacheSyncPort
+
+SyncCachePort = CacheSyncPort
+AsyncCachePort = CacheAsyncPort
+
+__all__ = [
+    "__version__",
+    "AsyncCachePort",
+    "CacheAsyncPort",
+    "CacheClosedError",
+    "CacheError",
+    "CacheKeyNotFoundError",
+    "CacheSyncPort",
+    "DecryptionError",
+    "MemoryCacheAsyncAdapter",
+    "MemoryCacheSyncAdapter",
+    "RedisCacheAsyncAdapter",
+    "RedisCacheSyncAdapter",
+    "SerializationError",
+    "SyncCachePort",
+]

async_redis_client/adapters/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure adapters (Redis, optional in-memory stubs)."""

async_redis_client/adapters/memory/__init__.py

@@ -0,0 +1,4 @@
+from async_redis_client.adapters.memory.async_adapter import MemoryCacheAsyncAdapter
+from async_redis_client.adapters.memory.sync_adapter import MemoryCacheSyncAdapter
+
+__all__ = ["MemoryCacheAsyncAdapter", "MemoryCacheSyncAdapter"]

async_redis_client/adapters/memory/async_adapter.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping, Sequence
+from typing import Self, TypeVar
+
+from pydantic import BaseModel, JsonValue
+
+from async_redis_client.adapters.memory.sync_adapter import MemoryCacheSyncAdapter
+
+TModel = TypeVar("TModel")
+
+
+class MemoryCacheAsyncAdapter:
+    """Async façade over :class:`MemoryCacheSyncAdapter` with an asyncio lock."""
+
+    __slots__ = ("_inner", "_lock")
+
+    def __init__(
+        self,
+        *,
+        namespace: str = "",
+        key_prefix: str = "",
+    ) -> None:
+        self._inner = MemoryCacheSyncAdapter(namespace=namespace, key_prefix=key_prefix)
+        self._lock = asyncio.Lock()
+
+    async def close(self) -> None:
+        """No-op; satisfies :class:`~async_redis_client.ports.async_cache_port.CacheAsyncPort`."""
+
+    aclose = close
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.close()
+
+    async def get(self, key: str) -> JsonValue | None:
+        async with self._lock:
+            return self._inner.get(key)
+
+    async def set(
+        self, key: str, value: JsonValue, ttl_seconds: int | None = None
+    ) -> None:
+        async with self._lock:
+            self._inner.set(key, value, ttl_seconds=ttl_seconds)
+
+    async def set_json(
+        self, key: str, value: JsonValue, ttl_seconds: int | None = None
+    ) -> None:
+        async with self._lock:
+            self._inner.set_json(key, value, ttl_seconds=ttl_seconds)
+
+    async def get_json(self, key: str) -> JsonValue | None:
+        async with self._lock:
+            return self._inner.get_json(key)
+
+    async def get_or_raise_if_missing(self, key: str) -> JsonValue:
+        async with self._lock:
+            return self._inner.get_or_raise_if_missing(key)
+
+    async def get_json_or_raise_if_missing(self, key: str) -> JsonValue:
+        async with self._lock:
+            return self._inner.get_json_or_raise_if_missing(key)
+
+    async def set_model(
+        self, key: str, model: BaseModel, ttl_seconds: int | None = None
+    ) -> None:
+        async with self._lock:
+            self._inner.set_model(key, model, ttl_seconds=ttl_seconds)
+
+    async def get_as_model(self, key: str, model_type: type[TModel]) -> TModel | None:
+        async with self._lock:
+            return self._inner.get_as_model(key, model_type)
+
+    async def delete(self, key: str) -> int:
+        async with self._lock:
+            return self._inner.delete(key)
+
+    async def exists(self, key: str) -> bool:
+        async with self._lock:
+            return self._inner.exists(key)
+
+    async def incr(self, key: str, amount: int = 1) -> int:
+        async with self._lock:
+            return self._inner.incr(key, amount)
+
+    async def decr(self, key: str, amount: int = 1) -> int:
+        async with self._lock:
+            return self._inner.decr(key, amount)
+
+    async def incrby(self, key: str, amount: int) -> int:
+        async with self._lock:
+            return self._inner.incrby(key, amount)
+
+    async def set_many(
+        self, mapping: Mapping[str, JsonValue], ttl_seconds: int | None = None
+    ) -> None:
+        async with self._lock:
+            self._inner.set_many(mapping, ttl_seconds=ttl_seconds)
+
+    async def get_many(self, keys: Sequence[str]) -> dict[str, JsonValue | None]:
+        async with self._lock:
+            return self._inner.get_many(keys)

async_redis_client/adapters/memory/sync_adapter.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Self, TypeVar
+
+from pydantic import BaseModel, JsonValue, TypeAdapter
+
+from async_redis_client.errors import CacheKeyNotFoundError, SerializationError
+
+TModel = TypeVar("TModel")
+
+
+class MemoryCacheSyncAdapter:
+    """
+    Minimal in-memory implementation of :class:`~async_redis_client.ports.sync_cache_port.CacheSyncPort`.
+
+    Intended for domain/unit tests without Redis. Mutually exclusive storage per key:
+    JSON tree, ``BaseModel``, or integer counter (same collision rules as documented for Redis).
+    TTL is not simulated (``ttl_seconds`` is accepted and ignored).
+
+    Physical keys mirror Redis adapters: ``namespace + key_prefix +`` logical key passed to port methods.
+    """
+
+    __slots__ = ("_counters", "_json", "_models", "_namespace", "_key_prefix")
+
+    def __init__(
+        self,
+        *,
+        namespace: str = "",
+        key_prefix: str = "",
+    ) -> None:
+        self._json: dict[str, JsonValue] = {}
+        self._models: dict[str, BaseModel] = {}
+        self._counters: dict[str, int] = {}
+        self._namespace = namespace
+        self._key_prefix = key_prefix
+
+    def _full_key(self, logical_key: str) -> str:
+        return f"{self._namespace}{self._key_prefix}{logical_key}"
+
+    def close(self) -> None:
+        """No-op; satisfies :class:`~async_redis_client.ports.sync_cache_port.CacheSyncPort`."""
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    def _clear_non_counter(self, physical_key: str) -> None:
+        self._json.pop(physical_key, None)
+        self._models.pop(physical_key, None)
+
+    def get(self, key: str) -> JsonValue | None:
+        fk = self._full_key(key)
+        if fk in self._models:
+            raise SerializationError("Key holds a model instance; use get_as_model().")
+        if fk in self._counters:
+            raise SerializationError("Key holds a counter; use incr/decr APIs.")
+        return self._json.get(fk)
+
+    def set(self, key: str, value: JsonValue, ttl_seconds: int | None = None) -> None:
+        del ttl_seconds
+        fk = self._full_key(key)
+        self._clear_non_counter(fk)
+        self._json[fk] = value
+
+    def set_json(
+        self, key: str, value: JsonValue, ttl_seconds: int | None = None
+    ) -> None:
+        self.set(key, value, ttl_seconds=ttl_seconds)
+
+    def get_json(self, key: str) -> JsonValue | None:
+        return self.get(key)
+
+    def get_or_raise_if_missing(self, key: str) -> JsonValue:
+        fk = self._full_key(key)
+        if fk in self._models:
+            raise SerializationError("Key holds a model instance; use get_as_model().")
+        if fk in self._counters:
+            raise SerializationError("Key holds a counter; use incr/decr APIs.")
+        if fk not in self._json:
+            raise CacheKeyNotFoundError(key)
+        return self._json[fk]
+
+    def get_json_or_raise_if_missing(self, key: str) -> JsonValue:
+        return self.get_or_raise_if_missing(key)
+
+    def set_model(
+        self, key: str, model: BaseModel, ttl_seconds: int | None = None
+    ) -> None:
+        del ttl_seconds
+        fk = self._full_key(key)
+        self._clear_non_counter(fk)
+        self._models[fk] = model
+        self._json.pop(fk, None)
+
+    def get_as_model(self, key: str, model_type: type[TModel]) -> TModel | None:
+        fk = self._full_key(key)
+        if fk in self._json:
+            raw = TypeAdapter(JsonValue).dump_json(self._json[fk])
+            return TypeAdapter(model_type).validate_json(raw)
+        if fk in self._models:
+            m = self._models[fk]
+            if isinstance(m, model_type):
+                return m
+            return TypeAdapter(model_type).validate_python(m.model_dump())
+        if fk in self._counters:
+            raise SerializationError("Key holds a counter; cannot load as model.")
+        return None
+
+    def delete(self, key: str) -> int:
+        fk = self._full_key(key)
+        existed = fk in self._json or fk in self._models or fk in self._counters
+        self._json.pop(fk, None)
+        self._models.pop(fk, None)
+        self._counters.pop(fk, None)
+        return 1 if existed else 0
+
+    def exists(self, key: str) -> bool:
+        fk = self._full_key(key)
+        return fk in self._json or fk in self._models or fk in self._counters
+
+    def incr(self, key: str, amount: int = 1) -> int:
+        fk = self._full_key(key)
+        self._clear_non_counter(fk)
+        cur = self._counters.get(fk, 0) + amount
+        self._counters[fk] = cur
+        return cur
+
+    def decr(self, key: str, amount: int = 1) -> int:
+        return self.incr(key, -amount)
+
+    def incrby(self, key: str, amount: int) -> int:
+        return self.incr(key, amount)
+
+    def set_many(
+        self, mapping: Mapping[str, JsonValue], ttl_seconds: int | None = None
+    ) -> None:
+        for k, v in mapping.items():
+            self.set(k, v, ttl_seconds=ttl_seconds)
+
+    def get_many(self, keys: Sequence[str]) -> dict[str, JsonValue | None]:
+        return {k: self.get(k) for k in keys}

async_redis_client/adapters/redis/__init__.py

@@ -0,0 +1,4 @@
+from async_redis_client.adapters.redis.async_adapter import RedisCacheAsyncAdapter
+from async_redis_client.adapters.redis.sync_adapter import RedisCacheSyncAdapter
+
+__all__ = ["RedisCacheAsyncAdapter", "RedisCacheSyncAdapter"]

async_redis_client/adapters/redis/_helpers.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from cryptography.fernet import Fernet
+from pydantic import JsonValue
+
+from async_redis_client.crypto import decrypt_bytes, encrypt_bytes
+from async_redis_client.serialization import dump_json_value, load_json_value
+
+
+def full_key(namespace: str, key_prefix: str, logical_key: str) -> str:
+    """Physical Redis key: ``namespace + key_prefix + logical_key``."""
+    return f"{namespace}{key_prefix}{logical_key}"
+
+
+def redis_raw_to_bytes(raw: object) -> bytes:
+    if isinstance(raw, bytes):
+        return raw
+    if isinstance(raw, bytearray):
+        return bytes(raw)
+    return bytes(raw)
+
+
+def encrypt_json_tree(fernet: Fernet, value: JsonValue) -> bytes:
+    return encrypt_bytes(fernet, dump_json_value(value))
+
+
+def decrypt_json_tree(
+    fernet: Fernet,
+    raw: bytes,
+    *,
+    secondary: Fernet | None,
+) -> JsonValue:
+    plain = decrypt_bytes(fernet, raw, secondary=secondary)
+    return load_json_value(plain)
+
+
+def pipeline_enqueue_json_sets(
+    pipe: Any,
+    mapping: Mapping[str, JsonValue],
+    *,
+    namespace: str,
+    key_prefix: str,
+    fernet: Fernet,
+    ttl_seconds: int | None,
+) -> None:
+    for logical_key, value in mapping.items():
+        fk = full_key(namespace, key_prefix, logical_key)
+        blob = encrypt_json_tree(fernet, value)
+        if ttl_seconds is not None:
+            pipe.set(fk, blob, ex=ttl_seconds)
+        else:
+            pipe.set(fk, blob)
+
+
+def redis_keys_from_logical(
+    namespace: str, key_prefix: str, keys: Sequence[str]
+) -> list[str]:
+    return [full_key(namespace, key_prefix, k) for k in keys]
+
+
+def decode_mget_json_rows(
+    keys: Sequence[str],
+    values: Sequence[object | None],
+    *,
+    fernet: Fernet,
+    secondary: Fernet | None,
+) -> dict[str, JsonValue | None]:
+    out: dict[str, JsonValue | None] = {}
+    for logical, raw in zip(keys, values, strict=False):
+        if raw is None:
+            out[logical] = None
+            continue
+        data = redis_raw_to_bytes(raw)
+        out[logical] = decrypt_json_tree(fernet, data, secondary=secondary)
+    return out

async_redis_client/adapters/redis/async_adapter.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Self, TypeVar
+
+from pydantic import BaseModel, JsonValue
+from redis.asyncio import Redis as AsyncRedis
+from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster
+
+from async_redis_client.adapters.redis._helpers import (
+    decode_mget_json_rows,
+    decrypt_json_tree,
+    encrypt_json_tree,
+    full_key,
+    pipeline_enqueue_json_sets,
+    redis_keys_from_logical,
+    redis_raw_to_bytes,
+)
+from async_redis_client.crypto import (
+    build_fernet,
+    build_secondary_fernet,
+    decrypt_bytes,
+    encrypt_bytes,
+)
+from async_redis_client.errors import CacheClosedError, CacheKeyNotFoundError
+from async_redis_client.serialization import dump_model, load_as_type
+
+RedisAsyncClient = AsyncRedis | AsyncRedisCluster
+
+TModel = TypeVar("TModel")
+
+
+class RedisCacheAsyncAdapter:
+    """
+    Async Redis cache implementing :class:`~async_redis_client.ports.async_cache_port.CacheAsyncPort`.
+
+    Semantics match :class:`~async_redis_client.adapters.redis.sync_adapter.RedisCacheSyncAdapter`:
+    encrypted JSON/model payloads vs plaintext integer counters; Cluster hash-slot constraints
+    apply to :meth:`set_many` / :meth:`get_many`. Secondary Fernet key behaves as in the sync adapter.
+
+    **Lifecycle:** URL factories set ``owns_client=True``; use ``async with adapter:`` or await
+    :meth:`close`. Injected clients default to ``owns_client=False`` (you close the Redis client),
+    unless you pass ``owns_client=True``. :meth:`aclose` is an alias of :meth:`close`. After an
+    owned shutdown, operations raise :exc:`~async_redis_client.errors.CacheClosedError`.
+    """
+
+    __slots__ = (
+        "_client",
+        "_fernet",
+        "_fernet_secondary",
+        "_namespace",
+        "_key_prefix",
+        "_owns_client",
+        "_closed",
+    )
+
+    def __init__(
+        self,
+        client: RedisAsyncClient,
+        *,
+        fernet_key: bytes | None = None,
+        fernet_key_secondary: bytes | None = None,
+        namespace: str = "",
+        key_prefix: str = "",
+        owns_client: bool = False,
+    ) -> None:
+        self._client = client
+        self._fernet = build_fernet(fernet_key=fernet_key)
+        self._fernet_secondary = build_secondary_fernet(fernet_key=fernet_key_secondary)
+        self._namespace = namespace
+        self._key_prefix = key_prefix
+        self._owns_client = owns_client
+        self._closed = False
+
+    @classmethod
+    def from_standalone_url(
+        cls,
+        url: str,
+        *,
+        fernet_key: bytes | None = None,
+        fernet_key_secondary: bytes | None = None,
+        namespace: str = "",
+        key_prefix: str = "",
+        **kwargs: object,
+    ) -> RedisCacheAsyncAdapter:
+        client = AsyncRedis.from_url(url, **kwargs)  # type: ignore[arg-type]
+        return cls(
+            client,
+            fernet_key=fernet_key,
+            fernet_key_secondary=fernet_key_secondary,
+            namespace=namespace,
+            key_prefix=key_prefix,
+            owns_client=True,
+        )
+
+    @classmethod
+    def from_cluster_url(
+        cls,
+        url: str,
+        *,
+        fernet_key: bytes | None = None,
+        fernet_key_secondary: bytes | None = None,
+        namespace: str = "",
+        key_prefix: str = "",
+        **kwargs: object,
+    ) -> RedisCacheAsyncAdapter:
+        client = AsyncRedisCluster.from_url(url, **kwargs)  # type: ignore[arg-type]
+        return cls(
+            client,
+            fernet_key=fernet_key,
+            fernet_key_secondary=fernet_key_secondary,
+            namespace=namespace,
+            key_prefix=key_prefix,
+            owns_client=True,
+        )
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        if self._owns_client:
+            await self._client.aclose()
+            self._owns_client = False
+            self._closed = True
+
+    aclose = close
+
+    async def __aenter__(self) -> Self:
+        self._require_open()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.close()
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise CacheClosedError("Redis cache adapter is closed")
+
+    def _full_key(self, key: str) -> str:
+        return full_key(self._namespace, self._key_prefix, key)
+
+    async def get(self, key: str) -> JsonValue | None:
+        self._require_open()
+        raw = await self._client.get(self._full_key(key))
+        if raw is None:
+            return None
+        data = redis_raw_to_bytes(raw)
+        return decrypt_json_tree(self._fernet, data, secondary=self._fernet_secondary)
+
+    async def set(
+        self, key: str, value: JsonValue, ttl_seconds: int | None = None
+    ) -> None:
+        self._require_open()
+        fk = self._full_key(key)
+        blob = encrypt_json_tree(self._fernet, value)
+        if ttl_seconds is not None:
+            await self._client.set(fk, blob, ex=ttl_seconds)
+        else:
+            await self._client.set(fk, blob)
+
+    async def set_json(
+        self, key: str, value: JsonValue, ttl_seconds: int | None = None
+    ) -> None:
+        await self.set(key, value, ttl_seconds=ttl_seconds)
+
+    async def get_json(self, key: str) -> JsonValue | None:
+        return await self.get(key)
+
+    async def get_or_raise_if_missing(self, key: str) -> JsonValue:
+        self._require_open()
+        raw = await self._client.get(self._full_key(key))
+        if raw is None:
+            raise CacheKeyNotFoundError(key)
+        data = redis_raw_to_bytes(raw)
+        return decrypt_json_tree(self._fernet, data, secondary=self._fernet_secondary)
+
+    async def get_json_or_raise_if_missing(self, key: str) -> JsonValue:
+        return await self.get_or_raise_if_missing(key)
+
+    async def set_model(
+        self, key: str, model: BaseModel, ttl_seconds: int | None = None
+    ) -> None:
+        self._require_open()
+        fk = self._full_key(key)
+        blob = encrypt_bytes(self._fernet, dump_model(model))
+        if ttl_seconds is not None:
+            await self._client.set(fk, blob, ex=ttl_seconds)
+        else:
+            await self._client.set(fk, blob)
+
+    async def get_as_model(self, key: str, model_type: type[TModel]) -> TModel | None:
+        self._require_open()
+        raw = await self._client.get(self._full_key(key))
+        if raw is None:
+            return None
+        data = redis_raw_to_bytes(raw)
+        plain = decrypt_bytes(self._fernet, data, secondary=self._fernet_secondary)
+        return load_as_type(model_type, plain)
+
+    async def delete(self, key: str) -> int:
+        self._require_open()
+        return int(await self._client.delete(self._full_key(key)))
+
+    async def exists(self, key: str) -> bool:
+        self._require_open()
+        return bool(await self._client.exists(self._full_key(key)))
+
+    async def incr(self, key: str, amount: int = 1) -> int:
+        self._require_open()
+        return int(await self._client.incrby(self._full_key(key), amount))
+
+    async def decr(self, key: str, amount: int = 1) -> int:
+        self._require_open()
+        return int(await self._client.decrby(self._full_key(key), amount))
+
+    async def incrby(self, key: str, amount: int) -> int:
+        self._require_open()
+        return int(await self._client.incrby(self._full_key(key), amount))
+
+    async def set_many(
+        self, mapping: Mapping[str, JsonValue], ttl_seconds: int | None = None
+    ) -> None:
+        self._require_open()
+        if not mapping:
+            return
+        pipe = self._client.pipeline(transaction=False)
+        pipeline_enqueue_json_sets(
+            pipe,
+            mapping,
+            namespace=self._namespace,
+            key_prefix=self._key_prefix,
+            fernet=self._fernet,
+            ttl_seconds=ttl_seconds,
+        )
+        await pipe.execute()
+
+    async def get_many(self, keys: Sequence[str]) -> dict[str, JsonValue | None]:
+        self._require_open()
+        if not keys:
+            return {}
+        rkeys = redis_keys_from_logical(self._namespace, self._key_prefix, keys)
+        values = await self._client.mget(rkeys)
+        return decode_mget_json_rows(
+            keys,
+            values,
+            fernet=self._fernet,
+            secondary=self._fernet_secondary,
+        )