fastapi-canon 0.1.0__py3-none-any.whl

fastapi_canon/__init__.py

@@ -0,0 +1,22 @@
+"""Opinionated FastAPI feature composition with Dishka and Problem Details."""
+
+from .error import Error, ErrorConfigurationError, ErrorRegistry, Problem
+from .feature import (
+    Composition,
+    ErrorOptions,
+    ExceptionHandlerSpec,
+    Feature,
+    FeatureConfigurationError,
+)
+
+__all__ = [
+    "Composition",
+    "Error",
+    "ErrorConfigurationError",
+    "ErrorOptions",
+    "ErrorRegistry",
+    "ExceptionHandlerSpec",
+    "Feature",
+    "FeatureConfigurationError",
+    "Problem",
+]

fastapi_canon/error/__init__.py

@@ -0,0 +1,11 @@
+from .error import Error
+from .problem import Problem
+from .registry import ErrorRegistry
+from .types import ErrorConfigurationError
+
+__all__ = [
+    "Error",
+    "ErrorConfigurationError",
+    "ErrorRegistry",
+    "Problem",
+]

fastapi_canon/error/contracts.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fastapi import APIRouter
+from fastapi.routing import APIRoute
+from starlette.routing import BaseRoute
+
+from fastapi_canon.error.types import ErrorConfigurationError
+
+if TYPE_CHECKING:
+    from fastapi_canon.error.registry import AnyError, ErrorRegistry
+
+ERRORS_EXTENSION = "x-fastapi-canon-errors"
+INSTALLED_REGISTRY_STATE_KEY = "_fastapi_canon_error_registry"
+
+
+@runtime_checkable
+class _IncludedRouterRoute(Protocol):
+    original_router: APIRouter
+
+
+def iter_http_contracts(
+    router: APIRouter, registry: ErrorRegistry
+) -> Iterator[tuple[APIRoute, tuple[AnyError, ...]]]:
+    """Yield standard FastAPI routes and errors declared through responses=."""
+    yield from _walk_http_contracts(router.routes, registry)
+
+
+def _walk_http_contracts(
+    routes: Sequence[BaseRoute], registry: ErrorRegistry
+) -> Iterator[tuple[APIRoute, tuple[AnyError, ...]]]:
+    for route in routes:
+        if isinstance(route, _IncludedRouterRoute):
+            yield from _walk_http_contracts(route.original_router.routes, registry)
+            continue
+        if isinstance(route, APIRoute):
+            yield route, _errors_from_responses(route, registry)
+
+
+def _errors_from_responses(
+    route: APIRoute, registry: ErrorRegistry
+) -> tuple[AnyError, ...]:
+    by_identity = {str(id(error)): error for error in registry.errors}
+    result: list[AnyError] = []
+    seen: set[int] = set()
+
+    for configured_response in route.responses.values():
+        response: object = configured_response
+        if not isinstance(response, Mapping):
+            continue
+        identities = response.get(ERRORS_EXTENSION, ())
+        if not isinstance(identities, list) or not all(
+            isinstance(identity, str) for identity in identities
+        ):
+            msg = f"route {route.path!r} contains invalid fastapi-canon error metadata"
+            raise ErrorConfigurationError(msg)
+        for identity in identities:
+            error = by_identity.get(identity)
+            if error is None:
+                msg = (
+                    f"route {route.path!r} declares an error whose exact definition "
+                    "is missing from the installed registry"
+                )
+                raise ErrorConfigurationError(msg)
+            if id(error) not in seen:
+                seen.add(id(error))
+                result.append(error)
+
+    return tuple(result)

fastapi_canon/error/error.py

