Skip to main content

sapphire_framework_sync/
store.rs

1//! Replica store (redb): one table of path states and one metadata record.
2
3use std::path::Path;
4
5use redb::{Database, ReadableDatabase, ReadableTable, TableDefinition};
6use serde::{Deserialize, Serialize};
7
8use crate::error::{Error, RedbExt, Result};
9use crate::hlc::Hlc;
10use crate::id::ReplicaId;
11use crate::state::PathState;
12use crate::vv::VersionVector;
13
14/// On-disk format of the replica store. Bump for any change in stored data *or* in
15/// merge behaviour (spec §5.4).
16pub const FORMAT_VERSION: u32 = 1;
17
18const PATHS: TableDefinition<&str, &[u8]> = TableDefinition::new("paths");
19const META: TableDefinition<&str, &[u8]> = TableDefinition::new("meta");
20const META_KEY: &str = "meta";
21
22/// Replica-wide metadata.
23#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
24pub struct Meta {
25    pub format_version: u32,
26    pub replica_id: ReplicaId,
27    /// Counter of the last dot this replica assigned.
28    pub counter: u64,
29    pub hlc: Hlc,
30    /// Every dot whose effects this replica's states include.
31    pub vv: VersionVector,
32    /// Workspace root this store belongs to.
33    pub root: String,
34}
35
36/// Persistent replica state.
37pub struct ReplicaStore {
38    db: Database,
39}
40
41#[derive(Deserialize)]
42struct FormatProbe {
43    format_version: u32,
44}
45
46impl ReplicaStore {
47    pub fn open(path: &Path, root: &str) -> Result<Self> {
48        Self::open_with_id(path, root, None)
49    }
50
51    /// Open or create the store. `id` is used only when the store is created.
52    pub fn open_with_id(path: &Path, root: &str, id: Option<ReplicaId>) -> Result<Self> {
53        if let Some(parent) = path.parent() {
54            std::fs::create_dir_all(parent)?;
55        }
56        let db = Database::create(path).db()?;
57        let wtx = db.begin_write().db()?;
58        {
59            wtx.open_table(PATHS).db()?;
60            let mut meta_table = wtx.open_table(META).db()?;
61            let existing = meta_table.get(META_KEY).db()?.map(|g| g.value().to_vec());
62            match existing {
63                None => {
64                    let meta = Meta {
65                        format_version: FORMAT_VERSION,
66                        replica_id: id.unwrap_or_default(),
67                        counter: 0,
68                        hlc: Hlc::default(),
69                        vv: VersionVector::new(),
70                        root: root.to_owned(),
71                    };
72                    meta_table
73                        .insert(META_KEY, serde_json::to_vec(&meta)?.as_slice())
74                        .db()?;
75                }
76                Some(bytes) => {
77                    let probe: FormatProbe = serde_json::from_slice(&bytes)?;
78                    if probe.format_version > FORMAT_VERSION {
79                        return Err(Error::FormatTooNew {
80                            found: probe.format_version,
81                            supported: FORMAT_VERSION,
82                        });
83                    }
84                    let meta: Meta = serde_json::from_slice(&bytes)?;
85                    if meta.root != root {
86                        return Err(Error::RootMismatch {
87                            stored: meta.root,
88                            requested: root.to_owned(),
89                        });
90                    }
91                }
92            }
93        }
94        wtx.commit().db()?;
95        Ok(Self { db })
96    }
97
98    /// Record that the workspace this store belongs to now lives at `root`: its folder
99    /// was moved. Every state is kept — the store holds workspace-relative paths only —
100    /// so the replica carries on as the same replica rather than starting over.
101    pub fn relocate(path: &Path, root: &str) -> Result<()> {
102        let db = Database::open(path).db()?;
103        let wtx = db.begin_write().db()?;
104        {
105            let mut meta_table = wtx.open_table(META).db()?;
106            let bytes = meta_table
107                .get(META_KEY)
108                .db()?
109                .map(|g| g.value().to_vec())
110                .ok_or_else(|| Error::Corrupt("missing meta record".into()))?;
111            let mut meta: Meta = serde_json::from_slice(&bytes)?;
112            meta.root = root.to_owned();
113            meta_table
114                .insert(META_KEY, serde_json::to_vec(&meta)?.as_slice())
115                .db()?;
116        }
117        wtx.commit().db()
118    }
119
120    pub fn meta(&self) -> Result<Meta> {
121        let rtx = self.db.begin_read().db()?;
122        let table = rtx.open_table(META).db()?;
123        let guard = table
124            .get(META_KEY)
125            .db()?
126            .ok_or_else(|| Error::Corrupt("missing meta record".into()))?;
127        Ok(serde_json::from_slice(guard.value())?)
128    }
129
130    pub fn get(&self, path: &str) -> Result<Option<PathState>> {
131        let rtx = self.db.begin_read().db()?;
132        let table = rtx.open_table(PATHS).db()?;
133        match table.get(path).db()? {
134            Some(guard) => Ok(Some(serde_json::from_slice(guard.value())?)),
135            None => Ok(None),
136        }
137    }
138
139    pub fn all(&self) -> Result<Vec<(String, PathState)>> {
140        let rtx = self.db.begin_read().db()?;
141        let table = rtx.open_table(PATHS).db()?;
142        let mut out = Vec::new();
143        for item in table.iter().db()? {
144            let (k, v) = item.db()?;
145            out.push((k.value().to_owned(), serde_json::from_slice(v.value())?));
146        }
147        Ok(out)
148    }
149
150    pub fn any_materialized(&self) -> Result<bool> {
151        Ok(self.all()?.iter().any(|(_, s)| s.disk.hash.is_some()))
152    }
153
154    /// Write `meta` and `states` in one transaction.
155    pub fn commit(&self, meta: &Meta, states: &[(String, PathState)]) -> Result<()> {
156        let wtx = self.db.begin_write().db()?;
157        {
158            let mut meta_table = wtx.open_table(META).db()?;
159            meta_table
160                .insert(META_KEY, serde_json::to_vec(meta)?.as_slice())
161                .db()?;
162            let mut paths = wtx.open_table(PATHS).db()?;
163            for (path, state) in states {
164                paths
165                    .insert(path.as_str(), serde_json::to_vec(state)?.as_slice())
166                    .db()?;
167            }
168        }
169        wtx.commit().db()?;
170        Ok(())
171    }
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177    use crate::entry::{Content, Entry};
178    use crate::hash::ContentHash;
179    use crate::state::DiskState;
180    use crate::vv::Dot;
181    use grain_id::GrainId;
182
183    fn state(id: ReplicaId, body: &str, on_disk: bool) -> PathState {
184        let e = Entry {
185            path: "a.txt".into(),
186            content: Content::File {
187                hash: ContentHash::of_bytes(body.as_bytes()),
188                len: 1,
189            },
190            hlc: Hlc::default(),
191            dot: Dot {
192                replica: id,
193                counter: 1,
194            },
195            context: VersionVector::new(),
196            author: GrainId::NIL,
197        };
198        let mut seen = VersionVector::new();
199        seen.add_dot(&e.dot);
200        let disk = DiskState {
201            hash: on_disk.then(|| ContentHash::of_bytes(body.as_bytes())),
202            ..DiskState::default()
203        };
204        PathState {
205            versions: vec![e],
206            seen,
207            disk,
208        }
209    }
210
211    #[test]
212    fn creates_meta_once_and_persists_commits() {
213        let dir = tempfile::tempdir().unwrap();
214        let path = dir.path().join("sync.redb");
215        let (id, s) = {
216            let store = ReplicaStore::open(&path, "/root").unwrap();
217            let mut meta = store.meta().unwrap();
218            assert_eq!(meta.format_version, FORMAT_VERSION);
219            assert_eq!(meta.counter, 0);
220            meta.counter = 7;
221            let s = state(meta.replica_id, "x", false);
222            store.commit(&meta, &[("a.txt".into(), s.clone())]).unwrap();
223            (meta.replica_id, s)
224        };
225        let store = ReplicaStore::open(&path, "/root").unwrap();
226        let meta = store.meta().unwrap();
227        assert_eq!((meta.replica_id, meta.counter), (id, 7));
228        assert_eq!(store.get("a.txt").unwrap(), Some(s.clone()));
229        assert_eq!(store.get("b.txt").unwrap(), None);
230        assert_eq!(store.all().unwrap(), vec![("a.txt".to_string(), s)]);
231        assert!(!store.any_materialized().unwrap());
232    }
233
234    #[test]
235    fn a_relocated_store_opens_at_its_new_root_with_its_state() {
236        let dir = tempfile::tempdir().unwrap();
237        let path = dir.path().join("sync.redb");
238        let (id, s) = {
239            let store = ReplicaStore::open(&path, "/old").unwrap();
240            let meta = store.meta().unwrap();
241            let s = state(meta.replica_id, "x", true);
242            store.commit(&meta, &[("a.txt".into(), s.clone())]).unwrap();
243            (meta.replica_id, s)
244        };
245        ReplicaStore::relocate(&path, "/new").unwrap();
246        assert!(matches!(
247            ReplicaStore::open(&path, "/old"),
248            Err(Error::RootMismatch { .. })
249        ));
250        let store = ReplicaStore::open(&path, "/new").unwrap();
251        assert_eq!(store.meta().unwrap().replica_id, id);
252        assert_eq!(store.get("a.txt").unwrap(), Some(s));
253    }
254
255    #[test]
256    fn any_materialized_sees_files_on_disk() {
257        let dir = tempfile::tempdir().unwrap();
258        let store = ReplicaStore::open(&dir.path().join("s.redb"), "/r").unwrap();
259        let meta = store.meta().unwrap();
260        store
261            .commit(
262                &meta,
263                &[("a.txt".into(), state(meta.replica_id, "x", true))],
264            )
265            .unwrap();
266        assert!(store.any_materialized().unwrap());
267    }
268
269    #[test]
270    fn refuses_another_root() {
271        let dir = tempfile::tempdir().unwrap();
272        let path = dir.path().join("s.redb");
273        drop(ReplicaStore::open(&path, "/one").unwrap());
274        assert!(matches!(
275            ReplicaStore::open(&path, "/two"),
276            Err(Error::RootMismatch { .. })
277        ));
278    }
279
280    #[test]
281    fn refuses_a_newer_format() {
282        let dir = tempfile::tempdir().unwrap();
283        let path = dir.path().join("s.redb");
284        {
285            let store = ReplicaStore::open(&path, "/r").unwrap();
286            let mut meta = store.meta().unwrap();
287            meta.format_version = FORMAT_VERSION + 1;
288            store.commit(&meta, &[]).unwrap();
289        }
290        assert!(matches!(
291            ReplicaStore::open(&path, "/r"),
292            Err(Error::FormatTooNew { found, .. }) if found == FORMAT_VERSION + 1
293        ));
294    }
295
296    #[test]
297    fn open_with_id_uses_the_id_only_on_creation() {
298        let dir = tempfile::tempdir().unwrap();
299        let path = dir.path().join("s.redb");
300        let fixed = ReplicaId(uuid::Uuid::from_u128(5));
301        let store = ReplicaStore::open_with_id(&path, "/r", Some(fixed)).unwrap();
302        assert_eq!(store.meta().unwrap().replica_id, fixed);
303        drop(store);
304        let other = ReplicaId(uuid::Uuid::from_u128(6));
305        let store = ReplicaStore::open_with_id(&path, "/r", Some(other)).unwrap();
306        assert_eq!(store.meta().unwrap().replica_id, fixed);
307    }
308}