Skip to main content

qualia_core_db/net/qdnf/link/
budget.rs

1//! Pre-authentication amplification budget.
2//!
3//! Unauthenticated discovery and handshake bytes/work are charged **before**
4//! neighbor state or reassembly buffers are occupied. Excess is
5//! [`QdnfError::BudgetExhausted`], not a larger table.
6
7use crate::net::qdnf::errors::QdnfError;
8
9/// Default unauthenticated byte cap (a few beacons / cookies, not a flood).
10pub const MAX_UNAUTH_BYTES: u64 = 4096;
11/// Default unauthenticated work units (one HMAC / beacon decode each).
12pub const MAX_UNAUTH_WORK: u64 = 32;
13
14#[repr(C)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub struct PreAuthBudget {
17    cap_bytes: u64,
18    cap_work: u64,
19    used_bytes: u64,
20    used_work: u64,
21}
22
23impl PreAuthBudget {
24    /// Creates a default `PreAuthBudget`.
25    pub const fn new() -> Self {
26        Self::with_caps(MAX_UNAUTH_BYTES, MAX_UNAUTH_WORK)
27    }
28
29    /// Builder: `caps`.
30    pub const fn with_caps(cap_bytes: u64, cap_work: u64) -> Self {
31        Self {
32            cap_bytes,
33            cap_work,
34            used_bytes: 0,
35            used_work: 0,
36        }
37    }
38
39    #[inline]
40    /// `PreAuthBudget::used_bytes`.
41    pub const fn used_bytes(self) -> u64 {
42        self.used_bytes
43    }
44
45    #[inline]
46    /// `PreAuthBudget::used_work`.
47    pub const fn used_work(self) -> u64 {
48        self.used_work
49    }
50
51    #[inline]
52    /// `PreAuthBudget::remaining_bytes`.
53    pub const fn remaining_bytes(self) -> u64 {
54        self.cap_bytes.saturating_sub(self.used_bytes)
55    }
56
57    /// Charge unauthenticated bytes and work. On failure the counters are
58    /// unchanged (no partial charge of the overflowing request).
59    pub fn charge(&mut self, bytes: u64, work: u64) -> Result<(), QdnfError> {
60        let new_bytes = self.used_bytes.checked_add(bytes).ok_or(QdnfError::Range)?;
61        let new_work = self.used_work.checked_add(work).ok_or(QdnfError::Range)?;
62        if new_bytes > self.cap_bytes || new_work > self.cap_work {
63            return Err(QdnfError::BudgetExhausted);
64        }
65        self.used_bytes = new_bytes;
66        self.used_work = new_work;
67        Ok(())
68    }
69}
70
71impl Default for PreAuthBudget {
72    fn default() -> Self {
73        Self::new()
74    }
75}
76
77/// Admit an unauthenticated frame: charge first, then the caller may copy.
78pub fn admit_unauthenticated(
79    budget: &mut PreAuthBudget,
80    bytes: u64,
81    work: u64,
82) -> Result<(), QdnfError> {
83    budget.charge(bytes, work)
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89
90    #[test]
91    fn amplification_budget_exhausts_without_partial_charge() {
92        let mut budget = PreAuthBudget::with_caps(64, 4);
93        assert_eq!(admit_unauthenticated(&mut budget, 64, 1), Ok(()));
94        assert_eq!(budget.used_bytes(), 64);
95        assert_eq!(
96            admit_unauthenticated(&mut budget, 1, 0),
97            Err(QdnfError::BudgetExhausted)
98        );
99        assert_eq!(budget.used_bytes(), 64);
100        assert_eq!(budget.remaining_bytes(), 0);
101    }
102
103    #[test]
104    fn work_cap_exhausts_independently() {
105        let mut budget = PreAuthBudget::with_caps(4096, 2);
106        budget.charge(10, 2).unwrap();
107        assert_eq!(budget.charge(10, 1), Err(QdnfError::BudgetExhausted));
108        assert_eq!(budget.used_work(), 2);
109        assert_eq!(budget.used_bytes(), 10);
110    }
111
112    #[test]
113    fn overflow_is_range_not_wrap() {
114        let mut budget = PreAuthBudget::with_caps(u64::MAX, u64::MAX);
115        budget.charge(1, 0).unwrap();
116        assert_eq!(budget.charge(u64::MAX, 0), Err(QdnfError::Range));
117        assert_eq!(budget.used_bytes(), 1);
118    }
119}