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

xtr_http_kernel-1.4.0/README.md → xtr_http_kernel-2.0.0/PKG-INFO

@@ -1,3 +1,37 @@
+Metadata-Version: 2.4
+Name: xtr-http-kernel
+Version: 2.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
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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: 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-Python: >=3.11
+Provides-Extra: console
+Provides-Extra: logging
+Provides-Extra: rate-limiter
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 # xtr-http-kernel
@@ -38,6 +72,7 @@ Listeners are services, so they come from the container with everything else the
 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
 ```
 
 Requires Python 3.11+. The web framework and the container layer come with the package
@@ -124,7 +159,7 @@ contribute. Each is dispatched at most once, however the request went:
 |---|---|---|---|
 | `RequestEvent` | `REQUEST` | it arrived, nothing has looked at it | read it, or `set_response(...)` to answer instead of the application |
 | `ResponseEvent` | `RESPONSE` | a response is about to start | assign `status_code`, change `headers` in place |
-| `ExceptionEvent` | `EXCEPTION` | handling raised, nothing was sent | read `exception`, or `set_response(...)` to answer with it |
+| `ExceptionEvent` | `EXCEPTION` | handling raised, nothing was sent | read `exception`, or `set_response(...)` to answer with it — an `Exception` only: a cancellation, interrupt or exit is announced and goes on |
 | `FinishRequestEvent` | `FINISH_REQUEST` | handling finished — **on every path** | put away what the request set up |
 | `TerminateEvent` | `TERMINATE` | everything was sent | work worth doing once the caller has their answer |
 
@@ -194,11 +229,87 @@ The bundle registers these; which ones depend on what is installed and active:
 | `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 — `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 |
 
 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
 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:
+
+```python
+from fastapi import APIRouter, FastAPI, Request
+
+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]: ...
+
+
+def by_username(request: Request) -> str:
+    return request.headers.get("x-username", "anonymous")
+
+
+@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
+```
+
+- **Where it runs.** After routing and before the endpoint: routing is the framework's, so the
+  limit is a dependency rather than a lifecycle listener, and runs in the framework's order —
+  the application's, the routers', then the route's. As a decorator it must sit **below** the
+  route decorator, which reads the endpoint when the route is declared; a router must be
+  limited **before** routes are added, since each route copies its router's dependencies.
+- **What a request is counted under.** `key` is a string, or a function of the request —
+  awaited when it returns an awaitable. By default: the client's address, the method and the
+  route's path template — `/books/{isbn}`, so asking for another book 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`).
+- **`tokens`** a request consumes, and **`methods`** limited — every one when empty; `GET` also
+  limits `HEAD`.
+- **A refusal** is answered `429 Too Many Requests` with `Retry-After`, raised as
+  `TooManyRequestsError` — 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. Limits consulted before a refusal keep their spend.
+- **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 one 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.
+- **The published schema** is untouched: the limit never appears as a parameter.
+
+A limiter the application did not configure fails the request with `UnknownRateLimiterError`,
+naming the ones it did. To limit by hand — throttling logins only on failure, say — inject the
+limiter by name like any 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
+    ...
+```
+
 ## Use in an application
 
 Everything adding this package to an application on
@@ -206,13 +317,13 @@ Everything adding this package to an application on
 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. Neither is needed to
-  serve requests.
+  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.
 - **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
-  lifecycle dispatches through it; the [logging](../xtr-logging) and [console](../xtr-console)
-  bundles whenever those packages are *installed* — they are required peers, pulled in and made
+  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.
 - **Configure** — nothing is required: the zero-config path gives a `uuid4` request id under
@@ -243,7 +354,7 @@ default:
 
 The constructor refuses values the lifecycle would silently misread: a `request_id_header` that
 is not an HTTP token, an empty `log_channel`, or an `app` that is not exactly one module and one
-attribute around a single `:`, each raise `ValueError`.
+attribute around a single `:`, each raise `InvalidArgumentError` — also a `ValueError`.
 
 The bundle declares the default `log_channel` on the logging config for you. An application
 renaming it must declare the new channel in its own logging configuration — this bundle's
@@ -352,6 +463,8 @@ async def test_it_uses_the_fake_catalogue() -> None:
 ```
 
 A key is a type, or a `(type, qualifier)` pair for a qualified service.
+The overrides live on the application itself, so two tests serving one application must not
+run at the same time: the block that exits last would restore what the other replaced.
 
 ## Errors
 
