omnixys-cache 3.0.6__py3-none-any.whl

cache/__init__.py

@@ -0,0 +1,43 @@
+from cache.client import CacheClient
+from cache.delayed_job import (
+    DelayedJob,
+    DelayedJobContext,
+    DelayedJobHandlerNotFoundError,
+    DelayedJobRegistry,
+    DelayedJobSchedule,
+    DelayedJobService,
+    DelayedJobWorker,
+    delayed_job,
+)
+from cache.invalidation import CacheInvalidationService
+from cache.keys import create_key, key
+from cache.lock import CacheLock, LockNotAcquiredError
+from cache.model import CacheKeyDefinition, CacheSerializer
+from cache.rate_limit import RateLimiter, RateLimitResult
+from cache.serializer import JsonCacheSerializer, StrictJsonCacheSerializer
+from cache.stream import StreamMessage, ValkeyStreamService
+
+__all__ = [
+    "CacheClient",
+    "CacheInvalidationService",
+    "CacheKeyDefinition",
+    "CacheLock",
+    "CacheSerializer",
+    "DelayedJob",
+    "DelayedJobContext",
+    "DelayedJobHandlerNotFoundError",
+    "DelayedJobRegistry",
+    "DelayedJobSchedule",
+    "DelayedJobService",
+    "DelayedJobWorker",
+    "JsonCacheSerializer",
+    "LockNotAcquiredError",
+    "RateLimitResult",
+    "RateLimiter",
+    "StreamMessage",
+    "StrictJsonCacheSerializer",
+    "ValkeyStreamService",
+    "create_key",
+    "delayed_job",
+    "key",
+]

cache/client.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any
+
+from redis.asyncio import Redis
+
+from cache.model import CacheKeyDefinition, CacheSerializer
+from cache.serializer import JsonCacheSerializer
+
+
+class CacheClient:
+    def __init__(
+        self,
+        url: str | None = None,
+        key_prefix: str = "",
+        password: str | None = None,
+        serializer: CacheSerializer | None = None,
+        client: Redis | None = None,
+    ) -> None:
+        if client is not None:
+            self._client = client
+        else:
+            if url is None:
+                raise ValueError("Either 'url' or 'client' must be provided")
+            self._client = Redis.from_url(
+                url,
+                password=password or None,
+                decode_responses=True,
+                health_check_interval=30,
+            )
+        self._prefix = key_prefix
+        self._serializer = serializer or JsonCacheSerializer()
+
+    async def ping(self) -> bool:
+        return bool(await self._client.ping())
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def get(self, key: str | CacheKeyDefinition, *parts: str) -> str | None:
+        key_str = self._resolve(key, *parts)
+        value = await self._client.get(key_str)
+        return str(value) if value is not None else None
+
+    async def set(
+        self,
+        key: str | CacheKeyDefinition,
+        value: str,
+        ttl_seconds: int | None = None,
+        *parts: str,
+    ) -> None:
+        key_str = self._resolve(key, *parts)
+        ttl = self._resolve_ttl(key, ttl_seconds)
+        await self._client.set(key_str, value, ex=ttl)
+
+    async def delete(self, key: str | CacheKeyDefinition, *parts: str) -> int:
+        key_str = self._resolve(key, *parts)
+        result = await self._client.delete(key_str)
+        return int(result)
+
+    async def exists(self, key: str | CacheKeyDefinition, *parts: str) -> bool:
+        key_str = self._resolve(key, *parts)
+        return bool(await self._client.exists(key_str))
+
+    async def expire(self, key: str | CacheKeyDefinition, ttl_seconds: int, *parts: str) -> bool:
+        key_str = self._resolve(key, *parts)
+        return bool(await self._client.expire(key_str, ttl_seconds))
+
+    async def ttl(self, key: str | CacheKeyDefinition, *parts: str) -> int:
+        key_str = self._resolve(key, *parts)
+        result = await self._client.ttl(key_str)
+        return int(result)
+
+    async def increment(self, key: str | CacheKeyDefinition, ttl_seconds: int | None = None, *parts: str) -> int:
+        key_str = self._resolve(key, *parts)
+        val = await self._client.incr(key_str)
+        ttl = self._resolve_ttl(key, ttl_seconds)
+        if ttl is not None:
+            await self._client.expire(key_str, ttl)
+        return int(val)
+
+    async def get_json(
+        self,
+        key: str | CacheKeyDefinition,
+        *parts: str,
+    ) -> Any | None:
+        value = await self.get(key, *parts)
+        if value is None:
+            return None
+        return self._serializer.deserialize(value)
+
+    async def set_json(
+        self,
+        key: str | CacheKeyDefinition,
+        value: Any,
+        ttl_seconds: int | None = None,
+        *parts: str,
+    ) -> None:
+        serialized = self._serializer.serialize(value)
+        key_str = self._resolve(key, *parts)
+        ttl = self._resolve_ttl(key, ttl_seconds)
+        await self._client.set(key_str, serialized, ex=ttl)
+
+    async def set_if_not_exists(
+        self,
+        key: str | CacheKeyDefinition,
+        value: str,
+        ttl_seconds: int | None = None,
+        *parts: str,
+    ) -> bool:
+        key_str = self._resolve(key, *parts)
+        ttl = self._resolve_ttl(key, ttl_seconds)
+        result = await self._client.set(key_str, value, ex=ttl, nx=True)
+        return result is not None
+
+    @property
+    def raw(self) -> Redis:
+        """The underlying redis.asyncio client for advanced low-level access."""
+        return self._client
+
+    async def set_nx_px(self, key: str, value: str, ttl_ms: int) -> bool:
+        """Atomically set a raw key only if absent, expiring in milliseconds."""
+        result = await self._client.set(key, value, nx=True, px=ttl_ms)
+        return result is not None
+
+    def _resolve(self, key: str | CacheKeyDefinition, *parts: str) -> str:
+        raw = key.key(*parts) if isinstance(key, CacheKeyDefinition) else ":".join((key, *parts)) if parts else key
+        return f"{self._prefix}:{raw}" if self._prefix else raw
+
+    @staticmethod
+    def _resolve_ttl(key: str | CacheKeyDefinition, ttl_seconds: int | None) -> int | None:
+        if ttl_seconds is not None:
+            return ttl_seconds
+        if isinstance(key, CacheKeyDefinition):
+            return key.ttl_seconds
+        return None

