#[non_exhaustive]pub enum AppendError<E> {
ConditionViolated(ConditionViolated),
NoEvents,
ExceedsStoreLimit {
limit: StoreLimit,
len: usize,
},
Busy(E),
Store(E),
}Expand description
Why an append failed.
The DCB concurrency signal is lifted out of the adapter’s error type and into this enum on purpose. Every store fails differently — disk full, socket closed, a lost acknowledgement — but every store fails identically when an append condition is violated, and callers must be able to distinguish “retry the decision” from “this went wrong” without pattern-matching on strings or knowing which adapter they were handed.
A busy refusal is lifted out for the same reason, into
Busy. SQLITE_BUSY after a busy timeout and a PostgreSQL
serialisation failure after an adapter’s own retry budget are different
driver errors with one meaning — nothing was written, and the same decision
may be taken again — and a generic caller that could only ask
is_condition_violated could not see that
meaning behind Store.
§Examples
match result {
Ok(()) => {}
// Expected under contention: rebuild the decision model and retry.
Err(AppendError::ConditionViolated(_)) => { /* re-decide */ }
// Transient, and nothing was written: deciding again is safe.
Err(AppendError::Busy(_)) => { /* re-decide, within your own bound */ }
// Everything else is a genuine failure.
Err(other) => panic!("append failed: {other:?}"),
}Note the catch-all arm: this enum is #[non_exhaustive], so matching every
named variant is not enough and a wildcard is required.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
ConditionViolated(ConditionViolated)
The store already contained an event matching the append condition.
NoEvents
The caller passed an empty batch.
The specification defines a batch as a non-empty collection of events, so there is no position an adapter could honestly return. This is a caller bug, not a store failure.
ExceedsStoreLimit
The batch exceeded a capacity the store documents.
Distinct from Store on purpose, and the distinction is
the whole reason the variant exists: a caller that cannot tell “this will
never fit here, park it and tell a human” from “the disk is full, retry”
has to guess, and a sync runner that guesses wrong drops an event
permanently.
A store MUST report a capacity refusal through this variant rather than
through Store, and MUST NOT truncate instead.
Fields
limit: StoreLimitWhich limit was exceeded.
Busy(E)
The store refused the append for a transient reason, before the batch took any effect.
Nothing was written, and re-running the decision is safe. That sentence is the variant’s whole contract, and an adapter reporting it promises all three parts of it:
- Before any effect. No event of the batch is in the store, and none will appear later. A position the store allocated and then abandoned may leave a gap, which the specification already permits.
- Transient. The same call can succeed once whatever held the store
has let go: a lock not acquired within the adapter’s own bound, or a
serialisation failure its own retry budget did not absorb. A refusal
that no retry can cure is
Store. - Safe to re-run. Read again, decide again, and append under the new
read’s condition, which is the loop a
ConditionViolatedalready asks for. Because nothing landed, re-submitting the same batch under the same condition is safe too: the condition still guards it.
An ambiguous outcome MUST stay Store. A commit whose
acknowledgement was lost, a connection that dropped after COMMIT was
sent, a timeout whose effect is unknown: each may have written, so none
may be reported here, however transient its cause looks. Busy is a
claim about what the store holds, not about why the driver failed. A
caller who re-runs an unconditional append on the strength of it would
otherwise append twice. A store that cannot tell is not busy.
It is not the concurrency signal:
is_condition_violated answers
false, because no condition was evaluated. Nor is it a capacity
refusal, which is ExceedsStoreLimit and will
never fit. A store is never obliged to produce it: one that serialises
its writers in-process, as MemoryEventStore does, has nothing to be
busy with.
The payload is the adapter’s own error, carried for diagnostics exactly
as Store carries it and reachable through
source. Branch on the variant, never on
the payload.
Store(E)
The adapter failed for its own reasons.
Including every outcome it cannot vouch for: an append reported here may
or may not have landed. Busy is the refusal known to have
written nothing.
Implementations§
Source§impl<E> AppendError<E>
impl<E> AppendError<E>
Sourcepub const fn is_condition_violated(&self) -> bool
pub const fn is_condition_violated(&self) -> bool
Whether this is the DCB concurrency signal rather than a store failure.
Sourcepub const fn is_busy(&self) -> bool
pub const fn is_busy(&self) -> bool
Whether the store refused transiently, before writing anything.
true only for Busy. A caller that retries on this
re-runs a decision that is known not to have landed. It is not the
question is_condition_violated asks, and
a loop that wants both asks both.
let busy: AppendError<std::io::Error> =
AppendError::Busy(std::io::Error::other("database is locked"));
assert!(busy.is_busy());
assert!(!busy.is_condition_violated());
// A store failure is neither, whatever its message says.
let broken: AppendError<std::io::Error> =
AppendError::Store(std::io::Error::other("database is locked"));
assert!(!broken.is_busy());Sourcepub fn map_store<F, T>(self, f: F) -> AppendError<T>where
F: FnOnce(E) -> T,
pub fn map_store<F, T>(self, f: F) -> AppendError<T>where
F: FnOnce(E) -> T,
Maps the adapter-specific error wherever one is carried, in
Store and in Busy, leaving every other
variant untouched.
Useful when a higher layer wraps an adapter’s error in its own type. The variant survives the mapping: a busy refusal stays busy, because the classification is the store’s claim about what it holds, and a wrapper has no standing to change it.
let busy: AppendError<&str> = AppendError::Busy("database is locked");
let wrapped: AppendError<String> = busy.map_store(str::to_owned);
assert!(wrapped.is_busy());Trait Implementations§
Source§impl<E: Clone> Clone for AppendError<E>
impl<E: Clone> Clone for AppendError<E>
Source§impl<E: Debug> Debug for AppendError<E>
impl<E: Debug> Debug for AppendError<E>
Source§impl<E> Display for AppendError<E>where
E: Display,
impl<E> Display for AppendError<E>where
E: Display,
impl<E: Eq> Eq for AppendError<E>
Source§impl<E> Error for AppendError<E>
impl<E> Error for AppendError<E>
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()