xtr-http-kernel 1.4.0__py3-none-any.whl

xtr_http_kernel/event_listener/log_unit_listener.py

@@ -0,0 +1,39 @@
+"""Each request framed as one unit of work for the logging package.
+
+This module needs the optional logging extra: it is deliberately left out of
+the package's eager re-exports, and the bundle registers the listener only
+when the logging bundle is active.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_logging import begin_unit, end_unit
+
+if TYPE_CHECKING:
+    from xtr_http_kernel.event import RequestEvent, TerminateEvent
+
+__all__ = ["LogUnitListener"]
+
+
+@final
+class LogUnitListener:
+    """Opens a unit of work when a request arrives, and closes it when all was sent.
+
+    State the logging package keeps per unit — the id tying a request's
+    records together, a fingers-crossed buffer — then lives exactly as long
+    as the request, and two requests handled at once keep their own.
+    """
+
+    __slots__ = ()
+
+    def on_request(self, event: RequestEvent) -> None:
+        """Open the request's unit, before anything else contributes."""
+        del event
+        begin_unit()
+
+    def on_terminate(self, event: TerminateEvent) -> None:
+        """Close the unit, after everything has been sent."""
+        del event
+        end_unit()

xtr_http_kernel/event_listener/request_id_listener.py

@@ -0,0 +1,72 @@
+"""Every request gets an id, and every response says which one it carried."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Final, final
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from xtr_logging_contracts import Context
+
+    from xtr_http_kernel.event import RequestEvent, ResponseEvent
+
+__all__ = ["RequestIdListener"]
+
+_VALID_REQUEST_ID: Final = re.compile(r"[A-Za-z0-9._-]{1,200}")
+"""What an incoming id may look like before it is worth keeping."""
+
+# Binding the id to the ambient log context is a courtesy to the logging
+# package, which is an optional extra: without it there is nothing to bind to
+# and the listener still does its job.
+_bind_context: Callable[[Context], None] | None
+try:
+    from xtr_logging import bind_context as _bind_context
+except ImportError:  # pragma: no cover — exercised only without the logging extra.
+    _bind_context = None
+
+
+@final
+class RequestIdListener:
+    """Keeps, or mints, one id per request, and echoes it on the response.
+
+    At the request: a well-formed incoming header is kept when trusted,
+    anything else is replaced with a fresh ``uuid4().hex``. The id is put on
+    ``request.state.request_id`` for whoever handles the request, and bound
+    to the ambient log context when the logging package is around, so every
+    record made while handling carries it.
+
+    At the response: the id goes out under the same header, so the caller
+    can quote it back.
+    """
+
+    __slots__ = ("_header", "_trust_incoming")
+
+    def __init__(self, header: str = "X-Request-Id", trust_incoming: bool = True) -> None:
+        """Read and write ``header``, keeping a valid incoming id when ``trust_incoming``."""
+        self._header = header
+        self._trust_incoming = trust_incoming
+
+    def on_request(self, event: RequestEvent) -> None:
+        """Settle the request's id before anything handles it."""
+        incoming = event.request.headers.get(self._header)
+        keep = (
+            self._trust_incoming and incoming is not None and _VALID_REQUEST_ID.fullmatch(incoming)
+        )
+        request_id = incoming if keep and incoming is not None else uuid4().hex
+        event.request.state.request_id = request_id
+        if _bind_context is not None:
+            _bind_context({"request_id": request_id})
+
+    def on_response(self, event: ResponseEvent) -> None:
+        """Echo the request's id on the outgoing head.
+
+        A listener answering at the request stops that event before this
+        listener's request half runs, so a response can start without an id
+        having been settled; such a response goes out unmarked.
+        """
+        request_id = getattr(event.request.state, "request_id", None)
+        if isinstance(request_id, str):
+            event.headers[self._header] = request_id

xtr_http_kernel/exception/__init__.py

@@ -0,0 +1,14 @@
+"""Every error this library raises.
+
+All of them derive from :class:`HttpKernelError`, so one ``except`` catches
+anything the request lifecycle can go wrong with, and a narrower one handles
+one cause. Each carries the data a caller needs as typed attributes rather
+than forcing a message to be parsed.
+"""
+
+from __future__ import annotations
+
+from .http_kernel_error import HttpKernelError
+from .invalid_middleware_priority_error import InvalidMiddlewarePriorityError
+
+__all__ = ["HttpKernelError", "InvalidMiddlewarePriorityError"]

