Behaviour for handling parsed HTTP requests.

Implementations receive the parsed request map and return a {Response, Req2} pair — the Response selects what the conn does on the wire, and Req2 is the (possibly mutated) request threaded back to the conn. Always returning Req2 lets the conn drain unread bodies in body_buffering => manual mode, lets response middlewares observe and rewrite, and matches cowboy's idiom of threading Req through the entire request lifecycle.

Response is one of:

• {StatusCode, Headers, Body} — buffered response, encoded and sent in one shot. Without a content-length or transfer-encoding header, HTTP/1.1 adds content-length from the body (HTTP/2 and HTTP/3 frame the body themselves).
• {stream, StatusCode, Headers, StreamFun} — chunked streaming. The connection emits status + headers (with Transfer-Encoding: chunked auto-prepended) and calls StreamFun(Send) where Send(Data, nofin | fin | {fin, Trailers}) writes one chunk; fin also writes the size-0 terminator and {fin, Trailers} writes the terminator followed by the given trailer headers (RFC 9112 §7.1.2). Trailer names should be advertised in the response's Trailer header.
• {sendfile, StatusCode, Headers, {Filename, Offset, Length}} — zero-copy file body. The connection emits status + headers verbatim (the handler is responsible for Content-Length and Content-Type), then dispatches file:sendfile/5 for plain TCP (kernel-space copy) or a chunked read+send loop for TLS (where the kernel sendfile path can't see plaintext). Used by roadrunner_static so large assets don't get copied through the Erlang heap.
• {loop, StatusCode, Headers, State} — message-driven streaming. The connection emits status + headers, then enters a receive loop in the conn process. Each Erlang message is dispatched through the optional handle_info/3 callback, which can call Push(Data) to emit a chunk. Returning {stop, _} writes the size-0 terminator and closes. Useful for SSE/long-poll endpoints that subscribe to a pubsub topic in handle/1 and forward messages to the wire.
• {websocket, Module, State} — upgrade to a roadrunner_ws_handler.
• {websocket, Module, State, Headers} — the same upgrade, with Headers added to the 101 Switching Protocols response (e.g. a set-cookie). The handshake's own headers (upgrade, connection, sec-websocket-accept, sec-websocket-extensions) win: an entry naming one of them is dropped, as is a content-length or transfer-encoding, which a 1xx response must not carry.

If the handler did not call roadrunner_req:read_body/1,2, just thread the original Req back. Idiomatic shape:

handle(Req) ->
    {{200, [], ~"hello"}, Req}.

handle(Req) ->
    {ok, Body, Req2} = roadrunner_req:read_body(Req),
    {{200, [], Body}, Req2}.

init_route/1: optional setup when the routes compile

A handler may implement init_route/1. It runs once per route that names the handler, when the listener starts and again on every roadrunner_listener:reload_routes/2, never per request. It gets the route's state and its return becomes the state the handler reads with roadrunner_req:state/1:

init_route(Opts) -> State.  %% once per route, when the routes compile
handle(Req) -> Result.      %% per request, roadrunner_req:state(Req) is State

Check the route's options and precompute there: a bad option then stops the listener from starting instead of failing a request, and the work is paid once. roadrunner_static uses it this way. It is the handler's counterpart of a middleware's init/1; the name differs because a module can also be a roadrunner_ws_handler, whose init/1 runs per WebSocket session.