-spec accept_connect(connection(), stream_id(), headers()) ->
                        {ok, gen_tcp | ssl, term(), binary()} | {error, term()}.

Server: reply 200 Connection Established to a classic HTTP/1.1 CONNECT (RFC 9110 §9.3.6, RFC 9112 §3.2.3 authority-form request-target) and take ownership of the raw socket. Mirror of accept_upgrade/3 for the 101 Switching Protocols case, but writes status 200 and injects no Connection/Upgrade headers so bytes after CRLF belong to the tunnel.

-spec accept_upgrade(connection(), stream_id(), headers()) -> {ok, term(), binary()} | {error, term()}.

Server: reply 101 Switching Protocols to an upgrade request and take ownership of the raw socket. Injects the Connection: Upgrade and Upgrade: <proto> framing headers itself and strips any caller-supplied copies (case-insensitive), so the 101 carries exactly one of each. Pass only protocol-specific extras in ExtraHeaders (e.g. sec-websocket-accept).

-spec continue(connection(), stream_id()) -> ok | {error, term()}.

Server: send 100 Continue to a client waiting on Expect.

-spec peername(connection()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

Address and port of the connected peer. Works in both modes: the remote client on a server connection, the remote server on a client connection.

-spec pipeline(connection(), boolean()) -> ok | {error, term()}.

Toggle request pipelining on a client connection.

-spec request(connection(), headers()) -> {ok, stream_id()} | {error, term()}.

Send a request using h2-compatible pseudo-headers. The list may contain :method, :path, :authority; they're translated into the HTTP/1.1 request line + Host header.

-spec respond(connection(), stream_id(), status(), headers(), iodata()) -> ok | {error, term()}.

Server: send a complete response (status, headers, and body) in a single socket write and end the stream. A Content-Length is added when the headers carry neither Content-Length nor Transfer-Encoding, so the body is sent fixed-length rather than chunked. Use this for fully-known bodies; use send_response/4 + send_data/4 for streaming.

If the request body has not been fully received when this is called (an early response, e.g. rejecting an oversized upload with 413), h1 adds Connection: close, sends the response, then drains and discards the rest of the inbound body before closing the socket. The response is delivered cleanly and the connection is not reused. The drain is bounded by the listener's early_response_drain budget (default {infinity, 30000}).

-spec respond(connection(), stream_id(), status(), headers(), iodata(), respond_opts()) ->
                 ok | {error, term()}.

As respond/5, with per-response options. early_response_drain overrides the listener's drain budget for this response only: pass a larger {MaxBytes, MaxMs} to a known-large upload endpoint, or 0 to close immediately without draining.

-spec send_data(connection(), stream_id(), binary(), boolean()) -> ok | {error, term()}.

Send a body chunk. With EndStream = true the stream is ended; if the request body was not fully received first (server side), h1 advertises Connection: close and drains the remaining inbound body before closing, as for respond/5.

-spec send_informational(connection(), stream_id(), 100..199, headers()) -> ok | {error, term()}.

Server: send an interim (1xx) response, e.g. 103 Early Hints, ahead of the final response. May be called several times per stream, until the final response headers are sent. 101 is rejected (use the Upgrade machinery), and so are HTTP/1.0 clients (RFC 9110 §15.2).

-spec serve_socket(ssl:sslsocket() | gen_tcp:socket(), server_opts()) -> {ok, pid()} | {error, term()}.

Serve an already-accepted connection: run the server loop on a socket someone else accepted. The caller has completed the TCP accept and, for TLS, the handshake and ALPN negotiation — h1 does not handshake again, so cert, key, verify and ssl_opts are ignored here. Use it to serve HTTP/1.1 and HTTP/2 on one TLS port: negotiate ALPN yourself, then hand http/1.1 sockets to this function.

Requires handler; every other option is the per-connection subset start_server/2 accepts (timeouts, parser limits, drain budget).

The socket must be passive ({active, false}): h1 arms it itself, and bytes an active socket already delivered to the caller's mailbox cannot be recovered.

On {ok, Pid} the returned process is linked to the caller and owns the socket: it is the socket's controlling process from that point on, and closes it when it exits (unless the socket was handed off by Upgrade or CONNECT). Killing the caller therefore closes the connection. These connections belong to no listener, so stop_server/1 does not close them.

  {ok, Sock} = ssl:handshake(Raw, 5000),
  {ok, <<"http/1.1">>} = ssl:negotiated_protocol(Sock),
  {ok, _Pid} = h1:serve_socket(Sock, #{handler => fun my_app:handle/5}).

-spec stop_accepting(server_ref()) -> ok.

Stop accepting new connections while continuing to serve the established ones (graceful drain). Synchronous. Call stop_server/1 afterwards to close the remaining connections.

-spec stop_server(server_ref()) -> ok.

Stop a server. Synchronous: closes the listen socket, the acceptor pool, and every accepted connection (kept-alive and in-flight included) before returning.

-spec upgrade(connection(), binary(), headers()) ->
                 {ok, stream_id(), term(), binary(), headers()} | {error, term()}.

Client: send an Upgrade request and wait for 101 Switching Protocols.