domainkit 0.6.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.6.2
+Version: 0.7.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,19 +20,26 @@ Provides-Extra: argon2
 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: 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: 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,8 +47,10 @@ 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)
 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
@@ -49,6 +58,10 @@ 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 +71,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 +85,43 @@ 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/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 (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/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/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 +134,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.7.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,43 @@ 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/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 (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/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/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 +74,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.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.6.2"
+version = "0.7.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -40,14 +40,24 @@ 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)"]
+# The IANA time zones for cron schedules where the system has none (Windows).
+tzdata = ["tzdata (>=2025.2)"]
 
 # Runs commands before a project exists: "domainkit init billingAPI".
 [project.scripts]
@@ -151,3 +161,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.7.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.7.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.7.0}/src/domainkit/cache/__init__.py

@@ -12,6 +12,10 @@ then use them anywhere in the application layer::
     @cached(ttl=60)
     async def invoice_summary(invoice_id: UUID) -> InvoiceSummary: ...
 
+    @router.get("/invoices", dependencies=[Public])
+    @cache_page(ttl=60)
+    async def list_invoices() -> list[InvoiceSummary]: ...
+
 Values are JSON; a failing cache is skipped, not fatal. See ADR 0012 and
 ``docs/cache.md``.
 """
@@ -21,6 +25,7 @@ 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
+from domainkit.cache.pages import cache_page
 
 __all__ = [
     "DEFAULT_TTL",
@@ -33,6 +38,7 @@ __all__ = [
     "DummyStore",
     "MemoryStore",
     "Store",
+    "cache_page",
     "cached",
     "caches",
     "invalidate_on",

{domainkit-0.6.2 → domainkit-0.7.0}/src/domainkit/cache/core.py

@@ -65,7 +65,7 @@ _MISS: Final = object()
 
 
 @cache
-def _adapter(type_: TypeForm) -> TypeAdapter[Any]:
+def adapter(type_: TypeForm) -> TypeAdapter[Any]:
     """Build (once) the validator that turns JSON into ``type_``."""
     return TypeAdapter(type_)
 
@@ -85,7 +85,7 @@ def decode(payload: bytes, type_: TypeForm) -> Any:  # noqa: ANN401 - as type_.
     """Parse JSON, validated as ``type_`` unless it is None."""
     if type_ is None:
         return from_json(payload)
-    return _adapter(type_).validate_json(payload)
+    return adapter(type_).validate_json(payload)
 
 
 def split(raw: bytes) -> tuple[bytes, float | None, float]:

{domainkit-0.6.2 → domainkit-0.7.0}/src/domainkit/cache/memory.py

@@ -2,12 +2,12 @@
 
 import re
 import threading
-import time
 from collections import OrderedDict
 from collections.abc import Callable, Mapping, Sequence
 from typing import Final
 
 from domainkit.cache.base import CacheError, Store
+from domainkit.clock import monotonic
 
 _INTEGER: Final = re.compile(rb"-?[0-9]+")
 
@@ -22,7 +22,7 @@ class MemoryStore(Store):
     """
 
     def __init__(
-        self, max_entries: int, clock: Callable[[], float] = time.monotonic
+        self, max_entries: int, clock: Callable[[], float] = monotonic
     ) -> None:
         """Keep at most ``max_entries``; ``clock`` reads seconds."""
         self.max_entries = max_entries

domainkit-0.7.0/src/domainkit/cache/pages.py

