Skip to main content

SyncPeer

Trait SyncPeer 

pub trait SyncPeer {
    type Error: Error + Classify + 'static;
    type Resume: Clone + 'static;

    // Required methods
    async fn pull(
        &self,
        from: Option<&Self::Resume>,
    ) -> Result<Pulled<Self::Resume>, Self::Error>;
    async fn push(&self, batch: &PushBatch) -> Result<Ack, Self::Error>;
    fn limits(&self) -> PeerLimits;
}
Expand description

One peer relationship.

This is the !Send flavour and the one to use in generic bounds; adapters that can cross threads should implement SendSyncPeer and get this for free.

§One peer, not a peer set

Every method describes a single relationship. Fan-out across several peers, ordering between them, and what to do when two disagree are policy, and policy on the port would make every adapter author — including whoever writes the 200-line HTTP client — inherit the merge problem. They belong to a runner above this trait, in the same division of labour that puts the projection runner above ProjectionStore. “Add a second peer” is then a runner configuration and not a breaking change to a published trait.

§Hub-ness is not on the port

Nothing here says whether the far side is a hub or a spoke. A store in the middle of a chain — a Durable Object that is a spoke to a cloud estate store and a hub to 138 tablets — is one peer wearing each hat, and a is_hub() on the port would force it to answer a question that has two answers.

Required Associated Types§

type Error: Error + Classify + 'static

How this peer’s transport fails; each failure states its class.

Carries no Send bound. That is what admits the Durable Object peer, whose errors wrap a JsValue-derived string behind an Rc and are !Send for reasons no adapter author can do anything about. Requiring Send + Sync here was attempted; the Durable Object stand-in in tests/real_peer_shapes.rs fails it with two error[E0277]s — Rc<str> cannot be sent between threads safely, and the same again for Sync.

type Resume: Clone + 'static

Where to resume from: opaque to the caller, owned by the caller.

An associated type rather than a Watermark or a SequencePosition, for two reasons that pull in the same direction. A position is meaningful only inside one store, so it cannot cross this boundary at all; and whether replication is whole-log or scoped is still open, and a scalar cannot distinguish “not yet received” from “filtered out”. An opaque associated type defers that question into the adapter without deferring the port.

Owned and Clone, never a handle the peer holds. A resume token that lives inside the peer object is a resume token that does not exist at the edge: a Worker is cancelled mid-flight, a Durable Object is evicted, a tablet loses signal. The normal termination path out there is the handle going away, so the token has to survive the handle being dropped and reconstructed.

It is not required to be Send, and that is a gap rather than a decision: trait_variant marks the derived futures Send and leaves associated types alone, so a runner that wants to tokio::spawn a per-peer task and carry the token out of it needs to write S::Resume: Send at its own bound. E0277 when it does not; the same gap happenstance-core has on EventStore::Error, arriving on a type that carries data rather than a failure, where it cannot be collapsed to a usize before the next await.

Required Methods§

async fn pull( &self, from: Option<&Self::Resume>, ) -> Result<Pulled<Self::Resume>, Self::Error>

Fetches the next batch of events the far side holds and this side does not, plus the token to resume after them.

from is None on a first exchange. The returned token is always the one to use next, even when the batch is empty — an empty batch means “caught up for now”, not “start over”.

§One round trip

The whole operation must complete in a single exchange. There is no open / next_batch / close, which is the shape every socket-based design produces and is unimplementable on a peer that reaches its store over one-shot HTTP.

§Errors

Returns the adapter’s error for transport and authorisation failures. Nothing about the content of the far side’s log is an error here.

async fn push(&self, batch: &PushBatch) -> Result<Ack, Self::Error>

Offers a batch of events to the far side.

§Errors

Transport- or authorisation-level refusals only. A peer may not refuse a push because it disagrees with the events in it: an ingested event is a fact another store has already durably committed, and refusing it does not un-commit it — it only guarantees the two logs never converge.

fn limits(&self) -> PeerLimits

What this peer can accept, readable before a push rather than discovered as an error after one.

Not async, and that is the whole point: a runner that has to await a round trip to learn a size cap will skip the check, and a limit nobody checks is a limit discovered at ingest — which is after the write has already committed somewhere else, the one moment at which nothing useful can be done about it.

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§

§

impl<S, I, A> SyncPeer for StoreSyncPeer<S, I, A>

§

impl<TraitVariantBlanketType: SendSyncPeer> SyncPeer for TraitVariantBlanketType

§

type Error = <TraitVariantBlanketType as SendSyncPeer>::Error

§

type Resume = <TraitVariantBlanketType as SendSyncPeer>::Resume

§

impl<X: Exchange> SyncPeer for RemoteSyncPeer<X>