Skip to main content

coven_sync/
error.rs

1//! Failures of sequence publication, file uploads and sync steps (E5, E7).
2
3use crate::OperationRejection;
4use coven_crypto::{custody::KeyError, CryptoError, MaterialError};
5use coven_database::DbError;
6use coven_foundation::files::{FileError, ObservationError, StoreLockError};
7use coven_foundation::id_source::KeyId;
8use coven_merge::Audience;
9use coven_storage::{StorageError, StorageFailure};
10use std::sync::Arc;
11
12/// Why `confirm_device_cut_off` refused (§14.2, §20.9). Each is a reason the
13/// call can't change anything; the app tells the person which one.
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub enum CutOffRefusal {
16    /// The applied history doesn't have the device gone for good: its
17    /// removal hasn't reached this device yet, or it was never removed.
18    /// After the next pass has read the removal the call can succeed.
19    DeviceNotGone,
20    /// The member whose device this is doesn't hold the store: another
21    /// member's account does, and only their devices change sharing. The
22    /// call can't succeed here.
23    NotStoreOwner,
24    /// The store is on S3, where no account is shared, so there is nothing to
25    /// take back. The call can't succeed.
26    NoAccountShared,
27}
28
29/// A synchronization request failed; its durable queue, if any, remains retryable.
30#[derive(Debug, thiserror::Error)]
31pub enum SyncError {
32    /// This call requires work that cannot yet advance.
33    #[error("pending: {0:?}")]
34    Pending(Box<crate::PendingRecord>),
35    /// A local invariant or resource failed, classified without erasing its
36    /// native cause. One failure delivered to several callers shares one cause.
37    #[error("{failure:?}: {source}")]
38    Failed {
39        /// Durable local category.
40        failure: crate::LocalFailure,
41        /// Original failure retained by the initiating call.
42        #[source]
43        source: Arc<dyn std::error::Error + Send + Sync>,
44    },
45    /// A later step, such as a rollback or closing another owner, failed
46    /// too; neither failure is hidden.
47    #[error("{operation}; then: {cleanup}")]
48    Cleanup {
49        /// The original failure.
50        operation: Box<SyncError>,
51        /// The later failure, such as restoring the original state.
52        #[source]
53        cleanup: Box<SyncError>,
54    },
55    /// This call requires connected storage; durable work remains queued.
56    #[error("storage is not connected")]
57    NoStorage,
58    /// The member whose account holds the store can't be removed, and their
59    /// access can't move to another account (§10.1): OneDrive and CloudKit
60    /// can't hand a store to another account, and coven doesn't use Dropbox's
61    /// ownership transfer (bae-fm/coven#237).
62    #[error("the store owner cannot be removed or leave the account that holds the store")]
63    StoreOwner,
64    /// The request or invitation is absent, expired, or no longer matches.
65    #[error("invitation or join request is no longer current")]
66    InvitationChanged,
67    /// The requested journal row is not failed app work available for retry or discard.
68    #[error("operation {0:?} is not pending")]
69    NotPending(crate::OperationId),
70    /// Administrative and snapshot publication wait for the retained reload (§11).
71    #[error("snapshot reload {0:?} must finish before publishing entries or snapshots")]
72    ReloadPending(crate::OperationId),
73    /// Deleting stored files waits for this unfinished snapshot, whose
74    /// journal still owns references no row holds (§17.10).
75    #[error("snapshot {0:?} must finish before stored files are deleted")]
76    SnapshotPending(crate::OperationId),
77    /// Decoding persisted operation data failed; its cause remains available.
78    #[error("invalid operation data: {0}")]
79    OperationData(#[from] serde_json::Error),
80    /// The sequence has no next slot: slot numbers are `u64`s, and the
81    /// slot it would follow is the last one.
82    #[error("the store sequence is exhausted")]
83    SequenceExhausted,
84    /// Storage refused or failed a request.
85    #[error(transparent)]
86    Storage(StorageError),
87    /// The local database failed.
88    #[error(transparent)]
89    Database(DbError),
90    /// Unlocking or keeping keys failed.
91    #[error(transparent)]
92    SecureStorage(KeyError),
93    /// Making encrypted or signed bytes failed.
94    #[error(transparent)]
95    Crypto(CryptoError),
96    /// The proposed entry violates its byte format.
97    #[error(transparent)]
98    Format(coven_format::Error),
99    /// A required key has not arrived or the local key material conflicts.
100    #[error(transparent)]
101    Key(#[from] MaterialError),
102    /// A required key's sealed copy has not arrived.
103    #[error("key {key} is not available yet")]
104    KeyUnavailable {
105        /// The audience the key belongs to.
106        audience: Audience,
107        /// The missing key.
108        key: KeyId,
109    },
110    /// The proposed change is already invalid in the author's applied view.
111    #[error("administrative change rejected: {0:?}")]
112    Rejected(OperationRejection),
113    /// `confirm_device_cut_off` changed nothing, for this reason.
114    #[error("the device cut-off was refused: {0:?}")]
115    CutOffRefused(CutOffRefusal),
116    /// A required object failed authentication or parsing.
117    #[error(transparent)]
118    Damaged(#[from] crate::DamagedObject),
119    /// This device is not in the store, and won't be again: it or its member
120    /// was removed, or a joined store read to the end of the sequence with its
121    /// pair bound nowhere in its history, which means the admission that
122    /// published it was refused. Syncing stops for good (§13.2, §14.1).
123    #[error("this device is not in the store: {0:?}")]
124    Removed(coven_database::Removal),
125    /// Another copy uses this device's id, as this evidence shows. This copy
126    /// sends nothing more; nothing is recorded, and `reset_device` is the
127    /// app's option (§19.3).
128    #[error("another copy uses this device's id: {0:?}")]
129    DeviceIdInUse(crate::DeviceIdEvidence),
130    /// Held signing credentials are no longer current for this stable id, or
131    /// an object was fixed under credentials that are no longer current.
132    /// Sending stops; it never re-signs an old object with newer keys (§14.1).
133    #[error("member {member:?} has newer keys; held credentials cannot send")]
134    MemberKeysReplaced {
135        /// The stable member whose keys were replaced.
136        member: coven_foundation::id_source::MemberId,
137    },
138    /// This call needs a newer app schema or coven format (§18).
139    #[error("an update is required: {0:?}")]
140    UpdateRequired(crate::RequiredUpdate),
141    /// A code can't be used for this call, as one naming another store.
142    #[error(transparent)]
143    Code(#[from] crate::CodeError),
144    /// The call's runtime is shutting down and dropped its work (E15). A
145    /// database call the blocking pool dropped unstarted changed nothing; a
146    /// call that runs as its own task, as closing and replacing credentials
147    /// do, may have stopped partway.
148    #[error(transparent)]
149    Shutdown(#[from] coven_foundation::task::Shutdown),
150    /// The call's work panicked: a bug in coven, which the caller reports
151    /// (E15). Its category is `LocalFailure::Bug`.
152    #[error(transparent)]
153    Bug(#[from] coven_foundation::task::Bug),
154    /// The worker this call needs ended on a panic: the sync loop, a
155    /// connection attempt or the upload worker. The store's bug sink heard
156    /// the bug as it happened, so the app shows this and doesn't report it
157    /// again (E15). Its category is `LocalFailure::Bug`.
158    #[error("{0}; it has stopped")]
159    WorkerFailed(coven_foundation::task::Bug),
160}
161
162impl From<CutOffRefusal> for SyncError {
163    fn from(refusal: CutOffRefusal) -> Self {
164        Self::CutOffRefused(refusal)
165    }
166}
167
168impl coven_foundation::task::CarriesBug for SyncError {
169    fn bug(&self) -> Option<&coven_foundation::task::Bug> {
170        match self {
171            Self::Bug(bug) => Some(bug),
172            // An earlier bug, which the sink heard as it happened.
173            Self::WorkerFailed(_) => None,
174            Self::Database(error) => error.bug(),
175            Self::SecureStorage(error) => error.bug(),
176            Self::Storage(error) => error.bug(),
177            Self::Cleanup { operation, cleanup } => operation.bug().or_else(|| cleanup.bug()),
178            // The cause `into_shared` shares is the error itself.
179            Self::Failed { source, .. } => {
180                source.downcast_ref::<Self>().and_then(coven_foundation::task::CarriesBug::bug)
181            }
182            _ => None,
183        }
184    }
185}
186
187impl From<coven_foundation::task::TaskFailed> for SyncError {
188    fn from(failed: coven_foundation::task::TaskFailed) -> Self {
189        failed.into_error()
190    }
191}
192
193impl From<coven_database::SqliteError> for SyncError {
194    fn from(error: coven_database::SqliteError) -> Self {
195        DbError::from(error).into()
196    }
197}
198
199/// Sync's own writes keep their error: a database failure as itself, and
200/// any other with a failed rollback or byte removal as a later step that
201/// failed too (§4, Appendix C.3).
202impl coven_database::WriteFailure for SyncError {
203    fn with_rollback(self, rollback: coven_database::SqliteError) -> Self {
204        match self {
205            Self::Database(error) => Self::Database(error.with_rollback(rollback)),
206            error => Self::cleanup(error, rollback.into()),
207        }
208    }
209
210    fn with_cleanup(write: Self, failures: Vec<DbError>) -> Self {
211        match write {
212            Self::Database(error) => Self::Database(DbError::with_cleanup(error, failures)),
213            error => failures
214                .into_iter()
215                .fold(error, |error, failure| Self::cleanup(error, failure.into())),
216        }
217    }
218}
219
220impl From<DbError> for SyncError {
221    fn from(error: DbError) -> Self {
222        match error {
223            // The database refusing sync's own requests against changed state
224            // is not a database failure an app can act on.
225            error @ DbError::OperationChanged(_) => {
226                Self::Failed { failure: crate::LocalFailure::Database, source: Arc::new(error) }
227            }
228            // Coven broke its own rule: a bug, as a panic is.
229            error @ DbError::Invariant { .. } => {
230                Self::Failed { failure: crate::LocalFailure::Bug, source: Arc::new(error) }
231            }
232            // The process is ending the call; the database did not fail.
233            DbError::Shutdown(shutdown) => Self::Shutdown(shutdown),
234            DbError::Bug(bug) => Self::Bug(bug),
235            DbError::StagingCleanup { operation, cleanup } => {
236                Self::cleanup((*operation).into(), (*cleanup).into())
237            }
238            error => Self::Database(error),
239        }
240    }
241}
242
243impl SyncError {
244    /// `operation` failed, and a later step (a rollback, closing another
245    /// owner) failed too; neither failure is hidden.
246    pub fn cleanup(operation: SyncError, cleanup: SyncError) -> Self {
247        Self::Cleanup { operation: Box::new(operation), cleanup: Box::new(cleanup) }
248    }
249
250    /// The durable reason for a failed request, without losing its typed cause here.
251    /// Every variant is matched by name, so a new one is classified here.
252    #[deny(clippy::wildcard_enum_match_arm)]
253    pub fn pending_reason(&self, provider: coven_storage::CloudProvider) -> crate::PendingReason {
254        use crate::PendingReason;
255        let error = self;
256        match error {
257            SyncError::Pending(record) => record.reason.clone(),
258            SyncError::Storage(error) => PendingReason::Storage {
259                provider,
260                failure: error.failure(),
261                answered: error.answered(),
262            },
263            SyncError::Damaged(object) => PendingReason::Refused(object.failure.clone()),
264            SyncError::UpdateRequired(update) => PendingReason::UpdateRequired(*update),
265            SyncError::Removed(removal) => PendingReason::Removed(*removal),
266            SyncError::MemberKeysReplaced { member } => {
267                PendingReason::MemberKeysReplaced { member: *member }
268            }
269            SyncError::KeyUnavailable { audience, key } => PendingReason::KeyUnavailable {
270                audience: audience.clone(),
271                key: *key,
272                holders: None,
273            },
274            SyncError::Rejected(reason) => PendingReason::Rejected(reason.clone()),
275            SyncError::Cleanup { operation, cleanup } => PendingReason::Cleanup {
276                operation: Box::new(operation.pending_reason(provider)),
277                cleanup: Box::new(cleanup.pending_reason(provider)),
278            },
279            SyncError::Failed { .. }
280            | SyncError::NoStorage
281            | SyncError::StoreOwner
282            | SyncError::InvitationChanged
283            | SyncError::CutOffRefused(_)
284            | SyncError::NotPending(_)
285            | SyncError::ReloadPending(_)
286            | SyncError::SnapshotPending(_)
287            | SyncError::OperationData(_)
288            | SyncError::SequenceExhausted
289            | SyncError::Database(_)
290            | SyncError::SecureStorage(_)
291            | SyncError::Crypto(_)
292            | SyncError::Format(_)
293            | SyncError::Key(_)
294            | SyncError::DeviceIdInUse(_)
295            | SyncError::Code(_)
296            | SyncError::Shutdown(_)
297            | SyncError::Bug(_)
298            | SyncError::WorkerFailed(_) => PendingReason::Failed(error.local_failure()),
299        }
300    }
301
302    /// A local file, directory or store-lock failure, retaining its cause.
303    pub(crate) fn disk(error: impl std::error::Error + Send + Sync + 'static) -> Self {
304        Self::Failed { failure: crate::LocalFailure::of_disk(&error), source: Arc::new(error) }
305    }
306
307    /// The local category recorded for a failure that names no other condition.
308    #[deny(clippy::wildcard_enum_match_arm)]
309    pub(crate) fn local_failure(&self) -> crate::LocalFailure {
310        match self {
311            Self::Failed { failure, .. } => *failure,
312            Self::Database(_) => crate::LocalFailure::Database,
313            Self::SecureStorage(_) => crate::LocalFailure::KeyCustody,
314            Self::Crypto(_) | Self::Key(_) => crate::LocalFailure::Crypto,
315            Self::Cleanup { operation, .. } => operation.local_failure(),
316            Self::Pending(_)
317            | Self::NoStorage
318            | Self::StoreOwner
319            | Self::InvitationChanged
320            | Self::NotPending(_)
321            | Self::ReloadPending(_)
322            | Self::SnapshotPending(_)
323            | Self::OperationData(_)
324            | Self::SequenceExhausted
325            | Self::Storage(_)
326            | Self::Format(_)
327            | Self::KeyUnavailable { .. }
328            | Self::Rejected(_)
329            | Self::CutOffRefused(_)
330            | Self::Damaged(_)
331            | Self::Removed(_)
332            | Self::DeviceIdInUse(_)
333            | Self::MemberKeysReplaced { .. }
334            | Self::UpdateRequired(_)
335            | Self::Code(_) => crate::LocalFailure::Operation,
336            Self::Shutdown(_) => crate::LocalFailure::Shutdown,
337            Self::Bug(_) | Self::WorkerFailed(_) => crate::LocalFailure::Bug,
338        }
339    }
340
341    /// A local database, disk or custody failure that can clear by itself,
342    /// such as a locked keychain or a failed disk write (E5), or the runtime
343    /// shutting down, which the next process clears (E15). It fails only
344    /// this attempt and says nothing about the slot being applied (§19.1).
345    pub(crate) fn local_failure_clears_by_itself(&self) -> bool {
346        matches!(
347            self,
348            Self::Database(_)
349                | Self::SecureStorage(_)
350                | Self::Failed { .. }
351                | Self::Shutdown(_)
352                | Self::Bug(_)
353                | Self::WorkerFailed(_)
354        ) && crate::PendingReason::Failed(self.local_failure()).clears()
355            == Some(crate::pending::Clears::ByItself)
356    }
357
358    /// The error a pending record keeps as its cause, the one `into_shared`
359    /// shares: a local failure's source, any other error itself.
360    pub(crate) fn cause(&self) -> &(dyn std::error::Error + 'static) {
361        match self {
362            Self::Failed { source, .. } => source.as_ref(),
363            error => error,
364        }
365    }
366
367    /// The local category and one shared cause, for a status and a waiting
368    /// caller failed by the same error.
369    pub fn into_shared(self) -> (crate::LocalFailure, Arc<dyn std::error::Error + Send + Sync>) {
370        match self {
371            Self::Failed { failure, source } => (failure, source),
372            error => (error.local_failure(), Arc::new(error)),
373        }
374    }
375}
376
377impl From<StorageError> for SyncError {
378    fn from(error: StorageError) -> Self {
379        match error {
380            StorageError::Bug(bug) => Self::Bug(bug),
381            error => Self::Storage(error),
382        }
383    }
384}
385
386impl From<KeyError> for SyncError {
387    fn from(error: KeyError) -> Self {
388        match error {
389            KeyError::Bug(bug) => Self::Bug(bug),
390            error => Self::SecureStorage(error),
391        }
392    }
393}
394
395impl From<FileError> for SyncError {
396    fn from(error: FileError) -> Self {
397        match error {
398            FileError::Bug(bug) => Self::Bug(bug),
399            error => Self::disk(error),
400        }
401    }
402}
403
404impl From<ObservationError> for SyncError {
405    fn from(error: ObservationError) -> Self {
406        Self::disk(error)
407    }
408}
409
410impl From<coven_foundation::files::WriterError> for SyncError {
411    fn from(error: coven_foundation::files::WriterError) -> Self {
412        match error {
413            coven_foundation::files::WriterError::Lock(error) => error.into(),
414            coven_foundation::files::WriterError::File(error) => error.into(),
415        }
416    }
417}
418
419impl From<StoreLockError> for SyncError {
420    fn from(error: StoreLockError) -> Self {
421        match error {
422            StoreLockError::Bug(bug) => Self::Bug(bug),
423            error => Self::disk(error),
424        }
425    }
426}
427
428/// A sync step stopped as a whole (E5).
429#[derive(Clone, Debug, thiserror::Error)]
430pub enum SyncFailure {
431    /// A schema or stored object format is newer than this implementation.
432    #[error("an update is required")]
433    UpdateRequired(crate::RequiredUpdate),
434    /// This device is not in the store (§13.2, §14.1).
435    #[error("this device is not in the store: {0:?}")]
436    Removed(coven_database::Removal),
437    /// Another copy uses this device's id; this copy sends nothing more (§19.3).
438    #[error("another copy uses this device's id: {0:?}")]
439    DeviceIdInUse(crate::DeviceIdEvidence),
440    /// The provider refused or failed a request.
441    #[error("storage failed: {0}")]
442    Storage(#[source] Arc<StorageError>),
443    /// The pass finished, but this work of coven's own failed its last
444    /// attempt; it retries under backoff (E5). The record carries the cause
445    /// it keeps, and the text names it.
446    #[error("coven's own work failed its last attempt: {0}")]
447    Operation(Box<crate::PendingRecord>),
448    /// Any other failure, retaining its typed cause.
449    #[error("sync failed: {0}")]
450    Other(#[source] Arc<dyn std::error::Error + Send + Sync>),
451}
452
453impl From<OperationRejection> for SyncError {
454    fn from(reason: OperationRejection) -> Self {
455        match reason {
456            OperationRejection::StoreOwner => Self::StoreOwner,
457            reason => Self::Rejected(reason),
458        }
459    }
460}
461
462impl From<StorageFailure> for SyncError {
463    fn from(failure: StorageFailure) -> Self {
464        Self::Storage(failure.into())
465    }
466}
467
468impl From<SyncError> for SyncFailure {
469    fn from(error: SyncError) -> Self {
470        match error {
471            SyncError::Removed(removal) => Self::Removed(removal),
472            SyncError::DeviceIdInUse(evidence) => Self::DeviceIdInUse(evidence),
473            SyncError::UpdateRequired(update) => Self::UpdateRequired(update),
474            SyncError::Storage(error) => Self::Storage(Arc::new(error)),
475            error => Self::Other(Arc::new(error)),
476        }
477    }
478}
479
480impl From<coven_format::Error> for SyncError {
481    fn from(error: coven_format::Error) -> Self {
482        match required_format(&error) {
483            Some(update) => Self::UpdateRequired(update),
484            None => Self::Format(error),
485        }
486    }
487}
488
489impl From<CryptoError> for SyncError {
490    fn from(error: CryptoError) -> Self {
491        Self::Crypto(error)
492    }
493}
494
495/// An object whose checks failed (§19.1).
496#[derive(Clone, Debug, thiserror::Error)]
497#[error("damaged object at {path}: {failure}")]
498pub struct DamagedObject {
499    /// The exact path read from storage.
500    pub path: String,
501    /// The failed check and its cause.
502    #[source]
503    pub failure: crate::Refusal,
504}
505
506pub(crate) fn required_format(
507    error: &(dyn std::error::Error + 'static),
508) -> Option<crate::RequiredUpdate> {
509    let version = match error.downcast_ref::<coven_format::Error>() {
510        Some(coven_format::Error::UnsupportedVersion(version)) => Some(*version),
511        _ => None,
512    }?;
513    (version > coven_format::FORMAT_VERSION)
514        .then_some(crate::RequiredUpdate::CovenFormat { version })
515}
516
517/// Older unsupported formats are damaged inputs; only newer ones require an update.
518pub(crate) fn newer_format(error: &(dyn std::error::Error + 'static)) -> bool {
519    required_format(error).is_some()
520}
521
522#[cfg(test)]
523#[path = "error_tests.rs"]
524mod tests;