Skip to main content

coven_database/
journal.rs

1//! The journal as one of coven's steps in a write sees it (§4, §11): sync's
2//! steps read and change the journal's rows, pending records and retry
3//! waits in the write's own transaction, through this, and commit or roll
4//! back with the app's SQL. Sync owns what the rows mean.
5
6use super::FileWrite;
7use crate::{
8    DbError, NewOperation, OperationId, OperationRecord, OperationUpdate, RetrySubject, StoreState,
9};
10
11/// The journal inside one write, for sync's steps.
12pub struct Journal<'write> {
13    files: &'write FileWrite<'write>,
14}
15
16impl<'write> Journal<'write> {
17    pub(crate) fn new(files: &'write FileWrite<'write>) -> Self {
18        Self { files }
19    }
20
21    /// The operation's journal row, as this write sees it; `None` once it
22    /// has finished, or if it never existed.
23    pub fn operation(&self, id: OperationId) -> Result<Option<OperationRecord>, DbError> {
24        crate::operation::find(self.files.database, id)
25    }
26
27    /// The journal's rows of `kind`, oldest first, as this write sees them.
28    pub fn operations(&self, kind: &str) -> Result<Vec<OperationRecord>, DbError> {
29        crate::operation::of_kind(self.files.database, kind)
30    }
31
32    /// Advance an operation one step past the row it read; its pending
33    /// record and retry wait end with the step it left. A row that has
34    /// moved on since fails with `OperationChanged`.
35    pub fn advance_operation(&self, update: &OperationUpdate) -> Result<(), DbError> {
36        crate::operation::advance(self.files.database, update)
37    }
38
39    /// Retire an operation the write's step has ended: its pending record and
40    /// retry wait go with it. An operation that has finished already fails
41    /// with `OperationChanged`.
42    pub fn finish_operation(&self, id: OperationId) -> Result<(), DbError> {
43        if crate::operation::finish(self.files.database, id)? != 1 {
44            return Err(DbError::OperationChanged(id));
45        }
46        Ok(())
47    }
48
49    /// Membership and audience state after the applied slots, as this
50    /// write sees it.
51    pub fn store_state(&self) -> Result<StoreState, DbError> {
52        crate::store_state_tables::read(self.files.database)
53    }
54
55    /// The last slot whose effects this device has applied.
56    pub fn applied_slot(&self) -> Result<u64, DbError> {
57        crate::sequence::applied(self.files.database)
58    }
59
60    /// Journal an operation before its first step, which sync runs and
61    /// ends on its own; `coven_operations` doesn't list it.
62    pub fn start_operation(&self, operation: &NewOperation) -> Result<OperationId, DbError> {
63        crate::operation::insert(self.files.database, operation)
64    }
65
66    /// Journal an operation the app's write asks for, of `kind` as sync
67    /// names it, before its first step. It is listed in `coven_operations`
68    /// from this write's commit until the app acknowledges its outcome.
69    pub fn start_app_operation(
70        &self,
71        operation: &NewOperation,
72        kind: &str,
73    ) -> Result<OperationId, DbError> {
74        crate::operation::insert_for_app(self.files.database, operation, kind)
75    }
76
77    /// End the app's record of a finished operation: it leaves
78    /// `coven_operations`. One still running fails with `OperationRunning`;
79    /// one this device doesn't list, never journaled by the app or
80    /// acknowledged already, with `OperationUnknown`.
81    pub(crate) fn acknowledge(&self, id: OperationId) -> Result<(), DbError> {
82        crate::operation::acknowledge(self.files.database, id)
83    }
84
85    /// The pending record that names the operation, if any.
86    pub fn operation_pending<P: crate::PendingValue>(
87        &self,
88        id: OperationId,
89    ) -> Result<Option<P>, DbError> {
90        crate::pending::operation(self.files.database, id)
91    }
92
93    /// Whether automatic work can retry the subject with the coven and
94    /// schema versions installed now.
95    pub fn pending_can_retry<P: crate::PendingValue>(
96        &self,
97        subject: &P::Subject,
98    ) -> Result<bool, DbError> {
99        crate::pending::retry::<P>(self.files.database, self.files.call, subject)
100    }
101
102    /// Clear the subject's pending record.
103    pub fn clear_pending<S: serde::Serialize>(&self, subject: &S) -> Result<(), DbError> {
104        crate::pending::clear(self.files.database, subject)
105    }
106
107    /// Clear the subject's retry wait.
108    pub fn clear_retry(&self, subject: RetrySubject) -> Result<(), DbError> {
109        crate::retry::clear(self.files.database, subject)
110    }
111}
112
113#[cfg(test)]
114#[path = "journal_tests.rs"]
115mod tests;