QUIC frame parsing and building (RFC 9000 sec 19). More...

#include "protocore_config.h"

Classes
struct	QuicAckFrame
	ACK payload (RFC 9000 sec 19.3). More...

struct	QuicCryptoFrame
	CRYPTO payload (RFC 9000 sec 19.6). `data` aliases the input buffer. More...

struct	QuicStreamFrame
	STREAM payload (RFC 9000 sec 19.8). `data` aliases the input buffer. More...

struct	QuicMaxDataFrame
	MAX_DATA payload (RFC 9000 sec 19.9). More...

struct	QuicCloseFrame
	CONNECTION_CLOSE payload (RFC 9000 sec 19.19). `reason` aliases the input buffer. More...

struct	QuicFrameHeader
	One parsed frame. Pointer fields alias the input buffer (not copied). More...

struct	QuicFrameNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	QUIC_FT_PADDING 0x00

#define	QUIC_FT_PING 0x01

#define	QUIC_FT_ACK 0x02
	0x02 (no ECN) .. 0x03 (with ECN counts)

#define	QUIC_FT_ACK_ECN 0x03

#define	QUIC_FT_CRYPTO 0x06

#define	QUIC_FT_STREAM 0x08
	0x08..0x0f; low 3 bits are OFF (0x04) / LEN (0x02) / FIN (0x01)

#define	QUIC_FT_MAX_DATA 0x10

#define	QUIC_FT_CONNECTION_CLOSE 0x1c
	transport-level close (carries the triggering frame type)

#define	QUIC_FT_CONNECTION_CLOSE_APP 0x1d
	application-level close

#define	QUIC_FT_HANDSHAKE_DONE 0x1e

#define	QUIC_FT_RESET_STREAM 0x04

#define	QUIC_FT_STOP_SENDING 0x05

#define	QUIC_FT_NEW_TOKEN 0x07

#define	QUIC_FT_MAX_STREAM_DATA 0x11

#define	QUIC_FT_MAX_STREAMS_BIDI 0x12

#define	QUIC_FT_MAX_STREAMS_UNI 0x13

#define	QUIC_FT_DATA_BLOCKED 0x14

#define	QUIC_FT_STREAM_DATA_BLOCKED 0x15

#define	QUIC_FT_STREAMS_BLOCKED_BIDI 0x16

#define	QUIC_FT_STREAMS_BLOCKED_UNI 0x17

#define	QUIC_FT_NEW_CONNECTION_ID 0x18

#define	QUIC_FT_RETIRE_CONNECTION_ID 0x19

#define	QUIC_FT_PATH_CHALLENGE 0x1a

#define	QUIC_FT_PATH_RESPONSE 0x1b

#define	QUIC_STREAM_FIN 0x01
	STREAM frame type bits.

#define	QUIC_STREAM_LEN 0x02

#define	QUIC_STREAM_OFF 0x04

#define	QUIC_ERR_NO_ERROR 0x00
	Transport error codes for CONNECTION_CLOSE (RFC 9000 sec 20.1).

#define	QUIC_ERR_INTERNAL 0x01

#define	QUIC_ERR_FLOW_CONTROL 0x03

#define	QUIC_ERR_STREAM_LIMIT 0x04

#define	QUIC_ERR_FRAME_ENCODING 0x07
	a frame could not be decoded

#define	QUIC_ERR_PROTOCOL_VIOLATION 0x0a
	a frame/packet violated the protocol

#define	QUIC_ERR_APPLICATION 0x0c
	the application abandoned the connection (sec 20.1)

#define	QUIC_ERR_CRYPTO_BASE 0x0100
	0x0100 + the TLS alert code (RFC 9001 sec 4.8)

Functions
	PROTOCORE_NS_LAYOUT (QuicFrameNs, parse, build_padding, build_ping, build_handshake_done, build_ack, build_crypto, build_stream, build_max_data, build_connection_close)

size_t	protocore_quic_frame_parse (uint8_t work, const uint8_t buf, size_t len, QuicFrameHeader *out)
	Parse one frame at buf. bytes consumed, or 0 on malformed / .

size_t	protocore_quic_frame_build_padding (uint8_t work, uint8_t out, size_t cap, size_t n)
	N PADDING frames (n zero bytes). n, or 0 if it does not fit.

size_t	protocore_quic_frame_build_ping (uint8_t work, uint8_t out, size_t cap)
	A PING frame.

size_t	protocore_quic_frame_build_handshake_done (uint8_t work, uint8_t out, size_t cap)
	A HANDSHAKE_DONE frame.

size_t	protocore_quic_frame_build_ack (uint8_t work, uint8_t out, size_t cap, uint64_t largest, uint64_t delay, uint64_t first_range)
	A single-range ACK frame (ACK Range Count 0): Largest, ACK Delay, .