cache/container.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dishka import Provider, Scope, provide
+from redis.asyncio import Redis
+
+from cache.client import CacheClient
+from cache.delayed_job import DelayedJobRegistry, DelayedJobService, get_default_registry
+from cache.invalidation import CacheInvalidationService
+from cache.lock import CacheLock
+from cache.rate_limit import RateLimiter
+from cache.serializer import JsonCacheSerializer
+from cache.stream import ValkeyStreamService
+
+
+class CacheProvider(Provider):
+    scope = Scope.APP
+
+    @provide
+    def serializer(self) -> JsonCacheSerializer:
+        return JsonCacheSerializer()
+
+    @provide
+    def cache_client(
+        self,
+        url: str,
+        key_prefix: str = "",
+        serializer: JsonCacheSerializer | None = None,
+    ) -> CacheClient:
+        return CacheClient(url=url, key_prefix=key_prefix, serializer=serializer)
+
+    @provide
+    def invalidation(self, url: str, channel: str = "omnixys:cache:invalidate") -> CacheInvalidationService:
+        return CacheInvalidationService(
+            redis=Redis.from_url(url, decode_responses=True),
+            channel=channel,
+        )
+
+    @provide
+    def lock(self, client: CacheClient) -> CacheLock:
+        return CacheLock(client)
+
+    @provide
+    def rate_limiter(self, client: CacheClient) -> RateLimiter:
+        return RateLimiter(client)
+
+    @provide
+    def stream_service(self, client: CacheClient) -> ValkeyStreamService:
+        return ValkeyStreamService(client)
+
+    @provide
+    def delayed_job_service(self, client: CacheClient) -> DelayedJobService:
+        return DelayedJobService(client)
+
+    @provide
+    def delayed_job_registry(self) -> DelayedJobRegistry:
+        return get_default_registry()

cache/delayed_job.py

