draft-ietf-webtrans-http3-15 SS4.2/SS5.6: the WebTransport-specific capsule types layered on top of the generic RFC 9297 Capsule Protocol codec (app/http3/core/capsule/capsule.h). More...

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

Macros
#define	QUIC_WTCAPSULE_CLOSE_MESSAGE_MAX 1024
	Maximum WT_CLOSE_SESSION application error message length, in bytes (draft-ietf-webtrans-http3-15 SS4.2).

Functions
int	quic_wtcapsule_encode_close (quic_obuf *out, u32 app_error_code, quic_span message)
	Encode a WT_CLOSE_SESSION capsule (type 0x2843) into out.
int	quic_wtcapsule_encode_drain (quic_obuf *out)
	Encode a WT_DRAIN_SESSION capsule (type 0x78ae, empty body) into out.
int	quic_wtcapsule_decode_close (quic_span data, usz at, u32 app_error_code, quic_span *message)
	Attempt to decode the capsule at *at within data as a WT_CLOSE_SESSION.
int	quic_wtcapsule_decode_drain (quic_span data, usz *at)
	Attempt to decode the capsule at *at within data as a WT_DRAIN_SESSION.
int	quic_wtcapsule_encode_max_streams (quic_obuf *out, int bidi, u64 max_streams)
	Encode a WT_MAX_STREAMS capsule (draft-ietf-webtrans-http3-15 SS5.6.2) into out: type 0x190B4D3F for bidi, 0x190B4D40 for uni, body a single varint (Maximum Streams).
int	quic_wtcapsule_decode_max_streams (quic_span data, usz at, int bidi, u64 max_streams)
	Attempt to decode the capsule at *at within data as a WT_MAX_STREAMS capsule of the given direction.
int	quic_wtcapsule_encode_streams_blocked (quic_obuf *out, int bidi, u64 max_streams)
	Encode a WT_STREAMS_BLOCKED capsule (SS5.6.3) into out: type 0x190B4D43 for bidi, 0x190B4D44 for uni, body a single varint (Maximum Streams).
int	quic_wtcapsule_decode_streams_blocked (quic_span data, usz at, int bidi, u64 max_streams)
	Attempt to decode the capsule at *at within data as a WT_STREAMS_BLOCKED capsule of the given direction.
int	quic_wtcapsule_encode_max_data (quic_obuf *out, u64 max_data)
	Encode a WT_MAX_DATA capsule (SS5.6.4, type 0x190B4D3D) into out: body a single varint (Maximum Data, in bytes).
int	quic_wtcapsule_decode_max_data (quic_span data, usz at, u64 max_data)
	Attempt to decode the capsule at *at within data as a WT_MAX_DATA capsule.
int	quic_wtcapsule_encode_data_blocked (quic_obuf *out, u64 max_data)
	Encode a WT_DATA_BLOCKED capsule (SS5.6.5, type 0x190B4D41) into out: body a single varint (Maximum Data, the limit in effect when blocking occurred).
int	quic_wtcapsule_decode_data_blocked (quic_span data, usz at, u64 max_data)
	Attempt to decode the capsule at *at within data as a WT_DATA_BLOCKED capsule.

Detailed Description

draft-ietf-webtrans-http3-15 SS4.2/SS5.6: the WebTransport-specific capsule types layered on top of the generic RFC 9297 Capsule Protocol codec (app/http3/core/capsule/capsule.h).

This is the wire-format layer only – it does not call into the session state machine (session/ session.h) itself; a caller decodes a capsule here and then drives the session transition (e.g. wired_wt_session_drain) as a separate step.

WT_CLOSE_SESSION (type 0x2843): Application Error Code (32) Application Error Message (..) – UTF-8, MUST NOT exceed 1024 bytes

WT_DRAIN_SESSION (type 0x78ae): empty body (Length=0), purely a signal.

Session-level flow-control capsules (SS5.6), each body a single varint: WT_MAX_STREAMS (0x190B4D3F bidi, 0x190B4D40 uni): Maximum Streams WT_STREAMS_BLOCKED (0x190B4D43 bidi, 0x190B4D44 uni): Maximum Streams WT_MAX_DATA (0x190B4D3D): Maximum Data WT_DATA_BLOCKED (0x190B4D41): Maximum Data