size_t	protocore_quic_frame_build_crypto (uint8_t work, uint8_t out, size_t cap, uint64_t offset, const uint8_t *data, size_t len)
	A CRYPTO frame carrying len bytes at stream offset.

size_t	protocore_quic_frame_build_stream (uint8_t work, uint8_t out, size_t cap, uint64_t id, uint64_t offset, const uint8_t *data, size_t len, proto_bool fin)
	A STREAM frame (LEN always set; OFF set when offset > 0; FIN per .

size_t	protocore_quic_frame_build_max_data (uint8_t work, uint8_t out, size_t cap, uint64_t max)
	A MAX_DATA frame.

size_t	protocore_quic_frame_build_connection_close (uint8_t work, uint8_t out, size_t cap, proto_bool app, uint64_t error_code, uint64_t frame_type, const char *reason, size_t reason_len)
	A CONNECTION_CLOSE with a reason phrase. app selects the .

Variables
PROTOCORE_NS QuicFrameNs QuicFrame	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

QUIC frame parsing and building (RFC 9000 sec 19).

The payload of a QUIC packet is a sequence of frames, each Frame Type (i) followed by type-specific fields coded with QUIC varints. This module reads one frame at a time into a tagged QuicFrameHeader and builds the frames a server sends. It covers the frames a minimal HTTP/3 server needs - PADDING, PING, ACK, CRYPTO, STREAM, MAX_DATA, CONNECTION_CLOSE, HANDSHAKE_DONE - and reports the frame type for anything else so the caller can decide.

Data-bearing frames (CRYPTO / STREAM / CONNECTION_CLOSE reason) point into the caller's packet buffer; nothing is copied. Pure, zero heap, host-tested.

work is bytes the CALLER holds. This module reads none of them: it carries nothing between calls, so there is no state to keep and nothing to wipe. The parameter is there so a caller drives every namespace the same way.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file quic_frame.h.

Macro Definition Documentation

◆ QUIC_FT_PADDING

#define QUIC_FT_PADDING 0x00

Definition at line 36 of file quic_frame.h.

◆ QUIC_FT_PING

#define QUIC_FT_PING 0x01

Definition at line 37 of file quic_frame.h.

◆ QUIC_FT_ACK

#define QUIC_FT_ACK 0x02

0x02 (no ECN) .. 0x03 (with ECN counts)

Definition at line 38 of file quic_frame.h.

◆ QUIC_FT_ACK_ECN

#define QUIC_FT_ACK_ECN 0x03

Definition at line 39 of file quic_frame.h.

◆ QUIC_FT_CRYPTO

#define QUIC_FT_CRYPTO 0x06

Definition at line 40 of file quic_frame.h.

◆ QUIC_FT_STREAM

#define QUIC_FT_STREAM 0x08

0x08..0x0f; low 3 bits are OFF (0x04) / LEN (0x02) / FIN (0x01)

Definition at line 41 of file quic_frame.h.

◆ QUIC_FT_MAX_DATA

#define QUIC_FT_MAX_DATA 0x10

Definition at line 42 of file quic_frame.h.

◆ QUIC_FT_CONNECTION_CLOSE

#define QUIC_FT_CONNECTION_CLOSE 0x1c

transport-level close (carries the triggering frame type)

Definition at line 43 of file quic_frame.h.

◆ QUIC_FT_CONNECTION_CLOSE_APP

#define QUIC_FT_CONNECTION_CLOSE_APP 0x1d

application-level close

Definition at line 44 of file quic_frame.h.

◆ QUIC_FT_HANDSHAKE_DONE

#define QUIC_FT_HANDSHAKE_DONE 0x1e

Definition at line 45 of file quic_frame.h.

◆ QUIC_FT_RESET_STREAM

#define QUIC_FT_RESET_STREAM 0x04

Definition at line 52 of file quic_frame.h.

◆ QUIC_FT_STOP_SENDING

#define QUIC_FT_STOP_SENDING 0x05

Definition at line 53 of file quic_frame.h.

◆ QUIC_FT_NEW_TOKEN

#define QUIC_FT_NEW_TOKEN 0x07

Definition at line 54 of file quic_frame.h.

◆ QUIC_FT_MAX_STREAM_DATA

#define QUIC_FT_MAX_STREAM_DATA 0x11

Definition at line 55 of file quic_frame.h.

◆ QUIC_FT_MAX_STREAMS_BIDI

#define QUIC_FT_MAX_STREAMS_BIDI 0x12

Definition at line 56 of file quic_frame.h.

◆ QUIC_FT_MAX_STREAMS_UNI

#define QUIC_FT_MAX_STREAMS_UNI 0x13

Definition at line 57 of file quic_frame.h.

◆ QUIC_FT_DATA_BLOCKED

#define QUIC_FT_DATA_BLOCKED 0x14

Definition at line 58 of file quic_frame.h.

◆ QUIC_FT_STREAM_DATA_BLOCKED

#define QUIC_FT_STREAM_DATA_BLOCKED 0x15

Definition at line 59 of file quic_frame.h.

◆ QUIC_FT_STREAMS_BLOCKED_BIDI

#define QUIC_FT_STREAMS_BLOCKED_BIDI 0x16

Definition at line 60 of file quic_frame.h.

◆ QUIC_FT_STREAMS_BLOCKED_UNI

#define QUIC_FT_STREAMS_BLOCKED_UNI 0x17

Definition at line 61 of file quic_frame.h.

◆ QUIC_FT_NEW_CONNECTION_ID

#define QUIC_FT_NEW_CONNECTION_ID 0x18

Definition at line 62 of file quic_frame.h.

◆ QUIC_FT_RETIRE_CONNECTION_ID

#define QUIC_FT_RETIRE_CONNECTION_ID 0x19

Definition at line 63 of file quic_frame.h.

◆ QUIC_FT_PATH_CHALLENGE

#define QUIC_FT_PATH_CHALLENGE 0x1a

Definition at line 64 of file quic_frame.h.

◆ QUIC_FT_PATH_RESPONSE

#define QUIC_FT_PATH_RESPONSE 0x1b

Definition at line 65 of file quic_frame.h.

◆ QUIC_STREAM_FIN

#define QUIC_STREAM_FIN 0x01

STREAM frame type bits.

Definition at line 68 of file quic_frame.h.

◆ QUIC_STREAM_LEN

#define QUIC_STREAM_LEN 0x02

Definition at line 69 of file quic_frame.h.

◆ QUIC_STREAM_OFF

#define QUIC_STREAM_OFF 0x04

Definition at line 70 of file quic_frame.h.

◆ QUIC_ERR_NO_ERROR

#define QUIC_ERR_NO_ERROR 0x00

Transport error codes for CONNECTION_CLOSE (RFC 9000 sec 20.1).

Definition at line 73 of file quic_frame.h.

◆ QUIC_ERR_INTERNAL

#define QUIC_ERR_INTERNAL 0x01

Definition at line 74 of file quic_frame.h.

◆ QUIC_ERR_FLOW_CONTROL

#define QUIC_ERR_FLOW_CONTROL 0x03

Definition at line 75 of file quic_frame.h.

◆ QUIC_ERR_STREAM_LIMIT

#define QUIC_ERR_STREAM_LIMIT 0x04

Definition at line 76 of file quic_frame.h.

◆ QUIC_ERR_FRAME_ENCODING

#define QUIC_ERR_FRAME_ENCODING 0x07

a frame could not be decoded

Definition at line 77 of file quic_frame.h.

◆ QUIC_ERR_PROTOCOL_VIOLATION

#define QUIC_ERR_PROTOCOL_VIOLATION 0x0a

a frame/packet violated the protocol

Definition at line 78 of file quic_frame.h.

◆ QUIC_ERR_APPLICATION

#define QUIC_ERR_APPLICATION 0x0c

the application abandoned the connection (sec 20.1)

Definition at line 79 of file quic_frame.h.

◆ QUIC_ERR_CRYPTO_BASE

#define QUIC_ERR_CRYPTO_BASE 0x0100

0x0100 + the TLS alert code (RFC 9001 sec 4.8)

Definition at line 80 of file quic_frame.h.

Function Documentation

◆ PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	QuicFrameNs	,
		parse	,
		build_padding	,
		build_ping	,
		build_handshake_done	,
		build_ack	,
		build_crypto	,
		build_stream	,
		build_max_data	,
		build_connection_close
	)

