webtransport_session (webtransport v0.5.9)
View SourceWebTransport 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
Functions
Close the session immediately with the given error code and reason.
Gracefully close a stream by sending FIN.
Initiate a graceful drain: no new streams, existing ones finish.
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.
The session is established: the server sent its 2xx, or the client registered the session. Runs the actions the handler's init returned.
As established/1, with the peer SETTINGS in effect when the session was accepted (h2, http2-16 §4.3.1). They replace the ones read earlier.
Return a map of session metrics: stream count, flow control limits, bytes sent/received.
The connection received GOAWAY: no new streams (http3-17 §4.7).
Deliver a decoded capsule to the session (called by transport layers).
Deliver an inbound datagram payload to the session.
Notify the session that a stream was closed or reset by the peer.
Deliver inbound stream data to the session (called by transport layers).
Notify the session that a peer-initiated stream was opened.
Open a new locally-initiated stream of the given type.
Abruptly reset a stream with the given application error code.
Send data on a stream. Set Fin to true to half-close the local side.
Send an unreliable datagram on the session.
Start a session with default gen_statem options.
Start a session linked to the caller, with explicit gen_statem start options.
Ask the peer to stop sending on a stream with the given error code.
The QUIC connection can open a stream of this type again, after an open was refused with stream_limit (h3, sent by the router).
Types
Functions
-spec close(session(), non_neg_integer(), binary()) -> ok.
Close the session immediately with the given error code and reason.
-spec close_stream(session(), stream_ref()) -> ok | {error, term()}.
Gracefully close a stream by sending FIN.
-spec drain(session()) -> ok.
Initiate a graceful drain: no new streams, existing ones finish.
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.
-spec established(session()) -> ok.
The session is established: the server sent its 2xx, or the client registered the session. Runs the actions the handler's init returned.
As established/1, with the peer SETTINGS in effect when the session was accepted (h2, http2-16 §4.3.1). They replace the ones read earlier.
Return a map of session metrics: stream count, flow control limits, bytes sent/received.
-spec goaway(session(), non_neg_integer()) -> ok.
The connection received GOAWAY: no new streams (http3-17 §4.7).
Deliver a decoded capsule to the session (called by transport layers).
Deliver an inbound datagram payload to the session.
The receive buffer is bounded (overview-14 §4.2): when the session already has ?WT_DATAGRAM_QUEUE_MAX messages waiting, the datagram is dropped.
-spec handle_stream_closed(session(), stream_ref(), term()) -> ok.
Notify the session that a stream was closed or reset by the peer.
-spec handle_stream_data(session(), stream_ref(), binary(), boolean()) -> ok.
Deliver inbound stream data to the session (called by transport layers).
-spec handle_stream_opened(session(), stream_ref(), bidi | uni) -> ok.
Notify the session that a peer-initiated stream was opened.
-spec open_stream(session(), bidi | uni) -> {ok, stream_ref()} | {error, term()}.
Open a new locally-initiated stream of the given type.
-spec reset_stream(session(), stream_ref(), non_neg_integer()) -> ok | {error, term()}.
Abruptly reset a stream with the given application error code.
-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 an unreliable datagram on the session.
Start a session with default gen_statem options.
Start a session linked to the caller, with explicit gen_statem start options.
-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.
-spec transport_streams_available(session(), bidi | uni) -> ok.
The QUIC connection can open a stream of this type again, after an open was refused with stream_limit (h3, sent by the router).