@@ -0,0 +1,273 @@
+import builtins
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import cast
+
+from pydantic import BaseModel, ValidationError
+
+from fastapi_canon.error.types import (
+    CODE_PATTERN,
+    Detail,
+    ErrorConfigurationError,
+    Extensions,
+    Headers,
+    JsonValue,
+    OpenAPIHeader,
+    is_absolute_uri,
+)
+
+_RESERVED_MEMBERS = frozenset({"type", "title", "status", "detail", "instance", "code"})
+_HEADER_NAME_PATTERN = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+_FORBIDDEN_RESPONSE_HEADERS = frozenset(
+    {"connection", "content-length", "content-type", "transfer-encoding"}
+)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Error[ExceptionT: Exception]:
+    """An immutable error contract shared by runtime handling and OpenAPI."""
+
+    exception: builtins.type[ExceptionT]
+    status: int = field(kw_only=True)
+    code: str = field(kw_only=True)
+    title: str = field(kw_only=True)
+    type: str | None = field(default=None, kw_only=True)
+    detail: Detail[ExceptionT] = field(default=None, kw_only=True)
+    extensions_model: builtins.type[BaseModel] | None = field(
+        default=None, kw_only=True
+    )
+    extensions: Extensions[ExceptionT] = field(default=None, kw_only=True)
+    headers: Headers[ExceptionT] = field(default=None, kw_only=True)
+    openapi_headers: Mapping[str, OpenAPIHeader] | None = field(
+        default=None, kw_only=True
+    )
+    description: str | None = field(default=None, kw_only=True)
+    example: Mapping[str, JsonValue] | None = field(default=None, kw_only=True)
+    schema_name: str | None = field(default=None, kw_only=True)
+
+    def __post_init__(self) -> None:
+        """Validate and detach all static inputs from caller-owned mutation."""
+        self._validate_identity()
+        self._validate_detail()
+        self._validate_extensions()
+        self._validate_headers()
+        self._validate_documentation()
+
+    @property
+    def effective_schema_name(self) -> str:
+        """Return the explicit or deterministic OpenAPI component name."""
+        if self.schema_name is not None:
+            return self.schema_name
+        return "".join(part.capitalize() for part in self.code.split("_")) + "Problem"
+
+    def _validate_identity(self) -> None:
+        exception: object = self.exception
+        status: object = self.status
+        code: object = self.code
+        title: object = self.title
+        problem_type: object = self.type
+
+        if not isinstance(exception, builtins.type) or not issubclass(
+            exception, Exception
+        ):
+            msg = "exception must be an Exception subclass"
+            raise ErrorConfigurationError(msg)
+        if (
+            not isinstance(status, int)
+            or isinstance(status, bool)
+            or not 400 <= status <= 599
+        ):
+            msg = "status must be between 400 and 599"
+            raise ErrorConfigurationError(msg)
+        if not isinstance(code, str) or CODE_PATTERN.fullmatch(code) is None:
+            msg = "code must match ^[a-z][a-z0-9_]{2,}$"
+            raise ErrorConfigurationError(msg)
+        if (
+            not isinstance(title, str)
+            or not title.strip()
+            or "\r" in title
+            or "\n" in title
+        ):
+            msg = "title must be a non-empty, single-line string"
+            raise ErrorConfigurationError(msg)
+        if problem_type is not None and (
+            not isinstance(problem_type, str) or not is_absolute_uri(problem_type)
+        ):
+            msg = "type must be an absolute URI without a fragment"
+            raise ErrorConfigurationError(msg)
+
+    def _validate_detail(self) -> None:
+        detail: object = self.detail
+        if detail is not None and not isinstance(detail, str) and not callable(detail):
+            msg = "detail must be a string, callable, or None"
+            raise ErrorConfigurationError(msg)
+
+    def _validate_extensions(self) -> None:
+        model: object = self.extensions_model
+        extensions: object = self.extensions
+
+        if model is not None and (
+            not isinstance(model, builtins.type) or not issubclass(model, BaseModel)
+        ):
+            msg = "extensions_model must be a Pydantic BaseModel subclass"
+            raise ErrorConfigurationError(msg)
+        if model is not None:
+            self._validate_extension_model(model)
+
+        if extensions is None:
+            if model is not None:
+                msg = "extensions is required when extensions_model is provided"
+                raise ErrorConfigurationError(msg)
+            return
+
+        if not isinstance(extensions, Mapping):
+            if not callable(extensions):
+                msg = "extensions must be a mapping, callable, or None"
+                raise ErrorConfigurationError(msg)
+            if model is None:
+                msg = "callable extensions require extensions_model"
+                raise ErrorConfigurationError(msg)
+            return
+
+        overlap = _RESERVED_MEMBERS.intersection(extensions)
+        if overlap:
+            names = ", ".join(sorted(overlap))
+            msg = f"extensions must not redefine reserved members: {names}"
+            raise ErrorConfigurationError(msg)
+
+        frozen_extensions = _freeze_json_mapping(extensions, path="extensions")
+        if model is not None:
+            try:
+                validated = model.model_validate(dict(frozen_extensions))
+            except ValidationError as error:
+                msg = "static extensions do not validate against extensions_model"
+                raise ErrorConfigurationError(msg) from error
+            serialized = cast(
+                dict[str, JsonValue],
+                validated.model_dump(mode="json", by_alias=True),
+            )
+            frozen_extensions = _freeze_json_mapping(serialized, path="extensions")
+        object.__setattr__(self, "extensions", frozen_extensions)
+
+    def _validate_extension_model(self, model: builtins.type[BaseModel]) -> None:
+        serialized_names = {
+            field.serialization_alias or field.alias or name
+            for name, field in model.model_fields.items()
+        }
+        overlap = _RESERVED_MEMBERS.intersection(serialized_names)
+        if overlap:
+            names = ", ".join(sorted(overlap))
+            msg = f"extensions_model must not define reserved members: {names}"
+            raise ErrorConfigurationError(msg)
+
+    def _validate_headers(self) -> None:
+        headers: object = self.headers
+        openapi_headers: object = self.openapi_headers
+        if (
+            headers is not None
+            and not isinstance(headers, Mapping)
+            and not callable(headers)
+        ):
+            msg = "headers must be a mapping, callable, or None"
+            raise ErrorConfigurationError(msg)
+        if isinstance(headers, Mapping):
+            frozen_headers = freeze_headers(headers, path="headers")
+            object.__setattr__(self, "headers", frozen_headers)
+
+        if openapi_headers is not None:
+            if not isinstance(openapi_headers, Mapping):
+                msg = "openapi_headers must be a mapping or None"
+                raise ErrorConfigurationError(msg)
+            definitions: dict[str, OpenAPIHeader] = {}
+            for name, definition in openapi_headers.items():
+                header_name = _validate_header_name(name, path="openapi_headers")
+                if not isinstance(definition, Mapping):
+                    msg = f"openapi_headers.{header_name} must be a mapping"
+                    raise ErrorConfigurationError(msg)
+                definitions[header_name] = _freeze_json_mapping(
+                    definition, path=f"openapi_headers.{header_name}"
+                )
+            object.__setattr__(self, "openapi_headers", MappingProxyType(definitions))
+
+    def _validate_documentation(self) -> None:
+        description: object = self.description
+        schema_name: object = self.schema_name
+        example: object = self.example
+        if description is not None and not isinstance(description, str):
+            msg = "description must be a string or None"
+            raise ErrorConfigurationError(msg)
+        if schema_name is not None and (
+            not isinstance(schema_name, str) or not schema_name.strip()
+        ):
+            msg = "schema_name must be a non-empty string or None"
+            raise ErrorConfigurationError(msg)
+        if example is not None:
+            if not isinstance(example, Mapping):
+                msg = "example must be a mapping or None"
+                raise ErrorConfigurationError(msg)
+            object.__setattr__(
+                self,
+                "example",
+                _freeze_json_mapping(example, path="example"),
+            )
+
+
+def _freeze_json_mapping[KeyT, ValueT](
+    value: Mapping[KeyT, ValueT], *, path: str
+) -> Mapping[str, JsonValue]:
+    frozen: dict[str, JsonValue] = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            msg = f"{path} keys must be strings"
+            raise ErrorConfigurationError(msg)
+        frozen[key] = _freeze_json(item, path=f"{path}.{key}")
+    return MappingProxyType(frozen)
+
+
+def _freeze_json(value: object, *, path: str) -> JsonValue:
+    if value is None or isinstance(value, bool | int | str):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            msg = f"{path} must contain only finite JSON numbers"
+            raise ErrorConfigurationError(msg)
+        return value
+    if isinstance(value, list):
+        return cast(
+            JsonValue,
+            tuple(
+                _freeze_json(item, path=f"{path}[{index}]")
+                for index, item in enumerate(value)
+            ),
+        )
+    if isinstance(value, Mapping):
+        return cast(JsonValue, _freeze_json_mapping(value, path=path))
+    msg = f"{path} contains a non-JSON value of type {type(value).__name__}"
+    raise ErrorConfigurationError(msg)
+
+
+def freeze_headers[KeyT, ValueT](
+    value: Mapping[KeyT, ValueT], *, path: str
+) -> Mapping[str, str]:
+    """Validate response headers and return an immutable detached mapping."""
+    frozen: dict[str, str] = {}
+    for name, header_value in value.items():
+        header_name = _validate_header_name(name, path=path)
+        if not isinstance(header_value, str):
+            msg = f"{path}.{header_name} must be a string"
+            raise ErrorConfigurationError(msg)
+        frozen[header_name] = header_value
+    return MappingProxyType(frozen)
+
+
+def _validate_header_name(name: object, *, path: str) -> str:
+    if not isinstance(name, str) or _HEADER_NAME_PATTERN.fullmatch(name) is None:
+        msg = f"{path} contains an invalid HTTP header name"
+        raise ErrorConfigurationError(msg)
+    if name.lower() in _FORBIDDEN_RESPONSE_HEADERS:
+        msg = f"{path} must not define the managed response header {name!r}"
+        raise ErrorConfigurationError(msg)
+    return name