◆ protocore_quic_frame_parse()

size_t protocore_quic_frame_parse	(	uint8_t *	work,
		const uint8_t *	buf,
		size_t	len,
		QuicFrameHeader *	out
	)

Parse one frame at buf. bytes consumed, or 0 on malformed / .

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
buf	Buf
len	Len
out	Out

Returns: The size_t.

◆ protocore_quic_frame_build_padding()

size_t protocore_quic_frame_build_padding	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		size_t	n
	)

N PADDING frames (n zero bytes). n, or 0 if it does not fit.

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
n	N

Returns: The size_t.

◆ protocore_quic_frame_build_ping()

size_t protocore_quic_frame_build_ping	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap
	)

A PING frame.

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap

Returns: The size_t.

◆ protocore_quic_frame_build_handshake_done()

size_t protocore_quic_frame_build_handshake_done	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap
	)

A HANDSHAKE_DONE frame.

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap

Returns: The size_t.

◆ protocore_quic_frame_build_ack()

size_t protocore_quic_frame_build_ack	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint64_t	largest,
		uint64_t	delay,
		uint64_t	first_range
	)

A single-range ACK frame (ACK Range Count 0): Largest, ACK Delay, .

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
largest	Largest
delay	Delay
first_range	First range

Returns: The size_t.

