Skip to main content

qualia_core_db/net/peer/host/
driver.rs

1//! Protected send/receive/close. Offsets commit only after accepted transfer.
2
3use super::session_table::SessionHandle;
4use super::NativePeer;
5use crate::net::peer::cells::pass_budget::{PassCharge, PassGuard};
6use crate::net::peer::runtime::{CancelEpoch, ResourceBudget};
7use crate::net::qdnf::authority::{ExecutionPermit, InstalledSessionKeys};
8use crate::net::qdnf::bearer::contract::Bearer;
9use crate::net::qdnf::errors::QdnfError;
10use crate::net::qdnf::frame::{copy_payload, decode_frame, encode_frame, FrameHeader};
11use crate::net::qdnf::registries::{FrameType, NextProtocol};
12use crate::net::qdnf::session::paths::PathHandle;
13use crate::net::qdnf::session::protected_ack::packet_number_of;
14use crate::net::qdnf::session::{ProtectedAckSession, ProtectedRecv, SessionBinding};
15use crate::net::qdnf::types::{LinkId, ObservedLocator};
16
17const SESSION_CHARGE: ResourceBudget = ResourceBudget {
18    bytes: 256,
19    work: 1,
20    io: 1,
21};
22
23/// Capture enough sealed bytes that [`require_protected`] can see ciphertext vs plaintext.
24const SEALED_CAPTURE: usize = 4096 + 64;
25
26/// Capture helper: last sealed frame bytes for the wire oracle (bounded).
27#[derive(Clone, Copy, Debug)]
28pub struct SealedFrame {
29    pub(crate) bytes: [u8; SEALED_CAPTURE],
30    pub(crate) len: u16,
31}
32
33impl SealedFrame {
34    /// Raw sealed-frame bytes.
35    pub fn as_slice(&self) -> &[u8] {
36        &self.bytes[..self.len as usize]
37    }
38
39    fn from_sealed(sealed: &[u8]) -> Self {
40        let mut out = Self {
41            bytes: [0u8; SEALED_CAPTURE],
42            len: 0,
43        };
44        let copy = sealed.len().min(out.bytes.len());
45        out.bytes[..copy].copy_from_slice(&sealed[..copy]);
46        out.len = copy as u16;
47        out
48    }
49}
50
51impl NativePeer {
52    /// `Ok(())` when not cancelled.
53    pub(super) fn require_not_cancelled(&self) -> Result<(), QdnfError> {
54        if self.cancelled {
55            Err(QdnfError::Cancelled)
56        } else {
57            Ok(())
58        }
59    }
60
61    /// `Ok(())` when primary.
62    pub(super) fn require_primary(&self) -> Result<SessionHandle, QdnfError> {
63        self.primary.ok_or(QdnfError::Unauthorized)
64    }
65
66    /// Verified neighbor for `dest`. Missing adjacency is [`QdnfError::NoRoute`].
67    pub(super) fn require_verified_dest(
68        &self,
69        dest: &ObservedLocator,
70    ) -> Result<LinkId, QdnfError> {
71        let remote = self.remote_or_reject()?;
72        let adj = self
73            .neighbors
74            .forwarding(remote)
75            .ok_or(QdnfError::NoRoute)?;
76        if adj.observed_peer.as_slice() != dest.as_slice() {
77            return Err(QdnfError::Unauthorized);
78        }
79        Ok(remote)
80    }
81
82    /// Activates a protected session (handshake + capability negotiation); returns the session handle.
83    pub fn activate_protected(
84        &mut self,
85        permit: ExecutionPermit,
86        keys: InstalledSessionKeys,
87        now_unix: u64,
88    ) -> Result<SessionHandle, QdnfError> {
89        if self.sessions.is_full() {
90            return Err(QdnfError::Capacity);
91        }
92        let session = SessionBinding::from_permit(&permit, &keys, now_unix)?;
93        let protection =
94            ProtectedAckSession::from_keys(*keys.send_key(), *keys.recv_key(), keys.generation())?;
95        let reservation = self.ledger.reserve(SESSION_CHARGE, true)?;
96        let handle = self.sessions.insert(session, protection, reservation)?;
97        if self.primary.is_none() {
98            self.primary = Some(handle);
99        }
100        Ok(handle)
101    }
102
103    /// Closes session `h`; `QdnfError` on unknown/invalid handle.
104    pub fn close_session(&mut self, h: SessionHandle) -> Result<(), QdnfError> {
105        self.sessions.close(h, &mut self.ledger)?;
106        if self.primary == Some(h) {
107            self.primary = self.sessions.first_live();
108        }
109        Ok(())
110    }
111
112    #[inline]
113    /// Number of live sessions.
114    pub fn live_session_count(&self) -> usize {
115        self.sessions.live_count()
116    }
117
118    #[inline]
119    /// Remaining host byte budget.
120    pub fn remaining_host_bytes(&self) -> u64 {
121        self.ledger.host_remaining_bytes()
122    }
123
124    #[inline]
125    /// The primary session handle, if any.
126    pub fn primary_session(&self) -> Option<SessionHandle> {
127        self.primary
128    }
129
130    /// Cancel in-flight send/recv. Does not commit application offsets.
131    pub fn cancel(&mut self) -> Result<CancelEpoch, QdnfError> {
132        self.cancel_epoch = self.cancel_epoch.next()?;
133        self.cancelled = true;
134        Ok(self.cancel_epoch)
135    }
136
137    /// Traffic-secret update. Does not mint a new permit or grant.
138    pub fn rekey_protected(
139        &mut self,
140        table: &mut crate::net::qdnf::session::rekey::RekeyTable,
141    ) -> Result<u64, QdnfError> {
142        self.require_not_cancelled()?;
143        let h = self.require_primary()?;
144        let _session = self.sessions.binding(h)?;
145        let protection = self.sessions.get_mut(h)?;
146        let next = table.rotate()?;
147        let (send, recv) = table.keys(next)?;
148        protection.install_update(send, recv, crate::net::qdnf::types::Generation(next))?;
149        Ok(next)
150    }
151
152    /// Charge one Sentinel network pass (accounting only; no 42 MiB map).
153    pub fn network_pass(&mut self, charge: PassCharge) -> Result<u64, QdnfError> {
154        let _ = self;
155        let mut guard = PassGuard::enter(&charge)?;
156        let n = guard.charged();
157        guard.success();
158        Ok(n)
159    }
160
161    /// Sends stream bytes on the primary session.
162    pub fn send_stream(
163        &mut self,
164        dest: &ObservedLocator,
165        payload: &[u8],
166    ) -> Result<usize, QdnfError> {
167        let _ = self.send_protected(dest, payload)?;
168        Ok(payload.len())
169    }
170
171    /// Receives stream bytes into `out`; returns bytes read.
172    pub fn recv_stream(&mut self, out: &mut [u8]) -> Result<usize, QdnfError> {
173        self.recv_protected(out)
174    }
175
176    /// Sends a protected frame on the primary session.
177    pub fn send_protected(
178        &mut self,
179        dest: &ObservedLocator,
180        payload: &[u8],
181    ) -> Result<SealedFrame, QdnfError> {
182        let h = self.require_primary()?;
183        self.send_protected_on(h, dest, payload)
184    }
185
186    /// Sends a protected frame on session `h`.
187    pub fn send_protected_on(
188        &mut self,
189        h: SessionHandle,
190        dest: &ObservedLocator,
191        payload: &[u8],
192    ) -> Result<SealedFrame, QdnfError> {
193        let path = self.ensure_primary_path()?;
194        self.send_protected_with_path(h, path, dest, payload)
195    }
196
197    /// Sends protected with path.
198    pub(super) fn send_protected_with_path(
199        &mut self,
200        h: SessionHandle,
201        path: PathHandle,
202        dest: &ObservedLocator,
203        payload: &[u8],
204    ) -> Result<SealedFrame, QdnfError> {
205        self.require_not_cancelled()?;
206        let session = self.sessions.binding(h)?;
207        session.admit_application()?;
208        let _remote = self.require_verified_dest(dest)?;
209        const MAX_PROTECTED_PAYLOAD: usize = 4096;
210        const PROTECTED_SEAL_CAP: usize = MAX_PROTECTED_PAYLOAD + 24;
211        const PROTECTED_WIRE_CAP: usize = 80 + PROTECTED_SEAL_CAP;
212        if payload.len() > MAX_PROTECTED_PAYLOAD {
213            return Err(QdnfError::Capacity);
214        }
215        let _ = self.sessions.path_cc.path_rtt(path)?;
216        if !payload.is_empty() {
217            self.sessions
218                .path_cc
219                .check_send(path, payload.len() as u64)?;
220        }
221        let mut pass = PassGuard::enter(&PassCharge {
222            arena: 0,
223            scratch: payload.len() as u64,
224            crypto: 24,
225            kernel: 80,
226            pinned: 0,
227        })?;
228        let mut pt = [0u8; MAX_PROTECTED_PAYLOAD];
229        pt[..payload.len()].copy_from_slice(payload);
230        let mut sealed = [0u8; PROTECTED_SEAL_CAP];
231        let n = {
232            let protection = self.sessions.get_mut(h)?;
233            protection.seal_tracked(b"qsession/stream", &mut pt[..payload.len()], &mut sealed)?
234        };
235        if !payload.is_empty() {
236            let pn = packet_number_of(&sealed[..n], n)?;
237            self.sessions.path_cc.send(path, pn, payload.len() as u64)?;
238        }
239        let mut header = FrameHeader::new(FrameType::SessionStream, NextProtocol::QSession);
240        header.source_link_id = self.local_link;
241        header.payload_len = n as u16;
242        let mut wire = [0u8; PROTECTED_WIRE_CAP];
243        let wn = encode_frame(&header, &sealed[..n], &mut wire)?;
244        match self.bearer.send(dest, &wire[..wn]) {
245            Ok(sent) if sent == wn => {
246                let len = u16::try_from(payload.len()).map_err(|_| QdnfError::Capacity)?;
247                self.sessions.commit_send_offset(h, len)?;
248                pass.success();
249                Ok(SealedFrame::from_sealed(&sealed[..n]))
250            }
251            Ok(_) => Err(QdnfError::WouldBlock),
252            Err(e) => Err(e),
253        }
254    }
255
256    /// Receives a protected frame into `out` on the primary session.
257    pub fn recv_protected(&mut self, out: &mut [u8]) -> Result<usize, QdnfError> {
258        let h = self.require_primary()?;
259        self.recv_protected_on(h, out)
260    }
261
262    /// Receives a protected frame on session `h`.
263    pub fn recv_protected_on(
264        &mut self,
265        h: SessionHandle,
266        out: &mut [u8],
267    ) -> Result<usize, QdnfError> {
268        self.require_not_cancelled()?;
269        let session = self.sessions.binding(h)?;
270        session.admit_application()?;
271        let _ = self.remote_or_reject()?;
272        const MAX_PROTECTED_PAYLOAD: usize = 4096;
273        const PROTECTED_SEAL_CAP: usize = MAX_PROTECTED_PAYLOAD + 24;
274        const PROTECTED_WIRE_CAP: usize = 80 + PROTECTED_SEAL_CAP;
275        let mut wire = [0u8; PROTECTED_WIRE_CAP];
276        let (got, _meta) = self.bearer.recv(&mut wire)?;
277        let (decoded, off, len) = decode_frame(&wire[..got])?;
278        if decoded.frame_type != FrameType::SessionStream {
279            return Err(QdnfError::Malformed);
280        }
281        let mut sealed = [0u8; PROTECTED_SEAL_CAP];
282        let copied = copy_payload(&wire[..got], off, len, &mut sealed)?;
283        let protection = self.sessions.get_mut(h)?;
284        match protection.open_tracked(b"qsession/stream", &sealed[..copied], out)? {
285            (ProtectedRecv::Delivered, n) => Ok(n),
286            (ProtectedRecv::Duplicate, _) => Err(QdnfError::Replay),
287        }
288    }
289
290    /// Poll until `deadline_unix`. Empty queue before the deadline is WouldBlock;
291    /// at/after the deadline with nothing is Expired.
292    pub fn poll_recv(
293        &mut self,
294        now_unix: u64,
295        deadline_unix: u64,
296        out: &mut [u8],
297    ) -> Result<usize, QdnfError> {
298        match self.recv_protected(out) {
299            Ok(n) => Ok(n),
300            Err(QdnfError::WouldBlock) => {
301                if now_unix >= deadline_unix {
302                    Err(QdnfError::Expired)
303                } else {
304                    Err(QdnfError::WouldBlock)
305                }
306            }
307            Err(e) => Err(e),
308        }
309    }
310}
311
312#[cfg(test)]
313mod tests {
314    use super::*;
315    use crate::net::peer::cells::pass_budget::{PassCharge, SENTINEL_PASS_TOTAL};
316    use crate::net::qdnf::types::ScopeEpoch;
317
318    #[test]
319    fn network_pass_charges_scratch_crypto_kernel() {
320        let scope = ScopeEpoch { scope: 1, epoch: 1 };
321        let (mut a, _b) = NativePeer::pair_ipc(b"did:q42:a", b"did:q42:b", scope, 1280).unwrap();
322        let ok = PassCharge {
323            scratch: 16,
324            crypto: 16,
325            kernel: 16,
326            ..PassCharge::ZERO
327        };
328        assert_eq!(a.network_pass(ok).unwrap(), 48);
329        let over = PassCharge {
330            scratch: SENTINEL_PASS_TOTAL,
331            crypto: 1,
332            kernel: 1,
333            ..PassCharge::ZERO
334        };
335        assert_eq!(a.network_pass(over).unwrap_err(), QdnfError::Capacity);
336        let dest = crate::net::qdnf::types::ObservedLocator::from_slice(&[0x02]).unwrap();
337        assert_eq!(
338            a.send_protected(&dest, b"x").unwrap_err(),
339            QdnfError::Unauthorized
340        );
341    }
342}