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}