skip to content

CORS & Custom Middleware

Middleware wraps every request, including ones no route matches, while a dependency runs only for its routes. Interviewers ask about CORS with credentials and the order middleware runs in.

on this pageshow

explore

questions

6

In FastAPI, how do you write an @app.middleware("http") function that adds a request-timing header, and which requests does it run for?

level: juniorimportance: must knowfreq 40%

answer

  1. a decorator on the app object
  2. request plus call_next
  3. await first, then edit headers
  4. unmatched paths still pass through
  5. expose_headers for browser code

basics

~20 s

Decorate an async function taking request and call_next with @app.middleware("http"), await call_next(request), then set a header such as X-Process-Time on the returned response. It wraps the whole router, so it also runs for 404s, and before any dependency.

solid answer

~30 s

You write `async def add_process_time_header(request: Request, call_next)` and decorate it with `@app.middleware("http")`. Inside, you take `time.perf_counter()`, `await call_next(request)` to run routing, dependencies and the path operation, then set `response.headers["X-Process-Time"]` and return the response. FastAPI registers it through `app.add_middleware(BaseHTTPMiddleware, dispatch=func)`, so it wraps the whole router: it sees requests no route matches (the 404 is produced inside `call_next`), 405s and 422s, and it runs before any dependency. It handles HTTP only, so WebSocket connections pass by it. If browser code on another origin must read the header, list it in `CORSMiddleware(expose_headers=[...])`.

code

python · 21 lines
python
import time
from collections.abc import Awaitable, Callable

from fastapi import FastAPI, Request, Response

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(
    request: Request, call_next: Callable[[Request], Awaitable[Response]]
) -> Response:
    start = time.perf_counter()
    response = await call_next(request)
    response.headers["X-Process-Time"] = f"{time.perf_counter() - start:.6f}"
    return response


@app.get("/items/{item_id}")
async def read_item(item_id: int) -> dict[str, int]:
    return {"item_id": item_id}

go deeper

for a junior

Recall the shape: an async function with request and call_next, decorated with @app.middleware("http"), awaiting call_next and setting a header before returning the response.

for a middle

Explain that the decorator registers BaseHTTPMiddleware around the router, so 404s, 405s and 422s pass through it, and dependencies run inside call_next.

for a senior

Point out that call_next returns at header time, so streamed bodies escape the timing, and that WebSockets and CORS preflights may never reach this function.

for a principal

Decide where request timing belongs for the team: a decorated function, a pure ASGI class, or the server and edge access logs, and keep one convention.

