domainkit 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.4.0
+Version: 0.6.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -16,15 +16,20 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
+Provides-Extra: argon2
 Provides-Extra: immudb
+Provides-Extra: jwt
 Provides-Extra: metrics
 Provides-Extra: postgres
+Provides-Extra: rabbitmq
 Provides-Extra: redis
 Provides-Extra: sqlite
 Provides-Extra: testing
 Provides-Extra: tracing
+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: fastapi (>=0.141.1,<0.142.0)
 Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "testing"
@@ -32,6 +37,7 @@ 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: 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: redis (>=8.1.0,<9.0.0) ; extra == "redis"
@@ -54,11 +60,17 @@ A Django-style framework for domain-driven FastAPI services. It provides:
   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
+- 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
+  `contrib.auth`: password hashing and rules, backends, object permissions,
+  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
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, immudb, redis, rabbitmq, metrics, tracing, testing
 ```
 
 ## Documentation
@@ -69,7 +81,10 @@ pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis,
   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/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging (and workers on RabbitMQ),
+  audit, idempotency, and evidence
+- [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/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)
@@ -84,11 +99,17 @@ cd billing
 python manage.py check
 python manage.py startdomain invoices --aggregate Invoice   # prints how to install it
 python manage.py makemigrations -m "create invoices" && python manage.py migrate
+python manage.py createsuperuser
 pytest
 python manage.py runserver            # http://127.0.0.1:8000/docs
 ```
 
-`domainkit init` creates a project that passes `check` and its tests as it is:
+`domainkit init` creates a project that passes `check` and its tests as it is.
+Users, groups, and permissions are installed, requests are authenticated,
+and every route must say who may call it: generated domains need their
+model permissions, and `/auth` and `/admin/auth` log users in and manage
+them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/main/docs/auth.md)).
+
 
 ```text
 billing/
@@ -105,7 +126,10 @@ billing/
 
 The production settings read `BILLING_API_ALLOWED_HOSTS` and
 `BILLING_API_DATABASE_URL` from the environment, and the deployment checks
-refuse to start without them, or without verified TLS to the database.
+refuse to start without them, or without verified TLS to the database. They
+also turn the API docs off, send HSTS for a year, and limit each caller to
+300 requests a minute; `BILLING_API_API_DOCS`,
+`BILLING_API_SECURE_HSTS_SECONDS`, and `BILLING_API_RATE_LIMIT` change that.
 
 ## Developing domainkit
 
@@ -118,9 +142,9 @@ poetry run pytest --cov                # random order; coverage gate in pyprojec
 poetry run mutmut run "domainkit.http*" && poetry run mutmut results
 ```
 
-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
+Without servers, the database tests use SQLite, the Redis and RabbitMQ
+tests use in-memory fakes, and the tests that need PostgreSQL, immudb, or a
+real Redis, Valkey, or RabbitMQ are skipped. Point them at throwaway servers to run
 them; each test cleans up after itself:
 
 ```bash
@@ -132,8 +156,9 @@ DOMAINKIT_TEST_REDIS_URL=redis://127.0.0.1:56379/0 \
   poetry run pytest
 ```
 
-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
+The other variables (immudb, Redis over TLS, Valkey, RabbitMQ) are listed
+at the top of `domainkit_tests/test_immudb.py`, `test_redis.py`, and
+`test_rabbitmq.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
@@ -144,7 +169,8 @@ 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 against PostgreSQL 18, immudb with TLS and a signing key,
-  Redis 8 (plain and TLS), and Valkey 9; no test may be skipped there
+  Redis 8 (plain and TLS), Valkey 9, and RabbitMQ 4 (plain and TLS); 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.4.0 → domainkit-0.6.0}/README.md

@@ -9,11 +9,17 @@ A Django-style framework for domain-driven FastAPI services. It provides:
   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
+- 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
+  `contrib.auth`: password hashing and rules, backends, object permissions,
+  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
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, immudb, redis, rabbitmq, metrics, tracing, testing
 ```
 
 ## Documentation
@@ -24,7 +30,10 @@ pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, redis,
   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/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging (and workers on RabbitMQ),
+  audit, idempotency, and evidence
+- [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/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)
@@ -39,11 +48,17 @@ cd billing
 python manage.py check
 python manage.py startdomain invoices --aggregate Invoice   # prints how to install it
 python manage.py makemigrations -m "create invoices" && python manage.py migrate
