FastAPI Custom ASGI Middleware

Mental model

FastAPI middleware is an outer ASGI wrapper around your application, executing onion-style before and after every HTTP request.

Theory

Custom middlewares can be implemented via @app.middleware("http") or pure ASGI class wrappers (BaseHTTPMiddleware). Middlewares are ideal for cross-cutting concerns: setting unique X-Request-ID correlation headers, logging request duration, handling global CORS policies, and scoping thread-safe request state using Python contextvars.ContextVar.

Alternatives and trade-offs

• Middlewares: Run globally on every request (CORS, timing, request ID).
• FastAPI Dependencies: Run only on targeted routes and support Depends graph composition.

Failure modes and misconceptions

1. BaseHTTPMiddleware Streaming Issues: BaseHTTPMiddleware buffers responses in memory and can break SSE / WebSocket streaming.
2. ContextVar Leaks: Always reset ContextVar tokens in finally blocks when reusing threads across requests.

Decision scenario

Use @app.middleware("http") for application-wide request logging and correlation headers. Use route-level Depends for granular authentication and authorization checks.

Learning outcomes

• Build HTTP middlewares for correlation tracing and latency logging.
• Store context-local state safely across async tasks using contextvars.ContextVar.
• Avoid response buffering issues with high-throughput streaming endpoints.

Trade-offs

Global middlewares execute on every incoming HTTP request path, so middleware logic must stay extremely fast and lightweight.