Enum IngestError
#[non_exhaustive]pub enum IngestError<E> {
#[non_exhaustive] ExceedsStoreLimit {
limit: StoreLimit,
len: usize,
},
#[non_exhaustive] UnheldOwnIdentity {
id: EventId,
},
Busy(E),
Store(E),
}Expand description
Why an ingest did not land.
Every arm, save the one case below, means nothing in the call was
written: a store refuses before its transaction opens or rolls the whole
call back. A runner therefore retries, splits, parks or stops on the
class alone, and never has to ask the store what part
of a batch survived.
One case leaves the outcome unknown instead: a Store error
raised after the commit was sent and its reply lost. The whole call either
landed or did not, never part of it, and re-delivering it converges, because
an event the store already holds is a skip.
No arm refuses an event for its content. The event is already durable at
its origin, so refusing it only guarantees the two logs never converge
(SY-1, SY-33). UnheldOwnIdentity is not such
a refusal: it is about this store’s own identity, not the event’s.
#[non_exhaustive], so an arm added later, such as SY-33’s, is not
a breaking change. No bounds sit on the enum itself (they go on the
impls), so IngestError<E> is Send and Sync exactly when E is, and
the Durable Object’s Rc-holding error stays legal (ADR-0009).
§Examples
A runner reads the class, never the variant:
use happenstance_core::{EventId, SequencePosition, StoreId};
use happenstance_sync::{Classify, FailureClass, IngestError};
/// An adapter's own failure.
#[derive(Debug)]
struct DiskFull;
impl core::fmt::Display for DiskFull {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str("the disk is full")
}
}
impl core::error::Error for DiskFull {}
impl Classify for DiskFull {
fn class(&self) -> FailureClass {
FailureClass::Transient
}
}
let own = StoreId::from_bytes([7; 16]);
let claim = EventId::new(own, SequencePosition::new(3).ok_or("position zero")?);
let refused: IngestError<DiskFull> = IngestError::unheld_own_identity(claim);
// Halt this edge: an operator re-mints the store, and the same batch lands.
assert_eq!(refused.class(), FailureClass::Stop);
// The adapter's own failure answers its own class.
assert_eq!(IngestError::Store(DiskFull).class(), FailureClass::Transient);Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
#[non_exhaustive]ExceedsStoreLimit
Over a ceiling the store declares, checked before anything is written.
It mirrors AppendError::ExceedsStoreLimit, so a runner tells “this
will never fit here” from “retry” without knowing the adapter (VT-25).
Two limits are about the batch:
EventsPerBatch and
TagsPerBatch are
Split, because the batch is too big and its
events are not. Groups are atomic, though, so a call of one group over
either limit cannot be split further, and what a runner does then is
#244’s. Every other limit is about one event, and is
Park.
Fields
This variant is marked as non-exhaustive
limit: StoreLimitWhich ceiling was exceeded.
#[non_exhaustive]UnheldOwnIdentity
An event claims this store’s own identity at a position this store does not hold.
This store minted that identity, so holding nothing under it means the store was restored or rewound under an identity it should have re-minted (VT-6). Writing the event would wedge the local append that later reaches the claimed position, so nothing in the call is written.
Stop, because the remedy is configuration: an
operator re-mints the store’s identity, and the same batch then lands,
with the claim as a foreign event (SY-38). A retry without the remedy
fails the same way. The refusal is about this store’s identity, not the
event’s content or the log’s, which is why it is not SY-33’s forbidden
kind of refusal.
Fields
This variant is marked as non-exhaustive
Busy(E)
The store’s write lock was not acquired, and nothing was written.
Transient whatever the cause’s own class:
the same call can succeed once the holder lets go, which is
AppendError::Busy’s contract on the ingest path. A store that cannot
tell contention from failure reports Store instead.
Store(E)
The adapter failed, and its own Classify impl states the class.
The one arm whose outcome can be unknown. When it is raised after the commit was sent and the reply lost, the call either landed whole or not at all, and re-delivery converges.
Implementations§
§impl<E> IngestError<E>
Constructors for the two struct arms.
impl<E> IngestError<E>
Constructors for the two struct arms.
Both arms are #[non_exhaustive], so a field can be added to either
later without breaking a match: the offending event’s identity on
ExceedsStoreLimit is the likely one, for a runner that parks a single
event. The price is that a struct literal is refused outside this crate,
so an adapter builds the arms through these. A match outside the crate
spells { id, .. }.
pub const fn exceeds_store_limit(limit: StoreLimit, len: usize) -> Self
pub const fn exceeds_store_limit(limit: StoreLimit, len: usize) -> Self
ExceedsStoreLimit: len, in limit’s
own unit, is over the store’s ceiling.
pub const fn unheld_own_identity(id: EventId) -> Self
pub const fn unheld_own_identity(id: EventId) -> Self
UnheldOwnIdentity: id claims this
store’s identity, and this store does not hold it.
Trait Implementations§
§impl<E: Classify> Classify for IngestError<E>
Each arm’s class is fixed by the arm, except Store,
which asks the adapter’s error. So the class is a function of the value
alone (SY-36).
impl<E: Classify> Classify for IngestError<E>
Each arm’s class is fixed by the arm, except Store,
which asks the adapter’s error. So the class is a function of the value
alone (SY-36).
§fn class(&self) -> FailureClass
fn class(&self) -> FailureClass
§impl<E: Debug> Debug for IngestError<E>
impl<E: Debug> Debug for IngestError<E>
§impl<E> Display for IngestError<E>where
E: Display,
impl<E> Display for IngestError<E>where
E: Display,
§impl<E> Error for IngestError<E>
impl<E> Error for IngestError<E>
§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()