domainkit 0.6.0__tar.gz → 0.6.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.6.0
+Version: 0.6.2
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -124,9 +124,10 @@ billing/
   tests/test_health.py
 ```
 
-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. They
+The production settings read `BILLING_API_ALLOWED_HOSTS`,
+`BILLING_API_DATABASE_URL`, and `BILLING_API_TRUSTED_PROXIES` (the load
+balancers' networks, or empty) from the environment, and the deployment
+checks 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.

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

@@ -73,9 +73,10 @@ billing/
   tests/test_health.py
 ```
 
-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. They
+The production settings read `BILLING_API_ALLOWED_HOSTS`,
+`BILLING_API_DATABASE_URL`, and `BILLING_API_TRUSTED_PROXIES` (the load
+balancers' networks, or empty) from the environment, and the deployment
+checks 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.

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

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.6.0"
+version = "0.6.2"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/conf/env.py

@@ -18,6 +18,7 @@ is not expanded.
 """
 
 import builtins
+import math
 import os
 import re
 import tomllib
@@ -188,7 +189,7 @@ class Env:
         text = self.raw(name)
         if text is None:
             return self._default(name, default)
-        return self._convert(name, text, builtins.float, "a number")
+        return self._convert(name, text, _finite, "a finite number")
 
     def bool[D](
         self, name: builtins.str, default: D | _Missing = MISSING
@@ -202,7 +203,7 @@ class Env:
             return True
         if normalized in _FALSE:
             return False
-        raise self._invalid(name, text, "a boolean (true/false)")
+        raise self._invalid(name, "a boolean (true/false)")
 
     def list[D](
         self, name: builtins.str, default: D | _Missing = MISSING
@@ -243,16 +244,26 @@ class Env:
         """Convert with ``cast`` or explain which variable is invalid."""
         try:
             return cast(text)
-        except ValueError as exc:
-            raise self._invalid(name, text, expected) from exc
+        except ValueError:
+            # "from None": the ValueError would quote the value, maybe a secret.
+            raise self._invalid(name, expected) from None
 
     def _invalid(
-        self, name: builtins.str, text: builtins.str, expected: builtins.str
+        self, name: builtins.str, expected: builtins.str
     ) -> ImproperlyConfigured:
-        """Build the error for a value that cannot be converted."""
-        return ImproperlyConfigured(
-            f"{self.prefix}{name} must be {expected}, got {text!r}."
-        )
+        """Build the error for a value that cannot be converted.
+
+        The value is not quoted: it may be a secret read from ``<NAME>_FILE``.
+        """
+        return ImproperlyConfigured(f"{self.prefix}{name} must be {expected}.")
+
+
+def _finite(text: builtins.str) -> builtins.float:
+    """Read a number; infinity and NaN are no setting's value."""
+    value = builtins.float(text)
+    if not math.isfinite(value):
+        raise ValueError  # _convert explains it, without the value.
+    return value
 
 
 def _from_root(path: Path) -> Path:

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/conf/global_settings.py

@@ -6,10 +6,10 @@ the framework does not declare must belong to an installed domain (see
 so a misspelled setting fails at startup instead of being silently ignored.
 """
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
 from pathlib import Path
 from typing import Any, Final, Literal, Self
-from urllib.parse import parse_qs, urlsplit
+from urllib.parse import SplitResult, parse_qs, urlsplit
 
 from pydantic import (
     BaseModel,
@@ -17,6 +17,8 @@ from pydantic import (
     Field,
     IPvAnyNetwork,
     SecretStr,
+    SerializerFunctionWrapHandler,
+    model_serializer,
     model_validator,
 )
 
@@ -24,6 +26,8 @@ from domainkit.conf.env import project_root
 from domainkit.utils.rates import parse_rate
 
 DEFAULT_DB_ALIAS: Final = "default"
+HIDDEN: Final = "**********"
+"""What ``repr`` and dumps of the settings show for domain settings."""
 
 Environment = Literal["local", "test", "staging", "production"]
 DEPLOYED_ENVIRONMENTS: Final = frozenset({"staging", "production"})
@@ -61,7 +65,7 @@ IMMUDB_PORT: Final = 3322
 class DatabaseConfig(BaseModel):
     """One ``DATABASES`` entry: an SQLAlchemy async URL plus connection options."""
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     URL: SecretStr
     """``dialect+driver://user:password@host/name``; hidden in reprs and errors."""
@@ -111,6 +115,21 @@ class DatabaseConfig(BaseModel):
         return self
 
 
+def _check_port(parts: SplitResult) -> None:
+    """Refuse a URL whose port is not a number, without quoting it.
+
+    A ``/`` in the password ends the host early, so the port Python reads is
+    part of the password; its own error would quote it.
+    """
+    try:
+        parts.port  # noqa: B018 - reading it parses it.
+    except ValueError:
+        raise ValueError(
+            "the URL's port is not a number; percent-encode / ? # @ and : in "
+            "the user name and password"
+        ) from None
+
+
 class LedgerConfig(BaseModel):
     """One ``LEDGERS`` entry: write once, read many, verified on the client.
 
@@ -118,7 +137,7 @@ class LedgerConfig(BaseModel):
     migrated and never take part in a unit of work.
     """
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     URL: SecretStr
     """``immudb://user:password@host:3322/database``, or ``memory://`` for tests."""
@@ -135,6 +154,7 @@ class LedgerConfig(BaseModel):
         parts = urlsplit(self.URL.get_secret_value())
         if parts.scheme not in LEDGER_SCHEMES:
             raise ValueError("a ledger URL starts with immudb:// or memory://")
+        _check_port(parts)
         if parts.scheme == "immudb" and not parts.hostname:
             raise ValueError("an immudb URL needs a host: immudb://user:pw@host/db")
         return self
@@ -152,7 +172,7 @@ class ShardConfig(BaseModel):
     to one database. Moving buckets between databases is how a group grows.
     """
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     DATABASES: tuple[str, ...] = Field(min_length=1)
     """The group's SQL aliases; ``makemigrations`` compares against the first."""
@@ -224,7 +244,7 @@ class CacheConfig(BaseModel):
     ``get_or_set`` and ``@cached`` compute values instead (see ADR 0012).
     """
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     URL: SecretStr = SecretStr("memory://")
     """``memory://`` (this process), ``redis://``/``rediss://`` (Redis, Valkey), ``dummy://``."""
@@ -264,6 +284,7 @@ class CacheConfig(BaseModel):
             raise ValueError(
                 "a cache URL starts with memory://, redis://, rediss://, or dummy://"
             )
+        _check_port(parts)
         if parts.scheme in REDIS_SCHEMES:
             if not parts.hostname:
                 raise ValueError("a Redis URL needs a host: redis://host:6379/0")
@@ -318,7 +339,7 @@ class BrokerConfig(BaseModel):
     never drops them (see ADR 0014).
     """
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     URL: SecretStr
     """``amqps://user:password@host:5671/vhost`` (RabbitMQ), or ``memory://``."""
@@ -340,6 +361,7 @@ class BrokerConfig(BaseModel):
         parts = urlsplit(self.URL.get_secret_value())
         if parts.scheme not in BROKER_SCHEMES:
             raise ValueError("a broker URL starts with amqp://, amqps://, or memory://")
+        _check_port(parts)
         if parts.scheme != "memory":
             if not parts.hostname:
                 raise ValueError("an AMQP URL needs a host: amqps://user:pw@host/vhost")
@@ -380,7 +402,7 @@ class BrokerConfig(BaseModel):
 class Settings(BaseModel):
     """Validated, read-only settings; extra names are checked at ``setup()``."""
 
-    model_config = ConfigDict(frozen=True, extra="allow")
+    model_config = ConfigDict(frozen=True, extra="allow", allow_inf_nan=False)
 
     SETTINGS_MODULE: str = ""
     """Set by the loader to the module that produced these settings."""
@@ -466,6 +488,23 @@ class Settings(BaseModel):
     )
     CORS_ALLOW_CREDENTIALS: bool = False
 
+    def __repr_args__(self) -> Iterator[tuple[str | None, Any]]:
+        """Show declared settings; domain settings, which may hold keys, hidden."""
+        domain = self.model_extra or {}
+        for name, value in super().__repr_args__():
+            yield name, HIDDEN if name in domain else value
+
+    @model_serializer(mode="wrap")
+    def _hide_domain_settings(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, Any]:
+        """Dump domain settings hidden: they are checked, and typed, elsewhere."""
+        dumped: dict[str, Any] = handler(self)
+        return {
+            name: HIDDEN if name in (self.model_extra or {}) else value
+            for name, value in dumped.items()
+        }
+
     @model_validator(mode="after")
     def check_consistency(self) -> Self:
         """Reject combinations that are unsafe or would fail later at runtime."""
@@ -534,6 +573,12 @@ class Settings(BaseModel):
                 f"Requests are not rate limited; set RATE_LIMIT and list "
                 f"{RATE_LIMIT_MIDDLEWARE} in MIDDLEWARE."
             )
