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

xtr_http_kernel/command/route_description.py

@@ -0,0 +1,81 @@
+"""What the router commands report about one route of an application."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import FunctionType, MethodType
+from typing import TYPE_CHECKING, Final, final
+
+from starlette.routing import Mount, WebSocketRoute
+
+if TYPE_CHECKING:
+    from starlette.routing import BaseRoute
+
+    from ._route_contexts import RouteView
+
+__all__ = ["RouteDescription"]
+
+_ANY_METHOD: Final = "-"
+"""Stands in for a route that answers whatever arrives, or has no method at all."""
+
+_MOUNT: Final = "MOUNT"
+_WEBSOCKET: Final = "WEBSOCKET"
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class RouteDescription:
+    """One line of what a router holds, ready to be printed.
+
+    Built from the routing layer's own view of a route, so the path is the
+    one requests are matched against — an included router's prefix already
+    applied — rather than the one written at the endpoint.
+
+    Attributes:
+        methods: The methods the route answers, comma-separated;
+            ``WEBSOCKET`` for a connection route, ``MOUNT`` for a mounted
+            application, ``-`` for a route taking whatever arrives.
+        path: The path as routing reads it.
+        name: The name the route answers to, empty when it has none.
+        endpoint: What the route hands the request to, as ``module:qualname``.
+    """
+
+    methods: str
+    path: str
+    name: str
+    endpoint: str
+
+    @classmethod
+    def of(cls, view: RouteView) -> RouteDescription:
+        """Describe the route ``view`` stands for."""
+        endpoint = view.endpoint
+        return cls(
+            methods=_methods(view),
+            path=view.path or "",
+            name=view.name or "",
+            endpoint=_qualified(endpoint if endpoint is not None else _carried(view.route)),
+        )
+
+
+def _methods(view: RouteView) -> str:
+    """Name the methods the route answers, or else the kind of route it is."""
+    if view.methods:
+        return ", ".join(sorted(view.methods))
+    if isinstance(view.route, WebSocketRoute):
+        return _WEBSOCKET
+    if isinstance(view.route, Mount):
+        return _MOUNT
+    return _ANY_METHOD
+
+
+def _carried(route: BaseRoute) -> object:
+    """Return what a route with no endpoint of its own hands the request to."""
+    return route.app if isinstance(route, Mount) else route
+
+
+def _qualified(target: object) -> str:
+    """Name ``target`` as ``module:qualname`` — its type's when it has none of its own."""
+    if isinstance(target, (type, FunctionType, MethodType)):
+        return f"{target.__module__}:{target.__qualname__}"
+    kind = type(target)
+    return f"{kind.__module__}:{kind.__qualname__}"

xtr_http_kernel/command/router_command.py

@@ -0,0 +1,69 @@
+"""What both router commands share: finding the application to report on."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, ClassVar, Final, cast
+
+from fastapi import FastAPI
+
+from xtr_http_kernel.bundle.http_kernel_config import HttpKernelConfig
+
+if TYPE_CHECKING:
+    from xtr_console import ConsoleStyle
+
+__all__ = ["RouterCommand"]
+
+_ZERO_CONFIG: Final = HttpKernelConfig()
+"""What a console without a container builds these commands with."""
+
+_NO_APPLICATION: Final = (
+    'no application to read: pass --app "package.module:app", or name one on the '
+    "http kernel's configuration"
+)
+
+
+class RouterCommand:
+    """A command reporting on an application, named on the command line or configured.
+
+    A container builds it with the http kernel's configuration, so an
+    application that names its own needs no option. Without a container the
+    console builds it bare, and ``--app`` is the only way to name one.
+
+    Nothing is imported until a command runs, and the application is only
+    read: no server starts, and no route is touched.
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_config",)
+
+    _config: HttpKernelConfig
+
+    def __init__(self, config: HttpKernelConfig = _ZERO_CONFIG) -> None:
+        """Report on the application ``config`` names, unless an option overrides it."""
+        self._config = config
+
+    def _app_or_report(self, io: ConsoleStyle, app: str | None) -> FastAPI | None:
+        """Import the application ``app`` names, or say on ``io`` why there is none.
+
+        ``app`` is the command line's answer and wins; the configuration's
+        is used when it is ``None``.
+        """
+        reference = app if app is not None else self._config.app
+        if reference is None:
+            io.error(_NO_APPLICATION)
+            return None
+        module_name, _, attribute = reference.partition(":")
+        if not module_name or not attribute:
+            io.error(f'an application reads "package.module:app", not {reference!r}')
+            return None
+        try:
+            module = import_module(module_name)
+        except ImportError as error:
+            io.error(f"cannot import {module_name!r}: {error}")
+            return None
+        # A module attribute is whatever the module put there: the check below decides.
+        loaded = cast("object", getattr(module, attribute, None))
+        if not isinstance(loaded, FastAPI):
+            io.error(f"{reference!r} does not name an application")
+            return None
+        return loaded