Per-stream flow-control capsules (e.g. a hypothetical WT_MAX_STREAM_DATA / WT_STREAM_DATA_BLOCKED) are intentionally NOT declared here and never will be: the HTTP/3 WebTransport mapping (this draft) does not define them at all – they exist only in the sibling HTTP/2-based WebTransport mapping, which this SDK does not implement. Per-stream flow control on HTTP/3 is instead covered natively by QUIC's own MAX_STREAM_DATA frame at the transport layer (already implemented outside this file). Do not confuse this with the SESSION-level WT_MAX_DATA/WT_MAX_STREAMS family declared above, which the draft does define and this file implements.

Function Documentation

◆ quic_wtcapsule_decode_close()

int quic_wtcapsule_decode_close	(	quic_span	data,
		usz *	at,
		u32 *	app_error_code,
		quic_span *	message )

Attempt to decode the capsule at *at within data as a WT_CLOSE_SESSION.

"Wrong type, don't consume" contract: if a complete capsule is present at at but its type is not 0x2843, this returns 0 and *at, *app_error_code, *message are all left UNCHANGED – so a caller can go on to try a different decode_ function (e.g. quic_wtcapsule_decode_drain) at the same, still-unconsumed offset. This differs from quic_capsule_decode itself, which reports "no complete capsule yet" the same way it reports "wrong type" would be reported here: both leave *at untouched, so the two failure causes are indistinguishable to the caller by design (either way, nothing was consumed).

Also returns 0, *at unchanged, if the capsule IS type 0x2843 but malformed: its value is too short to hold the 32-bit error code, or its message exceeds QUIC_WTCAPSULE_CLOSE_MESSAGE_MAX bytes.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data
app_error_code	set to the decoded error code on success
message	set to a view of the error message on success

Returns: 1 on success, 0 otherwise (see above)

◆ quic_wtcapsule_decode_data_blocked()

int quic_wtcapsule_decode_data_blocked	(	quic_span	data,
		usz *	at,
		u64 *	max_data )

Attempt to decode the capsule at *at within data as a WT_DATA_BLOCKED capsule.

Same contract as quic_wtcapsule_decode_max_data.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data
max_data	set to the decoded Maximum Data value on success

Returns: 1 on success, 0 otherwise

◆ quic_wtcapsule_decode_drain()

int quic_wtcapsule_decode_drain	(	quic_span	data,
		usz *	at )

Attempt to decode the capsule at *at within data as a WT_DRAIN_SESSION.

Same "wrong type / incomplete, don't consume" contract as quic_wtcapsule_decode_close – *at only advances on a confirmed WT_DRAIN_SESSION capsule.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data

Returns: 1 if a WT_DRAIN_SESSION capsule was present and consumed, 0 otherwise

◆ quic_wtcapsule_decode_max_data()

int quic_wtcapsule_decode_max_data	(	quic_span	data,
		usz *	at,
		u64 *	max_data )

Attempt to decode the capsule at *at within data as a WT_MAX_DATA capsule.

Same "wrong type/incomplete, don't consume" contract as quic_wtcapsule_decode_close.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data
max_data	set to the decoded Maximum Data value on success

Returns: 1 on success, 0 otherwise

◆ quic_wtcapsule_decode_max_streams()

int quic_wtcapsule_decode_max_streams	(	quic_span	data,
		usz *	at,
		int	bidi,
		u64 *	max_streams )

Attempt to decode the capsule at *at within data as a WT_MAX_STREAMS capsule of the given direction.

Same "wrong type/incomplete, don't consume" contract as quic_wtcapsule_decode_close.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data
bidi	nonzero to match the bidi type, 0 to match uni
max_streams	set to the decoded Maximum Streams value on success

Returns: 1 on success, 0 otherwise

◆ quic_wtcapsule_decode_streams_blocked()

int quic_wtcapsule_decode_streams_blocked	(	quic_span	data,
		usz *	at,
		int	bidi,
		u64 *	max_streams )

Attempt to decode the capsule at *at within data as a WT_STREAMS_BLOCKED capsule of the given direction.

Same contract as quic_wtcapsule_decode_max_streams.

Parameters