@@ -0,0 +1,392 @@
+"""Delayed jobs scheduled on a Redis sorted set with persisted records.
+
+A job is scheduled with an absolute execution timestamp. `DelayedJobWorker`
+atomically claims due jobs (ZRANGEBYSCORE + ZREM via a WATCH/MULTI
+transaction) and executes the registered handler through the
+`DelayedJobRegistry`. Failed jobs are retried with a linear backoff until
+`max_retries` is exhausted, after which they are marked as failed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import secrets
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+import redis as redis_pkg
+from redis.asyncio import Redis
+
+from cache.client import CacheClient
+
+QUEUE_KEY = "delayed:jobs:scheduled"
+RECORD_KEY_PREFIX = "delayed:job"
+RECORD_TTL_SECONDS = 7 * 24 * 60 * 60
+
+DelayedJobState = Literal["scheduled", "running", "completed", "failed", "canceled"]
+
+JobHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+def now_ms() -> int:
+    return int(datetime.now(UTC).timestamp() * 1000)
+
+
+@dataclass(frozen=True, slots=True)
+class DelayedJobContext:
+    request_id: str = "unscoped"
+    correlation_id: str = "unscoped"
+    trace_id: str | None = None
+    actor_id: str | None = None
+    tenant_id: str | None = None
+
+
+@dataclass(slots=True)
+class DelayedJob:
+    id: str
+    type: str
+    payload: dict[str, Any]
+    execute_at_ms: int
+    retries: int = 0
+    max_retries: int = 3
+    retry_delay_ms: int = 1000
+    status: DelayedJobState = "scheduled"
+    created_at_ms: int = field(default_factory=now_ms)
+    updated_at_ms: int = field(default_factory=now_ms)
+    last_error: str | None = None
+    context: DelayedJobContext | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "type": self.type,
+            "payload": self.payload,
+            "executeAtMs": self.execute_at_ms,
+            "retries": self.retries,
+            "maxRetries": self.max_retries,
+            "retryDelayMs": self.retry_delay_ms,
+            "status": self.status,
+            "createdAtMs": self.created_at_ms,
+            "updatedAtMs": self.updated_at_ms,
+            "lastError": self.last_error,
+            "context": dataclass_to_dict(self.context),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DelayedJob:
+        return cls(
+            id=str(data["id"]),
+            type=str(data["type"]),
+            payload=data.get("payload") or {},
+            execute_at_ms=int(data["executeAtMs"]),
+            retries=int(data.get("retries", 0)),
+            max_retries=int(data.get("maxRetries", 3)),
+            retry_delay_ms=int(data.get("retryDelayMs", 1000)),
+            status=data.get("status", "scheduled"),
+            created_at_ms=int(data.get("createdAtMs", 0)),
+            updated_at_ms=int(data.get("updatedAtMs", 0)),
+            last_error=data.get("lastError"),
+            context=_context_from_dict(data.get("context")),
+        )
+
+
+def dataclass_to_dict(context: DelayedJobContext | None) -> dict[str, str | None] | None:
+    if context is None:
+        return None
+    return {
+        "requestId": context.request_id,
+        "correlationId": context.correlation_id,
+        "traceId": context.trace_id,
+        "actorId": context.actor_id,
+        "tenantId": context.tenant_id,
+    }
+
+
+def _context_from_dict(data: Any) -> DelayedJobContext | None:
+    if not isinstance(data, dict):
+        return None
+    return DelayedJobContext(
+        request_id=str(data.get("requestId", "unscoped")),
+        correlation_id=str(data.get("correlationId", "unscoped")),
+        trace_id=data.get("traceId"),
+        actor_id=data.get("actorId"),
+        tenant_id=data.get("tenantId"),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class DelayedJobSchedule:
+    type: str
+    payload: dict[str, Any]
+    delay_ms: int
+    max_retries: int = 3
+    retry_delay_ms: int = 1000
+    context: DelayedJobContext | None = None
+
+
+class DelayedJobHandlerNotFoundError(Exception):
+    def __init__(self, job_type: str) -> None:
+        self.job_type = job_type
+        super().__init__(f"No handler registered for delayed job type '{job_type}'")
+
+
+class DelayedJobRegistry:
+    """Maps delayed-job types to their async handlers."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, JobHandler] = {}
+
+    def register(self, job_type: str, handler: JobHandler) -> None:
+        self._handlers[job_type] = handler
+
+    def execute(self, job_type: str, payload: dict[str, Any]) -> Awaitable[Any]:
+        handler = self._handlers.get(job_type)
+        if handler is None:
+            raise DelayedJobHandlerNotFoundError(job_type)
+        return handler(payload)
+
+    def has(self, job_type: str) -> bool:
+        return job_type in self._handlers
+
+    def handlers(self) -> tuple[str, ...]:
+        return tuple(sorted(self._handlers))
+
+    def __len__(self) -> int:
+        return len(self._handlers)
+
+
+_default_registry = DelayedJobRegistry()
+
+
+def get_default_registry() -> DelayedJobRegistry:
+    return _default_registry
+
+
+def delayed_job(job_type: str) -> Callable[[JobHandler], JobHandler]:
+    """Decorator that registers an async handler for a delayed-job type."""
+
+    def decorator(handler: JobHandler) -> JobHandler:
+        _default_registry.register(job_type, handler)
+        return handler
+
+    return decorator
+
+
+class DelayedJobService:
+    def __init__(self, client: CacheClient) -> None:
+        self._client = client
+
+    @property
+    def raw(self) -> Redis:
+        return self._client.raw
+
+    async def schedule(self, schedule: DelayedJobSchedule) -> str:
+        """Schedule a job and return its id."""
+        if schedule.delay_ms < 0:
+            raise ValueError("Delayed job delay_ms must be non-negative")
+        if schedule.max_retries < 0:
+            raise ValueError("Delayed job max_retries must be non-negative")
+
+        now = now_ms()
+        job = DelayedJob(
+            id=secrets.token_hex(16),
+            type=schedule.type,
+            payload=schedule.payload,
+            execute_at_ms=now + schedule.delay_ms,
+            max_retries=schedule.max_retries,
+            retry_delay_ms=schedule.retry_delay_ms,
+            context=schedule.context,
+        )
+        await self.persist(job)
+        await self.raw.zadd(QUEUE_KEY, {job.id: job.execute_at_ms})
+        return job.id
+
+    async def cancel(self, job_id: str) -> bool:
+        job = await self.status(job_id)
+        if job is None or job.status in ("completed", "running", "canceled", "failed"):
+            return False
+        await self.raw.zrem(QUEUE_KEY, job_id)
+        job.status = "canceled"
+        job.updated_at_ms = now_ms()
+        await self.persist(job)
+        return True
+
+    async def retry(self, job_id: str, delay_ms: int = 0) -> bool:
+        if delay_ms < 0:
+            raise ValueError("Delayed job retry delay must be non-negative")
+        job = await self.status(job_id)
+        if job is None or job.status == "running":
+            return False
+        job.status = "scheduled"
+        job.execute_at_ms = now_ms() + delay_ms
+        job.updated_at_ms = now_ms()
+        job.last_error = None
+        await self.persist(job)
+        await self.raw.zadd(QUEUE_KEY, {job.id: job.execute_at_ms})
+        return True
+
+    async def status(self, job_id: str) -> DelayedJob | None:
+        raw = await self.raw.get(self._record_key(job_id))
+        if not raw:
+            return None
+        try:
+            return DelayedJob.from_dict(json.loads(raw))
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+            return None
+
+    async def claim_due(self, count: int = 10) -> list[DelayedJob]:
+        """Atomically claim up to `count` due jobs and mark them running."""
+        claimed_ids = await self._claim_due_ids(count)
+        jobs: list[DelayedJob] = []
+        for raw_id in claimed_ids:
+            job = await self.status(str(raw_id))
+            if job is None or job.status != "scheduled":
+                continue
+            job.status = "running"
+            job.updated_at_ms = now_ms()
+            await self.persist(job)
+            jobs.append(job)
+        return jobs
+
+    async def _claim_due_ids(self, count: int) -> list[str]:
+        pipe = self.raw.pipeline(transaction=True)
+        while True:
+            try:
+                await pipe.watch(QUEUE_KEY)
+                ids = await pipe.zrangebyscore(QUEUE_KEY, "-inf", now_ms(), start=0, num=count)
+                if not ids:
+                    await pipe.unwatch()  # type: ignore[no-untyped-call]
+                    return []
+                pipe.multi()  # type: ignore[no-untyped-call]
+                pipe.zrem(QUEUE_KEY, *ids)
+                await pipe.execute()
+                return [str(item) for item in ids]
+            except redis_pkg.WatchError:
+                continue
+
+    async def complete(self, job: DelayedJob) -> None:
+        job.status = "completed"
+        job.updated_at_ms = now_ms()
+        await self.persist(job)
+
+    async def fail(self, job: DelayedJob, error: Any) -> None:
+        job.retries += 1
+        job.last_error = str(error) if error else "unknown error"
+        job.updated_at_ms = now_ms()
+        if job.retries <= job.max_retries:
+            job.status = "scheduled"
+            job.execute_at_ms = now_ms() + job.retry_delay_ms * job.retries
+            await self.persist(job)
+            await self.raw.zadd(QUEUE_KEY, {job.id: job.execute_at_ms})
+            return
+        job.status = "failed"
+        await self.persist(job)
+
+    async def persist(self, job: DelayedJob) -> None:
+        await self.raw.set(
+            self._record_key(job.id),
+            json.dumps(job.to_dict()),
+            ex=RECORD_TTL_SECONDS,
+        )
+
+    def _record_key(self, job_id: str) -> str:
+        return f"{RECORD_KEY_PREFIX}:{job_id}"
+
+
+class DelayedJobWorker:
+    """Background loop that claims and executes due delayed jobs."""
+
+    def __init__(
+        self,
+        service: DelayedJobService,
+        registry: DelayedJobRegistry | None = None,
+        *,
+        claim_count: int = 10,
+        poll_interval_ms: int = 250,
+        on_error: Callable[[str, Any], None] | None = None,
+    ) -> None:
+        self._service = service
+        self._registry = registry or _default_registry
+        self._claim_count = claim_count
+        self._poll_interval_ms = poll_interval_ms
+        self._on_error = on_error
+        self._running = False
+        self._in_flight = 0
+        self._task: asyncio.Task[None] | None = None
+
+    def ready(self) -> bool:
+        return self._running
+
+    def status(self) -> DelayedJobState:
+        if not self._running:
+            return "running" if self._in_flight > 0 else "canceled"
+        return "running" if self._in_flight > 0 else "scheduled"
+
+    def health(self) -> dict[str, Any]:
+        return {"healthy": self._running, "status": self.status()}
+
+    def diagnostics(self) -> dict[str, Any]:
+        return {
+            "status": self.status(),
+            "inFlight": self._in_flight,
+            "handlers": self._registry.handlers(),
+        }
+
+    async def start(self) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._task = asyncio.create_task(self._run(), name="delayed-job-worker")
+
+    async def _run(self) -> None:
+        while self._running:
+            try:
+                jobs = await self._service.claim_due(self._claim_count)
+                for job in jobs:
+                    await self._handle(job)
+                if not jobs:
+                    await asyncio.sleep(self._poll_interval_ms / 1000)
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:  # noqa: BLE001
+                if not self._running:
+                    break
+                if self._on_error is not None:
+                    self._on_error("delayed_job_worker", exc)
+                await asyncio.sleep(1.0)
+
+    async def _handle(self, job: DelayedJob) -> None:
+        self._in_flight += 1
+        try:
+            await self._registry.execute(job.type, job.payload)
+            await self._service.complete(job)
+        except Exception as exc:  # noqa: BLE001
+            await self._service.fail(job, exc)
+            if self._on_error is not None:
+                self._on_error(job.type, exc)
+        finally:
+            self._in_flight -= 1
+
+    async def drain(self, timeout_ms: int = 5000) -> None:
+        deadline = now_ms() + timeout_ms
+        while self._in_flight > 0:
+            if now_ms() >= deadline:
+                raise TimeoutError(f"Delayed job drain timed out after {timeout_ms}ms")
+            await asyncio.sleep(0.01)
+
+    async def close(self) -> None:
+        if self._task is None and not self._running:
+            return
+        self._running = False
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+        await self.drain()
+
+    shutdown = close

