qx-cache 0.1.0__py3-none-any.whl

qx/cache/__init__.py

@@ -0,0 +1,20 @@
+"""Qx cache layer."""
+
+from __future__ import annotations
+
+from qx.cache.client import Cache, CacheSettings, create_client
+from qx.cache.distributed_lock import DistributedLock, LockNotHeldError
+from qx.cache.idempotency import IdempotencyConflictError, IdempotencyStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cache",
+    "CacheSettings",
+    "DistributedLock",
+    "IdempotencyConflictError",
+    "IdempotencyStore",
+    "LockNotHeldError",
+    "__version__",
+    "create_client",
+]

qx/cache/client/__init__.py

@@ -0,0 +1,96 @@
+"""Async Redis client wrapper.
+
+We use ``redis.asyncio`` directly — no custom wrapping of the data API. This
+module supplies:
+
+- ``CacheSettings`` (Pydantic settings, ``QX_CACHE__*`` env vars).
+- ``create_client(settings)`` — builds the singleton client with pooling.
+- A trivial ``Cache`` facade with the half-dozen methods we actually use across
+  the framework (``get_json`` / ``set_json`` / ``incr`` / ``expire``). Anyone
+  needing more reaches for the underlying ``Redis`` instance.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, ClassVar
+
+import redis.asyncio as aioredis
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["Cache", "CacheSettings", "create_client"]
+
+
+class CacheSettings(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="QX_CACHE__",
+        extra="ignore",
+    )
+
+    url: str = Field(default="redis://localhost:6379/0")
+    max_connections: int = 20
+    decode_responses: bool = False  # we decode ourselves where needed
+    socket_timeout_seconds: float = 2.0
+    socket_connect_timeout_seconds: float = 2.0
+    health_check_interval_seconds: int = 30
+
+
+def create_client(settings: CacheSettings) -> aioredis.Redis:
+    """Create a pooled async Redis client.
+
+    Idempotent: the same settings produce the same pool topology. Dispose with
+    ``await client.aclose()`` at shutdown.
+    """
+    pool = aioredis.ConnectionPool.from_url(
+        settings.url,
+        max_connections=settings.max_connections,
+        decode_responses=settings.decode_responses,
+        socket_timeout=settings.socket_timeout_seconds,
+        socket_connect_timeout=settings.socket_connect_timeout_seconds,
+        health_check_interval=settings.health_check_interval_seconds,
+    )
+    return aioredis.Redis(connection_pool=pool)
+
+
+class Cache:
+    """Thin facade over Redis for the framework's own use.
+
+    Services can take this for the common ops, or pull the raw client out of
+    DI (``Redis`` is registered alongside ``Cache``) when they need more.
+    """
+
+    def __init__(self, client: aioredis.Redis, *, namespace: str = "qx") -> None:
+        self._r = client
+        self._ns = namespace
+
+    def key(self, *parts: str) -> str:
+        return ":".join((self._ns, *parts))
+
+    async def get_json(self, key: str) -> Any | None:
+        raw = await self._r.get(key)
+        if raw is None:
+            return None
+        return json.loads(raw)
+
+    async def set_json(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        payload = json.dumps(value, default=str)
+        await self._r.set(key, payload, ex=ttl_seconds)
+
+    async def delete(self, key: str) -> bool:
+        return bool(await self._r.delete(key))
+
+    async def incr(self, key: str, *, by: int = 1) -> int:
+        return await self._r.incrby(key, by)  # type: ignore[no-any-return]
+
+    async def expire(self, key: str, seconds: int) -> bool:
+        return await self._r.expire(key, seconds)  # type: ignore[no-any-return]
+
+    async def exists(self, key: str) -> bool:
+        return bool(await self._r.exists(key))

qx/cache/distributed_lock/__init__.py

@@ -0,0 +1,96 @@
+"""Distributed lock.
+
+A simple ``SET NX EX`` lock with a token, for short-duration critical sections
+(leader-election bootstrap, outbox-relay singleton enforcement). NOT a
+replacement for proper coordination — for anything mission-critical, use a
+real consensus protocol (etcd, ZooKeeper) or a transactional advisory lock
+(``pg_advisory_lock``).
+
+The lock acquires a UUID token and stores it as the value; release runs a Lua
+script that only deletes the key if the value still matches the token. This
+prevents the classic "lock expired, someone else acquired, then I release
+their lock" footgun.
+
+Lock TTL is intentionally short (default 30s). If your critical section is
+longer, you have a different problem; consider whether the work belongs in
+the request path at all.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    import redis.asyncio as aioredis
+
+__all__ = ["DistributedLock", "LockNotHeldError"]
+
+
+_RELEASE_SCRIPT = """
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('DEL', KEYS[1])
+end
+return 0
+"""
+
+
+class LockNotHeldError(Exception):
+    """Raised on release when the lock was already lost (timed out, stolen)."""
+
+
+class DistributedLock:
+    """A single named lock instance.
+
+    Construct via ``DistributedLock(client, "leader:outbox-relay")`` once;
+    reuse to acquire/release.
+    """
+
+    def __init__(self, client: aioredis.Redis, name: str) -> None:
+        self._r = client
+        self._name = name
+        self._token: str | None = None
+
+    async def acquire(self, *, ttl_seconds: int = 30) -> bool:
+        """Try to acquire. Returns True on success, False if already held."""
+        token = str(uuid4())
+        # SET key token NX EX ttl — atomic. Returns OK only if not held.
+        ok = await self._r.set(self._name, token, nx=True, ex=ttl_seconds)
+        if ok:
+            self._token = token
+            return True
+        return False
+
+    async def renew(self, *, ttl_seconds: int = 30) -> bool:
+        """Extend TTL if we still hold the lock."""
+        if self._token is None:
+            return False
+        # Lua so the check-and-extend is atomic.
+        script = """
+        if redis.call('GET', KEYS[1]) == ARGV[1] then
+            return redis.call('EXPIRE', KEYS[1], ARGV[2])
+        end
+        return 0
+        """
+        result = await self._r.eval(script, 1, self._name, self._token, str(ttl_seconds))  # type: ignore[misc]
+        return bool(result)
+
+    async def release(self) -> None:
+        """Release the lock — only deletes if the token still matches."""
+        if self._token is None:
+            return
+        await self._r.eval(_RELEASE_SCRIPT, 1, self._name, self._token)  # type: ignore[misc]
+        self._token = None
+
+    @contextlib.asynccontextmanager
+    async def acquired(self, *, ttl_seconds: int = 30) -> AsyncIterator[bool]:
+        """Async context manager that yields whether we got the lock."""
+        ok = await self.acquire(ttl_seconds=ttl_seconds)
+        try:
+            yield ok
+        finally:
+            if ok:
+                await self.release()

