Skip to main content

IngestError

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 enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

#[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
Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.
§limit: StoreLimit

Which ceiling was exceeded.

§len: usize

The magnitude that exceeded it, in the limit’s own unit.

§

#[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
Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.
§id: EventId

The first such identity the write met.

§

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.

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

ExceedsStoreLimit: len, in limit’s own unit, is over the store’s ceiling.

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).

§

fn class(&self) -> FailureClass

The remedy this failure calls for.
§

impl<E: Debug> Debug for IngestError<E>

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl<E> Display for IngestError<E>
where E: Display,

§

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl<E> Error for IngestError<E>
where E: Error + 'static, Self: Debug + Display,

§

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more

Auto Trait Implementations§

§

impl<E> Freeze for IngestError<E>
where E: Freeze,

§

impl<E> RefUnwindSafe for IngestError<E>
where E: RefUnwindSafe,

§

impl<E> Send for IngestError<E>
where E: Send,

§

impl<E> Sync for IngestError<E>
where E: Sync,

§

impl<E> Unpin for IngestError<E>
where E: Unpin,

§

impl<E> UnsafeUnpin for IngestError<E>
where E: UnsafeUnpin,

§

impl<E> UnwindSafe for IngestError<E>
where E: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.