Skip to content

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 send and reading raw header bytes is harder to follow than Request and Response objects.
  • 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 reach request.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.