Skip to main content

zero_client/client/
storage.rs

1//! Where a client keeps its replica: its client groups, clients, and each
2//! group's snapshot and pending mutations, what Replicache keeps in
3//! IndexedDB (zero-swift's `ZeroStorage`).
4//!
5//! The client owns everything but the bytes: it keeps the client groups and
6//! clients in memory, makes every decision in JS's order, and hands a
7//! [`StorageBackend`] an ordered stream of [`StorageOp`]s to write. The
8//! memory storage is in the core; SQLite is behind the `sqlite` feature; an
9//! app can bring its own backend with [`ZeroStorage::Custom`].
10
11use crate::json::Value;
12use crate::strings;
13use std::collections::BTreeMap;
14use std::fmt;
15use std::rc::Rc;
16
17/// Where a client keeps its replica (`ZeroStorage` in zero-swift,
18/// `kvStore` in JS).
19#[derive(Clone, Default)]
20pub enum ZeroStorage {
21    /// Memory only, kept for the life of the thread: a client created later
22    /// with the same options finds what an earlier one stored, as with JS
23    /// `kvStore: 'mem'`. **Nothing survives a restart.**
24    #[default]
25    Memory,
26    /// A SQLite database file per database name in `directory`. The default
27    /// directory is `~/Library/Application Support/Zero` on macOS,
28    /// `%LOCALAPPDATA%\Zero` on Windows, and `$XDG_DATA_HOME/zero` (or
29    /// `~/.local/share/zero`) elsewhere.
30    #[cfg(feature = "sqlite")]
31    Sqlite {
32        /// Where the files go; `None` for the default directory.
33        directory: Option<std::path::PathBuf>,
34    },
35    /// A store the app brings.
36    Custom(Rc<dyn StorageBackend>),
37}
38
39impl fmt::Debug for ZeroStorage {
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        match self {
42            ZeroStorage::Memory => f.write_str("Memory"),
43            #[cfg(feature = "sqlite")]
44            ZeroStorage::Sqlite { directory } => f
45                .debug_struct("Sqlite")
46                .field("directory", directory)
47                .finish(),
48            ZeroStorage::Custom(b) => write!(f, "Custom({})", b.location()),
49        }
50    }
51}
52
53/// A failure of the local storage, rather than of its data
54/// (`StorageFailureError`): the client keeps running on memory.
55#[derive(Clone, Debug, PartialEq, Eq)]
56pub struct StorageFailure {
57    /// What failed.
58    pub kind: StorageFailureKind,
59    /// The error, as the store reported it.
60    pub message: String,
61}
62
63/// What part of the store failed.
64#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
65pub enum StorageFailureKind {
66    /// The device is out of space.
67    Full,
68    /// The database can't be opened.
69    CannotOpen,
70    /// A read or write failed.
71    IoError,
72}
73
74impl StorageFailureKind {
75    /// The kind as JS names it.
76    pub fn as_str(self) -> &'static str {
77        match self {
78            StorageFailureKind::Full => "full",
79            StorageFailureKind::CannotOpen => "cannot-open",
80            StorageFailureKind::IoError => "io-error",
81        }
82    }
83}
84
85impl StorageFailure {
86    /// A failure of `kind`.
87    pub fn new(kind: StorageFailureKind, message: impl Into<String>) -> Self {
88        StorageFailure {
89            kind,
90            message: message.into(),
91        }
92    }
93}
94
95impl fmt::Display for StorageFailure {
96    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97        write!(f, "{}: {}", self.kind.as_str(), self.message)
98    }
99}
100
101impl std::error::Error for StorageFailure {}
102
103/// Why a database couldn't be read.
104#[derive(Clone, Debug, PartialEq, Eq)]
105pub enum LoadError {
106    /// The storage failed: the client runs on memory.
107    Failure(StorageFailure),
108    /// What it holds doesn't decode, so the client state is lost
109    /// (`InvalidRefCountError` in JS): the client drops the database and
110    /// starts a new one.
111    Corrupt(String),
112}
113
114impl From<StorageFailure> for LoadError {
115    fn from(f: StorageFailure) -> Self {
116        LoadError::Failure(f)
117    }
118}
119
120/// What [`Zero::delete`](crate::client::Zero::delete) and
121/// [`drop_all_databases`] deleted.
122#[derive(Clone, Debug, Default, PartialEq, Eq)]
123pub struct DroppedDatabases {
124    /// The names of the databases deleted.
125    pub deleted: Vec<String>,
126    /// The databases that couldn't be deleted.
127    pub errors: Vec<StorageFailure>,
128}
129
130/// A client group: the clients that share a replica because they register
131/// the same mutators (`ClientGroup`).
132#[derive(Clone, Debug, PartialEq)]
133pub struct ClientGroupRecord {
134    /// The group's ID.
135    pub id: String,
136    /// The names of the mutators its clients register.
137    pub mutator_names: Vec<String>,
138    /// The server lost the group, so no new client joins it.
139    pub disabled: bool,
140}
141
142/// A client that used the database (`ClientV6`).
143#[derive(Clone, Debug, PartialEq)]
144pub struct ClientRecord {
145    /// The client's ID.
146    pub id: String,
147    /// The group the client is in.
148    pub client_group_id: String,
149    /// When the client last showed it was running, in ms since 1970.
150    pub heartbeat: f64,
151}
152
153/// A deleted client the server may not know about yet.
154#[derive(Clone, Debug, PartialEq, Eq)]
155pub struct ClientIdPair {
156    /// The client's group.
157    pub client_group_id: String,
158    /// The client's ID.
159    pub client_id: String,
160}
161
162impl ClientIdPair {
163    /// `normalizeDeletedClients`: sorted by group then client, deduplicated.
164    pub fn normalize(mut pairs: Vec<ClientIdPair>) -> Vec<ClientIdPair> {
165        pairs.sort_by(|a, b| {
166            strings::utf16(&a.client_group_id, &b.client_group_id)
167                .then_with(|| strings::utf16(&a.client_id, &b.client_id))
168        });
169        pairs.dedup();
170        pairs
171    }
172}
173
174/// The synced aggregate rows (`a/` keys) a mutation's last run wrote, with
175/// their values after it (`None` for deleted).
176pub type AggregateWrites = Vec<(String, Option<Value>)>;
177
178/// A mutation that ran on a client and the server has not confirmed.
179#[derive(Clone, Debug, PartialEq)]
180pub struct StoredMutation {
181    /// The client that ran it.
182    pub client_id: String,
183    /// Its ID, counting up from 1 per client.
184    pub id: f64,
185    /// The mutator it ran.
186    pub name: String,
187    /// Its arguments.
188    pub args: Value,
189    /// When it ran, in ms since 1970.
190    pub timestamp: f64,
191    /// JS persists these in the mutation's commit; the client runs the
192    /// mutation again at launch, before any query registers the aggregates
193    /// it moves, and puts these back.
194    pub aggregate_writes: AggregateWrites,
195}
196
197/// What a client group keeps: the last server snapshot and the mutations
198/// not yet in it.
199#[derive(Clone, Debug, Default, PartialEq)]
200pub struct StoredGroup {
201    /// The replica: every key the server synced, with its value.
202    pub entries: BTreeMap<String, Value>,
203    /// The server's cookie for the snapshot.
204    pub cookie: Value,
205    /// The last mutation of each client that the snapshot includes.
206    pub last_mutation_ids: BTreeMap<String, f64>,
207    /// In the order they were added.
208    pub mutations: Vec<StoredMutation>,
209}
210
211/// What a database holds besides the groups' data, read when it opens.
212#[derive(Clone, Debug, Default, PartialEq)]
213pub struct StoredClients {
214    /// In the order they were added: a client joins the first that fits.
215    pub groups: Vec<ClientGroupRecord>,
216    /// The clients, in the order they were added.
217    pub clients: Vec<ClientRecord>,
218    /// The deleted clients the server may not know about yet.
219    pub deleted_clients: Vec<ClientIdPair>,
220    /// The profile ID of the device (`profileID`): one for every database
221    /// of the backend.
222    pub profile_id: String,
223}
224
225/// A change to the database, applied in order.
226#[derive(Clone, Debug, PartialEq)]
227pub enum StorageOp {
228    /// Adds the group, or updates whether it is disabled.
229    PutGroup(ClientGroupRecord),
230    /// Deletes the group with its snapshot and mutations.
231    DeleteGroup(String),
232    /// Adds the client, or updates its heartbeat.
233    PutClient(ClientRecord),
234    /// Deletes the clients.
235    DeleteClients(Vec<String>),
236    /// Replaces the deleted clients.
237    SetDeletedClients(Vec<ClientIdPair>),
238    /// The snapshot after a poke: the keys it changed (`None` for deleted),
239    /// whether it cleared every key first, and its cookie and last mutation
240    /// IDs. Drops the mutations the IDs confirm.
241    UpdateSnapshot {
242        /// The group.
243        group: String,
244        /// The keys the poke changed, with their values (`None` for deleted).
245        changes: Vec<(String, Option<Value>)>,
246        /// Whether the poke cleared every key first.
247        cleared: bool,
248        /// The snapshot's cookie.
249        cookie: Value,
250        /// The last mutation of each client the snapshot includes.
251        last_mutation_ids: BTreeMap<String, f64>,
252    },
253    /// Adds a mutation that is pending.
254    AddMutation {
255        /// The group.
256        group: String,
257        /// The mutation.
258        mutation: StoredMutation,
259    },
260    /// What a rebase of a pending mutation wrote to synced aggregate rows.
261    SetAggregateWrites {
262        /// The group.
263        group: String,
264        /// The client that ran the mutation.
265        client_id: String,
266        /// The mutation's ID.
267        id: f64,
268        /// The aggregate rows it wrote.
269        writes: AggregateWrites,
270    },
271    /// Drops the mutations the IDs confirm, keeping the snapshot.
272    DeleteConfirmedMutations {
273        /// The group.
274        group: String,
275        /// The last mutation of each client the server confirmed.
276        last_mutation_ids: BTreeMap<String, f64>,
277    },
278}
279
280/// A place that keeps a client's databases, such as a directory of SQLite
281/// files. Every call is on the client's thread.
282pub trait StorageBackend {
283    /// Where the databases are, such as `sqlite:/path/to/dir`. Clients on
284    /// this thread with the same location and database name share one open
285    /// database, as JS tabs share one IndexedDB database.
286    fn location(&self) -> String;
287
288    /// Opens the database `name`, a new empty one if there is none. `name`
289    /// can hold any character.
290    fn open(&self, name: &str) -> Result<Box<dyn StoredDatabase>, LoadError>;
291
292    /// Deletes the databases that aren't open whose name `matches`.
293    fn drop_databases(&self, matches: &dyn Fn(&str) -> bool) -> DroppedDatabases;
294
295    /// Deletes, in the background, the databases other than `except` that
296    /// no client used for `max_age` ms since `now` (`collectIDBDatabases`),
297    /// such as those of an older schema. Optional.
298    fn collect_databases(&self, except: &str, now: f64, max_age: f64) {
299        let _ = (except, now, max_age);
300    }
301}
302
303/// An open database of a [`StorageBackend`].
304///
305/// Writes may be done later, such as on another thread, but in order. A
306/// failed write stops the writes after it, and is returned by the next
307/// call that can return it; the client then runs on what it has in memory
308/// and calls `ZeroOptions::on_storage_failure`.
309pub trait StoredDatabase {
310    /// The client groups and clients, read once when the database opens.
311    fn load(&self) -> Result<StoredClients, LoadError>;
312
313    /// The snapshot and pending mutations of group `id`; an empty group
314    /// when it has none.
315    fn load_group(&self, id: &str) -> Result<StoredGroup, LoadError>;
316
317    /// Writes `ops`, in order, after the writes before, as one transaction.
318    /// Returns the failure of an earlier write.
319    fn write(&self, ops: &[StorageOp]) -> Result<(), StorageFailure>;
320
321    /// Waits for the writes so far.
322    fn flush(&self) -> Result<(), StorageFailure>;
323
324    /// Closes the database once the writes so far are done.
325    fn close(&self) -> Result<(), StorageFailure>;
326
327    /// Deletes the database, after the writes before. Later writes do
328    /// nothing.
329    fn drop_database(&self);
330}
331
332/// Deletes every Zero database in `storage`, of every user
333/// (`dropAllDatabases`). Clients still open on one keep running on what
334/// they have in memory, and their later writes are dropped.
335pub fn drop_all_databases(storage: &ZeroStorage) -> DroppedDatabases {
336    super::database::ReplicaDatabase::drop_matching(storage, &|_| true)
337}