Continuation-style middleware for roadrunner handlers.

A middleware wraps the rest of the request pipeline:

-callback call(Request, Next, State) -> Result when
    Request :: roadrunner_req:request(),
    Next :: fun((Request) -> Result),
    State :: state(),
    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 a Callable, optionally paired with its State as {Callable, State}. State is the middleware's own configuration, handed to the third argument of the call. A bare Callable is shorthand for {Callable, undefined}, the same way a {Path, Handler} route omits the state a {Path, Handler, State} route carries.

• module() / {module(), State} — the module's call/3 behaviour callback is invoked as Mod:call(Req, Next, State).
• fun((Request, Next, State) -> Result) / {Fun, State} — the fun is invoked directly as Fun(Req, Next, State).

State defaults to undefined for the bare forms. The same callable can appear more than once with different State, e.g. [{rate_limit, #{rps => 10}}, {rate_limit, #{rps => 100}}].

Middleware State is not the request's state field. Route state ({Path, Handler, State}) is injected onto the request map and read with roadrunner_req:state/1; middleware State is handed to call/3 as an argument and never touches the request.

Examples

%% Stateless auth check — halt with 401 when missing. Wire it as a
%% bare `fun ?MODULE:auth/3`.
auth(Req, Next, _State) ->
    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, _State) ->
    Start = erlang:monotonic_time(millisecond),
    Result = Next(Req),
    logger:info(#{took_ms => erlang:monotonic_time(millisecond) - Start}),
    Result.

%% Stateful: inject a configurable `server` header on every response.
%% Wire it as `{fun ?MODULE:server_header/3, ~"roadrunner"}`.
server_header(Req, Next, Server) ->
    {{S, H, B}, Req2} = Next(Req),
    {{S, [{~"server", Server} | H], B}, Req2}.