## What the decorator registers In FastAPI a **middleware** is code that runs around every request the application receives. The quickest way to write one is the decorator `@app.middleware("http")` placed on an `async def` function. The argument names the kind of traffic, and `"http"` is the only type the decorator supports. Under the hood the decorator is one line: FastAPI calls `self.add_middleware(BaseHTTPMiddleware, dispatch=func)`. `BaseHTTPMiddleware` is a Starlette class that turns the low-level ASGI interface into a request-and-response interface, and your function becomes its `dispatch` callable. Because it goes through `add_middleware`, the decorator and explicit `app.add_middleware(...)` calls share one stack. ## Writing the timing middleware The function receives two arguments: - **`request`**: a `fastapi.Request` (Starlette's `Request` re-exported) for the incoming call. - **`call_next`**: an async callable. `await call_next(request)` hands the request to the rest of the app (routing, dependencies, the path operation, exception handlers) and returns the `Response` they produced. Code before the `await` runs on the way in; code after it runs on the way out, where you can still change the response's headers before returning it: ```python @app.middleware("http") async def add_process_time_header(request: Request, call_next): start = time.perf_counter() response = await call_next(request) response.headers["X-Process-Time"] = f"{time.perf_counter() - start:.6f}" return response ``` The FastAPI docs use `time.perf_counter()` rather than `time.time()` because it is the more precise clock for measuring an interval. The function must return a response; returning the one from `call_next` is the normal case. ## Which requests it sees The decorated function wraps the router, not individual routes, so it runs for: 1. **Matched requests**, before any dependency or the path operation runs; both execute inside `call_next`. 2. **Unmatched paths**: the router produces the `404 {"detail": "Not Found"}` inside `call_next`, so the 404 still gets your header. 3. **Wrong methods and invalid input**: a 405 or a 422 validation error is also built inside `call_next`, so it passes back out through the middleware. It does **not** run for: - **WebSocket connections**: `BaseHTTPMiddleware` checks the ASGI scope type and passes anything other than `"http"` straight through. - **CORS preflight requests when `CORSMiddleware` was added after it**: the last-added middleware is outermost, and `CORSMiddleware` answers a preflight itself without calling inward. ## Passing values inward The middleware and the route share the same ASGI scope, so attributes set on `request.state` in the middleware are readable further in: - set `request.state.request_id = ...` before `await call_next(request)`; - read it in a dependency or path operation that declares `request: Request`; - copy it onto the response afterwards, for example as an `X-Request-ID` header. This is the usual way to hand a per-request value, such as a correlation id, to inner code without a global variable. The other direction is narrower: after `call_next` the middleware sees only the response's status, headers and body stream, never the path operation's Python return value. ## What the measured time means `call_next` returns as soon as the inner app has produced the response's status and headers. The body of a `StreamingResponse` is sent afterwards, while your middleware returns the wrapper. For a streamed answer the header therefore measures **time to the first byte of headers**, not the whole transfer. The returned object is a streaming wrapper with a `body_iterator` and no `.body` attribute, so reading the body means consuming and re-wrapping that iterator. ## Making the header visible to a browser A browser exposes only a few response headers to JavaScript on a cross-origin call. To let a frontend on another origin read `X-Process-Time`, add it to `CORSMiddleware(expose_headers=["X-Process-Time"])`. `allow_headers` is about request headers the browser may send, not response headers it may read. | Where the code sits | When it runs | |---|---| | Before `await call_next(request)` | on the way in, before routing and dependencies | | After `await call_next(request)` | on the way out, once headers are ready | | Not calling `call_next` at all | the app never sees the request | ## Common mistakes - Expecting it to apply to one router only: in FastAPI 0.143 middleware attaches to the application, not to an `APIRouter`. - Raising `HTTPException` from inside it: user middleware sits outside the layer that runs exception handlers, so the client gets a 500 instead. - Doing blocking work in it: it is an `async` function on the event loop, so a blocking call stalls every request in that process. - Forgetting `return response`: the function must return a response object, otherwise Starlette has nothing to send and the client gets a 500.

  • Why does X-Process-Time look tiny for a slow StreamingResponse in FastAPI?
    `call_next` returns once the inner app has sent the status and headers; the streamed body is delivered after the middleware has already returned. The header measures time to the start of the response, not the full transfer. To time the whole exchange, write a pure ASGI middleware that wraps `send` and records the time when the final body message (no `more_body`) goes out.
  • In a FastAPI app, does a timing middleware run before or after the path operation's dependencies?
    Before. Dependencies are solved by the route inside `call_next`, so the middleware's code before the `await` runs first and its code after the `await` runs once the route has produced a response. That is also why a dependency cannot see anything the middleware sets on the response, while the middleware can put values on `request.state` for dependencies to read.

  • Says the middleware only runs for requests that match a route.
  • Thinks @app.middleware("http") also wraps WebSocket connections.
  • Expects call_next to return the path operation's raw return value.
  • Lists the timing header in allow_headers to make the browser read it.
  • Believes middleware runs after the path operation's dependencies.
open as a page

A FastAPI API called with cookies from a browser app on another origin fails once credentials are sent; how should CORSMiddleware be configured, and why not allow_origins=["*"]?

level: seniorimportance: must knowfreq 45%

basics

~20 s

List the frontend's exact origins in allow_origins, set allow_credentials=True, and name the methods and headers it uses. With credentials on, allow_origins=["*"] makes Starlette echo any Origin back with credentials allowed, so any website could read responses sent with users' cookies.

open as a page

In FastAPI, when middleware is registered with both app.add_middleware and @app.middleware("http"), which runs first, and where do the built-in layers sit?

level: middleimportance: should knowfreq 35%

basics

~20 s

Both styles feed one stack, and each new registration becomes the outermost layer, so the last one added runs first on the request and last on the response. ServerErrorMiddleware wraps all of them; ExceptionMiddleware sits inside them.

open as a page

What do FastAPI's bundled GZipMiddleware, TrustedHostMiddleware and HTTPSRedirectMiddleware each do, and which of their defaults matter when you add them?

level: middleimportance: should knowfreq 25%

basics

~20 s

GZipMiddleware compresses responses for clients accepting gzip, skipping bodies under 500 bytes; TrustedHostMiddleware answers 400 to a Host matching no allowed_hosts entry; HTTPSRedirectMiddleware redirects http and ws requests to https and wss with a 307.

open as a page

In a FastAPI app with CORSMiddleware, why does the browser report a CORS error whenever an endpoint raises an unhandled exception, and how do you fix it?

level: seniorimportance: should knowfreq 25%

basics

~20 s

An unhandled exception propagates past CORSMiddleware to ServerErrorMiddleware, which builds the 500 outside every user middleware, so the response has no CORS headers and the browser hides it. Catch errors in a middleware inside CORSMiddleware, or wrap the whole app.

open as a page

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%

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.

open as a page