xtr_http_kernel/exception/http_kernel_error.py

@@ -0,0 +1,15 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["HttpKernelError"]
+
+
+class HttpKernelError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything turning a request into a response can go
+    wrong with; catch a subclass to handle one cause. Every subclass carries
+    the data a caller needs as typed attributes and composes its own message
+    from them.
+    """

xtr_http_kernel/exception/invalid_middleware_priority_error.py

@@ -0,0 +1,39 @@
+"""Raised when a middleware tag carries a priority that is not an integer."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .http_kernel_error import HttpKernelError
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+__all__ = ["InvalidMiddlewarePriorityError"]
+
+
+class InvalidMiddlewarePriorityError(HttpKernelError):
+    """A ``http_kernel.middleware`` tag's ``priority`` attribute is not an integer.
+
+    Raised while the kernel is built, so a misdeclared bundle fails at
+    startup rather than serving an unordered chain.
+
+    Attributes:
+        key: The tagged service's ``(type, qualifier)`` key.
+        priority: What the tag carried instead of an integer.
+    """
+
+    key: tuple[type, Hashable | None]
+    priority: object
+
+    def __init__(self, key: tuple[type, Hashable | None], priority: object) -> None:
+        """Record the offending service key and what its tag carried."""
+        self.key = key
+        self.priority = priority
+        provided, qualifier = key
+        name = f"{provided.__module__}.{provided.__qualname__}"
+        service = name if qualifier is None else f"{name}[{qualifier!r}]"
+        super().__init__(
+            f"the http_kernel.middleware tag on {service} must carry an integer priority, "
+            f"not {priority!r}"
+        )

xtr_http_kernel/kernel_events.py

@@ -0,0 +1,51 @@
+"""The names the request lifecycle dispatches its events under."""
+
+from __future__ import annotations
+
+from typing import Final, final
+
+from xtr_event_dispatcher_contracts import event_name_of
+
+from .event import (
+    ExceptionEvent,
+    FinishRequestEvent,
+    RequestEvent,
+    ResponseEvent,
+    TerminateEvent,
+)
+
+__all__ = ["KernelEvents"]
+
+
+@final
+class KernelEvents:
+    """One name per lifecycle event, for listeners registered by name.
+
+    An event is keyed by the qualified name of its class, so a listener
+    declared on a typed parameter and one registered under the matching
+    constant here are registered for the same event. The constants exist for
+    the places a class cannot be written — a listener whose event is chosen
+    at runtime, a configuration file, a subscriber mapping names to methods:
+
+    ```python
+    dispatcher.add_listener(KernelEvents.RESPONSE, stamp_request_id, priority=100)
+    ```
+
+    Keeping them in one place also means the set of moments a request goes
+    through can be read at a glance, in the order it goes through them.
+    """
+
+    REQUEST: Final[str] = event_name_of(RequestEvent)
+    """The request arrived and nothing has handled it."""
+
+    RESPONSE: Final[str] = event_name_of(ResponseEvent)
+    """A response is about to start, and its head can still be changed."""
+
+    EXCEPTION: Final[str] = event_name_of(ExceptionEvent)
+    """Handling raised, and nothing has been sent."""
+
+    FINISH_REQUEST: Final[str] = event_name_of(FinishRequestEvent)
+    """Handling finished — dispatched on every path."""
+
+    TERMINATE: Final[str] = event_name_of(TerminateEvent)
+    """Everything has been sent, or the failure went past the lifecycle."""

xtr_http_kernel/middleware_stack.py

