Skip to main content

second_brain_sync/
protocol.rs

1use std::fmt;
2use std::io::BufRead;
3
4use anyhow::{Context, Result};
5use second_brain_core::sqlite_store::SCHEMA_VERSION;
6use serde::{Deserialize, Serialize};
7
8/// Bump whenever the sync wire format or the meaning of a field changes:
9/// the record envelope, the header line, the line framing or the crypto frame.
10/// `wire_format_matches_the_protocol_version` pins the current format.
11/// Releases up to second-brain 0.10.0 sent no header and count as protocol 1.
12pub const SYNC_PROTOCOL_VERSION: u32 = 2;
13
14const UNVERSIONED_PROTOCOL: u32 = 1;
15
16/// Makes the header line neither base64 nor JSON: binaries up to 0.10.0 pass
17/// any non-base64 line through as a plaintext JSON record, and only a parse
18/// failure on the first line stops them before they apply anything.
19const HEADER_PREFIX: &str = "second-brain-sync";
20
21/// First line of every sync stream: `HEADER_PREFIX`, a space, then plaintext
22/// JSON, so a peer holding the wrong key still gets a version error. It carries
23/// no data, is not a change-log entry and has no sequence number.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
25pub struct SyncHeader {
26    pub sync_protocol: u32,
27    /// `PRAGMA user_version` of the store whose records the stream carries.
28    pub schema_version: i64,
29}
30
31impl SyncHeader {
32    pub fn current(schema_version: i64) -> Self {
33        Self {
34            sync_protocol: SYNC_PROTOCOL_VERSION,
35            schema_version,
36        }
37    }
38
39    /// The versions this binary was built with.
40    pub fn local() -> Self {
41        Self::current(SCHEMA_VERSION)
42    }
43
44    pub fn to_line(&self) -> String {
45        let json = serde_json::to_string(self).expect("SyncHeader serializes");
46        format!("{HEADER_PREFIX} {json}")
47    }
48
49    pub fn parse_line(line: &str) -> Result<Self, VersionError> {
50        line.trim()
51            .strip_prefix(HEADER_PREFIX)
52            .and_then(|rest| serde_json::from_str(rest).ok())
53            .ok_or(VersionError::MissingHeader)
54    }
55
56    /// Refuses unless both sides speak the same protocol over the same schema.
57    /// `local_name` and `peer_name` name the two sides in the error message.
58    pub fn ensure_matches(
59        &self,
60        local_name: &str,
61        peer: &Self,
62        peer_name: &str,
63    ) -> Result<(), VersionError> {
64        if self == peer {
65            return Ok(());
66        }
67        Err(VersionError::Mismatch {
68            local: *self,
69            local_name: local_name.to_string(),
70            peer: *peer,
71            peer_name: peer_name.to_string(),
72        })
73    }
74}
75
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub enum VersionError {
78    /// A stream or request without a header: its sender predates versioning.
79    MissingHeader,
80    /// The local daemon has no version route: it predates versioning.
81    UnversionedDaemon,
82    Mismatch {
83        local: SyncHeader,
84        local_name: String,
85        peer: SyncHeader,
86        peer_name: String,
87    },
88}
89
90impl fmt::Display for VersionError {
91    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
92        match self {
93            VersionError::MissingHeader => write_unversioned(f, "the sender"),
94            VersionError::UnversionedDaemon => write_unversioned(f, "the local daemon"),
95            VersionError::Mismatch {
96                local,
97                local_name,
98                peer,
99                peer_name,
100            } => {
101                let older = if (local.sync_protocol, local.schema_version)
102                    < (peer.sync_protocol, peer.schema_version)
103                {
104                    local_name
105                } else {
106                    peer_name
107                };
108                write!(
109                    f,
110                    "sync version mismatch: {local_name} has sync protocol {} and schema {}, \
111                     {peer_name} has sync protocol {} and schema {}; upgrade {older}, \
112                     nothing was applied",
113                    local.sync_protocol,
114                    local.schema_version,
115                    peer.sync_protocol,
116                    peer.schema_version
117                )
118            }
119        }
120    }
121}
122
123fn write_unversioned(f: &mut fmt::Formatter<'_>, side: &str) -> fmt::Result {
124    write!(
125        f,
126        "{side} declared no sync version, so it speaks sync protocol {UNVERSIONED_PROTOCOL} \
127         (second-brain 0.10.0 or older) and this side speaks protocol {SYNC_PROTOCOL_VERSION}; \
128         upgrade {side}, nothing was applied"
129    )
130}
131
132impl std::error::Error for VersionError {}
133
134/// Reads the header line that must open a sync stream, skipping blank lines.
135/// An empty stream is refused like a header-less one: a current sender always
136/// writes the header, even when it has no records.
137pub fn read_header<R: BufRead>(reader: &mut R) -> Result<SyncHeader> {
138    let mut line = String::new();
139    loop {
140        line.clear();
141        if reader
142            .read_line(&mut line)
143            .context("reading sync stream header")?
144            == 0
145        {
146            return Err(VersionError::MissingHeader.into());
147        }
148        if !line.trim().is_empty() {
149            return Ok(SyncHeader::parse_line(&line)?);
150        }
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use std::io::BufReader;
157
158    use base64::Engine;
159    use base64::engine::general_purpose::STANDARD as B64;
160    use chrono::{TimeZone, Utc};
161    use second_brain_core::schema::{SyncNodeType, SyncOp, SyncRecord};
162
163    use super::*;
164    use crate::crypto::{XChaChaEncryptor, seal_line};
165
166    fn header(protocol: u32, schema: i64) -> SyncHeader {
167        SyncHeader {
168            sync_protocol: protocol,
169            schema_version: schema,
170        }
171    }
172
173    #[test]
174    fn header_line_round_trips() {
175        let h = SyncHeader::current(7);
176        let line = h.to_line();
177        assert!(!line.contains('\n'));
178        assert_eq!(SyncHeader::parse_line(&line).unwrap(), h);
179    }
180
181    #[test]
182    fn header_line_aborts_an_unversioned_reader() {
183        let line = SyncHeader::current(7).to_line();
184        assert!(
185            serde_json::from_str::<serde_json::Value>(&line).is_err(),
186            "{line}"
187        );
188        assert!(B64.decode(line.trim()).is_err(), "{line}");
189    }
190
191    #[test]
192    fn read_header_consumes_only_the_header_line() {
193        let enc = XChaChaEncryptor::new([3; 32]);
194        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
195        let stream = format!("\n{}\n{record}\n", SyncHeader::current(7).to_line());
196        let mut reader = BufReader::new(stream.as_bytes());
197        assert_eq!(read_header(&mut reader).unwrap(), SyncHeader::current(7));
198        let rest: Vec<String> = reader.lines().map(|l| l.unwrap()).collect();
199        assert_eq!(
200            rest,
201            vec![record],
202            "records after the header are left unread"
203        );
204    }
205
206    #[test]
207    fn stream_starting_with_a_record_has_no_header() {
208        let enc = XChaChaEncryptor::new([3; 32]);
209        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
210        let stream = format!("{record}\n");
211        let mut reader = BufReader::new(stream.as_bytes());
212        let err = read_header(&mut reader).unwrap_err();
213        assert_eq!(
214            err.downcast_ref::<VersionError>(),
215            Some(&VersionError::MissingHeader)
216        );
217        assert!(err.to_string().contains("protocol 1"), "{err}");
218    }
219
220    #[test]
221    fn legacy_plaintext_record_is_not_a_header() {
222        let legacy = r#"{"local_seq":1,"origin_machine_id":"m","origin_seq":1,"op":"create","node_type":"memory","node_id":"x","timestamp":"2026-01-01T00:00:00Z","data":null}"#;
223        assert_eq!(
224            SyncHeader::parse_line(legacy),
225            Err(VersionError::MissingHeader)
226        );
227    }
228
229    #[test]
230    fn empty_stream_has_no_header() {
231        let mut reader = BufReader::new(&b""[..]);
232        let err = read_header(&mut reader).unwrap_err();
233        assert_eq!(
234            err.downcast_ref::<VersionError>(),
235            Some(&VersionError::MissingHeader)
236        );
237    }
238
239    #[test]
240    fn matching_headers_pass() {
241        let h = SyncHeader::current(7);
242        assert!(h.ensure_matches("this machine", &h, "peer").is_ok());
243    }
244
245    #[test]
246    fn protocol_mismatch_names_both_versions_and_the_older_side() {
247        let err = header(2, 7)
248            .ensure_matches("this machine", &header(3, 7), "pi")
249            .unwrap_err()
250            .to_string();
251        assert!(
252            err.contains("this machine has sync protocol 2 and schema 7"),
253            "{err}"
254        );
255        assert!(err.contains("pi has sync protocol 3 and schema 7"), "{err}");
256        assert!(err.contains("upgrade this machine"), "{err}");
257    }
258
259    #[test]
260    fn schema_mismatch_names_the_older_side() {
261        let err = header(2, 8)
262            .ensure_matches("this machine", &header(2, 7), "pi")
263            .unwrap_err()
264            .to_string();
265        assert!(
266            err.contains("schema 8") && err.contains("schema 7"),
267            "{err}"
268        );
269        assert!(err.contains("upgrade pi"), "{err}");
270    }
271
272    fn every_op() -> Vec<SyncOp> {
273        let ops = vec![SyncOp::Create, SyncOp::Update, SyncOp::Delete];
274        for op in &ops {
275            match op {
276                SyncOp::Create | SyncOp::Update | SyncOp::Delete => {}
277            }
278        }
279        ops
280    }
281
282    fn every_node_type() -> Vec<SyncNodeType> {
283        let types = vec![
284            SyncNodeType::Memory,
285            SyncNodeType::Entity,
286            SyncNodeType::Conversation,
287            SyncNodeType::Relation,
288            SyncNodeType::Distillation,
289        ];
290        for t in &types {
291            match t {
292                SyncNodeType::Memory
293                | SyncNodeType::Entity
294                | SyncNodeType::Conversation
295                | SyncNodeType::Relation
296                | SyncNodeType::Distillation => {}
297            }
298        }
299        types
300    }
301
302    fn wire_format() -> String {
303        let record = SyncRecord {
304            local_seq: 1,
305            origin_machine_id: "m".to_string(),
306            origin_seq: 2,
307            op: SyncOp::Create,
308            node_type: SyncNodeType::Memory,
309            node_id: "n".to_string(),
310            timestamp: Utc.with_ymd_and_hms(2026, 1, 2, 3, 4, 5).unwrap(),
311            data: Some(serde_json::json!({"k": "v"})),
312        };
313        let ops: Vec<String> = every_op()
314            .iter()
315            .map(|o| serde_json::to_string(o).unwrap())
316            .collect();
317        let types: Vec<String> = every_node_type()
318            .iter()
319            .map(|t| serde_json::to_string(t).unwrap())
320            .collect();
321        format!(
322            "header={}\nrecord={}\nops={}\nnode_types={}\nframe={}",
323            SyncHeader::current(7).to_line(),
324            serde_json::to_string(&record).unwrap(),
325            ops.join(","),
326            types.join(","),
327            crate::crypto::frame_format(),
328        )
329    }
330
331    #[test]
332    fn wire_format_matches_the_protocol_version() {
333        const PINNED: (u32, &str) = (
334            2,
335            "header=second-brain-sync {\"sync_protocol\":2,\"schema_version\":7}\n\
336             record={\"local_seq\":1,\"origin_machine_id\":\"m\",\"origin_seq\":2,\"op\":\"create\",\
337             \"node_type\":\"memory\",\"node_id\":\"n\",\"timestamp\":\"2026-01-02T03:04:05Z\",\
338             \"data\":{\"k\":\"v\"}}\n\
339             ops=\"create\",\"update\",\"delete\"\n\
340             node_types=\"memory\",\"entity\",\"conversation\",\"relation\",\"distillation\"\n\
341             frame=base64(0x01 | nonce[24] | xchacha20poly1305 ciphertext)",
342        );
343        assert_eq!(
344            (SYNC_PROTOCOL_VERSION, wire_format().as_str()),
345            PINNED,
346            "the sync wire format changed: bump SYNC_PROTOCOL_VERSION and re-pin this test"
347        );
348    }
349}