Interceptors: the middleware onion

An interceptor wraps every call as one composable layer, so cross-cutting concerns — auth, tracing, metrics, the retry policy — are written once around the handler instead of copy-pasted into every method; client-side interceptors wrap the outbound call, server-side ones wrap the inbound call, and together they form a chain a request passes inward through and the response passes back outward.

Previously

We just built a retry policy — but it can't live inside each method any more than deadline-checking or auth can; all of these wrap every call, so we need the one structural pattern that lets them compose as layers.

Scene 08

Interceptors: the middleware onion

Watch
Try it
Predict
Capture

What to watch for

Every call needs the same wrapping work: prove the caller is allowed (auth), open a span so it's traceable (trace), count and time it (metrics), and apply the retry budget you built last scene (retry). Copy-pasting that into all 40 methods of a service is madness. The fix is an interceptor: a single piece of code that wraps a call, runs its bit before handing the call along, and runs its bit again on the way back. Stack several of them and you get a middleware chain — an onion of layers around the real method. Watch greet("Ada") enter from outside and pass INWARD through auth → trace → metrics → retry to reach the handler, then watch the reply travel back OUTWARD through the same layers in reverse. Same layers, opposite order.

Concentric rings wrap a central handler core that runs greet("Ada").
The request enters from the entry edge (your code on the client, the transport on the server) and travels INWARD, crossing each installed ring in turn; the response travels back OUTWARD through the same rings in reverse.
Each ring is ONE interceptor — auth, trace, metrics, retry are example layers; the ordered stack of them is the middleware chain.
A ring drawn dashed/ghosted is switched off: the call passes straight through it.
The side toggle decides whether this onion wraps the client's outbound call or the server's inbound call.

Implementation

Highlighted lines are the ones running in the diagram right now.

Client.intercept

one client-side interceptor wraps the OUTBOUND call

1def intercept(ctx, method, req, invoker):
2    # runs on the way IN, before the call leaves
3    ctx = attach(ctx)  # e.g. deadline header, token
4    resp = invoker(ctx, method, req)  # hand to next layer
5    # runs on the way OUT, on the reply
6    observe(resp)
7    return resp

Server.intercept

one server-side interceptor wraps the INBOUND call

1def intercept(ctx, req, handler):
2    # runs as the call ARRIVES, before the handler
3    if not allowed(ctx):   # auth lives here, not in the method
4        return Unauthenticated
5    resp = handler(ctx, req)  # the real greet("Ada")
6    # runs after the handler, before the reply leaves
7    record(resp)
8    return resp

Chain.compose

fold the enabled layers into one onion around the handler

1def compose(layers, handler):
2    call = handler  # the core
3    for layer in reversed(layers):
4        if not layer.enabled:
5            continue   # skip: call passes straight through
6        call = wrap(layer, call)  # outer now wraps inner
7    return call  # the chain, outermost-first

Sources

Where this sits in Build a gRPC-style RPC framework

Scene 08 of 14, in the Reliability act — Deadlines, cancellation, retries, and the interceptor onion.. An interceptor wraps every call as one composable layer, so auth, metrics, tracing, and the retry policy are written once around the handler instead of per method.

Up next. Our chain of layers decides WHAT happens to a call — but not WHERE it goes; the moment we ask which of many backends gets the call, HTTP/2's one-connection trick turns into a trap.

All 14 scenes in Build a gRPC-style RPC framework · Every curriculum

Built with Arqly

Every scene in Build a gRPC-style RPC framework builds on the one before it.All 14 Build a gRPC-style RPC framework scenes