-type http2_opts() ::
          #{conn_window => 1..2147483647,
            stream_window => 1..2147483647,
            window_refill_threshold => 1..2147483647}.

HTTP/2 listener tunables (under {http2, ThisMap} in protocols).

• conn_window — connection-level receive window peak in bytes (1..2^31-1). RFC 9113 default 65535; values above the default emit an early WINDOW_UPDATE(0, peak - 65535) after the server SETTINGS. Worst-case memory is max_clients × peak.
• stream_window — stream-level receive window peak in bytes (1..2^31-1). Advertised via SETTINGS_INITIAL_WINDOW_SIZE. Default 65535. Setting above conn_window is allowed but not useful — the conn-level peak is the binding constraint.
• window_refill_threshold — refill trigger in bytes. When the remaining window drops below this, the conn refills back to the peak. Lower threshold = fewer WINDOW_UPDATE frames per byte consumed but a smaller live window between refills. Default 32768.

-type http3_opts() :: #{listeners => 1..1024}.

HTTP/3 listener tunables (under {http3, ThisMap} in protocols).

• listeners — number of reuseport listener processes in the QUIC pool (1..1024). They bind the same UDP port and share one connection registry; the kernel spreads inbound datagrams across them, so inbound demux parallelizes across cores. Default 8. 1 disables pooling (a single listener, no SO_REUSEPORT).

-type opts() ::
          #{port := inet:port_number(),
            routes =>
                module() |
                {module(), term()} |
                #{handler := module(),
                  state => term(),
                  middlewares => roadrunner_middleware:middleware_list()} |
                roadrunner_router:routes(),
            middlewares => roadrunner_middleware:middleware_list(),
            max_content_length => non_neg_integer(),
            ws => ws_opts(),
            request_timeout => non_neg_integer(),
            keep_alive_timeout => non_neg_integer(),
            num_acceptors => pos_integer(),
            max_keep_alive_requests => pos_integer(),
            max_clients => pos_integer(),
            min_bytes_per_second => non_neg_integer(),
            rate_check_interval => pos_integer(),
            body_buffering => auto | manual,
            slot_reconciliation => disabled | #{interval := pos_integer()},
            graceful_drain => boolean(),
            hibernate_after => pos_integer(),
            protocols => [protocol_entry(), ...],
            tls => [ssl:tls_server_option()]}.

Listener configuration map.

Required:

• port — TCP port to bind. 0 lets the kernel pick an ephemeral port; query it back with port/1.

Routing (pick one):

• routes => module() — single-handler dispatch. Every request goes to Module:handle/1 and roadrunner_req:state/1 returns undefined.
• routes => {module(), term()} — single-handler dispatch with per-handler state. The opaque second element is reachable from the handler via roadrunner_req:state/1.
• routes => #{handler := module(), state => term(), middlewares => [...]} — map form for single-handler dispatch; use it to attach per-handler middlewares (or future per-handler framework knobs) alongside the state.
• routes => roadrunner_router:routes() — list of route entries; each entry is either a {Path, Handler} / {Path, Handler, State} tuple or a #{path := Path, handler := Handler, state => ..., middlewares => [...]} map. First match wins.

Optional middleware and timing knobs (durations in milliseconds):

• middlewares — listener-wide pipeline applied to every request.
• max_content_length — request-body cap; over-cap reads return payload_too_large. Default 10 MB.
• ws — WebSocket inbound size caps as a nested map (see ws_opts/0): max_frame_size (per-frame payload cap) and max_message_size (reassembled + decompressed message cap). Both default to 10 MB; over-cap closes the connection with code 1009.
• request_timeout — header-read timeout on a fresh conn. Default 30 s.
• keep_alive_timeout — idle timeout between requests on a keep-alive conn. Default 60 s.
• num_acceptors — size of the acceptor pool. Default 10.
• max_keep_alive_requests — requests served per conn before forced close. Default 1000.
• max_clients — concurrent connection cap. Default 150.
• min_bytes_per_second — slow-loris guard on the request-read phase (0 disables). Default 100.
• rate_check_interval — how often the rate guard re-checks (ms). Default 1000.
• body_buffering — auto (default; framework reads the full body before invoking the handler) or manual (handler calls roadrunner_req:read_body/1,2).
• slot_reconciliation — disabled (default) or #{interval := Ms} to periodically reap slots orphaned by brutal-kill exits.
• graceful_drain — opt out of the per-conn pg drain group (true default; false trades drain notification for ~10 % lower per-conn overhead on short-lived workloads).
• hibernate_after — when set, idle conns hibernate after this many milliseconds of main-loop idle time.
• protocols — list of protocol_entry/0. Default [http1]. On TLS this drives alpn_preferred_protocols automatically.
• tls — [ssl:tls_server_option()] for HTTPS. Empty / absent for plain HTTP.

The inline source comments next to each field carry the deeper ops-tuning rationale.

-type protocol_entry() ::
          http1 | http2 | http3 | {http1, #{}} | {http2, http2_opts()} | {http3, http3_opts()}.

One protocol entry in the listener's protocols list. Either a bare atom (http1 / http2 / http3) for default opts, or a tuple {Proto, ProtoOpts} carrying protocol-specific tuning. HTTP/1 has no tunables (its opts map must be empty); HTTP/2 tunables live under http2_opts/0 and HTTP/3 under http3_opts/0.

On TLS the list drives alpn_preferred_protocols for the TCP protocols. On plain TCP, [http2] means prior-knowledge h2c (client sends the h2 preface directly); [http1, http2] on plain TCP is rejected at init/1 since there's no Upgrade: h2c implementation.

http3 runs HTTP/3 over QUIC on the UDP port of the same number, and requires tls (QUIC mandates TLS 1.3) — listing it without tls is rejected at init/1. It co-listens with the TCP protocols: e.g. [http1, http2, http3] serves h1/h2 over TCP and h3 over UDP on the same port. The QUIC handshake advertises the h3 ALPN itself, so http3 does not appear in the TCP alpn_preferred_protocols.

-type ws_opts() :: #{max_frame_size => 0..2147483647, max_message_size => 0..2147483647}.

WebSocket inbound size caps (under ws in the listener opts).

• max_frame_size — per-frame payload cap in bytes. An inbound frame declaring more than this closes the connection with code 1009 before the payload is buffered. Default 10 MB.
• max_message_size — cap on a reassembled message in bytes: the running fragment total, and the decompressed size when permessage-deflate is negotiated. Over-cap closes with 1009. Must be >= max_frame_size. Default 10 MB.