loom-kernel 2.13.0__tar.gz → 2.14.0__tar.gz

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/CHANGELOG.md

@@ -140,6 +140,13 @@
 
 ### rest
 
+- **rest:** a single `RuleViolation(field, message)` now answers its `field`.
+  `HttpErrorMapper` dropped it, so two `rule_violation` 422s could only be
+  told apart by their message text. The body adds `field` (`ErrorField.FIELD`,
+  the key each `violations` item of `RuleViolations` already carries) next to
+  the unchanged `code`, `message` and `trace_id`; the status stays `422`. This
+  includes the SQL endpoint's 422s, whose `field` is `sql` or `body`. Every
+  other error body is unchanged.
 - **rest:** a strict `pydantic.BaseModel` result, a `list` of them or an
   envelope holding one now renders directly on a REST route, through
   `MsgspecJSONResponse`'s `enc_hook`, and documents in OpenAPI
@@ -363,6 +370,19 @@
   capability does not recover yet; see "A session that died after it opened is
   replaced by the next call" in `docs/ai/mcp.md`.
 
+### rest
+
+- **rest:** an authenticator can report an outage instead of answering `500`.
+  An exception raised inside `AuthenticationMiddleware` never reached
+  Starlette's exception handlers, so a custom authenticator whose identity
+  provider was unreachable answered a bare `500`. An authenticator now raises
+  `loom.rest.auth.AuthenticationUnavailable` and the request answers `503`
+  with the standard error body (`code: service_unavailable`, a fixed message,
+  `trace_id`) and no `WWW-Authenticate` challenge; the exception's message
+  and cause are logged at `WARNING`, never sent. `ErrorCode` gains
+  `SERVICE_UNAVAILABLE`, which `HttpErrorMapper` maps to `503`. Any other
+  exception from the authenticator, and the `401` refusal, are unchanged.
+
 ## ♻️ Refactor
 
 ### etl

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.13.0
+Version: 2.14.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/core/errors/codes.py

@@ -34,4 +34,5 @@ class ErrorCode(StrEnum):
     UNSUPPORTED_FORMAT = "unsupported_format"
     UNSUPPORTED_QUERY = "unsupported_query"
     SYSTEM_ERROR = "system_error"
+    SERVICE_UNAVAILABLE = "service_unavailable"
     POST_COMMIT_FAILURE = "post_commit_failure"

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/rest/auth/__init__.py

@@ -12,13 +12,14 @@ Install the optional JWT dependency with::
     pip install "loom-kernel[jwt]"
 """
 
-from loom.rest.auth.abc import Authenticator, RequestCredentials
+from loom.rest.auth.abc import AuthenticationUnavailable, Authenticator, RequestCredentials
 from loom.rest.auth.config import JwtAuthConfig, JwtIssuerConfig
 from loom.rest.auth.jwt import JwtAuthenticator, JwtIssuer
 from loom.rest.auth.middleware import AuthenticationMiddleware, JwtAuthMiddleware
 
 __all__ = [
     "AuthenticationMiddleware",
+    "AuthenticationUnavailable",
     "Authenticator",
     "JwtAuthConfig",
     "JwtAuthMiddleware",

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/rest/auth/abc.py

@@ -13,6 +13,8 @@ from dataclasses import dataclass
 from types import MappingProxyType
 from typing import Protocol, runtime_checkable
 
+from loom.core.errors import LoomError
+from loom.core.errors.codes import ErrorCode
 from loom.core.identity import Identity
 
 
@@ -59,6 +61,39 @@ class RequestCredentials:
         return self.headers.get(name.lower())
 
 
+class AuthenticationUnavailable(LoomError):
+    """Raised by an authenticator that cannot decide on the credentials right now.
+
+    An outage of something the mechanism depends on — an identity provider's
+    key set, a session store, a revocation list — is neither a refusal nor a
+    bug.  :class:`~loom.rest.auth.middleware.AuthenticationMiddleware` answers
+    it with ``503 service_unavailable``: a ``401`` would make clients discard
+    credentials that are still valid, and a ``500`` would report a bug where
+    there is an outage.
+    Any other exception an authenticator raises keeps propagating unchanged.
+
+    Raised from an authenticator, the message goes to the server log, never to
+    the caller, so it may name the unreachable dependency; raised anywhere
+    else, :class:`~loom.rest.errors.HttpErrorMapper` answers ``503`` with it,
+    like any :class:`~loom.core.errors.LoomError`.  It must never carry the
+    credential.  Chain the underlying error with ``raise ... from exc`` to keep
+    its traceback.
+
+    Args:
+        message: Operator-facing description of what is unavailable.
+
+    Example::
+
+        try:
+            keys = await self._jwks.fetch()
+        except httpx.HTTPError as exc:
+            raise AuthenticationUnavailable("issuer key set unreachable") from exc
+    """
+
+    def __init__(self, message: str = "Authentication is temporarily unavailable") -> None:
+        super().__init__(message, code=ErrorCode.SERVICE_UNAVAILABLE)
+
+
 @runtime_checkable
 class Authenticator(Protocol):
     """Turns the credentials of one request into a verified identity.