@@ -360,7 +473,11 @@ typed attributes rather than only a message.
 
 | 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` |
 
 ## Layout
 
@@ -374,6 +491,7 @@ 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
 ├── command/                        debug:router and router:match
 ├── exception/                      HttpKernelError, the root of everything this library raises
 └── bundle/                         HttpKernelBundle and HttpKernelConfig

xtr_http_kernel-1.4.0/PKG-INFO → xtr_http_kernel-2.0.0/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: xtr-http-kernel
-Version: 1.4.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: Razvan Ceana
-Author-email: Razvan Ceana <razvan@ceana.ro>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-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]>=1.0,<2
-Requires-Dist: xtr-event-dispatcher>=1.0,<2
-Requires-Dist: xtr-event-dispatcher-contracts>=1.0,<2
-Requires-Dist: xtr-logging-contracts>=1.0,<2
-Requires-Dist: xtr-service-contracts>=1.0,<2
-Requires-Dist: typing-extensions>=4.4
-Requires-Dist: xtr-console>=1.0,<2 ; extra == 'console'
-Requires-Dist: xtr-logging>=1.0,<2 ; extra == 'logging'
-Requires-Python: >=3.11
-Provides-Extra: console
-Provides-Extra: logging
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 # xtr-http-kernel
@@ -69,6 +38,7 @@ Listeners are services, so they come from the container with everything else the
 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
 ```
 
 Requires Python 3.11+. The web framework and the container layer come with the package
@@ -155,7 +125,7 @@ contribute. Each is dispatched at most once, however the request went:
 |---|---|---|---|
 | `RequestEvent` | `REQUEST` | it arrived, nothing has looked at it | read it, or `set_response(...)` to answer instead of the application |
 | `ResponseEvent` | `RESPONSE` | a response is about to start | assign `status_code`, change `headers` in place |
-| `ExceptionEvent` | `EXCEPTION` | handling raised, nothing was sent | read `exception`, or `set_response(...)` to answer with it |
+| `ExceptionEvent` | `EXCEPTION` | handling raised, nothing was sent | read `exception`, or `set_response(...)` to answer with it — an `Exception` only: a cancellation, interrupt or exit is announced and goes on |
 | `FinishRequestEvent` | `FINISH_REQUEST` | handling finished — **on every path** | put away what the request set up |
 | `TerminateEvent` | `TERMINATE` | everything was sent | work worth doing once the caller has their answer |
 
@@ -225,11 +195,87 @@ The bundle registers these; which ones depend on what is installed and active:
 | `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 — `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 |
 
 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
 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:
+
+```python
+from fastapi import APIRouter, FastAPI, Request
+
+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]: ...
+
+
+def by_username(request: Request) -> str:
+    return request.headers.get("x-username", "anonymous")
+
+
+@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
+```
+
+- **Where it runs.** After routing and before the endpoint: routing is the framework's, so the
+  limit is a dependency rather than a lifecycle listener, and runs in the framework's order —
+  the application's, the routers', then the route's. As a decorator it must sit **below** the
+  route decorator, which reads the endpoint when the route is declared; a router must be
+  limited **before** routes are added, since each route copies its router's dependencies.
+- **What a request is counted under.** `key` is a string, or a function of the request —
+  awaited when it returns an awaitable. By default: the client's address, the method and the
+  route's path template — `/books/{isbn}`, so asking for another book 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`).
+- **`tokens`** a request consumes, and **`methods`** limited — every one when empty; `GET` also
+  limits `HEAD`.
+- **A refusal** is answered `429 Too Many Requests` with `Retry-After`, raised as
+  `TooManyRequestsError` — 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. Limits consulted before a refusal keep their spend.
+- **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 one 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.
+- **The published schema** is untouched: the limit never appears as a parameter.
+
+A limiter the application did not configure fails the request with `UnknownRateLimiterError`,
+naming the ones it did. To limit by hand — throttling logins only on failure, say — inject the
+limiter by name like any 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
+    ...
+```
+
 ## Use in an application
 
 Everything adding this package to an application on
@@ -237,13 +283,13 @@ Everything adding this package to an application on
 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. Neither is needed to
-  serve requests.
+  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.
 - **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
-  lifecycle dispatches through it; the [logging](../xtr-logging) and [console](../xtr-console)
-  bundles whenever those packages are *installed* — they are required peers, pulled in and made
+  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.
 - **Configure** — nothing is required: the zero-config path gives a `uuid4` request id under
@@ -274,7 +320,7 @@ default:
 
 The constructor refuses values the lifecycle would silently misread: a `request_id_header` that
 is not an HTTP token, an empty `log_channel`, or an `app` that is not exactly one module and one
-attribute around a single `:`, each raise `ValueError`.
+attribute around a single `:`, each raise `InvalidArgumentError` — also a `ValueError`.
 
 The bundle declares the default `log_channel` on the logging config for you. An application
 renaming it must declare the new channel in its own logging configuration — this bundle's
@@ -383,6 +429,8 @@ async def test_it_uses_the_fake_catalogue() -> None:
 ```
 
 A key is a type, or a `(type, qualifier)` pair for a qualified service.
+The overrides live on the application itself, so two tests serving one application must not
+run at the same time: the block that exits last would restore what the other replaced.
 
 ## Errors
 
