Trait IngestStore
pub trait IngestStore {
type Error: Error + Classify + 'static;
// Required methods
async fn store_id(&self) -> Result<StoreId, Self::Error>;
async fn ingest(
&self,
groups: &[IngestGroup<'_>],
) -> Result<Ingested, IngestError<Self::Error>>;
async fn watermark(&self) -> Result<Watermark, Self::Error>;
}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§
Required Methods§
async fn store_id(&self) -> Result<StoreId, Self::Error>
async fn store_id(&self) -> Result<StoreId, Self::Error>
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.
async fn ingest(
&self,
groups: &[IngestGroup<'_>],
) -> Result<Ingested, IngestError<Self::Error>>
async fn ingest( &self, groups: &[IngestGroup<'_>], ) -> Result<Ingested, IngestError<Self::Error>>
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.
async fn watermark(&self) -> Result<Watermark, Self::Error>
async fn watermark(&self) -> Result<Watermark, Self::Error>
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".