Skip to main content

coven_database/
database_operations.rs

1//! Operation transactions, borrowing the database owner's connections.
2
3use super::StoreDatabase;
4use crate::write_failure::{hosted, Hosted};
5use crate::{DbError, NewOperation, OperationId, OperationRecord, OperationUpdate};
6use coven_foundation::id_source::DeviceId;
7use std::collections::BTreeSet;
8
9impl StoreDatabase {
10    /// Read every unfinished operation, including permanently failed ones.
11    pub async fn operations(&self) -> Result<Vec<OperationRecord>, DbError> {
12        self.call(move |inner| inner.access.with_committed(|db, _| crate::operation::read(db)))
13            .await
14    }
15
16    /// Read one committed journal row without loading unrelated operation data.
17    /// Absence means the operation has finished or never existed.
18    pub async fn operation(&self, id: OperationId) -> Result<Option<OperationRecord>, DbError> {
19        self.call(move |inner| {
20            inner.access.with_committed(|writer, _| crate::operation::find(writer, id))
21        })
22        .await
23    }
24
25    /// The journal's rows of `kind`, oldest first, in one committed state.
26    pub async fn operations_of_kind(&self, kind: &str) -> Result<Vec<OperationRecord>, DbError> {
27        let kind = kind.to_owned();
28        self.read_committed(move |db| crate::operation::of_kind(db, &kind)).await
29    }
30
31    /// The same rows, live: a status that follows one operation reads them
32    /// (E4).
33    pub fn subscribe_operations_of_kind<E>(
34        &self,
35        kind: &str,
36    ) -> crate::LiveQuery<Vec<OperationRecord>, E>
37    where
38        E: From<DbError> + coven_foundation::task::CarriesBug + Send + 'static,
39    {
40        let kind = kind.to_owned();
41        self.follow(move |db| crate::operation::of_kind(db, &kind).map_err(E::from))
42    }
43
44    /// Read the earliest unfinished row of a sync-owned kind, including failures.
45    pub async fn first_operation(&self, kind: &str) -> Result<Option<OperationRecord>, DbError> {
46        let kind = kind.to_owned();
47        self.call(move |inner| {
48            inner.access.with_committed(|writer, _| crate::operation::first(writer, &kind))
49        })
50        .await
51    }
52
53    /// Commit the operation before its first step.
54    pub async fn start_operation(&self, operation: NewOperation) -> Result<OperationId, DbError> {
55        self.call(move |inner| {
56            inner.access.with_writer(|writer, _| {
57                writer.transaction(|db| crate::operation::insert(db, &operation))
58            })
59        })
60        .await
61    }
62
63    /// Commit an operation a call of the app's starts, before its first
64    /// step, listed in `coven_operations` as `kind` names it from this
65    /// commit until a write acknowledges its outcome (§11.4, §11.6).
66    pub async fn start_listed_operation(
67        &self,
68        operation: NewOperation,
69        kind: String,
70    ) -> Result<OperationId, DbError> {
71        self.call(move |inner| {
72            inner.access.with_writer(|writer, _| {
73                writer.transaction(|db| crate::operation::insert_for_app(db, &operation, &kind))
74            })
75        })
76        .await
77    }
78
79    /// Commit a new operation and a step of another that names it, in one
80    /// transaction: `update` builds the step from the new operation's id. A
81    /// parent that journals a child this way never loses track of it, nor
82    /// starts a second one, whenever it stops.
83    pub async fn start_operation_advancing<E: crate::WriteFailure + Send + 'static>(
84        &self,
85        operation: NewOperation,
86        update: impl FnOnce(OperationId) -> Result<OperationUpdate, E> + Send + 'static,
87    ) -> Result<OperationId, E> {
88        self.call(move |inner| {
89            inner.access.with_writer(|writer, _| {
90                writer
91                    .transaction(|db| {
92                        hosted(|| {
93                            let id = crate::operation::insert(db, &operation)?;
94                            crate::operation::advance(db, &update(id)?)?;
95                            Ok(id)
96                        })
97                    })
98                    .map_err(Hosted::into_inner)
99            })
100        })
101        .await
102    }
103
104    /// Reserve the path number of a snapshot attempt or a floor body about to
105    /// be prepared: the next of this device's sequence, never reused, which
106    /// §19.3 compares with its stored snapshots.
107    pub async fn reserve_snapshot_number(&self) -> Result<std::num::NonZeroU64, DbError> {
108        self.call(move |inner| {
109            inner
110                .access
111                .with_writer(|writer, _| writer.transaction(crate::operation::reserve_snapshot))
112        })
113        .await
114    }
115
116    /// Commit a local step's state after an idempotent storage effect.
117    pub async fn advance_operation(&self, update: OperationUpdate) -> Result<(), DbError> {
118        self.call(move |inner| {
119            inner.access.with_writer(|writer, _| {
120                writer.transaction(|db| crate::operation::advance(db, &update))
121            })
122        })
123        .await
124    }
125
126    /// Commit the step that journals a captured body, the file `name` of
127    /// `size` bytes, and count the file among the store's own files, in one
128    /// transaction (§17.8): the count starts as the journal takes the file.
129    pub async fn advance_operation_counting_capture(
130        &self,
131        update: OperationUpdate,
132        name: String,
133        size: u64,
134    ) -> Result<(), DbError> {
135        self.call(move |inner| {
136            inner.access.with_writer(|writer, _| {
137                writer.transaction(|db| {
138                    crate::operation::advance(db, &update)?;
139                    crate::database::library_bytes::count_capture(db, &name, size)
140                })
141            })
142        })
143        .await
144    }
145
146    /// Read the journal's rows of `kind` and commit the transitions `step`
147    /// makes from them, in one transaction on the writer: no other write
148    /// comes between the read and the transitions. `step` also returns what
149    /// it concluded from the rows. A failure fails this handle with its
150    /// cause, as losing a pending record does: the rows would go on showing
151    /// the app a state their owner has left.
152    pub async fn advance_operations<T: Send + 'static>(
153        &self,
154        kind: &str,
155        step: impl FnOnce(&[OperationRecord]) -> Result<(Vec<OperationUpdate>, T), DbError>
156            + Send
157            + 'static,
158    ) -> Result<T, DbError> {
159        let kind = kind.to_owned();
160        self.call(move |inner| {
161            inner.access.with_writer(|writer, _| {
162                crate::pending::state_transaction(writer, |db| {
163                    let (updates, concluded) = step(&crate::operation::of_kind(db, &kind)?)?;
164                    for update in &updates {
165                        crate::operation::advance(db, update)?;
166                    }
167                    Ok(concluded)
168                })
169            })
170        })
171        .await
172    }
173
174    /// Read the journal's rows of `kind`, then commit the transitions and
175    /// endings `step` makes from them, in one transaction on the writer, as
176    /// `advance_operations` does. An ending removes the row with its pending
177    /// record and retry wait.
178    pub async fn settle_operations<T: Send + 'static>(
179        &self,
180        kind: &str,
181        step: impl FnOnce(
182                &[OperationRecord],
183            ) -> Result<(Vec<OperationUpdate>, Vec<OperationId>, T), DbError>
184            + Send
185            + 'static,
186    ) -> Result<T, DbError> {
187        let kind = kind.to_owned();
188        self.call(move |inner| {
189            inner.access.with_writer(|writer, _| {
190                crate::pending::state_transaction(writer, |db| {
191                    let (updates, finished, concluded) =
192                        step(&crate::operation::of_kind(db, &kind)?)?;
193                    for update in &updates {
194                        crate::operation::advance(db, update)?;
195                    }
196                    for id in finished {
197                        if crate::operation::finish(db, id)? != 1 {
198                            return Err(DbError::OperationChanged(id));
199                        }
200                    }
201                    Ok(concluded)
202                })
203            })
204        })
205        .await
206    }
207
208    /// Advance an operation one step and record the deletion it leaves owed,
209    /// in one transaction: an ended pairing's marker, which goes once a
210    /// request can no longer reach its path (§13.2).
211    pub async fn advance_operation_with_removal(
212        &self,
213        update: OperationUpdate,
214        removal: crate::ObjectRemoval,
215    ) -> Result<(), DbError> {
216        self.call(move |inner| {
217            inner.access.with_writer(|writer, _| {
218                writer.transaction(|db| {
219                    crate::operation::advance(db, &update)?;
220                    crate::object_removals::record(db, &removal)
221                })
222            })
223        })
224        .await
225    }
226
227    /// Record member pairs this installation holds, or is about to keep in
228    /// custody, before custody keeps them: applying a binding of its member
229    /// to a pair not recorded stops it for good (§12.3).
230    pub async fn hold_member_keys(
231        &self,
232        keys: Vec<coven_crypto::MemberPublicKeys>,
233    ) -> Result<(), DbError> {
234        self.call(move |inner| {
235            inner.access.with_writer(|writer, _| {
236                writer.transaction(|db| crate::operation::hold_keys(db, &keys))
237            })
238        })
239        .await
240    }
241
242    /// Read the pending condition associated with a journal row.
243    pub async fn operation_pending<P: crate::PendingValue>(
244        &self,
245        id: OperationId,
246    ) -> Result<Option<P>, DbError> {
247        self.call(move |inner| inner.access.with_writer(|db, _| crate::pending::operation(db, id)))
248            .await
249    }
250
251    /// Clear a condition for an explicit retry; completed steps stay recorded.
252    #[cfg(test)]
253    pub async fn retry_operation(&self, id: OperationId) -> Result<(), DbError> {
254        self.call(move |inner| {
255            inner.access.with_writer(|writer, _| {
256                writer.transaction(|db| crate::pending::clear_operation(db, id))
257            })
258        })
259        .await
260    }
261
262    /// Commit completed work and its first remaining condition in one transaction.
263    #[cfg(test)]
264    pub async fn advance_operation_pending<P: crate::PendingValue>(
265        &self,
266        update: OperationUpdate,
267        pending: P,
268    ) -> Result<(), DbError> {
269        self.call(move |inner| {
270            inner.access.with_writer(|writer, _| {
271                if pending.operation() != Some(update.id) {
272                    return Err(DbError::Invariant {
273                        what: "an operation's condition names its journal row",
274                    });
275                }
276                writer.transaction(|db| {
277                    crate::operation::advance(db, &update)?;
278                    crate::pending::save(db, &pending)
279                })
280            })
281        })
282        .await
283    }
284
285    /// Retire a finished operation with its outcome, in the outcome type of
286    /// its kind, which `coven_operations` lists for an operation the app's
287    /// write journaled, in the same transaction: an outcome nobody awaits is
288    /// never lost (§11.4). `None` for a kind `coven_operations` never lists.
289    /// An operation that has ended already fails with `OperationChanged`.
290    pub async fn finish_operation_with_outcome(
291        &self,
292        id: OperationId,
293        outcome: Option<crate::ListedOutcome>,
294    ) -> Result<(), DbError> {
295        self.call(move |inner| {
296            inner.access.with_writer(|writer, _| {
297                writer.transaction(|db| {
298                    crate::operation::finish_with_outcome(db, id, outcome.as_ref())
299                })
300            })
301        })
302        .await
303    }
304
305    /// Retire an ended invite in one commit with the operations it started
306    /// that are still journaled, its `children`, and with the deletion it
307    /// leaves owed: its marker's, once that has passed (§13.2). An `outcome`
308    /// the invite ends with, with its `kind` as `coven_operations` lists it,
309    /// is listed there until the app acknowledges it. An invite, or a child,
310    /// that has ended already fails with `OperationChanged`.
311    pub async fn finish_operation_with_removal(
312        &self,
313        id: OperationId,
314        children: Vec<OperationId>,
315        removal: crate::ObjectRemoval,
316        outcome: Option<(String, crate::InviteOutcome)>,
317    ) -> Result<(), DbError> {
318        self.call(move |inner| {
319            inner.access.with_writer(|writer, _| {
320                writer.transaction(|db| {
321                    // The invite's outcome is listed in `coven_operations`
322                    // until the app acknowledges it, the journal row's end
323                    // requiring it written first.
324                    if let Some((kind, outcome)) = &outcome {
325                        crate::operation::list_outcome(db, id, kind, outcome)?;
326                    }
327                    for id in children.iter().copied().chain([id]) {
328                        if crate::operation::finish(db, id)? != 1 {
329                            return Err(DbError::OperationChanged(id));
330                        }
331                    }
332                    crate::object_removals::record(db, &removal)
333                })
334            })
335        })
336        .await
337    }
338
339    /// End an operation another started in the transaction that advances
340    /// its parent past it: the parent's step and the child's end commit
341    /// together, so no restart finds one without the other. The child's
342    /// `outcome`, for one `coven_operations` lists, is written as
343    /// `finish_operation_with_outcome` writes it. A parent that has moved on
344    /// since, or a child already ended, fails with `OperationChanged`.
345    pub async fn finish_operation_advancing(
346        &self,
347        child: OperationId,
348        outcome: Option<crate::ListedOutcome>,
349        parent: OperationUpdate,
350    ) -> Result<(), DbError> {
351        self.call(move |inner| {
352            inner.access.with_writer(|writer, _| {
353                writer.transaction(|db| {
354                    crate::operation::advance(db, &parent)?;
355                    crate::operation::finish_with_outcome(db, child, outcome.as_ref())
356                })
357            })
358        })
359        .await
360    }
361
362    /// End every operation the app's writes journaled that still runs, and
363    /// every invite this device made, as the transaction applying a stop for
364    /// good does, for a stop no slot applies: history shows another copy of
365    /// this installation using its device id (§19.3). A failure fails this
366    /// handle with its cause: they would otherwise run, listed, forever.
367    pub async fn end_for_good(&self, stop: crate::DeviceStop) -> Result<(), DbError> {
368        self.call(move |inner| {
369            inner.access.with_writer(|writer, _| {
370                crate::pending::state_transaction(writer, |db| {
371                    crate::operation::end_for_good(db, stop)
372                })
373            })
374        })
375        .await
376    }
377
378    /// `end_for_good` for history showing another copy of this installation
379    /// using its device id at `slot`, which also records the stop in the
380    /// same transaction, so a reset can tell this copy from a damaged
381    /// database (§19.3). The record stays until a reset or deletion.
382    pub async fn end_for_copy(&self, slot: coven_merge::Slot) -> Result<(), DbError> {
383        self.call(move |inner| {
384            inner.access.with_writer(|writer, _| {
385                crate::pending::state_transaction(writer, |db| {
386                    crate::operation::end_for_copy(db, slot)
387                })
388            })
389        })
390        .await
391    }
392
393    /// Stop at this device's own removal, or its member's, which a reload
394    /// found in history past the slots this device applied: install `state`,
395    /// what the device keeps at the removal, over the device's own rows, and
396    /// end what its app journaled, as the transaction applying the removal's
397    /// slot does. The device keeps its copy and its applied slot (§14.1,
398    /// §16.5).
399    pub async fn stop_at_removal(&self, state: crate::StoreState) -> Result<(), DbError> {
400        self.call(move |inner| {
401            let reader = inner.access.database.reader();
402            inner.with_files("stop at the device's removal", |writer, call, files| {
403                inner.access.with_leased(&reader, |reader, reader_call| {
404                    crate::transaction_constants::read_with_constants(reader, reader_call, || {
405                        crate::write_schema::prepare_evaluators(
406                            reader,
407                            &inner.access.write_schema,
408                        )?;
409                        crate::transaction_constants::schema_version(reader, reader_call)?;
410                        crate::own_removal::stop(
411                            writer,
412                            call,
413                            reader,
414                            reader_call,
415                            &inner.access.write_schema,
416                            &state,
417                            files,
418                        )
419                    })
420                })
421            })
422        })
423        .await
424    }
425
426    /// How the applied state stops this installation for good, if it does:
427    /// its device removed or replaced, its member removed, or its member
428    /// bound to a pair it doesn't hold (§14.1). `None` while the applied
429    /// state doesn't name its device. A restore ending without its store
430    /// reads it for the facts (§13.1).
431    pub async fn device_stop(&self) -> Result<Option<crate::DeviceStop>, DbError> {
432        self.call(|inner| inner.access.with_committed(|db, _| crate::operation::stopped(db))).await
433    }
434
435    /// The paths of objects whose time to go has passed by `now`, in seconds
436    /// since the Unix epoch.
437    pub async fn due_object_removals(&self, now: u64) -> Result<Vec<String>, DbError> {
438        let now = i64::try_from(now).unwrap_or(i64::MAX);
439        self.call(move |inner| {
440            inner.access.with_committed(|db, _| {
441                Ok(db.query(
442                    "SELECT path FROM _coven_object_removals WHERE after<=?1 ORDER BY after",
443                    [now],
444                    |r| r.get(0),
445                )?)
446            })
447        })
448        .await
449    }
450
451    /// The object at `path` is gone from storage.
452    pub async fn object_removed(&self, path: String) -> Result<(), DbError> {
453        self.call(move |inner| {
454            inner.access.with_writer(|writer, _| {
455                writer.transaction(|db| crate::object_removals::removed(db, &path))
456            })
457        })
458        .await
459    }
460
461    /// The devices gone for good whose join requests this device ended
462    /// (§13.2).
463    pub async fn requests_ended(&self) -> Result<BTreeSet<DeviceId>, DbError> {
464        self.call(move |inner| {
465            inner.access.with_committed(|db, _| {
466                Ok(db.query("SELECT device FROM _coven_requests_ended", [], |r| {
467                    r.get::<_, DeviceId>(0)
468                })?)
469            })
470        })
471        .await
472        .map(|devices| devices.into_iter().collect())
473    }
474
475    /// This device ended `device`'s join requests: its gone marker is in
476    /// storage, and nothing else was under its requests when listed (§13.2).
477    pub async fn record_requests_ended(&self, device: DeviceId) -> Result<(), DbError> {
478        self.call(move |inner| {
479            inner.access.with_writer(|writer, _| {
480                writer.transaction(|db| {
481                    Ok(db
482                        .execute("INSERT INTO _coven_requests_ended(device) VALUES(?1)", [device])
483                        .map(drop)?)
484                })
485            })
486        })
487        .await
488    }
489
490    /// The devices gone for good whose storage this device cleared once
491    /// (§16.6, §17.10).
492    pub async fn gone_storage_cleared(&self) -> Result<BTreeSet<DeviceId>, DbError> {
493        self.call(move |inner| {
494            inner.access.with_committed(|db, _| {
495                Ok(db.query("SELECT device FROM _coven_gone_storage_cleared", [], |r| {
496                    r.get::<_, DeviceId>(0)
497                })?)
498            })
499        })
500        .await
501        .map(|devices| devices.into_iter().collect())
502    }
503
504    /// This device ended the uploads `device` left, listed its snapshot
505    /// folders and deleted every body there that no announcement names
506    /// (§16.6, §17.10). Recording it again, after clearing repeated because
507    /// its operation hadn't finished, changes nothing.
508    pub async fn record_gone_storage_cleared(&self, device: DeviceId) -> Result<(), DbError> {
509        self.call(move |inner| {
510            inner.access.with_writer(|writer, _| {
511                writer.transaction(|db| {
512                    Ok(db.execute(
513                        "INSERT INTO _coven_gone_storage_cleared(device) VALUES(?1) ON CONFLICT DO NOTHING",
514                        [device],
515                    )
516                    .map(drop)?)
517                })
518            })
519        })
520        .await
521    }
522
523    /// Retire a finished operation. The caller must publish every reserved entry
524    /// before discarding; removing this row cannot retire the publication queue.
525    pub async fn finish_operation(&self, id: OperationId) -> Result<(), DbError> {
526        self.call(move |inner| {
527            inner.access.with_writer(|writer, _| {
528                writer.transaction(|db| crate::operation::finish(db, id).map(drop))
529            })
530        })
531        .await
532    }
533}