Skip to main content

StoreSyncPeer

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>

pub const fn new(events: S, ingest: I) -> Self

A peer over events and ingest, declaring PeerLimits::minimum.

Examples found in repository?
examples/two-devices-one-seat/src/scenario.rs (line 138)
134    fn linked_to(central: &Central, rule: A) -> Self {
135        // Two handles onto one store: central's read half and ingest half
136        // must be the same store, and a `SqliteEventStore` clone is a second
137        // handle onto the same connection, not a copy of the log.
138        let far = StoreSyncPeer::new(central.clone(), central.clone()).with_adjudicator(rule);
139        let limits = far.limits();
140        Self {
141            peer: RemoteSyncPeer::new(Uplink::new(far), limits),
142            edge: Edge::new(),
143        }
144    }

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>

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.

Examples found in repository?
examples/two-devices-one-seat/src/scenario.rs (line 138)
134    fn linked_to(central: &Central, rule: A) -> Self {
135        // Two handles onto one store: central's read half and ingest half
136        // must be the same store, and a `SqliteEventStore` clone is a second
137        // handle onto the same connection, not a copy of the log.
138        let far = StoreSyncPeer::new(central.clone(), central.clone()).with_adjudicator(rule);
139        let limits = far.limits();
140        Self {
141            peer: RemoteSyncPeer::new(Uplink::new(far), limits),
142            edge: Edge::new(),
143        }
144    }

Trait Implementations§

§

impl<S: Clone, I: Clone, A: Clone> Clone for StoreSyncPeer<S, I, A>

§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
§

impl<S: Debug, I: Debug, A: Debug> Debug for StoreSyncPeer<S, I, A>

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

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

§

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>

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.

§

type Error = StorePeerError<<S as WriteGroupStore>::Error, <I as IngestStore>::Error, <A as Adjudicate>::Error>

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

type Resume = StoreResume

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

fn limits(&self) -> PeerLimits

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

Auto Trait Implementations§

§

impl<S, I, A> Freeze for StoreSyncPeer<S, I, A>
where S: Freeze, I: Freeze, A: Freeze,

§

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

§

impl<S, I, A> Send for StoreSyncPeer<S, I, A>
where S: Send, I: Send, A: Send,

§

impl<S, I, A> Sync for StoreSyncPeer<S, I, A>
where S: Sync, I: Sync, A: Sync,

§

impl<S, I, A> Unpin for StoreSyncPeer<S, I, A>
where S: Unpin, I: Unpin, A: Unpin,

§

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

§

impl<S, I, A> UnwindSafe for StoreSyncPeer<S, I, A>
where S: UnwindSafe, I: UnwindSafe, A: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.