xtr_http_kernel/command/router_match_command.py

@@ -0,0 +1,96 @@
+"""``router:match``: which route a path reaches, and which one nearly does."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from starlette.routing import Match
+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
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from starlette.types import Scope
+
+__all__ = ["RouterMatchCommand"]
+
+
+@as_command("router:match")
+@final
+class RouterMatchCommand(RouterCommand):
+    """Names the route a path and a method reach, without serving anything.
+
+    The routes are tried against a request that is built and thrown away —
+    nothing is sent, no endpoint runs, and the application is left as it was.
+    """
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        path: str,
+        *,
+        method: str = "GET",
+        app: str | None = None,
+    ) -> int:
+        """Report the route ``path`` reaches with ``method``.
+
+        Exits successfully on a route that answers. A route matching the
+        path but refusing the method is reported as the near miss it is, and
+        so is a path no route answers at all — both fail the run.
+
+        Args:
+            io: Where the command writes.
+            path: The path to try, as it would arrive.
+            method: The method to try it with.
+            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
+        wanted = method.upper()
+        scope: Scope = {"type": "http", "method": wanted, "path": path, "root_path": ""}
+        refused: RouteDescription | None = None
+        for view in route_contexts(application.routes):
+            match, child_scope = view.matches(scope)
+            if match is Match.FULL:
+                _report(io, RouteDescription.of(view), child_scope)
+                return ExitCode.SUCCESS
+            if match is Match.PARTIAL and refused is None:
+                refused = RouteDescription.of(view)
+        if refused is not None:
+            io.error(
+                f'"{escape(path)}" reaches the route "{escape(refused.name)}" '
+                f"({escape(refused.path)}), which does not answer {escape(wanted)}"
+            )
+            return ExitCode.FAILURE
+        io.error(f"no route matches {escape(wanted)} {escape(path)}")
+        return ExitCode.FAILURE
+
+
+def _report(io: ConsoleStyle, route: RouteDescription, child_scope: Scope) -> None:
+    """Say which route answered, and what it read out of the path."""
+    io.success(f'"{escape(route.path)}" is answered by {escape(route.endpoint)}')
+    io.table(
+        ("Name", "Methods", "Path", "Endpoint"),
+        [
+            (
+                escape(route.name),
+                escape(route.methods),
+                escape(route.path),
+                escape(route.endpoint),
+            )
+        ],
+    )
+    parameters = cast("Mapping[str, object]", child_scope.get("path_params", {}))
+    if parameters:
+        io.table(
+            ("Parameter", "Value"),
+            [(escape(name), escape(str(value))) for name, value in sorted(parameters.items())],
+        )

xtr_http_kernel/event/__init__.py