@@ -0,0 +1,52 @@
+"""An ordered, immutable chain of middleware factories, ready to wrap an app.
+
+The http_kernel bundle builds one when the kernel is compiled: every
+definition tagged ``http_kernel.middleware`` contributes a factory, ordered
+by the tag's ``priority`` — highest first, so it wraps outermost and sees
+the request first. The setup call fetches the stack once per application
+life; the middleware it added composes the stack over the application.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Iterator
+
+    from starlette.types import ASGIApp
+
+    MiddlewareFactory = Callable[[ASGIApp], ASGIApp]
+
+__all__ = ["MiddlewareStack"]
+
+
+@final
+class MiddlewareStack:
+    """The middleware factories a kernel contributed, the outermost first.
+
+    Immutable: built once when the kernel is compiled, composed as many
+    times as the serving code asks.
+    """
+
+    __slots__ = ("_factories",)
+
+    def __init__(self, factories: Iterable[MiddlewareFactory] = ()) -> None:
+        """Hold ``factories`` in the given order — the outermost first."""
+        self._factories = tuple(factories)
+
+    def wrap(self, app: ASGIApp) -> ASGIApp:
+        """Return ``app`` wrapped in every factory, the first one outermost."""
+        wrapped = app
+        # The first factory sits outermost, so it wraps last.
+        for factory in reversed(self._factories):
+            wrapped = factory(wrapped)
+        return wrapped
+
+    def __len__(self) -> int:
+        """Return how many factories the stack holds."""
+        return len(self._factories)
+
+    def __iter__(self) -> Iterator[MiddlewareFactory]:
+        """Yield the factories, the outermost first."""
+        return iter(self._factories)

xtr_http_kernel/middleware_tag.py

@@ -0,0 +1,19 @@
+"""The tag a bundle puts on the middleware factories it contributes.
+
+A definition tagged this way provides a middleware factory — a callable
+taking the downstream ASGI app and returning the app wrapped. The
+http_kernel bundle collects every tagged definition when the kernel is
+built and orders them into the
+:class:`~xtr_http_kernel.middleware_stack.MiddlewareStack` by the tag's
+integer ``priority`` attribute (0 when absent): the highest priority sits
+outermost, so it sees the request first.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = ["MIDDLEWARE_TAG"]
+
+MIDDLEWARE_TAG: Final = "http_kernel.middleware"
+"""The tag name bundles and the setup call agree on."""

xtr_http_kernel/request_lifecycle_middleware.py

