0001: Pure ASGI middleware, not BaseHTTPMiddleware¶
Status: accepted, since 0.1.0 · Reviewed: 2026-10-31
Context¶
The request middleware runs on every request. It has to see the status code, the duration, the matched route, and context the endpoint sets during the request, such as set_user_context(). Starlette's BaseHTTPMiddleware, with its dispatch(request, call_next), is the easy way to write one.
Decision¶
RequestLoggingMiddleware is a plain ASGI callable (request_logging.py:47). It reads headers from the raw scope bytes and wraps send to see the response status.
Evidence¶
The two middlewares in examples/benchmarks/middleware_overhead.py only pass the request through. Measured on Starlette 1.10.0, Python 3.14.7, Apple silicon, 20,000 in-process requests × 5 rounds, median shown:
| Per request | |
|---|---|
| No middleware | 5.6 µs |
| Pure ASGI | 5.7 µs |
BaseHTTPMiddleware |
158.4 µs |
BaseHTTPMiddleware adds about 153 µs before doing any work.
The same script checks context visibility. An async endpoint sets a context variable, and each request runs in a fresh context. Afterwards, pure ASGI middleware sees the value and BaseHTTPMiddleware sees None, because it runs the endpoint in a separate task. That's why user_context set in an async endpoint appears on the request.completed line.
What it cost¶
- Harder code to read. Wrapping
sendand reading raw header bytes is harder to follow thanRequestandResponseobjects. - Sync endpoints run in a copy of the context. Sync (
def) endpoints run in a thread pool with a copy of the context, so a context variable they set doesn't reachrequest.completed.set_user_context()used to be lost this way. Since 0008 it also stores its value on a holder that the middleware creates, so it arrives. Context variables of your own still don't.