domainkit 0.6.2__tar.gz → 0.8.0__tar.gz

{domainkit-0.6.2 → domainkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.6.2
+Version: 0.8.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -17,22 +17,34 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Provides-Extra: argon2
+Provides-Extra: granian
+Provides-Extra: httpclient
 Provides-Extra: immudb
 Provides-Extra: jwt
 Provides-Extra: metrics
+Provides-Extra: mfa
 Provides-Extra: postgres
 Provides-Extra: rabbitmq
 Provides-Extra: redis
 Provides-Extra: sqlite
 Provides-Extra: testing
 Provides-Extra: tracing
+Provides-Extra: tzdata
+Provides-Extra: uploads
+Provides-Extra: uvloop
+Provides-Extra: webhooks
 Requires-Dist: aio-pika (>=10.1.0,<11.0.0) ; extra == "rabbitmq"
 Requires-Dist: aiosqlite (>=0.22.1,<0.23.0) ; extra == "sqlite"
 Requires-Dist: alembic (>=1.20.0,<2.0.0)
 Requires-Dist: argon2-cffi (>=25.1.0,<26.0.0) ; extra == "argon2"
 Requires-Dist: asyncpg (>=0.31.0,<0.32.0) ; extra == "postgres"
+Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "mfa"
+Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "webhooks"
 Requires-Dist: fastapi (>=0.141.1,<0.142.0)
+Requires-Dist: granian (==2.8.4) ; extra == "granian"
+Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "httpclient"
 Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "testing"
+Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "webhooks"
 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"
@@ -40,15 +52,22 @@ Requires-Dist: pydantic (>=2.14.1,<3.0.0)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "jwt"
 Requires-Dist: pytest (>=9.1.1,<10.0.0) ; extra == "testing"
 Requires-Dist: python-dotenv (>=1.2.4,<2.0.0)
+Requires-Dist: python-multipart (>=0.0.32,<0.1.0) ; extra == "uploads"
 Requires-Dist: redis (>=8.1.0,<9.0.0) ; extra == "redis"
 Requires-Dist: sqlalchemy[asyncio] (>=2.0.54,<2.1)
+Requires-Dist: tzdata (>=2025.2) ; extra == "tzdata"
 Requires-Dist: uvicorn[standard] (>=0.54.0,<0.55.0)
+Requires-Dist: uvloop (==0.23.0) ; (sys_platform != "win32") and (extra == "uvloop")
 Project-URL: Changelog, https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/karimmattar/domainkit/blob/main/docs/reference.md
 Project-URL: Homepage, https://github.com/karimmattar/domainkit
 Project-URL: Issues, https://github.com/karimmattar/domainkit/issues
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/karimmattar/domainkit/main/docs/assets/domainkit-banner.jpg" alt="domainkit, a domain-driven FastAPI framework" width="720">
+</p>
+
 # domainkit
 
 A Django-style framework for domain-driven FastAPI services. It provides:
@@ -58,8 +77,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
+- caches in memory or in Redis and Valkey (one server, Sentinel, or
+  Cluster), with stampede protection, and rate limits shared by every
+  replica, globally or per route
+- answers in the caller's language (English and Arabic ship), times shown
+  in the business's time zone, and numbers and dates in local formats
+- file storage and uploads checked by their content, under names the
+  storage makes
 - background work through a transactional outbox, run by polling workers or
   through RabbitMQ, with queues for separate worker pools
 - users, groups, and permissions per content type, as in Django's
@@ -67,24 +91,53 @@ A Django-style framework for domain-driven FastAPI services. It provides:
   and a swappable user model; token or JWT authentication, and route rules
   as in Django REST framework
 - optional apps for reliable messaging, audit trails, idempotent requests,
-  and tamper-evident evidence
+  tamper-evident evidence, signed outgoing webhooks, feature flags, and privacy
+  requests (export, erasure, and retention)
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, immudb, redis, rabbitmq, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, mfa, immudb, redis, rabbitmq, metrics, tracing, uploads, testing, webhooks, tzdata
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
-  observability, testing, commands, and extension points
+  the API surface (OpenAPI, versions, deprecations), 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/queries.md](https://github.com/karimmattar/domainkit/blob/main/docs/queries.md): querying repositories,
+  pages, filters, soft delete, row locks, and savepoints
+- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/main/docs/resources.md): aggregates over REST:
+  resource routes, commands and queries, derived schemas, partial changes,
+  ETags and conditional writes, field policies, nesting, the generators,
+  and the generic admin
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): how async work runs:
+  background tasks, clean contexts, the shutdown budget, readiness,
+  event-handler timeouts, and workers and the outbox
 - [docs/cache.md](https://github.com/karimmattar/domainkit/blob/main/docs/cache.md): caches in memory, Redis, and Valkey,
   and shared rate limits
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): running under load: request
+  deadlines, load shedding, database timeouts and PgBouncer, and outgoing
+  HTTP calls
 - [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging (and workers on RabbitMQ),
-  audit, idempotency, and evidence
+  webhooks, audit and records' history, idempotency, evidence, and
+  feature flags
 - [docs/auth.md](https://github.com/karimmattar/domainkit/blob/main/docs/auth.md): users, groups, permissions, content
   types, passwords, backends, tokens, route rules, and the admin API
+- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/main/docs/mail.md): email, mail templates, text messages,
+  and push notifications, sent through the outbox
+- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/main/docs/i18n.md): responses in the caller's language,
+  time zones, and number and date formats
+- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/main/docs/uploads.md): file storages, receiving uploads,
+  and serving files
+- [docs/live.md](https://github.com/karimmattar/domainkit/blob/main/docs/live.md): WebSockets and Server-Sent Events,
+  bounded and re-authorized while open, and committed events streamed live
+- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/main/docs/privacy.md): exporting and erasing a person's
+  data, and retention
+- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/main/docs/testing.md): the pytest plugin: test databases,
+  sync and async clients, factories, a clock to freeze, and query counts
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): how async work runs: event loops,
+  logging off the loop, finding blocking code, free-threaded Python, and servers
 - [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)
