quic_h3_connection (quic v1.3.1)

View Source

HTTP/3 connection management.

This module implements the HTTP/3 connection layer on top of QUIC. It manages critical unidirectional streams (control, QPACK encoder/decoder), request/response streams, and the HTTP/3 protocol state machine.

Summary

Types

error_code/0
role/0
stream_id/0

Functions

awaiting_quic(EventType, OldState, State)
callback_mode()
cancel_push(Conn, PushId)

Cancel a push (client only). Sends CANCEL_PUSH to tell server we don't want this push.

cancel_stream(Conn, StreamId)

Cancel a stream.

cancel_stream(Conn, StreamId, ErrorCode)
close(Conn)

Close the connection.

closing(EventType, OldState, State)
code_change(OldVsn, StateName, State, Extra)
connected(EventType, OldState, State)
get_peer_settings(Conn)

Get peer settings.

get_quic_conn(Conn)

Get the underlying QUIC connection pid.

get_settings(Conn)

Get local settings.

goaway(Conn)

Initiate graceful shutdown.

goaway_received(EventType, OldState, State)
goaway_sent(EventType, OldState, State)
h3_connecting(EventType, OldState, State)
h3_datagrams_enabled(Conn)

Whether both sides negotiated RFC 9297 support.

init(_)
max_datagram_size(Conn, StreamId)

Max payload we can fit in one H3 DATAGRAM for this stream, given the peer's max_datagram_frame_size minus the quarter-stream-id prefix. Returns 0 if RFC 9297 isn't live.

open_bidi_stream(Conn, SignalType)

Open a client-initiated bidirectional stream outside the H3 request/response flow. When SignalType is a non-negative integer, the stream is pre-claimed so inbound data is delivered as stream_type_data owner messages. When undefined, behaves as a plain unclaimed stream.

push(Conn, RequestStreamId, Headers)

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.

request(Conn, Headers)

Send a request (client only). Returns the stream ID for tracking the response.

request(Conn, Headers, Opts)
send_data(Conn, StreamId, Data)

Send body data on a stream.

send_data(Conn, StreamId, Data, Fin)
send_datagram(Conn, StreamId, Data)

Send an HTTP Datagram (RFC 9297) associated with a request stream.

send_push_data(Conn, PushId, Data, Fin)

Send data on a push stream (server only).

send_push_response(Conn, PushId, Status, Headers)

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

send_response(Conn, StreamId, Status, Headers)

Send a response (server only).

send_trailers(Conn, StreamId, Trailers)

Send trailers on a stream.

set_max_push_id(Conn, MaxPushId)

Set the maximum push ID (client only). This enables server push up to the specified push ID.

set_stream_handler(Conn, StreamId, HandlerPid)

Register a handler process to receive stream data. The handler will receive {quic_h3, Conn, {data, StreamId, Data, Fin}} messages. Any data buffered before registration is returned.

set_stream_handler(Conn, StreamId, HandlerPid, Opts)

Register a handler with options. Options: - drain_buffer: If true (default), returns buffered data instead of sending as messages

start_link(QuicConn, Host, Port)

Start an HTTP/3 connection as a client.

start_link(QuicConn, Host, Port, Opts)

Start an HTTP/3 connection with options.

terminate(Reason, StateName, State)
test_discarded_uni_streams(State)
test_push_stream(PushId, State)
test_stream(StreamId, State)
unset_stream_handler(Conn, StreamId)

Unregister a stream handler. Future data will be sent to the connection owner.

Types

error_code/0

-type error_code() :: non_neg_integer().

role/0

-type role() :: client | server.

stream_id/0

-type stream_id() :: non_neg_integer().

Functions

awaiting_quic(EventType, OldState, State)

callback_mode()

cancel_push(Conn, PushId)

-spec cancel_push(pid(), non_neg_integer()) -> ok.

Cancel a push (client only). Sends CANCEL_PUSH to tell server we don't want this push.

