Continuation-style middleware for roadrunner handlers.

A middleware wraps the rest of the request pipeline:

-callback call(Request, Next) -> Result when
    Request :: roadrunner_req:request(),
    Next :: fun((Request) -> Result),
    Result :: roadrunner_handler:result().

The pipeline (handler at its core) returns {Response, Req2}. Each middleware sees the same shape and is expected to return it — either straight from Next or after transforming it.

Each middleware decides:

• pass through unchanged — Next(Req)
• transform the request — Next(Req#{...})
• short-circuit / halt — return {Response, Req} without calling Next
• wrap the response — let Next(Req) run, then transform what it returned (status, headers, body)
• side effects around the call — log, time, instrument

This shape is deliberately lighter than cowboy's deprecated (Req, Env) middlewares (which couldn't see the response) and much lighter than cowboy stream handlers (which split the request lifecycle into five callbacks). It matches the modern continuation/decorator pattern used by Plug.Builder, Express.js, Tower, and Servant.

No direct wire writes from middleware

Middleware code never has access to the underlying socket — the Request map intentionally excludes any socket reference. To respond, a middleware must return a Result (either the one from Next(Req) or its own response triple); there is no reply escape hatch equivalent to cowboy's mid-flight cowboy_req:reply/4.

This is a feature, not a limitation. Bytes only hit the wire from one place — the conn process — which means:

• [roadrunner, request, stop] telemetry fires for every request, with consistent duration and status metadata.
• gzip wrapping, response transforms, and Content-Length framing are applied uniformly regardless of which middleware produced the response.
• Send errors are handled in one place ([roadrunner, response, send_failed] telemetry, drain bookkeeping, slot release).
• The "halt" pattern is structurally simple: don't call Next, just return a response. There's no second halt protocol to maintain (compare: an arizona cowboy adapter has to support BOTH stashed redirects AND raw-write-from-middleware to stay backward-compatible with cowboy's permissiveness; the roadrunner adapter only handles the stashed-redirect path).

If you're porting middleware from cowboy that called cowboy_req:reply/4 directly, replace the call with returning a response triple — {Status, Headers, Body} — from the middleware, and the framework writes the bytes.

Where middlewares live

• Listener-level: roadrunner_listener:start_link(_, #{middlewares => [...]}). These run for every request — single-handler and routed.
• Per-route: as the middlewares key on a map-shape route entry: #{path => ~"/path", handler => handler_mod, middlewares => [...]}. The tuple shorthands ({Path, Handler} / {Path, Handler, State}) intentionally cannot carry middlewares — use the map form when you want them.

When both are configured, listener middlewares wrap route middlewares which wrap the handler — first in each list runs outermost.

Middleware shape

Each entry in a middlewares list is one of:

• module() — the module's call/2 (this behaviour callback) is invoked.
• fun((Request, Next) -> Result) — invoked directly.

Examples

%% Auth check — halt with 401 when missing.
auth(Req, Next) ->
    case roadrunner_req:header(~"authorization", Req) of
        undefined -> {roadrunner_resp:unauthorized(), Req};
        _ -> Next(Req)
    end.

%% Around: time the whole request including the response write.
timing(Req, Next) ->
    Start = erlang:monotonic_time(millisecond),
    Result = Next(Req),
    logger:info(#{took_ms => erlang:monotonic_time(millisecond) - Start}),
    Result.

%% Inject a server header on every response.
server_header(Req, Next) ->
    {{S, H, B}, Req2} = Next(Req),
    {{S, [{~"server", ~"roadrunner"} | H], B}, Req2}.