Skip to main content

qualia_core_db/net/peer/cells/
host_owner.rs

1//! One host owner aggregates every cell/role/session/operation charge (E03.2).
2//!
3//! Extra identities cannot mint a second host budget (E03.6). Leases and ledger
4//! charges bind to this owner; copied cell-slot byte fields are not authority.
5
6use crate::governance::webizen::{classify_budget, ArenaBudgetClass};
7use crate::net::peer::cells::admit::{
8    CellProfile, CellSlot, CellTable, MAX_CELLS, MAX_ORDINARY_CELL,
9};
10use crate::net::peer::runtime::{LeaseTable, ReservationHandle, ReservationLedger, ResourceBudget};
11use crate::net::qdnf::errors::QdnfError;
12use crate::net::qdnf::types::StrongDigest;
13
14const HOST_WORK: u64 = 1024;
15const HOST_IO: u64 = 1024;
16const MAX_TRACKED_IDENTITIES: usize = 8;
17
18/// Aggregate host byte cap: one owner, up to [`MAX_CELLS`] ordinary cells.
19/// Per-cell ceiling remains [`MAX_ORDINARY_CELL`]; this is accounting, not RSS.
20pub const MAX_HOST_BYTES: u64 = MAX_CELLS as u64 * MAX_ORDINARY_CELL;
21
22/// Aggregate admission owner for one host process.
23pub struct HostAdmission {
24    ledger: ReservationLedger,
25    leases: LeaseTable,
26    cells: CellTable,
27    host_bytes: u64,
28    identities: [StrongDigest; MAX_TRACKED_IDENTITIES],
29    identity_count: u8,
30}
31
32impl HostAdmission {
33    /// Creates a default `HostAdmission`.
34    pub fn new(host_bytes: u64) -> Result<Self, QdnfError> {
35        if host_bytes == 0 || host_bytes > MAX_HOST_BYTES {
36            return Err(QdnfError::Capacity);
37        }
38        let cap = ResourceBudget {
39            bytes: host_bytes,
40            work: HOST_WORK,
41            io: HOST_IO,
42        };
43        Ok(Self {
44            ledger: ReservationLedger::new(cap, cap, cap, cap, cap),
45            leases: LeaseTable::new(),
46            cells: CellTable::new(),
47            host_bytes,
48            identities: [StrongDigest::ZERO; MAX_TRACKED_IDENTITIES],
49            identity_count: 0,
50        })
51    }
52
53    #[inline]
54    /// `HostAdmission::host_bytes`.
55    pub const fn host_bytes(&self) -> u64 {
56        self.host_bytes
57    }
58
59    #[inline]
60    /// `HostAdmission::remaining_host_bytes`.
61    pub fn remaining_host_bytes(&self) -> u64 {
62        self.ledger.host_remaining_bytes()
63    }
64
65    /// `HostAdmission::profile_for_bytes`.
66    pub fn profile_for_bytes(bytes: u64) -> Result<CellProfile, QdnfError> {
67        if bytes == 0 || bytes > MAX_ORDINARY_CELL {
68            return Err(QdnfError::Capacity);
69        }
70        match classify_budget(bytes) {
71            Ok(ArenaBudgetClass::SentinelPass) => Ok(CellProfile::SentinelPass),
72            Ok(ArenaBudgetClass::OrdinaryCell) => Ok(CellProfile::Ordinary),
73            Ok(ArenaBudgetClass::Rejected) => Err(QdnfError::Capacity),
74            Err(_) => Ok(CellProfile::NetworkSmall),
75        }
76    }
77
78    /// Admit one cell against the shared host ledger.
79    pub fn admit_cell(&mut self, profile: CellProfile, bytes: u64) -> Result<CellSlot, QdnfError> {
80        self.cells
81            .reserve(&mut self.leases, &mut self.ledger, profile, bytes)
82    }
83
84    /// Releases a cell slot.
85    pub fn release_cell(&mut self, slot: CellSlot) -> Result<(), QdnfError> {
86        self.cells.release(&mut self.leases, &mut self.ledger, slot)
87    }
88
89    #[inline]
90    /// `HostAdmission::occupied_cells`.
91    pub fn occupied_cells(&self) -> usize {
92        self.cells.occupied()
93    }
94
95    /// Charge work for a peer identity. The identity is recorded; it does not
96    /// receive an independent host cap.
97    pub fn charge(
98        &mut self,
99        identity: StrongDigest,
100        add: ResourceBudget,
101        verified_peer: bool,
102    ) -> Result<ReservationHandle, QdnfError> {
103        if identity.is_zero() {
104            return Err(QdnfError::Unauthorized);
105        }
106        self.remember(identity)?;
107        self.ledger.reserve(add, verified_peer)
108    }
109
110    /// Releases a charge reservation.
111    pub fn release_charge(&mut self, handle: ReservationHandle) -> Result<(), QdnfError> {
112        self.ledger.release(handle)
113    }
114
115    fn remember(&mut self, identity: StrongDigest) -> Result<(), QdnfError> {
116        let n = self.identity_count as usize;
117        let mut i = 0usize;
118        while i < n {
119            if self.identities[i] == identity {
120                return Ok(());
121            }
122            i += 1;
123        }
124        if n >= MAX_TRACKED_IDENTITIES {
125            return Ok(());
126        }
127        self.identities[n] = identity;
128        self.identity_count = (n as u8).saturating_add(1);
129        Ok(())
130    }
131
132    #[inline]
133    /// `HostAdmission::tracked_identities`.
134    pub const fn tracked_identities(&self) -> u8 {
135        self.identity_count
136    }
137}
138
139/// Extra DIDs/controllers cannot multiply the host byte cap.
140#[inline]
141pub fn extra_identity_multiplies_host_budget() -> bool {
142    false
143}
144
145#[cfg(test)]
146mod tests {
147    use super::*;
148
149    fn digest(b: u8) -> StrongDigest {
150        let mut d = StrongDigest::ZERO;
151        d.0[0] = b;
152        d.0[47] = b ^ 0xff;
153        d
154    }
155
156    #[test]
157    fn extra_identity_cannot_multiply_host_budget() {
158        let mut host = HostAdmission::new(100).unwrap();
159        let add = ResourceBudget {
160            bytes: 60,
161            work: 1,
162            io: 1,
163        };
164        let a = host.charge(digest(1), add, true).unwrap();
165        assert_eq!(host.tracked_identities(), 1);
166        assert_eq!(
167            host.charge(digest(2), add, true).unwrap_err(),
168            QdnfError::BudgetExhausted
169        );
170        assert_eq!(host.tracked_identities(), 2);
171        assert!(!extra_identity_multiplies_host_budget());
172        host.release_charge(a).unwrap();
173        host.charge(digest(2), add, true).unwrap();
174        assert_eq!(host.remaining_host_bytes(), 40);
175    }
176
177    #[test]
178    fn zero_identity_cannot_charge() {
179        let mut host = HostAdmission::new(100).unwrap();
180        let add = ResourceBudget {
181            bytes: 10,
182            work: 1,
183            io: 1,
184        };
185        assert_eq!(
186            host.charge(StrongDigest::ZERO, add, true).unwrap_err(),
187            QdnfError::Unauthorized
188        );
189        assert_eq!(host.remaining_host_bytes(), 100);
190    }
191
192    #[test]
193    fn cell_admission_uses_shared_host_ledger() {
194        let mut host = HostAdmission::new(2 * 1024 * 1024).unwrap();
195        let profile = CellProfile::NetworkSmall;
196        let first = host.admit_cell(profile, 1024 * 1024).unwrap();
197        assert_eq!(
198            host.admit_cell(profile, 1024 * 1024 + 1).unwrap_err(),
199            QdnfError::BudgetExhausted
200        );
201        host.release_cell(first).unwrap();
202        host.admit_cell(profile, 1024 * 1024).unwrap();
203    }
204
205    #[test]
206    fn host_zero_or_over_aggregate_is_capacity() {
207        assert_eq!(HostAdmission::new(0).err(), Some(QdnfError::Capacity));
208        assert_eq!(
209            HostAdmission::new(MAX_HOST_BYTES + 1).err(),
210            Some(QdnfError::Capacity)
211        );
212        HostAdmission::new(MAX_ORDINARY_CELL + 1).expect("host aggregates more than one cell");
213    }
214}