cache/invalidation.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from redis.asyncio import Redis
+
+
+class CacheInvalidationService:
+    def __init__(self, redis: Redis, channel: str = "omnixys:cache:invalidate") -> None:
+        self._redis = redis
+        self._channel = channel
+        self._pubsub = redis.pubsub()
+
+    async def publish(
+        self,
+        key: str,
+        operation: str = "delete",
+        source: str = "",
+        request_id: str | None = None,
+        correlation_id: str | None = None,
+    ) -> None:
+        event = {
+            "eventId": str(uuid4()),
+            "key": key,
+            "operation": operation,
+            "source": source,
+            "occurredAtEpochMs": int(datetime.now(UTC).timestamp() * 1000),
+            "requestId": request_id or "",
+            "correlationId": correlation_id or "",
+        }
+        await self._redis.publish(self._channel, json.dumps(event))
+
+    async def subscribe(self) -> None:
+        await self._pubsub.subscribe(self._channel)
+
+    async def unsubscribe(self) -> None:
+        await self._pubsub.unsubscribe(self._channel)
+
+    async def get_message(self, poll_timeout: float = 1.0) -> dict[str, Any] | None:
+        raw = await self._pubsub.get_message(timeout=poll_timeout, ignore_subscribe_messages=True)
+        if raw is None or raw["type"] != "message":
+            return None
+        data = raw.get("data", "")
+        if isinstance(data, bytes):
+            data = data.decode("utf-8")
+        return json.loads(data) if data else None
+
+    async def close(self) -> None:
+        await self._pubsub.close()

