FastAPI Middleware — Logging, CORS and Custom Middleware

In production at TheCodeForge, we treat middleware as the 'Defensive Perimeter' of our services. Middleware handles cross-cutting concerns—logic that shouldn't clutter your business endpoints. Whether you're enforcing Cross-Origin Resource Sharing (CORS) policies, injecting global trace IDs for distributed logging, or measuring request latency, middleware provides a centralized point of control that wraps your entire ASGI application.

But here's the thing: one wrong middleware can silently drop all requests. That's not theory—it's a 2 AM pager call. Understanding execution order, short-circuiting behavior, and how to avoid blocking the event loop is what separates a working API from one that crashes under load.

This article covers the patterns we use, the production traps we've fixed, and the debugging steps that get you back online fast.

How FastAPI CORS Middleware Actually Works

CORS middleware in FastAPI intercepts every incoming HTTP request before it reaches your route handler and adds the necessary CORS headers to the response. It's a WSGI/ASGI middleware that wraps the entire application, inspecting the Origin header and deciding whether to include Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers based on your configuration. The core mechanic is simple: it's a preflight handler for OPTIONS requests and a response header injector for all other requests.

In practice, FastAPI's CORSMiddleware operates at the ASGI level, meaning it runs before any path operation decorator or dependency injection. It matches origins against a whitelist using exact string comparison or regex patterns. The middleware caches the allowed origins in memory, so lookups are O(1) after initialization. A critical detail: if you set allow_origins=["*"], the middleware will echo back the request's Origin header — it does not blindly send a wildcard when credentials are involved, because the CORS spec forbids wildcard with credentials.

You should use FastAPI's CORSMiddleware when your API serves a browser-based frontend on a different domain, port, or protocol. Without it, browsers will block cross-origin requests entirely. In production, never use allow_origins=["*"] with allow_credentials=True — the browser will reject the response. Instead, explicitly list your frontend domains. This middleware is also the correct place to handle preflight caching via Access-Control-Max-Age to reduce OPTIONS request volume.

CORS Middleware: Securing Cross-Origin Traffic

CORS is a security feature, not an error. When your frontend (e.g., React on port 3000) tries to talk to your FastAPI backend (port 8000), the browser blocks the request unless the server explicitly permits it. For production, never use ['*']. Always whitelist specific, trusted domains.

But it gets tricky: when allow_credentials=True, the Access-Control-Allow-Origin response header must be a single origin, not a wildcard. The browser enforces this. And if you have a middleware that returns a 403 for unauthenticated requests before CORS headers are set, the frontend gets a CORS error—not a 403. That's a common head-scratcher.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Configure the 'Onion' layers
# CORSMiddleware should generally be added early in the stack
app.add_middleware(
    CORSMiddleware,
    # List specific trusted origins for production
    allow_origins=[
        'https://api.thecodeforge.io',
        'https://dashboard.thecodeforge.io',
        'http://localhost:3000'
    ],
    # Required if your frontend sends cookies or Authorization headers
    allow_credentials=True,
    allow_methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    allow_headers=['Authorization', 'X-Forge-Trace-ID', 'Content-Type'],
)

# Note: If allow_credentials is True, allow_origins cannot be ['*']

Custom Middleware — Performance Logging

Custom middleware uses the call_next pattern. This allows you to run code before the request reaches your route and after the response has been generated. This is the ideal place to calculate 'Time to First Byte' (TTFB) or inject unique request identifiers for log aggregation.

But there's a subtle trap: if you do heavy synchronous work (like hashing or JSON serialization) in the middleware, you block the entire event loop. All concurrent requests wait. Always push heavy work to a thread pool or make it async-friendly.

from fastapi import FastAPI, Request
import time
import uuid
import logging

app = FastAPI()
logger = logging.getLogger("thecodeforge.access")

@app.middleware('http')
async def add_process_time_header(request: Request, call_next):
    # 1. Logic BEFORE the route (Request Phase)
    start_time = time.perf_counter()
    request_id = str(uuid.uuid4())

    # Inject trace ID into request state for downstream access
    request.state.trace_id = request_id

    # 2. Hand off to the next middleware or route handler
    response = await call_next(request)

    # 3. Logic AFTER the route (Response Phase)
    process_time = time.perf_counter() - start_time

    # Log the performance metric
    logger.info(f"RID: {request_id} | Path: {request.url.path} | Time: {process_time:.4f}s")

    # Standardize our response headers
    response.headers['X-Forge-Process-Time'] = str(process_time)
    response.headers['X-Forge-Trace-ID'] = request_id

    return response

Understanding Middleware Execution Order: The Onion Model

FastAPI middleware follows a Last-In-First-Out (LIFO) order for requests and First-In-First-Out (FIFO) for responses. The last middleware you add with app.add_middleware() is the first to process the request, and the last to process the response. This is identical to how ASP.NET Core and Express middleware work.