@@ -391,7 +439,11 @@ typed attributes rather than only a message.
 
 | 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` |
 
 ## Layout
 
@@ -405,6 +457,7 @@ 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
 ├── command/                        debug:router and router:match
 ├── exception/                      HttpKernelError, the root of everything this library raises
 └── bundle/                         HttpKernelBundle and HttpKernelConfig

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-kernel"
-version = "1.4.0"
+version = "2.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,21 +27,25 @@ classifiers = [
 dependencies = [
     "fastapi>=0.121.3",
     "starlette>=0.40",
-    "xtr-dependency-injection[fastapi]>=1.0,<2",
-    "xtr-event-dispatcher>=1.0,<2",
-    "xtr-event-dispatcher-contracts>=1.0,<2",
-    "xtr-logging-contracts>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "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",
     "typing-extensions>=4.4",
 ]
 
 [[project.authors]]
-name = "Razvan Ceana"
-email = "razvan@ceana.ro"
+name = "Xterr"
+email = "me@xterr.dev"
 
 [project.optional-dependencies]
-logging = ["xtr-logging>=1.0,<2"]
-console = ["xtr-console>=1.0,<2"]
+logging = ["xtr-logging>=2.0,<3"]
+console = ["xtr-console>=2.0,<3"]
+rate-limiter = [
+    "xtr-clock>=2.0,<3",
+    "xtr-rate-limiter[di]>=2.0,<3",
+]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 http_kernel = "xtr_http_kernel.bundle:HttpKernelBundle"
@@ -54,8 +58,10 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-logging>=1.0,<2",
-    "xtr-console>=1.0,<2",
+    "xtr-logging>=2.0,<3",
+    "xtr-console>=2.0,<3",
+    "xtr-clock>=2.0,<3",
+    "xtr-rate-limiter[di]>=2.0,<3",
     "httpx>=0.27",
 ]
 

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

@@ -1,13 +1,13 @@
 [project]
 name = "xtr-http-kernel"
-version = "1.4.0"
+version = "2.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"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
-    { name = "Razvan Ceana", email = "razvan@ceana.ro" }
+    { name = "Xterr", email = "me@xterr.dev" }
 ]
 keywords = ["http", "kernel", "request", "lifecycle", "events", "middleware", "fastapi"]
 classifiers = [
@@ -26,20 +26,24 @@ dependencies = [
     "fastapi>=0.121.3",
     # Imported directly — requests, responses, middleware — not only through fastapi.
     "starlette>=0.40",
-    "xtr-dependency-injection[fastapi]>=1.0,<2",
-    "xtr-event-dispatcher>=1.0,<2",
-    "xtr-event-dispatcher-contracts>=1.0,<2",
-    "xtr-logging-contracts>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "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",
     "typing-extensions>=4.4",
 ]
 
 [project.optional-dependencies]
 logging = [
-    "xtr-logging>=1.0,<2",
+    "xtr-logging>=2.0,<3",
 ]
 console = [
-    "xtr-console>=1.0,<2",
+    "xtr-console>=2.0,<3",
+]
+rate-limiter = [
+    "xtr-clock>=2.0,<3",
+    "xtr-rate-limiter[di]>=2.0,<3",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -55,8 +59,10 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-logging>=1.0,<2",
-    "xtr-console>=1.0,<2",
+    "xtr-logging>=2.0,<3",
+    "xtr-console>=2.0,<3",
+    "xtr-clock>=2.0,<3",
+    "xtr-rate-limiter[di]>=2.0,<3",
     # Requests are driven straight at the application through an ASGI
     # transport, so the suite never binds a socket.
     "httpx>=0.27",

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

@@ -65,6 +65,7 @@ _UNIT_CLOSE_PRIORITY: Final = -8192
 @required_bundle(EventDispatcherBundle)
 @required_bundle("xtr_logging.bundle:LoggingBundle", ignore_on_invalid=True)
 @required_bundle("xtr_console.bundle:ConsoleBundle", ignore_on_invalid=True)
+@required_bundle("xtr_rate_limiter.bundle:RateLimiterBundle", ignore_on_invalid=True)
 @as_bundle("http_kernel", config=HttpKernelConfig)
 class HttpKernelBundle(Bundle[HttpKernelConfig]):
     """Puts the request lifecycle's services under the container."""
@@ -117,7 +118,7 @@ class HttpKernelBundle(Bundle[HttpKernelConfig]):
         )
         if bundle_active(builder, "logging"):
             # Needs the optional logging extra, which being here proves installed.
-            from xtr_http_kernel.event_listener.log_unit_listener import (  # noqa: PLC0415
+            from xtr_http_kernel.event_listener.log_unit_listener import (  # noqa: PLC0415 — optional extra
                 LogUnitListener,
             )
 
@@ -139,6 +140,15 @@ class HttpKernelBundle(Bundle[HttpKernelConfig]):
             _ = services.set(_error_logging_listener(config.log_channel)).add_tag(
                 _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.
+            from xtr_http_kernel.event_listener.rate_limit_headers_listener import (  # noqa: PLC0415
+                RateLimitHeadersListener,
+            )
+
+            _ = services.set(RateLimitHeadersListener).add_tag(
+                _LISTENER_TAG, event=ResponseEvent, method="on_response"
+            )
         if bundle_active(builder, "console"):
             services.load("xtr_http_kernel.command")
 

{xtr_http_kernel-1.4.0 → xtr_http_kernel-2.0.0}/src/xtr_http_kernel/bundle/http_kernel_config.py

@@ -6,6 +6,8 @@ import re
 from dataclasses import dataclass
 from typing import Final
 
+from xtr_http_kernel.exception.invalid_argument_error import InvalidArgumentError
+
 __all__ = ["HttpKernelConfig"]
 
 _HTTP_TOKEN: Final = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
@@ -33,7 +35,7 @@ class HttpKernelConfig:
             load the application from, when they need one.
 
     Raises:
-        ValueError: When ``request_id_header`` is not an HTTP token,
+        InvalidArgumentError: When ``request_id_header`` is not an HTTP token,
             ``log_channel`` is empty, or ``app`` does not hold exactly one
             module and one attribute around a single ``:``.
     """
@@ -51,12 +53,12 @@ class HttpKernelConfig:
             message = (
                 f"request_id_header must be a non-empty HTTP token, not {self.request_id_header!r}"
             )
-            raise ValueError(message)
+            raise InvalidArgumentError(message)
         if not self.log_channel:
             message = "log_channel must not be empty"
-            raise ValueError(message)
+            raise InvalidArgumentError(message)
         if self.app is not None:
             module, separator, attribute = self.app.partition(":")
             if not (module and separator and attribute) or ":" in attribute:
                 message = f'app must read "package.module:app", not {self.app!r}'
-                raise ValueError(message)
+                raise InvalidArgumentError(message)

{xtr_http_kernel-1.4.0 → xtr_http_kernel-2.0.0}/src/xtr_http_kernel/bundle/request_lifecycle_middleware_factory.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, final
 
 # Read at runtime: the container fills the constructor from this annotation.
-from xtr_event_dispatcher_contracts import EventDispatcherInterface  # noqa: TC002
+from xtr_event_dispatcher_contracts import EventDispatcherInterface  # noqa: TC002 — read at runtime
 
 from xtr_http_kernel.request_lifecycle_middleware import RequestLifecycleMiddleware
 

xtr_http_kernel-2.0.0/src/xtr_http_kernel/event_listener/rate_limit_headers_listener.py

@@ -0,0 +1,52 @@
+"""Responses say how much of their rate limit is left."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, final
+
+from xtr_http_kernel.rate_limiter._applied_rate_limit import applied_rate_limit
+
+if TYPE_CHECKING:
+    from xtr_http_kernel.event import ResponseEvent
+
+__all__ = ["RateLimitHeadersListener"]
+
+_LIMIT: Final = "X-RateLimit-Limit"
+_REMAINING: Final = "X-RateLimit-Remaining"
+_RESET: Final = "X-RateLimit-Reset"
+
+
+@final
+class RateLimitHeadersListener:
+    """Writes the ``X-RateLimit-*`` headers of the limit that speaks for a response.
+
+    The limit is the one a route's rate limit left on the request, when it
+    exposes its state: the calls a route may still make, how many a full
+    limit allows, and when it is full again, in seconds since the epoch. A
+    response already carrying any of the three keeps its own. The response
+    is made private too, so a shared cache never serves one caller's count
+    to another.
+    """
+
+    __slots__ = ()
+
+    def on_response(self, event: ResponseEvent) -> None:
+        """Report the limit that speaks for the response, if one does."""
+        applied = applied_rate_limit(event.request)
+        if applied is None or applied.rate_limit.reset_at is None:
+            return
+        headers = event.headers
+        if any(name in headers for name in (_LIMIT, _REMAINING, _RESET)):
+            return
+
+        headers[_LIMIT] = str(applied.rate_limit.limit // applied.tokens)
+        headers[_REMAINING] = str(max(0, int(applied.remaining_calls)))
+        headers[_RESET] = str(int(applied.rate_limit.reset_at.timestamp()))
+        directives = [
+            directive.strip()
+            for directive in headers.get("cache-control", "").split(",")
+            if directive.strip() and directive.strip().lower() != "public"
+        ]
+        if not any(directive.lower() in {"private", "no-store"} for directive in directives):
+            directives.append("private")
+        headers["cache-control"] = ", ".join(directives)

{xtr_http_kernel-1.4.0 → xtr_http_kernel-2.0.0}/src/xtr_http_kernel/exception/__init__.py

@@ -9,6 +9,17 @@ than forcing a message to be parsed.
 from __future__ import annotations
 
 from .http_kernel_error import HttpKernelError
+from .invalid_argument_error import InvalidArgumentError
 from .invalid_middleware_priority_error import InvalidMiddlewarePriorityError
+from .invalid_rate_limit_error import InvalidRateLimitError
+from .too_many_requests_error import TooManyRequestsError
+from .unknown_rate_limiter_error import UnknownRateLimiterError
 
-__all__ = ["HttpKernelError", "InvalidMiddlewarePriorityError"]
+__all__ = [
+    "HttpKernelError",
+    "InvalidArgumentError",
+    "InvalidMiddlewarePriorityError",
+    "InvalidRateLimitError",
+    "TooManyRequestsError",
+    "UnknownRateLimiterError",
+]

xtr_http_kernel-2.0.0/src/xtr_http_kernel/exception/invalid_argument_error.py

@@ -0,0 +1,25 @@
+"""The lifecycle or its configuration was given a value it cannot work with."""
+
+from __future__ import annotations
+
+from .http_kernel_error import HttpKernelError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(HttpKernelError, ValueError):
+    """The lifecycle or its configuration was given a value it cannot work with.
+
+    Also a :class:`ValueError`, so code that already guards its configuration
+    with ``except ValueError`` keeps working without learning a new exception.
+
+    Attributes:
+        reason: What is wrong with the value.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what is wrong with the value."""
+        self.reason = reason
+        super().__init__(reason)

xtr_http_kernel-2.0.0/src/xtr_http_kernel/exception/invalid_rate_limit_error.py

@@ -0,0 +1,26 @@
+"""A route's rate limit was declared in a way it cannot be applied."""
+
+from __future__ import annotations
+
+from .http_kernel_error import HttpKernelError
+
+__all__ = ["InvalidRateLimitError"]
+
+
+class InvalidRateLimitError(HttpKernelError, ValueError):
+    """A route's rate limit was declared in a way it cannot be applied.
+
+    Raised where it is declared — fewer than one token, a router that
+    already has routes, a key that is not a string — rather than silently
+    limiting nothing.
+
+    Attributes:
+        reason: What is wrong with the declaration.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what is wrong with the declaration."""
+        self.reason = reason
+        super().__init__(reason)

xtr_http_kernel-2.0.0/src/xtr_http_kernel/exception/too_many_requests_error.py

@@ -0,0 +1,50 @@
+"""A route turned a request away because a rate limit refused it."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Final
+
+from starlette.exceptions import HTTPException
+
+from .http_kernel_error import HttpKernelError
+
+if TYPE_CHECKING:
+    from xtr_rate_limiter import RateLimit
+
+__all__ = ["TooManyRequestsError"]
+
+_TOO_MANY_REQUESTS: Final = 429
+
+
+class TooManyRequestsError(HttpKernelError, HTTPException):  # pyright: ignore[reportUnsafeMultipleInheritance] -- HttpKernelError adds no __init__; HTTPException's is called below
+    """A route turned a request away because a rate limit refused it.
+
+    Also the framework's own HTTP exception, so the application answers it
+    as it answers any other: ``429 Too Many Requests`` with a ``Retry-After``
+    header, reshaped by an exception handler registered for this class when
+    the application wants another body.
+
+    Attributes:
+        rate_limit: The limit that refused the request.
+        limiter: The configured limiter's name.
+        key: The key the request was counted under.
+        retry_after: Whole seconds until the request would be accepted.
+    """
+
+    rate_limit: RateLimit
+    limiter: str
+    key: str
+    retry_after: int
+
+    def __init__(self, rate_limit: RateLimit, limiter: str, key: str, now: float) -> None:
+        """Record the refused limit, counting the wait from ``now``."""
+        self.rate_limit = rate_limit
+        self.limiter = limiter
+        self.key = key
+        self.retry_after = max(0, math.ceil(rate_limit.retry_after.timestamp() - now))
+        HTTPException.__init__(
+            self,
+            _TOO_MANY_REQUESTS,
+            headers={"Retry-After": str(self.retry_after)},
+        )

xtr_http_kernel-2.0.0/src/xtr_http_kernel/exception/unknown_rate_limiter_error.py

@@ -0,0 +1,34 @@
+"""A route names a rate limiter nobody configured."""
+
+from __future__ import annotations
+
+from .http_kernel_error import HttpKernelError
+
+__all__ = ["UnknownRateLimiterError"]
+
+
+class UnknownRateLimiterError(HttpKernelError, LookupError):
+    """A route names a rate limiter nobody configured.
+
+    Raised when the first request reaches the route, since routes are
+    declared before any kernel is built. A limiter is configured in the
+    rate limiter bundle's configuration, under the name the route uses.
+
+    Attributes:
+        limiter: The name the route used.
+        available: The names the application configured.
+    """
+
+    limiter: str
+    available: tuple[str, ...]
+
+    def __init__(self, limiter: str, available: tuple[str, ...]) -> None:
+        """Record the unknown name and the ones that exist."""
+        self.limiter = limiter
+        self.available = available
+        names = '", "'.join(available)
+        known = f'"{names}"' if available else "none"
+        super().__init__(
+            f'Rate limiter "{limiter}" does not exist. Did you forget to configure it? '
+            f"Available limiters: {known}.",
+        )

xtr_http_kernel-2.0.0/src/xtr_http_kernel/rate_limiter/__init__.py

@@ -0,0 +1,11 @@
+"""Rate limits on routes, routers and whole applications, through the rate limiter bundle.
+
+Needs the ``rate-limiter`` extra, which brings xtr-rate-limiter; importing
+this package without it fails, which is why nothing else here imports it.
+"""
+
+from __future__ import annotations
+
+from .rate_limited import RateLimited, RateLimitKey
+
+__all__ = ["RateLimitKey", "RateLimited"]

xtr_http_kernel-2.0.0/src/xtr_http_kernel/rate_limiter/_applied_rate_limit.py

@@ -0,0 +1,40 @@
+"""The rate limit that speaks for a response, out of every one a request consumed."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, final
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from xtr_rate_limiter import RateLimit
+
+__all__ = ["STATE_KEY", "AppliedRateLimit", "applied_rate_limit"]
+
+STATE_KEY: Final = "_xtr_rate_limit"
+"""Where a request keeps the limit its response reports, on ``request.state``."""
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class AppliedRateLimit:
+    """A consumed limit, and how many tokens each call of its route takes.
+
+    Attributes:
+        rate_limit: The limit as the request left it.
+        tokens: The tokens one call consumes.
+    """
+
+    rate_limit: RateLimit
+    tokens: int
+
+    @property
+    def remaining_calls(self) -> float:
+        """The calls left, rather than the tokens."""
+        return self.rate_limit.remaining_tokens / self.tokens
+
+
+def applied_rate_limit(request: Request) -> AppliedRateLimit | None:
+    """Return the limit ``request``'s response reports; ``None`` when there is none."""
+    applied: object = getattr(request.state, STATE_KEY, None)
+    return applied if isinstance(applied, AppliedRateLimit) else None

xtr_http_kernel-2.0.0/src/xtr_http_kernel/rate_limiter/rate_limited.py

@@ -0,0 +1,283 @@
+"""A rate limit on a route, a router or a whole application."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Final, ParamSpec, TypeVar, cast, overload
+
+from fastapi import APIRouter
+from fastapi.params import Depends
+
+# The framework reads the dependency's signature at runtime to hand it the request.
+from starlette.requests import Request
+from xtr_clock import Clock
+from xtr_dependency_injection import current_unit_of_work
+from xtr_event_dispatcher_contracts import EventDispatcherInterface
+from xtr_rate_limiter import RateLimiterFactoryInterface, RateLimitExceededEvent
+
+from xtr_http_kernel.exception import (
+    InvalidRateLimitError,
+    TooManyRequestsError,
+    UnknownRateLimiterError,
+)
+
+from ._applied_rate_limit import STATE_KEY, AppliedRateLimit, applied_rate_limit
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from xtr_service_contracts import ContainerInterface
+
+__all__ = ["RateLimitKey", "RateLimited"]
+
+RateLimitKey = str | Callable[[Request], str | Awaitable[str]]
+"""What a request is counted under: a fixed key, or one worked out from the request."""
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+_HIDDEN_PREFIX: Final = "_xtr_rate_limit_"
+"""What the parameter a decorated endpoint gains is called, numbered."""
+
+
+class RateLimited(Depends):
+    """A rate limit a request must pass before its endpoint runs.
+
+    Attributes:
+        limiter: The name the limiter is configured under.
+        key: What a request is counted under; the client's address, the
+            method and the route's path template when ``None``.
+        tokens: The tokens one request consumes.
+        methods: The methods limited; every method when empty.
+        expose_headers: Whether the response reports this limit.
+
+    One declaration, written wherever the framework takes a dependency, or
+    as a decorator:
+
+    ```python
+    @router.get("/books")
+    @RateLimited("api")  # below the route: the route reads what it decorates
+    async def list_books() -> list[Book]: ...
+
+
+    @router.post("/login", dependencies=[RateLimited("login", key=by_username)])
+    async def login() -> None: ...
+
+
+    reports = RateLimited("reports", expose_headers=True)(APIRouter(prefix="/reports"))
+    app.include_router(admin, dependencies=[RateLimited("admin")])
+    app = FastAPI(dependencies=[RateLimited("global")])
+    ```
+
+    The limit runs after routing and before the endpoint, in the order the
+    framework resolves dependencies: the application's, the routers', then
+    the route's. A request the limiter refuses is answered ``429 Too Many
+    Requests`` with ``Retry-After``, and a
+    :class:`~xtr_rate_limiter.RateLimitExceededEvent` is dispatched first.
+    Limits consulted before a refusal keep their spend.
+
+    With ``expose_headers``, the response carries ``X-RateLimit-Limit``,
+    ``X-RateLimit-Remaining`` and ``X-RateLimit-Reset`` for the limit closest
+    to refusing among those exposing theirs; a refusing limit always speaks,
+    and one that does not expose its state leaves the response without them.
+    """
+
+    # Set through object.__setattr__ in __init__: the base is a frozen dataclass.
+    limiter: str  # pyright: ignore[reportUninitializedInstanceVariable]
+    key: RateLimitKey | None  # pyright: ignore[reportUninitializedInstanceVariable]
+    tokens: int  # pyright: ignore[reportUninitializedInstanceVariable]
+    methods: frozenset[str]  # pyright: ignore[reportUninitializedInstanceVariable]
+    expose_headers: bool  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    def __init__(
+        self,
+        limiter: str,
+        *,
+        key: RateLimitKey | None = None,
+        tokens: int = 1,
+        methods: str | Iterable[str] = (),
+        expose_headers: bool = False,
+    ) -> None:
+        """Limit requests through the configured limiter ``limiter``.
+
+        Args:
+            limiter: The name the limiter is configured under.
+            key: What the request is counted under — a string, or a
+                function of the request returning one, awaited when it
+                returns an awaitable. By default the client's address, the
+                method and the route's path template — ``/books/{isbn}``,
+                so every book shares one count.
+            tokens: The tokens one request consumes.
+            methods: The methods limited; every method when empty. ``GET``
+                also limits ``HEAD``.
+            expose_headers: Report this limit in ``X-RateLimit-*`` headers.
+
+        Raises:
+            InvalidRateLimitError: When ``tokens`` is below one.
+        """
+        if tokens < 1:
+            raise InvalidRateLimitError(
+                f"A rate limit must consume at least one token, got {tokens}.",
+            )
+        normalized = {methods.upper()} if isinstance(methods, str) else {m.upper() for m in methods}
+        if "GET" in normalized:
+            normalized.add("HEAD")
+        # Every declaration runs on its own: two limits sharing a limiter both count.
+        super().__init__(dependency=self._enforce, use_cache=False)
+        # The framework's dependency marker is a frozen dataclass.
+        object.__setattr__(self, "limiter", limiter)
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "tokens", tokens)
+        object.__setattr__(self, "methods", frozenset(normalized))
+        object.__setattr__(self, "expose_headers", expose_headers)
+
+    @overload
+    def __call__(self, target: APIRouter, /) -> APIRouter: ...
+
+    @overload
+    def __call__(self, target: Callable[_P, _R], /) -> Callable[_P, _R]: ...
+
+    def __call__(self, target: APIRouter | Callable[_P, _R], /) -> APIRouter | Callable[_P, _R]:
+        """Apply this limit to every route of ``target``, or to the endpoint ``target``.
+
+        A router must have no route yet: the framework copies a router's
+        dependencies into each route as the route is added. An endpoint must
+        be decorated before the route is declared — below its route
+        decorator — since the route reads the endpoint's signature then.
+
+        Raises:
+            InvalidRateLimitError: When ``target`` is a router that already
+                has routes.
+        """
+        if isinstance(target, APIRouter):
+            if target.routes:
+                raise InvalidRateLimitError(
+                    "Rate limit a router before adding its routes, or give the limit to "
+                    "include_router(..., dependencies=[...]).",
+                )
+            target.dependencies.append(self)
+            return target
+        return self._decorate(target)
+
+    def _decorate(self, endpoint: Callable[_P, _R]) -> Callable[_P, _R]:
+        """Return ``endpoint`` taking this limit as a hidden dependency.
+
+        The wrapper's signature is the endpoint's with one keyword-only
+        parameter more, defaulting to this limit — which the framework reads
+        as a dependency, and keeps out of the published schema. The wrapper
+        drops it before calling the endpoint.
+        """
+        signature = inspect.signature(endpoint)
+        taken = set(signature.parameters)
+        index = 0
+        while f"{_HIDDEN_PREFIX}{index}" in taken:
+            index += 1
+        name = f"{_HIDDEN_PREFIX}{index}"
+
+        parameters = list(signature.parameters.values())
+        keywords = [p for p in parameters if p.kind is inspect.Parameter.VAR_KEYWORD]
+        others = [p for p in parameters if p.kind is not inspect.Parameter.VAR_KEYWORD]
+        hidden = inspect.Parameter(name, inspect.Parameter.KEYWORD_ONLY, default=self)
+        extended = signature.replace(parameters=[*others, hidden, *keywords])
+
+        if inspect.iscoroutinefunction(endpoint):
+            call = cast("Callable[_P, Awaitable[object]]", endpoint)
+
+            @functools.wraps(endpoint)
+            async def asynchronous(*args: _P.args, **kwargs: _P.kwargs) -> object:
+                _ = kwargs.pop(name, None)
+                return await call(*args, **kwargs)
+
+            wrapper = cast("Callable[_P, _R]", asynchronous)
+        else:
+
+            @functools.wraps(endpoint)
+            def synchronous(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+                _ = kwargs.pop(name, None)
+                return endpoint(*args, **kwargs)
+
+            wrapper = synchronous
+        # The framework reads the signature from here; functions take any attribute.
+        wrapper.__signature__ = extended  # pyright: ignore[reportAttributeAccessIssue]  # ty: ignore[unresolved-attribute]
+        return wrapper
+
+    async def _enforce(self, request: Request) -> None:
+        """Consume this limit for ``request``, refusing it with 429 when the limiter does.
+
+        Raises:
+            UnknownRateLimiterError: When no limiter is configured under the
+                name, or no kernel serves the request.
+            TooManyRequestsError: When the limiter refuses the request.
+        """
+        if self.methods and request.method not in self.methods:
+            return
+        container = current_unit_of_work()
+        if container is None or not container.has(RateLimiterFactoryInterface, self.limiter):
+            raise UnknownRateLimiterError(self.limiter, await _configured(container))
+
+        key = await self._key_of(request)
+        factory = await container.get(RateLimiterFactoryInterface, self.limiter)
+        rate_limit = await factory.create(key).consume(self.tokens)
+        candidate = (
+            AppliedRateLimit(rate_limit, self.tokens)
+            if self.expose_headers and rate_limit.reset_at is not None
+            else None
+        )
+
+        if not rate_limit.is_accepted():
+            # A refusing limit speaks for the response, even to say nothing.
+            setattr(request.state, STATE_KEY, candidate)
+            if container.has(EventDispatcherInterface):
+                dispatcher = await container.get(EventDispatcherInterface)
+                _ = await dispatcher.dispatch(
+                    RateLimitExceededEvent(rate_limit, self.limiter, key),
+                )
+            raise TooManyRequestsError(rate_limit, self.limiter, key, Clock().now().timestamp())
+
+        applied = applied_rate_limit(request)
+        if candidate is not None and (
+            applied is None or candidate.remaining_calls < applied.remaining_calls
+        ):
+            setattr(request.state, STATE_KEY, candidate)
+
+    async def _key_of(self, request: Request) -> str:
+        """Return what ``request`` is counted under.
+
+        Raises:
+            InvalidRateLimitError: When the key function returns anything
+                but a string.
+        """
+        if self.key is None:
+            client = request.client.host if request.client is not None else "unknown"
+            # The route's template, not the path: /books/1 and /books/2 share one count, so
+            # varying a path parameter never earns a fresh limit.
+            route: object = request.scope.get("route")
+            path = getattr(route, "path_format", None)
+            return (
+                f"{client}~{request.method}~{path if isinstance(path, str) else request.url.path}"
+            )
+        if isinstance(self.key, str):
+            return self.key
+        key: object = self.key(request)
+        if inspect.isawaitable(key):
+            key = await key
+        if not isinstance(key, str):  # pyright: ignore[reportUnnecessaryIsInstance] -- the application's function; its annotation is not enforced
+            raise InvalidRateLimitError(  # pyright: ignore[reportUnreachable] -- as above
+                f'The key of the "{self.limiter}" rate limit must be a string, got {key!r}.',
+            )
+        return key
+
+
+async def _configured(container: ContainerInterface | None) -> tuple[str, ...]:
+    """Return the names the application configured limiters under; none without a kernel."""
+    if container is None:
+        return ()
+    # The bundle's configuration names every limiter; only its bundle registers it.
+    from xtr_rate_limiter.bundle import RateLimiterConfig  # noqa: PLC0415
+
+    if not container.has(RateLimiterConfig):
+        return ()
+    config = await container.get(RateLimiterConfig)
+    return tuple(sorted(config.limiters))

{xtr_http_kernel-1.4.0 → xtr_http_kernel-2.0.0}/src/xtr_http_kernel/request_lifecycle_middleware.py

@@ -175,7 +175,13 @@ class RequestLifecycleMiddleware:
             exception_event = ExceptionEvent(lifecycle.request, error)
             _ = await self._dispatcher.dispatch(exception_event)
             answer = exception_event.response
-            if answer is not None and not lifecycle.response_started:
+            # Only a failure is answered: a cancellation, an interrupt or an exit goes on
+            # as it arrived, or timeouts, cancelled tasks and shutdowns would stop working.
+            if (
+                answer is not None
+                and not lifecycle.response_started
+                and isinstance(error, Exception)
+            ):
                 await answer(scope, receive, lifecycle.send)
                 return
             await lifecycle.finish()