cache/keys.py

@@ -0,0 +1,24 @@
+"""Typed cache key definitions and the `create_key` builder."""
+
+from __future__ import annotations
+
+import math
+
+from cache.model import CacheKeyDefinition
+
+
+def create_key(prefix: str, ttl_seconds: int | None = None) -> CacheKeyDefinition:
+    """Build a `CacheKeyDefinition`, validating the TTL.
+
+    Raises:
+        ValueError: when `ttl_seconds` is not a positive finite number.
+    """
+    if ttl_seconds is not None and (not math.isfinite(ttl_seconds) or ttl_seconds <= 0):
+        raise ValueError("Cache key ttl_seconds must be a positive finite number")
+    return CacheKeyDefinition(prefix=prefix, ttl_seconds=ttl_seconds)
+
+
+def key(name: str, *parts: str) -> CacheKeyDefinition:
+    """Convenience shorthand for `create_key` with an optional suffix chain."""
+    prefix = ":".join((name, *parts)) if parts else name
+    return CacheKeyDefinition(prefix=prefix)

cache/lock.py

@@ -0,0 +1,72 @@
+"""Distributed lock support backed by a Redis/Valkey SET NX PX primitive."""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import redis as redis_pkg
+from redis.asyncio import Redis
+
+from cache.client import CacheClient
+
+
+class LockNotAcquiredError(Exception):
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(f"Could not acquire lock for key '{key}'")
+
+
+class CacheLock:
+    """Non-blocking distributed lock with a safety TTL and token-based release.
+
+    The lock is released atomically (WATCH + GET + MULTI DEL) only when the
+    stored token matches, so a lock acquired by another holder can never be
+    released by us.
+    """
+
+    def __init__(self, client: CacheClient) -> None:
+        self._client = client
+
+    @property
+    def raw(self) -> Redis:
+        return self._client.raw
+
+    async def acquire(self, key: str, ttl_ms: int = 3000) -> str | None:
+        """Try to acquire `key`; returns the release token or None if already held."""
+        token = secrets.token_hex(16)
+        acquired = await self._client.set_nx_px(key, token, ttl_ms)
+        return token if acquired else None
+
+    async def release(self, key: str, token: str) -> bool:
+        """Release `key` if and only if it is still held by `token`."""
+        pipe = self.raw.pipeline(transaction=True)
+        while True:
+            try:
+                await pipe.watch(key)
+                stored = await pipe.get(key)
+                if stored != token:
+                    await pipe.unwatch()  # type: ignore[no-untyped-call]
+                    return False
+                pipe.multi()  # type: ignore[no-untyped-call]
+                pipe.delete(key)
+                await pipe.execute()
+            except redis_pkg.WatchError:
+                continue
+            else:
+                return True
+
+    async def is_locked(self, key: str) -> bool:
+        return await self._client.exists(key)
+
+    @asynccontextmanager
+    async def locked(self, key: str, ttl_ms: int = 3000) -> AsyncIterator[None]:
+        """Context manager that acquires `key` and raises if it is already held."""
+        token = await self.acquire(key, ttl_ms)
+        if token is None:
+            raise LockNotAcquiredError(key)
+        try:
+            yield
+        finally:
+            await self.release(key, token)