@@ -97,7 +150,7 @@ pip install "domainkit[postgres,sqlite,testing]"
 domainkit init billingAPI billing     # the name sets the variable prefix: BILLING_API_*
 cd billing
 python manage.py check
-python manage.py startdomain invoices --aggregate Invoice   # prints how to install it
+python manage.py startdomain invoices --aggregate Invoice   # installs and mounts it
 python manage.py makemigrations -m "create invoices" && python manage.py migrate
 python manage.py createsuperuser
 pytest

{domainkit-0.6.2 → domainkit-0.8.0}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/karimmattar/domainkit/main/docs/assets/domainkit-banner.jpg" alt="domainkit, a domain-driven FastAPI framework" width="720">
+</p>
+
 # domainkit
 
 A Django-style framework for domain-driven FastAPI services. It provides:
@@ -7,8 +11,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
+- caches in memory or in Redis and Valkey (one server, Sentinel, or
+  Cluster), with stampede protection, and rate limits shared by every
+  replica, globally or per route
+- answers in the caller's language (English and Arabic ship), times shown
+  in the business's time zone, and numbers and dates in local formats
+- file storage and uploads checked by their content, under names the
+  storage makes
 - background work through a transactional outbox, run by polling workers or
   through RabbitMQ, with queues for separate worker pools
 - users, groups, and permissions per content type, as in Django's
@@ -16,24 +25,53 @@ A Django-style framework for domain-driven FastAPI services. It provides:
   and a swappable user model; token or JWT authentication, and route rules
   as in Django REST framework
 - optional apps for reliable messaging, audit trails, idempotent requests,
