Skip to main content

qualia_core_db/net/qdnf/bearer/
fragment.rs

1//! PQ handshake fragmentation with admission **before** buffering.
2//!
3//! Bytes are charged against a per-message cap first. Only then may a fragment
4//! be copied into the bounded reassembly slot. Truncated wire is
5//! [`QdnfError::Truncated`] and does not copy. Interface loss is
6//! [`QdnfError::Closed`]; reconnect bumps generation so old tickets are useless.
7
8use crate::net::qdnf::errors::QdnfError;
9
10use super::mtu::{unfragmented_fit, MAX_QDNF_MTU, MIN_QDNF_MTU};
11
12/// `msg_id(4) || offset(2) || total(2) || frag_len(2)`.
13pub const FRAG_HDR_LEN: usize = 10;
14/// Hybrid handshake (ML-KEM-768 + X25519 + signatures) fits under this cap.
15pub const MAX_HANDSHAKE_BYTES: usize = 8192;
16pub const MAX_SESSIONS: usize = 2;
17pub const MAX_FRAGMENTS: usize = 8;
18pub const MAX_FRAME: usize = MAX_QDNF_MTU as usize;
19
20#[repr(C)]
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub struct FragmentHeader {
23    pub msg_id: u32,
24    pub offset: u16,
25    pub total: u16,
26    pub frag_len: u16,
27}
28
29/// Proof that `charged` bytes were admitted for `msg_id` at `generation`.
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct AdmitTicket {
32    generation: u64,
33    slot: u8,
34    msg_id: u32,
35    charged: u16,
36}
37
38struct Slot {
39    occupied: bool,
40    msg_id: u32,
41    total: u16,
42    admitted: u16,
43    received: u16,
44    buf: [u8; MAX_HANDSHAKE_BYTES],
45    filled: [bool; MAX_HANDSHAKE_BYTES],
46}
47
48impl Slot {
49    fn empty() -> Self {
50        Self {
51            occupied: false,
52            msg_id: 0,
53            total: 0,
54            admitted: 0,
55            received: 0,
56            buf: [0u8; MAX_HANDSHAKE_BYTES],
57            filled: [false; MAX_HANDSHAKE_BYTES],
58        }
59    }
60
61    fn clear(&mut self) {
62        *self = Self::empty();
63    }
64}
65
66pub struct HandshakeReassembler {
67    slots: [Slot; MAX_SESSIONS],
68    alive: bool,
69    generation: u64,
70}
71
72impl HandshakeReassembler {
73    /// Creates an empty fragment reassembler.
74    pub fn new() -> Self {
75        Self {
76            slots: [Slot::empty(), Slot::empty()],
77            alive: true,
78            generation: 1,
79        }
80    }
81
82    #[inline]
83    /// Generation.
84    pub const fn generation(&self) -> u64 {
85        self.generation
86    }
87
88    /// Occupied count.
89    pub fn occupied(&self) -> usize {
90        self.slots.iter().filter(|s| s.occupied).count()
91    }
92
93    /// Bytes buffered for message `msg_id`.
94    pub fn buffered_len(&self, msg_id: u32) -> usize {
95        self.slots
96            .iter()
97            .find(|s| s.occupied && s.msg_id == msg_id)
98            .map(|s| s.received as usize)
99            .unwrap_or(0)
100    }
101
102    /// Charge `frag_len` against the message cap **before** any copy.
103    pub fn admit(
104        &mut self,
105        msg_id: u32,
106        total: u16,
107        frag_len: u16,
108    ) -> Result<AdmitTicket, QdnfError> {
109        if !self.alive {
110            return Err(QdnfError::Closed);
111        }
112        if frag_len == 0 || total == 0 {
113            return Err(QdnfError::Malformed);
114        }
115        if total as usize > MAX_HANDSHAKE_BYTES {
116            return Err(QdnfError::Capacity);
117        }
118        let slot_idx = self.find_or_alloc(msg_id, total)?;
119        let slot = &mut self.slots[slot_idx];
120        if slot.total != total {
121            return Err(QdnfError::Conflict);
122        }
123        let new_admitted = slot
124            .admitted
125            .checked_add(frag_len)
126            .ok_or(QdnfError::Range)?;
127        if new_admitted as usize > slot.total as usize {
128            return Err(QdnfError::Capacity);
129        }
130        slot.admitted = new_admitted;
131        Ok(AdmitTicket {
132            generation: self.generation,
133            slot: slot_idx as u8,
134            msg_id,
135            charged: frag_len,
136        })
137    }
138
139    /// Copy `src` only after a matching ticket. Short `src` is Truncated.
140    pub fn buffer(
141        &mut self,
142        ticket: AdmitTicket,
143        offset: u16,
144        src: &[u8],
145        complete_out: &mut [u8],
146    ) -> Result<Option<usize>, QdnfError> {
147        if !self.alive {
148            return Err(QdnfError::Closed);
149        }
150        if ticket.generation != self.generation {
151            return Err(QdnfError::StaleGeneration);
152        }
153        let slot_idx = ticket.slot as usize;
154        if slot_idx >= MAX_SESSIONS {
155            return Err(QdnfError::Range);
156        }
157        let slot = &mut self.slots[slot_idx];
158        if !slot.occupied || slot.msg_id != ticket.msg_id {
159            return Err(QdnfError::Unauthorized);
160        }
161        if src.len() < ticket.charged as usize {
162            return Err(QdnfError::Truncated);
163        }
164        if src.len() > ticket.charged as usize {
165            return Err(QdnfError::Capacity);
166        }
167        let start = offset as usize;
168        let end = start
169            .checked_add(ticket.charged as usize)
170            .ok_or(QdnfError::Range)?;
171        if end > slot.total as usize {
172            return Err(QdnfError::Capacity);
173        }
174        let dest = &mut slot.buf[start..end];
175        dest.copy_from_slice(&src[..ticket.charged as usize]);
176        for i in start..end {
177            if !slot.filled[i] {
178                slot.filled[i] = true;
179                slot.received = slot.received.saturating_add(1);
180            }
181        }
182        if slot.received == slot.total {
183            let n = slot.total as usize;
184            if complete_out.len() < n {
185                return Err(QdnfError::Capacity);
186            }
187            complete_out[..n].copy_from_slice(&slot.buf[..n]);
188            slot.clear();
189            return Ok(Some(n));
190        }
191        Ok(None)
192    }
193
194    /// Drops reassembly state on interface loss.
195    pub fn lose_interface(&mut self) {
196        self.alive = false;
197        let mut i = 0usize;
198        while i < MAX_SESSIONS {
199            self.slots[i].clear();
200            i += 1;
201        }
202    }
203
204    /// New generation; prior tickets cannot buffer. Requires a prior loss.
205    pub fn reconnect(&mut self) -> Result<(), QdnfError> {
206        if self.alive {
207            return Err(QdnfError::Conflict);
208        }
209        self.generation = self
210            .generation
211            .checked_add(1)
212            .ok_or(QdnfError::StaleGeneration)?;
213        self.alive = true;
214        let mut i = 0usize;
215        while i < MAX_SESSIONS {
216            self.slots[i].clear();
217            i += 1;
218        }
219        Ok(())
220    }
221
222    fn find_or_alloc(&mut self, msg_id: u32, total: u16) -> Result<usize, QdnfError> {
223        let mut i = 0usize;
224        while i < MAX_SESSIONS {
225            if self.slots[i].occupied && self.slots[i].msg_id == msg_id {
226                return Ok(i);
227            }
228            i += 1;
229        }
230        let mut i = 0usize;
231        while i < MAX_SESSIONS {
232            if !self.slots[i].occupied {
233                self.slots[i].occupied = true;
234                self.slots[i].msg_id = msg_id;
235                self.slots[i].total = total;
236                self.slots[i].admitted = 0;
237                self.slots[i].received = 0;
238                return Ok(i);
239            }
240            i += 1;
241        }
242        Err(QdnfError::Capacity)
243    }
244}
245
246impl Default for HandshakeReassembler {
247    fn default() -> Self {
248        Self::new()
249    }
250}
251
252/// Encodes a fragment header + payload into the frame.
253pub fn encode_fragment(
254    header: FragmentHeader,
255    payload: &[u8],
256    out: &mut [u8],
257) -> Result<usize, QdnfError> {
258    if payload.len() != header.frag_len as usize {
259        return Err(QdnfError::Malformed);
260    }
261    let total = FRAG_HDR_LEN
262        .checked_add(payload.len())
263        .ok_or(QdnfError::Range)?;
264    if out.len() < total {
265        return Err(QdnfError::Capacity);
266    }
267    out[0..4].copy_from_slice(&header.msg_id.to_be_bytes());
268    out[4..6].copy_from_slice(&header.offset.to_be_bytes());
269    out[6..8].copy_from_slice(&header.total.to_be_bytes());
270    out[8..10].copy_from_slice(&header.frag_len.to_be_bytes());
271    out[10..total].copy_from_slice(payload);
272    Ok(total)
273}
274
275/// Decodes a fragment header, returning it with the payload slice.
276pub fn decode_fragment(src: &[u8]) -> Result<(FragmentHeader, &[u8]), QdnfError> {
277    if src.len() < FRAG_HDR_LEN {
278        return Err(QdnfError::Truncated);
279    }
280    let header = FragmentHeader {
281        msg_id: u32::from_be_bytes(src[0..4].try_into().unwrap()),
282        offset: u16::from_be_bytes([src[4], src[5]]),
283        total: u16::from_be_bytes([src[6], src[7]]),
284        frag_len: u16::from_be_bytes([src[8], src[9]]),
285    };
286    let need = FRAG_HDR_LEN
287        .checked_add(header.frag_len as usize)
288        .ok_or(QdnfError::Range)?;
289    if src.len() < need {
290        return Err(QdnfError::Truncated);
291    }
292    Ok((header, &src[FRAG_HDR_LEN..need]))
293}
294
295/// Decode, admit, then copy. Truncated or oversize wire never copies.
296///
297/// Admission is charged before [`HandshakeReassembler::buffer`]. A missing
298/// ticket cannot be skipped: there is no whole-datagram fallback here.
299pub fn admit_and_buffer(
300    reassembler: &mut HandshakeReassembler,
301    src: &[u8],
302    complete_out: &mut [u8],
303) -> Result<Option<usize>, QdnfError> {
304    let (header, body) = decode_fragment(src)?;
305    let ticket = reassembler.admit(header.msg_id, header.total, header.frag_len)?;
306    reassembler.buffer(ticket, header.offset, body, complete_out)
307}
308
309/// Payload bytes available per fragment under `mtu`.
310pub fn fragment_payload_mtu(mtu: u16) -> Result<u16, QdnfError> {
311    if mtu < MIN_QDNF_MTU {
312        return Err(QdnfError::Range);
313    }
314    let payload = (mtu as usize).saturating_sub(FRAG_HDR_LEN);
315    if payload == 0 {
316        return Err(QdnfError::Range);
317    }
318    Ok(payload as u16)
319}
320
321/// Split a PQ handshake into bounded frames. `payload_mtu` is bytes after the
322/// fragment header (use [`fragment_payload_mtu`]).
323pub fn split_handshake(
324    msg_id: u32,
325    payload: &[u8],
326    payload_mtu: u16,
327    out_frames: &mut [[u8; MAX_FRAME]; MAX_FRAGMENTS],
328    out_lens: &mut [usize; MAX_FRAGMENTS],
329) -> Result<usize, QdnfError> {
330    if payload.is_empty() {
331        return Err(QdnfError::Malformed);
332    }
333    if payload.len() > MAX_HANDSHAKE_BYTES {
334        return Err(QdnfError::Capacity);
335    }
336    if payload_mtu == 0 {
337        return Err(QdnfError::Range);
338    }
339    if payload.len() <= payload_mtu as usize {
340        unfragmented_fit(payload.len() + FRAG_HDR_LEN, MAX_QDNF_MTU)?;
341    }
342    let total = u16::try_from(payload.len()).map_err(|_| QdnfError::Capacity)?;
343    let mut offset = 0usize;
344    let mut n = 0usize;
345    while offset < payload.len() {
346        if n >= MAX_FRAGMENTS {
347            return Err(QdnfError::Capacity);
348        }
349        let remaining = payload.len() - offset;
350        let take = remaining.min(payload_mtu as usize);
351        let header = FragmentHeader {
352            msg_id,
353            offset: offset as u16,
354            total,
355            frag_len: take as u16,
356        };
357        let written = encode_fragment(header, &payload[offset..offset + take], &mut out_frames[n])?;
358        out_lens[n] = written;
359        offset += take;
360        n += 1;
361    }
362    Ok(n)
363}
364
365#[cfg(test)]
366mod tests {
367    use super::*;
368
369    #[test]
370    fn admit_before_buffer_rejects_without_copy() {
371        let mut r = HandshakeReassembler::new();
372        assert_eq!(r.admit(1, 9000, 100), Err(QdnfError::Capacity));
373        assert_eq!(r.occupied(), 0);
374        assert_eq!(r.buffered_len(1), 0);
375
376        let ticket = r.admit(2, 8, 4).unwrap();
377        assert_eq!(r.occupied(), 1);
378        assert_eq!(r.buffered_len(2), 0);
379
380        let mut out = [0u8; 16];
381        assert_eq!(
382            r.buffer(ticket, 0, &[1, 2], &mut out),
383            Err(QdnfError::Truncated)
384        );
385        assert_eq!(r.buffered_len(2), 0);
386
387        r.buffer(ticket, 0, &[9, 9, 9, 9], &mut out).unwrap();
388        assert_eq!(r.buffered_len(2), 4);
389    }
390
391    #[test]
392    fn truncated_header_is_truncated() {
393        assert_eq!(decode_fragment(&[0u8; 9]), Err(QdnfError::Truncated));
394        let header = FragmentHeader {
395            msg_id: 1,
396            offset: 0,
397            total: 4,
398            frag_len: 4,
399        };
400        let mut wire = [0u8; 14];
401        let n = encode_fragment(header, &[1, 2, 3, 4], &mut wire).unwrap();
402        assert_eq!(decode_fragment(&wire[..n - 1]), Err(QdnfError::Truncated));
403    }
404
405    #[test]
406    fn oversize_unfragmented_is_capacity() {
407        assert_eq!(
408            unfragmented_fit(MAX_HANDSHAKE_BYTES, MIN_QDNF_MTU),
409            Err(QdnfError::Capacity)
410        );
411    }
412
413    #[test]
414    fn split_and_reassemble_pq_share() {
415        let mut payload = [0u8; 1216];
416        payload[0] = 0x11;
417        payload[1215] = 0x22;
418        let mtu = fragment_payload_mtu(MIN_QDNF_MTU).unwrap();
419        let mut frames = [[0u8; MAX_FRAME]; MAX_FRAGMENTS];
420        let mut lens = [0usize; MAX_FRAGMENTS];
421        let n = split_handshake(7, &payload, mtu, &mut frames, &mut lens).unwrap();
422        assert!(n >= 1);
423        let mut r = HandshakeReassembler::new();
424        let mut out = [0u8; 2048];
425        let mut complete = None;
426        for i in 0..n {
427            let (hdr, body) = decode_fragment(&frames[i][..lens[i]]).unwrap();
428            let ticket = r.admit(hdr.msg_id, hdr.total, hdr.frag_len).unwrap();
429            complete = r.buffer(ticket, hdr.offset, body, &mut out).unwrap();
430        }
431        assert_eq!(complete, Some(1216));
432        assert_eq!(&out[..1216], &payload);
433        assert_eq!(r.occupied(), 0);
434    }
435
436    #[test]
437    fn interface_loss_is_closed_and_reconnect_needs_new_admission() {
438        let mut r = HandshakeReassembler::new();
439        let ticket = r.admit(1, 4, 4).unwrap();
440        r.lose_interface();
441        assert_eq!(r.admit(1, 4, 4), Err(QdnfError::Closed));
442        let mut out = [0u8; 4];
443        assert_eq!(
444            r.buffer(ticket, 0, &[1, 2, 3, 4], &mut out),
445            Err(QdnfError::Closed)
446        );
447        assert_eq!(r.buffered_len(1), 0);
448        r.reconnect().unwrap();
449        assert_eq!(
450            r.buffer(ticket, 0, &[1, 2, 3, 4], &mut out),
451            Err(QdnfError::StaleGeneration)
452        );
453        let ticket2 = r.admit(1, 4, 4).unwrap();
454        assert_eq!(
455            r.buffer(ticket2, 0, &[1, 2, 3, 4], &mut out).unwrap(),
456            Some(4)
457        );
458        assert_eq!(&out[..4], &[1, 2, 3, 4]);
459    }
460
461    #[test]
462    fn third_concurrent_session_is_capacity() {
463        let mut r = HandshakeReassembler::new();
464        r.admit(1, 8, 4).unwrap();
465        r.admit(2, 8, 4).unwrap();
466        assert_eq!(r.admit(3, 8, 4), Err(QdnfError::Capacity));
467        assert_eq!(r.occupied(), 2);
468        assert_eq!(r.buffered_len(3), 0);
469    }
470
471    #[test]
472    fn admit_and_buffer_completes_and_oversize_total_is_capacity() {
473        let mut payload = [0u8; 24];
474        payload[0] = 0xA1;
475        payload[23] = 0xA2;
476        let mut frames = [[0u8; MAX_FRAME]; MAX_FRAGMENTS];
477        let mut lens = [0usize; MAX_FRAGMENTS];
478        let n = split_handshake(3, &payload, 16, &mut frames, &mut lens).unwrap();
479        assert!(n >= 2);
480        let mut r = HandshakeReassembler::new();
481        let mut out = [0u8; 32];
482        let mut complete = None;
483        for i in 0..n {
484            complete = admit_and_buffer(&mut r, &frames[i][..lens[i]], &mut out).unwrap();
485        }
486        assert_eq!(complete, Some(24));
487        assert_eq!(&out[..24], &payload);
488        assert_eq!(r.occupied(), 0);
489
490        let mut closed = HandshakeReassembler::new();
491        let too_big = (MAX_HANDSHAKE_BYTES as u16).saturating_add(1);
492        assert_eq!(closed.admit(9, too_big, 8), Err(QdnfError::Capacity));
493        assert_eq!(closed.occupied(), 0);
494        assert_eq!(closed.buffered_len(9), 0);
495        assert_eq!(
496            admit_and_buffer(&mut closed, &[0u8; 4], &mut out),
497            Err(QdnfError::Truncated)
498        );
499        assert_eq!(closed.buffered_len(9), 0);
500    }
501}