terp-cap-redis 0.1.0__tar.gz

terp_cap_redis-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_redis-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: terp-cap-redis
+Version: 0.1.0
+Summary: Terp Redis store adapters — shared idempotency, throttling, and cache state for multi-replica deployments.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: redis>=5
+Requires-Dist: terp-core==0.1.0
+Provides-Extra: all
+Requires-Dist: terp-cap-oidc==0.1.0; extra == 'all'
+Requires-Dist: terp-cap-realtime==0.1.0; extra == 'all'
+Provides-Extra: oidc
+Requires-Dist: terp-cap-oidc==0.1.0; extra == 'oidc'
+Provides-Extra: realtime
+Requires-Dist: terp-cap-realtime==0.1.0; extra == 'realtime'

terp_cap_redis-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-no-adhoc-background-runtime": 1
+}

terp_cap_redis-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-redis"
+version = "0.1.0"
+description = "Terp Redis store adapters — shared idempotency, throttling, and cache state for multi-replica deployments."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "redis>=5",
+]
+
+# Capability-facing adapters are OPT-IN extras, so the base distribution never installs
+# another capability: shared throttling/idempotency/cache must not drag in a
+# self-registering transport (realtime) or an SSO stack (oidc).
+[project.optional-dependencies]
+realtime = ["terp-cap-realtime==0.1.0"]
+oidc = ["terp-cap-oidc==0.1.0"]
+all = [
+    "terp-cap-realtime==0.1.0",
+    "terp-cap-oidc==0.1.0",
+]
+
+# A LIBRARY (store-adapter) capability: it provides Redis-backed implementations of
+# Terp's per-process store seams — IdempotencyStore, ThrottleStore, and CacheStore —
+# and declares NO `terp.capabilities` ModuleSpec entry point (nothing is auto-mounted)
+# and NO `terp.migrations` entry point (Redis owns no SQL tables). A composition root
+# opts in by wiring create_app(..., idempotency_store=..., throttle_store=...,
+# cache_store=..., require_shared_*=settings.is_production).
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.redis`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/redis"]

terp_cap_redis-0.1.0/src/terp/capabilities/redis/__init__.py

@@ -0,0 +1,94 @@
+"""terp.capabilities.redis — shared Redis-backed stores for horizontal deployments.
+
+Terp's kernel deliberately keeps the idempotency, throttling, and cache ports engine-free:
+``terp.core`` ships safe per-process defaults and boot guards, while a deployment that runs
+more than one replica wires a shared backend explicitly. This capability is that opt-in
+backend for Redis. It has no routes, models, or migrations; it is a library adapter a
+composition root constructs from either an existing redis-py client or a Redis URL and then
+passes to ``create_app``::
+
+    stores = RedisStoreBundle.from_url(settings.REDIS_URL)
+    create_app(
+        ...,
+        idempotency_store=stores.idempotency,
+        throttle_store=stores.throttle,
+        cache_store=stores.cache,
+        require_shared_idempotency_store=settings.is_production,
+        require_shared_throttle_store=settings.is_production,
+        require_shared_cache_store=settings.is_production,
+    )
+
+The adapters stamp themselves with the public ``mark_shared_*`` markers so the kernel's
+multi-instance boot promises are checked fail-closed. Redis operations are intentionally
+small and TTL-bound: idempotency claims and throttle counters use Lua scripts for atomicity;
+cache values use Redis' native string TTLs.
+
+Two capability-facing adapters live behind optional extras, so the base distribution
+depends only on ``terp-core`` (shared throttling/idempotency never installs another
+capability):
+
+* ``terp-cap-redis[realtime]`` — :class:`RedisConnectionTicketStore`
+  (:mod:`terp.capabilities.redis.realtime`), shared one-use realtime connection tickets.
+* ``terp-cap-redis[oidc]`` — :class:`RedisOIDCStateStore`
+  (:mod:`terp.capabilities.redis.oidc`), shared single-use OIDC authorization state for
+  multi-replica SSO.
+* ``terp-cap-redis[all]`` — both capability-facing adapters.
+
+Both re-export lazily from the package root: importing them without the matching extra
+raises a directive ``ModuleNotFoundError`` naming the extra to install. They are omitted
+from ``__all__`` so a wildcard import remains valid for a base-only installation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from terp.capabilities.redis.stores import (
+    RedisCacheStore,
+    RedisIdempotencyStore,
+    RedisStoreBundle,
+    RedisThrottleStore,
+)
+
+# The extras' adapters import their capability at module import time, so they resolve
+# lazily here: the base install (no extras) can `import terp.capabilities.redis` freely.
+_EXTRA_EXPORTS = {
+    "RedisConnectionTicketStore": (
+        "terp.capabilities.redis.realtime",
+        "terp.capabilities.realtime",
+        "realtime",
+    ),
+    "RedisOIDCStateStore": (
+        "terp.capabilities.redis.oidc",
+        "terp.capabilities.oidc",
+        "oidc",
+    ),
+}
+
+
+def __getattr__(name: str) -> Any:
+    extra = _EXTRA_EXPORTS.get(name)
+    if extra is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    module_name, required_module, extra_name = extra
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != required_module:
+            raise
+        raise ModuleNotFoundError(
+            f"{name} requires the optional `{extra_name}` adapter; "
+            f"install `terp-cap-redis[{extra_name}]` (or `terp-cap-redis[all]`).",
+            name=required_module,
+        ) from exc
+    return getattr(module, name)
+
+
+__all__ = [
+    "RedisCacheStore",
+    "RedisIdempotencyStore",
+    "RedisStoreBundle",
+    "RedisThrottleStore",
+]

terp_cap_redis-0.1.0/src/terp/capabilities/redis/oidc.py

@@ -0,0 +1,113 @@
+"""Redis-backed OIDC authorization state (the ``terp-cap-redis[oidc]`` extra).
+
+The OIDC capability's default :class:`~terp.capabilities.oidc.InMemoryStateStore` is
+per-process, so out of the box SSO needs one API replica or sticky routing. This store
+implements the same :class:`~terp.capabilities.oidc.OIDCStateStore` port over Redis:
+the ``/authorize`` and ``/callback`` halves of a flow may then land on different
+replicas. ``consume`` keeps the port's guarantees — strictly single-use (an atomic
+GET+DEL), expiring (a native Redis TTL bounds every pending flow), and
+provider-matched (a state issued for one provider cannot finish another's callback).
+
+Importing this submodule requires the ``oidc`` extra (``terp-cap-redis[oidc]``); the
+shared kernel stores in :mod:`terp.capabilities.redis.stores` stay decoupled from it.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import secrets
+from typing import Any
+
+from terp.capabilities.oidc import (
+    DEFAULT_STATE_TTL,
+    PendingAuthorization,
+    generate_code_verifier,
+)
+
+from terp.capabilities.redis.stores import _client_from_url, _text
+
+_CONSUME_STATE_SCRIPT = """
+local value = redis.call('GET', KEYS[1])
+if not value then
+    return nil
+end
+redis.call('DEL', KEYS[1])
+return value
+"""
+
+
+class RedisOIDCStateStore:
+    """A shared, single-use OIDC state store for multi-replica deployments."""
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        namespace: str = "terp",
+        ttl: datetime.timedelta = DEFAULT_STATE_TTL,
+    ) -> None:
+        ttl_seconds = int(ttl.total_seconds())
+        if ttl_seconds <= 0:
+            raise ValueError("RedisOIDCStateStore requires a positive ttl")
+        self._client = client
+        self._prefix = f"{namespace}:oidc-state:"
+        self._ttl = datetime.timedelta(seconds=ttl_seconds)
+
+    @classmethod
+    def from_url(
+        cls,
+        url: str,
+        *,
+        namespace: str = "terp",
+        ttl: datetime.timedelta = DEFAULT_STATE_TTL,
+    ) -> RedisOIDCStateStore:
+        """Create the store from a Redis URL using redis-py's ``Redis.from_url``."""
+        return cls(_client_from_url(url), namespace=namespace, ttl=ttl)
+
+    def issue(self, provider: str) -> tuple[str, PendingAuthorization]:
+        """Open a new flow for *provider*: returns ``(state, pending)``."""
+        state = secrets.token_urlsafe(32)
+        pending = PendingAuthorization(
+            provider=provider,
+            nonce=secrets.token_urlsafe(32),
+            code_verifier=generate_code_verifier(),
+            expires_at=datetime.datetime.now(datetime.UTC) + self._ttl,
+        )
+        value = json.dumps(
+            {
+                "provider": pending.provider,
+                "nonce": pending.nonce,
+                "code_verifier": pending.code_verifier,
+                "expires_at": pending.expires_at.isoformat(),
+            },
+            separators=(",", ":"),
+        )
+        # The Redis TTL is the expiry: an abandoned flow ages out server-side, so the
+        # store cannot grow without bound and a replica never sees a stale state.
+        self._client.set(self._key(state), value, ex=int(self._ttl.total_seconds()))
+        return state, pending
+
+    def consume(self, state: str, provider: str) -> PendingAuthorization | None:
+        """Redeem *state* exactly once, or ``None`` (unknown / expired / wrong provider)."""
+        raw = self._client.eval(_CONSUME_STATE_SCRIPT, 1, self._key(state))
+        if raw is None:
+            return None
+        payload = json.loads(_text(raw))
+        pending = PendingAuthorization(
+            provider=payload["provider"],
+            nonce=payload["nonce"],
+            code_verifier=payload["code_verifier"],
+            expires_at=datetime.datetime.fromisoformat(payload["expires_at"]),
+        )
+        if pending.provider != provider:
+            return None
+        if pending.expires_at <= datetime.datetime.now(datetime.UTC):
+            return None
+        return pending
+
+    def _key(self, state: str) -> str:
+        return f"{self._prefix}{state}"
+
+
+__all__ = ["RedisOIDCStateStore"]

terp_cap_redis-0.1.0/src/terp/capabilities/redis/realtime.py

@@ -0,0 +1,91 @@
+"""Redis-backed realtime connection tickets (the ``terp-cap-redis[realtime]`` extra).
+
+The realtime capability's one-use connection tickets are per-process by default; a
+multi-replica deployment shares them here so the replica that serves the WebSocket
+upgrade can consume a ticket another replica issued. This submodule is the only place
+terp-cap-redis touches terp-cap-realtime: importing it requires the ``realtime`` extra
+(``terp-cap-redis[realtime]``), so the shared kernel stores in
+:mod:`terp.capabilities.redis.stores` never drag a self-registering transport
+capability onto the path.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from terp.capabilities.realtime import ConnectionTicket, ConnectionTicketStore
+from terp.core import Principal, Role
+
+from terp.capabilities.redis.stores import _client_from_url, _text
+
+_CONSUME_TICKET_SCRIPT = """
+local value = redis.call('GET', KEYS[1])
+if not value then
+    return nil
+end
+redis.call('DEL', KEYS[1])
+return value
+"""
+
+
+class RedisConnectionTicketStore(ConnectionTicketStore):
+    """Shared one-use realtime tickets with atomic GET+DEL consumption."""
+
+    def __init__(self, client: Any, *, namespace: str = "terp") -> None:
+        self._client = client
+        self._prefix = f"{namespace}:realtime-ticket:"
+
+    @classmethod
+    def from_url(
+        cls, url: str, *, namespace: str = "terp"
+    ) -> RedisConnectionTicketStore:
+        return cls(_client_from_url(url), namespace=namespace)
+
+    def issue(self, ticket: ConnectionTicket, *, ttl_seconds: int) -> str:
+        if ttl_seconds <= 0:
+            raise ValueError(
+                "RedisConnectionTicketStore.issue requires a positive ttl_seconds"
+            )
+        token = uuid.uuid4().hex + uuid.uuid4().hex
+        value = json.dumps(
+            {
+                "principal_id": str(ticket.principal.id),
+                "role_name": ticket.principal.role.name,
+                "role_rank": ticket.principal.role.rank,
+                "channel": ticket.channel,
+                "transport": ticket.transport,
+                "credential": ticket.credential,
+                "audience": ticket.audience,
+            },
+            separators=(",", ":"),
+        )
+        self._client.set(self._key(token), value, ex=int(ttl_seconds))
+        return token
+
+    def consume(
+        self, token: str, *, channel: str, transport: str
+    ) -> ConnectionTicket | None:
+        raw = self._client.eval(_CONSUME_TICKET_SCRIPT, 1, self._key(token))
+        if raw is None:
+            return None
+        payload = json.loads(_text(raw))
+        if payload["channel"] != channel or payload["transport"] != transport:
+            return None
+        return ConnectionTicket(
+            principal=Principal(
+                id=uuid.UUID(payload["principal_id"]),
+                role=Role(payload["role_name"], int(payload["role_rank"])),
+            ),
+            channel=payload["channel"],
+            transport=payload["transport"],
+            credential=payload.get("credential", ""),
+            audience=payload.get("audience", ""),
+        )
+
+    def _key(self, token: str) -> str:
+        return f"{self._prefix}{token}"
+
+
+__all__ = ["RedisConnectionTicketStore"]

terp_cap_redis-0.1.0/src/terp/capabilities/redis/stores.py

@@ -0,0 +1,321 @@
+"""Redis implementations of Terp's kernel store ports (idempotency, throttle, cache).
+
+The three ports have deliberately narrow contracts, so the adapter keeps Redis usage narrow
+as well: one namespaced key per logical entry, explicit TTLs on every value, and Lua only
+where a multi-command transition must be indivisible. That gives horizontally scaled Terp
+apps honest global behaviour without teaching the kernel about Redis or weakening the
+single-process defaults.
+"""
+
+from __future__ import annotations
+
+import base64
+import importlib
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from terp.core import (
+    BeginOutcome,
+    CacheStore,
+    IdempotencyStore,
+    StoredResponse,
+    ThrottleStore,
+    mark_shared_cache_store,
+    mark_shared_idempotency_store,
+    mark_shared_throttle_store,
+)
+
+_BEGIN_SCRIPT = """
+local fingerprint = redis.call('HGET', KEYS[1], 'fingerprint')
+if not fingerprint then
+  redis.call('HSET', KEYS[1], 'fingerprint', ARGV[1], 'lease', ARGV[2], 'done', '0')
+  redis.call('EXPIRE', KEYS[1], tonumber(ARGV[3]))
+  return {'started', ARGV[2]}
+end
+if fingerprint ~= ARGV[1] then
+  return {'mismatch'}
+end
+if redis.call('HGET', KEYS[1], 'done') ~= '1' then
+  return {'in_flight'}
+end
+return {
+  'replay',
+  redis.call('HGET', KEYS[1], 'status'),
+  redis.call('HGET', KEYS[1], 'headers'),
+  redis.call('HGET', KEYS[1], 'body')
+}
+"""
+
+_COMPLETE_SCRIPT = """
+if redis.call('HGET', KEYS[1], 'lease') ~= ARGV[1] then
+  return 0
+end
+redis.call(
+  'HSET', KEYS[1],
+  'done', '1',
+  'status', ARGV[2],
+  'headers', ARGV[3],
+  'body', ARGV[4]
+)
+redis.call('EXPIRE', KEYS[1], tonumber(ARGV[5]))
+return 1
+"""
+
+_RELEASE_SCRIPT = """
+if redis.call('HGET', KEYS[1], 'lease') == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+"""
+
+_HIT_SCRIPT = """
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then
+  redis.call('EXPIRE', KEYS[1], tonumber(ARGV[1]))
+end
+local ttl = redis.call('TTL', KEYS[1])
+if ttl < 0 then
+  redis.call('EXPIRE', KEYS[1], tonumber(ARGV[1]))
+  ttl = tonumber(ARGV[1])
+end
+return {count, ttl}
+"""
+
+def _client_from_url(url: str) -> Any:
+    """Construct a redis-py client lazily so importing the adapter stays lightweight."""
+    from redis import Redis  # arch-allow-no-adhoc-background-runtime: this capability IS the Redis adapter for shared store seams — the one governed place the engine is imported
+
+    return Redis.from_url(url)
+
+
+def _text(value: object) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    return str(value)
+
+
+def _bytes(value: object) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    return str(value).encode("utf-8")
+
+
+class RedisIdempotencyStore(IdempotencyStore):
+    """A Redis-backed :class:`~terp.core.IdempotencyStore` with atomic claims.
+
+    ``begin`` is a single Lua transition: the first caller creates an in-flight hash with a
+    random lease and TTL; concurrent callers see ``in_flight``; completed hashes replay only
+    when the fingerprint matches; reuse under a different fingerprint is always a
+    ``mismatch``. ``complete`` and ``release`` are also Lua lease checks, so a slow request
+    whose claim expired cannot overwrite or delete a newer claim.
+    """
+
+    def __init__(self, client: Any, *, namespace: str = "terp") -> None:
+        self._client = client
+        self._prefix = f"{namespace}:idempotency:"
+        mark_shared_idempotency_store(self)
+
+    @classmethod
+    def from_url(cls, url: str, *, namespace: str = "terp") -> RedisIdempotencyStore:
+        """Create the store from a Redis URL using redis-py's ``Redis.from_url``."""
+        return cls(_client_from_url(url), namespace=namespace)
+
+    def begin(self, key: str, fingerprint: str, *, ttl_seconds: int) -> BeginOutcome:
+        if ttl_seconds <= 0:
+            raise ValueError(
+                f"RedisIdempotencyStore.begin requires a positive ttl_seconds, got {ttl_seconds!r}"
+            )
+        lease = uuid.uuid4().hex
+        result = self._client.eval(
+            _BEGIN_SCRIPT,
+            1,
+            self._key(key),
+            fingerprint,
+            lease,
+            int(ttl_seconds),
+        )
+        parts = list(result)
+        state = _text(parts[0])
+        if state == "started":
+            return BeginOutcome(state="started", lease=_text(parts[1]))
+        if state == "in_flight":
+            return BeginOutcome(state="in_flight")
+        if state == "mismatch":
+            return BeginOutcome(state="mismatch")
+        headers = tuple((str(name), str(value)) for name, value in json.loads(_text(parts[2])))
+        body = base64.b64decode(_bytes(parts[3]))
+        response = StoredResponse(status_code=int(_text(parts[1])), headers=headers, body=body)
+        return BeginOutcome(state="replay", response=response)
+
+    def complete(
+        self, key: str, lease: str, response: StoredResponse, *, ttl_seconds: int
+    ) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError(
+                f"RedisIdempotencyStore.complete requires a positive ttl_seconds, got {ttl_seconds!r}"
+            )
+        headers = json.dumps(list(response.headers), separators=(",", ":"))
+        self._client.eval(
+            _COMPLETE_SCRIPT,
+            1,
+            self._key(key),
+            lease,
+            str(response.status_code),
+            headers,
+            base64.b64encode(response.body).decode("ascii"),
+            int(ttl_seconds),
+        )
+
+    def release(self, key: str, lease: str) -> None:
+        self._client.eval(_RELEASE_SCRIPT, 1, self._key(key), lease)
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}{key}"
+
+
+class RedisThrottleStore(ThrottleStore):
+    """A Redis fixed-window counter and lockout store.
+
+    Hit counters are namespaced strings whose first increment sets the window TTL in the
+    same Lua script. Locks are separate TTL strings, so clearing a key removes both the
+    counter and the lock while callers retain the port's simple ``hit`` / ``lock`` /
+    ``locked`` contract.
+    """
+
+    def __init__(self, client: Any, *, namespace: str = "terp") -> None:
+        self._client = client
+        self._hits_prefix = f"{namespace}:throttle:h:"
+        self._locks_prefix = f"{namespace}:throttle:l:"
+        mark_shared_throttle_store(self)
+
+    @classmethod
+    def from_url(cls, url: str, *, namespace: str = "terp") -> RedisThrottleStore:
+        """Create the store from a Redis URL using redis-py's ``Redis.from_url``."""
+        return cls(_client_from_url(url), namespace=namespace)
+
+    def hit(self, key: str, window_seconds: int) -> tuple[int, int]:
+        result = self._client.eval(_HIT_SCRIPT, 1, self._hit_key(key), int(window_seconds))
+        count, reset = list(result)
+        return int(count), max(1, int(reset))
+
+    def lock(self, key: str, seconds: int) -> None:
+        self._client.set(self._lock_key(key), "1", ex=int(seconds))
+
+    def locked(self, key: str) -> int:
+        ttl = int(self._client.ttl(self._lock_key(key)))
+        if ttl <= 0:
+            return 0
+        return ttl
+
+    def clear(self, key: str) -> None:
+        self._client.delete(self._hit_key(key), self._lock_key(key))
+
+    def _hit_key(self, key: str) -> str:
+        return f"{self._hits_prefix}{key}"
+
+    def _lock_key(self, key: str) -> str:
+        return f"{self._locks_prefix}{key}"
+
+
+class RedisCacheStore(CacheStore):
+    """A Redis string cache with one TTL-bound key per Terp cache entry."""
+
+    def __init__(self, client: Any, *, namespace: str = "terp") -> None:
+        self._client = client
+        self._prefix = f"{namespace}:cache:"
+        mark_shared_cache_store(self)
+
+    @classmethod
+    def from_url(cls, url: str, *, namespace: str = "terp") -> RedisCacheStore:
+        """Create the store from a Redis URL using redis-py's ``Redis.from_url``."""
+        return cls(_client_from_url(url), namespace=namespace)
+
+    def get(self, key: str) -> str | None:
+        value = self._client.get(self._key(key))
+        if value is None:
+            return None
+        return _text(value)
+
+    def set(self, key: str, value: str, *, ttl_seconds: int) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError(
+                f"RedisCacheStore.set requires a positive ttl_seconds, got {ttl_seconds!r}"
+            )
+        self._client.set(self._key(key), value, ex=int(ttl_seconds))
+
+    def delete(self, key: str) -> None:
+        self._client.delete(self._key(key))
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}{key}"
+
+
+@dataclass(frozen=True)
+class RedisStoreBundle:
+    """Convenience holder for Redis-backed platform store adapters.
+
+    Use this when one Redis deployment backs all three Terp store seams. Separate classes
+    remain available for deployments that split cache and control-state Redis clusters.
+    Capability-facing adapters (realtime connection tickets, OIDC authorization state)
+    live in their own submodules behind optional extras. For compatibility, the bundle
+    includes ``realtime_tickets`` when the ``realtime`` extra is installed; it is ``None``
+    in a base-only installation.
+    """
+
+    idempotency: RedisIdempotencyStore
+    throttle: RedisThrottleStore
+    cache: RedisCacheStore
+    realtime_tickets: Any | None = None
+
+    @classmethod
+    def from_client(cls, client: Any, *, namespace: str = "terp") -> RedisStoreBundle:
+        """Build all three adapters over an already-configured redis-py compatible client."""
+        return cls(
+            idempotency=RedisIdempotencyStore(client, namespace=namespace),
+            throttle=RedisThrottleStore(client, namespace=namespace),
+            cache=RedisCacheStore(client, namespace=namespace),
+            realtime_tickets=_optional_realtime_store(client, namespace=namespace),
+        )
+
+    @classmethod
+    def from_url(cls, url: str, *, namespace: str = "terp") -> RedisStoreBundle:
+        """Build all three adapters over one Redis client constructed from *url*."""
+        return cls.from_client(_client_from_url(url), namespace=namespace)
+
+
+def _optional_realtime_store(client: Any, *, namespace: str) -> Any | None:
+    """Build the compatibility bundle member only when the realtime extra is installed."""
+    try:
+        module = importlib.import_module("terp.capabilities.redis.realtime")
+    except ModuleNotFoundError as exc:
+        if exc.name == "terp.capabilities.realtime":
+            return None
+        raise
+    return module.RedisConnectionTicketStore(client, namespace=namespace)
+
+
+def __getattr__(name: str) -> Any:
+    """Preserve the former direct import path when the realtime extra is installed."""
+    if name != "RedisConnectionTicketStore":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = importlib.import_module("terp.capabilities.redis.realtime")
+    except ModuleNotFoundError as exc:
+        if exc.name != "terp.capabilities.realtime":
+            raise
+        raise ModuleNotFoundError(
+            "RedisConnectionTicketStore requires the optional `realtime` adapter; "
+            "install `terp-cap-redis[realtime]` (or `terp-cap-redis[all]`).",
+            name="terp.capabilities.realtime",
+        ) from exc
+    return module.RedisConnectionTicketStore
+
+
+__all__ = [
+    "RedisCacheStore",
+    "RedisIdempotencyStore",
+    "RedisStoreBundle",
+    "RedisThrottleStore",
+]