cache/model.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CacheSerializer(Protocol):
+    def serialize(self, value: Any) -> str: ...
+    def deserialize(self, data: str) -> Any: ...
+
+
+@dataclass(frozen=True)
+class CacheKeyDefinition:
+    prefix: str
+    ttl_seconds: int | None = None
+
+    def key(self, *parts: str) -> str:
+        return ":".join((self.prefix, *parts)) if parts else self.prefix

cache/rate_limit.py

@@ -0,0 +1,42 @@
+"""Fixed-window rate limiting backed by atomic Redis INCR/EXPIRE."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cache.client import CacheClient
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitResult:
+    allowed: bool
+    current: int
+    limit: int
+    remaining: int
+
+
+class RateLimiter:
+    """Fixed-window rate limiter.
+
+    Each `hit` atomically increments the counter for `key` and sets the TTL on
+    the first increment of the window. The window is therefore reset after
+    `ttl_seconds` pass.
+    """
+
+    def __init__(self, client: CacheClient) -> None:
+        self._client = client
+
+    async def hit(self, key: str, limit: int, ttl_seconds: int) -> bool:
+        """Record one hit; returns True if still within `limit` for the window."""
+        current = await self._client.increment(key, ttl_seconds=ttl_seconds)
+        return current <= limit
+
+    async def check(self, key: str, limit: int, ttl_seconds: int) -> RateLimitResult:
+        """Record one hit and return the full rate-limit result."""
+        current = await self._client.increment(key, ttl_seconds=ttl_seconds)
+        return RateLimitResult(
+            allowed=current <= limit,
+            current=current,
+            limit=limit,
+            remaining=max(limit - current, 0),
+        )

cache/serializer.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+class JsonCacheSerializer:
+    def serialize(self, value: Any) -> str:
+        return json.dumps(value, default=str)
+
+    def deserialize(self, data: str) -> Any | None:
+        try:
+            return json.loads(data)
+        except json.JSONDecodeError:
+            return None
+
+
+class StrictJsonCacheSerializer:
+    def serialize(self, value: Any) -> str:
+        return json.dumps(value, default=str)
+
+    def deserialize(self, data: str) -> Any:
+        try:
+            return json.loads(data)
+        except json.JSONDecodeError as exc:
+            msg = f"Failed to deserialize cache value: {exc}"
+            raise ValueError(msg) from exc

cache/stream.py

@@ -0,0 +1,101 @@
+"""Redis Streams consumer-group support for reliable work queues."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from redis.asyncio import Redis
+from redis.exceptions import ResponseError
+
+from cache.client import CacheClient
+
+_DATA_FIELD = "data"
+
+
+@dataclass(frozen=True, slots=True)
+class StreamMessage[T]:
+    id: str
+    data: T
+
+
+class ValkeyStreamService:
+    """Stream + consumer-group facade over a shared CacheClient.
+
+    Messages are stored as JSON in a single `data` field so payloads stay
+    transport-neutral.
+    """
+
+    def __init__(self, client: CacheClient) -> None:
+        self._client = client
+
+    @property
+    def raw(self) -> Redis:
+        return self._client.raw
+
+    async def ensure_group(self, stream: str, group: str) -> None:
+        """Create `group` on `stream` if missing (idempotent)."""
+        try:
+            await self.raw.xgroup_create(stream, group, id="$", mkstream=True)
+        except ResponseError as exc:
+            if "BUSYGROUP" in str(exc):
+                return
+            raise
+
+    async def enqueue(self, stream: str, payload: Any) -> str:
+        """Append `payload` to `stream`; returns the message id."""
+        result = await self.raw.xadd(stream, {_DATA_FIELD: json.dumps(payload)})
+        return str(result)
+
+    async def consume(
+        self,
+        stream: str,
+        group: str,
+        consumer: str,
+        count: int = 10,
+        block_ms: int = 5000,
+    ) -> list[StreamMessage[Any]]:
+        """Read new (unconsumed) messages from `group` as `consumer`."""
+        response = await self.raw.xreadgroup(
+            group,
+            consumer,
+            {stream: ">"},
+            count=count,
+            block=block_ms,
+        )
+        return self._flatten(response)
+
+    async def read_pending(
+        self,
+        stream: str,
+        group: str,
+        consumer: str,
+        count: int = 10,
+    ) -> list[StreamMessage[Any]]:
+        """Read already-delivered but unacknowledged messages (id '0')."""
+        response = await self.raw.xreadgroup(
+            group,
+            consumer,
+            {stream: "0"},
+            count=count,
+        )
+        return self._flatten(response)
+
+    async def ack(self, stream: str, group: str, message_id: str) -> None:
+        await self.raw.xack(stream, group, message_id)
+
+    def _flatten(self, response: Any) -> list[StreamMessage[Any]]:
+        if not response:
+            return []
+        messages: list[StreamMessage[Any]] = []
+        for entry in response:
+            _, entries = entry
+            for message_id, fields in entries:
+                payload = fields.get(_DATA_FIELD.encode(), fields.get(_DATA_FIELD))
+                data: Any = None
+                if payload is not None:
+                    decoded = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+                    data = json.loads(decoded)
+                messages.append(StreamMessage(str(message_id), data))
+        return messages

