magmalake flare_mlake

flare_mlake · API · grpc

flare.grpc.metadata

gRPC metadata carrier (initial + trailing).

gRPC metadata is a name-value map carried in HTTP/2 HEADERS frames at the start (initial metadata) and after the body (trailing metadata) of every call. The keys are ASCII-only (lowercased on the wire), and values come in two flavours:

  • Text keys (most): name ends in any suffix except -bin; value must be printable ASCII (subset of HTTP field-content per the gRPC spec).
  • Binary keys: name ends in -bin (e.g. trace-bin); value is arbitrary bytes encoded as base64 on the HTTP/2 wire. At the application layer the caller works with the raw bytes and the framing layer base64-encodes on egress, decodes on ingress.

Reserved keys begin with grpc- and are managed by the framework (e.g. grpc-status, grpc-message, grpc-encoding, grpc-timeout). The carrier rejects writes to reserved keys to keep handler code from accidentally clobbering framework-controlled trailers.

References:

Structs

GrpcMetadataEntry

struct GrpcMetadataEntry

Single metadata key-value pair. is_binary is derived from the key suffix (-bin) but cached for fast access.

Implements Copyable, Movable

Fields
key: String
value: List[UInt8]
is_binary: Bool

GrpcMetadata

struct GrpcMetadata

Ordered list of metadata entries.

The list preserves insertion order so trailers like set-cookie (rare in gRPC but legal) round-trip with their original sequence. Lookup is O(N) because metadata sets are typically tiny (under 10 entries); a hash-backed variant can be added later if profilers complain.

Implements Copyable, Defaultable, Movable

__init__

def __init__(out self)

copy

def copy(self) -> Self

len

def len(self) -> Int

append

def append(mut self, key: String, var value: List[UInt8])

Append a metadata entry. The key must not be reserved (grpc- prefix); reserved keys are framework-managed and are emitted by the gRPC adapter directly.

append_text

def append_text(mut self, key: String, value: String)

Convenience: append a text-valued metadata entry. The key must NOT end in -bin; text values that look like binary are a frequent footgun, so the carrier rejects them rather than silently mis-encoding.

get_text

def get_text(self, key: String) -> Optional[String]

Return the first text-valued entry under key, or None if absent. Raises if the entry is binary (the caller should use get_binary instead).

get_binary

def get_binary(self, key: String) -> Optional[List[UInt8]]

Return the first binary-valued entry under key.

entries

def entries(self) -> List[GrpcMetadataEntry]

Return a copy of the entry list (insertion order preserved). Useful for serialising the metadata into HTTP/2 HEADERS frames.