Skip to main content

coven_database/
retry.rs

1//! Durable retry deadlines (§6.7).
2//!
3//! Before an automatic retry waits, its owner persists the not-before
4//! wall-clock deadline `T` and the full wait `W` with the work: one row per
5//! operation, queued upload, pin coven keeps, the joiner's approval poll, or
6//! the provider cooldown. A running session enforces the wait monotonically;
7//! reopening arms `max(0, min(T - now, W))` from these rows. An operation's,
8//! upload's or pin's row is deleted with that work, an operation's also when
9//! its pending condition clears (it advanced, or the app retried it). The
10//! app's own reads and pins keep none: only its next call tries again
11//! (§17.7).
12
13use crate::sqlite::StoreSql;
14use crate::{DbError, OperationId};
15use std::time::{Duration, SystemTime};
16
17/// The work a persisted wait delays.
18#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
19pub enum RetrySubject {
20    /// A journal operation.
21    Operation(OperationId),
22    /// A queued file upload, by its queue id, which is never another
23    /// upload's.
24    Upload(i64),
25    /// A file a switch to the cloud asked this device to keep, which coven
26    /// downloads whole itself (§17.8), by its request's id: a later request
27    /// for the same file is another subject.
28    Pin(i64),
29    /// The joining device's polling for its request's outcome (§13.2).
30    Join,
31    /// A failed sequence pass.
32    Sync,
33    /// The provider/account cooldown a `Retry-After` requested; every
34    /// consumer of the store's connection waits for it.
35    Provider,
36}
37
38/// A persisted wait: `T` and `W`, and the consecutive unsuccessful attempts
39/// that chose `W`, so reopening does not reset the backoff exponent.
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub struct RetryWait {
42    /// Consecutive unsuccessful attempts; zero for a provider cooldown.
43    pub failures: u32,
44    /// `T`: the wall-clock time before which no automatic attempt starts.
45    pub not_before: SystemTime,
46    /// `W`: the full wait chosen when `T` was persisted.
47    pub wait: Duration,
48}
49impl RetryWait {
50    /// A wait as a retry column set stores it: failures, `T` and `W` in
51    /// milliseconds.
52    pub(crate) fn stored(failures: i64, not_before: &[u8], wait: i64) -> Result<Self, DbError> {
53        Ok(Self {
54            failures: u32::try_from(failures).map_err(|_overflow| DbError::DamagedDatabase)?,
55            not_before: crate::user_file::decode_time(not_before)?,
56            wait: crate::stored_millis::stored_wait(wait)?,
57        })
58    }
59}
60
61/// The row's one subject column and its value.
62enum Key {
63    Scope(&'static str),
64    Operation(i64),
65    Upload(i64),
66    Pin(i64),
67}
68
69fn key(subject: RetrySubject) -> Key {
70    match subject {
71        RetrySubject::Operation(id) => Key::Operation(id.0),
72        RetrySubject::Upload(id) => Key::Upload(id),
73        RetrySubject::Pin(id) => Key::Pin(id),
74        RetrySubject::Join => Key::Scope("join"),
75        RetrySubject::Sync => Key::Scope("sync"),
76        RetrySubject::Provider => Key::Scope("provider"),
77    }
78}
79
80/// The statements on `_coven_retries` for one subject column: read its
81/// row, insert one, end its wait and delete it, each with the subject as
82/// `?1`.
83struct KeyStatements {
84    find: &'static str,
85    insert: &'static str,
86    end: &'static str,
87    delete: &'static str,
88}
89
90const SCOPE: KeyStatements = KeyStatements {
91    find: "SELECT scope,operation,upload,pin,failures,not_before,wait FROM _coven_retries WHERE scope=?1",
92    insert: "INSERT INTO _coven_retries(scope,failures,not_before,wait) VALUES(?1,?2,?3,?4)",
93    end: "UPDATE _coven_retries SET not_before=?2,wait=0 WHERE scope=?1",
94    delete: "DELETE FROM _coven_retries WHERE scope=?1",
95};
96
97const OPERATION: KeyStatements = KeyStatements {
98    find: "SELECT scope,operation,upload,pin,failures,not_before,wait FROM _coven_retries WHERE operation=?1",
99    insert: "INSERT INTO _coven_retries(operation,failures,not_before,wait) VALUES(?1,?2,?3,?4)",
100    end: "UPDATE _coven_retries SET not_before=?2,wait=0 WHERE operation=?1",
101    delete: "DELETE FROM _coven_retries WHERE operation=?1",
102};
103
104const UPLOAD: KeyStatements = KeyStatements {
105    find: "SELECT scope,operation,upload,pin,failures,not_before,wait FROM _coven_retries WHERE upload=?1",
106    insert: "INSERT INTO _coven_retries(upload,failures,not_before,wait) VALUES(?1,?2,?3,?4)",
107    end: "UPDATE _coven_retries SET not_before=?2,wait=0 WHERE upload=?1",
108    delete: "DELETE FROM _coven_retries WHERE upload=?1",
109};
110
111const PIN: KeyStatements = KeyStatements {
112    find: "SELECT scope,operation,upload,pin,failures,not_before,wait FROM _coven_retries WHERE pin=?1",
113    insert: "INSERT INTO _coven_retries(pin,failures,not_before,wait) VALUES(?1,?2,?3,?4)",
114    end: "UPDATE _coven_retries SET not_before=?2,wait=0 WHERE pin=?1",
115    delete: "DELETE FROM _coven_retries WHERE pin=?1",
116};
117
118impl Key {
119    fn value(&self) -> sqlive::rusqlite::types::Value {
120        match self {
121            Self::Scope(scope) => sqlive::rusqlite::types::Value::Text((*scope).into()),
122            Self::Operation(id) | Self::Upload(id) | Self::Pin(id) => {
123                sqlive::rusqlite::types::Value::Integer(*id)
124            }
125        }
126    }
127
128    fn statements(&self) -> KeyStatements {
129        match self {
130            Self::Scope(_) => SCOPE,
131            Self::Operation(_) => OPERATION,
132            Self::Upload(_) => UPLOAD,
133            Self::Pin(_) => PIN,
134        }
135    }
136}
137
138fn read_row(row: &sqlive::rusqlite::Row<'_>) -> sqlive::rusqlite::Result<RawRow> {
139    Ok(RawRow {
140        scope: row.get(0)?,
141        operation: row.get(1)?,
142        upload: row.get(2)?,
143        pin: row.get(3)?,
144        failures: row.get(4)?,
145        not_before: row.get(5)?,
146        wait: row.get(6)?,
147    })
148}
149
150struct RawRow {
151    scope: Option<String>,
152    operation: Option<i64>,
153    upload: Option<i64>,
154    pin: Option<i64>,
155    failures: i64,
156    not_before: Vec<u8>,
157    wait: i64,
158}
159
160impl RawRow {
161    fn decode(self) -> Result<(RetrySubject, RetryWait), DbError> {
162        let subject = match (self.scope.as_deref(), self.operation, self.upload, self.pin) {
163            (None, Some(id), None, None) => RetrySubject::Operation(OperationId(id)),
164            (None, None, Some(id), None) => RetrySubject::Upload(id),
165            (None, None, None, Some(id)) => RetrySubject::Pin(id),
166            (Some("join"), None, None, None) => RetrySubject::Join,
167            (Some("sync"), None, None, None) => RetrySubject::Sync,
168            (Some("provider"), None, None, None) => RetrySubject::Provider,
169            _ => return Err(DbError::DamagedDatabase),
170        };
171        Ok((subject, RetryWait::stored(self.failures, &self.not_before, self.wait)?))
172    }
173}
174
175pub(crate) fn read_all(db: &StoreSql) -> Result<Vec<(RetrySubject, RetryWait)>, DbError> {
176    db.query(
177        "SELECT scope,operation,upload,pin,failures,not_before,wait FROM _coven_retries",
178        [],
179        read_row,
180    )?
181    .into_iter()
182    .map(RawRow::decode)
183    .collect()
184}
185
186pub(crate) fn find(db: &StoreSql, subject: RetrySubject) -> Result<Option<RetryWait>, DbError> {
187    let key = key(subject);
188    db.query(key.statements().find, [key.value()], read_row)?
189        .pop()
190        .map(|row| row.decode().map(|(_, wait)| wait))
191        .transpose()
192}
193
194/// `W` is stored in whole milliseconds, rounded up so a persisted wait never
195/// shortens the one the session armed.
196fn millis(wait: &RetryWait) -> Result<i64, DbError> {
197    crate::stored_millis::millis(wait.wait, crate::stored_millis::Round::Up)
198        .ok_or(DbError::Invariant { what: "a retry wait fits SQLite's integer" })
199}
200
201/// Replace the subject's wait.
202pub(crate) fn save(db: &StoreSql, subject: RetrySubject, wait: &RetryWait) -> Result<(), DbError> {
203    clear(db, subject)?;
204    let key = key(subject);
205    db.execute(
206        key.statements().insert,
207        sqlive::rusqlite::params![
208            key.value(),
209            i64::from(wait.failures),
210            crate::user_file::encode_time(wait.not_before),
211            millis(wait)?,
212        ],
213    )?;
214    Ok(())
215}
216
217/// Record a failed attempt's pending `record` with the subject's next wait,
218/// or with none, in the caller's transaction.
219pub(crate) fn save_failure<P: crate::PendingValue>(
220    db: &StoreSql,
221    record: &P,
222    subject: RetrySubject,
223    wait: Option<&RetryWait>,
224) -> Result<(), DbError> {
225    crate::pending::save(db, record)?;
226    set(db, subject, wait)
227}
228
229/// Replace the subject's wait, or end it when there is none.
230pub(crate) fn set(
231    db: &StoreSql,
232    subject: RetrySubject,
233    wait: Option<&RetryWait>,
234) -> Result<(), DbError> {
235    match wait {
236        Some(wait) => save(db, subject, wait),
237        None => clear(db, subject),
238    }
239}
240
241/// End the subject's wait at `now` in place: `T = now`, `W = 0`, keeping its
242/// failure count.
243pub(crate) fn end(db: &StoreSql, subject: RetrySubject, now: SystemTime) -> Result<(), DbError> {
244    let key = key(subject);
245    db.execute(
246        key.statements().end,
247        sqlive::rusqlite::params![key.value(), crate::user_file::encode_time(now)],
248    )?;
249    Ok(())
250}
251
252pub(crate) fn clear(db: &StoreSql, subject: RetrySubject) -> Result<(), DbError> {
253    let key = key(subject);
254    db.execute(key.statements().delete, [key.value()])?;
255    Ok(())
256}
257
258#[cfg(test)]
259#[path = "retry_tests.rs"]
260pub(crate) mod tests;