omnixys_cache-3.0.6.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: omnixys-cache
+Version: 3.0.6
+Summary: Omnixys shared cache package (Redis/Valkey client, serialization, invalidation)
+Project-URL: Homepage, https://github.com/omnixys/omnixys
+Project-URL: Repository, https://github.com/omnixys/omnixys
+Author-email: Omnixys Team <team@omnixys.com>
+License: GPL-3.0-or-later
+Keywords: cache,omnixys,redis,serialization,valkey
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: redis>=5.4.0
+Description-Content-Type: text/markdown
+
+# omnixys-cache
+
+Omnixys shared cache package — a typed Redis/Valkey facade with JSON serialization, invalidation, distributed locks, rate limiting, streams with consumer groups, and delayed jobs, all on one client.
+
+## Installation
+
+```bash
+pip install omnixys-cache
+```
+
+## Features
+
+- **CacheClient**: async Redis/Valkey facade with typed keys, JSON serialization, TTL handling, atomic `NX`/`PX` ops and low-level `raw` access
+- **Key definitions**: `create_key(prefix, ttl_seconds)` and `key(...)` builders validated at construction time
+- **CacheLock**: distributed mutual-exclusion lock with token-based (WATCH/MULTI) release
+- **RateLimiter**: fixed-window rate limiting with `hit`/`check` and TTL window reset
+- **ValkeyStreamService**: stream + consumer-group queues (`ensureGroup`, `enqueue`, `consume`, `read_pending`, `ack`)
+- **Delayed jobs**: schedule/claim/retry/cancel delayed jobs with a worker loop and decorator-driven registry
+- **Invalidation**: `CacheInvalidationService` with pluggable strategies
+- **Serialization**: JSON serializers (`JsonCacheSerializer`, `StrictJsonCacheSerializer`)
+- **DI**: `CacheProvider` container integration (dishka)
+
+## Usage
+
+### Client and keys
+
+```python
+import asyncio
+from cache import CacheClient, create_key
+
+session = create_key("session", ttl_seconds=300)
+cache = CacheClient(url="redis://localhost:6379", key_prefix="myapp")
+
+async def main() -> None:
+    await cache.set_json(session, {"userId": 42}, parts=("u1",))  # myapp:session:u1
+    assert await cache.get_json(session, "u1") == {"userId": 42}
+    await cache.expire(session, 60, "u1")
+    await cache.close()
+
+asyncio.run(main())
+```
+
+Raw keys work too — pass a plain `str` and optional parts are joined with `:`.
+
+### Distributed lock
+
+```python
+from cache import CacheClient, CacheLock
+
+async with CacheLock(cache, "deploy:eu1", ttl_ms=30_000, wait_ms=10_000) as lock:
+    ...
+# or manually:
+lock = CacheLock(cache, "deploy:eu1", ttl_ms=30_000)
+if await lock.acquire():
+    try:
+        ...
+    finally:
+        await lock.release()
+```
+
+### Rate limiting
+
+```python
+from cache import CacheClient, RateLimiter
+
+limiter = RateLimiter(cache)
+if not await limiter.check("sms:user:42", limit=5, ttl_seconds=60).allowed:
+    raise RuntimeError("rate limit exceeded")
+```
+
+### Streams with consumer groups
+
+```python
+from cache import CacheClient, ValkeyStreamService
+
+streams = ValkeyStreamService(cache)
+await streams.ensure_group("jobs", "workers")
+
+await streams.enqueue("jobs", {"type": "resize", "imageId": "abc"})
+
+for message in await streams.consume("jobs", "workers", consumer="w1", block_ms=1_000):
+    payload = message.data          # {"type": "resize", "imageId": "abc"}
+    await streams.ack("jobs", "workers", message.id)
+```
+
+### Delayed jobs
+
+```python
+from cache import DelayedJobService, DelayedJobSchedule, DelayedJobWorker, delayed_job
+
+@delayed_job("image.resize")
+async def resize(payload: dict) -> None:
+    print(payload["imageId"])
+
+service = DelayedJobService(cache)
+job_id = await service.schedule(
+    DelayedJobSchedule(type="image.resize", payload={"imageId": "abc"}, delay_ms=5_000)
+)
+
+worker = DelayedJobWorker(service)          # uses the default (decorated) registry
+await worker.start()
+```
+
+Jobs are persisted as records (7-day TTL), scheduled on a sorted set (`delayed:jobs`), claimed atomically via WATCH/MULTI, retried on failure up to `max_retries`, and surfaced through `status()`, `cancel()`, `retry()`, and `claim_due()`.
+
+## Testing
+
+The package ships behavior-level tests (pytest + fakeredis, no server needed):
+
+```bash
+uv run pytest -q          # 47 tests
+uv run ruff check .       # lint
+uv run mypy src/          # strict typing
+```
+
+## License
+
+GPL-3.0-or-later

