Skip to main content

SendIngestStore

Trait SendIngestStore 

pub trait SendIngestStore: Send {
    type Error: Error + Classify + 'static;

    // Required methods
    fn store_id(
        &self,
    ) -> impl Future<Output = Result<StoreId, Self::Error>> + Send;
    fn ingest(
        &self,
        groups: &[IngestGroup<'_>],
    ) -> impl Future<Output = Result<Ingested, IngestError<Self::Error>>> + Send;
    fn watermark(
        &self,
    ) -> impl Future<Output = Result<Watermark, Self::Error>> + Send;
}
Expand description

A store that can accept events another store already minted.

Separate from EventStore on purpose. The two operations look similar and are not: an append is a decision, taken now, against a condition checked now, by a store that assigns the identity. An ingest is the recording of a decision somebody else already took and already made durable, and the identity came with it.

Only a peer runner should hold one of these. Handing an IngestStore to application code hands it the ability to forge history.

§A third crate cannot supply this impl

Coherence permits this trait’s own crate, or a store’s own crate, to write the implementation. It permits nobody else, which is worth knowing before someone plans on a blanket impl in a testkit:

ⓘ
use happenstance_sync::IngestStore;

// Foreign trait, foreign type, third crate. The orphan rule refuses.
impl IngestStore for happenstance_core::Event {
    type Error = core::convert::Infallible;
}

§Flavours

This is the !Send flavour, and generic code should bind it: the ingest path on the Cloudflare side is single-threaded and cannot satisfy a Send bound at all. Adapters that can cross threads implement SendIngestStore and get this for free.

Required Associated Types§

type Error: Error + Classify + 'static

How this store fails, stating a class so a runner never infers one.

Required Methods§

fn store_id(&self) -> impl Future<Output = Result<StoreId, Self::Error>> + Send

This store’s own incarnation identifier.

Tells “an event I minted, coming back to me” from “an event a peer minted”. The first, while this store still holds it, is a skip like any other re-delivery. One that claims this identity and is not held means the store was restored or rewound under an identity it should have re-minted (VT-6). The ingest then writes nothing and fails with IngestError::UnheldOwnIdentity, whose remedy is the re-mint (SY-38).

async and fallible because a SQL store keeps its identity in a row, and reading it is I/O that can fail; a store holding it answers Ok.

§Errors

The adapter’s error: the store could not read its identity, so no claim on it can be judged and ingest cannot proceed. Its Classify impl states the class.

fn ingest( &self, groups: &[IngestGroup<'_>], ) -> impl Future<Output = Result<Ingested, IngestError<Self::Error>>> + Send

Records events other stores minted, preserving their identity, together with any compensation this side writes for them.

One call per pulled batch, not per event. Each group lands atomically or not at all, compensation included; a store may commit the whole batch as one unit, and one that can express it as one statement should.

Events land at the tail: an ingested event is assigned the next local position like any other write, and keeps its origin’s EventId and RecordedAt unchanged. Inserting it at the position its origin gave it would rewrite history under a projection that has already read past it.

No append condition is evaluated, the origin’s or this store’s (SY-1). A conflict is answered by the group’s compensation, which is minted here, as ordinary local events, in the same transaction as the events it answers.

Re-delivery is a no-op. A peer will offer the same event more than once — after a dropped connection, after a resume token that did not advance, after an operator re-seeds a device — and each repeat is skipped rather than appended again or rejected. The skip is decided inside the write, against the store’s own uniqueness on the origin pair (VT-8), never by a lookup ahead of it. A group whose foreign events were all skipped writes no compensation either (SY-11): the first delivery already wrote it.

§Errors

An IngestError, and nothing in the call was written: a capacity refusal, an unheld own identity (see store_id), a busy store, or the adapter’s own failure. The one exception is a Store error raised after the commit was sent and its reply lost: the outcome is unknown, and re-delivery converges, as a held event is a skip. None judges the events: content is durable elsewhere, so refusing it only guarantees the logs never converge.

fn watermark( &self, ) -> impl Future<Output = Result<Watermark, Self::Error>> + Send

The highest origin position this store holds from each origin store.

This is what a spoke sends as its resume position and what a hub answers a pull against. It is derived from the log rather than stored as a separate counter, so it cannot drift from what was actually written.

§Errors

The adapter’s error if the watermark cannot be computed.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

§

impl SendIngestStore for MemoryIngestStore

Available on crate feature memory only.