@@ -0,0 +1,182 @@
+"""Dispatches the request lifecycle events around whatever application it wraps."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, cast, final, runtime_checkable
+
+from starlette.datastructures import MutableHeaders
+from starlette.requests import Request
+
+from .event import (
+    ExceptionEvent,
+    FinishRequestEvent,
+    RequestEvent,
+    ResponseEvent,
+    TerminateEvent,
+)
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+    from xtr_event_dispatcher_contracts import EventDispatcherInterface
+
+__all__ = ["RequestLifecycleMiddleware"]
+
+_SERVER_ERROR = 500
+
+
+@runtime_checkable
+class _UnitScopedDispatcher(Protocol):
+    """What a dispatcher recording per unit of work offers on top of dispatching."""
+
+    def begin_unit(self) -> None: ...
+
+    def end_unit(self) -> None: ...
+
+
+@final
+class _Lifecycle:
+    """One request's passage: a ``send`` that dispatches around what leaves.
+
+    The middleware and the responses a listener answers with all send through
+    this one wrapper, so the sending rules live in one place: the response
+    start is announced (and adjusted) before it leaves, handling is declared
+    finished before the last body chunk leaves, and each announcement happens
+    at most once however the request went.
+    """
+
+    __slots__ = ("_dispatcher", "_finished", "_request", "_send", "_status_sent")
+
+    def __init__(self, dispatcher: EventDispatcherInterface, request: Request, send: Send) -> None:
+        self._dispatcher = dispatcher
+        self._request = request
+        self._send = send
+        self._status_sent: int | None = None
+        self._finished = False
+
+    @property
+    def request(self) -> Request:
+        return self._request
+
+    @property
+    def response_started(self) -> bool:
+        return self._status_sent is not None
+
+    @property
+    def status_sent(self) -> int:
+        """The status that left, or 500 when the response never started."""
+        return self._status_sent if self._status_sent is not None else _SERVER_ERROR
+
+    async def send(self, message: Message) -> None:
+        message_type = cast("str", message["type"])
+        if message_type == "http.response.start" and self._status_sent is None:
+            event = ResponseEvent(
+                self._request,
+                cast("int", message["status"]),
+                # The message's own header list, so what a listener writes is
+                # what leaves.
+                MutableHeaders(scope=message),
+            )
+            _ = await self._dispatcher.dispatch(event)
+            message["status"] = event.status_code
+            self._status_sent = event.status_code
+        elif message_type == "http.response.body" and not cast(
+            "bool", message.get("more_body", False)
+        ):
+            await self.finish()
+        await self._send(message)
+
+    async def finish(self) -> None:
+        """Declare handling finished, the first time this is asked for."""
+        if not self._finished:
+            self._finished = True
+            _ = await self._dispatcher.dispatch(FinishRequestEvent(self._request))
+
+
+@final
+class RequestLifecycleMiddleware:
+    """Announces each moment of a request's life to whoever listens.
+
+    Sits between the server and the application as plain middleware — built
+    from an application and a dispatcher, nothing else — so a framework
+    registers it the way it registers any other:
+
+    ```python
+    app.add_middleware(RequestLifecycleMiddleware, dispatcher=dispatcher)
+    ```
+
+    Every request then goes through the same sequence, whatever becomes of
+    it: :class:`~xtr_http_kernel.event.request_event.RequestEvent` before the
+    application sees it (a listener answering there skips the application),
+    :class:`~xtr_http_kernel.event.response_event.ResponseEvent` before the
+    response start leaves,
+    :class:`~xtr_http_kernel.event.exception_event.ExceptionEvent` when
+    handling raised (a listener answering there swallows the failure, unless
+    the response already started),
+    :class:`~xtr_http_kernel.event.finish_request_event.FinishRequestEvent`
+    before the last body chunk leaves — or before an unanswered failure
+    propagates — and
+    :class:`~xtr_http_kernel.event.terminate_event.TerminateEvent` last, with
+    the status that was sent. Each event at most once per request.
+
+    A failure nobody answered propagates as it arrived: turning it into a
+    response is the application's business, not this middleware's. Only the
+    lifespan of the application and its websockets pass through untouched —
+    they are not requests.
+
+    When the dispatcher records per unit of work — it offers callable
+    ``begin_unit`` and ``end_unit`` — each request is framed as one unit, so
+    overlapping requests each trace only their own events.
+    """
+
+    __slots__ = ("_app", "_dispatcher")
+
+    def __init__(self, app: ASGIApp, *, dispatcher: EventDispatcherInterface) -> None:
+        """Wrap ``app``, announcing every request to ``dispatcher``'s listeners."""
+        self._app = app
+        self._dispatcher = dispatcher
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Carry one connection through, dispatching the lifecycle when it is a request."""
+        if cast("str", scope["type"]) != "http":
+            await self._app(scope, receive, send)
+            return
+
+        lifecycle = _Lifecycle(self._dispatcher, Request(scope, receive), send)
+        unit = (
+            self._dispatcher
+            if isinstance(self._dispatcher, _UnitScopedDispatcher)
+            and callable(self._dispatcher.begin_unit)
+            and callable(self._dispatcher.end_unit)
+            else None
+        )
+        if unit is not None:
+            unit.begin_unit()
+        try:
+            await self._handle(scope, receive, lifecycle)
+        finally:
+            try:
+                _ = await self._dispatcher.dispatch(
+                    TerminateEvent(lifecycle.request, lifecycle.status_sent)
+                )
+            finally:
+                if unit is not None:
+                    unit.end_unit()
+
+    async def _handle(self, scope: Scope, receive: Receive, lifecycle: _Lifecycle) -> None:
+        request_event = RequestEvent(lifecycle.request)
+        _ = await self._dispatcher.dispatch(request_event)
+        answer = request_event.response
+        if answer is not None:
+            await answer(scope, receive, lifecycle.send)
+            return
+        try:
+            await self._app(scope, receive, lifecycle.send)
+        except BaseException as error:
+            exception_event = ExceptionEvent(lifecycle.request, error)
+            _ = await self._dispatcher.dispatch(exception_event)
+            answer = exception_event.response
+            if answer is not None and not lifecycle.response_started:
+                await answer(scope, receive, lifecycle.send)
+                return
+            await lifecycle.finish()
+            raise

xtr_http_kernel/setup.py

@@ -0,0 +1,96 @@
+"""Serving a FastAPI application from a kernel: the one public setup call.
+
+``setup(app, kernel)`` is everything an application calls. It wraps the
+application's lifespan so every application life builds, boots and shuts
+down its own kernel, and adds one middleware so every request runs inside
+the scope its scoped services live in. Call it before the first request —
+after the routes and the application's other middleware is fine. An
+application that already started refuses new middleware; the framework's
+own error surfaces then.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, cast
+
+from xtr_dependency_injection.integration.fastapi import attach, detach, request_scope
+from xtr_dependency_injection.testing import apply_overrides
+
+from ._kernel_middleware import KernelMiddleware
+from ._state import OVERRIDES_KEY, STACK_KEY
+from .middleware_stack import MiddlewareStack
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Hashable, Mapping
+
+    from fastapi import FastAPI
+    from starlette.types import Lifespan
+    from xtr_dependency_injection import Kernel
+    from xtr_dependency_injection.kernel.compiled_kernel import CompiledKernel
+
+__all__ = ["setup"]
+
+
+def setup(app: FastAPI, kernel: Kernel) -> None:
+    """Serve ``app`` from ``kernel``.
+
+    Nothing is built here: every start of the application's lifespan builds
+    the kernel afresh — a built container boots exactly once, and a test
+    starts the application many times — applies the overrides
+    :func:`xtr_http_kernel.testing.override_services` parked on the
+    application, boots, and attaches the kernel so the injection markers
+    resolve. The application's own lifespan runs inside, its state passing
+    through untouched. On the way out the kernel is detached and shut down.
+
+    Each life also fetches the :class:`~xtr_http_kernel.middleware_stack.MiddlewareStack`
+    the kernel's bundles contributed — ordered when the kernel was built,
+    highest tag ``priority`` outermost — as the chain every request runs
+    through, inside the one middleware this call adds, so the whole chain
+    sees the request's scope. A kernel without the http_kernel bundle
+    serves with an empty stack.
+
+    Args:
+        app: The application to serve, its routes and middleware already
+            registered.
+        kernel: The recipe to build each application life from.
+    """
+    app.router.lifespan_context = _serving_lifespan(app, kernel, app.router.lifespan_context)
+    app.add_middleware(KernelMiddleware, open_scope=request_scope)
+
+
+def _serving_lifespan(app: FastAPI, kernel: Kernel, inner: Lifespan[FastAPI]) -> Lifespan[FastAPI]:
+    """Return ``inner`` wrapped in one kernel life per application life."""
+
+    @asynccontextmanager
+    async def serving(target: FastAPI) -> AsyncGenerator[Mapping[str, object] | None, None]:
+        compiled = kernel.build()
+        overrides = cast(
+            "Mapping[type | tuple[type, Hashable], object] | None",
+            getattr(app.state, OVERRIDES_KEY, None),
+        )
+        if overrides is not None:
+            apply_overrides(compiled, overrides)
+        async with compiled.lifespan(app):
+            attach(app, compiled)
+            try:
+                setattr(app.state, STACK_KEY, await _stack(compiled))
+                async with inner(target) as state:
+                    yield state
+            finally:
+                if hasattr(app.state, STACK_KEY):
+                    delattr(app.state, STACK_KEY)
+                detach(app)
+
+    # The wrapper yields whatever the application's own lifespan yields;
+    # the framework's lifespan type is a union of the two shapes, not a
+    # context manager of the union.
+    return cast("Lifespan[FastAPI]", serving)
+
+
+async def _stack(compiled: CompiledKernel) -> MiddlewareStack:
+    """Return the kernel's middleware stack, empty when none was registered."""
+    container = compiled.container
+    if container.has(MiddlewareStack):
+        return await container.get(MiddlewareStack)
+    return MiddlewareStack()

