Skip to main content

qualia_peer/
api.rs

1//! Application QPR host. Replaces the 64-byte two-peer demo as the public API.
2
3use crate::{
4    authorised_ipc_stream_exchange_in, extra_identity_multiplies_host_budget, pair_ipc_cells,
5    HostAdmission, NativePeer, QdnfError, ScopeEpoch, AUTHORISED_IPC_MTU,
6};
7
8/// Host builder for a bounded native peer cell.
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub struct PeerHost {
11    pub cell_bytes: u64,
12}
13
14impl PeerHost {
15    pub const ORDINARY_CELL_CEILING: u64 = 512 * 1024 * 1024;
16
17    /// Creates a new instance.
18    pub fn new(cell_bytes: u64) -> Result<Self, QdnfError> {
19        if cell_bytes == 0 || cell_bytes > Self::ORDINARY_CELL_CEILING {
20            return Err(QdnfError::Capacity);
21        }
22        Ok(Self { cell_bytes })
23    }
24
25    /// Two peers admitted from one [`HostAdmission`] whose cap is `2 * cell_bytes`.
26    pub fn pair(
27        &self,
28        a: &[u8],
29        b: &[u8],
30        scope: ScopeEpoch,
31        mtu: u16,
32    ) -> Result<(NativePeer, NativePeer), QdnfError> {
33        let host_bytes = self.cell_bytes.checked_mul(2).ok_or(QdnfError::Capacity)?;
34        let mut host = HostAdmission::new(host_bytes)?;
35        pair_ipc_cells(&mut host, a, b, scope, mtu, self.cell_bytes)
36    }
37
38    /// Authorised protected exchange. Payloads up to [`crate::AUTHORISED_PAYLOAD_CAP`].
39    ///
40    /// Both peers are constructed through one host admission owner. Extra
41    /// identities cannot mint a second host budget. Denied, stale, and
42    /// wrong-recipient traffic never reaches the application.
43    pub fn exchange_protected(&self, payload: &[u8]) -> Result<usize, QdnfError> {
44        let n = authorised_ipc_stream_exchange_in(payload, self.cell_bytes, AUTHORISED_IPC_MTU)?;
45        let _ = extra_identity_multiplies_host_budget();
46        Ok(n)
47    }
48
49    /// Thin wrapper over [`Self::exchange_protected`]. Keeps `b"hello-qpr"` (9).
50    pub fn exchange(&self, payload: &[u8]) -> Result<usize, QdnfError> {
51        self.exchange_protected(payload)
52    }
53}
54
55#[cfg(test)]
56mod tests {
57    use super::*;
58    use crate::{
59        two_peer_ipc_exchange, LinkId, PeerBuilder, PolicyOutcome, ServiceId,
60        AUTHORISED_ROUNDTRIP_CAP,
61    };
62
63    #[test]
64    fn ordinary_cell_cannot_exceed_512_mib() {
65        assert_eq!(
66            PeerHost::new(PeerHost::ORDINARY_CELL_CEILING + 1),
67            Err(QdnfError::Capacity)
68        );
69    }
70
71    #[test]
72    fn native_facade_exchanges_without_ip() {
73        let host = PeerHost::new(64 * 1024 * 1024).unwrap();
74        assert_eq!(host.exchange(b"hello-qpr").unwrap(), 9);
75    }
76
77    #[test]
78    fn exchange_protected_roundtrip_cap() {
79        let host = PeerHost::new(64 * 1024 * 1024).unwrap();
80        let mut app = [0u8; AUTHORISED_ROUNDTRIP_CAP];
81        let mut i = 0usize;
82        while i < app.len() {
83            app[i] = (i as u8).wrapping_add(0x3C);
84            i = i.saturating_add(1);
85        }
86        assert_eq!(
87            host.exchange_protected(&app).unwrap(),
88            AUTHORISED_ROUNDTRIP_CAP
89        );
90    }
91
92    #[test]
93    fn vertical_64_demo_still_works() {
94        assert_eq!(two_peer_ipc_exchange(b"qsync-hello").unwrap(), 11);
95        assert_eq!(
96            two_peer_ipc_exchange(&[0u8; 65]).unwrap_err(),
97            QdnfError::Capacity
98        );
99    }
100
101    #[test]
102    fn allow_enum_does_not_open_session() {
103        let _ = PolicyOutcome::Allow;
104        let host = PeerHost::new(64 * 1024 * 1024).unwrap();
105        let scope = ScopeEpoch { scope: 1, epoch: 1 };
106        let (mut a, _b) = host.pair(b"did:q42:a", b"did:q42:b", scope, 1280).unwrap();
107        let service = ServiceId::from_iri(b"q42:QSync/1").unwrap();
108        assert_eq!(a.open_session(service), Err(QdnfError::Unauthorized));
109    }
110
111    #[test]
112    fn send_without_announce_is_unauthorized() {
113        let host = PeerHost::new(64 * 1024 * 1024).unwrap();
114        let scope = ScopeEpoch { scope: 1, epoch: 1 };
115        let (mut a, b) = host.pair(b"did:q42:a", b"did:q42:b", scope, 1280).unwrap();
116        assert_eq!(
117            a.send_stream(&b.locator(), b"x"),
118            Err(QdnfError::Unauthorized)
119        );
120    }
121
122    #[test]
123    fn pair_uses_host_cell_bytes_and_builder_rejects_zero() {
124        assert_eq!(PeerHost::new(0), Err(QdnfError::Capacity));
125        assert_eq!(
126            PeerBuilder::new(b"did:q42:a", LinkId::ZERO, 0).unwrap_err(),
127            QdnfError::Capacity
128        );
129        let host = PeerHost::new(4096).unwrap();
130        let scope = ScopeEpoch { scope: 1, epoch: 1 };
131        let (a, _b) = host.pair(b"did:q42:a", b"did:q42:b", scope, 1280).unwrap();
132        assert_eq!(a.remaining_host_bytes(), 4096);
133    }
134}