@@ -105,5 +140,9 @@ class Authenticator(Protocol):
             The verified identity, or ``None`` to refuse the request.  The
             refusal carries no reason on purpose: the response must not become
             an oracle about which part of the credentials failed.
+
+        Raises:
+            AuthenticationUnavailable: When the credentials cannot be verified
+                right now because a dependency of the mechanism is down.
         """
         ...

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/rest/auth/middleware.py

@@ -12,7 +12,8 @@ TLS without touching a single authorization rule.
 from __future__ import annotations
 
 import logging
-from collections.abc import Awaitable, Callable, Sequence
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from http import HTTPStatus
 from typing import Any
 
 import msgspec
@@ -20,7 +21,7 @@ import msgspec
 from loom.core.errors.codes import ErrorCode
 from loom.core.identity import reset_identity, set_identity
 from loom.core.tracing import get_trace_id
-from loom.rest.auth.abc import Authenticator, RequestCredentials
+from loom.rest.auth.abc import AuthenticationUnavailable, Authenticator, RequestCredentials
 from loom.rest.auth.config import JwtAuthConfig
 from loom.rest.auth.jwt import JwtAuthenticator
 from loom.rest.constants import BEARER_CHALLENGE
@@ -33,6 +34,7 @@ _ASGIApp = Callable[[_Scope, _Receive, _Send], Awaitable[None]]
 
 _HTTP_SCOPE = "http"
 _UNAUTHORIZED_MESSAGE = "Authentication required: missing or invalid credentials."
+_UNAVAILABLE_MESSAGE = "Authentication is temporarily unavailable."
 _UNKNOWN_CLIENT = "unknown"
 
 _logger = logging.getLogger(__name__)
@@ -55,6 +57,10 @@ class AuthenticationMiddleware:
     4. On success, installs the identity for the duration of the request and
        restores the previous one in a ``finally`` — without it, a reused
        worker task would inherit the previous caller.
+    5. When the authenticator raises
+       :class:`~loom.rest.auth.abc.AuthenticationUnavailable`, answers ``503``
+       with the standard error body and a fixed message, and logs the cause at
+       ``WARNING``.  Any other exception propagates unchanged.
 
     Non-HTTP scopes (WebSocket, lifespan) are passed through unchanged.
 
@@ -89,7 +95,23 @@ class AuthenticationMiddleware:
             await self._app(scope, receive, send)
             return
 
-        identity = await self._authenticator.authenticate(_credentials(scope))
+        try:
+            identity = await self._authenticator.authenticate(_credentials(scope))
+        except AuthenticationUnavailable:
+            _logger.warning(
+                "authentication unavailable method=%s path=%s",
+                scope.get("method", _UNKNOWN_CLIENT),
+                scope.get("path", _UNKNOWN_CLIENT),
+                exc_info=True,
+            )
+            await _send_error(
+                send,
+                HTTPStatus.SERVICE_UNAVAILABLE,
+                ErrorCode.SERVICE_UNAVAILABLE,
+                _UNAVAILABLE_MESSAGE,
+            )
+            return
+
         if identity is None:
             _logger.info(
                 "authentication refused method=%s path=%s client=%s",
@@ -170,9 +192,26 @@ async def send_unauthorized(send: _Send) -> None:
     Args:
         send: ASGI send callable of the request being refused.
     """
+    await _send_error(
+        send,
+        HTTPStatus.UNAUTHORIZED,
+        ErrorCode.UNAUTHENTICATED,
+        _UNAUTHORIZED_MESSAGE,
+        BEARER_CHALLENGE,
+    )
+
+
+async def _send_error(
+    send: _Send,
+    status: HTTPStatus,
+    code: ErrorCode,
+    message: str,
+    extra_headers: Mapping[str, str] | None = None,
+) -> None:
+    """Send *status* with the standard ``code``/``message``/``trace_id`` body."""
     detail = {
-        "code": ErrorCode.UNAUTHENTICATED.value,
-        "message": _UNAUTHORIZED_MESSAGE,
+        "code": code.value,
+        "message": message,
         "trace_id": get_trace_id(),
     }
     body = msgspec.json.encode({"detail": detail})
@@ -181,8 +220,8 @@ async def send_unauthorized(send: _Send) -> None:
         (b"content-length", str(len(body)).encode("ascii")),
         *(
             (name.lower().encode("ascii"), value.encode("ascii"))
-            for name, value in BEARER_CHALLENGE.items()
+            for name, value in (extra_headers or {}).items()
         ),
     ]
-    await send({"type": "http.response.start", "status": 401, "headers": headers})
+    await send({"type": "http.response.start", "status": status.value, "headers": headers})
     await send({"type": "http.response.body", "body": body})

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/rest/errors.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 from enum import StrEnum
+from http import HTTPStatus
 from typing import Any, ClassVar
 
 from fastapi import HTTPException
 
 from loom.core.engine.post_commit import PostCommitError