This matters because of the onion model: if middleware A adds CORS headers and middleware B injects a trace ID, middleware B must be added before A (so B runs first on the request) to ensure the trace ID is available before CORS processing. But then CORS will run last on the response, meaning the trace ID header might not be visible to the frontend if CORS strips unknown headers. You need to explicitly allow X-Forge-Trace-ID in allow_headers.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Execution order (request direction):
# 1. Security headers middleware (added last)
# 2. CORSMiddleware
# 3. Logging middleware (added first)
# 4. Route handler
# Response order is reverse

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_headers=["*"],
)

@app.middleware("http")
async def security_headers(request, call_next):
    response = await call_next(request)
    response.headers["X-Content-Type-Options"] = "nosniff"
    return response

@app.middleware("http")
async def logging_middleware(request, call_next):
    print(f"Request: {request.method} {request.url}")
    response = await call_next(request)
    print(f"Response status: {response.status_code}")
    return response

Short-Circuiting Middleware: Early Returns and IP Blocking

Sometimes you don't want to forward a request at all—like when an IP is on a blocklist, or you need to rate-limit a client. In FastAPI middleware, you can short-circuit by returning a Response object directly without calling call_next. This skips the rest of the middleware chain and the route handler, sending the response straight back to the client.

But there's a catch: if you short-circuit, you must ensure that any mandatory middleware (like CORS) hasn't been skipped. Because of the onion order, if you short-circuit in an outer middleware, no inner middleware runs. That means no CORS headers on the block response, and the client may not see the 403—just a CORS error. The solution: add CORS middleware as the outermost (first added) so it always runs, even on short-circuited responses.

from fastapi import FastAPI, Request, Response
import logging

app = FastAPI()
logger = logging.getLogger("thecodeforge.security")

BLOCKED_IPS = {"10.0.0.99", "192.168.1.200"}

@app.middleware("http")
async def ip_blocker(request: Request, call_next):
    client_ip = request.client.host if request.client else "unknown"
    if client_ip in BLOCKED_IPS:
        logger.warning(f"Blocked IP: {client_ip}")
        return Response(
            content='{"detail": "Forbidden"}',
            status_code=403,
            media_type="application/json"
        )
    # If not blocked, continue
    response = await call_next(request)
    return response

Error Handling Middleware: Global Exception Catching

FastAPI provides exception handlers, but a middleware can also catch exceptions that bubble up from routes or other middlewares. By wrapping await call_next(request) in a try-except, you can catch any unhandled exception and return a consistent JSON error response. This is especially useful for catching ValidationError, HTTPException, or unexpected server errors.

But careful catching everything can mask bugs. We log the error and return a 500 with a generic message, but preserve the trace ID for correlation.

from fastapi import FastAPI, Request, Response
from fastapi.responses import JSONResponse
import logging
import traceback

thecodeforge_logger = logging.getLogger("thecodeforge.error")

app = FastAPI()

@app.middleware("http")
async def catch_exceptions_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        return response
    except Exception as exc:
        # Log the full traceback internally
        thecodeforge_logger.error(
            f"Unhandled exception on {request.method} {request.url.path}: {traceback.format_exc()}"
        )
        # Return a generic error to the client
        return JSONResponse(
            status_code=500,
            content={"detail": "Internal server error. Please try again later.",
                      "trace_id": request.state.trace_id if hasattr(request, 'state') else None}
        )

Testing Middleware with FastAPI TestClient

You can't ship middleware without tests. FastAPI's TestClient provides a way to simulate requests and inspect responses without running the server. You can test that headers are set, that short-circuiting works, and that logging is called.

But a common mistake: the TestClient doesn't run ASGI middleware in the exact same way as a production server. Some middleware that relies on request.client.host or advanced ASGI features may behave differently in tests. We'll show you how to mock them and what to watch out for.

import pytest
from fastapi.testclient import TestClient
from io.thecodeforge.main import app  # assuming your FastAPI app is here

client = TestClient(app)

class TestCORS:
    def test_cors_headers_present(self):
        response = client.get("/", headers={"Origin": "https://dashboard.thecodeforge.io"})
        assert response.headers.get("access-control-allow-origin") == "https://dashboard.thecodeforge.io"
        assert response.headers.get("access-control-allow-credentials") == "true"

    def test_cors_rejects_wrong_origin(self):
        response = client.get("/", headers={"Origin": "https://evil.com"})
        # No CORS headers means browser blocks it
        assert "access-control-allow-origin" not in response.headers

class TestShortCircuit:
    def test_blocked_ip_returns_403(self):
        # Simulate an IP - this might not work in TestClient because request.client is None
        # We need to mock request.client
        with patch("fastapi.Request.client", new_callable=PropertyMock) as mock_client:
            mock_client.return_value = Mock(host="10.0.0.99")
            response = client.get("/")
            assert response.status_code == 403
            assert response.json() == {"detail": "Forbidden"}

CORS Preflight Requests: The OPTIONS Dance Your Browser Never Told You About