+python manage.py createsuperuser
 pytest
 python manage.py runserver            # http://127.0.0.1:8000/docs
 ```
 
-`domainkit init` creates a project that passes `check` and its tests as it is:
+`domainkit init` creates a project that passes `check` and its tests as it is.
+Users, groups, and permissions are installed, requests are authenticated,
+and every route must say who may call it: generated domains need their
+model permissions, and `/auth` and `/admin/auth` log users in and manage
+them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/main/docs/auth.md)).
+
 
 ```text
 billing/
@@ -60,7 +75,10 @@ billing/
 
 The production settings read `BILLING_API_ALLOWED_HOSTS` and
 `BILLING_API_DATABASE_URL` from the environment, and the deployment checks
-refuse to start without them, or without verified TLS to the database.
+refuse to start without them, or without verified TLS to the database. They
+also turn the API docs off, send HSTS for a year, and limit each caller to
+300 requests a minute; `BILLING_API_API_DOCS`,
+`BILLING_API_SECURE_HSTS_SECONDS`, and `BILLING_API_RATE_LIMIT` change that.
 
 ## Developing domainkit
 
@@ -73,9 +91,9 @@ poetry run pytest --cov                # random order; coverage gate in pyprojec
 poetry run mutmut run "domainkit.http*" && poetry run mutmut results
 ```
 
-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
+Without servers, the database tests use SQLite, the Redis and RabbitMQ
+tests use in-memory fakes, and the tests that need PostgreSQL, immudb, or a
+real Redis, Valkey, or RabbitMQ are skipped. Point them at throwaway servers to run
 them; each test cleans up after itself:
 
 ```bash
@@ -87,8 +105,9 @@ DOMAINKIT_TEST_REDIS_URL=redis://127.0.0.1:56379/0 \
   poetry run pytest
 ```
 
-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
+The other variables (immudb, Redis over TLS, Valkey, RabbitMQ) are listed
+at the top of `domainkit_tests/test_immudb.py`, `test_redis.py`, and
+`test_rabbitmq.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
@@ -99,7 +118,8 @@ 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 against PostgreSQL 18, immudb with TLS and a signing key,
-  Redis 8 (plain and TLS), and Valkey 9; no test may be skipped there
+  Redis 8 (plain and TLS), Valkey 9, and RabbitMQ 4 (plain and TLS); 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.4.0 → domainkit-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.4.0"
+version = "0.6.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -35,8 +35,15 @@ 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)"]
+# Argon2id password hashing for domainkit.contrib.auth (PBKDF2 needs nothing).
+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)"]
 # 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)"]
 # The domainkit.testing pytest plugin; Starlette's TestClient needs httpx2.
@@ -72,6 +79,8 @@ dev = [
     "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)",
+    # Throwaway certificates for the TLS tests.
+    "cryptography (>=50.0.2,<51.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.

{domainkit-0.4.0 → domainkit-0.6.0}/src/domainkit/apps/config.py

@@ -11,6 +11,10 @@ from pydantic import BaseModel
 from domainkit.exceptions import ImproperlyConfigured
 
 if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy import Table
+    from sqlalchemy.ext.asyncio import AsyncConnection
+
     from domainkit.db.routing import DatabaseRouter
     from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
 
@@ -101,6 +105,37 @@ class DomainConfig:
     ) -> None:
         """Add rows to a committing SQL unit of work (outbox, audit trail)."""
 
