txn_db/error.rs
1//! The crate error type.
2//!
3//! Every fallible operation in `txn-db` returns [`Result<T>`], whose error is
4//! [`TxnError`]. The type integrates with the portfolio's `error-forge`
5//! framework — it implements [`error_forge::ForgeError`], so callers get the
6//! stable `kind` / `is_fatal` metadata other crates rely on.
7//!
8//! The error a caller meets most often is [`TxnError::Conflict`]: under
9//! snapshot isolation, two transactions that wrote the same key race at commit
10//! time, and the later committer is aborted. That outcome is *expected* and
11//! *retryable* — the contract is that the caller re-runs the transaction
12//! against a fresher snapshot rather than treating it as a failure. The
13//! [`TxnError::is_retryable`] helper makes that decision a single call in a
14//! retry loop.
15
16use core::fmt;
17
18use error_forge::ForgeError;
19
20/// A specialised [`Result`](core::result::Result) for transaction operations.
21///
22/// Defaults its error to [`TxnError`], so most signatures read `Result<T>`.
23pub type Result<T, E = TxnError> = core::result::Result<T, E>;
24
25/// Everything that can go wrong while running a transaction.
26///
27/// The type is [`#[non_exhaustive]`](https://doc.rust-lang.org/reference/attributes/type_system.html#the-non_exhaustive-attribute):
28/// later versions may add variants without a major bump, so a `match` over it
29/// must include a wildcard arm. Each variant documents what the caller should
30/// do when they encounter it.
31#[non_exhaustive]
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub enum TxnError {
34 /// A write-write conflict aborted the transaction at commit time.
35 ///
36 /// Under snapshot isolation the database applies *first-committer-wins*:
37 /// when a transaction commits, every key it wrote is checked against the
38 /// version store, and if any of those keys was written by a different
39 /// transaction that committed *after* this one took its snapshot, this
40 /// commit is rejected. None of its writes are applied.
41 ///
42 /// This is the mechanism that prevents lost updates, and it is a normal
43 /// part of operating under optimistic concurrency control. The correct
44 /// response is to retry: begin a fresh transaction, re-read, re-apply the
45 /// logic, and commit again. [`TxnError::is_retryable`] returns `true` for
46 /// this variant.
47 ///
48 /// Only the length of the conflicting key is carried, never its bytes, so
49 /// the error is safe to log even when keys hold sensitive data.
50 Conflict {
51 /// Length in bytes of the key whose conflict aborted the commit.
52 key_len: usize,
53 },
54
55 /// The backing version store failed to service a read or apply a write.
56 ///
57 /// The in-memory store that ships with `txn-db` never produces this; it is
58 /// the channel through which a custom [`VersionStore`](crate::VersionStore)
59 /// — for example one backed by an on-disk engine — surfaces a failure
60 /// through the same [`Result`]. `context` names the operation that was
61 /// attempted (such as `"read visible version"`); `detail` carries the
62 /// store's own message. Whether to retry depends on the store, so this
63 /// variant is reported as non-fatal and left for the caller to judge.
64 Store {
65 /// The operation the store was performing when it failed.
66 context: &'static str,
67 /// The store's human-readable description of the failure.
68 detail: String,
69 },
70
71 /// The durable commit log failed, or a record read back from it was not
72 /// intact.
73 ///
74 /// Produced only with the `durability` feature: when appending or syncing a
75 /// commit record fails, or when recovery on [`Db::open`](crate::Db) reads a
76 /// record whose bytes do not decode. A commit that fails to become durable
77 /// is *not* acknowledged — the contract that an acknowledged commit survives
78 /// a crash holds — but the failure is fatal in the sense that the database's
79 /// durability guarantee is in question, so treat it as unrecoverable rather
80 /// than retrying blindly.
81 Durability {
82 /// A human-readable description of the durability failure.
83 detail: String,
84 },
85}
86
87impl TxnError {
88 /// Build a [`TxnError::Conflict`] for a key of the given length.
89 #[inline]
90 #[must_use]
91 pub(crate) fn conflict(key_len: usize) -> Self {
92 TxnError::Conflict { key_len }
93 }
94
95 /// Build a [`TxnError::Store`] from a static context and a store message.
96 ///
97 /// Intended for [`VersionStore`](crate::VersionStore) implementations that
98 /// can fail; the in-memory store never calls it.
99 #[inline]
100 #[must_use]
101 pub fn store(context: &'static str, detail: impl fmt::Display) -> Self {
102 TxnError::Store {
103 context,
104 detail: detail.to_string(),
105 }
106 }
107
108 /// Build a [`TxnError::Durability`] from a description of the failure.
109 #[cfg(feature = "durability")]
110 #[inline]
111 #[must_use]
112 pub(crate) fn durability(detail: impl fmt::Display) -> Self {
113 TxnError::Durability {
114 detail: detail.to_string(),
115 }
116 }
117
118 /// Returns `true` if re-running the transaction is the right response.
119 ///
120 /// A [`Conflict`](TxnError::Conflict) is retryable: another transaction won
121 /// the race, and a fresh attempt against the newer snapshot will typically
122 /// succeed. Backing-store failures are reported as not retryable here
123 /// because their recoverability is store-specific; inspect the variant when
124 /// a store can distinguish transient from permanent faults.
125 ///
126 /// # Examples
127 ///
128 /// ```
129 /// use txn_db::{Db, TxnError};
130 ///
131 /// let db = Db::new();
132 ///
133 /// // The common retry loop: keep trying while the commit is retryable.
134 /// let outcome = loop {
135 /// let mut tx = db.begin();
136 /// let current = tx.get(b"counter")?.map_or(0u64, |v| {
137 /// let mut buf = [0u8; 8];
138 /// buf.copy_from_slice(&v);
139 /// u64::from_le_bytes(buf)
140 /// });
141 /// tx.put(b"counter".to_vec(), (current + 1).to_le_bytes().to_vec());
142 /// match tx.commit() {
143 /// Ok(ts) => break ts,
144 /// Err(e) if e.is_retryable() => continue,
145 /// Err(e) => return Err(e),
146 /// }
147 /// };
148 /// # let _ = outcome;
149 /// # Ok::<(), TxnError>(())
150 /// ```
151 #[inline]
152 #[must_use]
153 pub fn is_retryable(&self) -> bool {
154 matches!(self, TxnError::Conflict { .. })
155 }
156}
157
158impl fmt::Display for TxnError {
159 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
160 match self {
161 TxnError::Conflict { key_len } => write!(
162 f,
163 "write-write conflict on a {key_len}-byte key; retry the transaction"
164 ),
165 TxnError::Store { context, detail } => {
166 write!(f, "version store error while {context}: {detail}")
167 }
168 TxnError::Durability { detail } => {
169 write!(f, "durable commit log error: {detail}")
170 }
171 }
172 }
173}
174
175impl core::error::Error for TxnError {}
176
177impl ForgeError for TxnError {
178 fn kind(&self) -> &'static str {
179 match self {
180 TxnError::Conflict { .. } => "Conflict",
181 TxnError::Store { .. } => "Store",
182 TxnError::Durability { .. } => "Durability",
183 }
184 }
185
186 fn caption(&self) -> &'static str {
187 "transaction error"
188 }
189
190 /// A [`Conflict`](TxnError::Conflict) is the retry signal and a
191 /// [`Store`](TxnError::Store) failure is the store's to classify, so neither
192 /// is fatal. A [`Durability`](TxnError::Durability) failure puts the crash
193 /// guarantee in doubt and is reported as fatal.
194 fn is_fatal(&self) -> bool {
195 matches!(self, TxnError::Durability { .. })
196 }
197}
198
199#[cfg(test)]
200#[allow(clippy::unwrap_used, clippy::expect_used)]
201mod tests {
202 use super::*;
203
204 #[test]
205 fn test_conflict_is_retryable() {
206 assert!(TxnError::conflict(8).is_retryable());
207 }
208
209 #[test]
210 fn test_store_error_is_not_retryable() {
211 assert!(!TxnError::store("read", "disk gone").is_retryable());
212 }
213
214 #[test]
215 fn test_conflict_display_reports_key_len_not_bytes() {
216 let msg = TxnError::conflict(16).to_string();
217 assert!(msg.contains("16-byte"));
218 assert!(msg.contains("retry"));
219 }
220
221 #[test]
222 fn test_kind_matches_variant() {
223 assert_eq!(TxnError::conflict(1).kind(), "Conflict");
224 assert_eq!(TxnError::store("x", "y").kind(), "Store");
225 }
226
227 #[test]
228 fn test_no_variant_is_fatal() {
229 assert!(!TxnError::conflict(1).is_fatal());
230 assert!(!TxnError::store("x", "y").is_fatal());
231 }
232
233 #[test]
234 fn test_error_is_clonable_and_comparable() {
235 let a = TxnError::conflict(4);
236 assert_eq!(a.clone(), a);
237 }
238}