domainkit 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.2.0
+Version: 0.4.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -16,8 +16,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
+Provides-Extra: immudb
 Provides-Extra: metrics
 Provides-Extra: postgres
+Provides-Extra: redis
 Provides-Extra: sqlite
 Provides-Extra: testing
 Provides-Extra: tracing
@@ -26,11 +28,13 @@ Requires-Dist: alembic (>=1.20.0,<2.0.0)
 Requires-Dist: asyncpg (>=0.31.0,<0.32.0) ; extra == "postgres"
 Requires-Dist: fastapi (>=0.141.1,<0.142.0)
 Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "testing"
+Requires-Dist: immudb-py (>=1.5.0,<1.6.0) ; extra == "immudb"
 Requires-Dist: opentelemetry-api (>=1.45.1,<2.0.0) ; extra == "tracing"
 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
@@ -46,17 +50,26 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - settings modules and installed domains
 - `manage.py` commands and migrations
 - DDD building blocks, with the layer rules between them enforced
-- optional apps for reliable messaging, audit trails, and idempotent requests
+- 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, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
   observability, testing, commands, and extension points
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, and idempotency
+- [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
 - [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/main/SECURITY.md)
@@ -105,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.2.0 → domainkit-0.4.0}/README.md

@@ -5,17 +5,26 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - settings modules and installed domains
 - `manage.py` commands and migrations
 - DDD building blocks, with the layer rules between them enforced
-- optional apps for reliable messaging, audit trails, and idempotent requests
+- 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, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
   observability, testing, commands, and extension points
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, and idempotency
+- [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
 - [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/main/SECURITY.md)
@@ -64,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.2.0 → domainkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.2.0"
+version = "0.4.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -35,6 +35,10 @@ postgres = ["asyncpg (>=0.31.0,<0.32.0)"]
 sqlite = ["aiosqlite (>=0.22.1,<0.23.0)"]
 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)"]
 
@@ -66,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.
@@ -104,6 +110,11 @@ mypy_path = "src:."
 files = ["src", "domainkit_tests"]
 exclude = ["/management/templates/", "/mutants/"]
 
+# immudb-py and grpcio ship no type information.
+[[tool.mypy.overrides]]
+module = ["immudb", "immudb.*", "grpc", "grpc.*", "ecdsa", "ecdsa.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["domainkit_tests"]
 pythonpath = ["."]
@@ -119,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.2.0 → domainkit-0.4.0}/src/domainkit/apps/config.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel
 from domainkit.exceptions import ImproperlyConfigured
 
 if TYPE_CHECKING:
+    from domainkit.db.routing import DatabaseRouter
     from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
 
 CONFIG_MODULE = "apps"
@@ -100,6 +101,15 @@ class DomainConfig:
     ) -> None:
         """Add rows to a committing SQL unit of work (outbox, audit trail)."""
 
+    def databases(self, router: "DatabaseRouter") -> frozenset[str]:
+        """The targets that hold this domain's tables (see ``DATABASE_ROUTING``).
+
+        By default, the domain's routing target. Apps whose rows must commit
+        with every domain's data (the outbox, the audit trail) return every
+        hosting target; apps without tables return none.
+        """
+        return frozenset({router.target_for(self.label)})
+
 
 def _import_domain(name: str) -> ModuleType:
     """Import a domain package, explaining a missing one."""

{domainkit-0.2.0 → domainkit-0.4.0}/src/domainkit/apps/registry.py

@@ -123,6 +123,13 @@ class DomainRegistry:
                 + ", ".join(_describe_unknown(name, known) for name in unknown)
                 + ". Declare them in a domain's settings_class or SETTINGS_CLASS."
             )
+        labels = list(self._configs)
+        if unrouted := sorted(set(current.DATABASE_ROUTING) - set(labels)):
+            raise ImproperlyConfigured(
+                "DATABASE_ROUTING names domains that are not installed: "
+                + ", ".join(_describe_unknown(label, labels) for label in unrouted)
+                + "."
+            )
 
 
 def _describe_unknown(name: str, known: list[str]) -> str:

{domainkit-0.2.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."""