Skip to main content

datum_persistence/
error.rs

1use thiserror::Error;
2
3use crate::{PersistenceId, Revision, SerializerId};
4
5/// Result type used by `datum-persistence`.
6pub type PersistenceResult<T> = Result<T, PersistenceError>;
7
8/// Errors produced by persistence operations.
9#[derive(Debug, Clone, Error)]
10#[non_exhaustive]
11pub enum PersistenceError {
12    /// A persistence id violates the identity format contract.
13    #[error("invalid persistence id: {0}")]
14    InvalidPersistenceId(String),
15
16    /// An atomic journal write violates its construction invariants.
17    #[error("invalid atomic journal write: {0}")]
18    InvalidAtomicWrite(String),
19
20    /// A deterministic request was rejected before storage.
21    #[error("persistence operation rejected: {0}")]
22    Rejected(String),
23
24    /// A persistence operation failed or its outcome is uncertain.
25    #[error("persistence operation failed: {0}")]
26    Failure(String),
27
28    /// A value could not be serialized or deserialized.
29    #[error("persistence serialization failed: {0}")]
30    Serialization(String),
31
32    /// No serializer is registered for a durable serializer id.
33    #[error("unknown persistence serializer id {0}")]
34    UnknownSerializer(SerializerId),
35
36    /// More than one serializer was registered with the same durable id.
37    #[error("duplicate persistence serializer id {0}")]
38    DuplicateSerializer(SerializerId),
39
40    /// A storage connection could not be established or was lost.
41    #[error("persistence connection failed: {0}")]
42    Connection(String),
43
44    /// A durable-state compare-and-set revision did not match.
45    #[error(
46        "durable-state revision conflict for {persistence_id}: expected {expected}, got {actual}"
47    )]
48    RevisionConflict {
49        /// Durable-state identity whose revision did not match.
50        persistence_id: PersistenceId,
51        /// Next revision required by the stored value or tombstone.
52        expected: Revision,
53        /// Revision supplied by the caller.
54        actual: Revision,
55    },
56
57    /// A durable-state revision cannot advance beyond its numeric range.
58    #[error("durable-state revision exhausted for {persistence_id}")]
59    RevisionExhausted {
60        /// Durable-state identity whose revision reached the maximum value.
61        persistence_id: PersistenceId,
62    },
63}
64
65/// Result of one input [`crate::AtomicWrite`] in a journal append batch.
66///
67/// Rejection is a deterministic value. An [`Err`](Result::Err) from
68/// [`crate::Journal::append`] instead means storage failed or the commit result
69/// is uncertain.
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub enum AppendOutcome {
72    /// The complete atomic write was stored.
73    Accepted,
74    /// The complete atomic write was refused before storage.
75    Rejected {
76        /// Backend-provided deterministic rejection explanation.
77        reason: String,
78    },
79}