Skip to main content

MemorySyncPeer

Struct MemorySyncPeer 

pub struct MemorySyncPeer { /* private fields */ }
Available on crate feature memory only.
Expand description

An in-memory peer.

Send + Sync, so it implements SendSyncPeer and gets the bare SyncPeer for free. That is the right choice for a fixture: a suite written against it can be run under tokio::spawn, and the !Send half of the port is exercised by the Durable-Object-shaped stand-in in tests/ instead.

Mutex rather than RefCell for exactly that reason, and the cost is stated rather than hidden: every method can now fail with MemoryPeerError::Poisoned, a failure mode a single-threaded peer does not have.

§Examples

A device pushes what it holds to a hub, and a second device pulls it — the hub-and-spoke shape, with the hub played by this type:

use happenstance_core::{Event, EventId, RecordedAt, SequencePosition, StoreId};
use happenstance_sync::{
    EventGroup, MemorySyncPeer, PushBatch, ReplicatedEvent, SyncPeer,
};

let tablet = StoreId::from_bytes([1; 16]);
let hub = MemorySyncPeer::new(StoreId::from_bytes([2; 16]));

// An event the tablet already made durable, carrying the identity it minted.
let recorded = 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![recorded])]);

// The hub takes it once; offering it again is a skip, never a second copy.
let first = hub.push(&batch).await?;
assert_eq!((first.appended, first.skipped), (1, 0));
let again = hub.push(&batch).await?;
assert_eq!((again.appended, again.skipped), (0, 1));
assert_eq!(again.confirmed.get(tablet), Some(SequencePosition::FIRST));

// Another device pulls from the start and gets it, with an owned token
// that survives this handle being dropped.
let pulled = hub.pull(None).await?;
assert_eq!(pulled.batch.events().count(), 1);
let caught_up = hub.pull(Some(&pulled.resume)).await?;
assert_eq!(caught_up.batch.events().count(), 0, "empty means caught up");
assert_eq!(caught_up.waiting, happenstance_sync::Waiting::Nothing);

Implementations§

§

impl MemorySyncPeer

pub fn compact_recorded_before( &self, cutoff: RecordedAt, ) -> Result<Option<EventId>, MemoryPeerError>

Drops the longest prefix of this peer’s log in which every event was recorded before cutoff, as a peer compacting on a retention window does, and answers the floor afterwards.

Only a prefix. A group recorded before cutoff that sits after a newer one stays, because the floor describes resumability, not completeness (SY-32, ADR-0028). cutoff is read as a window predicate on each event’s RecordedAt, which never orders events: the prefix is in this peer’s forwarding order.

The floor is the identity of the newest event dropped, and it only moves forward: a cutoff that drops nothing more answers the floor as it was. A pull from a token that has not consumed the dropped groups is then refused with MemoryPeerError::BelowRetentionFloor, class Reseed, and limits reports the floor. A prefix of groups with no events forgets no history, and is kept.

Dropped identities are forgotten, as a physical prune forgets them, so a later push of one appends it again; Ack::confirmed does not move back.

§Errors

MemoryPeerError::Poisoned if the log lock was poisoned.

pub fn floor_token(&self) -> Result<MemoryResume, MemoryPeerError>

A token that resumes just past this peer’s floor, which accepts the gap below it: the explicit, operator-side answer to a Reseed refusal (SY-32).

A pull from the start of a compacted log is refused, as a stale token is, so an edge that lost its token cannot converge on what is retained in silence; this is how a caller says the gap is accepted. MemoryResume::start while nothing has been compacted.

§Errors

MemoryPeerError::Poisoned if the log lock was poisoned.

§

impl MemorySyncPeer

pub fn new(store: StoreId) -> Self

A peer with the minimum conformant limits.

pub fn with_limits(store: StoreId, limits: PeerLimits) -> Self

A peer that declares limits.

Useful for the case the port exists to make survivable: an origin that has already durably committed an event larger than the far side can represent.

limits.retention_floor is not reported: the floor this peer’s own compaction sets replaces it, None until then. A floor a peer declares and does not enforce is the silent failure SY-32 forbids.

pub const fn store_id(&self) -> StoreId

The store incarnation this peer speaks for.

pub fn seed(&self, group: EventGroup) -> Result<(), MemoryPeerError>

Seeds the peer’s log directly, without going through a push.

For building a fixture’s starting state. Skips the limit checks on purpose: a test that needs an oversized event on the far side has to be able to put one there.

§Errors

MemoryPeerError::Poisoned if the log lock was poisoned.

pub fn group_count(&self) -> Result<usize, MemoryPeerError>

How many groups this peer holds.

§Errors

MemoryPeerError::Poisoned if the log lock was poisoned.

Trait Implementations§

§

impl Debug for MemorySyncPeer

§

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

Formats the value using the given formatter. Read more
§

impl SendSyncPeer for MemorySyncPeer

§

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

Appends each event this peer has never held, skips each it has, and acknowledges with what it now holds.

Ack::confirmed is a per-origin high-water mark, not a contiguous prefix: dedupe is by exact identity, so after a delayed page this peer can confirm an origin’s position 2 while it still lacks position 1. Read it as “the highest position held”, never as “everything up to”.

§Errors

MemoryPeerError::BatchTooLarge for a batch over the declared max_batch_bytes, and MemoryPeerError::Poisoned if the log lock was poisoned.

§

fn limits(&self) -> PeerLimits

The limits this peer was built with, and the floor its own compaction has set (SY-32).

§

type Error = MemoryPeerError

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

type Resume = MemoryResume

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

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. Read more

Auto Trait Implementations§

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

§

impl<TraitVariantBlanketType> SyncPeer for TraitVariantBlanketType
where TraitVariantBlanketType: SendSyncPeer,

§

type Error = <TraitVariantBlanketType as SendSyncPeer>::Error

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

type Resume = <TraitVariantBlanketType as SendSyncPeer>::Resume

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

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

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

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

Offers a batch of events to the far side. 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
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.