webtransport_session (webtransport v0.3.0)

WebTransport session state machine.

This module implements a gen_statem that manages a WebTransport session's lifecycle, including stream management, flow control, and handler callbacks.

The session supports both HTTP/2 and HTTP/3 transports, using the appropriate transport module for capsule/stream handling.

Summary

Types

request/0

session/0

stream_ref/0

Functions

callback_mode()

close(Session, ErrorCode, Reason)

Close the session immediately with the given error code and reason.

close_stream(Session, StreamId)

Gracefully close a stream by sending FIN.

connecting(_, _, StateData)

drain(Session)

Initiate a graceful drain: no new streams, existing ones finish.

draining(_, _, StateData)

early_data_accepted(Session)

Report whether the underlying connection negotiated 0-RTT early data. Returns true/false/unknown for h3 (per RFC 9001 §4.6), or not_supported for h2 which has no QUIC 0-RTT.

get_info(Session)

Return a map of session metrics: stream count, flow control limits, bytes sent/received.

handle_capsule(Session, Capsule)

Deliver a decoded capsule to the session (called by transport layers).

handle_datagram_data(Session, Data)

Deliver an inbound datagram payload to the session.

handle_stream_closed(Session, StreamId, Reason)

Notify the session that a stream was closed or reset by the peer.

handle_stream_data(Session, StreamId, Data, Fin)

Deliver inbound stream data to the session (called by transport layers).

handle_stream_opened(Session, StreamId, Type)

Notify the session that a peer-initiated stream was opened.

init(_)

open(_, Msg, Data)

open_stream(Session, Type)

Open a new locally-initiated stream of the given type.

reset_stream(Session, StreamId, ErrorCode)

Abruptly reset a stream with the given application error code.

send(Session, StreamId, Data, Fin)

Send data on a stream. Set Fin to true to half-close the local side.

send_datagram(Session, Data)

Send an unreliable datagram on the session.

start_link(Transport, TransportState, Handler, Opts)

Start a session with default gen_statem options.

start_link(Transport, TransportState, Handler, Opts, StartOpts)

Start a session linked to the caller, with explicit gen_statem start options.

stop_sending(Session, StreamId, ErrorCode)

Ask the peer to stop sending on a stream with the given error code.

terminate(Reason, State, Data)

Types

request/0

-type request() :: #{path := binary(), authority := binary(), headers => [{binary(), binary()}]}.

session/0

-type session() :: pid().

stream_ref/0

-type stream_ref() :: non_neg_integer().

Functions

callback_mode()

close(Session, ErrorCode, Reason)

-spec close(session(), non_neg_integer(), binary()) -> ok.

Close the session immediately with the given error code and reason.

close_stream(Session, StreamId)

-spec close_stream(session(), stream_ref()) -> ok | {error, term()}.

Gracefully close a stream by sending FIN.

connecting(_, _, StateData)

drain(Session)

-spec drain(session()) -> ok.

Initiate a graceful drain: no new streams, existing ones finish.

draining(_, _, StateData)

early_data_accepted(Session)

-spec early_data_accepted(session()) -> boolean() | unknown | not_supported.

Report whether the underlying connection negotiated 0-RTT early data. Returns true/false/unknown for h3 (per RFC 9001 §4.6), or not_supported for h2 which has no QUIC 0-RTT.

get_info(Session)

-spec get_info(session()) -> {ok, map()} | {error, term()}.

Return a map of session metrics: stream count, flow control limits, bytes sent/received.

handle_capsule(Session, Capsule)

-spec handle_capsule(session(), term()) -> ok.

Deliver a decoded capsule to the session (called by transport layers).

handle_datagram_data(Session, Data)

-spec handle_datagram_data(session(), binary()) -> ok.

Deliver an inbound datagram payload to the session.

handle_stream_closed(Session, StreamId, Reason)

-spec handle_stream_closed(session(), stream_ref(), term()) -> ok.

Notify the session that a stream was closed or reset by the peer.

handle_stream_data(Session, StreamId, Data, Fin)

-spec handle_stream_data(session(), stream_ref(), binary(), boolean()) -> ok.

Deliver inbound stream data to the session (called by transport layers).

handle_stream_opened(Session, StreamId, Type)

-spec handle_stream_opened(session(), stream_ref(), bidi | uni) -> ok.

Notify the session that a peer-initiated stream was opened.

init(_)

open(_, Msg, Data)

open_stream(Session, Type)

-spec open_stream(session(), bidi | uni) -> {ok, stream_ref()} | {error, term()}.

Open a new locally-initiated stream of the given type.

reset_stream(Session, StreamId, ErrorCode)

-spec reset_stream(session(), stream_ref(), non_neg_integer()) -> ok | {error, term()}.

Abruptly reset a stream with the given application error code.

send(Session, StreamId, Data, Fin)

-spec send(session(), stream_ref(), iodata(), boolean()) -> ok | {error, term()}.

Send data on a stream. Set Fin to true to half-close the local side.

send_datagram(Session, Data)

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

Send an unreliable datagram on the session.

start_link(Transport, TransportState, Handler, Opts)

-spec start_link(h2 | h3, term(), module(), map()) -> {ok, pid()} | {error, term()}.

Start a session with default gen_statem options.

start_link(Transport, TransportState, Handler, Opts, StartOpts)

-spec start_link(h2 | h3, term(), module(), map(), list()) -> {ok, pid()} | {error, term()}.

Start a session linked to the caller, with explicit gen_statem start options.

stop_sending(Session, StreamId, ErrorCode)

-spec stop_sending(session(), stream_ref(), non_neg_integer()) -> ok | {error, term()}.

Ask the peer to stop sending on a stream with the given error code.

terminate(Reason, State, Data)