xtr-http-kernel 4.0.4__tar.gz → 5.0.0__tar.gz

{xtr_http_kernel-4.0.4 → xtr_http_kernel-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-kernel
-Version: 4.0.4
+Version: 5.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,23 +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]>=4.0,<5
-Requires-Dist: xtr-event-dispatcher>=4.0,<5
-Requires-Dist: xtr-event-dispatcher-contracts>=4.0,<5
-Requires-Dist: xtr-http-message>=4.0,<5
-Requires-Dist: xtr-http-message-contracts>=4.0,<5
-Requires-Dist: xtr-logging-contracts>=4.0,<5
-Requires-Dist: xtr-service-contracts>=4.0,<5
+Requires-Dist: xtr-dependency-injection>=5.0,<6
+Requires-Dist: xtr-event-dispatcher>=5.0,<6
+Requires-Dist: xtr-event-dispatcher-contracts>=5.0,<6
+Requires-Dist: xtr-http-message>=5.0,<6
+Requires-Dist: xtr-http-message-contracts>=5.0,<6
+Requires-Dist: xtr-logging-contracts>=5.0,<6
+Requires-Dist: xtr-service-contracts>=5.0,<6
 Requires-Dist: typing-extensions>=4.4
 Requires-Dist: python-multipart>=0.0.18
-Requires-Dist: xtr-console>=4.0,<5 ; extra == 'console'
-Requires-Dist: xtr-logging>=4.0,<5 ; extra == 'logging'
-Requires-Dist: xtr-clock>=4.0,<5 ; extra == 'rate-limiter'
-Requires-Dist: xtr-rate-limiter[di]>=4.0,<5 ; extra == 'rate-limiter'
 Requires-Python: >=3.11
-Provides-Extra: console
-Provides-Extra: logging
-Provides-Extra: rate-limiter
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -75,16 +68,17 @@ Listeners are services, so they come from the container with everything else the
 ## Install
 
 ```sh
-uv add xtr-http-kernel                      # the lifecycle, its bundle and setup
-uv add "xtr-http-kernel[logging]"           # + the listeners that log
-uv add "xtr-http-kernel[console]"           # + the commands that report on the router
-uv add "xtr-http-kernel[rate-limiter]"      # + rate limits on routes, routers and the app
+uv add xtr-http-kernel     # the lifecycle, its bundle and setup
+uv add xtr-logging         # beside it: the listeners that log
+uv add xtr-console         # beside it: the commands that report on the router
+uv add xtr-rate-limiter    # beside it: rate limits on routes, routers and the app
 ```
 
 Requires Python 3.11+. The web framework and the container layer come with the package
-itself — this *is* the integration — so neither is an extra, and neither is the
-[HTTP message contract](../xtr-http-message-contracts) or
-[its implementation](../xtr-http-message): the bridge below is made of them.
+itself — this *is* the integration — and so do the
+[HTTP message contract](../xtr-http-message-contracts) and
+[its implementation](../xtr-http-message): the bridge below is made of them. The three
+packages beside it are optional: each is used when it is installed and left alone when not.
 
 ## Quick start
 
@@ -169,7 +163,10 @@ surfaces then, rather than a request running without its lifecycle.
 ## The lifecycle
 
 Every request goes through the same events, and a listener joins wherever it has something to
-contribute. Each is dispatched at most once, however the request went:
+contribute. Each is dispatched at most once, however the request went, and each carries the
+request as a message — the served request below — plus `state`, the per-request state bag the
+framework's own `request.state` wraps: what a listener puts there, the framework and every other
+listener read:
 
 | Event | `KernelEvents` | When | What a listener may do |
 |---|---|---|---|
