Skip to main content

qualia_core_db/p2p/
sync_ops.rs

1//! **libp2p op-transfer sync** (T3.1 p2p backend) — the wire protocol + reference relay that actually
2//! carries synchronisation operations peer-to-peer over the existing libp2p request-response swarm.
3//!
4//! Distinct from [`super::protocol`]'s `QualiaRequest::Sync`, which is only an *authorisation handshake*
5//! (hop-count / gatekeeper / target-shapes) and transfers no operations. This module adds the missing
6//! piece: **`Publish` / `PullSince` frames that move opaque, already-signed operation bytes**, plus a
7//! [`SyncOpRelay`] responder store. Operations travel as opaque `Vec<u8>` frames (the sync layer that
8//! owns the `SyncOperation` type serialises/deserialises them), so this stays a **dumb pipe**: it never
9//! validates or trusts — all trust remains in the consuming node's fail-closed inbox, exactly as the
10//! HTTP relay transport does. Encryption + auth come from libp2p's noise handshake on the connection.
11//!
12//! Native-only (libp2p). The swarm-driving `SyncTransport` bridge that maps the blocking
13//! publish/pull trait onto this protocol is the next step; this is the tested wire + store foundation.
14
15#![cfg(not(target_arch = "wasm32"))]
16
17use async_trait::async_trait;
18use libp2p::futures::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
19use libp2p::request_response::Codec;
20use libp2p::StreamProtocol;
21use serde::{de::DeserializeOwned, Deserialize, Serialize};
22use std::io;
23use std::sync::{Arc, Mutex};
24
25/// The request-response stream protocol id for op transfer (distinct from `/qualia/crdt-sync/1.0.0`).
26pub const SYNC_OP_PROTOCOL: &str = "/qualia/sync-ops/1.0.0";
27
28/// A hard cap on a single frame's encoded size, so a hostile peer cannot force an unbounded allocation.
29const MAX_FRAME_BYTES: usize = 64 * 1024 * 1024;
30
31/// A request in the op-transfer protocol. `op_frames` are opaque, already-signed operation bytes.
32#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
33pub enum SyncOpRequest {
34    /// Offer operations to the peer. Idempotent at the relay (dedup by frame content).
35    Publish { op_frames: Vec<Vec<u8>> },
36    /// Ask for operations the relay holds after `cursor` (`0` = from the start).
37    PullSince { cursor: u64 },
38}
39
40/// A response in the op-transfer protocol.
41#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
42pub enum SyncOpResponse {
43    /// How many *new* (non-duplicate) frames the publish added.
44    Published { accepted: u64 },
45    /// The frames after the requested cursor, plus the cursor to use next time.
46    Pulled {
47        op_frames: Vec<Vec<u8>>,
48        next_cursor: u64,
49    },
50}
51
52/// A reference op relay/store — append-only, dedup by frame content, cursor = position. The responder
53/// side of the protocol. A **dumb pipe**: it stores and serves opaque frames and trusts nothing.
54/// Cloning yields another handle onto the **same** store (so a node can both serve and be queried).
55#[derive(Clone, Default)]
56pub struct SyncOpRelay {
57    frames: Arc<Mutex<Vec<Vec<u8>>>>,
58}
59
60impl SyncOpRelay {
61    /// Creates a default `SyncOpRelay`.
62    pub fn new() -> Self {
63        Self::default()
64    }
65
66    /// Add frames, skipping any already present (dedup by content). Returns the number newly added.
67    pub fn publish(&self, op_frames: &[Vec<u8>]) -> u64 {
68        let mut store = self.frames.lock().expect("relay lock");
69        let mut accepted = 0;
70        for f in op_frames {
71            if !store.iter().any(|e| e == f) {
72                store.push(f.clone());
73                accepted += 1;
74            }
75        }
76        accepted
77    }
78
79    /// The frames after `cursor` (in store order) plus the next cursor. Re-pulling is safe.
80    pub fn pull_since(&self, cursor: u64) -> (Vec<Vec<u8>>, u64) {
81        let store = self.frames.lock().expect("relay lock");
82        let start = (cursor as usize).min(store.len());
83        (store[start..].to_vec(), store.len() as u64)
84    }
85
86    /// Number of distinct frames held.
87    pub fn len(&self) -> usize {
88        self.frames.lock().map(|v| v.len()).unwrap_or(0)
89    }
90
91    /// `true` when empty.
92    pub fn is_empty(&self) -> bool {
93        self.len() == 0
94    }
95
96    /// Serve one request against the store — the responder's request→response handler.
97    pub fn handle(&self, req: SyncOpRequest) -> SyncOpResponse {
98        match req {
99            SyncOpRequest::Publish { op_frames } => SyncOpResponse::Published {
100                accepted: self.publish(&op_frames),
101            },
102            SyncOpRequest::PullSince { cursor } => {
103                let (op_frames, next_cursor) = self.pull_since(cursor);
104                SyncOpResponse::Pulled {
105                    op_frames,
106                    next_cursor,
107                }
108            }
109        }
110    }
111}
112
113/// The libp2p request-response wire codec for op transfer: length-prefixed plain-CBOR (ciborium). Mirrors
114/// [`super::protocol::QualiaSyncCodec`]'s framing (4-byte big-endian length + body), without the Q42
115/// CBOR-LD term-compaction (the payload is opaque operation bytes, so there is nothing to term-compact).
116#[derive(Clone, Default)]
117pub struct SyncOpCodec;
118
119async fn read_frame<T, V>(io: &mut T) -> io::Result<V>
120where
121    T: AsyncRead + Unpin + Send,
122    V: DeserializeOwned,
123{
124    let mut len_buf = [0u8; 4];
125    io.read_exact(&mut len_buf).await?;
126    let len = u32::from_be_bytes(len_buf) as usize;
127    if len > MAX_FRAME_BYTES {
128        return Err(io::Error::new(
129            io::ErrorKind::InvalidData,
130            "sync-op frame too large",
131        ));
132    }
133    let mut buf = vec![0u8; len];
134    io.read_exact(&mut buf).await?;
135    ciborium::from_reader(&buf[..])
136        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e.to_string()))
137}
138
139async fn write_frame<T, V>(io: &mut T, v: &V) -> io::Result<()>
140where
141    T: AsyncWrite + Unpin + Send,
142    V: Serialize,
143{
144    let mut buf = Vec::new();
145    ciborium::into_writer(v, &mut buf)
146        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e.to_string()))?;
147    io.write_all(&(buf.len() as u32).to_be_bytes()).await?;
148    io.write_all(&buf).await?;
149    Ok(())
150}
151
152#[async_trait]
153impl Codec for SyncOpCodec {
154    type Protocol = StreamProtocol;
155    type Request = SyncOpRequest;
156    type Response = SyncOpResponse;
157
158    async fn read_request<T>(&mut self, _: &StreamProtocol, io: &mut T) -> io::Result<SyncOpRequest>
159    where
160        T: AsyncRead + Unpin + Send,
161    {
162        read_frame(io).await
163    }
164
165    async fn read_response<T>(
166        &mut self,
167        _: &StreamProtocol,
168        io: &mut T,
169    ) -> io::Result<SyncOpResponse>
170    where
171        T: AsyncRead + Unpin + Send,
172    {
173        read_frame(io).await
174    }
175
176    async fn write_request<T>(
177        &mut self,
178        _: &StreamProtocol,
179        io: &mut T,
180        req: SyncOpRequest,
181    ) -> io::Result<()>
182    where
183        T: AsyncWrite + Unpin + Send,
184    {
185        write_frame(io, &req).await
186    }
187
188    async fn write_response<T>(
189        &mut self,
190        _: &StreamProtocol,
191        io: &mut T,
192        res: SyncOpResponse,
193    ) -> io::Result<()>
194    where
195        T: AsyncWrite + Unpin + Send,
196    {
197        write_frame(io, &res).await
198    }
199}
200
201#[cfg(test)]
202mod tests {
203    use super::*;
204
205    #[test]
206    fn relay_dedups_publish_and_pulls_from_cursor() {
207        let relay = SyncOpRelay::new();
208        assert_eq!(relay.publish(&[b"a".to_vec(), b"b".to_vec()]), 2);
209        // Re-publishing 'a' is idempotent.
210        assert_eq!(relay.publish(&[b"a".to_vec()]), 0);
211        assert_eq!(relay.len(), 2);
212
213        let (frames, cursor) = relay.pull_since(0);
214        assert_eq!(frames, vec![b"a".to_vec(), b"b".to_vec()]);
215        assert_eq!(cursor, 2);
216        // Only what's new after the cursor.
217        assert_eq!(relay.publish(&[b"c".to_vec()]), 1);
218        let (fresh, next) = relay.pull_since(2);
219        assert_eq!(fresh, vec![b"c".to_vec()]);
220        assert_eq!(next, 3);
221    }
222
223    #[test]
224    fn handle_maps_requests_to_responses() {
225        let relay = SyncOpRelay::new();
226        assert_eq!(
227            relay.handle(SyncOpRequest::Publish {
228                op_frames: vec![b"x".to_vec()]
229            }),
230            SyncOpResponse::Published { accepted: 1 }
231        );
232        assert_eq!(
233            relay.handle(SyncOpRequest::PullSince { cursor: 0 }),
234            SyncOpResponse::Pulled {
235                op_frames: vec![b"x".to_vec()],
236                next_cursor: 1
237            }
238        );
239    }
240
241    /// The wire payload round-trips losslessly (the ciborium (de)serialization the codec applies before
242    /// the 4-byte length prefix). The framing is identical to the proven `QualiaSyncCodec`.
243    #[test]
244    fn wire_payload_roundtrips_losslessly() {
245        for req in [
246            SyncOpRequest::Publish {
247                op_frames: vec![b"op-1".to_vec(), b"op-2".to_vec()],
248            },
249            SyncOpRequest::PullSince { cursor: 42 },
250        ] {
251            let mut buf = Vec::new();
252            ciborium::into_writer(&req, &mut buf).unwrap();
253            let back: SyncOpRequest = ciborium::from_reader(&buf[..]).unwrap();
254            assert_eq!(back, req);
255        }
256        for res in [
257            SyncOpResponse::Published { accepted: 3 },
258            SyncOpResponse::Pulled {
259                op_frames: vec![b"op-1".to_vec()],
260                next_cursor: 7,
261            },
262        ] {
263            let mut buf = Vec::new();
264            ciborium::into_writer(&res, &mut buf).unwrap();
265            let back: SyncOpResponse = ciborium::from_reader(&buf[..]).unwrap();
266            assert_eq!(back, res);
267        }
268    }
269}