Skip to main content

coven_database/
pending.rs

1//! Typed persistence for sync-owned pending values, without depending on providers.
2
3use crate::sqlite::StoreSql;
4use crate::store_call::StoreCall;
5use crate::{DbError, OperationId};
6use coven_foundation::id_source::{DeviceId, FileId, ObjectId};
7use serde::{de::DeserializeOwned, Serialize};
8use std::sync::Arc;
9
10/// Which of this device's work on a file's stored bytes a record is about.
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum FileWork {
13    /// Its upload of them, and its reads of their staged original.
14    Upload,
15    /// Its downloads of them, for the app's pins, whose failures alone are
16    /// recorded. A download's record lasts only while a file over the bytes
17    /// does (§19.1).
18    Download,
19}
20
21/// Sync supplies its complete typed record; the database owns its atomic lifetime.
22/// The associated subject is the stable key, independent of the reason.
23///
24/// `coven_pending` reads the record's JSON: its `subject` and `reason`, when
25/// present, are enum variants as serde writes them, and an `Original` reason's
26/// `path` is an array of the path's bytes. JSON of another shape fails the
27/// write that stores it as a damaged database.
28pub trait PendingValue: Serialize + DeserializeOwned + Send + 'static {
29    /// Report a batch consumed after a preceding removal or key replacement.
30    fn writes_refused(
31        slot: coven_merge::Slot,
32        cutoff: coven_merge::Slot,
33        cause: crate::WriteCutoff,
34    ) -> Self;
35    /// Report an audience whose selected boundary has no committed data input.
36    fn reload(audience: coven_merge::Audience) -> Self;
37    /// Report one account's unresolved intended sharing change.
38    fn provider_access(operation: OperationId, account: String, grant: bool) -> Self;
39    /// Stable identity, ordered as the app presents it.
40    type Subject: Serialize + Ord;
41    /// The work that cannot advance.
42    fn subject(&self) -> &Self::Subject;
43    /// The journal row, if this record describes an operation.
44    fn operation(&self) -> Option<OperationId>;
45    /// The stored object this record describes, by its uploader and id,
46    /// and which work on it, if any: how coven's views join a record to
47    /// the rows whose file it is.
48    fn object(&self) -> Option<(FileWork, DeviceId, ObjectId)>;
49    /// The move this record describes, if any: cancelling the move ends it.
50    fn move_of(&self) -> Option<crate::MoveId>;
51    /// The file whose pin coven keeps this record describes, if any: the
52    /// record ends with the pin request.
53    fn pin_of(&self) -> Option<FileId>;
54    /// Sequence slot whose progress clears this observation.
55    fn slot(&self) -> Option<coven_merge::Slot>;
56    /// Whether a slot coverage including this object without applying it, as a
57    /// loaded snapshot's do, also end this observation: true for a write that
58    /// waits, false for a verdict on its bytes, which loading never clears (§19.1).
59    fn ends_when_covered(&self) -> bool;
60    /// The build of coven that judges these records, which every record
61    /// saved names: one draws its own at each compilation, so a change to the
62    /// code that judges gives another (§19.1).
63    const BUILD: u128;
64    /// Whether automatic work can retry, given the build that recorded this
65    /// record and the app's installed schema version.
66    fn can_retry(&self, recorded_build: u128, schema_version: u32) -> bool;
67    /// The text of the error behind this record, which `_coven_pending`
68    /// keeps beside it in the same write: none when no error was met in
69    /// this run, or when an app call received it.
70    fn cause(&self) -> Option<&str>;
71    /// This record as read back, with the cause its row keeps.
72    fn with_cause(self, cause: Option<String>) -> Self;
73}
74
75/// A subject as `_coven_pending.subject` keys its record: the subject's
76/// JSON, which sync's types give one spelling.
77#[derive(Clone, Debug, PartialEq, Eq)]
78pub(crate) struct SubjectKey(Vec<u8>);
79
80impl SubjectKey {
81    pub(crate) fn of<S: Serialize>(subject: &S) -> Result<Self, DbError> {
82        serde_json::to_vec(subject).map(Self).map_err(DbError::StateEncoding)
83    }
84}
85
86impl sqlive::rusqlite::ToSql for SubjectKey {
87    fn to_sql(&self) -> sqlive::rusqlite::Result<sqlive::rusqlite::types::ToSqlOutput<'_>> {
88        self.0.to_sql()
89    }
90}
91
92impl sqlive::rusqlite::types::FromSql for SubjectKey {
93    fn column_result(
94        value: sqlive::rusqlite::types::ValueRef<'_>,
95    ) -> sqlive::rusqlite::types::FromSqlResult<Self> {
96        Vec::column_result(value).map(Self)
97    }
98}
99
100const SELECT: &str =
101    "SELECT subject,value,operation,slot_key,work,device,object,build,move,pin,cause,id FROM _coven_pending";
102
103struct StoredRecord {
104    /// Its place in the order the records arose.
105    position: i64,
106    subject: SubjectKey,
107    value: Vec<u8>,
108    operation: Option<i64>,
109    slot_key: Option<Vec<u8>>,
110    object: Option<(String, DeviceId, ObjectId)>,
111    /// The build of coven that recorded it.
112    build: u128,
113    moved: Option<i64>,
114    pin: Option<String>,
115    cause: Option<String>,
116}
117impl StoredRecord {
118    fn read(row: &sqlive::rusqlite::Row<'_>) -> sqlive::rusqlite::Result<Self> {
119        Ok(Self {
120            subject: row.get(0)?,
121            value: row.get(1)?,
122            operation: row.get(2)?,
123            slot_key: row.get(3)?,
124            object: match (
125                row.get::<_, Option<String>>(4)?,
126                row.get::<_, Option<DeviceId>>(5)?,
127                row.get::<_, Option<ObjectId>>(6)?,
128            ) {
129                (Some(work), Some(device), Some(object)) => Some((work, device, object)),
130                (None, None, None) => None,
131                _ => {
132                    return Err(crate::write_encoding::damaged(
133                        4,
134                        sqlive::rusqlite::types::Type::Text,
135                    ))
136                }
137            },
138            build: u128::from_be_bytes(row.get(7)?),
139            moved: row.get(8)?,
140            pin: row.get(9)?,
141            cause: row.get(10)?,
142            position: row.get(11)?,
143        })
144    }
145    fn decode<P: PendingValue>(&self) -> Result<P, DbError> {
146        let record: P = serde_json::from_slice(&self.value).map_err(DbError::StateEncoding)?;
147        if SubjectKey::of(record.subject())? != self.subject
148            || record.operation().map(|id| id.0) != self.operation
149            || record.move_of().map(|id| id.0) != self.moved
150            || record.pin_of().map(|file| file.to_string()) != self.pin
151            || stored_slot_key(&record) != self.slot_key
152            || stored_object(&record)
153                != self
154                    .object
155                    .as_ref()
156                    .map(|(work, device, object)| (work.as_str(), *device, *object))
157        {
158            return Err(DbError::DamagedDatabase);
159        }
160        Ok(record.with_cause(self.cause.clone()))
161    }
162}
163
164/// Every record, in the order the records arose, as `coven_pending` lists
165/// them by position.
166pub(crate) fn read<P: PendingValue>(db: &StoreSql) -> Result<Vec<P>, DbError> {
167    Ok(positioned(db)?.into_iter().map(|(_, record)| record).collect())
168}
169
170/// Every record with its place, in the order the records arose, as
171/// `coven_pending.position` names it.
172pub(crate) fn positioned<P: PendingValue>(db: &StoreSql) -> Result<Vec<(i64, P)>, DbError> {
173    db.query(&format!("{SELECT} ORDER BY id"), [], StoredRecord::read)?
174        .iter()
175        .map(|stored| Ok((stored.position, stored.decode::<P>()?)))
176        .collect()
177}
178
179/// Save `$record` on `$db`, a store's open write or a test's connection
180/// outside any store. Both expand this one body, so a test records a
181/// pending record as a store does.
182macro_rules! save_record {
183    ($db:expr, $record:expr) => {{
184        let (db, record) = ($db, $record);
185        let subject = SubjectKey::of(record.subject())?;
186        let value = serde_json::to_vec(record).map_err(DbError::StateEncoding)?;
187        let (work, device, object) = match stored_object(record) {
188            Some((work, device, object)) => (Some(work), Some(device), Some(object)),
189            None => (None, None, None),
190        };
191        // A download of bytes no file over them names any more records
192        // nothing: no pin or read can try them again. The cause is the
193        // record's, written with it.
194        db.execute(
195            "INSERT INTO _coven_pending(subject,value,operation,slot_key,work,device,object,build,move,pin,cause)
196             SELECT ?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11
197             WHERE ?5 IS NOT 'download' OR EXISTS(SELECT 1 FROM _coven_stored_files AS s WHERE s.device=?6 AND s.object=?7)
198             ON CONFLICT(subject) DO UPDATE SET value=excluded.value,operation=excluded.operation,slot_key=excluded.slot_key,work=excluded.work,device=excluded.device,object=excluded.object,build=excluded.build,move=excluded.move,pin=excluded.pin,cause=excluded.cause
199             WHERE value!=excluded.value OR build!=excluded.build OR cause IS NOT excluded.cause",
200            sqlive::rusqlite::params![subject, value, record.operation().map(|id| id.0), stored_slot_key(record), work, device, object, P::BUILD.to_be_bytes(), record.move_of(), record.pin_of(), record.cause()],
201        )?;
202        Ok::<(), DbError>(())
203    }};
204}
205
206pub(crate) fn save<P: PendingValue>(db: &StoreSql, record: &P) -> Result<(), DbError> {
207    pending_change(db, || save_record!(db, record))
208}
209
210/// Save `record` on `connection`, a test's connection outside any store, as
211/// `save` does, so that coven's triggers show it in `coven_pending`.
212#[cfg(any(test, feature = "test-utils"))]
213pub fn save_outside_store<P: PendingValue>(
214    connection: &sqlive::rusqlite::Connection,
215    record: &P,
216) -> Result<(), DbError> {
217    save_record!(connection, record)
218}
219
220/// Opening clears every record's cause: a cause names an error the run that
221/// wrote it met, and a later run has met none of its own yet (§19.1). It
222/// runs before any app query observes the database.
223pub(crate) fn forget_causes(db: &StoreSql) -> Result<(), DbError> {
224    db.execute("UPDATE _coven_pending SET cause=NULL WHERE cause IS NOT NULL", [])?;
225    Ok(())
226}
227
228pub(crate) fn clear<S: Serialize>(db: &StoreSql, subject: &S) -> Result<(), DbError> {
229    clear_key(db, &SubjectKey::of(subject)?)
230}
231
232/// Clear the record of a subject already encoded for its key.
233pub(crate) fn clear_key(db: &StoreSql, subject: &SubjectKey) -> Result<(), DbError> {
234    pending_change(db, || {
235        db.execute("DELETE FROM _coven_pending WHERE subject=?1", [subject])?;
236        Ok(())
237    })
238}
239
240/// Clear the record of the move `id`, whatever it says.
241pub(crate) fn clear_move(db: &StoreSql, id: crate::MoveId) -> Result<(), DbError> {
242    pending_change(db, || {
243        db.execute("DELETE FROM _coven_pending WHERE move=?1", [id])?;
244        Ok(())
245    })
246}
247
248/// An operation's retry wait lives only while its condition does: advancing,
249/// finishing or an explicit retry ends both (§6.7).
250pub(crate) fn clear_operation(db: &StoreSql, id: OperationId) -> Result<(), DbError> {
251    crate::retry::clear(db, crate::RetrySubject::Operation(id))?;
252    pending_change(db, || {
253        db.execute(CLEAR_OPERATION, [id.0])?;
254        Ok(())
255    })
256}
257
258/// Deletes the pending record of the operation with this id.
259const CLEAR_OPERATION: &str = "DELETE FROM _coven_pending WHERE operation=?1";
260
261/// Clear the pending record of the operation `id` on `connection`, a test's
262/// connection outside any store, as `clear_operation` does. No test write
263/// makes a retry wait outside a store, so this function clears no retry
264/// wait.
265#[cfg(any(test, feature = "test-utils"))]
266pub(crate) fn clear_operation_outside_store(
267    connection: &sqlive::rusqlite::Connection,
268    id: OperationId,
269) -> Result<(), DbError> {
270    connection.execute(CLEAR_OPERATION, [id.0])?;
271    Ok(())
272}
273
274/// Whether the operation `id` has a pending record.
275pub(crate) fn operation_recorded(db: &StoreSql, id: OperationId) -> Result<bool, DbError> {
276    Ok(db.query_row(
277        "SELECT EXISTS(SELECT 1 FROM _coven_pending WHERE operation=?1)",
278        [id.0],
279        |r| r.get(0),
280    )?)
281}
282
283pub(crate) fn operation<P: PendingValue>(
284    db: &StoreSql,
285    id: OperationId,
286) -> Result<Option<P>, DbError> {
287    db.query(&format!("{SELECT} WHERE operation=?1"), [id.0], StoredRecord::read)?
288        .pop()
289        .map(|r| r.decode())
290        .transpose()
291}
292
293/// Whether a subject has a local record.
294pub(crate) fn recorded<S: Serialize>(db: &StoreSql, subject: &S) -> Result<bool, DbError> {
295    Ok(db.query_row(
296        "SELECT EXISTS(SELECT 1 FROM _coven_pending WHERE subject=?1)",
297        [SubjectKey::of(subject)?],
298        |r| r.get(0),
299    )?)
300}
301
302/// A subject's stored record, if it has one.
303fn stored<S: Serialize>(db: &StoreSql, subject: &S) -> Result<Option<StoredRecord>, DbError> {
304    Ok(db
305        .query(
306            &format!("{SELECT} WHERE subject=?1"),
307            [SubjectKey::of(subject)?],
308            StoredRecord::read,
309        )?
310        .pop())
311}
312
313/// The current local record for a subject, if any.
314pub(crate) fn find<P: PendingValue>(
315    db: &StoreSql,
316    subject: &P::Subject,
317) -> Result<Option<P>, DbError> {
318    stored(db, subject)?.map(|stored| stored.decode()).transpose()
319}
320
321pub(crate) fn retry<P: PendingValue>(
322    db: &StoreSql,
323    call: &StoreCall<'_>,
324    subject: &P::Subject,
325) -> Result<bool, DbError> {
326    match stored(db, subject)? {
327        None => Ok(true),
328        Some(stored) => Ok(stored
329            .decode::<P>()?
330            .can_retry(stored.build, crate::transaction_constants::schema_version(db, call)?)),
331    }
332}
333
334/// Make every record one `build` recorded, as a store opened by another
335/// build of coven finds the records an earlier one wrote.
336#[cfg(any(test, feature = "test-utils"))]
337pub(crate) fn set_build(db: &StoreSql, build: u128) -> Result<(), DbError> {
338    pending_change(db, || {
339        db.execute("UPDATE _coven_pending SET build=?1", [build.to_be_bytes()])?;
340        Ok(())
341    })
342}
343
344fn slot_key(slot: coven_merge::Slot, covered: bool) -> Vec<u8> {
345    let mut key = vec![u8::from(covered)];
346    key.extend(slot.get().to_be_bytes());
347    key
348}
349const COVERED_SLOT: u8 = 1;
350
351/// The record's stored object and work on it, as `_coven_pending` holds them.
352fn stored_object<P: PendingValue>(record: &P) -> Option<(&'static str, DeviceId, ObjectId)> {
353    record.object().map(|(work, device, object)| {
354        let work = match work {
355            FileWork::Upload => "upload",
356            FileWork::Download => "download",
357        };
358        (work, device, object)
359    })
360}
361
362fn stored_slot_key<P: PendingValue>(record: &P) -> Option<Vec<u8>> {
363    Some(slot_key(record.slot()?, record.ends_when_covered()))
364}
365
366/// An applied reset clears data-related observations permanently (§19.4).
367pub(crate) fn reset(db: &StoreSql) -> Result<(), DbError> {
368    pending_change(db, || {
369        db.execute("DELETE FROM _coven_pending AS p WHERE NOT EXISTS(SELECT 1 FROM _coven_provider_access a WHERE a.operation=p.operation)",[])?;
370        Ok(())
371    })
372}
373
374/// Kept progress removes only this installation's condition, in its transaction.
375pub(crate) fn clear_slot(db: &StoreSql, slot: coven_merge::Slot) -> Result<(), DbError> {
376    pending_change(db, || {
377        for covered in [false, true] {
378            db.execute("DELETE FROM _coven_pending WHERE slot_key=?1", [slot_key(slot, covered)])?;
379        }
380        Ok(())
381    })
382}
383
384/// Snapshot coverage that passes a waiting write ends that
385/// wait in the same transaction. Verdicts on a write's bytes remain (§19.1).
386pub(crate) fn clear_covered_slots(db: &StoreSql) -> Result<(), DbError> {
387    let waiting = db.query(
388        "SELECT slot_key FROM _coven_pending WHERE slot_key>=?1 AND slot_key<?2",
389        ([COVERED_SLOT].as_slice(), [COVERED_SLOT + 1].as_slice()),
390        |row| row.get::<_, Vec<u8>>(0),
391    )?;
392    if waiting.is_empty() {
393        return Ok(());
394    }
395    let applied = crate::sequence::applied(db)?;
396    pending_change(db, || {
397        for key in waiting {
398            let slot = u64::from_be_bytes(key[1..].try_into().expect("eight-byte slot"));
399            if slot <= applied {
400                db.execute("DELETE FROM _coven_pending WHERE slot_key=?1", [key])?;
401            }
402        }
403        Ok(())
404    })
405}
406
407pub(crate) fn pending_change<T>(
408    sql: &StoreSql,
409    run: impl FnOnce() -> Result<T, DbError>,
410) -> Result<T, DbError> {
411    run().map_err(|error| pending_failure(sql, error))
412}
413
414/// A transaction on `sql` that saves pending state: a failure fails the
415/// handle, so every later call reports it.
416pub(crate) fn state_transaction<T>(
417    sql: &mut StoreSql,
418    run: impl FnOnce(&StoreSql) -> Result<T, DbError>,
419) -> Result<T, DbError> {
420    let result = sql.transaction(run);
421    result.map_err(|error| pending_failure(sql, error))
422}
423
424/// Fail the handle `sql` serves when saving pending state failed, so every
425/// later call reports it.
426fn pending_failure(sql: &StoreSql, error: DbError) -> DbError {
427    if matches!(error, DbError::StatePersistence(_)) {
428        return error;
429    }
430    let error = Arc::new(error);
431    sql.fail_handle(crate::store_failure::StoreFailure::State(error.clone()));
432    DbError::StatePersistence(error)
433}
434
435#[cfg(test)]
436#[path = "pending_tests.rs"]
437pub(crate) mod tests;