draft-ietf-webtrans-http3-15 SS4: the WebTransport session state machine, independent of any specific transport wiring. More...

#include "common/bytes/span/span.h"
#include "common/platform/sys/syscall.h"

Data Structures
struct	wired_wt_buffered_stream
	One buffered pre-establishment stream: just its id, since the stream's own reassembly state lives in the transport layer (e.g. More...
struct	wired_wt_buffered_datagram
	One buffered pre-establishment datagram, copied (not viewed) since the caller's span may not outlive the call that offered it. More...
struct	wired_wt_session
	A WebTransport session. More...

Macros
#define	WIRED_WT_MAX_BUFFERED_STREAMS 4
	How many streams/datagrams that arrive before establishment this session buffers, each independently.
#define	WIRED_WT_MAX_BUFFERED_DATAGRAMS 4
	How many pre-establishment datagrams this session buffers.
#define	WIRED_WT_BUFFERED_DATAGRAM_CAP 256
	Fixed capacity for one buffered pre-establishment datagram's payload.

Enumerations
enum	wired_wt_state { WIRED_WT_UNESTABLISHED , WIRED_WT_ESTABLISHED , WIRED_WT_DRAINING , WIRED_WT_CLOSED }
	Session lifecycle state (draft-ietf-webtrans-http3-15 SS4). More...

Functions
void	wired_wt_session_init (wired_wt_session *s, u64 connect_stream_id)
	Reset s to WIRED_WT_UNESTABLISHED, empty of any buffered stream/datagram, identified by connect_stream_id.
