magmalake flare_mlake

flare_mlake · API · http2

flare.http2.frame

HTTP/2 frame codec (RFC 9113 §4).

Every HTTP/2 frame is a 9-octet header followed by a payload:

::

+-----------------------------------------------+
| Length (24) |
+---------------+---------------+---------------+
| Type (8) | Flags (8) |
+-+-------------+---------------+-------------------------------+
|R| Stream Identifier (31) |
+=+=============================================================+
| Frame Payload (0...) ...
+---------------------------------------------------------------+

This module provides:

  • :class:FrameHeader — the 9-byte fixed header.
  • :class:Frame — owned wrapper carrying header + payload.
  • :class:FrameType / :class:FrameFlags — typed constants.
  • :func:parse_frame — best-effort parser; raises Http2Error on malformed length / oversized payload / invalid stream-id.
  • :func:encode_frame — emit the wire representation.

The codec is connection-agnostic: it does not enforce stream state, frame ordering, or the SETTINGS/window math. Those checks live in :mod:flare.http2.state.

Structs

FrameType

struct FrameType

RFC 9113 §6 frame type codes (Table 1).

Implements Copyable, Defaultable, Movable

Fields
value: UInt8

__init__

def __init__(out self)
def __init__(out self, v: UInt8)

DATA

def DATA() -> Self

HEADERS

def HEADERS() -> Self

PRIORITY

def PRIORITY() -> Self

RST_STREAM

def RST_STREAM() -> Self

SETTINGS

def SETTINGS() -> Self

PUSH_PROMISE

def PUSH_PROMISE() -> Self

PING

def PING() -> Self

GOAWAY

def GOAWAY() -> Self

WINDOW_UPDATE

def WINDOW_UPDATE() -> Self

CONTINUATION

def CONTINUATION() -> Self

name

def name(self) -> String

FrameFlags

struct FrameFlags

RFC 9113 §6 per-type flag bits.

Implements Copyable, Defaultable, Movable

Fields
bits: UInt8

__init__

def __init__(out self)
def __init__(out self, b: UInt8)

has

def has(self, mask: UInt8) -> Bool

END_STREAM

def END_STREAM() -> UInt8

END_HEADERS

def END_HEADERS() -> UInt8

PADDED

def PADDED() -> UInt8

PRIORITY

def PRIORITY() -> UInt8

ACK

def ACK() -> UInt8

FrameHeader

struct FrameHeader

The 9-octet HTTP/2 frame header (RFC 9113 §4.1).

Stream id is unsigned 31-bit. The reserved high bit is masked off on parse and ignored on emit.

Implements Copyable, Defaultable, Movable

Fields
length: Int
type: FrameType
flags: FrameFlags
stream_id: Int

__init__

def __init__(out self)

Frame

struct Frame

A complete frame: header + owned payload bytes.

The payload is verbatim from the wire — it has not been decoded into HEADERS / SETTINGS / etc. typed fields. Higher layers (state.mojo and hpack.mojo) interpret the bytes.

Implements Copyable, Defaultable, Movable

Fields
header: FrameHeader
payload: List[UInt8]

__init__

def __init__(out self)

Functions

parse_frame

def parse_frame(buf: Span[UInt8]) -> Optional[Frame]

Try to parse one frame from the front of buf.

Raises Error: For frames whose declared length exceeds :data:H2_MAX_FRAME_SIZE (RFC 9113 §4.2 — connection error FRAME_SIZE_ERROR).

encode_frame_header_into

def encode_frame_header_into(ftype: FrameType, flags: FrameFlags, stream_id: Int, length: Int, mut out: List[UInt8])

Append the 9-octet frame header (RFC 9113 sec 4.1) for a payload of length bytes; the caller appends the payload itself.

encode_frame

def encode_frame(f: Frame) -> List[UInt8]

Emit the wire bytes for f (header + payload).

encode_frame_into

def encode_frame_into(f: Frame, mut out: List[UInt8])

Append the wire bytes for f (header + payload) to out.

Aliases

comptime H2_PREFACE = StringSpan("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n")

Fixed connection-preface bytes a client MUST send first.

comptime H2_DEFAULT_FRAME_SIZE = Int(16384)

SETTINGS_MAX_FRAME_SIZE initial value.

comptime H2_MAX_FRAME_SIZE = Int(16777215)

24-bit length field upper bound.