xtr-http-kernel 2.0.0__tar.gz → 3.0.0__tar.gz

{xtr_http_kernel-2.0.0 → xtr_http_kernel-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-kernel
-Version: 2.0.0
+Version: 3.0.0
 Summary: Requests turned into responses through events: a request lifecycle for FastAPI applications on the xtr kernel.
 Keywords: http,kernel,request,lifecycle,events,middleware,fastapi
 Author: Xterr
@@ -16,16 +16,16 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Dist: fastapi>=0.121.3
 Requires-Dist: starlette>=0.40
-Requires-Dist: xtr-dependency-injection[fastapi]>=2.0,<3
-Requires-Dist: xtr-event-dispatcher>=2.0,<3
-Requires-Dist: xtr-event-dispatcher-contracts>=2.0,<3
-Requires-Dist: xtr-logging-contracts>=2.0,<3
-Requires-Dist: xtr-service-contracts>=2.0,<3
+Requires-Dist: xtr-dependency-injection[fastapi]>=3.0,<4
+Requires-Dist: xtr-event-dispatcher>=3.0,<4
+Requires-Dist: xtr-event-dispatcher-contracts>=3.0,<4
+Requires-Dist: xtr-logging-contracts>=3.0,<4
+Requires-Dist: xtr-service-contracts>=3.0,<4
 Requires-Dist: typing-extensions>=4.4
-Requires-Dist: xtr-console>=2.0,<3 ; extra == 'console'
-Requires-Dist: xtr-logging>=2.0,<3 ; extra == 'logging'
-Requires-Dist: xtr-clock>=2.0,<3 ; extra == 'rate-limiter'
-Requires-Dist: xtr-rate-limiter[di]>=2.0,<3 ; extra == 'rate-limiter'
+Requires-Dist: xtr-console>=3.0,<4 ; extra == 'console'
+Requires-Dist: xtr-logging>=3.0,<4 ; extra == 'logging'
+Requires-Dist: xtr-clock>=3.0,<4 ; extra == 'rate-limiter'
+Requires-Dist: xtr-rate-limiter[di]>=3.0,<4 ; extra == 'rate-limiter'
 Requires-Python: >=3.11
 Provides-Extra: console
 Provides-Extra: logging
@@ -319,6 +319,9 @@ removing it undoes.
 - **Install** — `uv add "xtr-http-kernel[logging,console]"`; `logging` brings the listeners
   that write to a log, `console` the commands that report on the router, `rate-limiter` the
   [rate limits](#rate-limits). None is needed to serve requests.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
+  `HttpKernelBundle`. There is no config file, environment or ignore line to write; it prints the
+  `setup(app, kernel)` step, which a recipe cannot make for you.
 - **Activate** — `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
   from `xtr_http_kernel.bundle`. Then call `setup(app, kernel)` where the application is built.
 - **Brings along** — the [event dispatcher](../xtr-event-dispatcher) bundle always, because the

{xtr_http_kernel-2.0.0 → xtr_http_kernel-3.0.0}/README.md

@@ -285,6 +285,9 @@ removing it undoes.
 - **Install** — `uv add "xtr-http-kernel[logging,console]"`; `logging` brings the listeners
   that write to a log, `console` the commands that report on the router, `rate-limiter` the
   [rate limits](#rate-limits). None is needed to serve requests.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
+  `HttpKernelBundle`. There is no config file, environment or ignore line to write; it prints the
+  `setup(app, kernel)` step, which a recipe cannot make for you.
 - **Activate** — `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
   from `xtr_http_kernel.bundle`. Then call `setup(app, kernel)` where the application is built.
 - **Brings along** — the [event dispatcher](../xtr-event-dispatcher) bundle always, because the

{xtr_http_kernel-2.0.0 → xtr_http_kernel-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-kernel"
-version = "2.0.0"
+version = "3.0.0"
 description = "Requests turned into responses through events: a request lifecycle for FastAPI applications on the xtr kernel."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,11 +27,11 @@ classifiers = [
 dependencies = [
     "fastapi>=0.121.3",
     "starlette>=0.40",
-    "xtr-dependency-injection[fastapi]>=2.0,<3",
-    "xtr-event-dispatcher>=2.0,<3",
-    "xtr-event-dispatcher-contracts>=2.0,<3",
-    "xtr-logging-contracts>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-dependency-injection[fastapi]>=3.0,<4",
+    "xtr-event-dispatcher>=3.0,<4",
+    "xtr-event-dispatcher-contracts>=3.0,<4",
+    "xtr-logging-contracts>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
     "typing-extensions>=4.4",
 ]
 
@@ -40,16 +40,19 @@ name = "Xterr"
 email = "me@xterr.dev"
 
 [project.optional-dependencies]
-logging = ["xtr-logging>=2.0,<3"]
-console = ["xtr-console>=2.0,<3"]
+logging = ["xtr-logging>=3.0,<4"]
+console = ["xtr-console>=3.0,<4"]
 rate-limiter = [
-    "xtr-clock>=2.0,<3",
-    "xtr-rate-limiter[di]>=2.0,<3",
+    "xtr-clock>=3.0,<4",
+    "xtr-rate-limiter[di]>=3.0,<4",
 ]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 http_kernel = "xtr_http_kernel.bundle:HttpKernelBundle"
 
+[project.entry-points.xtr_recipes]
+http_kernel = "xtr_http_kernel.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
@@ -58,10 +61,10 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-logging>=2.0,<3",
-    "xtr-console>=2.0,<3",
-    "xtr-clock>=2.0,<3",
-    "xtr-rate-limiter[di]>=2.0,<3",
+    "xtr-logging>=3.0,<4",
+    "xtr-console>=3.0,<4",
+    "xtr-clock>=3.0,<4",
+    "xtr-rate-limiter[di]>=3.0,<4",
     "httpx>=0.27",
 ]
 

{xtr_http_kernel-2.0.0 → xtr_http_kernel-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-kernel"
-version = "2.0.0"
+version = "3.0.0"
 description = "Requests turned into responses through events: a request lifecycle for FastAPI applications on the xtr kernel."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,24 +26,24 @@ dependencies = [
     "fastapi>=0.121.3",
     # Imported directly — requests, responses, middleware — not only through fastapi.
     "starlette>=0.40",
-    "xtr-dependency-injection[fastapi]>=2.0,<3",
-    "xtr-event-dispatcher>=2.0,<3",
-    "xtr-event-dispatcher-contracts>=2.0,<3",
-    "xtr-logging-contracts>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-dependency-injection[fastapi]>=3.0,<4",
+    "xtr-event-dispatcher>=3.0,<4",
+    "xtr-event-dispatcher-contracts>=3.0,<4",
+    "xtr-logging-contracts>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
     "typing-extensions>=4.4",
 ]
 
 [project.optional-dependencies]
 logging = [
-    "xtr-logging>=2.0,<3",
+    "xtr-logging>=3.0,<4",
 ]
 console = [
-    "xtr-console>=2.0,<3",
+    "xtr-console>=3.0,<4",
 ]
 rate-limiter = [
-    "xtr-clock>=2.0,<3",
-    "xtr-rate-limiter[di]>=2.0,<3",
+    "xtr-clock>=3.0,<4",
+    "xtr-rate-limiter[di]>=3.0,<4",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -51,6 +51,10 @@ rate-limiter = [
 [project.entry-points."xtr_dependency_injection.bundles"]
 http_kernel = "xtr_http_kernel.bundle:HttpKernelBundle"
 
+# Advertises the recipe — what *Use in an application* takes — for recipes:sync.
+[project.entry-points."xtr_recipes"]
+http_kernel = "xtr_http_kernel.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
@@ -59,10 +63,10 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-logging>=2.0,<3",
-    "xtr-console>=2.0,<3",
-    "xtr-clock>=2.0,<3",
-    "xtr-rate-limiter[di]>=2.0,<3",
+    "xtr-logging>=3.0,<4",
+    "xtr-console>=3.0,<4",
+    "xtr-clock>=3.0,<4",
+    "xtr-rate-limiter[di]>=3.0,<4",
     # Requests are driven straight at the application through an ASGI
     # transport, so the suite never binds a socket.
     "httpx>=0.27",

xtr_http_kernel-3.0.0/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: xtr-http-kernel
+description: The HTTP entry point for a FastAPI application built on xtr-dependency-injection — setup(app, kernel), a request lifecycle of five events, container services injected into routes, and rate limits on routes. Use when wiring a FastAPI app to a kernel, writing a route that needs a container service, adding a request id or a response header for every request, logging uncaught exceptions with the request that caused it, short-circuiting a request before routing, turning an exception into a response, opening a per-request unit of work, contributing middleware from a bundle, listing routes with debug:router, rate limiting a route or router, or testing a served application with an httpx ASGI client. For plain FastAPI matters (routing, Depends, request bodies, response models, OpenAPI) use the fastapi skill instead.
+---
+
+# xtr-http-kernel
+
+FastAPI still routes, resolves arguments and serializes. This package adds the part around the
+endpoint: one `setup(app, kernel)` call that gives every application life its own kernel, five
+lifecycle events listeners can join, and container services injected straight into route
+signatures. Everything the framework already does well is left alone.
+
+## Quick reference
+
+- One call: `setup(app, kernel)` from `xtr_http_kernel`, after the routes and before the first
+  request.
+- Pull a container service into a route with `Injected[T]`, `Annotated[T, Target("name")]` or
+  `Annotated[T, Autowire(param=...)]`. Keep `Depends` for everything that is the framework's.
+- Join the lifecycle with `@as_event_listener()` from `xtr_event_dispatcher` on a function
+  taking one of `RequestEvent`, `ResponseEvent`, `ExceptionEvent`, `FinishRequestEvent`,
+  `TerminateEvent`.
+- Every response carries `X-Request-Id`; `request.state.request_id` holds the same value.
+- Test with `httpx.ASGITransport` inside `app.router.lifespan_context(app)`, never
+  `TestClient`. Swap services with `override_services` from `xtr_http_kernel.testing`.
+- Activate `HttpKernelBundle` from `xtr_http_kernel.bundle`; configure with `HttpKernelConfig`.
+
+## Set up the application
+
+```python
+# app/web.py
+from __future__ import annotations
+
+from fastapi import FastAPI
+from xtr_dependency_injection import Kernel
+from xtr_http_kernel import setup
+from xtr_http_kernel.bundle import HttpKernelBundle
+
+app = FastAPI()
+# ... routes and the application's own middleware here ...
+
+kernel = Kernel("app", bundles={HttpKernelBundle: {"all": True}})
+setup(app, kernel)
+```
+
+`setup` builds nothing. It wraps two seams:
+
+- **The lifespan.** Every application life builds the kernel afresh, applies test overrides,
+  boots it, attaches the container so the route markers resolve, runs the app's own lifespan
+  inside, then detaches and shuts down.
+- **One middleware.** Fetches the kernel's `MiddlewareStack` once per life and runs every
+  request through it, inside the request scope scoped services live in.
+
+Serve it with any ASGI server: `uvicorn app.web:app`.
+
+## Inject services into a route
+
+```python
+from typing import Annotated
+
+from xtr_dependency_injection import Autowire, Injected, Target
+
+
+@app.get("/books/{isbn}")
+async def read_book(
+    isbn: str,  # a path parameter, the framework's
+    catalogue: Injected[Catalogue],  # from the container
+    mailer: Annotated[Mailer, Target("smtp")],  # a qualified service
+    env: Annotated[str, Autowire(param="kernel.environment")],  # a kernel parameter
+) -> Book:
+    return await catalogue.get(isbn)
+```
+
+The markers never reach the OpenAPI schema, so the documented parameters stay the HTTP ones. A
+`lifetime="scoped"` service is built once per request and released after the response has been
+sent, which is when a per-request unit of work commits or rolls back; put cleanup that must
+survive an error in a `finally`.
+
+## Join the lifecycle
+
+```python
+from fastapi import Response
+from xtr_event_dispatcher import as_event_listener
+
+from xtr_http_kernel import ExceptionEvent, RequestEvent, ResponseEvent, TerminateEvent
+
+
+@as_event_listener(priority=100)
+def keep_it_out_of_the_index(event: ResponseEvent) -> None:
+    event.headers["x-robots-tag"] = "noindex"  # headers are the outgoing ones, mutated in place
+
+
+@as_event_listener()
+def serve_the_maintenance_page(event: RequestEvent) -> None:
+    if under_maintenance():
+        event.set_response(Response("back soon", status_code=503))  # the app never runs
+
+
+@as_event_listener()
+def answer_the_failure(event: ExceptionEvent) -> None:
+    if isinstance(event.exception, OutOfStock):
+        event.set_response(Response("sorry", status_code=409))
+
+
+@as_event_listener()
+def count_the_status(event: TerminateEvent) -> None:
+    metrics.increment(event.status_code)  # the caller already has their answer
+```
+
+Every event carries `request`. The kernel scans the application package, so a listener in a
+scanned module needs no further registration.
+
+| Event | When | A listener may |
+| --- | --- | --- |
+| `RequestEvent` | it arrived, nothing has looked at it | read `request`, or `set_response(...)` to answer instead of the application |
+| `ResponseEvent` | a response is about to start | assign `status_code`, mutate `headers`; there is no body here |
+| `ExceptionEvent` | handling raised, nothing was sent | read `exception` (a `BaseException`), or `set_response(...)` to answer with it |
+| `FinishRequestEvent` | handling finished, on every path | put away what the request set up |
+| `TerminateEvent` | everything was sent | read `status_code`, which is `500` when nothing left |
+
+- `set_response` stops the event: the listeners after it do not run.
+- `ExceptionEvent` only fires while nothing has been sent, and only an `Exception` is turned
+  into a response; a cancellation or an interrupt is announced and then carries on out.
+- `ResponseEvent` owns exactly the head, because the body is streamed. A listener wanting a
+  body of its own answers at the request or the exception.
+- `KernelEvents.REQUEST`, `.RESPONSE`, `.EXCEPTION`, `.FINISH_REQUEST` and `.TERMINATE` name the
+  same events, for a listener registered by hand:
+  `dispatcher.add_listener(KernelEvents.RESPONSE, stamp, priority=100)`.
+
+## What ships already
+
+The bundle registers `RequestIdListener` and `DisallowRobotsIndexingListener` always,
+`LogUnitListener` and `ErrorLoggingListener` when the logging bundle is active, and
+`RateLimitHeadersListener` when the rate limiter bundle is. So a request id, a per-request
+logging unit, an uncaught exception written to the log, a noindex header and the
+`X-RateLimit-*` headers are all already done: configure them rather than writing your own. See
+[references/listeners.md](references/listeners.md) for what each one does.
+
+## Rate limits
+
+With the `rate-limiter` extra, `RateLimited` holds a route, a router or the whole application to
+a limiter configured in xtr-rate-limiter's bundle:
+
+```python
+from xtr_http_kernel.rate_limiter import RateLimited
+
+app = FastAPI(dependencies=[RateLimited("global")])  # every route
+
+
+@app.get("/books")
+@RateLimited("api", expose_headers=True)  # below the route decorator
+async def list_books() -> list[Book]: ...
+```
+
+A refusal is `429 Too Many Requests` with `Retry-After`, raised as `TooManyRequestsError`.
+See [references/rate-limits.md](references/rate-limits.md) for keys, tokens, methods, headers,
+routers and limiting by hand.
+
+## Contribute middleware from a bundle
+
+A bundle tags a service that builds a middleware (a callable taking the downstream ASGI app and
+returning it wrapped) with `MIDDLEWARE_TAG` from `xtr_http_kernel` and an integer `priority`:
+`services.set(compression_middleware).add_tag(MIDDLEWARE_TAG, priority=10)`. Highest sits
+outermost, a missing one counts as `0`, ties keep registration order, and a non-integer fails
+the build with `InvalidMiddlewarePriorityError`.
+
+## Testing
+
+`TestClient` is unusable here: it leans on a deprecated framework path. Drive the application
+through an ASGI transport, inside its own lifespan so the kernel builds and boots:
+
+```python
+import httpx
+import pytest
+
+from app.web import app
+
+
+@pytest.mark.anyio
+async def test_a_book_carries_a_request_id() -> None:
+    async with app.router.lifespan_context(app):
+        transport = httpx.ASGITransport(app, raise_app_exceptions=False)
+        async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+            response = await client.get("/books/0262510871")
+
+    assert response.status_code == 200
+    assert response.headers["x-request-id"]
+```
+
+Swap a service by parking it on the application **before** entering the lifespan:
+
+```python
+from xtr_http_kernel.testing import override_services
+
+
+@pytest.mark.anyio
+async def test_it_uses_the_fake_catalogue() -> None:
+    with override_services(app, {Catalogue: FakeCatalogue()}):
+        async with app.router.lifespan_context(app):
+            ...  # every kernel built here resolves the fake
+```
+
+A key is a type, or a `(type, qualifier)` pair. The overrides live on the application, so two
+tests serving one application must not run at the same time.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`HttpKernelBundle`. That is the steps below a recipe can do; the `setup(app, kernel)` step it prints
+for you to make.
+
+1. **Install** `uv add "xtr-http-kernel[logging,console]"`. The extras: `logging` adds the
+   listeners that write to a log, `console` the router commands, `rate-limiter` the rate limits.
+   None is needed to serve requests.
+2. **Activate** `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
+   from `xtr_http_kernel.bundle`, then call `setup(app, kernel)` where the application is built.
+3. **Brings along** the event dispatcher bundle always; the logging, console and rate limiter
+   bundles whenever those packages are installed. Installing the extra is what activates them,
+   not listing.
+4. **Configure** nothing by default: a `uuid4` id under `X-Request-Id`, no robots header, the
+   `request` log channel.
+
+   ```python
+   # <app>/config/http_kernel.py
+   from xtr_dependency_injection import configure
+
+   from xtr_http_kernel.bundle import HttpKernelConfig
+
+
+   @configure
+   def http_kernel() -> HttpKernelConfig:
+       return HttpKernelConfig(disallow_search_indexing=True, app="app.web:app")
+   ```
+
+   Six fields, all optional: `request_id_header`, `trust_request_id`,
+   `disallow_search_indexing`, `log_channel`, `middleware_priority`, `app`. See
+   [references/configure.md](references/configure.md) for each one's default and meaning.
+5. **Environment** nothing.
+6. **Run** any ASGI server against the module `setup` was called in: `uvicorn app.web:app`.
+7. **Check** `debug:bundles` shows `http_kernel` as `listed` and `active`, `event_dispatcher` as
+   `required`. With a console bundle, `debug:router` lists the routes in the order routing tries
+   them, and `router:match PATH [--method GET]` names the route a path reaches.
+8. **Remove** drop the `setup(app, kernel)` call, drop the `BUNDLES` entry, delete
+   `<app>/config/http_kernel.py`, then `uv remove xtr-http-kernel`.
+
+## Errors
+
+All derive from `HttpKernelError`, in `xtr_http_kernel.exception`:
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidArgumentError` | an `HttpKernelConfig` field holds a value the lifecycle would misread; also a `ValueError` |
+| `InvalidMiddlewarePriorityError` | a `http_kernel.middleware` tag's `priority` is not an integer |
+| `InvalidRateLimitError` | a `RateLimited` takes fewer than one token, limits a router that already has routes, or its key function returns no string; also a `ValueError` |
+| `TooManyRequestsError` | a limiter refused the request; a 429 the framework answers, with `Retry-After` |
+| `UnknownRateLimiterError` | a `RateLimited` names a limiter the application did not configure; also a `LookupError` |
+
+A route marker resolving with no kernel attached, or outside a request scope, raises
+`FastapiIntegrationError` from xtr-dependency-injection.
+
+## Do not
+
+- Do not use `Depends` to reach a container service. Use `Injected[T]` or `Target("name")`, so
+  the service stays out of the OpenAPI schema.
+- Do not call `attach`, `detach`, `request_scope` or `provider` from
+  `xtr_dependency_injection.integration.fastapi`. They are what `setup` is built on; an
+  application calls `setup` and nothing lower.
+- Do not call `setup` after the application has started. The framework refuses new middleware
+  then, and the lifecycle would be missing.
+- Do not use `TestClient`, and do not drive the app without entering its lifespan: no kernel is
+  attached, so every marker fails.
+- Do not expect a body on `ResponseEvent`. Answer at `RequestEvent` or `ExceptionEvent` instead.
+- Do not look for a controller, controller-arguments or view event. Routing, argument resolution
+  and serialization are the framework's, deliberately.

xtr_http_kernel-3.0.0/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/references/configure.md

@@ -0,0 +1,44 @@
+# HttpKernelConfig
+
+A frozen dataclass buildable with no arguments; every field has a default. Import it from
+`xtr_http_kernel.bundle` and return it from a `@configure` function in
+`<app>/config/http_kernel.py`.
+
+```python
+from xtr_dependency_injection import configure
+
+from xtr_http_kernel.bundle import HttpKernelConfig
+
+
+@configure
+def http_kernel() -> HttpKernelConfig:
+    return HttpKernelConfig(disallow_search_indexing=True, app="app.web:app")
+```
+
+| Field | Default | What it sets |
+| --- | --- | --- |
+| `request_id_header` | `"X-Request-Id"` | the header the id is read from and echoed on; must be a non-empty HTTP token |
+| `trust_request_id` | `True` | keep a well-formed incoming id; `False` mints a fresh one every request |
+| `disallow_search_indexing` | `False` | mark every response `X-Robots-Tag: noindex` |
+| `log_channel` | `"request"` | the logging channel the error listener writes to |
+| `middleware_priority` | `0` | where the lifecycle middleware sits among the contributed factories, highest outermost |
+| `app` | `None` | the `"package.module:app"` string the router commands load the application from |
+
+## What the constructor refuses
+
+Each raises `InvalidArgumentError`, which is also a `ValueError`:
+
+- a `request_id_header` that is not an HTTP token (`"bad header"` with a space, or empty);
+- an empty `log_channel`;
+- an `app` that is not exactly one module and one attribute around a single `:`.
+
+## log_channel
+
+The bundle declares the default `request` channel on the logging config for you. An application
+renaming it must declare the new channel in its **own** logging configuration: this bundle's
+config resolves after logging's, so it cannot declare a name it does not yet know.
+
+## app
+
+Only the `debug:router` and `router:match` commands read it, and only when their `--app` option
+is left out. A served application never needs it.

xtr_http_kernel-3.0.0/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/references/listeners.md

@@ -0,0 +1,27 @@
+# The listeners the bundle registers
+
+Which ones join depends on what is installed and active. None of them needs to be listed: the
+bundle registers them.
+
+| Listener | Events | Active when | Does |
+| --- | --- | --- | --- |
+| `RequestIdListener` | `RequestEvent`, `ResponseEvent` | always | keeps a trusted incoming id or mints a `uuid4().hex`, puts it on `request.state.request_id`, binds it to the log context when logging is around, and echoes it on the response under `request_id_header` |
+| `DisallowRobotsIndexingListener` | `ResponseEvent` | always | stamps `X-Robots-Tag: noindex` on every response, when `disallow_search_indexing` turns it on |
+| `LogUnitListener` | `RequestEvent`, `TerminateEvent` | logging bundle active | opens a logging unit of work per request and closes it once all was sent |
+| `ErrorLoggingListener` | `ExceptionEvent` | logging bundle active | writes every uncaught exception to `log_channel`, at `error` below a 500 status and `critical` otherwise, leaving the response to whoever answers it |
+| `RateLimitHeadersListener` | `ResponseEvent` | rate limiter bundle active | writes the `X-RateLimit-*` headers of the limit that speaks for the response, and makes the response private |
+
+The two logging listeners open and close the unit of work outside everything else, so every
+record made while handling carries the request's id. The request id settles right after the unit
+opens, for the same reason.
+
+What this means for application code:
+
+- Read the current id from `request.state.request_id`, or from the response's
+  `request_id_header`. Do not mint your own.
+- An uncaught exception is already logged with the request that caused it. An
+  `ExceptionEvent` listener of your own should turn the failure into a response, not log it
+  again.
+- To keep every page out of a search index, set `disallow_search_indexing=True` rather than
+  writing a `ResponseEvent` listener.
+- To stop trusting an inbound id (a public edge), set `trust_request_id=False`.

xtr_http_kernel-3.0.0/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/references/rate-limits.md

@@ -0,0 +1,107 @@
+# Rate limits
+
+Needs the `rate-limiter` extra (`uv add "xtr-http-kernel[rate-limiter]"`) and limiters
+configured in [xtr-rate-limiter](https://github.com/xterr/python-xtr-rate-limiter)'s bundle.
+`RateLimited` names one of those limiters; everything else is where you put the declaration.
+
+```python
+from xtr_http_kernel.rate_limiter import RateLimited
+```
+
+## Where a declaration goes
+
+```python
+from fastapi import APIRouter, FastAPI, Request
+
+app = FastAPI(dependencies=[RateLimited("global")])  # every route
+
+
+@app.get("/books")
+@RateLimited("api", expose_headers=True)  # BELOW the route decorator
+async def list_books() -> list[Book]: ...
+
+
+@app.post("/login", dependencies=[RateLimited("login", key=by_username, methods="post")])
+async def login() -> None: ...
+
+
+reports = RateLimited("reports")(APIRouter(prefix="/reports"))  # BEFORE its routes
+app.include_router(admin, dependencies=[RateLimited("admin")])  # or when included
+```
+
+- A decorator must sit **below** the route decorator: the route reads the endpoint when it is
+  declared.
+- A router must be limited **before** routes are added, since each route copies its router's
+  dependencies. A router that already has routes raises `InvalidRateLimitError`; give the limit
+  to `include_router(..., dependencies=[...])` instead.
+- The limit runs after routing and before the endpoint, in the framework's dependency order:
+  the application's, the routers', then the route's.
+- Two declarations naming one limiter both count. The published schema is untouched: the limit
+  never appears as a parameter.
+
+## Arguments
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `limiter` | required | The name the limiter is configured under |
+| `key` | `None` | What the request is counted under |
+| `tokens` | `1` | Tokens one request consumes; below one raises `InvalidRateLimitError` |
+| `methods` | `()` | The methods limited, every one when empty. One string or an iterable, case-insensitive; `GET` also limits `HEAD` |
+| `expose_headers` | `False` | Report this limit in `X-RateLimit-*` headers |
+
+### `key`
+
+A string, or a function of the request returning a string, awaited when it returns an awaitable
+(`RateLimitKey = str | Callable[[Request], str | Awaitable[str]]`). Anything but a string raises
+`InvalidRateLimitError`.
+
+```python
+def by_username(request: Request) -> str:
+    return request.headers.get("x-username", "anonymous")
+```
+
+With no `key`, a request counts under the client's address, the method and the route's **path
+template**, so `/books/1` and `/books/2` share one count and varying a path parameter never
+earns a fresh limit. Behind a proxy the address is the proxy's unless the server trusts its
+forwarded headers (uvicorn's `--forwarded-allow-ips`).
+
+## A refusal
+
+- Answered `429 Too Many Requests` with `Retry-After`, raised as `TooManyRequestsError`. It is
+  the framework's own HTTP exception, so an exception handler registered for it reshapes the
+  body.
+- A `RateLimitExceededEvent` naming the limiter and the key is dispatched first, when an event
+  dispatcher is around.
+- Limits consulted before the refusal keep their spend.
+- A limiter the application never configured raises `UnknownRateLimiterError`, naming the ones
+  it did.
+
+## Headers
+
+With `expose_headers=True` the response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
+`X-RateLimit-Reset`, in calls rather than tokens, for the limit closest to refusing among those
+exposing theirs. A refusing limit always speaks, and a limiter that keeps its state to itself
+leaves the response without them. The response is made private, so a shared cache never serves
+one caller's count to another.
+
+## Limiting by hand
+
+For a limit that only applies in some outcome, such as throttling logins only on failure,
+inject the limiter by name like any other service:
+
+```python
+from typing import Annotated
+
+from xtr_dependency_injection import Target
+from xtr_rate_limiter import RateLimiterFactoryInterface
+
+
+@app.post("/login")
+async def login(
+    limiter: Annotated[RateLimiterFactoryInterface, Target("login")],
+) -> None:
+    limit = limiter.create(username)
+    if not (await limit.consume(0)).is_accepted():
+        raise TooManyAttempts
+    ...
+```

{xtr_http_kernel-2.0.0 → xtr_http_kernel-3.0.0}/src/xtr_http_kernel/bundle/http_kernel_bundle.py

@@ -22,7 +22,7 @@ from xtr_dependency_injection import (
     bundle_active,
     required_bundle,
 )
-from xtr_event_dispatcher.bundle import EventDispatcherBundle
+from xtr_event_dispatcher.bundle import LISTENER_TAG, EventDispatcherBundle
 
 # Read at runtime: the container fills factory parameters from annotations.
 from xtr_logging_contracts import LoggerInterface
@@ -50,9 +50,6 @@ if TYPE_CHECKING:
 
 __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.
@@ -104,17 +101,17 @@ class HttpKernelBundle(Bundle[HttpKernelConfig]):
             .set_argument("header", config.request_id_header)
             .set_argument("trust_incoming", config.trust_request_id)
             .add_tag(
-                _LISTENER_TAG,
+                LISTENER_TAG,
                 event=RequestEvent,
                 method="on_request",
                 priority=_REQUEST_ID_PRIORITY,
             )
-            .add_tag(_LISTENER_TAG, event=ResponseEvent, method="on_response")
+            .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")
+            .add_tag(LISTENER_TAG, event=ResponseEvent, method="on_response")
         )
         if bundle_active(builder, "logging"):
             # Needs the optional logging extra, which being here proves installed.
@@ -125,20 +122,20 @@ class HttpKernelBundle(Bundle[HttpKernelConfig]):
             _ = (
                 services.set(LogUnitListener)
                 .add_tag(
-                    _LISTENER_TAG,
+                    LISTENER_TAG,
                     event=RequestEvent,
                     method="on_request",
                     priority=_UNIT_OPEN_PRIORITY,
                 )
                 .add_tag(
-                    _LISTENER_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"
+                LISTENER_TAG, event=ExceptionEvent, method="on_exception"
             )
         if bundle_active(builder, "rate_limiter"):
             # Reads what the rate-limit dependency leaves on a request; the extra is installed.
@@ -147,7 +144,7 @@ class HttpKernelBundle(Bundle[HttpKernelConfig]):
             )
 
             _ = services.set(RateLimitHeadersListener).add_tag(
-                _LISTENER_TAG, event=ResponseEvent, method="on_response"
+                LISTENER_TAG, event=ResponseEvent, method="on_response"
             )
         if bundle_active(builder, "console"):
             services.load("xtr_http_kernel.command")

xtr_http_kernel-3.0.0/src/xtr_http_kernel/recipe/__init__.py

@@ -0,0 +1,15 @@
+"""This directory holds the package's recipe: its manifest.
+
+The recipe is what *Use in an application* in the README lists, written as
+data: the bundle to list, and the step only a person can take — where the
+application is built is application code, so a recipe says what to call rather
+than calling it. An application applies it with ``xtr-recipes recipes:sync``,
+which finds this module through the ``xtr_recipes`` entry point.
+
+Nothing is importable from here. The manifest is read as a file, so a recipe
+is the same from a wheel as from a working tree.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_http_kernel-3.0.0/src/xtr_http_kernel/recipe/manifest.toml

@@ -0,0 +1,24 @@
+# The recipe for xtr-http-kernel: what *Use in an application* in the README
+# takes, as data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+"xtr_http_kernel.bundle:HttpKernelBundle" = { all = true }
+
+# No [files]: nothing is required. With no configuration a request gets a uuid4
+# id under X-Request-Id, no robots header, and the "request" log channel; an
+# application changing any of that writes config/http_kernel.py itself.
+
+# No [env], and nothing to ignore.
+
+[gitignore]
+lines = []
+
+[notes]
+steps = [
+  "Call setup(app, kernel) where the application is built: the lifecycle reaches a request through it.",
+]
+check = [
+  "<script> debug:bundles — http_kernel is listed and active, event_dispatcher required",
+  "<script> debug:router — the application's routes",
+]