Struct WithholdingStore
pub struct WithholdingStore<S> { /* private fields */ }Expand description
Wraps a store so that it holds only part of its own log: a suffix, or a scattered subset with survivors between the holes.
Rejects: a reader that infers completeness from a port value. A pruned
store and a young store are the same value at every seam the port exposes
(CF-27, ES-39), so a projection runner or an ingest path that reads “the log
starts here” from head, from the lowest position it read, or from a
condition that passed, is wrong, and this is the store that shows it.
Every event it withholds behaves as removed: read never yields it, head
skips it, contains_event_id answers false for it, and an append condition
that only it would violate passes. What it withholds is reported through
withheld, its own inherent method, and never through an
EventStore method (ADR-0028).
With nothing withheld it is transparent: every call is delegated with the same arguments. Cloning it produces a second handle onto the same withheld set.
Cost. Each conditional append made while anything is withheld first reads the inner log up to the highest withheld position, which is what an instrument can afford and an adapter could not.
§What it cannot model
- Ingest deduplication. The inner store still holds what is withheld, so an ingest path over the inner store would deduplicate a re-delivered withheld event where a physically pruned store would admit it again.
- Position reuse. The inner store forgets nothing, so the instrument never reuses a position (ES-38) by delegation. That rule’s teeth are the real adapters, removing outside the port.
It implements the bare EventStore flavour only, as FaultyStore
does, and for the same coherence reason a Send sibling would be a second
type.
§Examples
use happenstance_core::{AppendCondition, Event, EventStore, MemoryEventStore};
use happenstance_core::{Query, QueryItem, ReadOptions, Tags, collect};
use happenstance_testkit::{WithholdingStore, block_on};
let claimed = |claim: &str| -> Result<Event, Box<dyn core::error::Error>> {
let tags = Tags::from_pairs([("claim", claim)])?;
Ok(Event::new("Claimed", &b"{}"[..])?.with_tags(tags))
};
let store = WithholdingStore::new(MemoryEventStore::new());
block_on(async {
for claim in ["first", "middle", "last"] {
store.append(&[claimed(claim)?], None).await?;
}
let all = collect(store.read(&Query::all(), ReadOptions::new())).await?;
let middle = all.get(1).ok_or("three were appended")?.position;
store.withhold(&[middle]).await?;
// `read` skips it, and the report names it.
let now = collect(store.read(&Query::all(), ReadOptions::new())).await?;
assert_eq!(now.len(), all.len() - 1);
assert!(now.iter().all(|event| event.position != middle));
assert!(store.withheld().contains(&middle));
// A condition only the withheld event would violate admits the append.
let only_middle =
Query::from_item(QueryItem::tagged(Tags::from_pairs([("claim", "middle")])?)?);
let landed = store
.append(&[claimed("middle")?], Some(&AppendCondition::new(only_middle)))
.await?;
assert!(landed > middle);
Ok::<(), Box<dyn core::error::Error>>(())
})?;Implementations§
§impl<S> WithholdingStore<S>
impl<S> WithholdingStore<S>
pub fn new(inner: S) -> Self
pub fn new(inner: S) -> Self
Wraps inner, withholding nothing.
pub fn withheld(&self) -> BTreeSet<SequencePosition>
pub fn withheld(&self) -> BTreeSet<SequencePosition>
Every position this instrument withholds, ascending: the report.
An owned snapshot rather than a borrowing iterator, because the set
lives behind a lock that cannot be held while a caller iterates, and a
concurrent withhold may change it meanwhile.
§impl<S: EventStore> WithholdingStore<S>
impl<S: EventStore> WithholdingStore<S>
pub async fn withhold(
&self,
positions: &[SequencePosition],
) -> Result<(), WithholdError<S::Error>>
pub async fn withhold( &self, positions: &[SequencePosition], ) -> Result<(), WithholdError<S::Error>>
Withholds the events the inner store holds at positions, all or
nothing.
Withholding an already-withheld position again is a no-op, and an empty slice withholds nothing and succeeds.
§Errors
WithholdError::NotHeld, naming the lowest such position, if the inner
store yields no event at one of positions; and
WithholdError::Store if reading the inner store fails. Either way
nothing is withheld.
pub async fn withhold_where(
&self,
select: impl FnMut(&SequencedEvent) -> bool,
) -> Result<Vec<SequencePosition>, WithholdError<S::Error>>
pub async fn withhold_where( &self, select: impl FnMut(&SequencedEvent) -> bool, ) -> Result<Vec<SequencePosition>, WithholdError<S::Error>>
Withholds every held, not yet withheld event that select picks, and
returns the positions it withheld, ascending.
The suffix is |event| event.position <= cut, a purge is a predicate on
tags, and |_| true withholds everything held.
§Errors
WithholdError::Store if reading the inner store fails, in which case
nothing is withheld.
§Examples
use happenstance_core::{Event, EventStore, MemoryEventStore, Query, ReadOptions, collect};
use happenstance_testkit::{WithholdingStore, block_on};
let store = WithholdingStore::new(MemoryEventStore::new());
block_on(async {
let mut assigned = Vec::new();
for _ in 0..4 {
assigned.push(store.append(&[Event::new("Ticked", &b"{}"[..])?], None).await?);
}
let cut = *assigned.get(1).ok_or("four were appended")?;
// Withhold a prefix of history: the store now holds only a suffix.
let withheld = store.withhold_where(|event| event.position <= cut).await?;
assert_eq!(withheld, assigned.get(..2).ok_or("four were appended")?);
let retained = collect(store.read(&Query::all(), ReadOptions::new())).await?;
assert!(retained.iter().all(|event| event.position > cut));
Ok::<(), Box<dyn core::error::Error>>(())
})?;