-  and tamper-evident evidence
+  tamper-evident evidence, signed outgoing webhooks, feature flags, and privacy
+  requests (export, erasure, and retention)
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, immudb, redis, rabbitmq, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, mfa, immudb, redis, rabbitmq, metrics, tracing, uploads, testing, webhooks, tzdata
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
-  observability, testing, commands, and extension points
+  the API surface (OpenAPI, versions, deprecations), 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/queries.md](https://github.com/karimmattar/domainkit/blob/main/docs/queries.md): querying repositories,
+  pages, filters, soft delete, row locks, and savepoints
+- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/main/docs/resources.md): aggregates over REST:
+  resource routes, commands and queries, derived schemas, partial changes,
+  ETags and conditional writes, field policies, nesting, the generators,
+  and the generic admin
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): how async work runs:
+  background tasks, clean contexts, the shutdown budget, readiness,
+  event-handler timeouts, and workers and the outbox
 - [docs/cache.md](https://github.com/karimmattar/domainkit/blob/main/docs/cache.md): caches in memory, Redis, and Valkey,
   and shared rate limits
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): running under load: request
+  deadlines, load shedding, database timeouts and PgBouncer, and outgoing
+  HTTP calls
 - [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging (and workers on RabbitMQ),
-  audit, idempotency, and evidence
+  webhooks, audit and records' history, idempotency, evidence, and
+  feature flags
 - [docs/auth.md](https://github.com/karimmattar/domainkit/blob/main/docs/auth.md): users, groups, permissions, content
   types, passwords, backends, tokens, route rules, and the admin API
+- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/main/docs/mail.md): email, mail templates, text messages,
+  and push notifications, sent through the outbox
+- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/main/docs/i18n.md): responses in the caller's language,
+  time zones, and number and date formats
+- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/main/docs/uploads.md): file storages, receiving uploads,
+  and serving files
+- [docs/live.md](https://github.com/karimmattar/domainkit/blob/main/docs/live.md): WebSockets and Server-Sent Events,
+  bounded and re-authorized while open, and committed events streamed live
+- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/main/docs/privacy.md): exporting and erasing a person's
+  data, and retention
+- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/main/docs/testing.md): the pytest plugin: test databases,
+  sync and async clients, factories, a clock to freeze, and query counts
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/main/docs/runtime.md): how async work runs: event loops,
+  logging off the loop, finding blocking code, free-threaded Python, and servers
 - [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)
@@ -46,7 +84,7 @@ pip install "domainkit[postgres,sqlite,testing]"
 domainkit init billingAPI billing     # the name sets the variable prefix: BILLING_API_*
 cd billing
 python manage.py check
-python manage.py startdomain invoices --aggregate Invoice   # prints how to install it
+python manage.py startdomain invoices --aggregate Invoice   # installs and mounts it
 python manage.py makemigrations -m "create invoices" && python manage.py migrate
 python manage.py createsuperuser
 pytest

