skip to content

In FastAPI, when would you write a pure ASGI middleware class instead of an @app.middleware("http") function, and how do you register it?

level: middleimportance: nice to knowfreq 20%

answer

  1. scope, receive, send
  2. the decorator is BaseHTTPMiddleware
  3. context variables do not flow back
  4. wrap send for headers
  5. add_middleware, not manual wrapping

basics

~20 s

Write a class taking app with an async call(scope, receive, send) when you need WebSockets, context variables set downstream, or the full streamed response; register it with app.add_middleware so FastAPI's error layers still wrap it.

solid answer

~40 s

`@app.middleware("http")` wraps your function in Starlette's `BaseHTTPMiddleware`, which handles only the `"http"` scope, runs the inner app in a separate task, and hands you a streaming response wrapper. Starlette documents that changes to a `contextvars.ContextVar` made in the endpoint do not propagate back up through it. A pure ASGI class, `__init__(self, app)` plus `async def __call__(self, scope, receive, send)`, avoids those limits: it can branch on `scope["type"]` to cover WebSockets, wraps `send` to edit headers on `http.response.start`, and sees every body chunk. Register it with `app.add_middleware(MyMiddleware, **options)`, which keeps it inside `ServerErrorMiddleware`. FastAPI instantiates it once, so per-request state must live in local variables inside `__call__`.

code

python · 34 lines
python
import time

from fastapi import FastAPI
from starlette.datastructures import MutableHeaders
from starlette.types import ASGIApp, Message, Receive, Scope, Send


class ProcessTimeMiddleware:
    def __init__(self, app: ASGIApp) -> None:
        self.app = app

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] != "http":  # websocket and lifespan pass straight through
            await self.app(scope, receive, send)
            return

        start = time.perf_counter()  # per-request state lives in __call__

        async def send_wrapper(message: Message) -> None:
            if message["type"] == "http.response.start":
                headers = MutableHeaders(scope=message)
                headers.append("X-Process-Time", f"{time.perf_counter() - start:.6f}")
            await send(message)

        await self.app(scope, receive, send_wrapper)


app = FastAPI()
app.add_middleware(ProcessTimeMiddleware)


@app.get("/ping")
async def ping() -> dict[str, str]:
    return {"ping": "pong"}

go deeper

for a junior

Know that FastAPI accepts any ASGI middleware class through app.add_middleware, and that the decorator style is a convenience on top of it.

for a middle

Write the class: init(app), async call(scope, receive, send), pass non-HTTP scopes through, wrap send to edit headers on http.response.start.

for a senior

Name the concrete triggers for switching: WebSockets, context variables, full-body timing, and the shared-instance bug from state stored on self.

for a principal

Set a team rule for which style new middleware uses and when the decorator is acceptable, so behaviour is predictable across services.

