Skip to content

xtr_http_kernel.bundle

The xtr-dependency-injection bundle for xtr-http-kernel.

ROUTE_REGISTRY_PARAMETER module-attribute

ROUTE_REGISTRY_PARAMETER: Final = 'http_kernel.route_registry'

The parameter the registry is stored under while the kernel compiles.

HttpKernelBundle

Bases: Bundle[HttpKernelConfig]

Puts the request lifecycle's services under the container.

build

build(builder: ContainerBuilder) -> None

Collect the route resources and routes files from what is scanned.

A function declared with @as_route_resource and a function declared with @as_routes are kept, in scan order; the registry pass stores them while the kernel compiles, and setup stages them and mounts what the routes files include. The lists are this build's own, so a bundle instance built twice starts from nothing found both times.

prepend_extension

prepend_extension(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.

In debug mode, a handler keeping each request's records for its profile joins the logging configuration too.

load_extension

load_extension(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.

process

process(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:

HttpKernelConfig dataclass

HttpKernelConfig(request_id_header: str = 'X-Request-Id', trust_request_id: bool = False, disallow_search_indexing: bool = False, log_channel: str = 'request', middleware_priority: int = 0, app: str | None = None, trusted_hosts: tuple[str, ...] = (), max_body_size: int | None = _TEN_MIB, profiler: ProfilerConfig = ProfilerConfig())

What an application may change about the request lifecycle.

Attributes:

  • request_id_header (str) –

    The header the request id is read from and echoed on. Must be a non-empty HTTP token.

  • trust_request_id (bool) –

    Whether a well-formed incoming id is kept. Off by default, so every request gets a fresh one: a caller can otherwise choose the id its own requests are logged under, and so collide two requests' records on purpose. Turn it on only where a proxy you control sets the header and strips whatever the caller sent.

  • disallow_search_indexing (bool) –

    Whether every response is marked X-Robots-Tag: noindex.

  • log_channel (str) –

    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 (int) –

    Where the lifecycle middleware sits among the contributed factories — highest outermost.

  • app (str | None) –

    The "package.module:app" import string the console commands load the application from, when they need one.

  • trusted_hosts (tuple[str, ...]) –

    The hosts a request may name in its Host header — exact names, *.example.com for every subdomain, addresses (a long one in brackets) — matched lowercased; any other host is answered 400 before the lifecycle starts. Empty, the default, lets every host through.

  • max_body_size (int | None) –

    The most bytes of a request body read, uploads included; a request sending more is answered 413. None reads any body. A route taking larger uploads raises its own limit.

  • profiler (ProfilerConfig) –

    Whether, and how, requests are profiled; off by default.

Raises:

  • InvalidArgumentError –

    When request_id_header is not an HTTP token, log_channel is empty, app does not hold exactly one module and one attribute around a single :, a trusted host names no host, or max_body_size is not positive.

ProfilerConfig dataclass

ProfilerConfig(enabled: bool = False, collect: bool = True, collect_parameter: str | None = None, only_exceptions: bool = False, excluded_paths: tuple[str, ...] = ('^/_(wdt|profiler)',), excluded_status_codes: tuple[int, ...] = (), storage_path: str | None = None, lifetime_seconds: int = 172800)

What an application may change about profiling its requests.

Off by default: a profile holds every request's headers, cookies and state, so it is turned on only where a developer reads it — the web profiler's bundle turns it on in the environments it is listed for.

Attributes:

  • enabled (bool) –

    Whether requests are profiled at all.

  • collect (bool) –

    Whether a request is profiled unless it asks otherwise; off, only a request carrying collect_parameter is.

  • collect_parameter (str | None) –

    A query parameter, or a state bag key, whose boolean value turns profiling on or off for that request alone.

  • only_exceptions (bool) –

    Profile only the requests whose handling raised.

  • excluded_paths (tuple[str, ...]) –

    Regular expressions; a request whose path matches one is not profiled. The profiler's own pages are excluded by default.

  • excluded_status_codes (tuple[int, ...]) –

    Statuses a profile is not kept for.

  • storage_path (str | None) –

    Where profiles are kept; None keeps them under the kernel's cache directory, in profiler/.

  • lifetime_seconds (int) –

    How long a profile is kept.

Raises:

  • InvalidArgumentError –

    When an excluded_paths entry is not a regular expression, collect_parameter is empty, or lifetime_seconds is below one.

ProfilerPass

Bases: CompilerPassInterface

Orders every http_kernel.data_collector service and gives the profiler them all.

Highest priority first, a missing one counting as 0, ties in registration order. The profiler gets the services in that order, and :class:~xtr_http_kernel.data_collector.DataCollectorTemplates the (name, template) pairs, which is what shows the panels. A pass rather than a bundle hook, so the collectors every other bundle tagged are in. Nothing happens when the profiler is off — it is not registered then.

process

process(builder: ContainerBuilder) -> None

Set the profiler's collectors and the templates of their panels.

Raises:

RouteRegistryPass

RouteRegistryPass(resources: Sequence[tuple[str, Callable[[APIRouter], None]]], files: Sequence[RoutesFile])

Bases: CompilerPassInterface

Stores the route resources and routes files the bundle collected.

A pass rather than a bundle hook because the autoconfiguration callbacks that collect both run after every hook: only here is the scan's harvest complete. Nothing is called and nothing is mounted while the kernel compiles — setup reads the parameter, stages the resources, and runs the files, and only what a file includes is served.

Hold the bundle's lists, read in :meth:process — the callbacks fill them after this.

process

process(builder: ContainerBuilder) -> None

Store the registry under its parameter.