Skip to main content

qualia_core_db/net/peer/host/
builder.rs

1//! Peer construction. The ledger is sized to the caller’s cell budget.
2
3use super::identity::ControllerIdentity;
4use super::session_table::SessionTable;
5use super::NativePeer;
6use crate::net::peer::cells::host_owner::HostAdmission;
7use crate::net::peer::cells::{CellSlot, MAX_ORDINARY_CELL};
8use crate::net::peer::runtime::{CancelEpoch, ReservationLedger, ResourceBudget};
9use crate::net::qdnf::bearer::IpcEndpoint;
10use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::types::{LinkId, ScopeEpoch};
12
13/// Default per-peer cell when the caller does not specify a budget.
14pub const CELL_BYTES_DEFAULT: u64 = 64 * 1024 * 1024;
15
16const LEDGER_WORK: u64 = 1024;
17const LEDGER_IO: u64 = 256;
18
19#[derive(Debug)]
20pub struct PeerBuilder {
21    identity: ControllerIdentity,
22    local_link: LinkId,
23    cell_bytes: u64,
24}
25
26impl PeerBuilder {
27    /// Creates a default `PeerBuilder`.
28    pub fn new(controller: &[u8], local_link: LinkId, cell_bytes: u64) -> Result<Self, QdnfError> {
29        if cell_bytes == 0 || cell_bytes > MAX_ORDINARY_CELL {
30            return Err(QdnfError::Capacity);
31        }
32        Ok(Self {
33            identity: ControllerIdentity::from_controller(controller)?,
34            local_link,
35            cell_bytes,
36        })
37    }
38
39    /// Builder: sets `bearer`.
40    pub fn with_bearer(self, bearer: IpcEndpoint) -> Result<NativePeer, QdnfError> {
41        self.with_bearer_cell(bearer, None)
42    }
43
44    /// Builder: sets `bearer_cell`.
45    pub fn with_bearer_cell(
46        self,
47        bearer: IpcEndpoint,
48        cell_slot: Option<CellSlot>,
49    ) -> Result<NativePeer, QdnfError> {
50        let cap = ResourceBudget {
51            bytes: self.cell_bytes,
52            work: LEDGER_WORK,
53            io: LEDGER_IO,
54        };
55        Ok(NativePeer {
56            identity: self.identity,
57            local_link: self.local_link,
58            neighbors: crate::net::qdnf::link::NeighborTable::new(),
59            ledger: ReservationLedger::new(cap, cap, cap, cap, cap),
60            sessions: SessionTable::new(),
61            primary: None,
62            bearer,
63            cancel_epoch: CancelEpoch::ZERO,
64            cancelled: false,
65            cell_slot,
66            challenges: crate::net::qdnf::link::ChallengeTable::new(),
67            preauth: crate::net::qdnf::link::PreAuthBudget::new(),
68        })
69    }
70}
71
72impl NativePeer {
73    /// Two connected native peers over `local-ipc-v1`. Transport only; no session.
74    /// Both cells are admitted from one [`HostAdmission`] aggregate (`2 *` cell).
75    pub fn pair_ipc(
76        a_controller: &[u8],
77        b_controller: &[u8],
78        scope: ScopeEpoch,
79        mtu: u16,
80    ) -> Result<(Self, Self), QdnfError> {
81        let host_bytes = CELL_BYTES_DEFAULT
82            .checked_mul(2)
83            .ok_or(QdnfError::Capacity)?;
84        let mut host = HostAdmission::new(host_bytes)?;
85        super::exchange::pair_ipc_cells(
86            &mut host,
87            a_controller,
88            b_controller,
89            scope,
90            mtu,
91            CELL_BYTES_DEFAULT,
92        )
93    }
94
95    /// Return this peer’s host cell to `host`. No-op when constructed without one.
96    pub fn release_into_host(&mut self, host: &mut HostAdmission) -> Result<(), QdnfError> {
97        match self.cell_slot.take() {
98            Some(slot) => host.release_cell(slot),
99            None => Ok(()),
100        }
101    }
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn builder_rejects_zero_and_oversize_cell_bytes() {
110        let link = LinkId::ZERO;
111        assert_eq!(
112            PeerBuilder::new(b"did:q42:a", link, 0).unwrap_err(),
113            QdnfError::Capacity
114        );
115        assert_eq!(
116            PeerBuilder::new(b"did:q42:a", link, MAX_ORDINARY_CELL.saturating_add(1)).unwrap_err(),
117            QdnfError::Capacity
118        );
119        assert!(PeerBuilder::new(b"did:q42:a", link, MAX_ORDINARY_CELL).is_ok());
120        assert!(PeerBuilder::new(b"did:q42:a", link, CELL_BYTES_DEFAULT).is_ok());
121    }
122}