Skip to main content

qualia_core_db/net/peer/runtime/
ledger.rs

1//! Atomic host/cell/role reservation ledger. All-or-nothing admission.
2//!
3//! Release requires a non-forgeable [`ReservationHandle`]. Arbitrary resource
4//! amounts cannot reclaim budget (E03.1).
5
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::types::Generation;
8
9mod headroom;
10mod incarnation;
11mod inspect;
12const HANDLE_SLOTS: usize = 32;
13
14#[repr(C)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub struct ResourceBudget {
17    pub bytes: u64,
18    pub work: u64,
19    pub io: u64,
20}
21
22impl ResourceBudget {
23    pub const ZERO: Self = Self {
24        bytes: 0,
25        work: 0,
26        io: 0,
27    };
28
29    /// Checked budget add; `QdnfError` on overflow.
30    pub fn saturating_add(self, other: Self) -> Result<Self, QdnfError> {
31        Ok(Self {
32            bytes: self
33                .bytes
34                .checked_add(other.bytes)
35                .ok_or(QdnfError::Range)?,
36            work: self.work.checked_add(other.work).ok_or(QdnfError::Range)?,
37            io: self.io.checked_add(other.io).ok_or(QdnfError::Range)?,
38        })
39    }
40}
41
42#[repr(C)]
43#[derive(Clone, Copy, Debug, PartialEq, Eq)]
44pub struct AdmissionScopes {
45    pub host: ResourceBudget,
46    pub cell: ResourceBudget,
47    pub role: ResourceBudget,
48    pub session: ResourceBudget,
49    pub operation: ResourceBudget,
50}
51
52#[derive(Clone, Copy)]
53struct HandleSlot {
54    occupied: bool,
55    generation: Generation,
56    budget: ResourceBudget,
57    verified_peer: bool,
58}
59
60impl HandleSlot {
61    const EMPTY: Self = Self {
62        occupied: false,
63        generation: Generation::ZERO,
64        budget: ResourceBudget::ZERO,
65        verified_peer: false,
66    };
67}
68
69/// Owner-issued reservation. Not `Copy`: a copied token cannot be mutated to
70/// reclaim a different amount.
71#[derive(Debug, PartialEq, Eq)]
72pub struct ReservationHandle {
73    slot: u8,
74    generation: Generation,
75}
76
77/// Copyable owner reference used by bounded tables. Not a public budget token.
78#[derive(Clone, Copy, Debug, PartialEq, Eq)]
79pub struct ChargeRef {
80    pub slot: u8,
81    pub generation: Generation,
82}
83
84impl ChargeRef {
85    pub const EMPTY: Self = Self {
86        slot: 0,
87        generation: Generation::ZERO,
88    };
89}
90
91impl ReservationHandle {
92    #[inline]
93    /// Generation.
94    pub const fn generation(&self) -> Generation {
95        self.generation
96    }
97
98    /// `ReservationHandle::as_ref`.
99    pub fn as_ref(&self) -> ChargeRef {
100        ChargeRef {
101            slot: self.slot,
102            generation: self.generation,
103        }
104    }
105
106    /// Wraps a charge reference as a handle.
107    pub(crate) fn from_ref(r: ChargeRef) -> Self {
108        Self {
109            slot: r.slot,
110            generation: r.generation,
111        }
112    }
113}
114
115pub struct ReservationLedger {
116    incarnation: super::incarnation::CanonicalIncarnation,
117    host_cap: ResourceBudget,
118    cell_cap: ResourceBudget,
119    role_cap: ResourceBudget,
120    session_cap: ResourceBudget,
121    operation_cap: ResourceBudget,
122    used: AdmissionScopes,
123    transient_used: ResourceBudget,
124    verified_used: ResourceBudget,
125    handles: [HandleSlot; HANDLE_SLOTS],
126}
127
128impl ReservationLedger {
129    /// Creates a default `ReservationLedger`.
130    pub const fn new(
131        host_cap: ResourceBudget,
132        cell_cap: ResourceBudget,
133        role_cap: ResourceBudget,
134        session_cap: ResourceBudget,
135        operation_cap: ResourceBudget,
136    ) -> Self {
137        Self {
138            incarnation: super::incarnation::CanonicalIncarnation::UNASSIGNED,
139            host_cap,
140            cell_cap,
141            role_cap,
142            session_cap,
143            operation_cap,
144            used: AdmissionScopes {
145                host: ResourceBudget::ZERO,
146                cell: ResourceBudget::ZERO,
147                role: ResourceBudget::ZERO,
148                session: ResourceBudget::ZERO,
149                operation: ResourceBudget::ZERO,
150            },
151            transient_used: ResourceBudget::ZERO,
152            verified_used: ResourceBudget::ZERO,
153            handles: [HandleSlot::EMPTY; HANDLE_SLOTS],
154        }
155    }
156
157    fn fits(cap: ResourceBudget, used: ResourceBudget, add: ResourceBudget) -> bool {
158        used.bytes.saturating_add(add.bytes) <= cap.bytes
159            && used.work.saturating_add(add.work) <= cap.work
160            && used.io.saturating_add(add.io) <= cap.io
161    }
162
163    fn free_slot(&self) -> Result<usize, QdnfError> {
164        let mut i = 0;
165        while i < HANDLE_SLOTS {
166            if !self.handles[i].occupied {
167                return Ok(i);
168            }
169            i += 1;
170        }
171        Err(QdnfError::Capacity)
172    }
173
174    /// Reserve every listed scope or leave every counter unchanged.
175    pub fn reserve(
176        &mut self,
177        add: ResourceBudget,
178        verified_peer: bool,
179    ) -> Result<ReservationHandle, QdnfError> {
180        if !Self::fits(self.host_cap, self.used.host, add)
181            || !Self::fits(self.cell_cap, self.used.cell, add)
182            || !Self::fits(self.role_cap, self.used.role, add)
183            || !Self::fits(self.session_cap, self.used.session, add)
184            || !Self::fits(self.operation_cap, self.used.operation, add)
185        {
186            return Err(QdnfError::BudgetExhausted);
187        }
188        if !verified_peer && !Self::fits(self.host_cap, self.transient_used, add) {
189            return Err(QdnfError::BudgetExhausted);
190        }
191        let slot = self.free_slot()?;
192        let generation = self.handles[slot].generation.next()?;
193        self.used.host = self.used.host.saturating_add(add)?;
194        self.used.cell = self.used.cell.saturating_add(add)?;
195        self.used.role = self.used.role.saturating_add(add)?;
196        self.used.session = self.used.session.saturating_add(add)?;
197        self.used.operation = self.used.operation.saturating_add(add)?;
198        if verified_peer {
199            self.verified_used = self.verified_used.saturating_add(add)?;
200        } else {
201            self.transient_used = self.transient_used.saturating_add(add)?;
202        }
203        self.handles[slot] = HandleSlot {
204            occupied: true,
205            generation,
206            budget: add,
207            verified_peer,
208        };
209        Ok(ReservationHandle {
210            slot: slot as u8,
211            generation,
212        })
213    }
214
215    /// Releases `handle`'s reservation.
216    pub fn release(&mut self, handle: ReservationHandle) -> Result<(), QdnfError> {
217        let i = handle.slot as usize;
218        if i >= HANDLE_SLOTS {
219            return Err(QdnfError::Range);
220        }
221        let slot = &mut self.handles[i];
222        if !slot.occupied {
223            return Err(QdnfError::DoubleRelease);
224        }
225        if slot.generation != handle.generation {
226            return Err(QdnfError::StaleGeneration);
227        }
228        let add = slot.budget;
229        let verified_peer = slot.verified_peer;
230        slot.occupied = false;
231        slot.budget = ResourceBudget::ZERO;
232        self.sub_used(add, verified_peer)
233    }
234
235    /// Release `handle` only if `(slot, generation)` matches AND the authoritative
236    /// recorded byte reservation equals `expected_bytes` (`R10` / `R11`).
237    pub fn release_checked_bytes(
238        &mut self,
239        handle: ReservationHandle,
240        expected_bytes: u64,
241    ) -> Result<(), QdnfError> {
242        let i = handle.slot as usize;
243        if i >= HANDLE_SLOTS {
244            return Err(QdnfError::Range);
245        }
246        let slot = &self.handles[i];
247        if !slot.occupied {
248            return Err(QdnfError::DoubleRelease);
249        }
250        if slot.generation != handle.generation {
251            return Err(QdnfError::StaleGeneration);
252        }
253        if slot.budget.bytes != expected_bytes {
254            return Err(QdnfError::Conflict);
255        }
256        self.release(handle)
257    }
258
259    fn sub_used(&mut self, add: ResourceBudget, verified_peer: bool) -> Result<(), QdnfError> {
260        self.used.host.bytes = self.used.host.bytes.saturating_sub(add.bytes);
261        self.used.host.work = self.used.host.work.saturating_sub(add.work);
262        self.used.host.io = self.used.host.io.saturating_sub(add.io);
263        self.used.cell.bytes = self.used.cell.bytes.saturating_sub(add.bytes);
264        self.used.cell.work = self.used.cell.work.saturating_sub(add.work);
265        self.used.cell.io = self.used.cell.io.saturating_sub(add.io);
266        self.used.role.bytes = self.used.role.bytes.saturating_sub(add.bytes);
267        self.used.role.work = self.used.role.work.saturating_sub(add.work);
268        self.used.role.io = self.used.role.io.saturating_sub(add.io);
269        self.used.session.bytes = self.used.session.bytes.saturating_sub(add.bytes);
270        self.used.session.work = self.used.session.work.saturating_sub(add.work);
271        self.used.session.io = self.used.session.io.saturating_sub(add.io);
272        self.used.operation.bytes = self.used.operation.bytes.saturating_sub(add.bytes);
273        self.used.operation.work = self.used.operation.work.saturating_sub(add.work);
274        self.used.operation.io = self.used.operation.io.saturating_sub(add.io);
275        if verified_peer {
276            self.verified_used.bytes = self.verified_used.bytes.saturating_sub(add.bytes);
277            self.verified_used.work = self.verified_used.work.saturating_sub(add.work);
278            self.verified_used.io = self.verified_used.io.saturating_sub(add.io);
279        } else {
280            self.transient_used.bytes = self.transient_used.bytes.saturating_sub(add.bytes);
281            self.transient_used.work = self.transient_used.work.saturating_sub(add.work);
282            self.transient_used.io = self.transient_used.io.saturating_sub(add.io);
283        }
284        Ok(())
285    }
286
287    /// Aggregate usage across admission scopes.
288    pub fn used(&self) -> AdmissionScopes {
289        self.used
290    }
291
292    /// Transient-scope usage.
293    pub fn transient_used(&self) -> ResourceBudget {
294        self.transient_used
295    }
296
297    /// Host bytes remaining under budget.
298    pub fn host_remaining_bytes(&self) -> u64 {
299        self.host_cap.bytes.saturating_sub(self.used.host.bytes)
300    }
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306
307    fn caps() -> ReservationLedger {
308        let cap = ResourceBudget {
309            bytes: 100,
310            work: 10,
311            io: 8,
312        };
313        ReservationLedger::new(cap, cap, cap, cap, cap)
314    }
315
316    #[test]
317    fn failed_reserve_leaves_counters_unchanged() {
318        let mut ledger = caps();
319        let add = ResourceBudget {
320            bytes: 60,
321            work: 1,
322            io: 1,
323        };
324        let _h = ledger.reserve(add, true).unwrap();
325        let before = ledger.used();
326        assert_eq!(
327            ledger
328                .reserve(
329                    ResourceBudget {
330                        bytes: 50,
331                        work: 1,
332                        io: 1
333                    },
334                    true
335                )
336                .unwrap_err(),
337            QdnfError::BudgetExhausted
338        );
339        assert_eq!(ledger.used(), before);
340    }
341
342    #[test]
343    fn sybil_does_not_multiply_host_admission() {
344        let mut ledger = caps();
345        let add = ResourceBudget {
346            bytes: 60,
347            work: 1,
348            io: 1,
349        };
350        let _h = ledger.reserve(add, false).unwrap();
351        assert_eq!(
352            ledger.reserve(add, false).unwrap_err(),
353            QdnfError::BudgetExhausted
354        );
355    }
356
357    #[test]
358    fn release_requires_owner_handle() {
359        let mut ledger = caps();
360        let add = ResourceBudget {
361            bytes: 10,
362            work: 1,
363            io: 1,
364        };
365        let handle = ledger.reserve(add, true).unwrap();
366        assert_eq!(ledger.release(handle), Ok(()));
367    }
368
369    #[test]
370    fn double_release_is_rejected() {
371        let mut ledger = caps();
372        let add = ResourceBudget {
373            bytes: 10,
374            work: 1,
375            io: 1,
376        };
377        let handle = ledger.reserve(add, true).unwrap();
378        ledger.release(handle).unwrap();
379        let stale = ReservationHandle {
380            slot: 0,
381            generation: Generation(1),
382        };
383        assert_eq!(ledger.release(stale), Err(QdnfError::DoubleRelease));
384    }
385
386    #[test]
387    fn foreign_generation_is_stale() {
388        let mut ledger = caps();
389        let add = ResourceBudget {
390            bytes: 10,
391            work: 1,
392            io: 1,
393        };
394        let handle = ledger.reserve(add, true).unwrap();
395        let forged = ReservationHandle {
396            slot: handle.slot,
397            generation: Generation(99),
398        };
399        let _ = handle;
400        assert_eq!(ledger.release(forged), Err(QdnfError::StaleGeneration));
401    }
402
403    #[test]
404    fn r10_r11_release_checked_bytes_rejects_mismatched_caller_amount_and_stale_generation() {
405        let mut ledger = caps();
406        let add = ResourceBudget {
407            bytes: 32,
408            work: 1,
409            io: 1,
410        };
411        let handle = ledger.reserve(add, true).unwrap();
412        let wrong_amount_ref = handle.as_ref();
413        assert_eq!(
414            ledger.release_checked_bytes(ReservationHandle::from_ref(wrong_amount_ref), 64),
415            Err(QdnfError::Conflict)
416        );
417        assert_eq!(ledger.used().host.bytes, 32);
418        assert_eq!(ledger.release_checked_bytes(handle, 32), Ok(()));
419        assert_eq!(ledger.used().host.bytes, 0);
420    }
421}