@@ -0,0 +1,228 @@
+"""``@cache_page``: cache what a GET endpoint returns (Django's per-view cache).
+
+The endpoint's return value is cached, typed by its return annotation as
+with ``@cached``, and FastAPI serializes it on every request, hit or miss,
+so ``response_model`` filtering always applies::
+
+    @router.get("/products", dependencies=[Public])
+    @cache_page(ttl=60)
+    async def list_products(category: str | None = None) -> list[ProductOut]: ...
+
+Entries are keyed by the endpoint, the URL (scheme, host, and path, as
+Django's absolute URIs), the query, the request's language, and the
+headers listed in ``vary``. Route dependencies (rules,
+throttles) run first, on every request, so a cached answer never reaches a
+caller who may not see it.
+
+A response depends on who asks unless proven otherwise, so requests that
+carry credentials are never served from, or stored in, the cache, unless
+the page varies on the user: ``vary_on_user=True`` keys entries by actor
+and marks them ``private``. Credentials are the actor, the ``Credentials``
+an authentication middleware accepted (``request.auth``: a token, a
+cookie, a client certificate), or an ``Authorization`` header. Requests
+with credentials but no actor or user id are never cached.
+
+Cached pages override the framework's ``Cache-Control: no-store`` on
+purpose: clients may keep them, and must revalidate them (``no-cache``)
+unless ``max_age`` says otherwise. Each answer has an ``ETag``, and a
+request whose ``If-None-Match`` names it gets 304 without a body.
+"""
+
+import hashlib
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from functools import update_wrapper
+from typing import Any, Final, get_type_hints
+
+from fastapi import Request, Response, status
+from pydantic_core import to_json
+
+from domainkit.cache.core import DEFAULT_TTL, TTL, adapter
+from domainkit.cache.handler import caches
+from domainkit.conf import DEFAULT_CACHE_ALIAS
+from domainkit.context import current_request
+from domainkit.i18n.translation import get_language
+from domainkit.utils.headers import none_match, patch_vary
+
+REQUEST: Final = "_cache_page_request"
+RESPONSE: Final = "_cache_page_response"
+"""Parameters added to the endpoint: FastAPI passes the request and response."""
+CACHEABLE_METHODS: Final = frozenset({"GET", "HEAD"})
+
+type Endpoint = Callable[..., Awaitable[Any]]
+
+
+def cache_page(
+    ttl: TTL = DEFAULT_TTL,
+    *,
+    cache: str = DEFAULT_CACHE_ALIAS,
+    vary: Sequence[str] = (),
+    vary_on_user: bool = False,
+    max_age: int = 0,
+    name: str | None = None,
+) -> Callable[[Endpoint], Endpoint]:
+    """Cache what an async GET endpoint returns, for ``ttl``, in ``cache``.
+
+    ``vary`` lists request headers the answer depends on (``X-Tenant``).
+    ``vary_on_user`` caches answers to users too, one entry per actor.
+    ``max_age`` lets clients reuse an answer that long without asking
+    again. ``name`` (default: the endpoint's import path) starts every key.
+
+    Raises:
+        TypeError: The endpoint is not async, or returns a ``Response``.
+        ValueError: ``max_age`` is negative.
+    """
+    if max_age < 0:
+        raise ValueError("max_age cannot be negative.")
+    headers = tuple(header.lower() for header in vary)
+
+    def decorate(endpoint: Endpoint) -> Endpoint:
+        if not inspect.iscoroutinefunction(endpoint):
+            raise TypeError("@cache_page decorates async endpoints.")
+        hints = get_type_hints(endpoint, include_extras=True)
+        returns = hints.get("return", Any)
+        if inspect.isclass(returns) and issubclass(returns, Response):
+            raise TypeError(
+                "@cache_page caches values FastAPI serializes, not Response objects."
+            )
+        prefix = name or f"{endpoint.__module__}.{endpoint.__qualname__}"
+        signature = _signature(endpoint, hints)
+        request_name = _parameter_of(signature, Request)
+        response_name = _parameter_of(signature, Response)
+
+        async def page(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401 - the endpoint's.
+            request: Request = kwargs[request_name]
+            response: Response = kwargs[response_name]
+            for added in (REQUEST, RESPONSE):  # Ours, not the endpoint's.
+                kwargs.pop(added, None)
+            user = _user(request)
+            if (
+                request.method not in CACHEABLE_METHODS
+                or user == _UNCHECKED
+                or (user is not None and not vary_on_user)
+            ):
+                return await endpoint(*args, **kwargs)
+            key = _key(prefix, request, headers, user)
+
+            async def compute() -> Any:  # noqa: ANN401 - the endpoint's.
+                # Typed now, so fields the return type leaves out are not cached.
+                result = await endpoint(*args, **kwargs)
+                return adapter(returns).validate_python(result, from_attributes=True)
+
+            value = await caches[cache].get_or_set(key, compute, returns, ttl)
+            etag = f'W/"{hashlib.sha256(to_json(value)).hexdigest()[:32]}"'
+            control = "private" if vary_on_user else "public"
+            answer = {
+                "ETag": etag,
+                "Cache-Control": f"{control}, "
+                + (f"max-age={max_age}" if max_age else "no-cache"),
+            }
+            if _matches(request.headers.get("if-none-match"), etag):
+                unchanged = Response(status_code=status.HTTP_304_NOT_MODIFIED)
+                unchanged.headers.update(answer)
+                patch_vary(unchanged.headers, ["Authorization", *vary])
+                return unchanged
+            response.headers.update(answer)
+            patch_vary(response.headers, ["Authorization", *vary])
+            return value
+
+        update_wrapper(page, endpoint)
+        page.__signature__ = signature  # type: ignore[attr-defined]
+        return page
+
+    return decorate
+
+
+_UNCHECKED: Final = ""
+"""Credentials no middleware accepted: whose they are is unknown."""
+
+
+def _user(request: Request) -> str | None:
+    """The actor, ``""`` for credentials without one, or None for anonymous callers.
+
+    Without an actor (no ``RequestContextMiddleware``), credentials that
+    middleware accepted (``request.auth``) still count, by their user's id:
+    a cookie or a client certificate sends no ``Authorization`` header.
+    """
+    context = current_request()
+    if context is not None and context.actor:
+        return context.actor
+    credentials = request.scope.get("auth")
+    if credentials is not None:
+        user_id = getattr(getattr(credentials, "user", None), "id", None)
+        return _UNCHECKED if user_id is None else str(user_id)
+    return _UNCHECKED if "authorization" in request.headers else None
+
+
+def _key(
+    prefix: str, request: Request, headers: Sequence[str], user: str | None
+) -> str:
+    """The entry for this request: URL, query, language, headers, and user.
+
+    The URL has the scheme and the host, so tenants chosen by ``Host``, and
+    answers that link to themselves, never share an entry.
+    """
+    query = sorted(request.query_params.multi_items(), key=lambda item: item[0])
+    url = request.url
+    parts = [
+        f"{url.scheme}://{url.netloc}{url.path}",
+        query,
+        get_language(),
+        [request.headers.get(header) for header in headers],
+        user,
+    ]
+    canonical = json.dumps(parts, separators=(",", ":"))
+    return f"page:{prefix}:{hashlib.sha256(canonical.encode()).hexdigest()[:32]}"
+
+
+def _matches(if_none_match: str | None, etag: str) -> bool:
+    """Whether ``If-None-Match`` names ``etag`` (or ``*``), compared weakly.
+
+    Resources compare their tags the same way (``utils.headers.none_match``).
+    """
+    return none_match(if_none_match, etag)
+
+
+def _signature(endpoint: Endpoint, hints: dict[str, Any]) -> inspect.Signature:
+    """The endpoint's signature, annotations resolved, with the request and response.
+
+    FastAPI reads parameters from it. It would evaluate annotations written
+    as strings (``from __future__ import annotations``) in this module,
+    where the endpoint's names are unknown, so they are resolved here.
+    FastAPI passes one ``Request`` and one ``Response`` parameter, so the
+    endpoint's own are used when it has them.
+    """
+    signature = inspect.signature(endpoint)
+    parameters = [
+        parameter.replace(annotation=hints.get(name, parameter.annotation))
+        for name, parameter in signature.parameters.items()
+    ]
+    if {REQUEST, RESPONSE} & set(signature.parameters):
+        raise TypeError(f"@cache_page needs the parameter names {REQUEST}, {RESPONSE}.")
+    keyword = inspect.Parameter.KEYWORD_ONLY
+    added = [
+        inspect.Parameter(name, keyword, annotation=kind)
+        for name, kind in ((REQUEST, Request), (RESPONSE, Response))
+        if not any(_is(parameter.annotation, kind) for parameter in parameters)
+    ]
+    variadic = [p for p in parameters if p.kind is inspect.Parameter.VAR_KEYWORD]
+    fixed = [p for p in parameters if p.kind is not inspect.Parameter.VAR_KEYWORD]
+    return signature.replace(
+        parameters=[*fixed, *added, *variadic],
+        return_annotation=hints.get("return", signature.return_annotation),
+    )
+
+
+def _parameter_of(signature: inspect.Signature, kind: type) -> str:
+    """The name of the parameter FastAPI passes a ``kind`` (request or response)."""
+    return next(
+        name
+        for name, parameter in signature.parameters.items()
+        if _is(parameter.annotation, kind)
+    )
+
+
+def _is(annotation: object, kind: type) -> bool:
+    """Whether a parameter annotated ``annotation`` receives a ``kind``."""
+    return inspect.isclass(annotation) and issubclass(annotation, kind)