Skip to main content

folderbase_core/
sync.rs

1use std::{
2    collections::{BTreeMap, BTreeSet},
3    path::{Component, Path, PathBuf},
4};
5
6use serde::{Deserialize, Serialize};
7use sha2::{Digest, Sha256};
8use uuid::Uuid;
9
10use crate::{FolderbaseError, Result};
11
12#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
13#[serde(rename_all = "snake_case")]
14pub enum ContentKind {
15    Text,
16    Binary,
17}
18
19#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
20pub struct SyncVersion {
21    pub digest: String,
22    pub bytes: u64,
23    pub kind: ContentKind,
24    pub author_device: String,
25    pub sequence: u64,
26}
27
28#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
29pub struct SyncEvent {
30    pub id: String,
31    pub path: PathBuf,
32    pub version: SyncVersion,
33}
34
35#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
36pub struct SyncConflict {
37    pub path: PathBuf,
38    pub base_digest: Option<String>,
39    pub local: SyncVersion,
40    pub remote: SyncVersion,
41    pub classification: ConflictClassification,
42}
43
44#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
45#[serde(rename_all = "snake_case")]
46pub enum ConflictClassification {
47    TextNeedsMerge,
48    PreserveBothBinary,
49}
50
51#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
52pub struct SyncReport {
53    pub uploaded: Vec<PathBuf>,
54    pub downloaded: Vec<PathBuf>,
55    pub unchanged: Vec<PathBuf>,
56    pub conflicts: Vec<SyncConflict>,
57}
58
59#[derive(Debug, Clone)]
60struct LocalEntry {
61    bytes: Vec<u8>,
62    kind: ContentKind,
63    base_digest: Option<String>,
64}
65
66/// A deterministic logical device used by the native client and fault tests.
67///
68/// It intentionally models sync separately from filesystem watching. Native
69/// clients feed completed local writes into this module only after the local
70/// object store has captured and verified them.
71#[derive(Debug)]
72pub struct SyncReplica {
73    device_id: String,
74    entries: BTreeMap<PathBuf, LocalEntry>,
75    applied_events: BTreeSet<String>,
76    applied_sequences: BTreeMap<PathBuf, u64>,
77}
78
79impl SyncReplica {
80    pub fn new(device_id: impl Into<String>) -> Self {
81        Self {
82            device_id: device_id.into(),
83            entries: BTreeMap::new(),
84            applied_events: BTreeSet::new(),
85            applied_sequences: BTreeMap::new(),
86        }
87    }
88
89    pub fn write(
90        &mut self,
91        path: impl AsRef<Path>,
92        bytes: impl Into<Vec<u8>>,
93        kind: ContentKind,
94    ) -> Result<()> {
95        let path = path.as_ref().to_path_buf();
96        ensure_safe_relative(&path)?;
97        let base_digest = self
98            .entries
99            .get(&path)
100            .and_then(|entry| entry.base_digest.clone());
101        self.entries.insert(
102            path,
103            LocalEntry {
104                bytes: bytes.into(),
105                kind,
106                base_digest,
107            },
108        );
109        Ok(())
110    }
111
112    pub fn read(&self, path: impl AsRef<Path>) -> Option<&[u8]> {
113        self.entries
114            .get(path.as_ref())
115            .map(|entry| entry.bytes.as_slice())
116    }
117
118    pub fn sync(&mut self, cloud: &mut MemorySyncCloud) -> Result<SyncReport> {
119        let mut report = SyncReport::default();
120        let mut paths = self.entries.keys().cloned().collect::<BTreeSet<_>>();
121        paths.extend(cloud.canonical.keys().cloned());
122
123        for path in paths {
124            ensure_safe_relative(&path)?;
125            let remote = cloud.canonical.get(&path).cloned();
126            let local = self.entries.get(&path).cloned();
127
128            match (local, remote) {
129                (Some(mut local), None) => {
130                    let local_version = cloud.capture(&self.device_id, &local.bytes, local.kind);
131                    cloud.publish(path.clone(), local_version.clone());
132                    local.base_digest = Some(local_version.digest.clone());
133                    self.entries.insert(path.clone(), local);
134                    self.applied_sequences
135                        .insert(path.clone(), local_version.sequence);
136                    report.uploaded.push(path);
137                }
138                (None, Some(remote)) => {
139                    let bytes = cloud.materialize(&remote.digest)?.to_vec();
140                    self.entries.insert(
141                        path.clone(),
142                        LocalEntry {
143                            bytes,
144                            kind: remote.kind,
145                            base_digest: Some(remote.digest.clone()),
146                        },
147                    );
148                    self.applied_sequences.insert(path.clone(), remote.sequence);
149                    report.downloaded.push(path);
150                }
151                (Some(mut local), Some(remote)) => {
152                    let local_digest = digest(&local.bytes);
153                    if local_digest == remote.digest {
154                        local.base_digest = Some(remote.digest.clone());
155                        self.entries.insert(path.clone(), local);
156                        self.applied_sequences.insert(path.clone(), remote.sequence);
157                        report.unchanged.push(path);
158                        continue;
159                    }
160
161                    if local.base_digest.as_deref() == Some(remote.digest.as_str()) {
162                        let local_version =
163                            cloud.capture(&self.device_id, &local.bytes, local.kind);
164                        cloud.publish(path.clone(), local_version.clone());
165                        local.base_digest = Some(local_version.digest.clone());
166                        self.entries.insert(path.clone(), local);
167                        self.applied_sequences
168                            .insert(path.clone(), local_version.sequence);
169                        report.uploaded.push(path);
170                        continue;
171                    }
172
173                    if local.base_digest.as_deref() == Some(local_digest.as_str()) {
174                        let bytes = cloud.materialize(&remote.digest)?.to_vec();
175                        self.entries.insert(
176                            path.clone(),
177                            LocalEntry {
178                                bytes,
179                                kind: remote.kind,
180                                base_digest: Some(remote.digest.clone()),
181                            },
182                        );
183                        self.applied_sequences.insert(path.clone(), remote.sequence);
184                        report.downloaded.push(path);
185                        continue;
186                    }
187
188                    let local_version = cloud.capture(&self.device_id, &local.bytes, local.kind);
189                    let classification =
190                        if local.kind == ContentKind::Text && remote.kind == ContentKind::Text {
191                            ConflictClassification::TextNeedsMerge
192                        } else {
193                            ConflictClassification::PreserveBothBinary
194                        };
195                    let conflict = SyncConflict {
196                        path: path.clone(),
197                        base_digest: local.base_digest.clone(),
198                        local: local_version,
199                        remote,
200                        classification,
201                    };
202                    cloud.record_conflict(conflict.clone());
203                    report.conflicts.push(conflict);
204                }
205                (None, None) => {}
206            }
207        }
208
209        sort_report(&mut report);
210        Ok(report)
211    }
212
213    /// Apply a notification idempotently.
214    ///
215    /// Dirty local content is never replaced; a normal sync will classify the
216    /// divergence and preserve both sides.
217    pub fn apply_event(&mut self, cloud: &MemorySyncCloud, event: &SyncEvent) -> Result<bool> {
218        ensure_safe_relative(&event.path)?;
219        if self.applied_events.contains(&event.id) {
220            return Ok(false);
221        }
222        if self
223            .applied_sequences
224            .get(&event.path)
225            .is_some_and(|sequence| *sequence >= event.version.sequence)
226        {
227            self.applied_events.insert(event.id.clone());
228            return Ok(false);
229        }
230
231        let can_download = self.entries.get(&event.path).is_none_or(|entry| {
232            let local_digest = digest(&entry.bytes);
233            entry.base_digest.as_deref() == Some(local_digest.as_str())
234        });
235        if !can_download {
236            return Ok(false);
237        }
238
239        let bytes = cloud.materialize(&event.version.digest)?.to_vec();
240        if digest(&bytes) != event.version.digest || bytes.len() as u64 != event.version.bytes {
241            return Err(FolderbaseError::InvalidRecord {
242                path: event.path.clone(),
243                message: "sync event content failed integrity verification".to_owned(),
244            });
245        }
246        self.entries.insert(
247            event.path.clone(),
248            LocalEntry {
249                bytes,
250                kind: event.version.kind,
251                base_digest: Some(event.version.digest.clone()),
252            },
253        );
254        self.applied_events.insert(event.id.clone());
255        self.applied_sequences
256            .insert(event.path.clone(), event.version.sequence);
257        Ok(true)
258    }
259}
260
261/// In-memory implementation of the immutable cloud data-plane contract.
262///
263/// Production transports can replace this implementation while retaining the
264/// planner semantics and deterministic simulator tests.
265#[derive(Debug, Default)]
266pub struct MemorySyncCloud {
267    blobs: BTreeMap<String, Vec<u8>>,
268    canonical: BTreeMap<PathBuf, SyncVersion>,
269    events: Vec<SyncEvent>,
270    conflicts: Vec<SyncConflict>,
271    sequence: u64,
272}
273
274impl MemorySyncCloud {
275    pub fn new() -> Self {
276        Self::default()
277    }
278
279    pub fn events(&self) -> &[SyncEvent] {
280        &self.events
281    }
282
283    pub fn conflicts(&self) -> &[SyncConflict] {
284        &self.conflicts
285    }
286
287    pub fn materialize(&self, digest: &str) -> Result<&[u8]> {
288        self.blobs
289            .get(digest)
290            .map(Vec::as_slice)
291            .ok_or_else(|| FolderbaseError::InvalidRecord {
292                path: PathBuf::from(digest),
293                message: "cloud version references a missing immutable blob".to_owned(),
294            })
295    }
296
297    pub fn canonical_version(&self, path: impl AsRef<Path>) -> Option<&SyncVersion> {
298        self.canonical.get(path.as_ref())
299    }
300
301    pub fn store_blob(&mut self, bytes: &[u8]) -> String {
302        let digest = digest(bytes);
303        self.blobs
304            .entry(digest.clone())
305            .or_insert_with(|| bytes.to_vec());
306        digest
307    }
308
309    fn capture(&mut self, device_id: &str, bytes: &[u8], kind: ContentKind) -> SyncVersion {
310        let digest = self.store_blob(bytes);
311        self.sequence += 1;
312        SyncVersion {
313            digest,
314            bytes: bytes.len() as u64,
315            kind,
316            author_device: device_id.to_owned(),
317            sequence: self.sequence,
318        }
319    }
320
321    fn publish(&mut self, path: PathBuf, version: SyncVersion) {
322        self.canonical.insert(path.clone(), version.clone());
323        self.events.push(SyncEvent {
324            id: format!("event_{}", Uuid::now_v7()),
325            path,
326            version,
327        });
328    }
329
330    fn record_conflict(&mut self, conflict: SyncConflict) {
331        let duplicate = self.conflicts.iter().any(|existing| {
332            existing.path == conflict.path
333                && existing.local.digest == conflict.local.digest
334                && existing.remote.digest == conflict.remote.digest
335        });
336        if !duplicate {
337            self.conflicts.push(conflict);
338        }
339    }
340}
341
342fn ensure_safe_relative(path: &Path) -> Result<()> {
343    if path.as_os_str().is_empty()
344        || path.is_absolute()
345        || path
346            .components()
347            .any(|component| !matches!(component, Component::Normal(_)))
348    {
349        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
350    }
351    Ok(())
352}
353
354fn digest(bytes: &[u8]) -> String {
355    format!("{:x}", Sha256::digest(bytes))
356}
357
358fn sort_report(report: &mut SyncReport) {
359    report.uploaded.sort();
360    report.downloaded.sort();
361    report.unchanged.sort();
362    report.conflicts.sort_by(|left, right| {
363        left.path
364            .cmp(&right.path)
365            .then_with(|| left.local.digest.cmp(&right.local.digest))
366    });
367}