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}