◆ protocore_quic_frame_build_crypto()

size_t protocore_quic_frame_build_crypto	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint64_t	offset,
		const uint8_t *	data,
		size_t	len
	)

A CRYPTO frame carrying len bytes at stream offset.

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
offset	Offset
data	Data
len	Len

Returns: The size_t.

◆ protocore_quic_frame_build_stream()

size_t protocore_quic_frame_build_stream	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint64_t	id,
		uint64_t	offset,
		const uint8_t *	data,
		size_t	len,
		proto_bool	fin
	)

A STREAM frame (LEN always set; OFF set when offset > 0; FIN per .

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
id	Id
offset	Offset
data	Data
len	Len
fin	Fin

Returns: The size_t.

◆ protocore_quic_frame_build_max_data()

size_t protocore_quic_frame_build_max_data	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint64_t	max
	)

A MAX_DATA frame.

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
max	Max

Returns: The size_t.

◆ protocore_quic_frame_build_connection_close()

size_t protocore_quic_frame_build_connection_close	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		proto_bool	app,
		uint64_t	error_code,
		uint64_t	frame_type,
		const char *	reason,
		size_t	reason_len
	)

A CONNECTION_CLOSE with a reason phrase. app selects the .

Parameters

work	PROTOCORE_QUIC_FRAME_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
app	App
error_code	Error code
frame_type	Frame type
reason	Reason
reason_len	Reason len

Returns: The size_t.

Variable Documentation

◆ PROTOCORE_UNUSED

PROTOCORE_NS QuicFrameNs QuicFrame PROTOCORE_UNUSED

Initial value:

= {
    .parse = protocore_quic_frame_parse,
    .build_padding = protocore_quic_frame_build_padding,
    .build_ping = protocore_quic_frame_build_ping,
    .build_handshake_done = protocore_quic_frame_build_handshake_done,
    .build_ack = protocore_quic_frame_build_ack,
    .build_crypto = protocore_quic_frame_build_crypto,
    .build_stream = protocore_quic_frame_build_stream,
    .build_max_data = protocore_quic_frame_build_max_data,
    .build_connection_close = protocore_quic_frame_build_connection_close}

Module namespace.

Definition at line 253 of file quic_frame.h.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ QUIC_FT_PADDING

◆ QUIC_FT_PING

◆ QUIC_FT_ACK

◆ QUIC_FT_ACK_ECN

◆ QUIC_FT_CRYPTO

◆ QUIC_FT_STREAM

◆ QUIC_FT_MAX_DATA

◆ QUIC_FT_CONNECTION_CLOSE

◆ QUIC_FT_CONNECTION_CLOSE_APP

◆ QUIC_FT_HANDSHAKE_DONE

◆ QUIC_FT_RESET_STREAM

◆ QUIC_FT_STOP_SENDING

◆ QUIC_FT_NEW_TOKEN

◆ QUIC_FT_MAX_STREAM_DATA

◆ QUIC_FT_MAX_STREAMS_BIDI

◆ QUIC_FT_MAX_STREAMS_UNI

◆ QUIC_FT_DATA_BLOCKED

◆ QUIC_FT_STREAM_DATA_BLOCKED

◆ QUIC_FT_STREAMS_BLOCKED_BIDI

◆ QUIC_FT_STREAMS_BLOCKED_UNI

◆ QUIC_FT_NEW_CONNECTION_ID

◆ QUIC_FT_RETIRE_CONNECTION_ID

◆ QUIC_FT_PATH_CHALLENGE

◆ QUIC_FT_PATH_RESPONSE

◆ QUIC_STREAM_FIN

◆ QUIC_STREAM_LEN

◆ QUIC_STREAM_OFF

◆ QUIC_ERR_NO_ERROR

◆ QUIC_ERR_INTERNAL

◆ QUIC_ERR_FLOW_CONTROL

◆ QUIC_ERR_STREAM_LIMIT

◆ QUIC_ERR_FRAME_ENCODING

◆ QUIC_ERR_PROTOCOL_VIOLATION

◆ QUIC_ERR_APPLICATION

◆ QUIC_ERR_CRYPTO_BASE

Function Documentation

◆ PROTOCORE_NS_LAYOUT()

◆ protocore_quic_frame_parse()

◆ protocore_quic_frame_build_padding()

◆ protocore_quic_frame_build_ping()

◆ protocore_quic_frame_build_handshake_done()

◆ protocore_quic_frame_build_ack()

◆ protocore_quic_frame_build_crypto()

◆ protocore_quic_frame_build_stream()

◆ protocore_quic_frame_build_max_data()

◆ protocore_quic_frame_build_connection_close()

Variable Documentation

◆ PROTOCORE_UNUSED