Skip to main content

qualia_core_db/net/qdnf/bearer/
leased_ipc.rs

1//! Lease-gated wrapper around `IpcEndpoint`.
2//!
3//! Transmit/receive capacity is reserved on a caller-owned `LeaseTable`
4//! for the duration of the copy into or out of the IPC queue. The queue
5//! then owns the frame bytes, so the lease is released before return.
6//!
7//! `IpcEndpoint::recv` checks `out.len()` before dequeue. A short output
8//! returns `Capacity` and leaves the frame queued. This wrapper still
9//! releases the recv lease on that `Capacity` so the table cannot leak.
10
11use crate::net::peer::runtime::{BufferLease, LeaseTable};
12use crate::net::qdnf::errors::QdnfError;
13use crate::net::qdnf::types::{ObservedLocator, ScopeEpoch};
14
15use super::contract::{check_frame_mtu, Bearer, RecvMeta};
16use super::ipc::{ipc_pair, IpcEndpoint};
17use super::lifecycle::{BearerLifecycle, BearerPhase};
18
19pub struct LeasedIpc {
20    inner: IpcEndpoint,
21    lifecycle: BearerLifecycle,
22}
23
24impl LeasedIpc {
25    /// Construct Ready from an existing connected endpoint.
26    pub fn from_endpoint(ep: IpcEndpoint) -> Self {
27        let mut lifecycle = BearerLifecycle::new(ep.mtu());
28        let _ = lifecycle.begin_init();
29        let _ = lifecycle.finish_init();
30        Self {
31            inner: ep,
32            lifecycle,
33        }
34    }
35
36    /// Sends a leased IPC frame.
37    pub fn send_leased(
38        &mut self,
39        leases: &mut LeaseTable,
40        dest: &ObservedLocator,
41        frame: &[u8],
42    ) -> Result<usize, QdnfError> {
43        if self.lifecycle.phase() != BearerPhase::Ready {
44            return Err(QdnfError::Closed);
45        }
46        check_frame_mtu(frame.len(), self.lifecycle.mtu())?;
47        let cap = u32::try_from(frame.len()).map_err(|_| QdnfError::Capacity)?;
48        let lease = leases.acquire(cap, true)?;
49        let sent = self.inner.send(dest, frame);
50        finish_lease(leases, lease, sent)
51    }
52
53    /// Receives a leased IPC frame.
54    pub fn recv_leased(
55        &mut self,
56        leases: &mut LeaseTable,
57        out: &mut [u8],
58    ) -> Result<(usize, RecvMeta), QdnfError> {
59        match self.lifecycle.phase() {
60            BearerPhase::Ready | BearerPhase::Draining => {}
61            _ => return Err(QdnfError::Closed),
62        }
63        let cap = u32::try_from(out.len()).map_err(|_| QdnfError::Capacity)?;
64        let lease = leases.acquire(cap, true)?;
65        let recvd = self.inner.recv(out);
66        finish_lease(leases, lease, recvd)
67    }
68
69    /// Drains the channel then shuts down; `inner_shutdown` controls the inner transport.
70    pub fn drain_and_shutdown(&mut self, inner_shutdown: bool) -> Result<(), QdnfError> {
71        if self.lifecycle.phase() == BearerPhase::Ready {
72            self.lifecycle.begin_drain()?;
73        }
74        self.lifecycle.shutdown()?;
75        if inner_shutdown {
76            self.inner.shutdown()?;
77        }
78        Ok(())
79    }
80
81    #[inline]
82    /// `LeasedIpc::lifecycle`.
83    pub fn lifecycle(&self) -> &BearerLifecycle {
84        &self.lifecycle
85    }
86
87    #[inline]
88    /// Locator.
89    pub fn locator(&self) -> ObservedLocator {
90        self.inner.locator()
91    }
92}
93
94/// Connected Ready pair with boot-scoped locators `0x01` and `0x02`.
95pub fn leased_ipc_pair(scope: ScopeEpoch, mtu: u16) -> Result<(LeasedIpc, LeasedIpc), QdnfError> {
96    let (a, b) = ipc_pair(scope, mtu)?;
97    Ok((LeasedIpc::from_endpoint(a), LeasedIpc::from_endpoint(b)))
98}
99
100fn finish_lease<T>(
101    leases: &mut LeaseTable,
102    lease: BufferLease,
103    result: Result<T, QdnfError>,
104) -> Result<T, QdnfError> {
105    match result {
106        Ok(v) => {
107            leases.release(lease.handle)?;
108            Ok(v)
109        }
110        Err(e) => {
111            let _ = leases.release(lease.handle);
112            Err(e)
113        }
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use crate::net::peer::runtime::{LeaseTable, LEASE_SLOTS};
121    use crate::net::qdnf::bearer::lifecycle::BearerPhase;
122    use crate::net::qdnf::errors::QdnfError;
123    use crate::net::qdnf::frame::{encode_frame, FrameHeader};
124    use crate::net::qdnf::registries::{FrameType, NextProtocol};
125    use crate::net::qdnf::types::ScopeEpoch;
126
127    fn encode_beacon(out: &mut [u8]) -> usize {
128        let mut header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
129        header.payload_len = 2;
130        encode_frame(&header, &[0xAA, 0xBB], out).unwrap()
131    }
132
133    fn pair() -> (LeasedIpc, LeasedIpc, LeaseTable) {
134        let scope = ScopeEpoch { scope: 1, epoch: 1 };
135        let (a, b) = leased_ipc_pair(scope, 1280).unwrap();
136        (a, b, LeaseTable::new())
137    }
138
139    #[test]
140    fn round_trip_qframe_observed_source_is_locator() {
141        let (mut a, mut b, mut leases) = pair();
142        let mut wire = [0u8; 128];
143        let n = encode_beacon(&mut wire);
144        a.send_leased(&mut leases, &b.locator(), &wire[..n])
145            .unwrap();
146        let mut out = [0u8; 128];
147        let (got, meta) = b.recv_leased(&mut leases, &mut out).unwrap();
148        assert_eq!(got, n);
149        assert_eq!(meta.observed_source.as_slice(), &[0x01]);
150        assert_eq!(&out[..n], &wire[..n]);
151        assert_eq!(leases.occupied_count(), 0);
152    }
153
154    #[test]
155    fn send_leased_releases_lease() {
156        let (mut a, b, mut leases) = pair();
157        let mut wire = [0u8; 128];
158        let n = encode_beacon(&mut wire);
159        a.send_leased(&mut leases, &b.locator(), &wire[..n])
160            .unwrap();
161        assert_eq!(leases.occupied_count(), 0);
162    }
163
164    #[test]
165    fn short_recv_buffer_is_capacity() {
166        let (mut a, mut b, mut leases) = pair();
167        let mut wire = [0u8; 128];
168        let n = encode_beacon(&mut wire);
169        a.send_leased(&mut leases, &b.locator(), &wire[..n])
170            .unwrap();
171        let mut tiny = [0u8; 4];
172        assert_eq!(
173            b.recv_leased(&mut leases, &mut tiny),
174            Err(QdnfError::Capacity)
175        );
176        assert_eq!(leases.occupied_count(), 0);
177        let mut out = [0u8; 128];
178        let (got, meta) = b.recv_leased(&mut leases, &mut out).unwrap();
179        assert_eq!(got, n);
180        assert_eq!(&out[..n], &wire[..n]);
181        assert_eq!(meta.observed_source.as_slice(), &[0x01]);
182        assert_eq!(leases.occupied_count(), 0);
183        assert_eq!(
184            b.recv_leased(&mut leases, &mut out),
185            Err(QdnfError::WouldBlock)
186        );
187    }
188
189    #[test]
190    fn drain_and_shutdown_closes_send() {
191        let (mut a, b, mut leases) = pair();
192        a.drain_and_shutdown(true).unwrap();
193        assert_eq!(a.lifecycle().phase(), BearerPhase::Closed);
194        let mut wire = [0u8; 128];
195        let n = encode_beacon(&mut wire);
196        assert_eq!(
197            a.send_leased(&mut leases, &b.locator(), &wire[..n]),
198            Err(QdnfError::Closed)
199        );
200    }
201
202    #[test]
203    fn shutdown_then_send_leased_is_closed() {
204        let (mut a, b, mut leases) = pair();
205        a.drain_and_shutdown(false).unwrap();
206        a.drain_and_shutdown(false).unwrap();
207        let mut wire = [0u8; 128];
208        let n = encode_beacon(&mut wire);
209        assert_eq!(
210            a.send_leased(&mut leases, &b.locator(), &wire[..n]),
211            Err(QdnfError::Closed)
212        );
213    }
214
215    #[test]
216    fn sequential_sends_and_queue_backpressure() {
217        let (mut a, mut b, mut leases) = pair();
218        let dest = b.locator();
219        let mut wire = [0u8; 128];
220        let n = encode_beacon(&mut wire);
221        a.send_leased(&mut leases, &dest, &wire[..n]).unwrap();
222        a.send_leased(&mut leases, &dest, &wire[..n]).unwrap();
223        assert_eq!(leases.occupied_count(), 0);
224        let mut out = [0u8; 128];
225        b.recv_leased(&mut leases, &mut out).unwrap();
226        b.recv_leased(&mut leases, &mut out).unwrap();
227
228        for _ in 0..32 {
229            a.send_leased(&mut leases, &dest, &wire[..n]).unwrap();
230        }
231        assert_eq!(
232            a.send_leased(&mut leases, &dest, &wire[..n]),
233            Err(QdnfError::WouldBlock)
234        );
235        assert_eq!(leases.occupied_count(), 0);
236    }
237
238    #[test]
239    fn thirty_three_sequential_sends_succeed_when_queue_drained() {
240        let (mut a, mut b, mut leases) = pair();
241        let dest = b.locator();
242        let mut wire = [0u8; 128];
243        let n = encode_beacon(&mut wire);
244        let mut out = [0u8; 128];
245        for _ in 0..33 {
246            a.send_leased(&mut leases, &dest, &wire[..n]).unwrap();
247            b.recv_leased(&mut leases, &mut out).unwrap();
248            assert_eq!(leases.occupied_count(), 0);
249        }
250    }
251
252    #[test]
253    fn held_table_blocks_tx_reservation() {
254        let (mut a, b, mut leases) = pair();
255        for _ in 0..LEASE_SLOTS {
256            leases.acquire(8, true).unwrap();
257        }
258        assert_eq!(leases.occupied_count(), LEASE_SLOTS);
259        let mut wire = [0u8; 128];
260        let n = encode_beacon(&mut wire);
261        assert_eq!(
262            a.send_leased(&mut leases, &b.locator(), &wire[..n]),
263            Err(QdnfError::Capacity)
264        );
265        assert_eq!(leases.occupied_count(), LEASE_SLOTS);
266    }
267
268    #[test]
269    fn recv_allowed_while_draining() {
270        let (mut a, mut b, mut leases) = pair();
271        let mut wire = [0u8; 128];
272        let n = encode_beacon(&mut wire);
273        a.send_leased(&mut leases, &b.locator(), &wire[..n])
274            .unwrap();
275        // Drain the sender; the queued frame is still readable on b.
276        a.lifecycle_begin_drain_for_test();
277        assert_eq!(
278            a.send_leased(&mut leases, &b.locator(), &wire[..n]),
279            Err(QdnfError::Closed)
280        );
281        let mut out = [0u8; 128];
282        let (got, meta) = b.recv_leased(&mut leases, &mut out).unwrap();
283        assert_eq!(got, n);
284        assert_eq!(meta.observed_source.as_slice(), &[0x01]);
285    }
286}
287
288impl LeasedIpc {
289    #[cfg(test)]
290    fn lifecycle_begin_drain_for_test(&mut self) {
291        self.lifecycle.begin_drain().unwrap();
292    }
293}