`flare.http3.frame`

HTTP/3 frame codec (RFC 9114 §7).

Every HTTP/3 frame on a request stream has the same shape:

Frame {
  Type   (varint),
  Length (varint),
  Frame Payload (..),
}

The frame type selects the payload schema. RFC 9114 §7.2 lists the seven core types (DATA, HEADERS, CANCEL_PUSH, SETTINGS, PUSH_PROMISE, GOAWAY, MAX_PUSH_ID); receivers are required to ignore (not error on) unknown types so the wire format can be extended without protocol negotiation.

This module is intentionally sans-I/O: the codec works on byte spans + buffers and never touches a socket or a QUIC stream adapter. The codec layer is the load-bearing primitive the future reactor + QUIC stream multiplexer will compose on top of.

References:

RFC 9114 §7 "HTTP/3 Frames".
RFC 9000 §16 (varint format; reused via :mod:flare.quic.varint).

Structs

`Http3FrameType`

struct Http3FrameType

Wraps a varint-encoded frame type. raw is the wire value; is_known() checks whether the type is one of the seven core types defined by RFC 9114. Receivers must ignore unknown types rather than erroring; the wrapper exists so callers can switch on the value cleanly.

Implements Copyable, Movable

Fields: raw: UInt64

`is_known`

def is_known(self) -> Bool

`is_reserved_grease`

def is_reserved_grease(self) -> Bool

RFC 9114 §7.2.8 reserves frame types of the form 0x1f * N + 0x21 as "grease" -- senders emit them to ensure receivers tolerate unknown types. The codec keeps the check inline so callers can audit grease tolerance.

`Http3Frame`

struct Http3Frame

Parsed HTTP/3 frame: type + payload bytes.

payload is a deep copy of the wire bytes that follow the type/length varints; callers own the buffer so the original receive buffer can be advanced/recycled.

Implements Copyable, Movable

Fields: frame_type: Http3FrameType; payload: List[UInt8]

`Http3Setting`

struct Http3Setting

A single identifier: value pair inside a SETTINGS frame's payload.

Implements Copyable, Movable

Fields: identifier: UInt64; value: UInt64

Functions

`encode_http3_frame`

def encode_http3_frame(frame_type: UInt64, payload: Span[UInt8], mut out: List[UInt8])

Append a complete RFC 9114 §7 frame (type varint, length varint, payload bytes) to out.

The caller owns the buffer and may reuse the same List[UInt8] across frames so the underlying allocation amortises across the stream. The encoder appends only; it never reads from or truncates the existing contents.

`decode_http3_frame`

def decode_http3_frame(buf: Span[UInt8]) -> Http3Frame

Decode the first complete frame at the start of buf.

Raises Error on a truncated input (a partial varint or a declared length that overruns buf). The decoder does not advance past the frame on its own; the caller computes the consumed length as decode_varint(type).consumed + decode_varint(length).consumed + length. This keeps the frame-level API focused on payload extraction; the framer-level API (stream cursor management) is the job of the HTTP/3 connection driver in a later cycle.

`encode_http3_settings`

def encode_http3_settings(settings: List[Http3Setting], mut out: List[UInt8])

Append the body of an HTTP/3 SETTINGS frame to out.

Writes the identifier / value varint pairs in order; the result is the payload only. Wrap it in :func:encode_http3_frame with type :data:H3_FRAME_TYPE_SETTINGS to get a complete frame.

The caller owns the buffer and may reuse the same List[UInt8] across calls so the underlying allocation amortises across the stream. The encoder appends only; it never reads from or truncates the existing contents.

`decode_http3_settings`

def decode_http3_settings(payload: Span[UInt8]) -> List[Http3Setting]

Decode a SETTINGS-frame payload into a list of pairs.

Raises if the payload is malformed (truncated varint, dangling identifier without a value). Duplicate identifiers are not rejected here -- RFC 9114 requires receivers to detect this and respond with H3_SETTINGS_ERROR, but that policy belongs to the connection driver, not the codec.

Aliases

comptime H3_FRAME_TYPE_DATA = UInt64(0)

comptime H3_FRAME_TYPE_HEADERS = UInt64(1)

comptime H3_FRAME_TYPE_CANCEL_PUSH = UInt64(3)

comptime H3_FRAME_TYPE_SETTINGS = UInt64(4)

comptime H3_FRAME_TYPE_PUSH_PROMISE = UInt64(5)

comptime H3_FRAME_TYPE_GOAWAY = UInt64(7)

comptime H3_FRAME_TYPE_MAX_PUSH_ID = UInt64(13)

comptime H3_FRAME_TYPE_H2_PRIORITY = UInt64(2)

HTTP/2 PRIORITY's type, reserved in HTTP/3 (RFC 9114 sec 7.2.8, 11.2.1): receipt on any stream is H3_FRAME_UNEXPECTED.

comptime H3_FRAME_TYPE_H2_PING = UInt64(6)

HTTP/2 PING's type, reserved in HTTP/3 (see :data:H3_FRAME_TYPE_H2_PRIORITY).

comptime H3_FRAME_TYPE_H2_WINDOW_UPDATE = UInt64(8)

HTTP/2 WINDOW_UPDATE's type, reserved in HTTP/3.

comptime H3_FRAME_TYPE_H2_CONTINUATION = UInt64(9)

HTTP/2 CONTINUATION's type, reserved in HTTP/3.

comptime H3_SETTINGS_QPACK_MAX_TABLE_CAPACITY = UInt64(1)

comptime H3_SETTINGS_MAX_FIELD_SECTION_SIZE = UInt64(6)

comptime H3_SETTINGS_QPACK_BLOCKED_STREAMS = UInt64(7)

comptime H3_SETTINGS_ENABLE_CONNECT_PROTOCOL = UInt64(8)

RFC 9220 — Bootstrapping WebSockets with HTTP/3.

comptime H3_SETTINGS_H3_DATAGRAM = UInt64(51)

RFC 9297 sec 2.1.1 — HTTP Datagrams; the value is 0 or 1.