-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 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(),
            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.
• 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 | {http1, #{}} | {http2, http2_opts()}.

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

On TLS the list drives alpn_preferred_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.