# flare.grpc.metadata

> A module of flare_mlake's API.

``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:
- gRPC PROTOCOL-HTTP2 spec (Metadata section).
- https://grpc.github.io/grpc/core/md_doc_PROTOCOL-HTTP2.html

## Structs

### `GrpcMetadataEntry`

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

```mojo
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__`

```mojo
def __init__(out self)
```

#### `copy`

```mojo
def copy(self) -> Self
```

#### `len`

```mojo
def len(self) -> Int
```

#### `append`

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

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

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

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

Return the first binary-valued entry under ``key``.

#### `entries`

```mojo
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.