Skip to main content

qualia_core_db/net/qdnf/session/
paths.rs

1//! Bounded dial races for QSession (NET-05.10 / RT-03.03 partial).
2//!
3//! At most [`MAX_ACTIVE_PATHS`] paths may be [`PathState::Active`]. Up to
4//! [`MAX_RACE_CANDIDATES`] Racing+Active slots may be occupied; a fourth Active
5//! is [`QdnfError::Capacity`]. Losing and late Racing attempts close and free
6//! the slot. Application [`crate::net::qdnf::types::OperationId`] is not a path
7//! id (NET-05.05 partial). Compat-carrier duplicate recovery stays off
8//! (NET-05.11).
9
10use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::types::Generation;
12
13/// Negotiated multipath ceiling (QSession max paths = 3).
14pub const MAX_ACTIVE_PATHS: usize = 3;
15/// Collected race candidates; only [`MAX_ACTIVE_PATHS`] may become Active.
16pub const MAX_RACE_CANDIDATES: usize = 8;
17
18#[repr(u8)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum PathState {
21    Racing = 1,
22    Active = 2,
23    Losing = 3,
24    Closed = 4,
25}
26
27#[repr(C)]
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub struct PathSlot {
30    pub id: u8,
31    pub generation: u64,
32    pub state: PathState,
33    pub proven: bool,
34}
35
36/// Generation-bearing path mutation handle. Not a budget or permit token.
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38pub struct PathHandle {
39    slot: u8,
40    generation: Generation,
41}
42
43impl PathHandle {
44    #[inline]
45    /// Slot.
46    pub const fn slot(self) -> u8 {
47        self.slot
48    }
49
50    #[inline]
51    /// Generation.
52    pub const fn generation(self) -> Generation {
53        self.generation
54    }
55}
56
57/// `PathHandle::path_handle_is_budget_token`.
58pub const fn path_handle_is_budget_token() -> bool {
59    false
60}
61
62/// Mutate `handle`'s slot. Stale generation → [`QdnfError::StaleGeneration`].
63/// Promoting to [`PathState::Active`] requires attested reachability.
64pub fn mutate_path(
65    table: &mut PathTable,
66    handle: PathHandle,
67    next: PathState,
68) -> Result<PathHandle, QdnfError> {
69    table.mutate(handle, next)
70}
71
72/// Eight-slot table. Occupied entries are Racing, Active, or Losing.
73pub struct PathTable {
74    slots: [Option<PathSlot>; MAX_RACE_CANDIDATES],
75}
76
77impl PathTable {
78    /// Creates a default `PathTable`.
79    pub const fn new() -> Self {
80        Self {
81            slots: [None; MAX_RACE_CANDIDATES],
82        }
83    }
84
85    /// Open a Racing candidate. Occupied Racing+Active+Losing at
86    /// [`MAX_RACE_CANDIDATES`] → [`QdnfError::Capacity`].
87    pub fn start_race(&mut self, generation: u64) -> Result<u8, QdnfError> {
88        if self.occupied_count() >= MAX_RACE_CANDIDATES {
89            return Err(QdnfError::Capacity);
90        }
91        let idx = self.free_index().ok_or(QdnfError::Capacity)?;
92        let id = idx as u8;
93        self.slots[idx] = Some(PathSlot {
94            id,
95            generation,
96            state: PathState::Racing,
97            proven: false,
98        });
99        Ok(id)
100    }
101
102    /// Path handle for `id`; error when absent.
103    pub fn handle_of(&self, id: u8) -> Result<PathHandle, QdnfError> {
104        let slot = self.get(id).ok_or(QdnfError::Closed)?;
105        Ok(PathHandle {
106            slot: slot.id,
107            generation: Generation(slot.generation),
108        })
109    }
110
111    /// Authenticated reachability proof already verified by the caller.
112    /// Mismatched generation → [`QdnfError::StaleGeneration`].
113    pub fn attest_reachability(&mut self, handle: PathHandle) -> Result<(), QdnfError> {
114        let idx = self.index_of(handle.slot)?;
115        let slot = self.slots[idx].as_mut().ok_or(QdnfError::Closed)?;
116        if slot.generation != handle.generation.0 {
117            return Err(QdnfError::StaleGeneration);
118        }
119        slot.proven = true;
120        Ok(())
121    }
122
123    /// Transitions `handle` to `next` state; returns the new handle.
124    pub fn mutate(&mut self, handle: PathHandle, next: PathState) -> Result<PathHandle, QdnfError> {
125        let idx = self.index_of(handle.slot)?;
126        {
127            let slot = self.slots[idx].as_ref().ok_or(QdnfError::Closed)?;
128            if slot.generation != handle.generation.0 {
129                return Err(QdnfError::StaleGeneration);
130            }
131            if next == PathState::Active {
132                if !slot.proven {
133                    return Err(QdnfError::Unauthorized);
134                }
135                if slot.state != PathState::Active && self.active_count() >= MAX_ACTIVE_PATHS {
136                    return Err(QdnfError::Capacity);
137                }
138            }
139        }
140        if matches!(next, PathState::Closed | PathState::Losing) {
141            let new_gen = Generation(handle.generation.0).next()?;
142            self.slots[idx] = None;
143            return Ok(PathHandle {
144                slot: handle.slot,
145                generation: new_gen,
146            });
147        }
148        let slot = self.slots[idx].as_mut().ok_or(QdnfError::Closed)?;
149        let new_gen = Generation(slot.generation).next()?;
150        slot.generation = new_gen.0;
151        slot.state = next;
152        Ok(PathHandle {
153            slot: handle.slot,
154            generation: new_gen,
155        })
156    }
157
158    /// Promote a Racing slot to Active by `(slot_id, generation)` equality (`R04`),
159    /// requiring attested reachability so stale slot IDs fail closed.
160    pub fn activate_generation(&mut self, id: u8, generation: u64) -> Result<PathHandle, QdnfError> {
161        let idx = self.index_of(id)?;
162        let slot = self.slots[idx].as_ref().ok_or(QdnfError::Closed)?;
163        if slot.id != id || slot.generation != generation {
164            return Err(QdnfError::StaleGeneration);
165        }
166        self.mutate(
167            PathHandle {
168                slot: id,
169                generation: Generation(generation),
170            },
171            PathState::Active,
172        )
173    }
174
175    /// Promote a Racing slot to Active. A fourth Active is Capacity.
176    pub fn mark_active(&mut self, id: u8) -> Result<(), QdnfError> {
177        let idx = self.index_of(id)?;
178        let state = self.slots[idx].ok_or(QdnfError::Closed)?.state;
179        match state {
180            PathState::Active => Ok(()),
181            PathState::Closed | PathState::Losing => Err(QdnfError::Closed),
182            PathState::Racing => {
183                if self.active_count() >= MAX_ACTIVE_PATHS {
184                    return Err(QdnfError::Capacity);
185                }
186                let slot = self.slots[idx].as_mut().ok_or(QdnfError::Closed)?;
187                slot.state = PathState::Active;
188                Ok(())
189            }
190        }
191    }
192
193    /// Losing/late attempts: Racing or Losing → Closed, slot freed.
194    /// Active may be retired the same way so a later race can win.
195    pub fn lose_and_cleanup(&mut self, id: u8) -> Result<(), QdnfError> {
196        let idx = self.index_of(id)?;
197        let slot = self.slots[idx].as_mut().ok_or(QdnfError::Closed)?;
198        match slot.state {
199            PathState::Closed => Err(QdnfError::Closed),
200            PathState::Racing | PathState::Losing | PathState::Active => {
201                slot.state = PathState::Losing;
202                self.slots[idx] = None;
203                Ok(())
204            }
205        }
206    }
207
208    /// Same as [`Self::lose_and_cleanup`], but the caller must present the
209    /// generation stored on the slot. Mismatch → [`QdnfError::StaleGeneration`].
210    pub fn lose_generation(&mut self, id: u8, generation: u64) -> Result<(), QdnfError> {
211        let idx = self.index_of(id)?;
212        let slot = self.slots[idx].as_ref().ok_or(QdnfError::Closed)?;
213        if slot.generation != generation {
214            return Err(QdnfError::StaleGeneration);
215        }
216        self.lose_and_cleanup(id)
217    }
218
219    /// Active paths.
220    pub fn active_count(&self) -> usize {
221        let mut n = 0usize;
222        let mut i = 0usize;
223        while i < MAX_RACE_CANDIDATES {
224            if let Some(slot) = self.slots[i] {
225                if slot.state == PathState::Active {
226                    n += 1;
227                }
228            }
229            i += 1;
230        }
231        n
232    }
233
234    /// NET-05.05 partial: the application operation id is not the path id.
235    pub const fn preserve_operation_id_across_path_change() -> bool {
236        true
237    }
238
239    /// NET-05.11: reliable-carrier compatibility disables duplicate recovery.
240    pub const fn duplicate_recovery_on_compat_carrier() -> bool {
241        false
242    }
243
244    /// `PathTable::get`.
245    pub fn get(&self, id: u8) -> Option<&PathSlot> {
246        let idx = id as usize;
247        if idx >= MAX_RACE_CANDIDATES {
248            return None;
249        }
250        self.slots[idx].as_ref()
251    }
252
253    fn occupied_count(&self) -> usize {
254        let mut n = 0usize;
255        let mut i = 0usize;
256        while i < MAX_RACE_CANDIDATES {
257            if let Some(slot) = self.slots[i] {
258                if slot.state != PathState::Closed {
259                    n += 1;
260                }
261            }
262            i += 1;
263        }
264        n
265    }
266
267    fn free_index(&self) -> Option<usize> {
268        let mut i = 0usize;
269        while i < MAX_RACE_CANDIDATES {
270            match self.slots[i] {
271                None => return Some(i),
272                Some(slot) if slot.state == PathState::Closed => return Some(i),
273                _ => {}
274            }
275            i += 1;
276        }
277        None
278    }
279
280    fn index_of(&self, id: u8) -> Result<usize, QdnfError> {
281        let idx = id as usize;
282        if idx >= MAX_RACE_CANDIDATES {
283            return Err(QdnfError::Range);
284        }
285        Ok(idx)
286    }
287}
288
289impl Default for PathTable {
290    fn default() -> Self {
291        Self::new()
292    }
293}
294
295#[cfg(test)]
296mod tests {
297    use super::*;
298    use crate::net::qdnf::types::Generation;
299
300    #[test]
301    fn fourth_mark_active_is_capacity() {
302        let mut table = PathTable::new();
303        let a = table.start_race(1).unwrap();
304        let b = table.start_race(1).unwrap();
305        let c = table.start_race(1).unwrap();
306        let d = table.start_race(1).unwrap();
307        table.mark_active(a).unwrap();
308        table.mark_active(b).unwrap();
309        table.mark_active(c).unwrap();
310        assert_eq!(table.active_count(), MAX_ACTIVE_PATHS);
311        assert_eq!(table.mark_active(d), Err(QdnfError::Capacity));
312        assert_eq!(table.get(d).unwrap().state, PathState::Racing);
313    }
314
315    #[test]
316    fn lose_and_cleanup_frees_slot_for_new_race() {
317        let mut table = PathTable::new();
318        let mut ids = [0u8; MAX_RACE_CANDIDATES];
319        let mut i = 0usize;
320        while i < MAX_RACE_CANDIDATES {
321            ids[i] = table.start_race(10 + i as u64).unwrap();
322            i += 1;
323        }
324        assert_eq!(table.start_race(99), Err(QdnfError::Capacity));
325        table.lose_and_cleanup(ids[0]).unwrap();
326        let reused = table.start_race(100).unwrap();
327        assert_eq!(reused, ids[0]);
328        assert_eq!(table.get(reused).unwrap().generation, 100);
329        assert_eq!(table.get(reused).unwrap().state, PathState::Racing);
330    }
331
332    #[test]
333    fn lose_generation_stale_is_rejected() {
334        let mut table = PathTable::new();
335        let id = table.start_race(7).unwrap();
336        assert_eq!(
337            table.lose_generation(id, 8),
338            Err(QdnfError::StaleGeneration)
339        );
340        assert_eq!(table.get(id).unwrap().state, PathState::Racing);
341        table.lose_generation(id, 7).unwrap();
342        assert!(table.get(id).is_none());
343    }
344
345    #[test]
346    fn late_racing_attempt_closes_after_active_winner() {
347        let mut table = PathTable::new();
348        let winner = table.start_race(1).unwrap();
349        let late = table.start_race(1).unwrap();
350        table.mark_active(winner).unwrap();
351        table.lose_and_cleanup(late).unwrap();
352        assert_eq!(table.active_count(), 1);
353        assert!(table.get(late).is_none());
354    }
355
356    #[test]
357    fn preserve_operation_id_across_path_change() {
358        assert!(PathTable::preserve_operation_id_across_path_change());
359    }
360
361    #[test]
362    fn duplicate_recovery_on_compat_carrier_is_disabled() {
363        assert!(!PathTable::duplicate_recovery_on_compat_carrier());
364    }
365
366    #[test]
367    fn stale_path_handle_is_stale_generation() {
368        let mut table = PathTable::new();
369        let id = table.start_race(4).unwrap();
370        let h = table.handle_of(id).unwrap();
371        table.attest_reachability(h).unwrap();
372        let fresh = mutate_path(&mut table, h, PathState::Racing).unwrap();
373        assert_eq!(
374            mutate_path(&mut table, h, PathState::Racing),
375            Err(QdnfError::StaleGeneration)
376        );
377        assert_eq!(fresh.generation(), Generation(5));
378        assert!(!path_handle_is_budget_token());
379        assert_eq!(
380            table.attest_reachability(h),
381            Err(QdnfError::StaleGeneration)
382        );
383    }
384
385    #[test]
386    fn coupled_multipath_does_not_multiply_window() {
387        use crate::net::qdnf::session::congestion::PathCcTable;
388        let mut table = PathTable::new();
389        let a = table.start_race(1).unwrap();
390        let b = table.start_race(1).unwrap();
391        table.mark_active(a).unwrap();
392        table.mark_active(b).unwrap();
393        let ha = table.handle_of(a).unwrap();
394        let hb = table.handle_of(b).unwrap();
395        let mut coupled = PathCcTable::new(500);
396        assert!(!coupled.independent_bottleneck);
397        coupled.attach(ha).unwrap();
398        coupled.attach(hb).unwrap();
399        coupled.send(ha, 1, 400).unwrap();
400        assert_eq!(coupled.send(hb, 2, 200), Err(QdnfError::BudgetExhausted));
401        assert!(coupled.total_in_flight() <= 500);
402        let mut independent = PathCcTable::new(500);
403        independent.independent_bottleneck = true;
404        independent.attach(ha).unwrap();
405        independent.attach(hb).unwrap();
406        independent.send(ha, 1, 500).unwrap();
407        independent.send(hb, 2, 500).unwrap();
408        assert_eq!(independent.total_in_flight(), 1000);
409    }
410
411    #[test]
412    fn mutate_active_requires_reachability_proof() {
413        let mut table = PathTable::new();
414        let id = table.start_race(1).unwrap();
415        let h = table.handle_of(id).unwrap();
416        assert_eq!(
417            mutate_path(&mut table, h, PathState::Active),
418            Err(QdnfError::Unauthorized)
419        );
420        table.attest_reachability(h).unwrap();
421        let active = mutate_path(&mut table, h, PathState::Active).unwrap();
422        assert_eq!(table.get(id).unwrap().state, PathState::Active);
423        assert_eq!(active.generation(), Generation(2));
424    }
425
426    #[test]
427    fn r04_activate_generation_requires_slot_and_generation_equality() {
428        let mut table = PathTable::new();
429        let id = table.start_race(10).unwrap();
430        let h = table.handle_of(id).unwrap();
431        table.attest_reachability(h).unwrap();
432        assert_eq!(
433            table.activate_generation(id, 9),
434            Err(QdnfError::StaleGeneration)
435        );
436        let next = table.activate_generation(id, 10).unwrap();
437        assert_eq!(next.generation(), Generation(11));
438        assert_eq!(
439            table.activate_generation(id, 10),
440            Err(QdnfError::StaleGeneration)
441        );
442    }
443}