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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-kernel
-Version: 5.0.0
+Version: 5.1.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
@@ -484,10 +484,11 @@ removing it undoes.
   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
   outright where that parser is missing.
-- **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
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Configure* steps below:
+  it lists `HttpKernelBundle` and writes `<app>/config/packages/http_kernel.py` with the bundle's
+  own defaults. There is no 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
+- **Activate** — `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/config/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
   lifecycle dispatches through it; the [logging](../xtr-logging), [console](../xtr-console) and
@@ -496,16 +497,19 @@ removing it undoes.
   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
-  [messages](#the-request-and-the-response-as-messages). A
-  `<app>/config/http_kernel.py` `@configure` function returning an `HttpKernelConfig` changes
-  that — see [Configure](#configure) and [Kernel / bundle](#kernel--bundle).
+- **Configure** — nothing is required: the recipe writes `<app>/config/packages/http_kernel.py`
+  holding the lifecycle defaults — every request a fresh `uuid4` id under `X-Request-Id`, an
+  inbound one is not trusted, no robots header, the `request` log channel, and the request and
+  the response of a request askable as
+  [messages](#the-request-and-the-response-as-messages). Changing what that `@configure`
+  function returns changes that — see [Configure](#configure) and
+  [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing.
 - **Ignore** — nothing.
-- **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`.
+- **Remove** — drop the `setup(app, kernel)` call, drop the `BUNDLES` entry;
+  `uv run xtr-recipes recipes:remove xtr-http-kernel` deletes
+  `<app>/config/packages/http_kernel.py`, unless you edited it, in which case it is moved aside
+  to `http_kernel.py.removed`. Then `uv remove xtr-http-kernel`.
 - **Check** — `debug:bundles` shows `http_kernel` as `listed` and `active`, `event_dispatcher`
   as `required`, and (when those packages are installed) `logging` and `console` as `required`;
   `debug:router` lists the application's routes.
@@ -544,17 +548,17 @@ config resolves after logging's, so it cannot declare a name it does not yet kno
 ## Kernel / bundle
 
 An application using [xtr-dependency-injection](../xtr-dependency-injection) lists
-`HttpKernelBundle` in its `app/bundles.py`:
+`HttpKernelBundle` in its `app/config/bundles.py`:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_http_kernel.bundle import HttpKernelBundle
 
 BUNDLES = {HttpKernelBundle: {"all": True}}
 ```
 
 ```python
-# app/config/http_kernel.py
+# app/config/packages/http_kernel.py
 from xtr_dependency_injection import configure
 
 from xtr_http_kernel.bundle import HttpKernelConfig

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/README.md

@@ -454,10 +454,11 @@ removing it undoes.
   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
   outright where that parser is missing.
-- **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
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Configure* steps below:
+  it lists `HttpKernelBundle` and writes `<app>/config/packages/http_kernel.py` with the bundle's
+  own defaults. There is no 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
+- **Activate** — `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/config/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
   lifecycle dispatches through it; the [logging](../xtr-logging), [console](../xtr-console) and
@@ -466,16 +467,19 @@ removing it undoes.
   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
-  [messages](#the-request-and-the-response-as-messages). A
-  `<app>/config/http_kernel.py` `@configure` function returning an `HttpKernelConfig` changes
-  that — see [Configure](#configure) and [Kernel / bundle](#kernel--bundle).
+- **Configure** — nothing is required: the recipe writes `<app>/config/packages/http_kernel.py`
+  holding the lifecycle defaults — every request a fresh `uuid4` id under `X-Request-Id`, an
+  inbound one is not trusted, no robots header, the `request` log channel, and the request and
+  the response of a request askable as
+  [messages](#the-request-and-the-response-as-messages). Changing what that `@configure`
+  function returns changes that — see [Configure](#configure) and
+  [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing.
 - **Ignore** — nothing.
-- **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`.
+- **Remove** — drop the `setup(app, kernel)` call, drop the `BUNDLES` entry;
+  `uv run xtr-recipes recipes:remove xtr-http-kernel` deletes
+  `<app>/config/packages/http_kernel.py`, unless you edited it, in which case it is moved aside
+  to `http_kernel.py.removed`. Then `uv remove xtr-http-kernel`.
 - **Check** — `debug:bundles` shows `http_kernel` as `listed` and `active`, `event_dispatcher`
   as `required`, and (when those packages are installed) `logging` and `console` as `required`;
   `debug:router` lists the application's routes.
@@ -514,17 +518,17 @@ config resolves after logging's, so it cannot declare a name it does not yet kno
 ## Kernel / bundle
 
 An application using [xtr-dependency-injection](../xtr-dependency-injection) lists
