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

xtr_http_kernel/__init__.py

@@ -0,0 +1,52 @@
+"""Requests turned into responses through events: a request lifecycle for web applications.
+
+A web framework routes a request to the function that answers it. Everything
+an application wants around that function — a request id on every response,
+an uncaught exception written to the log with the request that caused it, a
+header that keeps a page out of a search index — is not the endpoint's
+business, and does not belong in each of them.
+
+This library puts those between the framework and the endpoint as *events*:
+a request announces itself, the response it produced announces itself, and
+whoever listens contributes. Listeners come from the container, so they are
+services like any other.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .event import (
+    ExceptionEvent,
+    FinishRequestEvent,
+    RequestEvent,
+    ResponseEvent,
+    TerminateEvent,
+)
+from .exception import HttpKernelError
+from .kernel_events import KernelEvents
+from .middleware_stack import MiddlewareStack
+from .middleware_tag import MIDDLEWARE_TAG
+from .request_lifecycle_middleware import RequestLifecycleMiddleware
+from .setup import setup
+
+try:
+    __version__ = version("xtr-http-kernel")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "MIDDLEWARE_TAG",
+    "ExceptionEvent",
+    "FinishRequestEvent",
+    "HttpKernelError",
+    "KernelEvents",
+    "MiddlewareStack",
+    "RequestEvent",
+    "RequestLifecycleMiddleware",
+    "ResponseEvent",
+    "TerminateEvent",
+    "__version__",
+    "setup",
+]

xtr_http_kernel/_kernel_middleware.py

@@ -0,0 +1,76 @@
+"""The one middleware the setup call adds: a container scope around each request.
+
+Plain ASGI on purpose — no base class dispatch, no response buffering — so
+the scope opens before anything downstream runs and closes only when the
+downstream returned, which is after the response's last chunk left. The
+scope opener arrives through the constructor rather than an import, so this
+module stays free of the container layer.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, cast, final
+
+from ._state import STACK_KEY
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from contextlib import AbstractAsyncContextManager
+
+    from starlette.applications import Starlette
+    from starlette.types import ASGIApp, Receive, Scope, Send
+
+    from .middleware_stack import MiddlewareStack
+
+    ScopeOpener = Callable[[Starlette], AbstractAsyncContextManager[None]]
+
+__all__ = ["KernelMiddleware"]
+
+_SCOPED_TYPES: Final = frozenset({"http", "websocket"})
+
+
+@final
+class KernelMiddleware:
+    """Runs each connection inside the scope its scoped services live in.
+
+    ``http`` and ``websocket`` connections run through the middleware stack
+    the application's current life parked on its state — composed over the
+    downstream app — with the scope open around the whole of it, so a
+    scoped service lives until the response has been sent. The scope closes
+    on every path, a failing downstream included; the failure still
+    propagates. The ``lifespan`` connection passes through untouched.
+    """
+
+    __slots__ = ("_app", "_chain", "_open_scope", "_stack")
+
+    def __init__(self, app: ASGIApp, *, open_scope: ScopeOpener) -> None:
+        """Wrap ``app``, opening scopes through ``open_scope``."""
+        self._app = app
+        self._open_scope = open_scope
+        self._stack: MiddlewareStack | None = None
+        self._chain: ASGIApp = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Carry one connection through, scoped when it is a request."""
+        if cast("str", scope["type"]) not in _SCOPED_TYPES:
+            await self._app(scope, receive, send)
+            return
+        application = cast("Starlette", scope["app"])
+        chain = self._composed(application)
+        async with self._open_scope(application):
+            await chain(scope, receive, send)
+
+    def _composed(self, application: Starlette) -> ASGIApp:
+        """Return the chain for the application's current life, composed once.
+
+        The stack is frozen per application life, so its identity tells
+        whether the cached chain still stands.
+        """
+        stack = cast(
+            "MiddlewareStack | None",
+            getattr(application.state, STACK_KEY, None),
+        )
+        if stack is not self._stack:
+            self._stack = stack
+            self._chain = self._app if stack is None else stack.wrap(self._app)
+        return self._chain

xtr_http_kernel/_state.py

@@ -0,0 +1,17 @@
+"""Where the setup call, its middleware and the test seam meet: the app's state.
+
+Kept apart so the middleware module shares these keys with the setup and
+testing modules without importing either.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = ["OVERRIDES_KEY", "STACK_KEY"]
+
+STACK_KEY: Final = "_xtr_http_kernel_middleware"
+"""Where each application life parks the kernel's middleware stack."""
+
+OVERRIDES_KEY: Final = "_xtr_http_kernel_overrides"
+"""Where :func:`xtr_http_kernel.testing.override_services` parks its mapping."""