xtr_http_kernel/testing.py

@@ -0,0 +1,52 @@
+"""Swapping services in a served application, for the span of a test.
+
+The setup call builds a kernel at every start of the application's
+lifespan; :func:`override_services` parks a mapping on the application for
+those builds to apply, so every boot hook and every route already sees the
+replacements. Enter the block before starting the application's lifespan.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from ._state import OVERRIDES_KEY
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Hashable, Mapping
+
+    from fastapi import FastAPI
+
+__all__ = ["override_services"]
+
+
+@contextmanager
+def override_services(
+    app: FastAPI,
+    overrides: Mapping[type | tuple[type, Hashable], object],
+    /,
+) -> Generator[None, None, None]:
+    """Serve ``app`` with ``overrides`` while the block is entered.
+
+    A key is a type, or a ``(type, qualifier)`` pair for a qualified
+    service — the same keys ``apply_overrides`` takes. The mapping applies
+    to every kernel built while the block is entered; on exit the previous
+    overrides, if any, are restored::
+
+        with override_services(app, {Mailer: FakeMailer()}):
+            ...  # every application life started here sees the fake
+
+    Args:
+        app: The application the setup call serves.
+        overrides: What to replace, keyed by type or ``(type, qualifier)``.
+    """
+    previous: object = getattr(app.state, OVERRIDES_KEY, None)
+    setattr(app.state, OVERRIDES_KEY, dict(overrides))
+    try:
+        yield
+    finally:
+        if previous is None:
+            delattr(app.state, OVERRIDES_KEY)
+        else:
+            setattr(app.state, OVERRIDES_KEY, previous)