{domainkit-0.6.2 → domainkit-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.6.2"
+version = "0.8.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -40,14 +40,31 @@ argon2 = ["argon2-cffi (>=25.1.0,<26.0.0)"]
 # JSON Web Tokens for domainkit.contrib.auth (JWTAuthentication), with the
 # RSA, ECDSA, and EdDSA algorithms.
 jwt = ["pyjwt[crypto] (>=2.10.1,<3.0.0)"]
+# Second factors for domainkit.contrib.auth: AES-GCM for the TOTP secrets
+# it stores (auth.mfa).
+mfa = ["cryptography (>=50.0.2,<51.0.0)"]
 # Ledgers for evidence (WORM): immudb's SDK, with its verified operations.
 immudb = ["immudb-py (>=1.5.0,<1.6.0)"]
 # A message broker for the worker: RabbitMQ, through aio-pika.
 rabbitmq = ["aio-pika (>=10.1.0,<11.0.0)"]
 # Shared caches and rate limits: Redis or Valkey, through redis-py.
 redis = ["redis (>=8.1.0,<9.0.0)"]
+# File uploads (domainkit.http.uploads): FastAPI reads multipart forms with it.
+uploads = ["python-multipart (>=0.0.32,<0.1.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)"]
+# Outgoing webhooks (domainkit.contrib.webhooks) send with httpx2 and encrypt
+# subscription secrets with AES-GCM.
+webhooks = ["httpx2 (>=2.13.0,<3.0.0)", "cryptography (>=50.0.2,<51.0.0)"]
+# Outgoing HTTP calls (domainkit.http.client): pooled, bounded by the
+# request's deadline, retried, with a circuit breaker per host.
+httpclient = ["httpx2 (>=2.13.0,<3.0.0)"]
+# The IANA time zones for cron schedules where the system has none (Windows).
+tzdata = ["tzdata (>=2025.2)"]
+# uvloop's event loop for management commands and runserver (EVENT_LOOP).
+uvloop = ["uvloop (==0.23.0) ; sys_platform != 'win32'"]
+# Granian, an ASGI server in Rust: "runserver --server granian", or production.
+granian = ["granian (==2.8.4)"]
 
 # Runs commands before a project exists: "domainkit init billingAPI".
 [project.scripts]
@@ -151,3 +168,6 @@ exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
 source_paths = ["src"]
 also_copy = ["domainkit_tests/", "docs/"]
 pytest_add_cli_args_test_selection = ["domainkit_tests/", "-p", "no:randomly"]
+# Fork from a clean server: children forked after the suite ran hang on
+# database tests, which mutmut would count as killed by timeout.
+process_isolation = "forkserver"

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/__init__.py

@@ -37,4 +37,5 @@ def setup() -> None:
     event_bus.error_hook = lambda exc, event: report_error(
         exc, event=type(event).__qualname__, event_id=str(event.event_id)
     )
+    event_bus.handler_timeout = settings.EVENT_HANDLER_TIMEOUT
     registry.populate(settings.INSTALLED_DOMAINS)

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/apps/config.py

@@ -4,7 +4,7 @@ from collections.abc import Sequence
 from importlib import import_module
 from pathlib import Path
 from types import ModuleType
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
 from pydantic import BaseModel
 
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
     from sqlalchemy import Table
     from sqlalchemy.ext.asyncio import AsyncConnection
 
+    from domainkit.contrib.privacy import Retention
     from domainkit.db.routing import DatabaseRouter
     from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
 
@@ -34,6 +35,8 @@ class DomainConfig:
     verbose_name: str = ""
     settings_class: type[BaseModel] | None = None
     """Schema for this domain's settings, read from ``settings_name``."""
+    RETENTION: ClassVar[Sequence["Retention"]] = ()
+    """How long rows of its tables are kept (``domainkit.contrib.privacy``)."""
 
     def __init__(self, name: str, module: ModuleType) -> None:
         """Bind the config to the domain package ``name``."""
@@ -120,6 +123,16 @@ class DomainConfig:
         Content types and permissions are created this way.
         """
 
+    async def seed(self) -> None:
+        """Add the rows a fresh database needs to be useful (``manage.py seed``).
+
+        Sample data for development, or defaults a deployment starts with.
+        ``seed`` calls the hooks in ``INSTALLED_DOMAINS`` order, so a domain
+        may use what those before it seeded. Write rows through the domain's
+        own units of work, and make running twice harmless: rows that exist
+        stay as they are.
+        """
+
     def check_application(self, app: "FastAPI") -> list[str]:
         """Problems with the built application, such as routes no rule guards.
 
@@ -128,6 +141,15 @@ class DomainConfig:
         """
         return []
 
+    def deployment_warnings(self) -> list[str]:
+        """Weak but valid choices of this domain's settings where deployed.
+
+        ``check`` lists them after ``Settings.deployment_warnings``; they
+        do not stop the application. Return none outside staging and
+        production.
+        """
+        return []
+
     def holds_table(self, table: "Table") -> bool:
         """Whether ``table``, tagged with this domain, is in use now.
 

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/apps/registry.py

@@ -2,7 +2,7 @@
 
 import difflib
 from collections.abc import AsyncIterator, Iterable, Iterator
-from contextlib import AsyncExitStack, asynccontextmanager
+from contextlib import asynccontextmanager
 from typing import Final, cast
 
 from pydantic import BaseModel, ValidationError
@@ -10,6 +10,7 @@ from pydantic import BaseModel, ValidationError
 from domainkit.apps.config import DomainConfig
 from domainkit.conf import describe_errors, settings, unwrap_settings
 from domainkit.exceptions import ImproperlyConfigured
+from domainkit.utils.closing import close_in_turn
 from domainkit.utils.readiness import failing_checks
 
 
@@ -94,13 +95,26 @@ class DomainRegistry:
         return value
 
     @asynccontextmanager
-    async def lifespan(self) -> AsyncIterator[None]:
-        """Start domains in order and stop started ones in reverse, even on failure."""
-        async with AsyncExitStack() as stack:
+    async def lifespan(
+        self, *, stop_within: float | None = None
+    ) -> AsyncIterator[None]:
+        """Start domains in order and stop started ones in reverse, even on failure.
+
+        Stopping takes at most ``stop_within`` seconds (None: no limit). A
+        domain may use what is left of them, less a little kept for each
+        domain still to stop (``close_in_turn``): one whose ``shutdown``
+        hangs is cut off, and the domains started before it still stop.
+        Every domain is stopped; the first failure is raised, and later ones
+        are logged.
+        """
+        started: list[DomainConfig] = []
+        try:
             for config in self:
                 await config.startup()
-                stack.push_async_callback(config.shutdown)
+                started.append(config)
             yield
+        finally:
+            await close_in_turn(started[::-1], _stop, within=stop_within)
 
     async def check(self, seconds: float) -> list[str]:
         """Run every domain's readiness check; return the labels that failed."""
@@ -132,6 +146,11 @@ class DomainRegistry:
             )
 
 
