Skip to main content

qualia_core_db/net/peer/cells/
descriptors.rs

1//! Caller-backed cell descriptors (E10.1).
2//!
3//! Production admission is a 16-slot descriptor table charged against one
4//! [`HostAdmission`] owner. Per-cell bytes still cannot exceed 512 MiB.
5//! [`super::admit::CellTable`] grew to 16 slots with the same handle-based
6//! release; extra `owner_tag` values do not mint a second host budget.
7
8use super::admit::{CellProfile, CellSlot, MAX_CELLS};
9use super::host_owner::HostAdmission;
10use crate::net::qdnf::errors::QdnfError;
11
12/// Caller descriptor table size. Same as [`MAX_CELLS`].
13pub const MAX_DESCRIPTOR_CELLS: usize = 16;
14
15/// One caller-backed cell request. `owner_tag` is recorded identity, not budget.
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub struct CellDescriptor {
18    pub profile: CellProfile,
19    pub bytes: u64,
20    pub owner_tag: u64,
21}
22
23/// Admit `descs` against the shared host owner.
24///
25/// A 17th descriptor is [`QdnfError::Capacity`] and admits nothing. Two
26/// descriptors totalling more than `host_bytes` yield
27/// [`QdnfError::BudgetExhausted`]: the first may occupy `out_slots`, the
28/// second fails; there is no silent overcommit.
29pub fn admit_descriptors(
30    host: &mut HostAdmission,
31    descs: &[CellDescriptor],
32    out_slots: &mut [Option<CellSlot>],
33) -> Result<usize, QdnfError> {
34    if descs.len() > MAX_DESCRIPTOR_CELLS || descs.len() > MAX_CELLS {
35        return Err(QdnfError::Capacity);
36    }
37    if out_slots.len() < descs.len() {
38        return Err(QdnfError::Capacity);
39    }
40    let mut n = 0usize;
41    let mut i = 0usize;
42    while i < descs.len() {
43        match host.admit_cell(descs[i].profile, descs[i].bytes) {
44            Ok(slot) => {
45                let _ = descs[i].owner_tag;
46                out_slots[i] = Some(slot);
47                n += 1;
48            }
49            Err(e) => return Err(e),
50        }
51        i += 1;
52    }
53    Ok(n)
54}
55
56#[cfg(test)]
57mod tests {
58    use super::*;
59    use crate::net::peer::cells::admit::MAX_ORDINARY_CELL;
60    use crate::net::qdnf::errors::QdnfError;
61
62    const KIB: u64 = 1024;
63
64    fn desc(bytes: u64, tag: u64) -> CellDescriptor {
65        CellDescriptor {
66            profile: CellProfile::NetworkSmall,
67            bytes,
68            owner_tag: tag,
69        }
70    }
71
72    #[test]
73    fn sixteen_descriptors_ok_seventeenth_capacity() {
74        const N: usize = MAX_DESCRIPTOR_CELLS;
75        let mut host = HostAdmission::new(N as u64 * KIB).unwrap();
76        let mut descs = [desc(KIB, 1); N];
77        let mut i = 0usize;
78        while i < N {
79            descs[i].owner_tag = i as u64 + 1;
80            i += 1;
81        }
82        let mut out = [None; N];
83        let n = admit_descriptors(&mut host, &descs, &mut out).expect("16 descriptors");
84        assert_eq!(n, N);
85        assert_eq!(host.occupied_cells(), N);
86        assert_eq!(MAX_DESCRIPTOR_CELLS, MAX_CELLS);
87
88        let extra = [desc(KIB, 99); N + 1];
89        let mut extra_out = [None; N + 1];
90        assert_eq!(
91            admit_descriptors(&mut host, &extra, &mut extra_out),
92            Err(QdnfError::Capacity)
93        );
94        assert_eq!(host.occupied_cells(), N);
95    }
96
97    #[test]
98    fn overcommit_budget_exhausted_first_may_succeed() {
99        let mut host = HostAdmission::new(100).unwrap();
100        let descs = [desc(60, 1), desc(60, 2)];
101        let mut out = [None, None];
102        assert_eq!(
103            admit_descriptors(&mut host, &descs, &mut out),
104            Err(QdnfError::BudgetExhausted)
105        );
106        assert!(out[0].is_some());
107        assert!(out[1].is_none());
108        assert_eq!(host.occupied_cells(), 1);
109        assert_eq!(host.remaining_host_bytes(), 40);
110        host.release_cell(out[0].unwrap()).unwrap();
111        assert_eq!(host.remaining_host_bytes(), 100);
112    }
113
114    #[test]
115    fn owner_tag_does_not_multiply_host_budget() {
116        let mut host = HostAdmission::new(100).unwrap();
117        let descs = [desc(60, 1), desc(60, 2)];
118        let mut out = [None, None];
119        assert_eq!(
120            admit_descriptors(&mut host, &descs, &mut out),
121            Err(QdnfError::BudgetExhausted)
122        );
123    }
124
125    #[test]
126    fn per_cell_cap_still_512_mib() {
127        let mut host = HostAdmission::new(MAX_ORDINARY_CELL).unwrap();
128        let descs = [CellDescriptor {
129            profile: CellProfile::Ordinary,
130            bytes: MAX_ORDINARY_CELL + 1,
131            owner_tag: 1,
132        }];
133        let mut out = [None];
134        assert_eq!(
135            admit_descriptors(&mut host, &descs, &mut out),
136            Err(QdnfError::Capacity)
137        );
138        assert_eq!(host.occupied_cells(), 0);
139    }
140
141    #[test]
142    fn empty_slice_admits_zero() {
143        let mut host = HostAdmission::new(100).unwrap();
144        let mut out: [Option<CellSlot>; 0] = [];
145        assert_eq!(admit_descriptors(&mut host, &[], &mut out), Ok(0));
146    }
147}