-`HttpKernelBundle` in its `app/bundles.py`:
+`HttpKernelBundle` in its `app/config/bundles.py`:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_http_kernel.bundle import HttpKernelBundle
 
 BUNDLES = {HttpKernelBundle: {"all": True}}
 ```
 
 ```python
-# app/config/http_kernel.py
+# app/config/packages/http_kernel.py
 from xtr_dependency_injection import configure
 
 from xtr_http_kernel.bundle import HttpKernelConfig

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-kernel"
-version = "5.0.0"
+version = "5.1.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"

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-kernel"
-version = "5.0.0"
+version = "5.1.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"

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/SKILL.md

@@ -335,25 +335,26 @@ 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.
+`HttpKernelBundle` and writes `<app>/config/packages/http_kernel.py` with the bundle's own
+defaults. 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`. Installed beside it, xtr-logging adds the listeners that
    write to a log, xtr-console the router commands, xtr-rate-limiter the rate limits. None is
    needed to serve requests. The two message packages come with it, and so does the parser a
    submitted form with files in it is read with: building the request as a message asks the
    framework for the form behind every multipart body.
-2. **Activate** `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
+2. **Activate** `HttpKernelBundle: {"all": True}` in `BUNDLES` in `<app>/config/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 package is what activates them,
    not listing.
-4. **Configure** nothing by default: a fresh `uuid4` id under
-   `X-Request-Id` per request (an inbound one is not trusted), no robots header, the `request`
-   log channel.
+4. **Configure** the recipe writes `<app>/config/packages/http_kernel.py` holding the lifecycle
+   defaults: a fresh `uuid4` id under `X-Request-Id` per request (an inbound one is not trusted),
+   no robots header, the `request` log channel.
 
    ```python
-   # <app>/config/http_kernel.py
+   # <app>/config/packages/http_kernel.py
    from xtr_dependency_injection import configure
 
    from xtr_http_kernel.bundle import HttpKernelConfig
@@ -372,8 +373,10 @@ prints for you to make.
 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`.
+8. **Remove** drop the `setup(app, kernel)` call, drop the `BUNDLES` entry;
+   `uv run xtr-recipes recipes:remove xtr-http-kernel` deletes
+   `<app>/config/packages/http_kernel.py`, unless you edited it, in which case it is moved aside
+   to `http_kernel.py.removed`. Then `uv remove xtr-http-kernel`.
 
 ## Errors
 

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/src/xtr_http_kernel/.agents/skills/xtr-http-kernel/references/configure.md

@@ -2,7 +2,7 @@
 
 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`.
+`<app>/config/packages/http_kernel.py`.
 
 ```python
 from xtr_dependency_injection import configure

xtr_http_kernel-5.1.0/src/xtr_http_kernel/recipe/files/config/http_kernel.py.tmpl

@@ -0,0 +1,27 @@
+"""The request lifecycle: request ids, the error log, and the application the commands read.
+
+```python
+HttpKernelConfig(app="${app}.web.app:app", disallow_search_indexing=True)
+```
+"""
+
+from __future__ import annotations
+
+from xtr_dependency_injection import configure
+from xtr_http_kernel.bundle import HttpKernelConfig
+
+__all__ = ["http_kernel"]
+
+
+@configure
+def http_kernel() -> HttpKernelConfig:
+    """A fresh request id per request, and uncaught errors written to the request channel."""
+    # Set app to the "package.module:app" the router commands load, so debug:router and
+    # router:match need no --app.
+    #
+    # Every response echoes the X-Request-Id header, unless request_id_header names another.
+    # trust_request_id keeps the id a caller sent: turn it on only behind a proxy you control.
+    #
+    # disallow_search_indexing marks every response noindex; log_channel names the channel
+    # uncaught errors are written to.
+    return HttpKernelConfig()

{xtr_http_kernel-5.0.0 → xtr_http_kernel-5.1.0}/src/xtr_http_kernel/recipe/manifest.toml

@@ -5,11 +5,13 @@
 # "<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. A
-# bundle's recipe writing a routes file under config/routes/ gets that package
-# created by xtr-recipes itself.
+[files]
+# Destination under the application package = template under this recipe.
+# The bundle's own defaults written out — a uuid4 id under X-Request-Id, no
+# robots header, the "request" log channel — as the place to change them and to
+# name the application the router commands read. A bundle's recipe writing a
+# routes file under config/routes/ gets that package created by xtr-recipes.
+"config/packages/http_kernel.py" = "files/config/http_kernel.py.tmpl"
 
 # No [env], and nothing to ignore.