-spec accept(QuicConn, Opts) -> {ok, pid()} | {error, term()}
                when QuicConn :: pid(), Opts :: accept_opts().

Start the server side of HTTP/3 on a QUIC connection the caller already holds, and return the HTTP/3 process.

Use it from a listener's alpn_handler to serve HTTP/3 beside other protocols on one port (see the module doc). Returning the HTTP/3 process from the hook makes it the QUIC connection's owner during the handshake, before any stream event.

Opts takes the options start_server/3 applies to each connection: handler, settings, stream_type_handler, h3_datagram_enabled, max_buffered_body, defer_requests_until_settings, stream_reset_final_size, notify_streams_available and owner. owner defaults to the caller, which inside alpn_handler is the QUIC connection process, so pass the process that should receive the owner events.

The handler can be:

• A function: fun(Conn, StreamId, Method, Path, Headers) -> ok
• A module implementing handle_request/5

Example:

  alpn_handler => fun
      (Conn, <<"h3">>) ->
          quic_h3:accept(Conn, #{handler => fun my_http:handle/5, owner => Router});
      (Conn, <<"myproto">>) ->
          {ok, spawn(fun() -> myproto:loop(Conn) end)}
  end

Bad options return {error, {bad_opts, _}}, which fails the handshake. The QUIC options start_server/3 would set, stream_reset_final_size, notify_streams_available and max_datagram_frame_size, go on the listener.

-spec cancel(conn(), stream_id()) -> ok.

Cancel a stream with H3_REQUEST_CANCELLED error.

-spec cancel(conn(), stream_id(), error_code()) -> ok.

Cancel a stream with a specific error code.

-spec cancel_push(conn(), push_id()) -> ok.

Cancel a push (client only).

Sends CANCEL_PUSH to tell the server we don't want this push. Can be called after receiving a push_promise notification.

-spec close(conn()) -> ok.

Close the connection.

Immediately closes the HTTP/3 connection and underlying QUIC connection.

-spec close(conn(), error_code()) -> ok.

Close the connection with an HTTP/3 error code.

Same as close/1, but the peer receives ErrorCode in CONNECTION_CLOSE, for example H3_SETTINGS_ERROR (0x109) or H3_ID_ERROR (0x108).

-spec connect(Host, Port) -> {ok, conn()} | {error, term()}
                 when Host :: binary() | string() | inet:ip_address(), Port :: inet:port_number().

Connect to an HTTP/3 server.

Establishes a QUIC connection with ALPN "h3" and starts the HTTP/3 connection layer.

The calling process becomes the owner and will receive HTTP/3 events as messages.

-spec connect(Host, Port, Opts) -> {ok, conn()} | {error, term()}
                 when
                     Host :: binary() | string() | inet:ip_address(),
                     Port :: inet:port_number(),
                     Opts :: connect_opts().

Connect to an HTTP/3 server with options.

Options:

• sync - If true, wait for H3 connection to be established before returning. This ensures requests can be made immediately. Default: false.
• connect_timeout - Timeout in ms for sync connect. Default: 5000.

-spec consume(conn(), stream_id(), non_neg_integer()) -> ok | {error, term()}.

Return receive credit on a flow_control => manual stream.

Call it after processing Bytes of body received on StreamId; the peer may then send up to one stream window past what was consumed. HTTP/3 framing is credited without it, so count payload bytes only. A no-op returning ok on an auto stream. Returns {error, unknown_stream} once the stream is finished or reset.

  ok = quic_h3:set_stream_handler(Conn, StreamId, self(), #{flow_control => manual}),
  %% after handling Data:
  ok = quic_h3:consume(Conn, StreamId, byte_size(Data)).

-spec early_data_accepted(conn()) -> boolean() | unknown.

Report whether the peer accepted 0-RTT early data.

Returns true if the server accepted 0-RTT, false if it rejected the early data, or unknown before the handshake reaches a state where the outcome is known. RFC 9001 Section 4.6.

-spec get_peer_settings(conn()) -> map() | undefined.

Get peer HTTP/3 settings.

Returns undefined if SETTINGS has not been received yet.

-spec get_quic_conn(conn()) -> pid().

Get the underlying QUIC connection for an H3 connection.

Needed for WebTransport which uses native QUIC streams alongside H3.

-spec get_settings(conn()) -> map().

Get local HTTP/3 settings.

-spec goaway(conn()) -> ok.

Initiate graceful shutdown.

Sends a GOAWAY frame to the peer. No new requests will be accepted, but existing streams will complete.

-spec h3_datagrams_enabled(conn()) -> boolean().

Whether both sides negotiated RFC 9297 support and the extension is live on this connection.

-spec max_datagram_size(conn(), stream_id()) -> non_neg_integer().

Largest payload one H3 DATAGRAM for the given stream can carry now: quic:datagram_max_size/1 less the quarter stream ID. Returns 0 if RFC 9297 isn't live or the peer advertised 0 for max_datagram_frame_size.

-spec open_bidi_stream(conn()) -> {ok, stream_id()} | {error, term()}.

Open a client-initiated bidirectional stream outside the H3 request/response flow. Equivalent to open_bidi_stream(Conn, undefined) — the stream is a plain request stream and the caller is responsible for HEADERS/DATA framing (typically not useful on its own; prefer the /2 form below).

-spec open_bidi_stream(conn(), non_neg_integer() | undefined) -> {ok, stream_id()} | {error, term()}.

Open a client-initiated bidirectional stream and pre-claim it with an extension signal type (e.g. WebTransport's 16#41).

When SignalType is a non-negative integer, the stream is recorded in the H3 connection's claimed-bidi table. Subsequent inbound data on that stream bypasses the HTTP/3 request parser and is delivered to the connection owner as {quic_h3, Conn, {stream_type_data, bidi, StreamId, Data, Fin}}. The owner also receives {quic_h3, Conn, {stream_type_open, bidi, StreamId, SignalType}} at open time, mirroring the peer-initiated claimed-bidi path.

The caller sends the extension signal varint (and any session/header prefix) itself via send_data/4 — this API is extension-agnostic.

When SignalType is undefined, no claim is recorded and the stream behaves as a normal H3 request stream.

-spec open_uni_stream(conn(), non_neg_integer()) -> {ok, stream_id()} | {error, term()}.

Open a unidirectional stream of an extension type (e.g. WebTransport's 16#54), write the stream-type varint and claim it.

The owner receives {quic_h3, Conn, {stream_type_open, uni, StreamId, StreamType}}, and later {stream_type_stop_sending, uni, StreamId, ErrorCode} if the peer stops the stream, as for a stream it opened. Write the rest of the stream with quic:send_data/4 on get_quic_conn/1.

-spec push(conn(), stream_id(), headers()) -> {ok, push_id()} | {error, term()}.

Initiate a server push (server only).

Sends a PUSH_PROMISE on the request stream and allocates a push ID. Returns the push ID for subsequent send_push_response/send_push_data calls.

The Headers should contain the pseudo-headers for the pushed request: :method, :scheme, :authority, and :path.

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

Send an HTTP request.

Opens a new request stream and sends the HEADERS frame. Returns the stream ID for tracking the response.

Required pseudo-headers:

• :method - HTTP method (GET, POST, etc.)
• :scheme - URL scheme (https)
• :path - Request path
• :authority - Host authority

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

Send an HTTP request with options.

Options:

• end_stream - Close the request side after the headers (default true).
• flow_control - auto (default) or manual. With manual the response body waits for consume/3: the server can send at most one stream window past what the caller consumed.

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

Send a full HTTP response (status, headers and body) in one call.

Coalesces the work of send_response/4 plus a final send_data/4 with end-stream. HEAD, 204 and 304 responses send no body. A 1xx returns {error, informational_status} and 101 {error, status_101_forbidden}.

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

Send body data on a request stream.

For clients, this sends request body data. For servers, this sends response body data: after a HEAD, 204 or 304 response it returns ok and sends nothing, and before a final response it returns {error, no_final_response}.

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

Send body data with fin flag.

Set Fin to true to indicate the end of the body. A server gets ok with nothing sent after a HEAD, 204 or 304 response, and {error, no_final_response} before a final response.

Returns {error, send_queue_full} when the connection's send queue is full. Nothing was written; wait for the connection to drain and send the same piece again. Once the queue is below half its ceiling, the caller receives {quic_h3, Conn, {send_ready, StreamId}}, once.

-spec send_datagram(conn(), stream_id(), iodata()) -> ok | {error, term()}.

Send an HTTP Datagram bound to a request stream.

Enabled by passing h3_datagram_enabled => true to connect/3 or start_server/3; the underlying QUIC connection must also advertise a non-zero max_datagram_frame_size (RFC 9221) for the H3 extension to go live.

Returns {error, h3_datagrams_disabled} when the extension was not negotiated, {error, unknown_stream} when the stream id is not a known request stream, or one of the RFC 9221 error atoms (datagrams_not_supported, datagram_too_large, datagram_too_large_for_path, congestion_limited) forwarded from the QUIC layer.

Payload for a WebTransport-style CONNECT session is typically handed over unmodified; the quarter-stream-id prefix is added automatically.

-spec send_push_data(conn(), push_id(), binary(), boolean()) -> ok | {error, term()}.

Send data on a push stream (server only).

Set Fin to true to indicate this is the last data. Returns ok and sends nothing after a HEAD, 204 or 304 pushed response, and {error, no_final_response} before a final one.

-spec send_push_response(conn(), push_id(), status(), headers()) -> ok | {error, term()}.

Send response headers on a push stream (server only).

After push/3 returns a push ID, use this to send the response headers. The :status pseudo-header is added automatically. A pushed response to HEAD, or a 204 or 304, ends the push stream. Status 101 returns {error, status_101_forbidden}.

-spec send_response(conn(), stream_id(), status(), headers()) -> ok | {error, term()}.

Send an HTTP response (server only).

Sends the response status and headers. The body should be sent separately using send_data/4. A HEAD, 204 or 304 response is sent at once and ends the stream. A 1xx is interim and can be followed by more. Content-Length is removed from a 1xx and a 204. Status 101 returns {error, status_101_forbidden}.

-spec send_trailers(conn(), stream_id(), headers()) -> ok | {error, term()}.

Send trailers on a request stream.

Trailers are sent after the body and signal the end of the stream. A server gets ok with nothing sent after a HEAD, 204 or 304 response, and {error, no_final_response} before a final response.

-spec set_max_push_id(conn(), push_id()) -> ok | {error, term()}.

Set the maximum push ID (client only).

This enables server push up to the specified push ID. Call this after connecting to allow the server to push resources. The MaxPushId cannot be decreased once set.

Example:

  %% Enable push with up to 10 promised resources (push IDs 0-9)
  ok = quic_h3:set_max_push_id(Conn, 9).

-spec set_stream_handler(conn(), stream_id(), pid()) ->
                            ok | {ok, [{binary(), boolean()}]} | {error, term()}.

Register a handler to receive stream body data.

By default, body data messages are sent to the connection owner. For server handlers that need to receive body data (e.g., POST bodies), call this function to redirect data to the handler process.

The handler will receive messages of the form: {quic_h3, Conn, {data, StreamId, Data, Fin}}

If data arrived before registration, it is returned as a list of {Data, Fin} tuples that the handler should process.

Example:

  handle_request(Conn, StreamId, <<"POST">>, _Path, _Headers) ->
      case quic_h3:set_stream_handler(Conn, StreamId, self()) of
          ok ->
              receive_body(Conn, StreamId, <<>>);
          {ok, BufferedChunks} ->
              Body = process_chunks(BufferedChunks),
              receive_body(Conn, StreamId, Body)
      end.

-spec set_stream_handler(conn(), stream_id(), pid(), map()) ->
                            ok | {ok, [{binary(), boolean()}]} | {error, term()}.

Register a handler with options.

Options:

• drain_buffer - If true (default), returns buffered data. If false, sends buffered data as messages.
• flow_control - auto (default) grants the peer receive credit as data arrives. manual grants it only for the bytes the handler returns with consume/3, so a handler that stops reading stops the peer after one stream window. Data buffered before registration counts as received and is consumed like any other. Without the option the stream keeps its current mode.

-spec start_server(Name, Port, Opts) -> {ok, pid()} | {error, term()}
                      when Name :: atom(), Port :: inet:port_number(), Opts :: server_opts().

Start an HTTP/3 server.

The server listens on the given port and accepts HTTP/3 connections. Each incoming request triggers the handler with request details.

The handler can be:

• A function: fun(Conn, StreamId, Method, Path, Headers) -> ok
• A module implementing handle_request/5

Example:

  {ok, _} = quic_h3:start_server(my_server, 4433, #{
       cert => CertDer,
       key => KeyTerm,
       handler => fun(Conn, StreamId, <<"GET">>, Path, _) ->
           Body = <<"Hello from ", Path/binary>>,
           quic_h3:send_response(Conn, StreamId, 200, []),
           quic_h3:send_data(Conn, StreamId, Body, true)
       end
   }).

Receiving datagrams / stream-type events: when h3_datagram_enabled or stream_type_handler is used, owner-addressed messages are emitted per connection. Supply a durable receiver by returning #{owner => Pid} from the per-connection connection_handler callback. Without an explicit owner those messages route to the listener process, where they are discarded.

-spec stop_server(atom()) -> ok | {error, term()}.

Stop an HTTP/3 server.

-spec unset_stream_handler(conn(), stream_id()) -> ok.

Unregister a stream handler.

Future data will be sent to the connection owner.

-spec wait_connected(conn(), timeout()) -> ok | {error, timeout | term()}.

Wait for H3 connection to be ready.

Blocks until the connection is established and SETTINGS exchanged, until the QUIC connection fails (the failure reason is returned, e.g. {certificate_invalid, _}), or until the timeout expires.