@@ -0,0 +1,35 @@
+"""The events a request goes through, from arriving to being answered.
+
+Every request dispatches the same sequence, and a listener joins it wherever
+it has something to contribute:
+
+1. :class:`RequestEvent` — it arrived, nothing has looked at it. A listener
+   may answer it here instead of the application.
+2. :class:`ResponseEvent` — a response is about to start; its status and
+   headers can still be changed. **Or** :class:`ExceptionEvent` — handling
+   raised, and a listener may turn that into a response.
+3. :class:`FinishRequestEvent` — handling finished, on every path.
+4. :class:`TerminateEvent` — everything has been sent; whatever is done here
+   cannot reach the caller.
+
+Events are keyed by the qualified name of their class, so listening to
+``RequestEvent`` and listening to
+:data:`~xtr_http_kernel.kernel_events.KernelEvents.REQUEST` name the same
+event.
+"""
+
+from __future__ import annotations
+
+from .exception_event import ExceptionEvent
+from .finish_request_event import FinishRequestEvent
+from .request_event import RequestEvent
+from .response_event import ResponseEvent
+from .terminate_event import TerminateEvent
+
+__all__ = [
+    "ExceptionEvent",
+    "FinishRequestEvent",
+    "RequestEvent",
+    "ResponseEvent",
+    "TerminateEvent",
+]

xtr_http_kernel/event/exception_event.py

@@ -0,0 +1,65 @@
+"""Dispatched when handling a request raised."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+__all__ = ["ExceptionEvent"]
+
+
+@final
+class ExceptionEvent(Event):
+    """Handling ``request`` raised, and nothing has been sent.
+
+    A listener that only wants to know — one writing the failure to a log,
+    say — reads :attr:`exception` and leaves the response alone: the
+    exception then carries on out of the lifecycle, to whatever the
+    application put in charge of turning it into a response.
+
+    A listener that wants to answer calls :meth:`set_response`, which stops
+    the event: the exception is swallowed, and that response leaves instead.
+
+    :attr:`exception` is a :class:`BaseException`, not an :class:`Exception`:
+    a cancellation or an interrupt is exactly the kind of failure a listener
+    logging what went wrong wants to see.
+    """
+
+    def __init__(self, request: Request, exception: BaseException) -> None:
+        """Announce that handling ``request`` raised ``exception``."""
+        self._request = request
+        self._exception = exception
+        self._response: Response | None = None
+
+    @property
+    def request(self) -> Request:
+        """Return the request whose handling raised."""
+        return self._request
+
+    @property
+    def exception(self) -> BaseException:
+        """Return what was raised."""
+        return self._exception
+
+    @property
+    def response(self) -> Response | None:
+        """Return the response a listener turned the exception into, if one did."""
+        return self._response
+
+    def has_response(self) -> bool:
+        """Tell whether a listener turned the exception into a response."""
+        return self._response is not None
+
+    def set_response(self, response: Response) -> None:
+        """Answer with ``response``, and skip the listeners after this one.
+
+        The exception stops here: ``response`` is what leaves, and the
+        listeners that have not run never hear about the failure.
+        """
+        self._response = response
+        self.stop_propagation()

xtr_http_kernel/event/finish_request_event.py

@@ -0,0 +1,40 @@
+"""Dispatched when handling of a request finished, whatever came of it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+__all__ = ["FinishRequestEvent"]
+
+
+@final
+class FinishRequestEvent(Event):
+    """Handling of ``request`` finished — the one event dispatched on every path.
+
+    It runs whether the application answered, a listener short-circuited the
+    request, an exception was turned into a response, or an exception is
+    about to leave the lifecycle unhandled. That is what makes it the place
+    to put away anything a request set up: the per-request logging unit, a
+    trace, a scope closed by hand.
+
+    When there is a body, it is dispatched before the last chunk leaves, so a
+    listener can still do its work while the request is recognisably the one
+    being answered. It carries no response: by this point the head is gone,
+    and there is nothing left to change — see
+    :class:`~xtr_http_kernel.event.terminate_event.TerminateEvent` for what
+    was actually sent.
+    """
+
+    def __init__(self, request: Request) -> None:
+        """Announce that handling ``request`` finished."""
+        self._request = request
+
+    @property
+    def request(self) -> Request:
+        """Return the request whose handling finished."""
+        return self._request

xtr_http_kernel/event/request_event.py