@@ -250,12 +247,34 @@ async def issue(
     return response.with_status(201).with_header("content-type", "application/json")
 ```
 
-- **Built only when asked.** The request is built the first time something asks for it, from
-  FastAPI's own request object — the body it already read, the form it already parsed. A route
-  that does not ask pays nothing, and nothing is buffered anywhere.
-- **Once per request.** Both are `lifetime="scoped"`, so every endpoint, dependency and service
-  of one request sees the same request message and the same response. `RequestInterface` and
-  `MessageInterface` lead to the same build, so a parameter typed by any of the three gets it.
+- **The served request, read through the connection.** The request the events carry is the
+  message package's own `ServerRequest`, born connected over the bridge's `ServedConnection`:
+  its head — method, URI, headers, cookies, query parameters, environment parameters, protocol
+  version — is read straight off the connection, and its body is one lazy stream. Nothing is
+  read off the wire until a listener or an endpoint reads that stream; the first read
+  materialises the whole body once, parsing it per its content type on the way, and every later
+  read is served out of the buffer, seekable and rewindable. One instance is parked on the
+  connection's scope, so the events, the scoped `server_request` service and a route's injected
+  message are all the same object.
+- **A listener that reads the body drains the wire** — so the application is handed a `receive`
+  that replays the buffered bytes, and its routes read the body the caller sent as if nobody
+  had. A request no listener reads passes its original channel through untouched: nothing is
+  buffered unless something asks to read it.
+- **The parsed body answers by the time an endpoint asks.** A body that has a parsed side — a
+  form, JSON — is materialised before the container hands the message to a service or an
+  endpoint, so `get_parsed_body()` and `get_uploaded_files()` answer what the message contract
+  promises, unconditionally, for every consumer written against it. A body with no parsed side
+  is left unread. The events carry the message as it stands: a listener that asks for fields
+  reads the body stream first, and the reading parses — the one place the contract's wording
+  still needs that order, and a listener is the one consumer that can await.
+- **The attributes are live.** `get_attributes()` reads the matched route's path parameters as
+  they are now — routing fills them after the message exists. The `with_*` members return plain
+  copies: immutable snapshots of the message as it stands, so a change a listener makes never
+  reaches the connection.
+- **Once per request.** Both the request and the response are `lifetime="scoped"`, so every
+  endpoint, dependency and service of one request sees the same request message and the same
+  response. `RequestInterface` and `MessageInterface` lead to the same build, so a parameter
+  typed by any of the three gets it.
 - **One response, two names.** `xtr_http_kernel.bridge.Response` and `ResponseInterface` lead to
   that same build: an endpoint asks for the class and declares it returns it — parameter and
   return annotation the same type, nothing to narrow and nothing to configure — while a library
@@ -319,7 +338,7 @@ one:
 
 | Service | Does |
 |---|---|
-| `HttpMessageFactoryInterface` | `await create_request(request)` and `create_response(response)`: the framework's own, as messages |
+| `HttpMessageFactoryInterface` | `serve(request)`: the framework's own request, as a served request — a read-through view nothing has read the body of; `await create_request(request)` and `create_response(response)`: the framework's own, as messages read whole |
 | `StarletteHttpFactoryInterface` | `await create_request(message, streamed=False)` and `await create_response(message, streamed=False)`: a message, as the framework's own |
 
 A response that arrived from outside the application — one a worker built with
@@ -363,11 +382,11 @@ The bundle registers these; which ones depend on what is installed and active:
 
 | Listener | Events | Active when | Does |
 |---|---|---|---|
-| `RequestIdListener` | `RequestEvent`, `ResponseEvent` | always | mints a `uuid4().hex` — or keeps a well-formed incoming id, where `trust_request_id` says to — puts it on `request.state.request_id`, binds it to the log context when logging is around, and echoes it on the response |
+| `RequestIdListener` | `RequestEvent`, `ResponseEvent` | always | mints a `uuid4().hex` — or keeps a well-formed incoming id, where `trust_request_id` says to — puts it on the request's state bag, binds it to the log context when logging is around, and echoes it on the response |
 | `DisallowRobotsIndexingListener` | `ResponseEvent` | always | stamps `X-Robots-Tag: noindex` on every response, when the config turns it on |
 | `LogUnitListener` | `RequestEvent`, `TerminateEvent` | logging bundle active | opens a [logging unit of work](../xtr-logging#units-of-work) per request and closes it once all was sent |
 | `ErrorLoggingListener` | `ExceptionEvent` | logging bundle active | writes every uncaught exception to the request channel — `info` for a cancellation, an interrupt or an exit, `error` below a 500 status, `critical` otherwise — leaving the response to whoever answers it |
-| `RateLimitHeadersListener` | `ResponseEvent` | rate limiter bundle active | writes the `X-RateLimit-*` headers of the [rate limit](#rate-limits) that speaks for the response, and makes it private |
+| `RateLimitHeadersListener` | `ResponseEvent` | rate limiter bundle active | writes the `X-RateLimit-*` headers of the [rate limit](#rate-limits) that speaks for the response — the one a route's limit left on the request's state bag — and makes it private |
 
 The two logging listeners join only when the logging bundle is active, and open and close the
 unit of work outside everything else so every record made while handling carries the request's
@@ -375,9 +394,10 @@ id. The request id settles right after the unit opens, for the same reason.
 
 ## Rate limits
 
-With the `rate-limiter` extra, a route, a router or the whole application can be held to a
-limiter configured in [xtr-rate-limiter](../xtr-rate-limiter)'s bundle. `RateLimited` is one
-declaration, written as a decorator or wherever the framework takes a dependency:
+With [xtr-rate-limiter](../xtr-rate-limiter) installed beside this package, a route, a router or
+the whole application can be held to a limiter configured in that package's bundle.
+`RateLimited` is one declaration, written as a decorator or wherever the framework takes a
+dependency:
 
 ```python
 from fastapi import APIRouter, FastAPI, Request
@@ -454,11 +474,12 @@ Everything adding this package to an application on
 [xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what
 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. The
+- **Install** — `uv add xtr-http-kernel`; install [xtr-logging](../xtr-logging) beside it for
+  the listeners that write to a log, [xtr-console](../xtr-console) for the commands that report
+  on the router, [xtr-rate-limiter](../xtr-rate-limiter) for the [rate limits](#rate-limits).
+  None is needed to serve requests. The
   [HTTP message contract](../xtr-http-message-contracts) and
-  [its implementation](../xtr-http-message) come with the package, not behind an extra: the
+  [its implementation](../xtr-http-message) come with the package: the
   [messages](#the-request-and-the-response-as-messages) are part of what it does. So does the
   parser a submitted form with files in it is read with: building the request as a message
   asks the web framework for the form behind every multipart body, and the framework refuses
@@ -470,10 +491,11 @@ removing it undoes.
   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
   lifecycle dispatches through it; the [logging](../xtr-logging), [console](../xtr-console) and
-  [rate limiter](../xtr-rate-limiter) bundles whenever those packages are *installed* — they are required peers, pulled in and made
-  active without being listed, and left out silently when the package is not installed. Listing
-  is not what activates them; installing the extra is. No bundle comes along for the messages:
-  neither message package ships one, and this bundle registers their services itself.
+  [rate limiter](../xtr-rate-limiter) bundles whenever those packages are *installed* — they are
+  required peers, pulled in and made active without being listed, and left out silently when the
+  package is not installed. Listing is not what activates them; installing the package is. No
+  bundle comes along for the messages: neither message package ships one, and this bundle
+  registers their services itself.
 - **Configure** — nothing is required: the zero-config path gives every request a fresh `uuid4`
   id under `X-Request-Id` — an inbound one is not trusted — no robots header, and the `request`
   log channel, and makes the request and the response of a request askable as
@@ -485,8 +507,8 @@ removing it undoes.
 - **Remove** — drop the `setup(app, kernel)` call, drop the `BUNDLES` entry, delete
   `<app>/config/http_kernel.py` if you wrote one, then `uv remove xtr-http-kernel`.
 - **Check** — `debug:bundles` shows `http_kernel` as `listed` and `active`, `event_dispatcher`
-  as `required`, and (with the extras) `logging` and `console` as `required`; `debug:router`
-  lists the application's routes.
+  as `required`, and (when those packages are installed) `logging` and `console` as `required`;
+  `debug:router` lists the application's routes.
 
 ## Configure
 
@@ -572,96 +594,98 @@ offending definition.
 
 ## Routes
 
-A bundle ships its routes, and an application gets them served with no code in its entry point.
-The application arranges them in its routes files, and `setup` adds the result.
+Routes are native framework routes, end to end. A package ships them as *route resources* —
+named routers its registration functions fill — and an application registers them in its
+routes files. **Routing is never imported automatically:** a resource no routes file includes
+is not served. The file a package's recipe writes into `<app>/config/routes/` is what
+registers its endpoints; deleting the file uninstalls them.
 
-### A bundle's routes
+### What a package ships
 
-A route loader is a class with `load_routes()`, declared with `@as_route_loader`. It names the
-*resource* an application imports its routes by:
+A route resource is a plain function declared with `@as_route_resource`, filling an
+`APIRouter` with the framework's own routes:
 
 ```python
-from xtr_http_kernel.routing import Route, RouteCollection
-from xtr_http_kernel.routing.decorator import as_route_loader
+from fastapi import APIRouter
+from xtr_http_kernel.routing.decorator import as_route_resource
 
 
-async def list_books() -> list[str]:
-    return ["Dune"]
+@as_route_resource("books")
+def books_routes(router: APIRouter) -> None:
+    """Fill the router with the books endpoints."""
 
+    @router.get("/books", name="books_list")
+    async def list_books() -> list[str]:
+        return ["Dune"]
 
-@as_route_loader("books")
-class BooksRouteLoader:
-    def load_routes(self) -> RouteCollection:
-        routes = RouteCollection()
-        routes.add("books_list", Route("/books", list_books, methods=("GET",)))
-        return routes
+    @router.get("/books/{book_id}", name="books_show")
+    async def show_book(book_id: str) -> dict[str, str]:
+        return {"book": book_id}
 ```
 
-The loader is built with no arguments while the kernel compiles, before any service exists, so
-what it contributes is fixed by the code that ships it. A route a deployment turns off keeps
-answering — its endpoint refuses — and an application that wants it gone leaves it out in a
-routes file. Pass `prefixable=False` for routes a standard puts at a fixed place, such as a
-`/.well-known/` document: no routes file may move them under a prefix. A loader is found like any
-other declaration: in the application's scan, or in a module a bundle scans with
-`services.load(...)`.
-
-A `Route` carries a path, the endpoint the framework calls — its `Injected[...]` parameters
-untouched — and the options handed to the framework as they are: `methods`,
-`include_in_schema`, `tags`, `summary`, `status_code`, `response_model`. Its name is the key it
-has in its `RouteCollection`. A mounted route validates, documents and is reached by
-`url_path_for` exactly like the same function declared on a router.
+Everything the framework's own decorators take — `dependencies=`, `response_class`,
+`openapi_extra`, websockets — a resource takes: there is no layer in between. An endpoint
+needing a service declares it `Injected[...]` as anywhere else; a controller is a service
+like any other, and an application replaces one the way it replaces any service — its own
+definition of the type outranks a bundle's.
+
+The function is found like any other declaration — in the application's scan, or in a module
+a bundle scans with `services.load(...)` — and `setup` calls it once per resource with a
+fresh router, no services and no side effects: what a package contributes is fixed by the
+code that ships it. Several functions may fill one resource; two routes of a resource
+claiming one name are refused while staging. A route keeps the name it was declared with —
+`url_path_for`, and anything building a URL a stranger keeps, builds it by name — and a
+route a deployment turns off keeps answering: its endpoint refuses, and an application that
+wants it gone filters it out of the staged router.
 
 ### The application's routes files
 
-A routes file is a function declared `@as_routes` in `<app>/config/routes/`, receiving a
-`RoutingConfigurator`:
+A routes file is a function declared `@as_routes` in `<app>/config/routes/`, receiving the
+application and every staged resource as a native router:
 
 ```python
 from xtr_http_kernel.routing.decorator import as_routes
-from xtr_http_kernel.routing.loader.configurator import RoutingConfigurator
 
 
 @as_routes
-def shop(routes: RoutingConfigurator) -> None:
-    routes.import_("books").prefix("/shop").name_prefix("shop_")
-    routes.add("shop_books_list", "/shop/catalogue")  # move one route by its name
-    routes.add("home", "/").endpoint(home).methods("GET")
-
-
-async def home() -> dict[str, str]:
-    return {"page": "home"}
+def shop(app: FastAPI, resources: Mapping[str, APIRouter]) -> None:
+    """Serve the books under /shop, under renamed names."""
+    books = resources["books"]
+    for route in books.routes:
+        route.name = f"shop_{route.name}"
+    app.include_router(books, prefix="/shop")
 ```
 
-- `import_(resource)` brings in a resource's routes, arranged with `prefix`, `name_prefix` and
-  `exclude(*names)`; `skip(resource)` serves none of them. A resource no routes file imports or
-  skips is served at its own paths and names.
-- `add(name, path)` defines a route. Under a name already in the table it replaces that route:
-  without `.endpoint(...)` it moves the route and keeps the rest, with one it redefines it. Its
-  options — `methods`, `priority`, `tags`, `summary`, `status_code`, `include_in_schema`,
-  `response_model` — read like the `Route` fields.
-- `collection(name_prefix)` groups routes under one path prefix and name prefix;
-  `alias(name, target)` adds another name for a route, optionally `.deprecate(...)`d.
-- Nothing reaches the table while the file runs: every call is applied when it returns, in the
-  order written, so a route defined after an import replaces the imported one of that name.
-  Each file starts from the resources as their loaders returned them.
-
-A mistake is refused while the kernel compiles — so at `setup` — with an `InvalidArgumentError`
-naming it: an unknown resource or route, a prefix on fixed routes, a new route with no endpoint,
-two loaders claiming one resource. The kernel scans only packages, so `config/routes/` needs an
-`__init__.py`; xtr-recipes creates it with the first routes file a recipe writes there.
+The arrangement is native calls on a staged router — before it is included, so nothing
+mounted is ever rebuilt:
+
+- **Serve** — `app.include_router(resources["books"])`.
+- **Move** — `app.include_router(resources["books"], prefix="/shop")`.
+- **Skip** — do not include it; omission is the skip.
+- **Leave one route out** — `books.routes = [r for r in books.routes if r.name != "books_show"]`
+  before including.
+- **Rename the group** — the loop above sets `route.name` (and `route.operation_id`, when the
+  description matters); the framework has no name-prefixed include.
+- **Replace a route** — declare the application's own before `setup` — the application's
+  routes come first — and filter the contributed one out of its resource.
+
+The files run in scan order, and each sees the resources as staged. A resource is included by
+the first file including it; a second include of one is refused, as every name of it would
+land twice. A mistake is refused at `setup` with an `InvalidArgumentError` naming it: a file
+asking for a resource nothing installed contributes, two routes of one resource claiming one
+name. The kernel scans only packages, so `config/routes/` needs an `__init__.py`; xtr-recipes
+creates it with the first routes file a recipe writes there.
 
 ### Collisions with the application's own routes
 
-The application's own routes are never changed, and they come first. A contributed route sharing
-a name with one the application declared, or one the application's routes would answer first —
-the same method and path under any parameter names, a catch-all, a mount, or a router the
-application included — fails `setup` with a `RouteConflictError` naming both; so do two
-contributed routes answering the same method and path. To change a contributed route on purpose,
-redefine it by its name in a routes file.
-
-An alias is mounted under its own name, out of the API description, so `url_path_for` reaches it.
-The table is also a service: `RouterInterface.get_route_collection()` returns a copy of what was
-mounted, the same on every start of the application, for code that reads a route by name.
+The application's own routes — the ones declared before `setup` — are never changed, and they
+come first: a catch-all or a mount of the application's shadowing a contributed route is the
+application's own doing, and `router:match` answers who serves what. What `setup` refuses with
+a `RouteConflictError` naming both is the silent kind: a contributed route sharing a name with
+one the application declared, so `url_path_for` would guess; a contributed route answering a
+method at the path shape of one the application declared — parameters told apart by shape, not
+by name; and two contributed routes answering one method and path, the second of which no
+request could ever reach.
 
 ## Router commands
 
@@ -740,20 +764,20 @@ itself, as well as from `xtr_http_kernel.exception`.
 | `UnknownRateLimiterError` | a `RateLimited` names a limiter the application did not configure; also a `LookupError` |
 | `UnsupportedConnectionError` | something asked for the request as a message while a WebSocket was being served |
 
-The route table's errors live in `xtr_http_kernel.routing`, under `RoutingError` — itself an
+The routing layer's errors live in `xtr_http_kernel.routing`, under `RoutingError` — itself an
 `HttpKernelError`:
 
 | Error | Raised when |
 |---|---|
-| `InvalidArgumentError` | a routes file names an unknown resource or route, prefixes fixed routes, defines a route with no endpoint, or is `async`; one file skips a resource another imports; two loaders claim one resource, or two resources no file arranges contribute one name; a loader needs arguments or has an `async` `load_routes`; an alias is refused. Also the library's own `InvalidArgumentError`, so a `ValueError` |
-| `RouteConflictError` | `setup` finds a contributed route sharing a name with one the application declared, or answered first by one of the application's routes, or answering the same method and path as another contributed route |
-| `RouteCircularReferenceError` | aliases lead back to a name they already passed |
+| `InvalidArgumentError` | a routes file asks for a resource nothing installed contributes, or is `async`; two routes of one resource claim one name; `@as_route_resource` decorates anything but a plain function, or names no resource. Also the library's own `InvalidArgumentError`, so a `ValueError` |
+| `RouteConflictError` | `setup` finds a contributed route sharing a name with one the application declared, answering a method at the path shape of one the application declared, or answering a method and path shape another contributed route answers; or a resource included twice |
 
 ## Layout
 
 ```
 xtr_http_kernel/
 ├── setup.py                        setup(app, kernel), the one call an application makes
+├── _staging.py                     stages the resources, runs the routes files, refuses the collisions
 ├── testing.py                      override_services, for a served application under test
 ├── bridge/                         the request and the response as HTTP messages, both ways
 ├── event/                          the five lifecycle events, one class per file
@@ -762,8 +786,8 @@ xtr_http_kernel/
 ├── request_lifecycle_middleware.py the middleware that dispatches the events
 ├── middleware_stack.py             the ordered chain a bundle contributes to
 ├── middleware_tag.py               MIDDLEWARE_TAG, the tag bundles agree on
-├── rate_limiter/                   RateLimited, with the rate-limiter extra
-├── routing/                        Route, RouteCollection, Router, the loaders and configurators
+├── rate_limiter/                   RateLimited, when xtr-rate-limiter is installed
+├── routing/                        as_route_resource, as_routes, the registry setup stages from
 ├── command/                        debug:router and router:match
 ├── exception/                      HttpKernelError, the root of everything this library raises
 └── bundle/                         HttpKernelBundle and HttpKernelConfig
@@ -776,7 +800,7 @@ Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, und
 repository is a read-only copy, so send issues and pull requests to the monorepo.
 
 ```sh
-uv sync --all-extras
+uv sync
 uv run ruff check
 uv run ruff format --check
 uv run basedpyright