fastapi_canon/error/handlers.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from http import HTTPStatus
+from typing import TYPE_CHECKING, cast
+
+from fastapi import FastAPI, Request
+from fastapi.exception_handlers import (
+    http_exception_handler,
+    request_validation_exception_handler,
+)
+from fastapi.exceptions import RequestValidationError, ResponseValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+from starlette.responses import Response
+from starlette.types import ExceptionHandler
+
+from fastapi_canon.error.contracts import (
+    INSTALLED_REGISTRY_STATE_KEY,
+    iter_http_contracts,
+)
+from fastapi_canon.error.openapi import install_openapi
+from fastapi_canon.error.rendering import render_problem
+from fastapi_canon.error.types import ErrorConfigurationError, JsonValue
+
+if TYPE_CHECKING:
+    from fastapi_canon.error.registry import ErrorRegistry
+
+logger = logging.getLogger(__name__)
+
+
+def install_handlers(
+    registry: ErrorRegistry,
+    app: FastAPI,
+    *,
+    include_validation_error: bool,
+    include_http_exceptions: bool,
+    include_unhandled_error: bool,
+) -> None:
+    """Install handlers once while preserving user-owned handler conflicts."""
+    installed = getattr(app.state, INSTALLED_REGISTRY_STATE_KEY, None)
+    if installed is registry:
+        return
+    if installed is not None:
+        msg = "a different ErrorRegistry is already installed on this application"
+        raise ErrorConfigurationError(msg)
+    if app.openapi_schema is not None:
+        msg = "install ErrorRegistry before generating or caching OpenAPI"
+        raise ErrorConfigurationError(msg)
+
+    registry.require_resolved()
+    _validate_route_contracts(registry, app)
+    if (
+        include_validation_error or include_unhandled_error
+    ) and registry.type_base is None:
+        msg = (
+            "type_base is required when validation or unhandled-error normalization "
+            "is enabled"
+        )
+        raise ErrorConfigurationError(msg)
+
+    domain_classes = {
+        *(error.exception for error in registry.errors),
+    }
+    for exception_class in domain_classes:
+        _ensure_handler_available(app, exception_class)
+
+    domain_handler = _domain_handler(registry)
+    for exception_class in domain_classes:
+        app.add_exception_handler(exception_class, domain_handler)
+
+    if include_http_exceptions:
+        _ensure_default_or_available(app, HTTPException, http_exception_handler)
+        app.add_exception_handler(HTTPException, _http_exception_handler)
+    if include_validation_error:
+        _ensure_default_or_available(
+            app, RequestValidationError, request_validation_exception_handler
+        )
+        app.add_exception_handler(
+            RequestValidationError, _request_validation_handler(registry)
+        )
+        _ensure_handler_available(app, ResponseValidationError)
+        app.add_exception_handler(
+            ResponseValidationError, _response_validation_handler(registry)
+        )
+    if include_unhandled_error:
+        _ensure_handler_available(app, Exception)
+        app.add_exception_handler(Exception, _unhandled_handler(registry))
+
+    install_openapi(
+        registry,
+        app,
+        include_validation_error=include_validation_error,
+    )
+    setattr(app.state, INSTALLED_REGISTRY_STATE_KEY, registry)
+
+
+def _validate_route_contracts(registry: ErrorRegistry, app: FastAPI) -> None:
+    for http_route, http_errors in iter_http_contracts(app.router, registry):
+        for http_error in http_errors:
+            if not registry.contains(http_error):
+                msg = (
+                    f"route {http_route.path!r} declares error "
+                    f"{http_error.code!r}, but the "
+                    "installed registry does not contain that exact definition"
+                )
+                raise ErrorConfigurationError(msg)
+
+
+def _domain_handler(registry: ErrorRegistry) -> ExceptionHandler:
+    async def handler(connection: Request, exception: Exception) -> Response:
+        error = registry.resolve(exception)
+        if error is None:
+            raise exception
+        type_uri = registry.type_uri_for(error)
+        if type_uri is None:
+            msg = f"error {error.code!r} has no resolved problem type URI"
+            raise ErrorConfigurationError(msg)
+        try:
+            problem, headers = render_problem(error, exception, type_uri=type_uri)
+        except Exception:
+            logger.exception(
+                "Error rendering callback failed",
+                extra={
+                    "code": error.code,
+                    "exception_class": type(exception).__qualname__,
+                },
+            )
+            return _internal_error_response(registry)
+        return _problem_response(problem.as_dict(), error.status, headers=headers)
+
+    return cast(ExceptionHandler, handler)
+
+
+async def _http_exception_handler(request: Request, exception: Exception) -> Response:
+    del request
+    if not isinstance(exception, HTTPException):
+        raise exception
+    status = exception.status_code
+    try:
+        title = HTTPStatus(status).phrase
+    except ValueError:
+        title = "HTTP Error"
+    detail = exception.detail if isinstance(exception.detail, str) else None
+    payload: dict[str, JsonValue] = {
+        "type": "about:blank",
+        "title": title,
+        "status": status,
+        "code": f"http_{status}",
+    }
+    if detail is not None:
+        payload["detail"] = detail
+    return _problem_response(payload, status, headers=exception.headers)
+
+
+def _request_validation_handler(registry: ErrorRegistry) -> ExceptionHandler:
+    async def handler(request: Request, exception: Exception) -> Response:
+        del request
+        if not isinstance(exception, RequestValidationError):
+            raise exception
+        errors: list[JsonValue] = []
+        for error in exception.errors():
+            errors.append(_validation_error(error))
+        payload: dict[str, JsonValue] = {
+            "type": _builtin_type(registry, "request_validation_error"),
+            "title": "Request validation failed",
+            "status": 422,
+            "code": "request_validation_error",
+            "errors": errors,
+        }
+        return _problem_response(payload, 422)
+
+    return cast(ExceptionHandler, handler)
+
+
+def _response_validation_handler(registry: ErrorRegistry) -> ExceptionHandler:
+    async def handler(request: Request, exception: Exception) -> Response:
+        del request
+        if not isinstance(exception, ResponseValidationError):
+            raise exception
+        logger.error(
+            "FastAPI response validation failed",
+            exc_info=(type(exception), exception, exception.__traceback__),
+        )
+        return _internal_error_response(registry)
+
+    return cast(ExceptionHandler, handler)
+
+
+def _unhandled_handler(registry: ErrorRegistry) -> ExceptionHandler:
+    async def handler(request: Request, exception: Exception) -> Response:
+        del request
+        logger.error(
+            "Unhandled application exception",
+            exc_info=(type(exception), exception, exception.__traceback__),
+        )
+        return _internal_error_response(registry)
+
+    return cast(ExceptionHandler, handler)
+
+
+def _validation_error(error: dict[str, object]) -> JsonValue:
+    location = error.get("loc")
+    parts = tuple(location) if isinstance(location, tuple | list) else ()
+    source = parts[0] if parts else None
+    result: dict[str, JsonValue] = {
+        "code": str(error.get("type", "validation_error")),
+        "detail": str(error.get("msg", "Invalid input")),
+    }
+    if source == "body":
+        pointer = "#/" + "/".join(_escape_pointer(part) for part in parts[1:])
+        result["pointer"] = pointer.rstrip("/") or "#"
+    elif source in {"path", "query", "header", "cookie"} and len(parts) > 1:
+        result["parameter"] = str(parts[-1])
+        result["in"] = cast(str, source)
+    return result
+
+
+def _escape_pointer(value: object) -> str:
+    return str(value).replace("~", "~0").replace("/", "~1")
+
+
+def _internal_error_response(registry: ErrorRegistry) -> Response:
+    return _problem_response(
+        {
+            "type": _builtin_type(registry, "internal_server_error"),
+            "title": "Internal Server Error",
+            "status": 500,
+            "code": "internal_server_error",
+        },
+        500,
+    )
+
+
+def _builtin_type(registry: ErrorRegistry, code: str) -> str:
+    if registry.type_base is None:
+        msg = f"type_base is required to render built-in problem {code!r}"
+        raise ErrorConfigurationError(msg)
+    return f"{registry.type_base}/{code}"
+
+
+def _problem_response(
+    payload: dict[str, JsonValue],
+    status: int,
+    *,
+    headers: Mapping[str, str] | None = None,
+) -> Response:
+    return JSONResponse(
+        payload,
+        status_code=status,
+        headers=headers,
+        media_type="application/problem+json",
+    )
+
+
+def _ensure_handler_available(app: FastAPI, exception_class: type[Exception]) -> None:
+    if exception_class in app.exception_handlers:
+        msg = (
+            f"application already defines an exception handler for "
+            f"{exception_class.__qualname__}"
+        )
+        raise ErrorConfigurationError(msg)
+
+
+def _ensure_default_or_available(
+    app: FastAPI,
+    exception_class: type[Exception],
+    known_default: object,
+) -> None:
+    existing = app.exception_handlers.get(exception_class)
+    if existing is not None and existing is not known_default:
+        msg = (
+            f"application already defines an exception handler for "
+            f"{exception_class.__qualname__}"
+        )
+        raise ErrorConfigurationError(msg)