Skip to main content

qualia_core_db/net/qdnf/session/
loss.rs

1//! ACK ranges, PTO backoff, and sent-packet history (NET-05.08 partial).
2//!
3//! At most eight inclusive ACK ranges. Retransmits use fresh packet numbers
4//! (`reuse_packet_number_on_retransmit` is false). Sent history is 32 in-flight
5//! slots. Independent of `packet.rs` (plain `u64` packet numbers). Packages
6//! remain open.
7
8use crate::net::qdnf::errors::QdnfError;
9
10/// Duplicate of credit.rs — do not import that module from here.
11pub const MAX_ACK_RANGES: usize = 8;
12/// In-flight packet-number slots (sent history bound).
13pub const SENT_HISTORY: usize = 32;
14/// `pto_count` saturates here: `pto_us = rtt_us * 2^min(pto_count, cap)`.
15pub const PTO_BACKOFF_CAP: u32 = 8;
16
17#[repr(C)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub struct AckRange {
20    pub start: u64, // inclusive
21    pub end: u64,   // inclusive, end >= start
22}
23
24pub struct AckFrame {
25    ranges: [AckRange; MAX_ACK_RANGES],
26    count: u8,
27    pub delay_us: u32,
28}
29
30impl AckFrame {
31    /// Creates a default `AckFrame`.
32    pub const fn new() -> Self {
33        Self {
34            ranges: [AckRange { start: 0, end: 0 }; MAX_ACK_RANGES],
35            count: 0,
36            delay_us: 0,
37        }
38    }
39
40    /// Ack ranges carried in the frame.
41    pub fn range_count(&self) -> usize {
42        self.count as usize
43    }
44
45    /// Range `i`, or `None` when out of bounds.
46    pub fn range_at(&self, i: usize) -> Option<AckRange> {
47        if i < self.range_count() {
48            Some(self.ranges[i])
49        } else {
50            None
51        }
52    }
53
54    /// `true` when packet number `pn` is covered by any range.
55    pub fn contains(&self, pn: u64) -> bool {
56        let n = self.range_count();
57        let mut i = 0usize;
58        while i < n {
59            let other = self.ranges[i];
60            if pn >= other.start && pn <= other.end {
61                return true;
62            }
63            i += 1;
64        }
65        false
66    }
67
68    /// Insert inclusive range. Empty (`end < start`) → [`QdnfError::Range`].
69    /// Overlap with an existing range (`end >= other.start && start <= other.end`)
70    /// → [`QdnfError::Overlap`] (no silent merge). Ninth disjoint range →
71    /// [`QdnfError::Capacity`].
72    pub fn insert_range(&mut self, start: u64, end: u64) -> Result<(), QdnfError> {
73        if end < start {
74            return Err(QdnfError::Range);
75        }
76        let n = self.range_count();
77        let mut i = 0;
78        while i < n {
79            let other = self.ranges[i];
80            if end >= other.start && start <= other.end {
81                return Err(QdnfError::Overlap);
82            }
83            i += 1;
84        }
85        if n >= MAX_ACK_RANGES {
86            return Err(QdnfError::Capacity);
87        }
88        self.ranges[n] = AckRange { start, end };
89        self.count = (n as u8).saturating_add(1);
90        Ok(())
91    }
92}
93
94/// Thirty-two slots of in-flight packet numbers.
95pub struct SentTable {
96    slots: [Option<u64>; SENT_HISTORY],
97}
98
99impl SentTable {
100    /// Creates a default `SentTable`.
101    pub const fn new() -> Self {
102        Self {
103            slots: [None; SENT_HISTORY],
104        }
105    }
106
107    /// Record a newly sent `pn`. Duplicate occupied `pn` → [`QdnfError::Replay`].
108    /// Full table → [`QdnfError::Capacity`].
109    pub fn record_send(&mut self, pn: u64) -> Result<(), QdnfError> {
110        let mut free: Option<usize> = None;
111        let mut i = 0;
112        while i < SENT_HISTORY {
113            match self.slots[i] {
114                Some(occupied) if occupied == pn => return Err(QdnfError::Replay),
115                Some(_) => {}
116                None => {
117                    if free.is_none() {
118                        free = Some(i);
119                    }
120                }
121            }
122            i += 1;
123        }
124        let idx = free.ok_or(QdnfError::Capacity)?;
125        self.slots[idx] = Some(pn);
126        Ok(())
127    }
128
129    /// ACK a `pn` previously recorded. Unknown `pn` → [`QdnfError::Malformed`].
130    pub fn on_ack(&mut self, pn: u64) -> Result<(), QdnfError> {
131        let mut i = 0;
132        while i < SENT_HISTORY {
133            if self.slots[i] == Some(pn) {
134                self.slots[i] = None;
135                return Ok(());
136            }
137            i += 1;
138        }
139        Err(QdnfError::Malformed)
140    }
141
142    /// Packets currently in flight.
143    pub fn in_flight_count(&self) -> usize {
144        let mut n = 0;
145        let mut i = 0;
146        while i < SENT_HISTORY {
147            if self.slots[i].is_some() {
148                n += 1;
149            }
150            i += 1;
151        }
152        n
153    }
154
155    /// Packet number at table index `i`.
156    pub fn packet_at(&self, i: usize) -> Option<u64> {
157        if i < SENT_HISTORY {
158            self.slots[i]
159        } else {
160            None
161        }
162    }
163}
164
165/// PTO microseconds: `rtt_us * 2^pto_count` with `pto_count` capped at
166/// [`PTO_BACKOFF_CAP`]. Overflow or `rtt_us == 0` → [`QdnfError::Range`].
167pub fn pto_us(rtt_us: u64, pto_count: u32) -> Result<u64, QdnfError> {
168    if rtt_us == 0 {
169        return Err(QdnfError::Range);
170    }
171    let exp = pto_count.min(PTO_BACKOFF_CAP);
172    let factor = 1u64.checked_shl(exp).ok_or(QdnfError::Range)?;
173    rtt_us.checked_mul(factor).ok_or(QdnfError::Range)
174}
175
176/// Honest invariant probe: `false` — QDNF never reuses packet numbers on retransmit.
177pub fn reuse_packet_number_on_retransmit() -> bool {
178    false
179}
180
181/// Maximum ack ranges per frame (`MAX_ACK_RANGES`).
182pub fn ack_range_cap() -> usize {
183    MAX_ACK_RANGES
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    #[test]
191    fn eight_disjoint_ranges_ok_ninth_capacity() {
192        let mut ack = AckFrame::new();
193        let mut i = 0u64;
194        while i < MAX_ACK_RANGES as u64 {
195            let start = i * 10;
196            ack.insert_range(start, start + 1)
197                .expect("eight disjoint ranges fit");
198            i += 1;
199        }
200        assert_eq!(ack.range_count(), MAX_ACK_RANGES);
201        assert_eq!(ack.insert_range(800, 801), Err(QdnfError::Capacity));
202        assert_eq!(ack.range_count(), MAX_ACK_RANGES);
203    }
204
205    #[test]
206    fn overlapping_insert_is_overlap_count_unchanged() {
207        let mut ack = AckFrame::new();
208        ack.insert_range(10, 20).expect("first range");
209        assert_eq!(ack.range_count(), 1);
210        assert_eq!(ack.insert_range(15, 25), Err(QdnfError::Overlap));
211        assert_eq!(ack.range_count(), 1);
212        assert_eq!(ack.insert_range(10, 20), Err(QdnfError::Overlap));
213        assert_eq!(ack.range_count(), 1);
214        assert_eq!(ack.insert_range(20, 21), Err(QdnfError::Overlap));
215        assert_eq!(ack.range_count(), 1);
216    }
217
218    #[test]
219    fn empty_range_is_range_error() {
220        let mut ack = AckFrame::new();
221        assert_eq!(ack.insert_range(5, 4), Err(QdnfError::Range));
222        assert_eq!(ack.range_count(), 0);
223        ack.insert_range(5, 5).expect("singleton inclusive is live");
224        assert_eq!(ack.range_count(), 1);
225    }
226
227    #[test]
228    fn record_send_thirty_two_ok_thirty_third_capacity() {
229        let mut sent = SentTable::new();
230        let mut i = 0u64;
231        while i < SENT_HISTORY as u64 {
232            sent.record_send(i).expect("32 in-flight slots");
233            i += 1;
234        }
235        assert_eq!(sent.in_flight_count(), SENT_HISTORY);
236        assert_eq!(sent.record_send(99), Err(QdnfError::Capacity));
237        assert_eq!(sent.in_flight_count(), SENT_HISTORY);
238        assert_eq!(sent.record_send(0), Err(QdnfError::Replay));
239    }
240
241    #[test]
242    fn on_ack_unknown_malformed_known_decreases_in_flight() {
243        let mut sent = SentTable::new();
244        sent.record_send(7).expect("record");
245        sent.record_send(8).expect("record");
246        assert_eq!(sent.in_flight_count(), 2);
247        assert_eq!(sent.on_ack(99), Err(QdnfError::Malformed));
248        assert_eq!(sent.in_flight_count(), 2);
249        sent.on_ack(7).expect("ack recorded pn");
250        assert_eq!(sent.in_flight_count(), 1);
251        assert_eq!(sent.on_ack(7), Err(QdnfError::Malformed));
252        assert_eq!(sent.in_flight_count(), 1);
253    }
254
255    #[test]
256    fn pto_backoff_and_unknown_rtt() {
257        assert_eq!(pto_us(1000, 0), Ok(1000));
258        assert_eq!(pto_us(1000, 1), Ok(2000));
259        assert_eq!(pto_us(0, 0), Err(QdnfError::Range));
260        assert_eq!(pto_us(1000, PTO_BACKOFF_CAP), Ok(1000u64 * 256));
261        assert_eq!(pto_us(1000, PTO_BACKOFF_CAP + 1), Ok(1000u64 * 256));
262        assert_eq!(pto_us(u64::MAX, 1), Err(QdnfError::Range));
263    }
264
265    #[test]
266    fn fresh_packet_numbers_and_ack_range_cap() {
267        assert!(!reuse_packet_number_on_retransmit());
268        assert_eq!(ack_range_cap(), 8);
269        assert_eq!(ack_range_cap(), MAX_ACK_RANGES);
270    }
271}