Skip to main content

qualia_core_db/net/peer/cells/
pass_budget.rs

1//! 42 MiB Sentinel pass accounting (E03.4) and reclaim on every outcome (E03.5).
2//!
3//! This is **accounting only**. It does not allocate [`crate::governance::webizen::SlgArena`],
4//! does not map 42 MiB of RAM, and is not a measured process RSS. Callers charge
5//! arena, scratch, crypto, kernel and pinned bytes against
6//! [`SENTINEL_PASS_TOTAL`].
7
8use crate::governance::webizen::SENTINEL_PASS_BYTES;
9use crate::net::qdnf::errors::QdnfError;
10
11/// Exact 42 MiB pass ceiling. Same value as [`SENTINEL_PASS_BYTES`].
12pub const SENTINEL_PASS_TOTAL: u64 = 42 * 1024 * 1024;
13
14/// Explicit pass charge components (E03.4).
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub struct PassCharge {
17    pub arena: u64,
18    pub scratch: u64,
19    pub crypto: u64,
20    pub kernel: u64,
21    pub pinned: u64,
22}
23
24impl PassCharge {
25    pub const ZERO: Self = Self {
26        arena: 0,
27        scratch: 0,
28        crypto: 0,
29        kernel: 0,
30        pinned: 0,
31    };
32}
33
34/// Checked sum of every charged class. Greater than 42 MiB → [`QdnfError::Capacity`].
35pub fn charge_pass(c: &PassCharge) -> Result<u64, QdnfError> {
36    let mut total = 0u64;
37    total = total.checked_add(c.arena).ok_or(QdnfError::Capacity)?;
38    total = total.checked_add(c.scratch).ok_or(QdnfError::Capacity)?;
39    total = total.checked_add(c.crypto).ok_or(QdnfError::Capacity)?;
40    total = total.checked_add(c.kernel).ok_or(QdnfError::Capacity)?;
41    total = total.checked_add(c.pinned).ok_or(QdnfError::Capacity)?;
42    if total > SENTINEL_PASS_TOTAL {
43        return Err(QdnfError::Capacity);
44    }
45    let _ = SENTINEL_PASS_BYTES;
46    Ok(total)
47}
48
49/// Terminal pass outcomes that must still reclaim (E03.5).
50#[repr(u8)]
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52pub enum PassOutcome {
53    Success = 0,
54    Error = 1,
55    Cancel = 2,
56    Unwind = 3,
57}
58
59/// Reclaim charged pass bytes. Every outcome returns 0 remaining.
60pub fn reclaim_pass(_outcome: PassOutcome, charged: u64) -> u64 {
61    let _ = charged;
62    0
63}
64
65/// RAII Sentinel pass. Reclaims on success, error, and unwind. Does not map 42 MiB.
66pub struct PassGuard {
67    charged: u64,
68    outcome: PassOutcome,
69}
70
71impl PassGuard {
72    /// Enters the pass budget.
73    pub fn enter(charge: &PassCharge) -> Result<Self, QdnfError> {
74        Ok(Self {
75            charged: charge_pass(charge)?,
76            outcome: PassOutcome::Error,
77        })
78    }
79
80    #[inline]
81    /// `PassGuard::charged`.
82    pub const fn charged(&self) -> u64 {
83        self.charged
84    }
85
86    #[inline]
87    /// `PassGuard::success`.
88    pub fn success(&mut self) {
89        self.outcome = PassOutcome::Success;
90    }
91}
92
93impl Drop for PassGuard {
94    fn drop(&mut self) {
95        let _ = reclaim_pass(self.outcome, self.charged);
96    }
97}
98
99#[cfg(test)]
100mod tests {
101    use super::*;
102    use crate::net::qdnf::errors::QdnfError;
103
104    #[test]
105    fn forty_two_mib_exact_ok_plus_one_capacity() {
106        assert_eq!(SENTINEL_PASS_TOTAL, SENTINEL_PASS_BYTES as u64);
107        let exact = PassCharge {
108            arena: SENTINEL_PASS_TOTAL,
109            ..PassCharge::ZERO
110        };
111        assert_eq!(charge_pass(&exact), Ok(SENTINEL_PASS_TOTAL));
112        let over = PassCharge {
113            arena: SENTINEL_PASS_TOTAL,
114            scratch: 1,
115            ..PassCharge::ZERO
116        };
117        assert_eq!(charge_pass(&over), Err(QdnfError::Capacity));
118        let plus_one = PassCharge {
119            arena: SENTINEL_PASS_TOTAL + 1,
120            ..PassCharge::ZERO
121        };
122        assert_eq!(charge_pass(&plus_one), Err(QdnfError::Capacity));
123    }
124
125    #[test]
126    fn scratch_crypto_kernel_pinned_counted() {
127        let c = PassCharge {
128            arena: SENTINEL_PASS_TOTAL - 40,
129            scratch: 10,
130            crypto: 10,
131            kernel: 10,
132            pinned: 10,
133        };
134        assert_eq!(charge_pass(&c), Ok(SENTINEL_PASS_TOTAL));
135        let over = PassCharge {
136            arena: SENTINEL_PASS_TOTAL - 40,
137            scratch: 11,
138            crypto: 10,
139            kernel: 10,
140            pinned: 10,
141        };
142        assert_eq!(charge_pass(&over), Err(QdnfError::Capacity));
143    }
144
145    #[test]
146    fn reclaim_on_success_error_cancel_unwind() {
147        let charged = charge_pass(&PassCharge {
148            arena: 1024,
149            scratch: 1024,
150            ..PassCharge::ZERO
151        })
152        .unwrap();
153        assert_eq!(reclaim_pass(PassOutcome::Success, charged), 0);
154        assert_eq!(reclaim_pass(PassOutcome::Error, charged), 0);
155        assert_eq!(reclaim_pass(PassOutcome::Cancel, charged), 0);
156        assert_eq!(reclaim_pass(PassOutcome::Unwind, charged), 0);
157    }
158
159    #[test]
160    fn overflow_is_capacity_not_wrap() {
161        let c = PassCharge {
162            arena: u64::MAX,
163            scratch: 1,
164            ..PassCharge::ZERO
165        };
166        assert_eq!(charge_pass(&c), Err(QdnfError::Capacity));
167    }
168
169    #[test]
170    fn network_pass_charges_scratch_crypto_kernel() {
171        let over = PassCharge {
172            scratch: SENTINEL_PASS_TOTAL,
173            crypto: 1,
174            kernel: 1,
175            ..PassCharge::ZERO
176        };
177        assert_eq!(PassGuard::enter(&over).err(), Some(QdnfError::Capacity));
178        let ok = PassCharge {
179            scratch: 8,
180            crypto: 8,
181            kernel: 8,
182            ..PassCharge::ZERO
183        };
184        {
185            let mut g = PassGuard::enter(&ok).unwrap();
186            assert_eq!(g.charged(), 24);
187            g.success();
188        }
189        {
190            let g = PassGuard::enter(&ok).unwrap();
191            assert_eq!(g.charged(), 24);
192        }
193    }
194}