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, SqliteStore};
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/// The versions this daemon syncs at. A binary older than the database it
155/// serves is refused, because applying records it would drop the columns it
156/// does not know.
157pub fn store_header(sqlite: &SqliteStore) -> Result<SyncHeader> {
158    let store = SyncHeader::current(sqlite.schema_version()?);
159    SyncHeader::current(SCHEMA_VERSION).ensure_matches(
160        "this daemon's binary",
161        &store,
162        "its database",
163    )?;
164    Ok(store)
165}
166
167pub fn check_store_header(
168    sqlite: &SqliteStore,
169    declared: Option<SyncHeader>,
170    sender: &str,
171) -> Result<()> {
172    let ours = store_header(sqlite)?;
173    let theirs = declared.ok_or(VersionError::MissingHeader)?;
174    ours.ensure_matches("this daemon", &theirs, sender)?;
175    Ok(())
176}
177
178#[cfg(test)]
179mod tests {
180    use std::io::BufReader;
181
182    use base64::Engine;
183    use base64::engine::general_purpose::STANDARD as B64;
184    use chrono::{TimeZone, Utc};
185    use second_brain_core::schema::{SyncNodeType, SyncOp, SyncRecord};
186
187    use super::*;
188    use crate::crypto::{XChaChaEncryptor, seal_line};
189
190    fn header(protocol: u32, schema: i64) -> SyncHeader {
191        SyncHeader {
192            sync_protocol: protocol,
193            schema_version: schema,
194        }
195    }
196
197    #[test]
198    fn header_line_round_trips() {
199        let h = SyncHeader::current(7);
200        let line = h.to_line();
201        assert!(!line.contains('\n'));
202        assert_eq!(SyncHeader::parse_line(&line).unwrap(), h);
203    }
204
205    #[test]
206    fn header_line_aborts_an_unversioned_reader() {
207        let line = SyncHeader::current(7).to_line();
208        assert!(
209            serde_json::from_str::<serde_json::Value>(&line).is_err(),
210            "{line}"
211        );
212        assert!(B64.decode(line.trim()).is_err(), "{line}");
213    }
214
215    #[test]
216    fn read_header_consumes_only_the_header_line() {
217        let enc = XChaChaEncryptor::new([3; 32]);
218        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
219        let stream = format!("\n{}\n{record}\n", SyncHeader::current(7).to_line());
220        let mut reader = BufReader::new(stream.as_bytes());
221        assert_eq!(read_header(&mut reader).unwrap(), SyncHeader::current(7));
222        let rest: Vec<String> = reader.lines().map(|l| l.unwrap()).collect();
223        assert_eq!(
224            rest,
225            vec![record],
226            "records after the header are left unread"
227        );
228    }
229
230    #[test]
231    fn stream_starting_with_a_record_has_no_header() {
232        let enc = XChaChaEncryptor::new([3; 32]);
233        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
234        let stream = format!("{record}\n");
235        let mut reader = BufReader::new(stream.as_bytes());
236        let err = read_header(&mut reader).unwrap_err();
237        assert_eq!(
238            err.downcast_ref::<VersionError>(),
239            Some(&VersionError::MissingHeader)
240        );
241        assert!(err.to_string().contains("protocol 1"), "{err}");
242    }
243
244    #[test]
245    fn legacy_plaintext_record_is_not_a_header() {
246        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}"#;
247        assert_eq!(
248            SyncHeader::parse_line(legacy),
249            Err(VersionError::MissingHeader)
250        );
251    }
252
253    #[test]
254    fn empty_stream_has_no_header() {
255        let mut reader = BufReader::new(&b""[..]);
256        let err = read_header(&mut reader).unwrap_err();
257        assert_eq!(
258            err.downcast_ref::<VersionError>(),
259            Some(&VersionError::MissingHeader)
260        );
261    }
262
263    #[test]
264    fn matching_headers_pass() {
265        let h = SyncHeader::current(7);
266        assert!(h.ensure_matches("this machine", &h, "peer").is_ok());
267    }
268
269    #[test]
270    fn protocol_mismatch_names_both_versions_and_the_older_side() {
271        let err = header(2, 7)
272            .ensure_matches("this machine", &header(3, 7), "pi")
273            .unwrap_err()
274            .to_string();
275        assert!(
276            err.contains("this machine has sync protocol 2 and schema 7"),
277            "{err}"
278        );
279        assert!(err.contains("pi has sync protocol 3 and schema 7"), "{err}");
280        assert!(err.contains("upgrade this machine"), "{err}");
281    }
282
283    #[test]
284    fn schema_mismatch_names_the_older_side() {
285        let err = header(2, 8)
286            .ensure_matches("this machine", &header(2, 7), "pi")
287            .unwrap_err()
288            .to_string();
289        assert!(
290            err.contains("schema 8") && err.contains("schema 7"),
291            "{err}"
292        );
293        assert!(err.contains("upgrade pi"), "{err}");
294    }
295
296    fn every_op() -> Vec<SyncOp> {
297        let ops = vec![SyncOp::Create, SyncOp::Update, SyncOp::Delete];
298        for op in &ops {
299            match op {
300                SyncOp::Create | SyncOp::Update | SyncOp::Delete => {}
301            }
302        }
303        ops
304    }
305
306    fn every_node_type() -> Vec<SyncNodeType> {
307        let types = vec![
308            SyncNodeType::Memory,
309            SyncNodeType::Entity,
310            SyncNodeType::Conversation,
311            SyncNodeType::Relation,
312            SyncNodeType::Distillation,
313        ];
314        for t in &types {
315            match t {
316                SyncNodeType::Memory
317                | SyncNodeType::Entity
318                | SyncNodeType::Conversation
319                | SyncNodeType::Relation
320                | SyncNodeType::Distillation => {}
321            }
322        }
323        types
324    }
325
326    fn wire_format() -> String {
327        let record = SyncRecord {
328            local_seq: 1,
329            origin_machine_id: "m".to_string(),
330            origin_seq: 2,
331            op: SyncOp::Create,
332            node_type: SyncNodeType::Memory,
333            node_id: "n".to_string(),
334            timestamp: Utc.with_ymd_and_hms(2026, 1, 2, 3, 4, 5).unwrap(),
335            data: Some(serde_json::json!({"k": "v"})),
336        };
337        let ops: Vec<String> = every_op()
338            .iter()
339            .map(|o| serde_json::to_string(o).unwrap())
340            .collect();
341        let types: Vec<String> = every_node_type()
342            .iter()
343            .map(|t| serde_json::to_string(t).unwrap())
344            .collect();
345        format!(
346            "header={}\nrecord={}\nops={}\nnode_types={}\nframe={}",
347            SyncHeader::current(7).to_line(),
348            serde_json::to_string(&record).unwrap(),
349            ops.join(","),
350            types.join(","),
351            crate::crypto::frame_format(),
352        )
353    }
354
355    #[test]
356    fn wire_format_matches_the_protocol_version() {
357        const PINNED: (u32, &str) = (
358            2,
359            "header=second-brain-sync {\"sync_protocol\":2,\"schema_version\":7}\n\
360             record={\"local_seq\":1,\"origin_machine_id\":\"m\",\"origin_seq\":2,\"op\":\"create\",\
361             \"node_type\":\"memory\",\"node_id\":\"n\",\"timestamp\":\"2026-01-02T03:04:05Z\",\
362             \"data\":{\"k\":\"v\"}}\n\
363             ops=\"create\",\"update\",\"delete\"\n\
364             node_types=\"memory\",\"entity\",\"conversation\",\"relation\",\"distillation\"\n\
365             frame=base64(0x01 | nonce[24] | xchacha20poly1305 ciphertext)",
366        );
367        assert_eq!(
368            (SYNC_PROTOCOL_VERSION, wire_format().as_str()),
369            PINNED,
370            "the sync wire format changed: bump SYNC_PROTOCOL_VERSION and re-pin this test"
371        );
372    }
373}