# flare.http3.capsule

> A module of flare_mlake's API.

The Capsule Protocol (RFC 9297 sec 3).

A capsule is ``type (varint) || length (varint) || value`` on the data
stream of a tunnel such as an extended CONNECT. Sans-I/O: the encoder
appends to a caller-owned buffer and the parser reads from the front of
one, returning ``None`` until a whole capsule is there.

## Structs

### `Capsule`

```mojo
struct Capsule
```

Implements: `Copyable`, `Movable`

Fields:

- `capsule_type: UInt64`
- `value: List[UInt8]`

## Functions

### `encode_capsule`

```mojo
def encode_capsule(capsule_type: UInt64, value: Span[UInt8], mut out: List[UInt8])
```

Append one capsule to ``out``.

### `parse_capsule`

```mojo
def parse_capsule(buf: Span[UInt8], max_value: Int) -> Optional[Tuple[Capsule, Int]]
```

The capsule at the front of ``buf`` and the bytes it spans, or ``None`` while it is incomplete. A value longer than ``max_value`` raises before any of it is buffered, so a peer cannot make the receiver hold an arbitrarily large capsule.

## Aliases

### `CAPSULE_TYPE_DATAGRAM`

```mojo
comptime CAPSULE_TYPE_DATAGRAM = UInt64(0)
```

RFC 9297 sec 3.5: an HTTP Datagram carried on the stream.