## Two ways to write FastAPI middleware FastAPI runs on **ASGI**, the interface in which an application is an async callable taking `scope` (a dict describing the connection, including `scope["type"]`), `receive` (an awaitable that yields incoming messages) and `send` (an awaitable that emits outgoing messages). Middleware is an ASGI application that wraps another one. - **The `call_next` style**: `@app.middleware("http")` registers `BaseHTTPMiddleware` with your function as `dispatch`. You get a `Request` and a `call_next` that returns a `Response`. - **The pure ASGI style**: a class whose constructor receives the next `app` and whose `async __call__(self, scope, receive, send)` calls it, possibly with wrapped `receive` or `send` callables. Every middleware Starlette ships, including `CORSMiddleware` and `GZipMiddleware`, is written this way. ## What the call_next style costs | Concern | `@app.middleware("http")` | Pure ASGI class | |---|---|---| | WebSocket connections | passed through untouched | can handle `"websocket"` scope | | `contextvars` set in the endpoint | not visible after `call_next` | visible after the inner call returns, unless a `BaseHTTPMiddleware` sits further in | | Response body | streaming wrapper, `body_iterator` only | every `http.response.body` message as it is sent | | Effort | a short function | more code, works on raw messages | The context-variable limit is documented by Starlette: `BaseHTTPMiddleware` runs the inner application in a separate task, so a `ContextVar` the endpoint sets is not the value the middleware reads afterwards. Starlette also warns that it disrupts propagation for pure ASGI middleware in the same stack: a pure ASGI class outside a decorated function no longer sees the endpoint's value either. ## Writing one A pure ASGI middleware that adds a timing header: 1. Store the next app in `__init__`, along with any configuration. 2. In `__call__`, pass non-HTTP scopes (`"websocket"`, `"lifespan"`) straight through unless you mean to handle them. 3. Keep per-request values, such as the start time, in **local variables** inside `__call__`. 4. Wrap `send`: on an `http.response.start` message, edit headers with `MutableHeaders(scope=message)`; then forward every message. 5. Call `await self.app(scope, receive, send_wrapper)`. Other patterns Starlette documents: - wrap `receive` to inspect or limit the request body as it streams in; - store values in `scope` (Starlette's own convention) for endpoints to read through `request.scope`; - wrap the inner call in `try`/`except`/`finally` for metrics and cleanup; - send an early response yourself and not call the inner app at all. If you change the body, you must fix `Content-Length` to match. ## Reading the request body The two styles also differ on the way in. In the `call_next` style, calling `await request.body()` inside the function makes `BaseHTTPMiddleware` hold the **entire body in memory** and replay it to the app, which is fine for small JSON and costly for large uploads. A pure ASGI middleware wraps `receive` instead and sees each `http.request` message as it arrives, so it can count bytes, hash or log a prefix, or stop an oversized body early, without buffering the whole request. That is the shape of a body-size limit or a request-signature check that must read the exact bytes the endpoint will parse. ## Registering it in FastAPI Use `app.add_middleware(ProcessTimeMiddleware)`, passing extra keyword arguments for its constructor. The FastAPI docs recommend this over wrapping the app by hand (`app = SomeMiddleware(app)`), because `add_middleware` keeps the middleware inside FastAPI's error layers, so unhandled errors still become proper 500 responses and custom exception handlers keep working. Ordering follows the usual rule: the last added is outermost. Any third-party class that follows the ASGI interface is registered the same way. ## The stateless rule FastAPI builds the stack once, on the app's first call, and creates **one instance** of each middleware class at that moment. That instance handles every concurrent request. Storing a request's data on `self`, such as `self.start = time.perf_counter()`, lets parallel requests overwrite each other's values. Starlette's docs call this out directly: ASGI middleware should be stateless, with connection-specific state scoped to `__call__`. ## When the decorator is still fine For short HTTP-only logic that only reads the request and sets response headers, and does not depend on context variables, the decorator is simpler and readable. Pick the pure ASGI style when a requirement above applies, and say so in the code so reviewers know why.

  • How does a pure ASGI middleware in FastAPI measure the whole streamed response rather than time to headers?
    Wrap `send` and record the end time when a `http.response.body` message arrives with `more_body` false or missing, which is the last chunk. Then log or report the duration, since the headers have already gone out by then. The `call_next` style cannot do this, because `call_next` returns as soon as the response starts.
  • In a pure ASGI middleware for FastAPI, how do you pass a value to the path operation?
    Put it into the ASGI `scope` dict under a distinctive key before calling the inner app, for example `scope["request_id"] = ...`; the endpoint reads `request.scope["request_id"]`. Starlette uses this convention itself, and it is not part of the ASGI specification, so choose key names unlikely to clash with other middleware.

  • Thinks @app.middleware("http") also intercepts WebSocket connections.
  • Stores per-request data on self in an ASGI middleware class.
  • Wraps the app by hand, putting it outside FastAPI's 500 and handler layers.
  • Expects a ContextVar set in the endpoint to be visible after call_next.
  • Believes FastAPI creates a new middleware instance for every request.