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
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
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}