domainkit 0.3.0__tar.gz → 0.4.0__tar.gz

{domainkit-0.3.0 → domainkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -19,6 +19,7 @@ Classifier: Typing :: Typed
 Provides-Extra: immudb
 Provides-Extra: metrics
 Provides-Extra: postgres
+Provides-Extra: redis
 Provides-Extra: sqlite
 Provides-Extra: testing
 Provides-Extra: tracing
@@ -33,6 +34,7 @@ Requires-Dist: prometheus-client (>=0.26.0,<0.27.0) ; extra == "metrics"
 Requires-Dist: pydantic (>=2.14.1,<3.0.0)
 Requires-Dist: pytest (>=9.1.1,<10.0.0) ; extra == "testing"
 Requires-Dist: python-dotenv (>=1.2.4,<2.0.0)
+Requires-Dist: redis (>=8.1.0,<9.0.0) ; extra == "redis"
 Requires-Dist: sqlalchemy[asyncio] (>=2.0.54,<2.1)
 Requires-Dist: uvicorn[standard] (>=0.54.0,<0.55.0)
 Project-URL: Changelog, https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md
@@ -50,11 +52,13 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - DDD building blocks, with the layer rules between them enforced
 - several databases: domains routed to their own, sharding by key,
   PostgreSQL range partitioning, and immudb ledgers for evidence
+- caches in memory or in Redis and Valkey, with stampede protection, and
+  rate limits shared by every replica
 - optional apps for reliable messaging, audit trails, idempotent requests,
   and tamper-evident evidence
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
 ```
 
 ## Documentation
@@ -63,6 +67,8 @@ pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metric
   observability, testing, commands, and extension points
 - [docs/databases.md](https://github.com/karimmattar/domainkit/blob/main/docs/databases.md): several databases, routing,
   sharding, partitioning, and ledgers
+- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/main/docs/cache.md): caches in memory, Redis, and Valkey,
+  and shared rate limits
 - [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, idempotency, and evidence
 - [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/main/docs/versioning.md): compatibility, deprecations, and releases
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
@@ -112,24 +118,34 @@ poetry run pytest --cov                # random order; coverage gate in pyprojec
 poetry run mutmut run "domainkit.http*" && poetry run mutmut results
 ```
 
-The database tests use SQLite unless `DOMAINKIT_TEST_POSTGRES_URL` names a
-PostgreSQL server; each test then creates a database there and drops it.
-Use a throwaway server:
+Without servers, the database tests use SQLite, the Redis tests use an
+in-memory fake (fakeredis), and the tests that need PostgreSQL, immudb, or
+a real Redis or Valkey are skipped. Point them at throwaway servers to run
+them; each test cleans up after itself:
 
 ```bash
 docker run -d --rm --name domainkit-postgres -e POSTGRES_PASSWORD=postgres \
   -p 127.0.0.1:55432:5432 postgres:18-alpine
+docker run -d --rm --name domainkit-redis -p 127.0.0.1:56379:6379 redis:8-alpine
 DOMAINKIT_TEST_POSTGRES_URL=postgresql+asyncpg://postgres:postgres@127.0.0.1:55432/postgres \
+DOMAINKIT_TEST_REDIS_URL=redis://127.0.0.1:56379/0 \
   poetry run pytest
 ```
 
-CI (`.github/workflows/ci.yml`) runs the same checks on every push and pull
-request:
+The other variables (immudb, Redis over TLS, Valkey) are listed at the top
+of `domainkit_tests/test_immudb.py` and `test_redis.py`. Each run must cover
+98%; CI also combines the runs with and without servers, which must cover
+100%. To check that locally, run `pytest --cov` once without and once with
+the servers, each with its own `COVERAGE_FILE`, then `coverage combine` and
+`coverage report --fail-under=100`.
+
+CI (`.github/workflows/ci.yml`) runs on every push and pull request:
 
 - lint and strict typing
 - the tests on Python 3.13 and 3.14
-- the tests again with PostgreSQL 18, including row locking, the audit
-  triggers, and server-side timeouts
+- the tests again against PostgreSQL 18, immudb with TLS and a signing key,
+  Redis 8 (plain and TLS), and Valkey 9; no test may be skipped there
+- coverage of both runs combined, which must be 100%
 - a wheel build, installed and imported in a clean environment
 - pip-audit, and a gitleaks scan of the whole history
 

{domainkit-0.3.0 → domainkit-0.4.0}/README.md

@@ -7,11 +7,13 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - DDD building blocks, with the layer rules between them enforced
 - several databases: domains routed to their own, sharding by key,
   PostgreSQL range partitioning, and immudb ledgers for evidence
+- caches in memory or in Redis and Valkey, with stampede protection, and
+  rate limits shared by every replica
 - optional apps for reliable messaging, audit trails, idempotent requests,
   and tamper-evident evidence
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
 ```
 
 ## Documentation
@@ -20,6 +22,8 @@ pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metric
   observability, testing, commands, and extension points
 - [docs/databases.md](https://github.com/karimmattar/domainkit/blob/main/docs/databases.md): several databases, routing,
   sharding, partitioning, and ledgers
+- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/main/docs/cache.md): caches in memory, Redis, and Valkey,
+  and shared rate limits
 - [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, idempotency, and evidence
 - [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/main/docs/versioning.md): compatibility, deprecations, and releases
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
@@ -69,24 +73,34 @@ poetry run pytest --cov                # random order; coverage gate in pyprojec
 poetry run mutmut run "domainkit.http*" && poetry run mutmut results
 ```
 
-The database tests use SQLite unless `DOMAINKIT_TEST_POSTGRES_URL` names a
-PostgreSQL server; each test then creates a database there and drops it.
-Use a throwaway server:
+Without servers, the database tests use SQLite, the Redis tests use an
+in-memory fake (fakeredis), and the tests that need PostgreSQL, immudb, or
+a real Redis or Valkey are skipped. Point them at throwaway servers to run
+them; each test cleans up after itself:
 
 ```bash
 docker run -d --rm --name domainkit-postgres -e POSTGRES_PASSWORD=postgres \
   -p 127.0.0.1:55432:5432 postgres:18-alpine
+docker run -d --rm --name domainkit-redis -p 127.0.0.1:56379:6379 redis:8-alpine
 DOMAINKIT_TEST_POSTGRES_URL=postgresql+asyncpg://postgres:postgres@127.0.0.1:55432/postgres \
+DOMAINKIT_TEST_REDIS_URL=redis://127.0.0.1:56379/0 \
   poetry run pytest
 ```
 
-CI (`.github/workflows/ci.yml`) runs the same checks on every push and pull
-request:
+The other variables (immudb, Redis over TLS, Valkey) are listed at the top
+of `domainkit_tests/test_immudb.py` and `test_redis.py`. Each run must cover
+98%; CI also combines the runs with and without servers, which must cover
+100%. To check that locally, run `pytest --cov` once without and once with
+the servers, each with its own `COVERAGE_FILE`, then `coverage combine` and
+`coverage report --fail-under=100`.
+
+CI (`.github/workflows/ci.yml`) runs on every push and pull request:
 
 - lint and strict typing
 - the tests on Python 3.13 and 3.14
-- the tests again with PostgreSQL 18, including row locking, the audit
-  triggers, and server-side timeouts
+- the tests again against PostgreSQL 18, immudb with TLS and a signing key,
+  Redis 8 (plain and TLS), and Valkey 9; no test may be skipped there
+- coverage of both runs combined, which must be 100%
 - a wheel build, installed and imported in a clean environment
 - pip-audit, and a gitleaks scan of the whole history
 

{domainkit-0.3.0 → domainkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.3.0"
+version = "0.4.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -37,6 +37,8 @@ metrics = ["prometheus-client (>=0.26.0,<0.27.0)"]
 tracing = ["opentelemetry-api (>=1.45.1,<2.0.0)"]
 # Ledgers for evidence (WORM): immudb's SDK, with its verified operations.
 immudb = ["immudb-py (>=1.5.0,<1.6.0)"]
+# Shared caches and rate limits: Redis or Valkey, through redis-py.
+redis = ["redis (>=8.1.0,<9.0.0)"]
 # The domainkit.testing pytest plugin; Starlette's TestClient needs httpx2.
 testing = ["pytest (>=9.1.1,<10.0.0)", "httpx2 (>=2.13.0,<3.0.0)"]
 
@@ -68,6 +70,8 @@ dev = [
     "pip-audit (>=2.9.0,<3.0.0)",
     # Starlette's TestClient (it deprecates plain httpx).
     "httpx2 (>=2.13.0,<3.0.0)",
+    # An in-memory Redis, with Lua, so the Redis tests also run without a server.
+    "fakeredis[lua] (>=2.38.0,<3.0.0)",
     # In-memory span exporter for the tracing tests.
     "opentelemetry-sdk (>=1.45.1,<2.0.0)",
     # Random test order, property-based tests, mutation testing.
@@ -126,6 +130,8 @@ source = ["src"]
 [tool.coverage.report]
 show_missing = true
 skip_empty = true
+# Every run, with or without servers; CI's coverage job also requires 100%
+# of all runs combined.
 fail_under = 98
 precision = 2
 exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]

{domainkit-0.3.0 → domainkit-0.4.0}/src/domainkit/architecture.py

@@ -35,6 +35,7 @@ FORBIDDEN_LIBRARIES: Final = {
         "starlette",
         "sqlalchemy",
         "alembic",
+        "redis",
         "domainkit.db",
         "domainkit.http",
     ),

domainkit-0.4.0/src/domainkit/cache/__init__.py

@@ -0,0 +1,39 @@
+"""Caches: in process memory, or in Redis or Valkey shared by every replica.
+
+Configure them in ``CACHES`` (``default`` is a memory cache unless set),
+then use them anywhere in the application layer::
+
+    from domainkit.cache import cached, caches
+
+    summary = await caches["default"].get_or_set(
+        f"invoice:{invoice_id}", lambda: load_summary(invoice_id), InvoiceSummary
+    )
+
+    @cached(ttl=60)
+    async def invoice_summary(invoice_id: UUID) -> InvoiceSummary: ...
+
+Values are JSON; a failing cache is skipped, not fatal. See ADR 0012 and
+``docs/cache.md``.
+"""
+
+from domainkit.cache.base import CacheError, CacheUnavailable, Store
+from domainkit.cache.core import DEFAULT_TTL, TTL, Cache
+from domainkit.cache.decorators import CachedFunction, cached, invalidate_on
+from domainkit.cache.handler import CacheHandler, caches
+from domainkit.cache.memory import DummyStore, MemoryStore
+
+__all__ = [
+    "DEFAULT_TTL",
+    "TTL",
+    "Cache",
+    "CacheError",
+    "CacheHandler",
+    "CacheUnavailable",
+    "CachedFunction",
+    "DummyStore",
+    "MemoryStore",
+    "Store",
+    "cached",
+    "caches",
+    "invalidate_on",
+]

domainkit-0.4.0/src/domainkit/cache/base.py

@@ -0,0 +1,63 @@
+"""The store port: what a cache backend implements.
+
+A store keeps bytes under full keys, with expiry in milliseconds. ``Cache``
+(``domainkit.cache.core``) builds keys, encodes values, and handles failures
+on top of it, so a new backend implements only these operations.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+
+
+class CacheError(Exception):
+    """Base class of cache errors."""
+
+
+class CacheUnavailable(CacheError):
+    """The cache could not be reached in time, or is skipped after a failure."""
+
+
+class Store(ABC):
+    """Bytes under full keys; ``ttl`` is in milliseconds, None keeps the entry.
+
+    Raise ``CacheUnavailable`` when the backend cannot be reached, and
+    ``CacheError`` when it refuses an operation.
+    """
+
+    @abstractmethod
+    async def get_many(self, keys: Sequence[str]) -> list[bytes | None]:
+        """Return the value of each key, or None where it is missing or expired."""
+
+    @abstractmethod
+    async def set_many(self, items: Mapping[str, bytes], ttl: int | None) -> None:
+        """Store every item, replacing existing values."""
+
+    @abstractmethod
+    async def add(self, key: str, value: bytes, ttl: int | None) -> bool:
+        """Store ``value`` only if ``key`` is missing; report whether it was."""
+
+    @abstractmethod
+    async def delete_many(self, keys: Sequence[str]) -> int:
+        """Delete the keys; return how many existed."""
+
+    @abstractmethod
+    async def incr(self, key: str, delta: int, ttl: int | None) -> int:
+        """Add ``delta`` to an integer value and return it.
+
+        A missing key starts at 0 and gets ``ttl``; an existing key keeps its
+        expiry. Raise ``CacheError`` if the value is not an integer.
+        """
+
+    @abstractmethod
+    async def touch(self, key: str, ttl: int | None) -> bool:
+        """Give ``key`` a new expiry (None: none); report whether it exists."""
+
+    @abstractmethod
+    async def clear(self, prefix: str) -> int:
+        """Delete every key starting with ``prefix``; return how many."""
+
+    async def check(self) -> None:  # noqa: B027 - optional; most stores have it.
+        """Raise if the backend cannot be reached (readiness checks)."""
+
+    async def close(self) -> None:  # noqa: B027 - optional, for connections.
+        """Release connections; the store is not used afterwards."""