xtr_http_kernel.bundle ¶
The xtr-dependency-injection bundle for xtr-http-kernel.
ROUTE_REGISTRY_PARAMETER
module-attribute
¶
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 ¶
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 ¶
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 ¶
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
priorityis not an integer.
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
Hostheader — exact names,*.example.comfor 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.
Nonereads 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_headeris not an HTTP token,log_channelis empty,appdoes not hold exactly one module and one attribute around a single:, a trusted host names no host, ormax_body_sizeis 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_parameteris. -
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;
Nonekeeps them under the kernel's cache directory, inprofiler/. -
lifetime_seconds(int) –How long a profile is kept.
Raises:
-
InvalidArgumentError–When an
excluded_pathsentry is not a regular expression,collect_parameteris empty, orlifetime_secondsis 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 ¶
Set the profiler's collectors and the templates of their panels.
Raises:
-
InvalidCollectorTagError–When a tag lacks a
nameor atemplate. -
InvalidCollectorPriorityError–When a tag's
priorityis not an integer.
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.