@@ -0,0 +1,56 @@
+"""Dispatched first, before the application sees the request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+__all__ = ["RequestEvent"]
+
+
+@final
+class RequestEvent(Event):
+    """A request arrived, and nothing has looked at it yet.
+
+    This is the one moment a listener can answer instead of the application:
+    :meth:`set_response` short-circuits routing, so a cache, a maintenance
+    page or a redirect never reaches an endpoint. Answering stops the event,
+    because the listeners after it would be deciding about a request that has
+    already been dealt with.
+
+    A listener that only wants to read or annotate the request leaves the
+    response alone; the request then carries on to the router untouched.
+    """
+
+    def __init__(self, request: Request) -> None:
+        """Announce ``request``, before anything has handled it."""
+        self._request = request
+        self._response: Response | None = None
+
+    @property
+    def request(self) -> Request:
+        """Return the request that arrived."""
+        return self._request
+
+    @property
+    def response(self) -> Response | None:
+        """Return the response a listener answered with, if one did."""
+        return self._response
+
+    def has_response(self) -> bool:
+        """Tell whether a listener answered the request itself."""
+        return self._response is not None
+
+    def set_response(self, response: Response) -> None:
+        """Answer the request with ``response``, and skip the listeners after this one.
+
+        The application never runs: ``response`` is what leaves, after the
+        rest of the lifecycle has had its say about it.
+        """
+        self._response = response
+        self.stop_propagation()

xtr_http_kernel/event/response_event.py

@@ -0,0 +1,64 @@
+"""Dispatched when a response is about to start leaving."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.datastructures import MutableHeaders
+    from starlette.requests import Request
+
+__all__ = ["ResponseEvent"]
+
+
+@final
+class ResponseEvent(Event):
+    """A response is about to start, and its head can still be changed.
+
+    Dispatched once the application has decided on a status and a set of
+    headers, and before either has left — a request id, a caching directive
+    or a header keeping the page out of a search index belongs here.
+
+    **The body is not here, and cannot be replaced.** A response is streamed:
+    by the time the first chunk is written the head is already gone, and the
+    body may be produced a chunk at a time by something that is still
+    running. This event owns exactly what an application can still change at
+    that point: :attr:`status_code`, which may be assigned, and
+    :attr:`headers`, which may be mutated. A listener wanting to answer with
+    a body of its own does so at
+    :class:`~xtr_http_kernel.event.request_event.RequestEvent` or
+    :class:`~xtr_http_kernel.event.exception_event.ExceptionEvent`, where
+    nothing has been sent yet.
+    """
+
+    def __init__(self, request: Request, status_code: int, headers: MutableHeaders) -> None:
+        """Announce the response to ``request``, starting with ``status_code`` and ``headers``.
+
+        ``headers`` is the outgoing list itself, not a copy: what a listener
+        writes into it is what leaves.
+        """
+        self._request = request
+        self._status_code = status_code
+        self._headers = headers
+
+    @property
+    def request(self) -> Request:
+        """Return the request being answered."""
+        return self._request
+
+    @property
+    def status_code(self) -> int:
+        """Return the status the response will start with."""
+        return self._status_code
+
+    @status_code.setter
+    def status_code(self, status_code: int) -> None:
+        """Start the response with ``status_code`` instead."""
+        self._status_code = status_code
+
+    @property
+    def headers(self) -> MutableHeaders:
+        """Return the outgoing headers, to read or to change in place."""
+        return self._headers

xtr_http_kernel/event/terminate_event.py

