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 config as {Callable, Config}. A bare Callable is shorthand for {Callable, #{}} (empty config), the same way a {Path, Handler} route omits the state a {Path, Handler, State} route carries.

• module() / {module(), Config} — a module implementing this behaviour. If it exports the optional init(Config) callback, that runs once at pipeline-compile time and the value it returns becomes the State handed to every Mod:call(Req, Next, State); otherwise the config is threaded verbatim. See "init/1" below.
• fun((Request, Next, State) -> Result) / {Fun, State} — a fun has no init step, so its paired State is threaded verbatim as the third argument: Fun(Req, Next, State). Reach for a fun for lightweight inline middleware, a module when you want compile-time setup.

Config (module) and State (fun) default to #{} for the bare forms. The same callable can appear more than once with different config, 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.

init/1: optional compile-time setup (modules only)

A module middleware may implement init/1. When present, it runs once when the pipeline is compiled (listener boot and every reload_routes/2), never per request, and turns the user's raw config into the runtime state call/3 receives:

init(Config) -> State.            %% once, at compile time
call(Req, Next, State) -> Result. %% per request, the same State reused

Do config validation and any precompute (compile patterns, pre-join binaries, build lookup tables) in init/1: a bad config then fails loudly at listener start rather than on a request, and the work is paid once instead of per request. A bare module() entry is initialised with #{}, so an init/1 that reads an all-defaults config should accept the empty map.

When a module omits init/1, its config is threaded straight through as the call/3 state (#{} for a bare entry), exactly like a fun. So init/1 is purely opt-in: implement it for the compile-time hook, skip it for a stateless middleware that only needs call/3. A fun-form middleware never has an init/1 (there's no module to host the callback).

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}.