`flare.grpc.framing`

gRPC length-prefix-message (LPM) framing codec.

Every gRPC message on the wire is a 5-byte header followed by an opaque payload:

+--------+----------------+---------------+
| Flag   | Length (BE32)  | Payload bytes |
| (1B)   |   (4 bytes)    |  (Length B)   |
+--------+----------------+---------------+

Flag (1 byte): bit 0 is the "compressed" flag (1 = the payload is compressed with the message-level codec negotiated via grpc-encoding; 0 = uncompressed). All other bits are reserved and must be zero.
Length (4 bytes, big-endian): the byte count of the payload that follows. The wire-level maximum is 2^32 - 1; a per-channel max-receive-message-length policy lives at a higher layer.
Payload: opaque serialized protobuf (or other codec) bytes.

This is the wire format used by both unary RPCs (one frame in each direction) and streaming RPCs (multiple frames per stream). HTTP/2 DATA frames may carry a partial LPM frame or several back-to-back; the decoder must therefore handle "need more data" gracefully without throwing on a clean truncation at the buffer boundary.

References:

Structs

`GrpcCompressionFlag`

struct GrpcCompressionFlag

Typed wrapper around the LPM flag byte. is_compressed() returns True when bit 0 is set; raw exposes the byte for callers that need to forward greased / extension bits without interpretation.

Implements Copyable, Movable

Fields: raw: UInt8

`is_compressed`

def is_compressed(self) -> Bool

`has_reserved_bits`

def has_reserved_bits(self) -> Bool

Return True if any reserved bit (bits 1..7) is set. Callers may treat this as a protocol violation; the codec itself accepts the bits to remain forward-compatible with future spec extensions.

`GrpcMessage`

struct GrpcMessage

A decoded LPM frame: flag + opaque payload bytes.

Implements Copyable, Movable

Fields: flag: GrpcCompressionFlag; payload: List[UInt8]

`GrpcDecodeResult`

struct GrpcDecodeResult

Outcome of an LPM decode attempt.

The decoder operates on a streaming buffer where the message boundary may not yet be visible. needs_more is True when the buffer is too short to contain a complete frame; callers should accumulate more bytes and try again. message is populated only when needs_more is False.

Implements Copyable, Movable

Fields: message: GrpcMessage; consumed: Int; needs_more: Bool

Functions

`encode_grpc_message`

def encode_grpc_message(payload: Span[UInt8], mut out: List[UInt8], compressed: Bool = False)

Append a length-prefix-message (LPM) frame to out.

The frame is a single byte compression flag plus a 4-byte big-endian length plus the payload bytes. The caller is responsible for compressing the payload before calling this function if compressed=True; the framer just sets the flag byte and prefixes the length.

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_grpc_message`

def decode_grpc_message(buf: Span[UInt8]) -> GrpcDecodeResult

Decode the first complete LPM frame at the start of buf.

Returns needs_more=True (and an empty placeholder message) when the buffer is shorter than the declared frame. Raises only on hard errors -- in this version the only hard error is a payload length that would overflow Mojo's Int when the framer eventually accumulates consumed bytes (which would require a length declaration > 2^31; the wire format allows up to 2^32 - 1 but Mojo's Int is 64-bit so this is purely defensive).

Aliases

comptime GRPC_COMPRESSION_NONE = UInt8(0)

comptime GRPC_COMPRESSION_COMPRESSED = UInt8(1)

LPM flag-byte values. Other bits are reserved (RFC for HTTP/2- based gRPC framing) and must be zero on the wire.