omnixys_cache-3.0.6.dist-info/RECORD

@@ -0,0 +1,15 @@
+cache/__init__.py,sha256=IbAYEoI9OMOCmEVmHiILTBq9Xt-PDTXadm8CjtCEEUY,1200
+cache/client.py,sha256=mbviah3eb0eIqChjtSRBObpH3d82adHhDkwGZTg5xcc,4791
+cache/container.py,sha256=Lef5Zv7LTD_0aqhbhWYq3qSyP9RPT9VWL8ZROl5c2aE,1728
+cache/delayed_job.py,sha256=YH5GJ61wrq-A9PqqHYLraDucBNmaN-AxGsKnQSL4wfY,13177
+cache/invalidation.py,sha256=sWdtLO1UmRnjRz0iQ61452EbzaNpPmw5chySqs5AWHQ,1671
+cache/keys.py,sha256=D-dPh41ZSAdQ22NX3iBoFBVDjeIYGQeuLkd3QxvTwwY,873
+cache/lock.py,sha256=hyYGCmyETQteJ-nZjWAATB13-qbJKNDb6eZtcklQUoM,2420
+cache/model.py,sha256=uRPY_dyTxSmXuP-sOJtHGOtVantVGYWlRdSCq03CvpQ,489
+cache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cache/rate_limit.py,sha256=Go4YQm5aUVHhZJB9KoS5irt7LL65wkEv0rGDKObonLk,1313
+cache/serializer.py,sha256=85tAcXQ_q-v6XJ_JldmEp_UKKeNaXWUK2eh-ZEtRn98,722
+cache/stream.py,sha256=cSMWRymsrKTk1l7J7ivxWW7Mb7MtPF1eDYArN-3LWiQ,3049
+omnixys_cache-3.0.6.dist-info/METADATA,sha256=dQqMIjq2IQ8a-cX4K6ZnNchAwz8um7QPgamVQ1Z-8Lc,4468
+omnixys_cache-3.0.6.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+omnixys_cache-3.0.6.dist-info/RECORD,,

omnixys_cache-3.0.6.dist-info/WHEEL

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