Struct StoreSyncPeer
pub struct StoreSyncPeer<S, I, A = Accept> { /* private fields */ }Expand description
A peer over a store the caller holds: events to read, ingest to write.
Two handles rather than one value, because an adapter’s read half and its ingest half may be separate handles onto one store — and they must be the same store. A peer whose pushes land somewhere its pulls never read acknowledges events it will never forward.
§It adjudicates only with a rule
By default a push ingests with no compensation: the store peer only
replicates, under Accept. Given a merge rule by
with_adjudicator, it judges each pushed group
before the push lands, and lands each with the compensation the rule
answered, in one write (SY-2). That is how a hub served by this peer,
directly or behind
serve_sync_adjudicated, is the
peer SY-7 makes the adjudicator of what its spokes push (SY-10). It never
judges what it is pulled from: that is the pulling edge’s rule.
§Limits
The PeerLimits it declares are the ones it enforces on a push and fills
a pull to. Declare no more than the store accepts: an event the declaration
admits and the store’s ingest refuses is the failure SY-18 exists to move
ahead of the push.
The declaration binds pulls too, and that includes groups the far store
appended locally, which no push limit checked. A group at the head of the
unread log that the declaration cannot carry whole — an event over the
declared max_event_bytes, or more events or
bytes than one batch takes — cannot travel in any page, because a group is
never split: every pull from there on returns an empty page,
Waiting::Unknown and the token it was given, and replication stalls at
that group until the far side declares larger limits. Declare
max_batch_events at least the store’s per-call ceiling, and
max_event_bytes and max_batch_bytes at least the largest payload and the
largest write the store’s own writers accept.
§Send
Implements the bare SyncPeer, so a !Send store, such as the Durable
Object’s, is a valid far side. Bind it as SyncPeer in generic code
(RS-20-2). For concrete Send stores its futures are Send too, but the
type does not implement SendSyncPeer, and
coherence forbids adding it beside the bare impl: trait_variant’s
blanket impl already gives every SendSyncPeer the bare trait. Code that
spawns and binds SendSyncPeer takes
SendPeer::new(peer) instead, over Send + Sync halves
(#421).
§Examples
use happenstance_core::{Event, EventId, RecordedAt, SequencePosition, StoreId};
use happenstance_sync::{
EventGroup, MemoryIngestStore, PushBatch, ReplicatedEvent, StoreSyncPeer, SyncPeer,
Waiting,
};
// The far side's store; `&MemoryIngestStore` is not itself a store, so the
// example hands the peer a handle type of its own.
let hub = Shared(std::sync::Arc::new(MemoryIngestStore::new()));
let peer = StoreSyncPeer::new(hub.clone(), hub);
let tablet = StoreId::from_bytes([1; 16]);
let reading = ReplicatedEvent::new(
EventId::new(tablet, SequencePosition::FIRST),
RecordedAt::from_millis(1_700_000_000_000),
Event::new("ReadingTaken", &b"{\"celsius\":4}"[..])?,
);
let batch = PushBatch::new(vec![EventGroup::new(None, vec![reading])]);
assert_eq!(peer.push(&batch).await?.appended, 1);
let pulled = peer.pull(None).await?;
assert_eq!(pulled.batch, batch);
assert_eq!(pulled.waiting, Waiting::Nothing);Implementations§
§impl<S, I> StoreSyncPeer<S, I>
impl<S, I> StoreSyncPeer<S, I>
pub const fn new(events: S, ingest: I) -> Self
pub const fn new(events: S, ingest: I) -> Self
A peer over events and ingest, declaring
PeerLimits::minimum.
pub const fn with_limits(events: S, ingest: I, limits: PeerLimits) -> Self
pub const fn with_limits(events: S, ingest: I, limits: PeerLimits) -> Self
A peer over events and ingest that declares, and enforces, limits.
pub fn with_adjudicator<B>(self, rule: B) -> StoreSyncPeer<S, I, B>
pub fn with_adjudicator<B>(self, rule: B) -> StoreSyncPeer<S, I, B>
The same peer, judging what it is pushed by rule: each pushed group
lands in one write with the compensation rule answers for it (SY-2,
SY-7). The rule is asked only for a push the declared limits admit, so
a refused push reaches no rule and writes nothing.
Only the push: what this peer is pulled from is the pulling edge’s to
judge, through Edge::with_adjudicator.
Trait Implementations§
§impl<S, I, A> SyncPeer for StoreSyncPeer<S, I, A>
impl<S, I, A> SyncPeer for StoreSyncPeer<S, I, A>
§async fn pull(
&self,
from: Option<&StoreResume>,
) -> Result<Pulled<StoreResume>, Self::Error>
async fn pull( &self, from: Option<&StoreResume>, ) -> Result<Pulled<StoreResume>, Self::Error>
Reads the far store’s write groups above from, each whole, until the
declared budget is spent or the log ends, and names the store that
answered.
§Errors
StorePeerError::Read if the store’s group read fails, and
StorePeerError::Identity if its identity cannot be read; either way
nothing was forwarded, and the same pull can be retried.
§async fn push(&self, batch: &PushBatch) -> Result<Ack, Self::Error>
async fn push(&self, batch: &PushBatch) -> Result<Ack, Self::Error>
Ingests each pushed group as one atomic group, with the compensation the peer’s merge rule answers for it, and acknowledges with the store’s watermark after the write.
The travelling guards are not evaluated (SY-1): each is stored with its
group and forwarded on pull (SY-30), and a rule may read them as
evidence (SY-6). Under Accept, the default, no group is
compensated. The rule is asked after the limits admit the push and
before the one ingest, each group with the groups before it.
§Errors
StorePeerError::EventTooLarge, TooManyEvents
or BatchTooLarge for a push the
declared limits do not admit, with nothing written;
StorePeerError::Adjudicate if the rule cannot judge the push, with
nothing written;
StorePeerError::Ingest if the store refuses or fails the write; and
StorePeerError::Watermark or StorePeerError::Identity if the
write landed and the confirmation, or the identity that names the
store which took it, could not be read; in either case re-delivery is a
skip.