qualia_core_db/net/qdnf/bearer/
leased_ipc.rs1use 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 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 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 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 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 pub fn lifecycle(&self) -> &BearerLifecycle {
84 &self.lifecycle
85 }
86
87 #[inline]
88 pub fn locator(&self) -> ObservedLocator {
90 self.inner.locator()
91 }
92}
93
94pub 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 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}