Skip to main content

qualia_core_db/net/peer/fabric/
capsule.rs

1//! RFC 9297-style HTTP Datagram capsule framing for CSCP bytes.
2//!
3//! CSCP control bytes (`CSCP` magic TLV) travel as the DATAGRAM capsule
4//! value when UDP/HTTP/3 is unavailable. This module is **framing only**:
5//! it is not HTTP/3, not MASQUE Internet, not a full HTTP/2 stack, and
6//! not equivalent to UDP. Nested recovery over a reliable capsule stream
7//! is degraded (head-of-line blocking) and MUST be labelled as such.
8//!
9//! Wire: `Capsule Type (i) || Capsule Length (i) || Capsule Value (..)`
10//! with QUIC/HTTP variable-length integers (RFC 9000 §16). DATAGRAM
11//! type is `0x00`. The value is opaque CSCP bytes; this layer does not
12//! re-encode the CSCP TLV grammar.
13//!
14//! Unknown-type policy (local CSCP profile, not an IANA / RFC 9297
15//! registry claim — RFC 9297 ignores all unknown types):
16//! - `0x00` — DATAGRAM
17//! - `0x01..=0x3f` — unknown non-critical: [`decode_capsule`] returns
18//!   [`CapsuleError::UnknownNonCritical`]; [`decode_datagram_capsule`]
19//!   skips the frame (counted skip) and continues
20//! - `>= 0x40` — unknown critical: fail closed. This stands in for the
21//!   QUIC 62-bit high-bit rule (`type >= 1<<62`), which cannot appear in
22//!   a 62-bit varint. Tests use type `0x40`.
23//!
24//! Max Capsule Value is 1024 bytes (same numeric cap as CSCP `MAX_BODY`).
25//! Encode/decode take caller buffers; no `Vec`/`String`/`Box` on this path.
26
27/// DATAGRAM capsule type (RFC 9297).
28pub const CAPSULE_DATAGRAM: u64 = 0x00;
29
30/// Maximum Capsule Value length in bytes.
31pub const MAX_CAPSULE_VALUE: usize = 1024;
32
33const VARINT_1: u64 = 1 << 6;
34const VARINT_2: u64 = 1 << 14;
35const VARINT_4: u64 = 1 << 30;
36const MAX_VARINT: u64 = (1 << 62) - 1;
37const NONCRITICAL_TYPE_MAX: u64 = 0x3f;
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum CapsuleError {
41    Truncated,
42    Capacity,
43    Malformed,
44    UnknownCritical,
45    UnknownNonCritical,
46}
47
48#[derive(Clone, Copy)]
49enum TypeClass {
50    Datagram,
51    UnknownNonCritical,
52    UnknownCritical,
53}
54
55#[inline]
56const fn type_class(ty: u64) -> TypeClass {
57    if ty == CAPSULE_DATAGRAM {
58        TypeClass::Datagram
59    } else if ty <= NONCRITICAL_TYPE_MAX {
60        TypeClass::UnknownNonCritical
61    } else {
62        TypeClass::UnknownCritical
63    }
64}
65
66#[inline]
67const fn varint_len(value: u64) -> usize {
68    if value < VARINT_1 {
69        1
70    } else if value < VARINT_2 {
71        2
72    } else if value < VARINT_4 {
73        4
74    } else {
75        8
76    }
77}
78
79fn encode_varint(value: u64, out: &mut [u8]) -> Result<usize, CapsuleError> {
80    if value > MAX_VARINT {
81        return Err(CapsuleError::Malformed);
82    }
83    let len = varint_len(value);
84    if out.len() < len {
85        return Err(CapsuleError::Capacity);
86    }
87    match len {
88        1 => out[0] = value as u8,
89        2 => {
90            let n = (value as u16) | 0x4000;
91            out[..2].copy_from_slice(&n.to_be_bytes());
92        }
93        4 => {
94            let n = (value as u32) | 0x8000_0000;
95            out[..4].copy_from_slice(&n.to_be_bytes());
96        }
97        _ => {
98            let n = value | 0xC000_0000_0000_0000;
99            out[..8].copy_from_slice(&n.to_be_bytes());
100        }
101    }
102    Ok(len)
103}
104
105fn decode_varint(src: &[u8]) -> Result<(u64, usize), CapsuleError> {
106    let first = *src.first().ok_or(CapsuleError::Truncated)?;
107    let len = 1usize << (first >> 6);
108    if src.len() < len {
109        return Err(CapsuleError::Truncated);
110    }
111    let value = match len {
112        1 => first as u64,
113        2 => u16::from_be_bytes([src[0], src[1]]) as u64 & 0x3fff,
114        4 => u32::from_be_bytes([src[0], src[1], src[2], src[3]]) as u64 & 0x3fff_ffff,
115        8 => {
116            u64::from_be_bytes([
117                src[0], src[1], src[2], src[3], src[4], src[5], src[6], src[7],
118            ]) & MAX_VARINT
119        }
120        _ => return Err(CapsuleError::Malformed),
121    };
122    if varint_len(value) != len {
123        return Err(CapsuleError::Malformed);
124    }
125    Ok((value, len))
126}
127
128/// Parse one well-formed capsule. Returns `(type, value_offset, value_len)`.
129fn parse_frame(bytes: &[u8]) -> Result<(u64, usize, usize), CapsuleError> {
130    let (ty, tlen) = decode_varint(bytes)?;
131    let rest = bytes.get(tlen..).ok_or(CapsuleError::Truncated)?;
132    let (vlen, llen) = decode_varint(rest)?;
133    if vlen > MAX_CAPSULE_VALUE as u64 {
134        return Err(CapsuleError::Capacity);
135    }
136    let vlen_us = vlen as usize;
137    let header = tlen + llen;
138    let end = header.checked_add(vlen_us).ok_or(CapsuleError::Malformed)?;
139    if bytes.len() < end {
140        return Err(CapsuleError::Truncated);
141    }
142    Ok((ty, header, vlen_us))
143}
144
145/// Byte length of the first well-formed capsule (type + length + value).
146/// Classifies nothing; unknown types still have a span for a counted skip.
147pub fn capsule_span(bytes: &[u8]) -> Result<usize, CapsuleError> {
148    let (_, header, vlen) = parse_frame(bytes)?;
149    Ok(header + vlen)
150}
151
152/// Encode `type || length || value` into `out`. Payload > 1024 is Capacity.
153pub fn encode_capsule(ty: u64, payload: &[u8], out: &mut [u8]) -> Result<usize, CapsuleError> {
154    if payload.len() > MAX_CAPSULE_VALUE {
155        return Err(CapsuleError::Capacity);
156    }
157    let n_ty = encode_varint(ty, out)?;
158    let n_len = encode_varint(payload.len() as u64, &mut out[n_ty..])?;
159    let start = n_ty + n_len;
160    let end = start + payload.len();
161    if out.len() < end {
162        return Err(CapsuleError::Capacity);
163    }
164    out[start..end].copy_from_slice(payload);
165    Ok(end)
166}
167
168/// Encode a DATAGRAM capsule (`0x00`) carrying `payload`.
169pub fn encode_datagram_capsule(payload: &[u8], out: &mut [u8]) -> Result<usize, CapsuleError> {
170    encode_capsule(CAPSULE_DATAGRAM, payload, out)
171}
172
173/// Decode one capsule. DATAGRAM → `Ok((0x00, value))`.
174/// Type `0x01..=0x3f` → [`CapsuleError::UnknownNonCritical`].
175/// Type `>= 0x40` → [`CapsuleError::UnknownCritical`].
176pub fn decode_capsule(bytes: &[u8]) -> Result<(u64, &[u8]), CapsuleError> {
177    let (ty, header, vlen) = parse_frame(bytes)?;
178    match type_class(ty) {
179        TypeClass::Datagram => Ok((ty, &bytes[header..header + vlen])),
180        TypeClass::UnknownNonCritical => Err(CapsuleError::UnknownNonCritical),
181        TypeClass::UnknownCritical => Err(CapsuleError::UnknownCritical),
182    }
183}
184
185/// Decode a DATAGRAM value, skipping unknown non-critical capsules.
186/// Critical unknown fails closed. Empty input is Truncated. A stream of
187/// only non-critical unknowns is [`CapsuleError::UnknownNonCritical`].
188pub fn decode_datagram_capsule(bytes: &[u8]) -> Result<&[u8], CapsuleError> {
189    let mut off = 0;
190    let mut skipped = 0usize;
191    while off < bytes.len() {
192        let (ty, header, vlen) = parse_frame(&bytes[off..])?;
193        let span = header + vlen;
194        match type_class(ty) {
195            TypeClass::Datagram => return Ok(&bytes[off + header..off + header + vlen]),
196            TypeClass::UnknownNonCritical => {
197                skipped = skipped.saturating_add(1);
198                off += span;
199            }
200            TypeClass::UnknownCritical => return Err(CapsuleError::UnknownCritical),
201        }
202    }
203    if skipped > 0 {
204        Err(CapsuleError::UnknownNonCritical)
205    } else {
206        Err(CapsuleError::Truncated)
207    }
208}
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213
214    const CSCP_SHAPED: &[u8] = b"CSCP\x01\x00\x04body";
215
216    #[test]
217    fn datagram_round_trip_cscp_shaped() {
218        let mut out = [0u8; 64];
219        let n = encode_datagram_capsule(CSCP_SHAPED, &mut out).unwrap();
220        assert!(n > CSCP_SHAPED.len());
221        assert_eq!(out[0], 0x00);
222        let got = decode_datagram_capsule(&out[..n]).unwrap();
223        assert_eq!(got, CSCP_SHAPED);
224        let (ty, val) = decode_capsule(&out[..n]).unwrap();
225        assert_eq!(ty, CAPSULE_DATAGRAM);
226        assert_eq!(val, CSCP_SHAPED);
227    }
228
229    #[test]
230    fn truncated_buffer_and_input_fail_closed() {
231        let mut tiny = [0u8; 1];
232        assert_eq!(
233            encode_datagram_capsule(CSCP_SHAPED, &mut tiny),
234            Err(CapsuleError::Capacity)
235        );
236        assert_eq!(decode_datagram_capsule(&[]), Err(CapsuleError::Truncated));
237        assert_eq!(decode_capsule(&[0x00]), Err(CapsuleError::Truncated));
238        assert_eq!(decode_capsule(&[0x40]), Err(CapsuleError::Truncated));
239        // DATAGRAM, length 4, only 2 value bytes.
240        assert_eq!(
241            decode_datagram_capsule(&[0x00, 0x04, b'a', b'b']),
242            Err(CapsuleError::Truncated)
243        );
244    }
245
246    #[test]
247    fn oversize_payload_is_capacity() {
248        let big = [0x5au8; 1025];
249        let mut out = [0u8; 1100];
250        assert_eq!(
251            encode_datagram_capsule(&big, &mut out),
252            Err(CapsuleError::Capacity)
253        );
254        let max = [0x5au8; 1024];
255        let n = encode_datagram_capsule(&max, &mut out).unwrap();
256        assert_eq!(decode_datagram_capsule(&out[..n]).unwrap(), &max[..]);
257        // Claimed length 1025 as a 2-byte varint (0x4401).
258        assert_eq!(
259            decode_capsule(&[0x00, 0x44, 0x01]),
260            Err(CapsuleError::Capacity)
261        );
262    }
263
264    #[test]
265    fn unknown_noncritical_skipped_or_rejected() {
266        let mut frame = [0u8; 32];
267        let skip_n = encode_capsule(0x01, b"x", &mut frame).unwrap();
268        assert_eq!(
269            decode_capsule(&frame[..skip_n]),
270            Err(CapsuleError::UnknownNonCritical)
271        );
272        assert_eq!(capsule_span(&frame[..skip_n]).unwrap(), skip_n);
273
274        let mut dgm = [0u8; 32];
275        let d_n = encode_datagram_capsule(CSCP_SHAPED, &mut dgm).unwrap();
276        let mut stream = [0u8; 64];
277        stream[..skip_n].copy_from_slice(&frame[..skip_n]);
278        stream[skip_n..skip_n + d_n].copy_from_slice(&dgm[..d_n]);
279        let got = decode_datagram_capsule(&stream[..skip_n + d_n]).unwrap();
280        assert_eq!(got, CSCP_SHAPED);
281
282        let mut skip2 = [0u8; 16];
283        let s2 = encode_capsule(0x3f, b"z", &mut skip2).unwrap();
284        let mut two = [0u8; 80];
285        two[..skip_n].copy_from_slice(&frame[..skip_n]);
286        two[skip_n..skip_n + s2].copy_from_slice(&skip2[..s2]);
287        two[skip_n + s2..skip_n + s2 + d_n].copy_from_slice(&dgm[..d_n]);
288        assert_eq!(
289            decode_datagram_capsule(&two[..skip_n + s2 + d_n]).unwrap(),
290            CSCP_SHAPED
291        );
292        assert_eq!(
293            decode_datagram_capsule(&frame[..skip_n]),
294            Err(CapsuleError::UnknownNonCritical)
295        );
296    }
297
298    #[test]
299    fn unknown_critical_rejected() {
300        let mut frame = [0u8; 16];
301        let n = encode_capsule(0x40, b"y", &mut frame).unwrap();
302        assert!(n >= 3);
303        assert_eq!(frame[0] & 0xc0, 0x40);
304        assert_eq!(
305            decode_capsule(&frame[..n]),
306            Err(CapsuleError::UnknownCritical)
307        );
308        assert_eq!(
309            decode_datagram_capsule(&frame[..n]),
310            Err(CapsuleError::UnknownCritical)
311        );
312        let mut dgm = [0u8; 32];
313        let d_n = encode_datagram_capsule(CSCP_SHAPED, &mut dgm).unwrap();
314        let mut mixed = [0u8; 64];
315        mixed[..n].copy_from_slice(&frame[..n]);
316        mixed[n..n + d_n].copy_from_slice(&dgm[..d_n]);
317        assert_eq!(
318            decode_datagram_capsule(&mixed[..n + d_n]),
319            Err(CapsuleError::UnknownCritical)
320        );
321    }
322
323    #[test]
324    fn overlong_varint_is_malformed() {
325        assert_eq!(decode_capsule(&[0x40, 0x00]), Err(CapsuleError::Malformed));
326        assert_eq!(decode_varint(&[0x00]), Ok((0, 1)));
327        assert_eq!(encode_varint(63, &mut [0u8; 1]), Ok(1));
328        assert_eq!(
329            encode_varint(64, &mut [0u8; 1]),
330            Err(CapsuleError::Capacity)
331        );
332    }
333
334    #[test]
335    fn empty_datagram_value_ok() {
336        let mut out = [0u8; 8];
337        let n = encode_datagram_capsule(&[], &mut out).unwrap();
338        assert_eq!(&out[..n], &[0x00, 0x00]);
339        assert_eq!(decode_datagram_capsule(&out[..n]).unwrap(), b"");
340    }
341
342    #[test]
343    fn does_not_claim_masque_or_http3() {
344        // Local framing of CSCP bytes. Not MASQUE, not HTTP/3, not Internet.
345        let mut out = [0u8; 32];
346        let n = encode_datagram_capsule(b"CSCP", &mut out).unwrap();
347        assert_eq!(decode_datagram_capsule(&out[..n]).unwrap(), b"CSCP");
348        assert_eq!(CAPSULE_DATAGRAM, 0x00);
349        assert_eq!(MAX_CAPSULE_VALUE, 1024);
350    }
351}