cancel_stream(Conn, StreamId)

-spec cancel_stream(pid(), stream_id()) -> ok.

Cancel a stream.

cancel_stream(Conn, StreamId, ErrorCode)

-spec cancel_stream(pid(), stream_id(), error_code()) -> ok.

close(Conn)

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

Close the connection.

closing(EventType, OldState, State)

code_change(OldVsn, StateName, State, Extra)

connected(EventType, OldState, State)

get_peer_settings(Conn)

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

Get peer settings.

get_quic_conn(Conn)

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

Get the underlying QUIC connection pid.

get_settings(Conn)

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

Get local settings.

goaway(Conn)

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

Initiate graceful shutdown.

goaway_received(EventType, OldState, State)

goaway_sent(EventType, OldState, State)

h3_connecting(EventType, OldState, State)

h3_datagrams_enabled(Conn)

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

Whether both sides negotiated RFC 9297 support.

init(_)

max_datagram_size(Conn, StreamId)

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

Max payload we can fit in one H3 DATAGRAM for this stream, given the peer's max_datagram_frame_size minus the quarter-stream-id prefix. Returns 0 if RFC 9297 isn't live.

open_bidi_stream(Conn, SignalType)

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

Open a client-initiated bidirectional stream outside the H3 request/response flow. When SignalType is a non-negative integer, the stream is pre-claimed so inbound data is delivered as stream_type_data owner messages. When undefined, behaves as a plain unclaimed stream.

push(Conn, RequestStreamId, Headers)

-spec push(pid(), stream_id(), [{binary(), binary()}]) -> {ok, non_neg_integer()} | {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.

request(Conn, Headers)

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

Send a request (client only). Returns the stream ID for tracking the response.

request(Conn, Headers, Opts)

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

send_data(Conn, StreamId, Data)

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

Send body data on a stream.

send_data(Conn, StreamId, Data, Fin)

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

send_datagram(Conn, StreamId, Data)

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

Send an HTTP Datagram (RFC 9297) associated with a request stream.

send_push_data(Conn, PushId, Data, Fin)

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

Send data on a push stream (server only).

send_push_response(Conn, PushId, Status, Headers)

-spec send_push_response(pid(), non_neg_integer(), pos_integer(), [{binary(), binary()}]) ->
                            ok | {error, term()}.

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

send_response(Conn, StreamId, Status, Headers)

-spec send_response(pid(), stream_id(), pos_integer(), [{binary(), binary()}]) -> ok | {error, term()}.

Send a response (server only).

send_trailers(Conn, StreamId, Trailers)

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

Send trailers on a stream.

set_max_push_id(Conn, MaxPushId)

-spec set_max_push_id(pid(), non_neg_integer()) -> ok | {error, term()}.

Set the maximum push ID (client only). This enables server push up to the specified push ID.

set_stream_handler(Conn, StreamId, HandlerPid)

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

Register a handler process to receive stream data. The handler will receive {quic_h3, Conn, {data, StreamId, Data, Fin}} messages. Any data buffered before registration is returned.

See also: set_stream_handler/4.

set_stream_handler(Conn, StreamId, HandlerPid, Opts)

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

Register a handler with options. Options: - drain_buffer: If true (default), returns buffered data instead of sending as messages

start_link(QuicConn, Host, Port)

-spec start_link(pid(), binary(), pos_integer()) -> {ok, pid()} | {error, term()}.

Start an HTTP/3 connection as a client.

start_link(QuicConn, Host, Port, Opts)

-spec start_link(pid(), binary(), pos_integer(), map()) -> {ok, pid()} | {error, term()}.

Start an HTTP/3 connection with options.

terminate(Reason, StateName, State)

test_discarded_uni_streams(State)

test_push_stream(PushId, State)

test_stream(StreamId, State)

unset_stream_handler(Conn, StreamId)

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

Unregister a stream handler. Future data will be sent to the connection owner.