-from loom.core.errors import LoomError, NotFound, RuleViolations
+from loom.core.errors import LoomError, NotFound, RuleViolation, RuleViolations
 from loom.core.errors.codes import ErrorCode
 from loom.core.model import BoundaryValidationError
 from loom.core.tracing import get_trace_id
@@ -51,6 +52,7 @@ class HttpErrorMapper:
     per error type:
 
     - :class:`~loom.core.errors.NotFound` → ``entity``, ``id``
+    - :class:`~loom.core.errors.RuleViolation` → ``field``
     - :class:`~loom.core.errors.RuleViolations` → ``violations``
     - :class:`~loom.core.model.BoundaryValidationError` → ``violations``
       (``422``; a schema failure, distinct from a rule failure)
@@ -69,18 +71,19 @@ class HttpErrorMapper:
             raise mapper.to_http(exc) from exc
     """
 
-    _STATUS: ClassVar[dict[str, int]] = {
-        ErrorCode.NOT_FOUND: 404,
-        ErrorCode.UNAUTHENTICATED: 401,
-        ErrorCode.FORBIDDEN: 403,
-        ErrorCode.CONFLICT: 409,
-        ErrorCode.RULE_VIOLATIONS: 422,
-        ErrorCode.RULE_VIOLATION: 422,
-        ErrorCode.BOUNDARY_VALIDATION: 422,
-        ErrorCode.UNSUPPORTED_FORMAT: 400,
-        ErrorCode.UNSUPPORTED_QUERY: 400,
-        ErrorCode.SYSTEM_ERROR: 500,
-        ErrorCode.POST_COMMIT_FAILURE: 500,
+    _STATUS: ClassVar[dict[str, HTTPStatus]] = {
+        ErrorCode.NOT_FOUND: HTTPStatus.NOT_FOUND,
+        ErrorCode.UNAUTHENTICATED: HTTPStatus.UNAUTHORIZED,
+        ErrorCode.FORBIDDEN: HTTPStatus.FORBIDDEN,
+        ErrorCode.CONFLICT: HTTPStatus.CONFLICT,
+        ErrorCode.RULE_VIOLATIONS: HTTPStatus.UNPROCESSABLE_ENTITY,
+        ErrorCode.RULE_VIOLATION: HTTPStatus.UNPROCESSABLE_ENTITY,
+        ErrorCode.BOUNDARY_VALIDATION: HTTPStatus.UNPROCESSABLE_ENTITY,
+        ErrorCode.UNSUPPORTED_FORMAT: HTTPStatus.BAD_REQUEST,
+        ErrorCode.UNSUPPORTED_QUERY: HTTPStatus.BAD_REQUEST,
+        ErrorCode.SYSTEM_ERROR: HTTPStatus.INTERNAL_SERVER_ERROR,
+        ErrorCode.SERVICE_UNAVAILABLE: HTTPStatus.SERVICE_UNAVAILABLE,
+        ErrorCode.POST_COMMIT_FAILURE: HTTPStatus.INTERNAL_SERVER_ERROR,
     }
 
     def to_http(self, error: LoomError) -> HTTPException:
@@ -95,7 +98,7 @@ class HttpErrorMapper:
             also carries the ``WWW-Authenticate`` challenge required by
             RFC 9110 §11.6.1.
         """
-        status = self._STATUS.get(error.code, 500)
+        status = self._STATUS.get(error.code, HTTPStatus.INTERNAL_SERVER_ERROR)
         detail: dict[str, Any] = {
             ErrorField.CODE: error.code,
             ErrorField.MESSAGE: error.message,
@@ -106,6 +109,9 @@ class HttpErrorMapper:
             detail[ErrorField.ENTITY] = error.entity
             detail[ErrorField.ID] = error.id
 
+        if isinstance(error, RuleViolation):
+            detail[ErrorField.FIELD] = error.field
+
         if isinstance(error, RuleViolations):
             detail[ErrorField.VIOLATIONS] = [
                 {ErrorField.FIELD: v.field, ErrorField.MESSAGE: v.message} for v in error.violations
@@ -123,6 +129,6 @@ class HttpErrorMapper:
         return HTTPException(status_code=status, detail=detail, headers=_challenge(status))
 
 
-def _challenge(status: int) -> dict[str, str] | None:
+def _challenge(status: HTTPStatus) -> dict[str, str] | None:
     """Return the ``WWW-Authenticate`` header a ``401`` must carry, else ``None``."""
-    return dict(BEARER_CHALLENGE) if status == 401 else None
+    return dict(BEARER_CHALLENGE) if status is HTTPStatus.UNAUTHORIZED else None

{loom_kernel-2.13.0 → loom_kernel-2.14.0}/src/loom/rest/fastapi/_errors.py

@@ -47,7 +47,7 @@ async def _handle_validation_error(request: Request, exc: Exception) -> Response
     del request
     violations = _violations(exc) if isinstance(exc, RequestValidationError) else ()
     return MsgspecJSONResponse(
-        status_code=422,
+        status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
         content={
             "detail": {
                 ErrorField.CODE: ErrorCode.RULE_VIOLATIONS.value,