Module capsule 

The Capsule Protocol (RFC 9297 §3).

When a request stream carries Capsule-Protocol: ?1, its body is not a representation but a sequence of capsules:

Capsule Type (varint) | Capsule Length (varint) | Capsule Value

Two properties make this awkward and are the reason this module exists:

• Capsules do not align with stream chunks. A capsule may be split across any number of reads, and one read may contain many capsules. The decoder is therefore a state machine fed arbitrary byte slices, and the tests below feed it a byte at a time to prove it.
• Unknown capsule types must be skipped, not rejected (RFC 9297 §3.2), which is what lets the protocol be extended. Skipping uses the declared length, so a decoder that cannot skip cannot resynchronise.

Length is a varint and so may declare up to 2^62 bytes. Values of a known type are buffered, which is bounded here by rejecting anything larger than a UDP payload can be; values of unknown types are discarded as they arrive and are never buffered at all. Without both rules a peer could name a huge length and make the proxy allocate for it.

Structs

CapsuleDecoder

An incremental capsule decoder.

Enums

Capsule

A decoded capsule.

Error

Why a capsule sequence could not be decoded.

Constants

CAPSULE_TYPE_DATAGRAM

DATAGRAM capsule type (RFC 9297 §3.5).

MAX_DATAGRAM_CAPSULE_VALUE

Largest DATAGRAM capsule value accepted.

Functions

encode_datagram

Encodes a DATAGRAM capsule (RFC 9297 §3.5).