+    async def committed(self, uow: "UnitOfWork") -> None:
+        """Follow up after a SQL unit of work committed (publish its messages).
+
+        The data is already committed: a failure here is logged and reported,
+        and the unit of work carries on.
+        """
+
+    async def migrated(self, connection: "AsyncConnection", database: str) -> None:
+        """Fill alias ``database`` after ``migrate`` upgraded it (``post_migrate``).
+
+        Runs for every installed domain, in order, in one transaction on the
+        schema owner's ``connection``; check ``database`` before writing.
+        Content types and permissions are created this way.
+        """
+
+    def check_application(self, app: "FastAPI") -> list[str]:
+        """Problems with the built application, such as routes no rule guards.
+
+        ``check`` reports them, and staging and production refuse to start
+        with any; elsewhere the application starts and logs them.
+        """
+        return []
+
+    def holds_table(self, table: "Table") -> bool:
+        """Whether ``table``, tagged with this domain, is in use now.
+
+        A table that is not is neither migrated nor given a content type,
+        such as the default user table while ``AUTH.USER_MODEL`` swaps it.
+        """
+        return True
+
     def databases(self, router: "DatabaseRouter") -> frozenset[str]:
         """The targets that hold this domain's tables (see ``DATABASE_ROUTING``).
 

domainkit-0.6.0/src/domainkit/broker/__init__.py

@@ -0,0 +1,35 @@
+"""Message brokers: durable work queues for the worker (RabbitMQ, or in memory).
+
+Configure them in ``BROKERS`` and point ``MESSAGING.BROKER`` at one; the
+worker then takes its work from the broker instead of polling the outbox
+table. The outbox stays the record of every message (see ADR 0014)::
+
+    BROKERS = {"default": {"URL": "amqps://billing:pw@mq.internal/billing",
+                           "PREFIX": "billing"}}
+    MESSAGING = {"BROKER": "default"}
+"""
+
+from domainkit.broker.base import (
+    Broker,
+    BrokerError,
+    BrokerRefused,
+    BrokerUnavailable,
+    Delivery,
+    Handler,
+    Subscription,
+)
+from domainkit.broker.handler import BrokerHandler, brokers
+from domainkit.broker.memory import MemoryBroker
+
+__all__ = [
+    "Broker",
+    "BrokerError",
+    "BrokerHandler",
+    "BrokerRefused",
+    "BrokerUnavailable",
+    "Delivery",
+    "Handler",
+    "MemoryBroker",
+    "Subscription",
+    "brokers",
+]

domainkit-0.6.0/src/domainkit/broker/base.py

@@ -0,0 +1,72 @@
+"""The broker port: work queues that hand each message to one consumer.
+
+A message published to a queue goes to one of the queue's consumers, which
+acknowledges it once its work is recorded; a message whose consumer goes
+away before that goes to another. Adapters translate their failures into
+``BrokerUnavailable`` (unreachable, or no confirmation in time) and
+``BrokerRefused`` (the broker said no, as for a message no queue takes).
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+
+
+class BrokerError(Exception):
+    """Base class of broker errors."""
+
+
+class BrokerUnavailable(BrokerError):
+    """The broker could not be reached, or did not confirm in time."""
+
+
+class BrokerRefused(BrokerError):
+    """The broker refused a message (no queue took it, or it said no)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Delivery:
+    """One message handed to a consumer; ``ack`` or ``requeue`` it exactly once."""
+
+    queue: str
+    body: bytes
+    message_id: str
+    ack: Callable[[], Awaitable[None]]
+    """Done with it: the broker forgets the message."""
+    requeue: Callable[[], Awaitable[None]]
+    """Not now: the broker hands the message out again."""
+
+
+type Handler = Callable[[Delivery], Awaitable[None]]
+
+
+class Subscription(ABC):
+    """Deliveries flowing from queues to a handler."""
+
+    @abstractmethod
+    async def cancel(self) -> None:
+        """Stop new deliveries; deliveries being handled carry on."""
+
+
+class Broker(ABC):
+    """Durable work queues. Queue names are the application's; adapters prefix them."""
+
+    @abstractmethod
+    async def declare(self, queues: Iterable[str]) -> None:
+        """Create the queues if they do not exist yet."""
+
+    @abstractmethod
+    async def publish(self, queue: str, body: bytes, *, message_id: str) -> None:
+        """Hand ``body`` to ``queue``; return once the broker has it safely."""
+
+    @abstractmethod
+    async def consume(
+        self, queues: Iterable[str], prefetch: int, handler: Handler
+    ) -> Subscription:
+        """Call ``handler`` for messages of ``queues``, at most ``prefetch`` at once."""
+
+    async def check(self) -> None:  # noqa: B027 - optional; most brokers have it.
+        """Raise if the broker cannot be reached."""
+
+    async def close(self) -> None:  # noqa: B027 - optional, for connections.
+        """Release connections; the broker is not used afterwards."""

domainkit-0.6.0/src/domainkit/broker/handler.py