+        elif not self.TRUSTED_PROXIES:
+            warnings.append(
+                "TRUSTED_PROXIES is empty, so callers are rate limited by the "
+                "address they connect from: behind a load balancer or proxy, "
+                "they all share its count. List its networks in TRUSTED_PROXIES."
+            )
         return warnings
 
     def _check_deployment(self) -> None:
@@ -543,6 +588,11 @@ class Settings(BaseModel):
             raise ValueError(f"DEBUG must be False {where}")
         if "*" in self.ALLOWED_HOSTS:
             raise ValueError(f"ALLOWED_HOSTS must list real host names {where}")
+        if any(network.prefixlen == 0 for network in self.TRUSTED_PROXIES):
+            raise ValueError(
+                f"TRUSTED_PROXIES must list the proxies' networks, not every "
+                f"address {where}: any caller could choose its own address"
+            )
         rules: dict[str, Callable[[DatabaseConfig], bool]] = {
             "ECHO logs every statement; disable it": lambda db: db.ECHO,
             "LOG_PARAMETERS exposes bound values; disable it": lambda db: (

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/context.py

@@ -8,6 +8,10 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
+from typing import Final
+
+SYSTEM_ACTOR: Final = "system"
+"""The actor of work no caller asked for: periodic tasks, commands' messages."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -15,7 +19,8 @@ class RequestContext:
     """Facts about the request or job being served; no personal data.
 
     ``actor`` names who is acting. Authentication sets it; None means an
-    anonymous caller, and background work carries the actor that queued it.
+    anonymous caller, and background work carries the actor that queued it,
+    or ``SYSTEM_ACTOR`` when no request did.
     """
 
     request_id: str

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/audit/management/commands/auditverify.py

@@ -52,6 +52,8 @@ def _summary(report: Report) -> str:
     ):
         if found:
             lines.append(f"  {name}: {', '.join(str(each) for each in found)}")
+    if report.unanchored:
+        lines.append(f"  seals left unanchored: {report.unanchored}")
     if report.unsealed:
         lines.append(f"  unsealed rows: {report.unsealed}")
     return "\n".join(lines)

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/audit/personal.py

@@ -52,7 +52,8 @@ def pseudonym(key: bytes, field: str, value: object) -> str:
     """``value``, the ``field`` of a subject, as a pseudonym under their ``key``.
 
     The field's name is part of it, so equal values in different fields do
-    not give away that they are equal.
+    not give away that they are equal. Lone surrogates in strings are
+    encoded as they are, so every value has a pseudonym.
     """
     data = json.dumps(
         to_jsonable_python(value),
@@ -60,7 +61,8 @@ def pseudonym(key: bytes, field: str, value: object) -> str:
         separators=(",", ":"),
         ensure_ascii=False,
     )
-    digest = hmac.new(key, f"{field}\0{data}".encode(), hashlib.sha256).hexdigest()
+    message = f"{field}\0{data}".encode("utf-8", "surrogatepass")
+    digest = hmac.new(key, message, hashlib.sha256).hexdigest()
     return f"{PREFIX}{digest[:DIGITS]}"
 
 

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/audit/recorder.py

@@ -1,7 +1,8 @@
 """Building and writing audit rows.
 
 Who acted comes from the request context: the authenticated actor,
-``anonymous`` for unauthenticated requests, ``system`` outside requests.
+``anonymous`` for unauthenticated requests, ``system`` outside requests and
+in work no request queued (periodic tasks).
 Never put secrets in event fields or ``details``: they are kept for good.
 
 Personal values are written as pseudonyms (see ``personal``): the client's
@@ -22,7 +23,7 @@ from sqlalchemy import insert
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession
 
 from domainkit.apps import registry
-from domainkit.context import current_request
+from domainkit.context import SYSTEM_ACTOR, current_request
 from domainkit.db import connections
 from domainkit.ddd import DomainEvent
 from domainkit.ddd.personal import personal_fields
@@ -47,7 +48,7 @@ def _actor() -> str:
     """Return who is acting in the current context."""
     request = current_request()
     if request is None:
-        return "system"
+        return SYSTEM_ACTOR
     return request.actor or "anonymous"
 
 
@@ -110,8 +111,11 @@ def audit_row(
     """
     request = current_request()
     occurred_at = occurred_at or datetime.now(UTC)
-    caller = (request.actor if request else None) or anonymous_subject(
-        occurred_at.astimezone(UTC).date()
+    actor = request.actor if request else None
+    caller = (
+        actor
+        if actor not in {None, SYSTEM_ACTOR}
+        else anonymous_subject(occurred_at.astimezone(UTC).date())
     )
     row = {
         "id": uuid.uuid4(),

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/audit/seals.py

@@ -10,7 +10,8 @@ verifies what it returns: a chain rewritten after a head was anchored no
 longer matches it.
 
 ``verify`` reports changed and missing rows, links that do not follow,
-anchors the chain no longer matches, and rows left unsealed.
+anchors the chain no longer matches, seals left unanchored, and rows left
+unsealed.
 
 Rows are sealed after they commit, by the worker every ``AUDIT.SEAL_EVERY``
 or by ``auditseal``, so a row can be rewritten unnoticed until it is sealed
@@ -114,6 +115,9 @@ class Report:
     """Seals whose number or link does not follow the one before."""
     rewritten: list[int] = field(default_factory=list)
     """Anchored heads the chain no longer has."""
+    unanchored: int = 0
+    """Seals after the newest anchor, sealed more than ``ANCHOR_EVERY`` and
+    ``LOOKBACK`` ago: anchoring stopped (checked with a ledger only)."""
     unsealed: int = 0
     """Rows older than ``LOOKBACK`` without a seal."""
 
@@ -121,7 +125,7 @@ class Report:
     def intact(self) -> bool:
         """Whether nothing was found wrong."""
         problems = (self.changed, self.missing, self.broken, self.rewritten)
-        return not (any(problems) or self.unsealed)
+        return not (any(problems) or self.unanchored or self.unsealed)
 
 
 def digest(row: Mapping[Any, Any]) -> str:
@@ -163,7 +167,8 @@ async def anchor(
 ) -> Anchor | None:
     """Write ``database``'s head to ``ledger``; None when there is nothing new.
 
-    A head is anchored at most once per ``every``, and never twice.
+    A head is anchored at most once per ``every``, and never twice. An anchor
+    dated after ``now`` (written by a clock running ahead) holds none back.
     """
     now = now or datetime.now(UTC)
     async with connections.engine(database).connect() as connection:
@@ -175,7 +180,7 @@ async def anchor(
     except LedgerKeyNotFound:
         latest = None
     if latest is not None and (
-        latest.seq == head.seq or now - latest.anchored_at < every
+        latest.seq == head.seq or timedelta(0) <= now - latest.anchored_at < every
     ):
         return None
     written = Anchor(head.seq, head.link, now)
@@ -199,12 +204,27 @@ async def seal_all() -> dict[str, tuple[int, Anchor | None]]:
 
 
 async def verify(
-    database: str, ledger: Ledger | None = None, *, now: datetime | None = None
+    database: str,
+    ledger: Ledger | None = None,
+    *,
+    now: datetime | None = None,
+    every: timedelta | None = None,
 ) -> Report:
-    """Check ``database``'s chain against its rows, and against ``ledger``."""
+    """Check ``database``'s chain against its rows, and against ``ledger``.
+
+    With a ledger, seals sealed more than ``every`` (default:
+    ``AUDIT.ANCHOR_EVERY``) and ``LOOKBACK`` ago must be anchored.
+    """
+    now = now or datetime.now(UTC)
     report = Report(database)
     anchored = await _anchors(database, ledger) if ledger is not None else {}
     report.anchors = len(anchored)
+    newest_anchored = max(anchored, default=0)
+    overdue = None  # Sealed before this, a seal must be anchored.
+    if ledger is not None:
+        if every is None:
+            every = registry.settings(AuditSettings).ANCHOR_EVERY
+        overdue = now - every - LOOKBACK
     previous = Head(0, GENESIS)
     query = (
         select(audit_seals, *(audit_log.c[name] for name in COLUMNS))
@@ -225,16 +245,23 @@ async def verify(
                 report.changed.append(seal_row["entry_id"])
             if anchored.pop(seal_row["seq"], seal_row["link"]) != seal_row["link"]:
                 report.rewritten.append(seal_row["seq"])
+            if (
+                overdue is not None
+                and seal_row["seq"] > newest_anchored
+                and seal_row["sealed_at"] < overdue
+            ):
+                report.unanchored += 1
             previous = Head(seal_row["seq"], seal_row["link"])
         report.rewritten.extend(sorted(anchored))  # Anchored seals now gone.
-        report.unsealed = await _unsealed(connection, now or datetime.now(UTC))
+        report.unsealed = await _unsealed(connection, now)
     return report
 
 
 async def _seal_batch(connection: AsyncConnection, batch: int) -> int:
     """Seal up to ``batch`` rows after the head, oldest first."""
     head = await _head(connection)
-    horizon = await _horizon(connection, head)
+    sealed_at = datetime.now(UTC)
+    horizon = await _horizon(connection, head, sealed_at)
     unsealed = (
         select(*(audit_log.c[name] for name in COLUMNS))
         .outerjoin(audit_seals, audit_seals.c.entry_id == audit_log.c.id)
@@ -246,7 +273,6 @@ async def _seal_batch(connection: AsyncConnection, batch: int) -> int:
         unsealed = unsealed.where(audit_log.c.occurred_at >= horizon)
     rows = (await connection.execute(unsealed)).mappings().all()
     previous = head or Head(0, GENESIS)
-    sealed_at = datetime.now(UTC)
     seals = []
     for row in rows:
         row_digest = digest(row)
@@ -277,8 +303,14 @@ async def _head(connection: AsyncConnection) -> Head | None:
     return None if found is None else Head(found.seq, found.link)
 
 
-async def _horizon(connection: AsyncConnection, head: Head | None) -> datetime | None:
-    """Where to look for unsealed rows: ``LOOKBACK`` before the head's row."""
+async def _horizon(
+    connection: AsyncConnection, head: Head | None, now: datetime
+) -> datetime | None:
+    """Where to look for unsealed rows: ``LOOKBACK`` before the head's row.
+
+    A head's row dated after ``now`` (a clock running ahead) counts as
+    ``now``, so it cannot leave the rows written before it unsealable.
+    """
     if head is None:
         return None
     newest = await connection.scalar(
@@ -286,7 +318,7 @@ async def _horizon(connection: AsyncConnection, head: Head | None) -> datetime |
         .join(audit_seals, audit_seals.c.entry_id == audit_log.c.id)
         .where(audit_seals.c.seq == head.seq)
     )
-    return None if newest is None else newest - LOOKBACK
+    return None if newest is None else min(newest, now) - LOOKBACK
 
 
 async def _unsealed(connection: AsyncConnection, now: datetime) -> int:
@@ -327,7 +359,12 @@ def _plain(value: object) -> object:
 
 
 def _canonical(document: object) -> bytes:
-    """``document`` as compact JSON with sorted keys."""
+    """``document`` as compact JSON with sorted keys.
+
+    Strings can hold lone surrogates (JSON can escape half a surrogate
+    pair); they are encoded as they are, so every row has a digest, and the
+    bytes of every other string stay plain UTF-8.
+    """
     return json.dumps(
         document, sort_keys=True, separators=(",", ":"), ensure_ascii=False
-    ).encode()
+    ).encode("utf-8", "surrogatepass")

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/audit/settings.py

@@ -10,7 +10,7 @@ from domainkit.conf import DEFAULT_DB_ALIAS
 class AuditSettings(BaseModel):
     """What to record; every key is optional."""
 
-    model_config = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid", allow_inf_nan=False)
 
     DATABASE: str = DEFAULT_DB_ALIAS
     """Alias holding the audit trail; event audits need units of work on it."""

{domainkit-0.6.0 → domainkit-0.6.2}/src/domainkit/contrib/auth/__init__.py

@@ -46,6 +46,7 @@ from .access import (
     Require,
     check_object_permissions,
     current_user,
+    mark_public,
     open_routes,
 )
 from .authentication import (
@@ -165,6 +166,7 @@ __all__ = [
     "has_perm",
     "has_perms",
     "make_password",
+    "mark_public",
     "open_routes",
     "password_help_texts",
     "validate_password",