int	wired_wt_session_establish (wired_wt_session *s)
	unestablished -> established: the server has sent its 2xx response (draft-ietf-webtrans-http3-15 SS4.2 – establishment from the server's own perspective happens at send, not at acknowledgement).
int	wired_wt_session_drain (wired_wt_session *s)
	established -> draining: a WT_DRAIN_SESSION capsule was sent/received.
int	wired_wt_session_close (wired_wt_session *s)
	established/draining -> closed: the CONNECT stream closed (FIN or RESET, either direction) or a WT_CLOSE_SESSION capsule was sent/received.
int	wired_wt_session_offer_stream (wired_wt_session *s, u64 stream_id)
	Offer a stream to the session: buffers it if unestablished (subject to WIRED_WT_MAX_BUFFERED_STREAMS), associates it immediately if established or draining.
int	wired_wt_session_offer_datagram (wired_wt_session *s, quic_span data)
	Offer a datagram to the session: buffers a copy of it if unestablished (subject to WIRED_WT_MAX_BUFFERED_DATAGRAMS and WIRED_WT_BUFFERED_DATAGRAM_CAP), or accepts it directly if established or draining.
int	wired_wt_session_set_max_streams (wired_wt_session *s, int bidi, u64 max_streams)
	Record a WT_MAX_STREAMS value just received from the peer (draft-ietf-webtrans-http3-15 SS5.3).
int	wired_wt_session_stream_open_allowed (const wired_wt_session *s, int bidi)
	1 iff opening one more stream of the given direction stays within the peer's most recently advertised WT_MAX_STREAMS limit (draft-ietf-webtrans-http3-15 SS5.3).
void	wired_wt_session_note_stream_opened (wired_wt_session *s, int bidi)
	Record that one more stream of the given direction was opened, advancing the session's cumulative opened-stream count (SS5.3: the count includes streams that have since closed).
int	wired_wt_session_set_max_data (wired_wt_session *s, u64 max_data)
	Record a WT_MAX_DATA value just received from the peer (draft-ietf-webtrans-http3-15 SS5.4).
int	wired_wt_session_data_send_allowed (const wired_wt_session *s, usz len)
	1 iff sending len more Stream Body bytes stays within the peer's most recently advertised WT_MAX_DATA limit (SS5.4).
void	wired_wt_session_note_data_sent (wired_wt_session *s, usz len)
	Record that len more Stream Body bytes were sent, advancing the session's cumulative sent-data count.

Detailed Description

draft-ietf-webtrans-http3-15 SS4: the WebTransport session state machine, independent of any specific transport wiring.

A session moves through unestablished -> established -> draining -> closed, buffering streams and datagrams that arrive for it before establishment (SS4.7) and associating them directly once established or draining.

closed is absorbing: once reached, establish/drain/close are all no-ops. draining is advisory only (SS4.2 WT_DRAIN_SESSION): it does not terminate the session, and a draining session can still close via either of the two closing triggers (the CONNECT stream ending, or WT_CLOSE_SESSION).

SS5.3/SS5.4 session-level flow control: a session also tracks the cumulative stream-open counts and sent-data byte count against the limits most recently advertised by the peer via WT_MAX_STREAMS/WT_MAX_DATA capsules (see app/webtransport/capsule/wtcapsule/wtcapsule.h for the wire codec). A limit of 0 means "no WT_MAX_STREAMS/WT_MAX_DATA capsule has been received yet from the peer" – since flow control is opt-in (SS5.1), a limit of 0 does not itself forbid opening a stream or sending data; the caller decides whether flow control is enabled for this session before consulting these checks.

Macro Definition Documentation

◆ WIRED_WT_BUFFERED_DATAGRAM_CAP

#define WIRED_WT_BUFFERED_DATAGRAM_CAP 256

Fixed capacity for one buffered pre-establishment datagram's payload.

ponytail: bytes past this are truncated (not dropped) rather than growing the buffer; raise this if a real WT datagram workload needs more before establishment completes.

◆ WIRED_WT_MAX_BUFFERED_DATAGRAMS

#define WIRED_WT_MAX_BUFFERED_DATAGRAMS 4

How many pre-establishment datagrams this session buffers.

Same rationale as WIRED_WT_MAX_BUFFERED_STREAMS: room for the short race window, not a general-purpose queue.

◆ WIRED_WT_MAX_BUFFERED_STREAMS

#define WIRED_WT_MAX_BUFFERED_STREAMS 4

How many streams/datagrams that arrive before establishment this session buffers, each independently.

Matches WIRED_SRVLOOP_MAX_STREAMS (app/http3/server/srvloop/srvloop.h): this is not meant to support hundreds of concurrent pre-establishment arrivals, just enough room for the short race between a client opening streams and the server's own 2xx.

Enumeration Type Documentation

◆ wired_wt_state

enum wired_wt_state

Session lifecycle state (draft-ietf-webtrans-http3-15 SS4).

Enumerator
WIRED_WT_UNESTABLISHED	CONNECT seen, 2xx not yet sent.
WIRED_WT_ESTABLISHED	server has sent its 2xx response
WIRED_WT_DRAINING	WT_DRAIN_SESSION sent/received (advisory).
WIRED_WT_CLOSED	terminal: CONNECT stream closed, or WT_CLOSE_SESSION sent/received

Function Documentation

◆ wired_wt_session_close()

int wired_wt_session_close ( wired_wt_session * s )

established/draining -> closed: the CONNECT stream closed (FIN or RESET, either direction) or a WT_CLOSE_SESSION capsule was sent/received.

Per the verified design these two triggers are treated as one atomic transition to closed; callers should invoke this at the point either is processed.

Parameters

s	the session to transition

Returns: 1 if the transition applied, 0 if s was already closed (no-op)

◆ wired_wt_session_data_send_allowed()

int wired_wt_session_data_send_allowed	(	const wired_wt_session *	s,
		usz	len )

1 iff sending len more Stream Body bytes stays within the peer's most recently advertised WT_MAX_DATA limit (SS5.4).

A limit of 0 (none received yet) always allows sending, for the same opt-in-flow-control reason as wired_wt_session_stream_open_allowed. On 0, the caller MUST close the session with WT_FLOW_CONTROL_ERROR rather than send the data.

Parameters

s	the session to check
len	additional Stream Body bytes about to be sent

Returns: 1 if allowed, 0 if it would exceed the limit

◆ wired_wt_session_drain()

int wired_wt_session_drain ( wired_wt_session * s )

established -> draining: a WT_DRAIN_SESSION capsule was sent/received.

Advisory only; does not terminate the session.

Parameters

s	the session to transition

Returns: 1 if the transition applied, 0 if s was not in established

◆ wired_wt_session_establish()

int wired_wt_session_establish ( wired_wt_session * s )

unestablished -> established: the server has sent its 2xx response (draft-ietf-webtrans-http3-15 SS4.2 – establishment from the server's own perspective happens at send, not at acknowledgement).

Parameters

s	the session to transition

Returns: 1 if the transition applied, 0 if s was not in unestablished (no-op, including the closed absorbing state)

◆ wired_wt_session_init()

void wired_wt_session_init	(	wired_wt_session *	s,
		u64	connect_stream_id )

Reset s to WIRED_WT_UNESTABLISHED, empty of any buffered stream/datagram, identified by connect_stream_id.

Parameters

s	the session to initialize
connect_stream_id	the CONNECT stream's id (this session's identity)

◆ wired_wt_session_note_data_sent()

void wired_wt_session_note_data_sent	(	wired_wt_session *	s,
		usz	len )

Record that len more Stream Body bytes were sent, advancing the session's cumulative sent-data count.

Does not itself check wired_wt_session_data_send_allowed – callers check first, then note.

Parameters

s	the session to update
len	additional Stream Body bytes just sent

◆ wired_wt_session_note_stream_opened()

void wired_wt_session_note_stream_opened	(	wired_wt_session *	s,
		int	bidi )

Record that one more stream of the given direction was opened, advancing the session's cumulative opened-stream count (SS5.3: the count includes streams that have since closed).

Does not itself check wired_wt_session_stream_open_allowed – callers check first, then note.

Parameters

s	the session to update
bidi	nonzero for a bidirectional stream, 0 for uni

◆ wired_wt_session_offer_datagram()

int wired_wt_session_offer_datagram	(	wired_wt_session *	s,
		quic_span	data )

Offer a datagram to the session: buffers a copy of it if unestablished (subject to WIRED_WT_MAX_BUFFERED_DATAGRAMS and WIRED_WT_BUFFERED_DATAGRAM_CAP), or accepts it directly if established or draining.

Unlike wired_wt_session_offer_stream, a 0 return here is not an error the caller must act on: it means the datagram was silently dropped per the drop-newest policy (buffer full; existing buffered datagrams are unchanged) – draft-ietf-webtrans-http3-15 leaves this implementation-defined and this is the chosen policy.

Parameters

s	the session to offer the datagram to
data	the datagram payload

Returns: 1 if buffered or accepted, 0 if dropped

◆ wired_wt_session_offer_stream()

int wired_wt_session_offer_stream	(	wired_wt_session *	s,
		u64	stream_id )

Offer a stream to the session: buffers it if unestablished (subject to WIRED_WT_MAX_BUFFERED_STREAMS), associates it immediately if established or draining.

Does not perform any wire-level action itself – on a 0 return the caller must reset the stream with WT_BUFFERED_STREAM_REJECTED (0x3994bd84) themselves.

Parameters

s	the session to offer the stream to
stream_id	the arriving stream's id

Returns: 1 if buffered or associated, 0 if rejected (buffer full)

◆ wired_wt_session_set_max_data()

int wired_wt_session_set_max_data	(	wired_wt_session *	s,
		u64	max_data )

Record a WT_MAX_DATA value just received from the peer (draft-ietf-webtrans-http3-15 SS5.4).

Same in-order/cumulative/monotonic contract as wired_wt_session_set_max_streams.

Parameters

s	the session to update
max_data	the newly received cumulative session data limit

Returns: 1 if applied, 0 if max_data < the currently stored limit (caller must close the session with WT_FLOW_CONTROL_ERROR)

◆ wired_wt_session_set_max_streams()

int wired_wt_session_set_max_streams	(	wired_wt_session *	s,
		int	bidi,
		u64	max_streams )

Record a WT_MAX_STREAMS value just received from the peer (draft-ietf-webtrans-http3-15 SS5.3).

WT_MAX_STREAMS capsules are delivered in order on the session's connect stream, and Maximum Streams is cumulative, so a value lower than one already recorded is a protocol violation the caller MUST close the session for (WT_FLOW_CONTROL_ERROR) – this function detects that case and leaves the stored limit unchanged rather than applying it.

Parameters

s	the session to update
bidi	nonzero for the bidirectional limit, 0 for uni
max_streams	the newly received cumulative stream limit

Returns: 1 if applied, 0 if max_streams < the currently stored limit (caller must close the session with WT_FLOW_CONTROL_ERROR)

◆ wired_wt_session_stream_open_allowed()

int wired_wt_session_stream_open_allowed	(	const wired_wt_session *	s,
		int	bidi )

1 iff opening one more stream of the given direction stays within the peer's most recently advertised WT_MAX_STREAMS limit (draft-ietf-webtrans-http3-15 SS5.3).

A limit of 0 (none received yet) always allows opening – flow control is opt-in (SS5.1); the caller decides whether to consult this at all for a session that never enabled flow control. On 0, the caller MUST close the session with WT_FLOW_CONTROL_ERROR rather than open the stream.

Parameters

s	the session to check
bidi	nonzero to check the bidirectional limit, 0 for uni

Returns: 1 if allowed, 0 if it would exceed the limit

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ WIRED_WT_BUFFERED_DATAGRAM_CAP

◆ WIRED_WT_MAX_BUFFERED_DATAGRAMS

◆ WIRED_WT_MAX_BUFFERED_STREAMS

Enumeration Type Documentation

◆ wired_wt_state

Function Documentation

◆ wired_wt_session_close()

◆ wired_wt_session_data_send_allowed()

◆ wired_wt_session_drain()

◆ wired_wt_session_establish()

◆ wired_wt_session_init()

◆ wired_wt_session_note_data_sent()

◆ wired_wt_session_note_stream_opened()

◆ wired_wt_session_offer_datagram()

◆ wired_wt_session_offer_stream()

◆ wired_wt_session_set_max_data()

◆ wired_wt_session_set_max_streams()

◆ wired_wt_session_stream_open_allowed()