# flare.http3.frame > A module of flare_mlake's API. 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` ```mojo 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` ```mojo def is_known(self) -> Bool ``` #### `is_reserved_grease` ```mojo 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` ```mojo 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` ```mojo 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` ```mojo 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` ```mojo 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` ```mojo 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` ```mojo 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 ### `H3_FRAME_TYPE_DATA` ```mojo comptime H3_FRAME_TYPE_DATA = UInt64(0) ``` ### `H3_FRAME_TYPE_HEADERS` ```mojo comptime H3_FRAME_TYPE_HEADERS = UInt64(1) ``` ### `H3_FRAME_TYPE_CANCEL_PUSH` ```mojo comptime H3_FRAME_TYPE_CANCEL_PUSH = UInt64(3) ``` ### `H3_FRAME_TYPE_SETTINGS` ```mojo comptime H3_FRAME_TYPE_SETTINGS = UInt64(4) ``` ### `H3_FRAME_TYPE_PUSH_PROMISE` ```mojo comptime H3_FRAME_TYPE_PUSH_PROMISE = UInt64(5) ``` ### `H3_FRAME_TYPE_GOAWAY` ```mojo comptime H3_FRAME_TYPE_GOAWAY = UInt64(7) ``` ### `H3_FRAME_TYPE_MAX_PUSH_ID` ```mojo comptime H3_FRAME_TYPE_MAX_PUSH_ID = UInt64(13) ``` ### `H3_FRAME_TYPE_H2_PRIORITY` ```mojo 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``. ### `H3_FRAME_TYPE_H2_PING` ```mojo comptime H3_FRAME_TYPE_H2_PING = UInt64(6) ``` HTTP/2 PING's type, reserved in HTTP/3 (see :data:`H3_FRAME_TYPE_H2_PRIORITY`). ### `H3_FRAME_TYPE_H2_WINDOW_UPDATE` ```mojo comptime H3_FRAME_TYPE_H2_WINDOW_UPDATE = UInt64(8) ``` HTTP/2 WINDOW_UPDATE's type, reserved in HTTP/3. ### `H3_FRAME_TYPE_H2_CONTINUATION` ```mojo comptime H3_FRAME_TYPE_H2_CONTINUATION = UInt64(9) ``` HTTP/2 CONTINUATION's type, reserved in HTTP/3. ### `H3_SETTINGS_QPACK_MAX_TABLE_CAPACITY` ```mojo comptime H3_SETTINGS_QPACK_MAX_TABLE_CAPACITY = UInt64(1) ``` ### `H3_SETTINGS_MAX_FIELD_SECTION_SIZE` ```mojo comptime H3_SETTINGS_MAX_FIELD_SECTION_SIZE = UInt64(6) ``` ### `H3_SETTINGS_QPACK_BLOCKED_STREAMS` ```mojo comptime H3_SETTINGS_QPACK_BLOCKED_STREAMS = UInt64(7) ``` ### `H3_SETTINGS_ENABLE_CONNECT_PROTOCOL` ```mojo comptime H3_SETTINGS_ENABLE_CONNECT_PROTOCOL = UInt64(8) ``` RFC 9220 — Bootstrapping WebSockets with HTTP/3. ### `H3_SETTINGS_H3_DATAGRAM` ```mojo comptime H3_SETTINGS_H3_DATAGRAM = UInt64(51) ``` RFC 9297 sec 2.1.1 — HTTP Datagrams; the value is 0 or 1.