@@ -0,0 +1,43 @@
+"""Dispatched last, once the response has been sent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+__all__ = ["TerminateEvent"]
+
+
+@final
+class TerminateEvent(Event):
+    """Everything was sent, or the failure went past the lifecycle.
+
+    Dispatched after the last chunk of the response left, so nothing a
+    listener does here can reach the client. That is the point: work worth
+    doing once the caller has their answer — a metric, a notification, a
+    write that would otherwise have held the response — belongs here.
+
+    :attr:`status_code` is what was actually sent. When nothing was sent at
+    all, because an exception left the lifecycle before the response started,
+    it is ``500``: that is what the caller ends up seeing, and a listener
+    counting statuses should count it.
+    """
+
+    def __init__(self, request: Request, status_code: int) -> None:
+        """Announce that ``request`` was answered with ``status_code``."""
+        self._request = request
+        self._status_code = status_code
+
+    @property
+    def request(self) -> Request:
+        """Return the request that was answered."""
+        return self._request
+
+    @property
+    def status_code(self) -> int:
+        """Return the status that was sent, or ``500`` when nothing was."""
+        return self._status_code

xtr_http_kernel/event_listener/__init__.py

@@ -0,0 +1,23 @@
+"""The listeners this library ships for its own lifecycle.
+
+Each contributes one of the things every application wants around an
+endpoint: a request id, an uncaught exception in the log, a header keeping a
+page out of a search index, a unit of work per request. The bundle registers
+them; outside a container each is an ordinary object to register by hand.
+
+:class:`~xtr_http_kernel.event_listener.log_unit_listener.LogUnitListener`
+is not re-exported here: it needs the optional logging extra, so it is
+imported from its own module by whoever knows that extra is installed.
+"""
+
+from __future__ import annotations
+
+from .disallow_robots_indexing_listener import DisallowRobotsIndexingListener
+from .error_logging_listener import ErrorLoggingListener
+from .request_id_listener import RequestIdListener
+
+__all__ = [
+    "DisallowRobotsIndexingListener",
+    "ErrorLoggingListener",
+    "RequestIdListener",
+]

xtr_http_kernel/event_listener/disallow_robots_indexing_listener.py

@@ -0,0 +1,31 @@
+"""Keeping every response out of search indexes, when the application asks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from xtr_http_kernel.event import ResponseEvent
+
+__all__ = ["DisallowRobotsIndexingListener"]
+
+
+@final
+class DisallowRobotsIndexingListener:
+    """Marks every outgoing response ``X-Robots-Tag: noindex`` when enabled.
+
+    A staging deployment or an internal tool wants the whole application out
+    of search indexes, not one page: a response header set in one listener
+    beats a meta tag repeated in every template.
+    """
+
+    __slots__ = ("_enabled",)
+
+    def __init__(self, enabled: bool) -> None:
+        """Mark responses when ``enabled``; stay silent otherwise."""
+        self._enabled = enabled
+
+    def on_response(self, event: ResponseEvent) -> None:
+        """Stamp the outgoing head, when marking is on."""
+        if self._enabled:
+            event.headers["X-Robots-Tag"] = "noindex"

xtr_http_kernel/event_listener/error_logging_listener.py

@@ -0,0 +1,52 @@
+"""An uncaught exception written to the log with the request that caused it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, final
+
+from xtr_logging_contracts import EXCEPTION_KEY
+
+if TYPE_CHECKING:
+    from xtr_logging_contracts import LoggerInterface
+
+    from xtr_http_kernel.event import ExceptionEvent
+
+__all__ = ["ErrorLoggingListener"]
+
+_SERVER_ERROR: Final = 500
+
+
+@final
+class ErrorLoggingListener:
+    """Writes every exception the lifecycle announces to one logger.
+
+    The level follows whose fault the failure is: an exception carrying an
+    integer ``status_code`` below 500 is the caller's, and logged ``error``;
+    a server status, or an exception saying nothing about status, is logged
+    ``critical``. The exception itself travels under the logging contract's
+    exception key, so formatters print its class, origin and cause.
+    """
+
+    __slots__ = ("_logger",)
+
+    def __init__(self, logger: LoggerInterface) -> None:
+        """Write to ``logger`` — the bundle hands in the request channel's."""
+        self._logger = logger
+
+    def on_exception(self, event: ExceptionEvent) -> None:
+        """Log the failure, leaving the response to whoever answers it."""
+        status = getattr(event.exception, "status_code", None)
+        known = status if isinstance(status, int) else None
+        write = (
+            self._logger.error
+            if known is not None and known < _SERVER_ERROR
+            else self._logger.critical
+        )
+        write(
+            "handling {method} {path} raised",
+            {
+                "method": event.request.method,
+                "path": event.request.url.path,
+                EXCEPTION_KEY: event.exception,
+            },
+        )