@@ -0,0 +1,81 @@
+"""Brokers per ``BROKERS`` alias (the broker counterpart of ``caches``).
+
+AMQP connections, and the in-memory broker's queues, belong to the event
+loop that opened them, so each running loop gets its own brokers.
+"""
+
+import asyncio
+from collections.abc import Callable
+from typing import Final
+from weakref import WeakKeyDictionary
+
+from domainkit.broker.base import Broker
+from domainkit.broker.memory import MemoryBroker
+from domainkit.conf import BrokerConfig, settings
+from domainkit.exceptions import ImproperlyConfigured
+from domainkit.utils.closing import close_each
+
+type BrokerFactory = Callable[[BrokerConfig], Broker]
+
+
+def rabbitmq_broker(config: BrokerConfig) -> Broker:
+    """Connect to RabbitMQ; needs ``domainkit[rabbitmq]``."""
+    try:
+        from domainkit.broker.rabbitmq import RabbitMQBroker
+    except ImportError as exc:  # pragma: no cover - only without the [rabbitmq] extra.
+        raise ImproperlyConfigured(
+            "RabbitMQ brokers need the rabbitmq extra: "
+            "pip install 'domainkit[rabbitmq]'."
+        ) from exc
+    return RabbitMQBroker(config)
+
+
+class BrokerHandler:
+    """Create each configured broker on first use, per event loop."""
+
+    def __init__(self, connect: BrokerFactory = rabbitmq_broker) -> None:
+        """Use ``connect`` to build RabbitMQ brokers (tests may replace it)."""
+        self._connect = connect
+        self._brokers: WeakKeyDictionary[
+            asyncio.AbstractEventLoop, dict[str, tuple[BrokerConfig, Broker]]
+        ] = WeakKeyDictionary()
+        self._replaced: WeakKeyDictionary[asyncio.AbstractEventLoop, list[Broker]] = (
+            WeakKeyDictionary()
+        )
+
+    def config(self, alias: str) -> BrokerConfig:
+        """Return the ``BROKERS`` entry of ``alias``."""
+        try:
+            return settings.BROKERS[alias]
+        except KeyError:
+            raise ImproperlyConfigured(f"BROKERS has no {alias!r} alias.") from None
+
+    def __getitem__(self, alias: str) -> Broker:
+        """The running loop's broker for ``alias``; new if its settings changed."""
+        config = self.config(alias)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                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, {})
+        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])
+        broker = MemoryBroker() if config.scheme == "memory" else self._connect(config)
+        brokers[alias] = (config, broker)
+        return broker
+
+    async def close_all(self) -> None:
+        """Close the running loop's brokers; the next use opens new ones."""
+        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)
+
+
+brokers: Final = BrokerHandler()
+"""The process-wide brokers: ``brokers["default"]``."""

domainkit-0.6.0/src/domainkit/broker/memory.py

@@ -0,0 +1,113 @@
+"""An in-process broker (``memory://``) for tests and development.
+
+Its queues live in one process and one event loop: the relay and the
+consumers of a single ``runworker`` share them, but nothing else does, so
+staging and production refuse it.
+"""
+
+import asyncio
+from collections.abc import Iterable
+
+from domainkit.broker.base import Broker, BrokerRefused, Delivery, Handler, Subscription
+
+type _Message = tuple[bytes, str]
+
+
+class _MemorySubscription(Subscription):
+    """The pumps that hand queued messages to a handler."""
+
+    def __init__(self, pumps: list[asyncio.Task[None]]) -> None:
+        """Own ``pumps``."""
+        self._pumps = pumps
+
+    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)
+
+
+class MemoryBroker(Broker):
+    """Queues of this process: one consumer gets each message, as in RabbitMQ."""
+
+    def __init__(self) -> None:
+        """Start without queues."""
+        self._queues: dict[str, asyncio.Queue[_Message]] = {}
+        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())
+
+    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))
+
+    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
+
+    async def consume(
+        self, queues: Iterable[str], prefetch: int, handler: Handler
+    ) -> Subscription:
+        """Pump each queue into ``handler``, at most ``prefetch`` at once."""
+        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)
+
+    async def _pump(
+        self, queue: str, slots: asyncio.Semaphore, handler: Handler
+    ) -> None:
+        """Hand out ``queue``'s messages while a slot is free."""
+        source = self._queues[queue]
+        while True:
+            await slots.acquire()
+            try:
+                body, message_id = await source.get()
+            except asyncio.CancelledError:
+                slots.release()
+                raise
+            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 _deliver(
+        self,
+        queue: str,
+        body: bytes,
+        message_id: str,
+        slots: asyncio.Semaphore,
+        handler: Handler,
+    ) -> None:
+        """Run ``handler``; the message holds its slot until it is answered.
+
+        As in RabbitMQ, a handler may answer after it returns, and only the
+        first answer counts.
+        """
+        answered = False
+
+        def settle() -> bool:
+            nonlocal answered
+            if answered:
+                return False
+            answered = True
+            slots.release()
+            return True
+
+        async def ack() -> None:
+            settle()
+
+        async def requeue() -> None:
+            if settle():
+                self._queues[queue].put_nowait((body, message_id))
+
+        await handler(Delivery(queue, body, message_id, ack, requeue))