Skip to main content

qualia_core_db/net/qdnf/bearer/
ipc.rs

1//! In-process `local-ipc-v1` bearer. No IP, DNS, or libp2p.
2
3use std::sync::{Arc, Mutex};
4
5use crate::net::qdnf::errors::QdnfError;
6use crate::net::qdnf::registries::BearerProfile;
7use crate::net::qdnf::types::{ObservedLocator, ScopeEpoch};
8
9use super::contract::{check_frame_mtu, Bearer, BearerCapabilities, RecvMeta};
10
11const QUEUE_CAP: usize = 32;
12/// In-process `local-ipc-v1` frame cap. Not Ethernet [`super::mtu::MAX_QDNF_MTU`].
13pub const FRAME_CAP: usize = 8192;
14
15#[derive(Clone, Copy)]
16struct QueuedFrame {
17    src: ObservedLocator,
18    len: usize,
19    bytes: [u8; FRAME_CAP],
20}
21
22struct PairState {
23    a_to_b: Box<[QueuedFrame; QUEUE_CAP]>,
24    a_len: usize,
25    b_to_a: Box<[QueuedFrame; QUEUE_CAP]>,
26    b_len: usize,
27    closed: bool,
28}
29
30// Cold-only fixed queue construction. Never materialize the ~512KiB pair on
31// the caller stack. The actual bearer owner must admit this existing backing.
32fn empty_queue() -> Result<Box<[QueuedFrame; QUEUE_CAP]>, QdnfError> {
33    let mut frames = Vec::new();
34    frames
35        .try_reserve_exact(QUEUE_CAP)
36        .map_err(|_| QdnfError::Capacity)?;
37    for _ in 0..QUEUE_CAP {
38        frames.push(QueuedFrame {
39            src: ObservedLocator::EMPTY,
40            len: 0,
41            bytes: [0; FRAME_CAP],
42        });
43    }
44    frames
45        .into_boxed_slice()
46        .try_into()
47        .map_err(|_| QdnfError::Capacity)
48}
49impl PairState {
50    fn empty() -> Result<Self, QdnfError> {
51        Ok(Self {
52            a_to_b: empty_queue()?,
53            a_len: 0,
54            b_to_a: empty_queue()?,
55            b_len: 0,
56            closed: false,
57        })
58    }
59}
60// Only fixed heap-queue owners/indices cross constructor/Arc/Mutex value moves.
61const _: () = assert!(core::mem::size_of::<PairState>() <= 128);
62
63/// One end of a same-device IPC pair.
64pub struct IpcEndpoint {
65    id: u8,
66    locator: ObservedLocator,
67    scope: ScopeEpoch,
68    mtu: u16,
69    state: Arc<Mutex<PairState>>,
70}
71
72impl IpcEndpoint {
73    /// Bearer capabilities.
74    pub fn capabilities(&self) -> BearerCapabilities {
75        BearerCapabilities {
76            profile: BearerProfile::LocalIpcV1,
77            mtu: self.mtu,
78            group_delivery: false,
79            ordered: true,
80            may_duplicate: false,
81        }
82    }
83
84    fn queue<'a>(
85        state: &'a mut PairState,
86        is_a: bool,
87    ) -> (&'a mut [QueuedFrame; QUEUE_CAP], &'a mut usize) {
88        if is_a {
89            (&mut *state.a_to_b, &mut state.a_len)
90        } else {
91            (&mut *state.b_to_a, &mut state.b_len)
92        }
93    }
94}
95
96/// Construct a connected IPC pair with boot-scoped locators `0x01` and `0x02`.
97pub fn ipc_pair(scope: ScopeEpoch, mtu: u16) -> Result<(IpcEndpoint, IpcEndpoint), QdnfError> {
98    if mtu as usize > FRAME_CAP {
99        return Err(QdnfError::Capacity);
100    }
101    let state = Arc::new(Mutex::new(PairState::empty()?));
102    let a = IpcEndpoint {
103        id: 0,
104        locator: ObservedLocator::from_slice(&[0x01])?,
105        scope,
106        mtu,
107        state: state.clone(),
108    };
109    let b = IpcEndpoint {
110        id: 1,
111        locator: ObservedLocator::from_slice(&[0x02])?,
112        scope,
113        mtu,
114        state,
115    };
116    Ok((a, b))
117}
118
119impl Bearer for IpcEndpoint {
120    fn profile(&self) -> BearerProfile {
121        BearerProfile::LocalIpcV1
122    }
123
124    fn mtu(&self) -> u16 {
125        self.mtu
126    }
127
128    fn scope(&self) -> ScopeEpoch {
129        self.scope
130    }
131
132    fn send(&mut self, dest: &ObservedLocator, frame: &[u8]) -> Result<usize, QdnfError> {
133        check_frame_mtu(frame.len(), self.mtu)?;
134        if frame.len() > FRAME_CAP {
135            return Err(QdnfError::Capacity);
136        }
137        let mut state = self.state.lock().map_err(|_| QdnfError::Closed)?;
138        if state.closed {
139            return Err(QdnfError::Closed);
140        }
141        let is_a = self.id == 0;
142        let expected = if is_a {
143            ObservedLocator::from_slice(&[0x02]).unwrap()
144        } else {
145            ObservedLocator::from_slice(&[0x01]).unwrap()
146        };
147        if dest.as_slice() != expected.as_slice() {
148            return Err(QdnfError::Unauthorized);
149        }
150        let (queue, len) = IpcEndpoint::queue(&mut state, is_a);
151        if *len >= QUEUE_CAP {
152            return Err(QdnfError::WouldBlock);
153        }
154        queue[*len].src = self.locator;
155        queue[*len].len = frame.len();
156        queue[*len].bytes[..frame.len()].copy_from_slice(frame);
157        *len += 1;
158        Ok(frame.len())
159    }
160
161    fn recv(&mut self, out: &mut [u8]) -> Result<(usize, RecvMeta), QdnfError> {
162        let mut state = self.state.lock().map_err(|_| QdnfError::Closed)?;
163        if state.closed {
164            return Err(QdnfError::Closed);
165        }
166        let is_a = self.id == 0;
167        let (queue, len) = IpcEndpoint::queue(&mut state, !is_a);
168        if *len == 0 {
169            return Err(QdnfError::WouldBlock);
170        }
171        let frame = queue[0];
172        if out.len() < frame.len {
173            return Err(QdnfError::Capacity);
174        }
175        for i in 0..*len - 1 {
176            queue[i] = queue[i + 1];
177        }
178        *len -= 1;
179        out[..frame.len].copy_from_slice(&frame.bytes[..frame.len]);
180        Ok((
181            frame.len,
182            RecvMeta {
183                observed_source: frame.src,
184                scope: self.scope,
185                mtu: self.mtu,
186            },
187        ))
188    }
189
190    fn shutdown(&mut self) -> Result<(), QdnfError> {
191        let mut state = self.state.lock().map_err(|_| QdnfError::Closed)?;
192        state.closed = true;
193        state.a_len = 0;
194        state.b_len = 0;
195        Ok(())
196    }
197}
198
199impl IpcEndpoint {
200    /// Bearer locator.
201    pub fn locator(&self) -> ObservedLocator {
202        self.locator
203    }
204}
205
206#[cfg(test)]
207mod tests {
208    use super::*;
209    use crate::net::qdnf::frame::{encode_frame, FrameHeader};
210    use crate::net::qdnf::registries::{FrameType, NextProtocol};
211
212    #[test]
213    fn cold_fixed_heap_queues_preserve_capacity_order_metadata_and_zero_heap_hot_io() {
214        use crate::specialized_libs::computational_geometry::allocation_counter::AllocGuard;
215        assert!(core::mem::size_of::<PairState>() <= 128);
216        let scope = ScopeEpoch { scope: 7, epoch: 9 };
217        let (mut a, mut b) = ipc_pair(scope, 1280).unwrap();
218        let mut header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
219        header.payload_len = 1;
220        let mut wire = [0u8; 81];
221        let mut out = [0u8; 128];
222        let dest = b.locator();
223        encode_frame(&header, &[0], &mut wire).unwrap();
224        a.send(&dest, &wire).unwrap();
225        b.recv(&mut out).unwrap(); // warmup
226        let measure = AllocGuard::begin("actual fixed IPC queues", true);
227        for n in 0..QUEUE_CAP {
228            encode_frame(&header, &[n as u8], &mut wire).unwrap();
229            assert_eq!(a.send(&dest, &wire), Ok(81));
230        }
231        assert_eq!(a.send(&dest, &wire), Err(QdnfError::WouldBlock));
232        for n in 0..QUEUE_CAP {
233            let (len, meta) = b.recv(&mut out).unwrap();
234            assert_eq!(len, 81);
235            assert_eq!(out[80], n as u8);
236            assert_eq!(meta.observed_source, a.locator());
237            assert_eq!(meta.scope, scope);
238        }
239        assert_eq!(b.recv(&mut out), Err(QdnfError::WouldBlock));
240        measure.check().unwrap();
241        let positive = AllocGuard::begin("IPC queue positive control", true);
242        std::hint::black_box(vec![1u8; 8]);
243        assert!(positive.check().is_err());
244    }
245
246    #[test]
247    fn ipc_exchanges_qframe_without_ip() {
248        let scope = ScopeEpoch { scope: 1, epoch: 1 };
249        let (mut a, mut b) = ipc_pair(scope, 1280).unwrap();
250        let mut header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
251        header.payload_len = 2;
252        let mut wire = [0u8; 128];
253        let n = encode_frame(&header, &[0xAA, 0xBB], &mut wire).unwrap();
254        a.send(&b.locator(), &wire[..n]).unwrap();
255        let mut out = [0u8; 128];
256        let (got, meta) = b.recv(&mut out).unwrap();
257        assert_eq!(got, n);
258        assert_eq!(meta.observed_source.as_slice(), &[0x01]);
259        assert_eq!(a.profile(), BearerProfile::LocalIpcV1);
260        assert!(a.profile().native_independent());
261    }
262
263    #[test]
264    fn short_recv_buffer_does_not_drop_frame() {
265        let scope = ScopeEpoch { scope: 1, epoch: 1 };
266        let (mut a, mut b) = ipc_pair(scope, 1280).unwrap();
267        let mut header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
268        header.payload_len = 2;
269        let mut wire = [0u8; 128];
270        let n = encode_frame(&header, &[0xAA, 0xBB], &mut wire).unwrap();
271        a.send(&b.locator(), &wire[..n]).unwrap();
272        let mut tiny = [0u8; 4];
273        assert_eq!(b.recv(&mut tiny), Err(QdnfError::Capacity));
274        let mut out = [0u8; 128];
275        let (got, meta) = b.recv(&mut out).unwrap();
276        assert_eq!(got, n);
277        assert_eq!(&out[..n], &wire[..n]);
278        assert_eq!(meta.observed_source.as_slice(), &[0x01]);
279        assert_eq!(b.recv(&mut out), Err(QdnfError::WouldBlock));
280    }
281
282    #[test]
283    fn local_ipc_frame_cap_fits_authorised_payload() {
284        assert_eq!(FRAME_CAP, 8192);
285        let scope = ScopeEpoch { scope: 1, epoch: 1 };
286        assert!(ipc_pair(scope, FRAME_CAP as u16).is_ok());
287        match ipc_pair(scope, (FRAME_CAP as u16).saturating_add(1)) {
288            Err(e) => assert_eq!(e, QdnfError::Capacity),
289            Ok(_) => panic!("mtu above FRAME_CAP must be Capacity"),
290        }
291    }
292}