h2_connection (h2 v0.6.0)

View Source

HTTP/2 Connection State Machine (RFC 7540)

This module implements the HTTP/2 connection protocol using gen_statem. It handles both client and server modes, managing the connection preface, settings exchange, stream lifecycle, flow control, and frame dispatch.

States: - preface: Exchanging connection preface - settings: Exchanging SETTINGS frames - connected: Ready for requests/responses - goaway_sent: Graceful shutdown initiated by us - goaway_received: Peer initiated shutdown - closing: Connection closing

Summary

Functions

activate(Conn)

Activate the socket after ownership transfer. Must be called after transferring socket ownership to this process. Synchronous so the caller knows the preface + SETTINGS have been sent and the socket has been set to active mode before it proceeds.

callback_mode()
cancel_stream(Conn, StreamId)

Cancel a stream.

cancel_stream(Conn, StreamId, ErrorCode)

Cancel a stream with a specific error code.

close(Conn)

Close the connection.

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

Transfer ownership of the connection.

get_peer_settings(Conn)

Get peer settings.

get_settings(Conn)

Get local settings.

goaway_received(EventType, OldState, State)
goaway_sent(EventType, OldState, State)
init(_)
preface(EventType, OldState, State)
send_data(Conn, StreamId, Data)

Send data on a stream.

send_data(Conn, StreamId, Data, EndStream)

Send data on a stream with end_stream flag.

send_goaway(Conn)

Send GOAWAY frame.

send_goaway(Conn, ErrorCode)

Send GOAWAY frame with error code.

send_request(Conn, Method, Path, Headers)

Send a request (client mode).

send_request(Conn, Method, Path, Headers, EndStream)

Send a request with EndStream flag (client mode).

send_request_headers(Conn, Headers, EndStream)

Send a request with a pre-built header list (including pseudo-headers).

send_response(Conn, StreamId, Status, Headers)

Send a response (server mode).

send_trailers(Conn, StreamId, Trailers)

Send trailers on a stream.

set_stream_handler(Conn, StreamId, Pid)

Register a pid to receive body data for StreamId. By default any DATA frames that arrived before the handler was registered are replayed to the handler pid as {h2, Conn, {data, StreamId, Data, Fin}} messages, and the call returns ok. Pass #{drain_buffer => true} to receive the raw buffer in the reply ({ok, [{Data, Fin}, ...]}) and forward it manually. Matches quic_h3:set_stream_handler/3,4.

set_stream_handler(Conn, StreamId, Pid, Opts)
settings(EventType, OldState, State)
start_link(_, Socket, Opts)

Start a connection as a client.

start_link(Mode, Socket, Owner, Opts)

Start a connection with explicit owner.

terminate(Reason, StateName, State)
unset_stream_handler(Conn, StreamId)
wait_connected(Conn)

Wait for the connection to reach connected state.

wait_connected(Conn, Timeout)

Wait for the connection to reach connected state with timeout.

Functions

activate(Conn)

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

Activate the socket after ownership transfer. Must be called after transferring socket ownership to this process. Synchronous so the caller knows the preface + SETTINGS have been sent and the socket has been set to active mode before it proceeds.

callback_mode()

cancel_stream(Conn, StreamId)

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

Cancel a stream.

cancel_stream(Conn, StreamId, ErrorCode)

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

Cancel a stream with a specific error code.

close(Conn)

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

Close the connection.

closing(EventType, OldState, State)

code_change(OldVsn, StateName, State, Extra)

connected(EventType, OldState, State)

controlling_process(Conn, NewOwner)

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

Transfer ownership of the connection.

get_peer_settings(Conn)

-spec get_peer_settings(pid()) -> h2_settings:settings().

Get peer settings.

get_settings(Conn)

-spec get_settings(pid()) -> h2_settings:settings().

Get local settings.

goaway_received(EventType, OldState, State)

goaway_sent(EventType, OldState, State)

init(_)

preface(EventType, OldState, State)

send_data(Conn, StreamId, Data)

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

Send data on a stream.

send_data(Conn, StreamId, Data, EndStream)

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

Send data on a stream with end_stream flag.

send_goaway(Conn)

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

Send GOAWAY frame.

send_goaway(Conn, ErrorCode)

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

Send GOAWAY frame with error code.

send_request(Conn, Method, Path, Headers)

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

Send a request (client mode).

send_request(Conn, Method, Path, Headers, EndStream)

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

Send a request with EndStream flag (client mode).

send_request_headers(Conn, Headers, EndStream)

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

Send a request with a pre-built header list (including pseudo-headers).

send_response(Conn, StreamId, Status, Headers)

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

Send a response (server mode).

send_trailers(Conn, StreamId, Trailers)

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

Send trailers on a stream.

set_stream_handler(Conn, StreamId, Pid)

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

Register a pid to receive body data for StreamId. By default any DATA frames that arrived before the handler was registered are replayed to the handler pid as {h2, Conn, {data, StreamId, Data, Fin}} messages, and the call returns ok. Pass #{drain_buffer => true} to receive the raw buffer in the reply ({ok, [{Data, Fin}, ...]}) and forward it manually. Matches quic_h3:set_stream_handler/3,4.

set_stream_handler(Conn, StreamId, Pid, Opts)

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

settings(EventType, OldState, State)

start_link(_, Socket, Opts)

-spec start_link(client, gen_tcp:socket() | ssl:sslsocket(), map()) -> {ok, pid()} | {error, term()}.

Start a connection as a client.

start_link(Mode, Socket, Owner, Opts)

-spec start_link(client | server, gen_tcp:socket() | ssl:sslsocket(), pid(), map()) ->
                    {ok, pid()} | {error, term()}.

Start a connection with explicit owner.

terminate(Reason, StateName, State)

unset_stream_handler(Conn, StreamId)

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

wait_connected(Conn)

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

Wait for the connection to reach connected state.

wait_connected(Conn, Timeout)

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

Wait for the connection to reach connected state with timeout.