qualia_core_db/net/peer/fabric/
capsule.rs1pub const CAPSULE_DATAGRAM: u64 = 0x00;
29
30pub 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
128fn 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
145pub fn capsule_span(bytes: &[u8]) -> Result<usize, CapsuleError> {
148 let (_, header, vlen) = parse_frame(bytes)?;
149 Ok(header + vlen)
150}
151
152pub 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
168pub fn encode_datagram_capsule(payload: &[u8], out: &mut [u8]) -> Result<usize, CapsuleError> {
170 encode_capsule(CAPSULE_DATAGRAM, payload, out)
171}
172
173pub 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
185pub 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 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 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 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}