xtr_http_kernel/bundle/__init__.py

@@ -0,0 +1,8 @@
+"""The xtr-dependency-injection bundle for xtr-http-kernel."""
+
+from __future__ import annotations
+
+from .http_kernel_bundle import HttpKernelBundle
+from .http_kernel_config import HttpKernelConfig
+
+__all__ = ["HttpKernelBundle", "HttpKernelConfig"]

xtr_http_kernel/bundle/http_kernel_bundle.py

@@ -0,0 +1,211 @@
+"""The xtr-http-kernel bundle: the request lifecycle, under the container.
+
+The bundle is the integration, never the library: an application drives the
+lifecycle itself with :func:`xtr_http_kernel.setup`, and lists this bundle so
+the container owns the pieces the lifecycle reaches for — the middleware
+factory the setup call composes, and the listeners that give every request
+an id, a log record on failure and a unit of work of its own.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, cast, final
+
+from typing_extensions import override
+
+# ServiceKey stays a runtime import: it annotates a factory parameter the
+# container evaluates when the definitions are emitted.
+from xtr_dependency_injection import (
+    Bundle,
+    ServiceKey,
+    as_bundle,
+    bundle_active,
+    required_bundle,
+)
+from xtr_event_dispatcher.bundle import EventDispatcherBundle
+
+# Read at runtime: the container fills factory parameters from annotations.
+from xtr_logging_contracts import LoggerInterface
+from xtr_service_contracts import ContainerInterface  # noqa: TC002 — read at runtime, as above
+
+from xtr_http_kernel.event import ExceptionEvent, RequestEvent, ResponseEvent, TerminateEvent
+from xtr_http_kernel.event_listener import (
+    DisallowRobotsIndexingListener,
+    ErrorLoggingListener,
+    RequestIdListener,
+)
+from xtr_http_kernel.exception import InvalidMiddlewarePriorityError
+from xtr_http_kernel.middleware_stack import MiddlewareStack
+from xtr_http_kernel.middleware_tag import MIDDLEWARE_TAG
+
+from .http_kernel_config import HttpKernelConfig
+from .request_lifecycle_middleware_factory import RequestLifecycleMiddlewareFactory
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+
+    from xtr_dependency_injection import ContainerBuilder, ServiceConfigurator
+
+    from xtr_http_kernel.middleware_stack import MiddlewareFactory
+
+__all__ = ["HttpKernelBundle"]
+
+_LISTENER_TAG: Final = "event_dispatcher.listener"
+"""The tag the event dispatcher bundle reads listeners from."""
+
+# The unit of work opens before anything else contributes and closes after
+# everything else has heard the terminate; the request id settles right after
+# the unit opens, so every record made while handling carries it.
+_UNIT_OPEN_PRIORITY: Final = 8192
+_REQUEST_ID_PRIORITY: Final = 4096
+_UNIT_CLOSE_PRIORITY: Final = -8192
+
+
+@final
+@required_bundle(EventDispatcherBundle)
+@required_bundle("xtr_logging.bundle:LoggingBundle", ignore_on_invalid=True)
+@required_bundle("xtr_console.bundle:ConsoleBundle", ignore_on_invalid=True)
+@as_bundle("http_kernel", config=HttpKernelConfig)
+class HttpKernelBundle(Bundle[HttpKernelConfig]):
+    """Puts the request lifecycle's services under the container."""
+
+    @override
+    def prepend_extension(self, builder: ContainerBuilder) -> None:
+        """When ``logging`` is active, declare the default request channel on its config.
+
+        The channel name here is the config default: this bundle's own config
+        resolves after logging's, so a renamed channel is declared by the
+        application in its logging configuration instead.
+        """
+        if bundle_active(builder, "logging"):
+            builder.prepend_extension_config("logging", _add_request_channel)
+
+    @override
+    def load_extension(
+        self,
+        config: HttpKernelConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register the middleware factory, the listeners and the commands from ``config``.
+
+        The listeners that write to a log join only when the logging bundle
+        is active, and the router commands only when a console bundle is —
+        loading their module late keeps the console dependency out of the
+        graph of an application that never runs one.
+        """
+        _ = services.set(RequestLifecycleMiddlewareFactory).add_tag(
+            MIDDLEWARE_TAG, priority=config.middleware_priority
+        )
+        _ = services.set(_middleware_stack).set_argument("keys", ())
+        _ = (
+            services.set(RequestIdListener)
+            .set_argument("header", config.request_id_header)
+            .set_argument("trust_incoming", config.trust_request_id)
+            .add_tag(
+                _LISTENER_TAG,
+                event=RequestEvent,
+                method="on_request",
+                priority=_REQUEST_ID_PRIORITY,
+            )
+            .add_tag(_LISTENER_TAG, event=ResponseEvent, method="on_response")
+        )
+        _ = (
+            services.set(DisallowRobotsIndexingListener)
+            .set_argument("enabled", config.disallow_search_indexing)
+            .add_tag(_LISTENER_TAG, event=ResponseEvent, method="on_response")
+        )
+        if bundle_active(builder, "logging"):
+            # Needs the optional logging extra, which being here proves installed.
+            from xtr_http_kernel.event_listener.log_unit_listener import (  # noqa: PLC0415
+                LogUnitListener,
+            )
+
+            _ = (
+                services.set(LogUnitListener)
+                .add_tag(
+                    _LISTENER_TAG,
+                    event=RequestEvent,
+                    method="on_request",
+                    priority=_UNIT_OPEN_PRIORITY,
+                )
+                .add_tag(
+                    _LISTENER_TAG,
+                    event=TerminateEvent,
+                    method="on_terminate",
+                    priority=_UNIT_CLOSE_PRIORITY,
+                )
+            )
+            _ = services.set(_error_logging_listener(config.log_channel)).add_tag(
+                _LISTENER_TAG, event=ExceptionEvent, method="on_exception"
+            )
+        if bundle_active(builder, "console"):
+            services.load("xtr_http_kernel.command")
+
+    @override
+    def process(self, builder: ContainerBuilder) -> None:
+        """Order every tagged middleware into the stack, highest priority outermost.
+
+        Runs after every bundle loaded, so the builder holds every tag. The
+        tag's ``priority`` attribute is 0 when absent; ties keep
+        registration order.
+
+        Raises:
+            InvalidMiddlewarePriorityError: If a tag's ``priority`` is not
+                an integer.
+        """
+        entries: list[tuple[int, int, ServiceKey]] = []
+        for order, (key, attributes) in enumerate(
+            builder.find_tagged_service_ids(MIDDLEWARE_TAG).items()
+        ):
+            priority = attributes[0].get("priority", 0)
+            if not isinstance(priority, int):
+                raise InvalidMiddlewarePriorityError(key, priority)
+            entries.append((priority, order, key))
+        entries.sort(key=lambda entry: (-entry[0], entry[1]))
+        _ = builder.get_definition(MiddlewareStack).set_argument(
+            "keys", tuple(key for _, _, key in entries)
+        )
+
+
+async def _middleware_stack(
+    container: ContainerInterface, keys: tuple[ServiceKey, ...]
+) -> MiddlewareStack:
+    """Build the stack by resolving each ordered key through ``container``.
+
+    ``keys`` comes from the bundle's ``process`` hook: the tagged
+    definitions, already ordered highest priority first.
+    """
+    factories = [
+        cast("MiddlewareFactory", await container.get(provided, qualifier))
+        for provided, qualifier in keys
+    ]
+    return MiddlewareStack(factories)
+
+
+def _error_logging_listener(
+    channel: str,
+) -> Callable[[ContainerInterface], Coroutine[object, object, ErrorLoggingListener]]:
+    """Build the factory giving the error listener the ``channel`` logger.
+
+    The channel comes from this bundle's config, so it cannot sit in an
+    annotation the way a constant channel could: the factory asks the
+    container at build time instead.
+    """
+
+    async def error_logging_listener(container: ContainerInterface) -> ErrorLoggingListener:
+        return ErrorLoggingListener(await container.get(LoggerInterface, channel))
+
+    return error_logging_listener
+
+
+def _add_request_channel(config: object) -> object:
+    """Declare the default channel through the logging config's own ``with_channels``.
+
+    Duck-typed: this bundle depends on the logging contracts only, never on
+    xtr-logging, so it asks the config it is handed rather than importing
+    its type.
+    """
+    with_channels = cast("Callable[[str], object] | None", getattr(config, "with_channels", None))
+    default_channel = HttpKernelConfig().log_channel
+    return with_channels(default_channel) if with_channels is not None else config

xtr_http_kernel/bundle/http_kernel_config.py

@@ -0,0 +1,62 @@
+"""Configuration for :class:`~xtr_http_kernel.bundle.http_kernel_bundle.HttpKernelBundle`."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = ["HttpKernelConfig"]
+
+_HTTP_TOKEN: Final = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+"""What a header field name may be made of."""
+
+
+@dataclass(frozen=True, slots=True)
+class HttpKernelConfig:
+    """What an application may change about the request lifecycle.
+
+    Attributes:
+        request_id_header: The header the request id is read from and echoed
+            on. Must be a non-empty HTTP token.
+        trust_request_id: Whether a well-formed incoming id is kept. When
+            false every request gets a fresh one.
+        disallow_search_indexing: Whether every response is marked
+            ``X-Robots-Tag: noindex``.
+        log_channel: The logging channel the error listener writes to. The
+            bundle declares the default channel on the logging config; an
+            application choosing another name declares that channel in its
+            own logging configuration.
+        middleware_priority: Where the lifecycle middleware sits among the
+            contributed factories — highest outermost.
+        app: The ``"package.module:app"`` import string the console commands
+            load the application from, when they need one.
+
+    Raises:
+        ValueError: When ``request_id_header`` is not an HTTP token,
+            ``log_channel`` is empty, or ``app`` does not hold exactly one
+            module and one attribute around a single ``:``.
+    """
+
+    request_id_header: str = "X-Request-Id"
+    trust_request_id: bool = True
+    disallow_search_indexing: bool = False
+    log_channel: str = "request"
+    middleware_priority: int = 0
+    app: str | None = None
+
+    def __post_init__(self) -> None:
+        """Refuse values the lifecycle would silently misread."""
+        if not _HTTP_TOKEN.fullmatch(self.request_id_header):
+            message = (
+                f"request_id_header must be a non-empty HTTP token, not {self.request_id_header!r}"
+            )
+            raise ValueError(message)
+        if not self.log_channel:
+            message = "log_channel must not be empty"
+            raise ValueError(message)
+        if self.app is not None:
+            module, separator, attribute = self.app.partition(":")
+            if not (module and separator and attribute) or ":" in attribute:
+                message = f'app must read "package.module:app", not {self.app!r}'
+                raise ValueError(message)

xtr_http_kernel/bundle/request_lifecycle_middleware_factory.py

@@ -0,0 +1,35 @@
+"""The middleware factory the bundle tags for the kernel to order into the stack."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+# Read at runtime: the container fills the constructor from this annotation.
+from xtr_event_dispatcher_contracts import EventDispatcherInterface  # noqa: TC002
+
+from xtr_http_kernel.request_lifecycle_middleware import RequestLifecycleMiddleware
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp
+
+__all__ = ["RequestLifecycleMiddlewareFactory"]
+
+
+@final
+class RequestLifecycleMiddlewareFactory:
+    """Wraps a downstream app in the lifecycle middleware, around the container's dispatcher.
+
+    Tagged ``http_kernel.middleware`` with the config's
+    ``middleware_priority`` as the tag's ``priority``, so the bundle orders
+    it into the stack when the kernel is built — highest outermost.
+    """
+
+    __slots__ = ("_dispatcher",)
+
+    def __init__(self, dispatcher: EventDispatcherInterface) -> None:
+        """Hand ``dispatcher`` to every middleware built."""
+        self._dispatcher = dispatcher
+
+    def __call__(self, app: ASGIApp) -> ASGIApp:
+        """Return ``app`` wrapped in the lifecycle middleware."""
+        return RequestLifecycleMiddleware(app, dispatcher=self._dispatcher)

xtr_http_kernel/command/__init__.py

@@ -0,0 +1,9 @@
+"""Console commands the http kernel bundle contributes when a console is active."""
+
+from __future__ import annotations
+
+from .debug_router_command import DebugRouterCommand
+from .route_description import RouteDescription
+from .router_match_command import RouterMatchCommand
+
+__all__ = ["DebugRouterCommand", "RouteDescription", "RouterMatchCommand"]

xtr_http_kernel/command/_route_contexts.py

@@ -0,0 +1,113 @@
+"""One view of an application's routes, whichever way the framework hands them over.
+
+Newer releases keep a router included under a prefix as a wrapper around that
+router rather than as the routes it holds, and offer the effective view of
+every route — prefixes applied — through ``iter_route_contexts``. Older ones
+put each route in the list directly, already effective. This module is the
+only place that difference lives.
+
+A release that grew the wrapper before it grew the view of one lists an
+included router as the single opaque route the application holds: there is no
+supported way in, so the row names the wrapper for what it is rather than
+inventing a path for it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, cast, final
+
+from fastapi import routing as fastapi_routing
+from starlette.routing import Host, Mount, Route, WebSocketRoute
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+
+    from fastapi.routing import RouteContext
+    from starlette.routing import BaseRoute, Match
+    from starlette.types import Scope
+
+__all__ = ["RouteView", "route_contexts"]
+
+
+class _Matcher(Protocol):
+    """What answers whether a request reaches a route."""
+
+    def matches(self, scope: Scope, /) -> tuple[Match, Scope]:
+        """Return how well ``scope`` fits, and what the route reads out of it."""
+        ...
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class RouteView:
+    """What routing sees for one route, every prefix already applied.
+
+    Attributes:
+        route: The route itself, for what only its kind can answer.
+        path: The path requests are matched against, ``None`` for a route the
+            framework keeps to itself.
+        name: The name the route answers to, ``None`` when it has none.
+        methods: The methods it answers, ``None`` when it takes whatever
+            arrives or is not a method route at all.
+        endpoint: What it hands the request to, ``None`` when it hands it to
+            another application instead.
+        matcher: What answers :meth:`matches` — the framework's own view of
+            the route, or the route itself.
+    """
+
+    route: BaseRoute
+    path: str | None
+    name: str | None
+    methods: set[str] | None
+    endpoint: object | None
+    matcher: object
+
+    def matches(self, scope: Scope) -> tuple[Match, Scope]:
+        """Return how well ``scope`` fits this route, and what it reads out of it.
+
+        The framework's own view of a route stands in for it and forwards what
+        it is asked for, so it answers this without declaring it; the hop
+        through ``object`` is what says the shape is known rather than guessed.
+        """
+        return cast("_Matcher", self.matcher).matches(scope)
+
+
+def route_contexts(routes: Sequence[BaseRoute]) -> Sequence[RouteView]:
+    """Read every route of an application, prefixes applied.
+
+    A release offering the effective view of each route is asked for it; the
+    rest hand their routes over already effective.
+    """
+    effective = cast(
+        "Callable[[Sequence[BaseRoute]], Iterable[RouteContext]] | None",
+        getattr(fastapi_routing, "iter_route_contexts", None),
+    )
+    if effective is None:
+        return [_of_route(route) for route in routes]
+    return [_of_context(context) for context in effective(routes)]
+
+
+def _of_context(context: RouteContext) -> RouteView:
+    """Read the framework's own view of a route."""
+    return RouteView(
+        route=context.route,
+        path=context.path,
+        name=context.name,
+        methods=context.methods,
+        endpoint=context.endpoint,
+        matcher=context,
+    )
+
+
+def _of_route(route: BaseRoute) -> RouteView:
+    """Read a route a release hands over already effective.
+
+    Each line below names the kinds of route that can answer that much; a kind
+    that answers none of it is left to be named by itself.
+    """
+    methods = route.methods if isinstance(route, Route) else None
+    endpoint = route.endpoint if isinstance(route, (Route, WebSocketRoute)) else None
+    path = route.path if isinstance(route, (Mount, Route, WebSocketRoute)) else None
+    name = route.name if isinstance(route, (Host, Mount, Route, WebSocketRoute)) else None
+    return RouteView(route, path, name, methods, endpoint, route)

xtr_http_kernel/command/debug_router_command.py

@@ -0,0 +1,52 @@
+"""``debug:router``: every route of an application, as routing reads them."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from ._route_contexts import route_contexts
+from .route_description import RouteDescription
+from .router_command import RouterCommand
+
+__all__ = ["DebugRouterCommand"]
+
+
+@as_command("debug:router")
+@final
+class DebugRouterCommand(RouterCommand):
+    """Lists every route an application holds, in the order routing tries them."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, app: str | None = None) -> int:
+        """List the application's routes, prefixes applied.
+
+        A router included under a prefix is listed under it, and a mounted
+        application is listed as the one route that reaches it — which is
+        what routing sees.
+
+        Args:
+            io: Where the command writes.
+            app: The application to read, as ``package.module:app``; the
+                configured one when left out.
+        """
+        application = self._app_or_report(io, app)
+        if application is None:
+            return ExitCode.INVALID
+        described = [RouteDescription.of(view) for view in route_contexts(application.routes)]
+        io.section(f"Routes ({len(described)})")
+        io.table(
+            ("Methods", "Path", "Name", "Endpoint"),
+            [
+                (
+                    escape(route.methods),
+                    escape(route.path),
+                    escape(route.name),
+                    escape(route.endpoint),
+                )
+                for route in described
+            ],
+        )
+        return ExitCode.SUCCESS