+async def _stop(config: DomainConfig) -> None:
+    """Run the domain's own ``shutdown``."""
+    await config.shutdown()
+
+
 def _describe_unknown(name: str, known: list[str]) -> str:
     """Name an unknown setting and suggest the closest known one."""
     matches = difflib.get_close_matches(name, known, n=1)

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/architecture.py

@@ -4,8 +4,8 @@ Each domain package has four layers; dependencies point inward only::
 
     api  ->  infrastructure  ->  application  ->  domain
 
-- ``domain``: the standard library, ``domainkit.ddd``, and its own domain layer.
-  No frameworks, no I/O, no settings.
+- ``domain``: the standard library, ``domainkit.ddd``, ``domainkit.clock``, and
+  its own domain layer. No frameworks, no I/O, no settings.
 - ``application``: no ``infrastructure`` or ``api`` code, and no web or
   database libraries; it reaches storage through repository ports.
 - ``infrastructure``: no ``api`` code and no web libraries.
@@ -26,7 +26,7 @@ from typing import Final
 
 LAYERS: Final = ("domain", "application", "infrastructure", "api")
 
-DOMAIN_ALLOWED_PREFIXES: Final = ("domainkit.ddd",)
+DOMAIN_ALLOWED_PREFIXES: Final = ("domainkit.ddd", "domainkit.clock")
 """Non-stdlib modules a domain layer may import (besides its own layer)."""
 
 FORBIDDEN_LIBRARIES: Final = {
@@ -127,7 +127,7 @@ def _layer_rule(package: str, layer: str | None, imported: str) -> str | None:
         if not _is_stdlib(imported) and not _within(imported, allowed):
             return (
                 "the domain layer may import only the standard library, "
-                "domainkit.ddd, and its own domain layer"
+                "domainkit.ddd, domainkit.clock, and its own domain layer"
             )
         return None
     if layer is None:

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/broker/base.py

@@ -51,6 +51,13 @@ class Subscription(ABC):
 class Broker(ABC):
     """Durable work queues. Queue names are the application's; adapters prefix them."""
 
+    publish_timeout: float = 10.0
+    """Most seconds ``publish`` may take, connecting first included.
+
+    Relays lock the messages they publish for a little longer than this, so
+    a publication cut short (a crash, a stop) is retried soon after.
+    """
+
     @abstractmethod
     async def declare(self, queues: Iterable[str]) -> None:
         """Create the queues if they do not exist yet."""

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/broker/handler.py

@@ -5,6 +5,7 @@ loop that opened them, so each running loop gets its own brokers.
 """
 
 import asyncio
+import threading
 from collections.abc import Callable
 from typing import Final
 from weakref import WeakKeyDictionary
@@ -42,6 +43,8 @@ class BrokerHandler:
         self._replaced: WeakKeyDictionary[asyncio.AbstractEventLoop, list[Broker]] = (
             WeakKeyDictionary()
         )
+        self._lock = threading.Lock()
+        """Held to change or walk the registries: loops on other threads do too."""
 
     def config(self, alias: str) -> BrokerConfig:
         """Return the ``BROKERS`` entry of ``alias``."""
@@ -60,21 +63,42 @@ class BrokerHandler:
                 f"brokers[{alias!r}] needs a running event loop: connections "
                 "belong to one, so look brokers up inside async code."
             ) from None
-        brokers = self._brokers.setdefault(loop, {})
+        with self._lock:
+            if loop not in self._brokers:
+                self._forget_closed_loops()
+            brokers = self._brokers.setdefault(loop, {})
         current = brokers.get(alias)
         if current is not None and current[0] == config:
             return current[1]
         if current is not None:  # override_settings changed it; close it later.
-            self._replaced.setdefault(loop, []).append(current[1])
+            with self._lock:
+                replaced = self._replaced.setdefault(loop, [])
+            replaced.append(current[1])
         broker = MemoryBroker() if config.scheme == "memory" else self._connect(config)
         brokers[alias] = (config, broker)
         return broker
 
+    def _forget_closed_loops(self) -> None:
+        """Drop the brokers of loops closed without ``close_all``.
+
+        Their connections died with the loop, and a broker that references
+        its loop would keep it alive for good. Called with ``_lock`` held.
+        """
+        for loop in [loop for loop in self._brokers if loop.is_closed()]:
+            self._brokers.pop(loop, None)
+            self._replaced.pop(loop, None)
+
     async def close_all(self) -> None:
-        """Close the running loop's brokers; the next use opens new ones."""
+        """Close the running loop's brokers; the next use opens new ones.
+
+        Each broker's own ``close``: ``Broker.close`` is the base class's,
+        which closes nothing.
+        """
         loop = asyncio.get_running_loop()
-        current = [broker for _, broker in self._brokers.pop(loop, {}).values()]
-        await close_each([*current, *self._replaced.pop(loop, [])], Broker.close)
+        with self._lock:
+            current = [broker for _, broker in self._brokers.pop(loop, {}).values()]
+            replaced = self._replaced.pop(loop, [])
+        await close_each([*current, *replaced], lambda broker: broker.close())
 
 
 brokers: Final = BrokerHandler()

{domainkit-0.6.2 → domainkit-0.8.0}/src/domainkit/broker/memory.py

@@ -6,7 +6,8 @@ staging and production refuse it.
 """
 
 import asyncio
-from collections.abc import Iterable
+from collections import deque
+from collections.abc import Iterable, Sequence
 
 from domainkit.broker.base import Broker, BrokerRefused, Delivery, Handler, Subscription
 
@@ -14,17 +15,16 @@ type _Message = tuple[bytes, str]
 
 
 class _MemorySubscription(Subscription):
-    """The pumps that hand queued messages to a handler."""
+    """The pump that hands queued messages to a handler."""
 
-    def __init__(self, pumps: list[asyncio.Task[None]]) -> None:
-        """Own ``pumps``."""
-        self._pumps = pumps
+    def __init__(self, pump: asyncio.Task[None]) -> None:
+        """Own ``pump``."""
+        self._pump = pump
 
     async def cancel(self) -> None:
-        """Stop the pumps; handlers already running finish."""
-        for pump in self._pumps:
-            pump.cancel()
-        await asyncio.gather(*self._pumps, return_exceptions=True)
+        """Stop the pump; handlers already running finish."""
+        self._pump.cancel()
+        await asyncio.gather(self._pump, return_exceptions=True)
 
 
 class MemoryBroker(Broker):
@@ -32,54 +32,75 @@ class MemoryBroker(Broker):
 
     def __init__(self) -> None:
         """Start without queues."""
-        self._queues: dict[str, asyncio.Queue[_Message]] = {}
+        self._queues: dict[str, deque[_Message]] = {}
+        self._arrived = asyncio.Event()
         self._handling: set[asyncio.Task[None]] = set()
 
     async def declare(self, queues: Iterable[str]) -> None:
         """Create the missing queues."""
         for queue in queues:
-            self._queues.setdefault(queue, asyncio.Queue())
+            self._queues.setdefault(queue, deque())
 
     async def publish(self, queue: str, body: bytes, *, message_id: str) -> None:
         """Append to ``queue``; refuse queues nobody declared, as RabbitMQ does."""
         if queue not in self._queues:
             raise BrokerRefused(f"No queue {queue!r} takes the message.")
-        self._queues[queue].put_nowait((body, message_id))
+        self._put(queue, (body, message_id))
 
     def pending(self, queue: str) -> int:
         """Messages waiting in ``queue`` (tests); 0 for a queue never declared."""
-        return self._queues[queue].qsize() if queue in self._queues else 0
+        return len(self._queues.get(queue, ()))
 
     async def consume(
         self, queues: Iterable[str], prefetch: int, handler: Handler
     ) -> Subscription:
-        """Pump each queue into ``handler``, at most ``prefetch`` at once."""
+        """Pump the queues into ``handler``, at most ``prefetch`` at once in all."""
         queues = list(queues)
         await self.declare(queues)
-        slots = asyncio.Semaphore(prefetch)
-        pumps = [
-            asyncio.create_task(self._pump(queue, slots, handler)) for queue in queues
-        ]
-        return _MemorySubscription(pumps)
+        pump = asyncio.create_task(
+            self._pump(queues, asyncio.Semaphore(prefetch), handler)
+        )
+        return _MemorySubscription(pump)
+
+    def _put(self, queue: str, message: _Message) -> None:
+        """Queue ``message`` and wake the pumps."""
+        self._queues[queue].append(message)
+        self._arrived.set()
 
     async def _pump(
-        self, queue: str, slots: asyncio.Semaphore, handler: Handler
+        self, queues: Sequence[str], slots: asyncio.Semaphore, handler: Handler
     ) -> None:
-        """Hand out ``queue``'s messages while a slot is free."""
-        source = self._queues[queue]
+        """Hand out the queues' messages, in turn, while a slot is free.
+
+        One pump serves every queue of a subscription, so while it waits for
+        a message it holds one slot, not one per queue: an empty queue never
+        keeps a slot from a busy one.
+        """
+        turn = 0
         while True:
             await slots.acquire()
             try:
-                body, message_id = await source.get()
+                queue, (body, message_id) = await self._next(queues, turn)
             except asyncio.CancelledError:
                 slots.release()
                 raise
+            turn = queues.index(queue) + 1
             task = asyncio.create_task(
                 self._deliver(queue, body, message_id, slots, handler)
             )
             self._handling.add(task)
             task.add_done_callback(self._handling.discard)
 
+    async def _next(self, queues: Sequence[str], turn: int) -> tuple[str, _Message]:
+        """Take the next message, looking at ``queues`` from ``turn`` on."""
+        while True:
+            for offset in range(len(queues)):
+                queue = queues[(turn + offset) % len(queues)]
+                if self._queues[queue]:
+                    return queue, self._queues[queue].popleft()
+            self._arrived.clear()
+            await self._arrived.wait()
+
     async def _deliver(
         self,
         queue: str,
@@ -108,6 +129,6 @@ class MemoryBroker(Broker):
 
         async def requeue() -> None:
             if settle():
-                self._queues[queue].put_nowait((body, message_id))
+                self._put(queue, (body, message_id))
 
         await handler(Delivery(queue, body, message_id, ack, requeue))