Middleware¶
Middleware runs around every HTTP handler.
from oxbrook import Reply
@app.middleware
async def require_key(request, call_next):
if request.header("x-api-key") != SECRET:
return Reply({"error": "unauthorized"}, status=401)
reply = await call_next(request)
reply.headers["x-served-by"] = "oxbrook"
return reply
Middleware runs outermost-first in registration order and unwinds in reverse. It can observe a request, add response headers, change the status, or refuse to call the handler at all.
call_next returns a Reply, not a response¶
A Reply holds whatever the handler
returned, still unserialized: a dict, a model, a Response, an SSE, or
None. It is not a finished body.
This is intentional. A handler returning a dict is serialized to JSON in Rust,
and materializing a body so that middleware could inspect it would discard that
on every request, including requests whose middleware never inspects anything.
Middleware that does need the bytes can replace reply.value with a Response
it builds itself.
@app.middleware
async def timing(request, call_next):
started = time.perf_counter()
reply = await call_next(request)
reply.headers["x-elapsed-ms"] = f"{(time.perf_counter() - started) * 1000:.1f}"
return reply
Cost¶
Routes are untouched when no middleware is registered — the chain is built at startup, not per request, and a route with an empty chain calls the handler directly.
WebSocket routes¶
Middleware does not wrap socket handlers. A WebSocket handler runs after the
handshake has already completed, so there is nothing useful left to intercept:
the 101 is sent and the client believes it is connected.
Middleware does wrap a socket route's authorize function, which runs before
the handshake. That is how an app-wide rule still reaches sockets: give the
route an authorizer, even one that accepts everything, and the middleware chain
wraps it.
async def accept(request):
return None # None or True accepts; a Response or Reply refuses
@app.websocket("/feed", authorize=accept)
async def feed(request, ws): ...
With require_key registered above, that socket is now refused with 401
before the upgrade, by the same rule that guards the REST routes. A socket
route with no authorizer at all is not wrapped by anything. See
WebSocket.
A socket declared with auth= is wrapped whether or not it
has an authorizer, since its check has to run before the handshake too.
Middleware and authentication¶
On a route with auth=, the app's middleware runs outside the
check and the routers' inside it. An access log or an audit trail registered
on the app sees every refusal and, afterwards, who was
calling; a router's middleware never runs for a
caller who was refused. App middleware finds the request body unread, since
the body waits for the check: see request.read().
For an authentication rule of your own, write a scheme
rather than middleware: it is then enforced on WebSockets and tool calls, and
documented in OpenAPI, as well.
Router middleware¶
A router can register middleware that runs only for its own routes, inside the app's. An exception with a registered exception handler is mapped at every layer, so middleware always receives a reply from what it wraps.