qualia_core_db/net/qdnf/session/
paths.rs1use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::types::Generation;
12
13pub const MAX_ACTIVE_PATHS: usize = 3;
15pub 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38pub struct PathHandle {
39 slot: u8,
40 generation: Generation,
41}
42
43impl PathHandle {
44 #[inline]
45 pub const fn slot(self) -> u8 {
47 self.slot
48 }
49
50 #[inline]
51 pub const fn generation(self) -> Generation {
53 self.generation
54 }
55}
56
57pub const fn path_handle_is_budget_token() -> bool {
59 false
60}
61
62pub fn mutate_path(
65 table: &mut PathTable,
66 handle: PathHandle,
67 next: PathState,
68) -> Result<PathHandle, QdnfError> {
69 table.mutate(handle, next)
70}
71
72pub struct PathTable {
74 slots: [Option<PathSlot>; MAX_RACE_CANDIDATES],
75}
76
77impl PathTable {
78 pub const fn new() -> Self {
80 Self {
81 slots: [None; MAX_RACE_CANDIDATES],
82 }
83 }
84
85 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 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 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 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 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 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 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 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 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 pub const fn preserve_operation_id_across_path_change() -> bool {
236 true
237 }
238
239 pub const fn duplicate_recovery_on_compat_carrier() -> bool {
241 false
242 }
243
244 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}