data	the buffer to decode from
at	in/out cursor offset within data
bidi	nonzero to match the bidi type, 0 to match uni
max_streams	set to the decoded Maximum Streams value on success

Returns: 1 on success, 0 otherwise

◆ quic_wtcapsule_encode_close()

int quic_wtcapsule_encode_close	(	quic_obuf *	out,
		u32	app_error_code,
		quic_span	message )

Encode a WT_CLOSE_SESSION capsule (type 0x2843) into out.

Rejects (returns 0, leaves out unmodified) if message.n exceeds QUIC_WTCAPSULE_CLOSE_MESSAGE_MAX – this is a WebTransport wire-format constraint, checked independently of whether out happens to have room.

Parameters

out	destination buffer view
app_error_code	32-bit application error code
message	UTF-8 error message, message.n <= 1024 (may be empty)

Returns: 1 on success, 0 if message is too long or it doesn't fit in out

◆ quic_wtcapsule_encode_data_blocked()

int quic_wtcapsule_encode_data_blocked	(	quic_obuf *	out,
		u64	max_data )

Encode a WT_DATA_BLOCKED capsule (SS5.6.5, type 0x190B4D41) into out: body a single varint (Maximum Data, the limit in effect when blocking occurred).

Parameters

out	destination buffer view
max_data	the session-level data limit in effect when blocked

Returns: 1 on success, 0 if it doesn't fit in out or max_data is out of varint range

◆ quic_wtcapsule_encode_drain()

int quic_wtcapsule_encode_drain ( quic_obuf * out )

Encode a WT_DRAIN_SESSION capsule (type 0x78ae, empty body) into out.

Parameters

out	destination buffer view

Returns: 1 on success, 0 if it doesn't fit in out

◆ quic_wtcapsule_encode_max_data()

int quic_wtcapsule_encode_max_data	(	quic_obuf *	out,
		u64	max_data )

Encode a WT_MAX_DATA capsule (SS5.6.4, type 0x190B4D3D) into out: body a single varint (Maximum Data, in bytes).

Parameters

out	destination buffer view
max_data	cumulative session-level data limit

Returns: 1 on success, 0 if it doesn't fit in out or max_data is out of varint range

◆ quic_wtcapsule_encode_max_streams()

int quic_wtcapsule_encode_max_streams	(	quic_obuf *	out,
		int	bidi,
		u64	max_streams )

Encode a WT_MAX_STREAMS capsule (draft-ietf-webtrans-http3-15 SS5.6.2) into out: type 0x190B4D3F for bidi, 0x190B4D40 for uni, body a single varint (Maximum Streams).

Parameters

out	destination buffer view
bidi	nonzero for the bidirectional type, 0 for uni
max_streams	cumulative stream limit (<= 2^60 per the draft; not independently validated here, wire-range only)

Returns: 1 on success, 0 if it doesn't fit in out or max_streams is out of varint range

◆ quic_wtcapsule_encode_streams_blocked()

int quic_wtcapsule_encode_streams_blocked	(	quic_obuf *	out,
		int	bidi,
		u64	max_streams )

Encode a WT_STREAMS_BLOCKED capsule (SS5.6.3) into out: type 0x190B4D43 for bidi, 0x190B4D44 for uni, body a single varint (Maximum Streams).

Parameters

out	destination buffer view
bidi	nonzero for the bidirectional type, 0 for uni
max_streams	the stream limit in effect when blocking occurred

Returns: 1 on success, 0 if it doesn't fit in out or max_streams is out of varint range

Macros

Functions

Detailed Description

Function Documentation

◆ quic_wtcapsule_decode_close()

◆ quic_wtcapsule_decode_data_blocked()

◆ quic_wtcapsule_decode_drain()

◆ quic_wtcapsule_decode_max_data()

◆ quic_wtcapsule_decode_max_streams()

◆ quic_wtcapsule_decode_streams_blocked()

◆ quic_wtcapsule_encode_close()

◆ quic_wtcapsule_encode_data_blocked()

◆ quic_wtcapsule_encode_drain()

◆ quic_wtcapsule_encode_max_data()

◆ quic_wtcapsule_encode_max_streams()

◆ quic_wtcapsule_encode_streams_blocked()