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