Skip to main content

Module capsule

Module capsule 

Source
Expand description

RFC 9297-style HTTP Datagram capsule framing for CSCP bytes.

CSCP control bytes (CSCP magic TLV) travel as the DATAGRAM capsule value when UDP/HTTP/3 is unavailable. This module is framing only: it is not HTTP/3, not MASQUE Internet, not a full HTTP/2 stack, and not equivalent to UDP. Nested recovery over a reliable capsule stream is degraded (head-of-line blocking) and MUST be labelled as such.

Wire: Capsule Type (i) || Capsule Length (i) || Capsule Value (..) with QUIC/HTTP variable-length integers (RFC 9000 §16). DATAGRAM type is 0x00. The value is opaque CSCP bytes; this layer does not re-encode the CSCP TLV grammar.

Unknown-type policy (local CSCP profile, not an IANA / RFC 9297 registry claim — RFC 9297 ignores all unknown types):

  • 0x00 — DATAGRAM
  • 0x01..=0x3f — unknown non-critical: decode_capsule returns CapsuleError::UnknownNonCritical; decode_datagram_capsule skips the frame (counted skip) and continues
  • >= 0x40 — unknown critical: fail closed. This stands in for the QUIC 62-bit high-bit rule (type >= 1<<62), which cannot appear in a 62-bit varint. Tests use type 0x40.

Max Capsule Value is 1024 bytes (same numeric cap as CSCP MAX_BODY). Encode/decode take caller buffers; no Vec/String/Box on this path.

Enums§

CapsuleError

Constants§

CAPSULE_DATAGRAM
DATAGRAM capsule type (RFC 9297).
MAX_CAPSULE_VALUE
Maximum Capsule Value length in bytes.

Functions§

capsule_span
Byte length of the first well-formed capsule (type + length + value). Classifies nothing; unknown types still have a span for a counted skip.
decode_capsule
Decode one capsule. DATAGRAM → Ok((0x00, value)). Type 0x01..=0x3f → CapsuleError::UnknownNonCritical. Type >= 0x40 → CapsuleError::UnknownCritical.
decode_datagram_capsule
Decode a DATAGRAM value, skipping unknown non-critical capsules. Critical unknown fails closed. Empty input is Truncated. A stream of only non-critical unknowns is CapsuleError::UnknownNonCritical.
encode_capsule
Encode type || length || value into out. Payload > 1024 is Capacity.
encode_datagram_capsule
Encode a DATAGRAM capsule (0x00) carrying payload.