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
8pub const SYNC_PROTOCOL_VERSION: u32 = 2;
13
14const UNVERSIONED_PROTOCOL: u32 = 1;
15
16const HEADER_PREFIX: &str = "second-brain-sync";
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
25pub struct SyncHeader {
26 pub sync_protocol: u32,
27 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 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 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 MissingHeader,
80 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
134pub 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
154pub 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}