Your browser doesn't just blindly send cross-origin POST requests with custom headers. It first checks with the server using an HTTP OPTIONS request called a 'preflight.' If the server doesn't respond with the right CORS headers, the browser aborts the actual request before it even leaves the network stack.

This is where most CORS bugs live. You configure CORSMiddleware for GET and POST, but your frontend sends an Authorization header. The browser sends a preflight to check if that header's allowed. If your middleware doesn't include allow_headers=['Authorization'], the preflight fails silently and your JavaScript gets a cryptic CORS error.

The preflight response must include Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers. FastAPI's CORSMiddleware handles this automatically when you configure it correctly — but only if you know the dance exists. Skip a header, and you're debugging for hours.

// io.thecodeforge — python tutorial

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://frontend.example.com"],
    allow_methods=["GET", "POST"],      # Missing PUT, DELETE
    allow_headers=["Content-Type"],       # Missing Authorization
)

@app.post("/api/orders")
async def create_order():
    return {"status": "created"}

# curl -v -X OPTIONS http://localhost:8000/api/orders -H "Origin: https://frontend.example.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Authorization"

Allowing Any Origin With Credentials: The False Economy of the Wildcard

Setting allow_origins=["*"] sounds like a quick fix. It's not. The CORS spec explicitly forbids using a wildcard when allow_credentials=True. Why? Because a wildcard tells the browser to accept any origin, but credentials (cookies, Authorization headers) must only be sent to known origins. Combining them is a security hole the spec refuses to open.

When you try to set both, FastAPI's CORSMiddleware throws a ValueError at startup. Not at runtime — at startup. You'll see: 'CORS middleware configuration: allow_origins must not be a wildcard when allow_credentials is True.'

The fix is explicit. List every origin you trust. If you have multiple environments (staging, production, local dev), maintain a list. Use environment variables. Never ship with credentials + wildcard. The JavaScript console error you'll get on the frontend is useless: 'Access to fetch at ... has been blocked by CORS policy.' No mention of the credentials conflict.

If you truly need dynamic origins (e.g., a multi-tenant SaaS), implement a custom origin validation function. FastAPI's CORSMiddleware accepts a callable for allow_origins. Validate the request's Origin header against a database or config. That's production-grade.

// io.thecodeforge — python tutorial

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# This will crash on startup:
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Correct: explicit origins
from os import environ
origins = environ.get(
    "ALLOWED_ORIGINS",
    "https://app.example.com,http://localhost:3000"
).split(",")

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
)

@app.get("/api/user")
async def get_user():
    return {"user": "admin"}

CORS Middleware Is Not a Security Wall — It's a Browser Policy Enforcer

Juniors treat CORS middleware like a firewall. It's not. The browser enforces CORS, not your server. If you curl your API from a terminal, CORS headers are ignored. No browser, no CORS.

FastAPI's CORSMiddleware appends Access-Control-Allow-Origin to responses. That tells the browser: "This origin is allowed to read the response." Without it, the browser blocks JavaScript from reading cross-origin data—even if the server sends it.

This is critical for SPAs, mobile backends, and third-party API consumers. But understand the weakness: any non-browser client (curl, Postman, server-to-server) bypasses CORS entirely. So don't rely on CORS for auth. It's a UX enabler, not an access control gate. Use real auth middleware for security.

In production, never expose origins you don't explicitly trust. That includes * with credentials—we killed that myth in another section.

// io.thecodeforge — python tutorial

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "https://myapp.com",
    "https://admin.myapp.com",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/data")
async def get_data():
    return {"secret": "only browsers care"}

# curl http://localhost:8000/data
# -> {"secret": "only browsers care"}  # No CORS check – works fine

The CORSMiddleware Constructor: Tuning Origin, Method, and Header Whitelists

Eight parameters. Each one a footgun if you set it wrong. Let's skip the obvious ones and hit the killers.

allow_origins: A list of exact origins, or [""] for any. But [""] breaks with credentials. Prod tip: use allow_origin_regex for subdomain patterns like https://.*\.myapp\.com. Keeps the list tight.

allow_methods: Defaults to ["GET"]. If your frontend sends POST or DELETE, add them explicitly or use ["*"] for simplicity. But lazy wildcards leak attack surface—only allow methods your API actually exposes.

allow_headers: Same deal. If you send custom headers like X-Request-ID, list them. Using ["*"] is fine for open APIs, but for enterprise, whitelist.

expose_headers: The forgotten one. By default, browsers only expose a handful of response headers to JS. If your frontend needs X-Total-Count or Content-Disposition, add them here or JS gets null.

Set them once, test with curl and a browser, and don't touch again.

// io.thecodeforge — python tutorial

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex="https://.*\\.myapp\\.com",
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["X-Request-ID", "Content-Type", "Authorization"],
    expose_headers=["X-Total-Count"],
    allow_credentials=True,
    max_age=600,
)

@app.get("/items")
async def get_items():
    return {"count": 42}

# Browser gets: Access-Control-Expose-Headers: X-Total-Count
# So JS can read response.headers.get('X-Total-Count') -> 42