Skip to main content

qualia_core_db/net/qdnf/route/
overlap.rs

1//! Old/new forwarding-generation overlap. Incomplete tables never go live.
2
3use crate::net::qdnf::errors::QdnfError;
4
5use super::forwarding::ForwardingGeneration;
6use super::spf::SpfTable;
7
8/// Charged old generation plus the candidate new table. Never a third live gen.
9pub const MAX_LIVE_GENERATIONS: usize = 2;
10
11/// Pair of immutable forwarding generations with a reader charge on `old`.
12#[repr(C)]
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub struct GenerationPair {
15    old: ForwardingGeneration,
16    new: ForwardingGeneration,
17    old_readers: u8,
18}
19
20impl GenerationPair {
21    /// Empty value.
22    pub const fn empty() -> Self {
23        Self {
24            old: ForwardingGeneration::empty(0),
25            new: ForwardingGeneration::empty(0),
26            old_readers: 0,
27        }
28    }
29
30    /// QDNF has no default-route or LIG/DNS fallback.
31    pub const fn has_default_route() -> bool {
32        false
33    }
34
35    /// Install a computed table as `new`. Incomplete (`nodes == 0`) does not publish.
36    pub fn install_new(&mut self, table: SpfTable, id: u64) -> Result<(), QdnfError> {
37        Self::cancelled_computation_cannot_publish(&table)?;
38        let mut gen = ForwardingGeneration::empty(id);
39        gen.publish(table)?;
40        self.new = gen;
41        Ok(())
42    }
43
44    /// Atomic: unpublished `new` cannot activate. If `old_readers == 0`, swap
45    /// `new` → `old`. If readers remain, keep `old` until `release_old()`.
46    pub fn activate_new(&mut self) -> Result<(), QdnfError> {
47        if !self.new.published {
48            return Err(QdnfError::Incomplete);
49        }
50        if self.old_readers == 0 {
51            self.old = self.new;
52            self.new = ForwardingGeneration::empty(0);
53        }
54        Ok(())
55    }
56
57    /// Charge a reader on the retained old generation. Saturates at 255 → Capacity.
58    pub fn retain_old(&mut self) -> Result<(), QdnfError> {
59        match self.old_readers.checked_add(1) {
60            Some(n) => {
61                self.old_readers = n;
62                Ok(())
63            }
64            None => Err(QdnfError::Capacity),
65        }
66    }
67
68    /// Drop one old-generation reader. Zero charges → DoubleRelease.
69    pub fn release_old(&mut self) -> Result<(), QdnfError> {
70        if self.old_readers == 0 {
71            return Err(QdnfError::DoubleRelease);
72        }
73        self.old_readers -= 1;
74        if self.old_readers == 0 && self.new.published {
75            self.old = self.new;
76            self.new = ForwardingGeneration::empty(0);
77        }
78        Ok(())
79    }
80
81    /// Prefer published `new`; else published `old`; else Incomplete.
82    pub fn lookup(&self, dest_node: u8) -> Result<u8, QdnfError> {
83        if self.new.published {
84            return self.new.lookup_next(dest_node);
85        }
86        if self.old.published {
87            return self.old.lookup_next(dest_node);
88        }
89        Err(QdnfError::Incomplete)
90    }
91
92    /// Cancelled / empty computation cannot publish a live generation.
93    pub fn cancelled_computation_cannot_publish(table: &SpfTable) -> Result<(), QdnfError> {
94        if table.nodes == 0 {
95            Err(QdnfError::Incomplete)
96        } else {
97            Ok(())
98        }
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105    use crate::net::qdnf::route::forwarding::{decrement_hop, require_adjacency};
106    use crate::net::qdnf::route::spf::{compute_spf, LinkMetric};
107    use crate::net::qdnf::types::LinkId;
108
109    fn abc_links() -> [LinkMetric; 2] {
110        [
111            LinkMetric {
112                from: 0,
113                to: 1,
114                cost: 1,
115                bidirectional: true,
116            },
117            LinkMetric {
118                from: 1,
119                to: 2,
120                cost: 1,
121                bidirectional: true,
122            },
123        ]
124    }
125
126    fn compute_abc() -> SpfTable {
127        let mut table = SpfTable::EMPTY;
128        compute_spf(0, &abc_links(), &mut table).expect("A-B-C SPF");
129        table
130    }
131
132    #[test]
133    fn unpublished_empty_cannot_activate() {
134        let mut pair = GenerationPair::empty();
135        assert_eq!(pair.activate_new(), Err(QdnfError::Incomplete));
136        assert_eq!(pair.lookup(2), Err(QdnfError::Incomplete));
137    }
138
139    #[test]
140    fn install_abc_lookup_dest_two_is_next_hop_one() {
141        let mut pair = GenerationPair::empty();
142        pair.install_new(compute_abc(), 1).unwrap();
143        assert_eq!(pair.lookup(2), Ok(1));
144    }
145
146    #[test]
147    fn retain_old_then_activate_new_still_allows_lookup() {
148        let mut pair = GenerationPair::empty();
149        pair.install_new(compute_abc(), 1).unwrap();
150        pair.retain_old().unwrap();
151        pair.activate_new().unwrap();
152        assert_eq!(pair.lookup(2), Ok(1));
153        pair.release_old().unwrap();
154        assert_eq!(pair.lookup(2), Ok(1));
155        assert_eq!(pair.release_old(), Err(QdnfError::DoubleRelease));
156    }
157
158    #[test]
159    fn cancelled_empty_table_does_not_publish() {
160        let mut pair = GenerationPair::empty();
161        assert_eq!(
162            GenerationPair::cancelled_computation_cannot_publish(&SpfTable::EMPTY),
163            Err(QdnfError::Incomplete)
164        );
165        assert_eq!(
166            pair.install_new(SpfTable::EMPTY, 9),
167            Err(QdnfError::Incomplete)
168        );
169        assert_eq!(pair.lookup(1), Err(QdnfError::Incomplete));
170        assert_eq!(pair.activate_new(), Err(QdnfError::Incomplete));
171    }
172
173    #[test]
174    fn retain_old_capacity_at_255() {
175        let mut pair = GenerationPair::empty();
176        pair.old_readers = 255;
177        assert_eq!(pair.retain_old(), Err(QdnfError::Capacity));
178    }
179
180    #[test]
181    fn a_to_c_via_b_forward_without_default_route() {
182        let mut table = SpfTable::EMPTY;
183        compute_spf(0, &abc_links(), &mut table).unwrap();
184        let mut pair = GenerationPair::empty();
185        pair.install_new(table, 1).unwrap();
186        assert_eq!(pair.lookup(2), Ok(1));
187        assert_eq!(decrement_hop(1), Ok(0));
188        assert_eq!(decrement_hop(0), Err(QdnfError::HopLimit));
189
190        let one_sided = [LinkMetric {
191            from: 0,
192            to: 1,
193            cost: 1,
194            bidirectional: false,
195        }];
196        let mut ignored = SpfTable::EMPTY;
197        compute_spf(0, &one_sided, &mut ignored).unwrap();
198        assert!(ignored.dest.iter().take(ignored.nodes).all(|d| *d == 0));
199
200        assert!(!GenerationPair::has_default_route());
201        assert_eq!(MAX_LIVE_GENERATIONS, 2);
202
203        let neighbors = [LinkId([1u8; 16])];
204        require_adjacency(&neighbors, LinkId([1u8; 16])).unwrap();
205        assert_eq!(
206            require_adjacency(&neighbors, LinkId([2u8; 16])),
207            Err(QdnfError::NoRoute)
208        );
209    }
210}