qx/cache/idempotency/__init__.py

@@ -0,0 +1,172 @@
+"""Idempotency store.
+
+Implements the ``Idempotency-Key`` header pattern: a client sends a unique key
+with a request; if the same key + payload arrives again within the TTL, the
+server replays the stored response instead of re-executing the command.
+
+Storage shape (Redis hash, one per key)::
+
+    qx:idem:{tenant}:{key}
+        status     -> "in_progress" | "completed"
+        request_fp -> sha256 of the canonical request payload
+        response   -> JSON of the original response
+        created_at -> ISO timestamp
+
+The ``request_fp`` lets us distinguish two clients accidentally reusing the
+same key for different payloads — we 409 in that case rather than returning
+the wrong response. That's the difference between "idempotent" and "merely
+de-duplicated".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from qx.core import (
+    ConflictError,
+    InfrastructureError,
+    PreconditionFailedError,
+    Result,
+)
+
+if TYPE_CHECKING:
+    import redis.asyncio as aioredis
+
+__all__ = ["IdempotencyConflictError", "IdempotencyStore"]
+
+
+class IdempotencyConflictError(PreconditionFailedError):
+    """Same idempotency key, different payload — refuse to serve."""
+
+
+class IdempotencyStore:
+    """Store + retrieve idempotent operation outcomes."""
+
+    def __init__(
+        self,
+        client: aioredis.Redis,
+        *,
+        namespace: str = "qx:idem",
+        default_ttl_seconds: int = 24 * 3600,
+    ) -> None:
+        self._r = client
+        self._ns = namespace
+        self._ttl = default_ttl_seconds
+
+    def _key(self, tenant: str, idem_key: str) -> str:
+        return f"{self._ns}:{tenant}:{idem_key}"
+
+    @staticmethod
+    def fingerprint(payload: Any) -> str:
+        """Stable sha256 of a request payload."""
+        return hashlib.sha256(
+            json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode()
+        ).hexdigest()
+
+    async def begin(
+        self,
+        tenant: str,
+        idem_key: str,
+        payload: Any,
+        *,
+        ttl_seconds: int | None = None,
+    ) -> Result[None | dict[str, Any]]:
+        """Attempt to claim the key.
+
+        Returns:
+            ``Result.success(None)`` — caller may proceed (first time we see this key).
+            ``Result.success(stored_response)`` — replay the stored response.
+            ``Result.failure(IdempotencyConflictError)`` — same key, different
+              payload; client should retry with a fresh key or fix their bug.
+        """
+        key = self._key(tenant, idem_key)
+        fp = self.fingerprint(payload)
+        ttl = ttl_seconds or self._ttl
+
+        # We try to SETNX-style claim the slot atomically. WATCH+MULTI in Redis
+        # is the canonical pattern; here we use a small Lua script for clarity.
+        # 1) if no key, write status=in_progress + fp; return "claim"
+        # 2) if key exists with same fp: return whatever is stored
+        # 3) if key exists with different fp: return "conflict"
+        script = """
+        if redis.call('EXISTS', KEYS[1]) == 0 then
+            redis.call('HSET', KEYS[1], 'status', 'in_progress',
+                       'request_fp', ARGV[1], 'created_at', ARGV[2])
+            redis.call('EXPIRE', KEYS[1], ARGV[3])
+            return 'claim'
+        end
+        local stored_fp = redis.call('HGET', KEYS[1], 'request_fp')
+        if stored_fp ~= ARGV[1] then
+            return 'conflict'
+        end
+        local status = redis.call('HGET', KEYS[1], 'status')
+        if status == 'completed' then
+            return redis.call('HGET', KEYS[1], 'response')
+        end
+        return 'in_progress'
+        """
+        try:
+            result = await self._r.eval(  # type: ignore[misc]
+                script,
+                1,
+                key,
+                fp,
+                datetime.now(UTC).isoformat(),
+                str(ttl),
+            )
+        except Exception as exc:
+            return Result.failure(
+                InfrastructureError(
+                    code="idempotency.store_unavailable",
+                    message=f"idempotency store error: {exc}",
+                    cause=exc,
+                )
+            )
+
+        if result in {b"claim", "claim"}:
+            return Result.success(None)
+        if result in {b"conflict", "conflict"}:
+            return Result.failure(
+                IdempotencyConflictError(
+                    code="idempotency.payload_mismatch",
+                    message=(
+                        "Idempotency-Key already in use with a different request payload. "
+                        "Use a new key for a different request."
+                    ),
+                )
+            )
+        if result in {b"in_progress", "in_progress"}:
+            return Result.failure(
+                ConflictError(
+                    code="idempotency.in_progress",
+                    message=(
+                        "A request with this Idempotency-Key is already in progress. Retry shortly."
+                    ),
+                )
+            )
+        # Otherwise: a stored response payload
+        raw = result if isinstance(result, bytes) else result.encode()
+        return Result.success(json.loads(raw))
+
+    async def complete(
+        self,
+        tenant: str,
+        idem_key: str,
+        response: Any,
+        *,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Persist the response and mark the slot as completed."""
+        key = self._key(tenant, idem_key)
+        ttl = ttl_seconds or self._ttl
+        await self._r.hset(  # type: ignore[misc]
+            key,
+            mapping={
+                "status": "completed",
+                "response": json.dumps(response, default=str),
+            },
+        )
+        await self._r.expire(key, ttl)

qx_cache-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: qx-cache
+Version: 0.1.0
+Summary: Qx cache layer: Redis client, idempotency store, distributed locks
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: qx-core
+Requires-Dist: qx-di
+Requires-Dist: redis[hiredis]>=5.0.0
+Description-Content-Type: text/markdown
+
+# qx-cache
+
+Redis client, Lua-atomic idempotency store, and distributed lock for the Qx framework.
+
+## What lives here
+
+- **`qx.cache.Cache`** — thin async Redis client wrapper with typed `get`/`set`/`delete`/`exists` methods and TTL support.
+- **`qx.cache.CacheSettings`** — Pydantic settings for Redis connection URL.
+- **`qx.cache.create_client`** — async factory that opens and validates a Redis connection.
+- **`qx.cache.IdempotencyStore`** — Lua-script-based atomic check-and-set. A single round-trip to Redis either claims an idempotency key (first caller wins) or returns the cached result (all subsequent callers). Used by `IdempotencyBehavior` in the Mediator pipeline to make command handlers idempotent.
+- **`qx.cache.DistributedLock`** — Redis-backed advisory lock with TTL and async context-manager interface. Uses `SET NX PX` for acquisition and Lua for safe release (only the holder can release).
+- **`qx.cache.LockNotHeldError`** — raised when attempting to release a lock that has expired or was never acquired.
+
+## Usage
+
+### Idempotency store
+
+```python
+from qx.cache import IdempotencyStore, create_client
+
+redis = await create_client(settings.cache.url)
+store = IdempotencyStore(redis, ttl_seconds=3600)
+
+# In a command handler or pipeline behavior:
+key = f"create-order:{cmd.idempotency_key}"
+cached = await store.get(key)
+if cached is not None:
+    return Result.success(cached)
+
+result = await do_work(cmd)
+if result.is_success:
+    await store.set(key, result.value)
+return result
+```
+
+### Distributed lock
+
+```python
+from qx.cache import DistributedLock
+
+async with DistributedLock(redis, "outbox-relay-leader", ttl_seconds=30):
+    await relay.run_once()
+```
+
+## Design rules
+
+- **Lua atomicity** — `IdempotencyStore` uses a single Lua script for the check-and-set so there is no window between checking and setting, even under concurrent requests.
+- **No silent failures** — `DistributedLock` raises `LockNotHeldError` if the lock has expired before you release it, so callers know their critical section may have overlapped.
+- The cache layer has no dependency on `qx-db` or `qx-cqrs`. It can be used standalone.

qx_cache-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+qx/cache/__init__.py,sha256=TjMVdkN0mFPIq7m2Zbq_zYkzX6qj7I0VC2IDk1zxMw0,486
+qx/cache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qx/cache/client/__init__.py,sha256=7PQVCpCd-JPBahH3g9ftctESjG6GiJCD1qkyyyw50yA,3216
+qx/cache/distributed_lock/__init__.py,sha256=Wpm3sq_67oz0VtyS0WAGWIxybU5EUIVS__PphcnfrHo,3205
+qx/cache/idempotency/__init__.py,sha256=gx_Iqw_6wyCQGVZKouKw-ekS3XolontiTmr6UhuFHnE,5843
+qx_cache-0.1.0.dist-info/METADATA,sha256=bXqybQT_Q0jPYAm6mIixxCLvKuZaXOPuqwekoEKRqzs,2469
+qx_cache-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+qx_cache-0.1.0.dist-info/RECORD,,

qx_cache-0.1.0.dist-info/WHEEL

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