Skip to main content

happenstance_core/
projection_memory.rs

1//! An in-memory reference projection store.
2
3use alloc::string::{String, ToString};
4use std::collections::BTreeMap;
5use std::sync::atomic::{AtomicU64, Ordering};
6use std::sync::{PoisonError, RwLock};
7
8use crate::event::SequencePosition;
9use crate::projection::{
10    Authority, Checkpoint, CommitError, ProjectionId, ResetError, SendProjectionStore,
11};
12
13/// The reference implementation of [`ProjectionStore`](crate::ProjectionStore).
14///
15/// It exists for the same three reasons
16/// [`MemoryEventStore`](crate::MemoryEventStore) does, in the same order of
17/// importance:
18///
19/// 1. it is the oracle the conformance suite is validated against, so that a
20///    failing adapter is known to be the adapter's fault and not the suite's;
21/// 2. it makes this crate's examples runnable, so the documentation cannot
22///    drift from the API;
23/// 3. it lets application code be written and tested before any real adapter
24///    exists.
25///
26/// It is deliberately **obvious rather than fast**. When a conformance rule
27/// fails, the adapter is presumed wrong and this store is presumed right, so its
28/// correctness has to be readable in one sitting: one lock over one struct
29/// holding both halves, and [`commit`](crate::ProjectionStore::commit) takes
30/// that lock exactly once. Splitting it into more than one guarded section is
31/// precisely the shape a store that writes the checkpoint without its read model
32/// fails for.
33///
34/// # One end of the batch-shape axis
35///
36/// This store **applies on write**: a batch is a materialised delta layered over
37/// committed state, so it can be read back through before it commits, and
38/// `ProjectionProbe::READS_THROUGH_BATCH` is `true` here. The other end of that
39/// axis — a batch that buffers and replays at commit, where read-through is
40/// impossible and declining it is the conformant answer — is a separate
41/// implementation. Nothing a conformance rule needs may assume read-through
42/// beyond that constant.
43///
44/// The probe's name is deliberately not a link, for the reason the crate root
45/// gives twice: this page renders whenever `memory` is on, `ProjectionProbe`
46/// exists only under `conformance`, and `rustdoc::broken_intra_doc_links` is
47/// `deny` — so a link here is a hard error on the crate's **default** feature
48/// set, which is what a consumer builds.
49///
50/// # Examples
51///
52/// The whole loop: open a batch, write through it, commit the rows and the
53/// checkpoint as one unit, read both back, then return the projection to
54/// [`Checkpoint::NeverRun`] with the caller's own deletes.
55///
56/// ```
57/// use happenstance_core::{
58///     Authority, Checkpoint, MemoryProjectionStore, ProjectionId, ProjectionStore,
59///     SequencePosition,
60/// };
61///
62/// # #[tokio::main(flavor = "current_thread")]
63/// # async fn main() -> Result<(), Box<dyn core::error::Error>> {
64/// let store = MemoryProjectionStore::new();
65/// let id = ProjectionId::new("van_stock")?;
66///
67/// // Never run: the enum says so, and no `Option` is involved.
68/// assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);
69///
70/// // `begin` never yields and never fails here: opening a buffer is free.
71/// let mut batch = store.begin().await?;
72/// batch.write("depot-7", 12);
73///
74/// // Nothing is visible yet — not the row, not the checkpoint.
75/// assert_eq!(store.get("depot-7"), None);
76/// assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);
77///
78/// // One unit of work: the row and the checkpoint, or neither.
79/// store
80///     .commit(batch, &id, SequencePosition::FIRST, Authority::Live)
81///     .await?;
82///
83/// assert_eq!(store.get("depot-7"), Some(12));
84/// assert_eq!(
85///     store.checkpoint(&id).await?,
86///     Checkpoint::Live { through: SequencePosition::FIRST },
87/// );
88///
89/// // The dual: the caller's own batch carries the deletes, because the port
90/// // has no idea what the read model is.
91/// let mut clearing = store.begin().await?;
92/// clearing.delete_all();
93/// store.reset(clearing, &id).await?;
94///
95/// assert_eq!(store.get("depot-7"), None);
96/// assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);
97/// # Ok(())
98/// # }
99/// ```
100#[derive(Debug)]
101pub struct MemoryProjectionStore {
102    state: RwLock<State>,
103    /// Minted per store *instance*, which is what makes the foreign-batch check
104    /// possible at all — a per-type stamp would compare equal everywhere.
105    stamp: u64,
106}
107
108/// Hand-written, and **not** `#[derive(Default)]`, for the same reason
109/// [`MemoryEventStore`](crate::MemoryEventStore)'s is hand-written: `stamp` is
110/// this instance's identity, and the derive would fill it with `0` without ever
111/// calling the counter, which starts at `1`. Two `default()` stores would then
112/// share identity `0`, each would accept the other's batch, and
113/// [`CommitError::ForeignBatch`] — the check the oracle exists to be *right*
114/// about — would be unreachable through that constructor.
115/// `commit_rejects_a_foreign_batch_from_default_stores` and its `reset` twin in
116/// `tests/projection_memory.rs` are what keep the derive from coming back.
117impl Default for MemoryProjectionStore {
118    fn default() -> Self {
119        Self::new()
120    }
121}
122
123/// The read model and the checkpoints, behind **one** lock.
124///
125/// Keeping them behind one lock is what makes "installed under one lock
126/// acquisition" true by construction rather than by discipline. Two locks would
127/// compile, pass every test that reads them separately, and reintroduce the
128/// window the port exists to close.
129#[derive(Debug, Default)]
130struct State {
131    rows: BTreeMap<String, u64>,
132    checkpoints: BTreeMap<String, Checkpoint>,
133}
134
135impl MemoryProjectionStore {
136    /// A store with no rows and no checkpoints.
137    #[must_use]
138    pub fn new() -> Self {
139        Self {
140            state: RwLock::new(State::default()),
141            stamp: next_stamp(),
142        }
143    }
144
145    /// Opens a batch. The inherent twin of
146    /// [`begin`](crate::ProjectionStore::begin), so an application author can
147    /// drive this store without importing the port.
148    #[must_use]
149    pub fn open(&self) -> MemoryProjectionBatch {
150        MemoryProjectionBatch {
151            stamp: self.stamp,
152            writes: BTreeMap::new(),
153            clear_all: false,
154        }
155    }
156
157    /// One committed row, or `None`.
158    #[must_use]
159    pub fn get(&self, key: &str) -> Option<u64> {
160        self.read_guard().rows.get(key).copied()
161    }
162
163    /// Every committed row, in key order.
164    #[must_use]
165    pub fn snapshot(&self) -> BTreeMap<String, u64> {
166        self.read_guard().rows.clone()
167    }
168
169    /// How many committed rows the read model holds.
170    #[must_use]
171    pub fn len(&self) -> usize {
172        self.read_guard().rows.len()
173    }
174
175    /// Whether the read model holds no committed rows.
176    #[must_use]
177    pub fn is_empty(&self) -> bool {
178        self.read_guard().rows.is_empty()
179    }
180
181    /// Reads through the lock, recovering from poisoning.
182    ///
183    /// A panic in another thread while the lock was held cannot have left this
184    /// store inconsistent: every mutation happens in one guarded section and the
185    /// validation preceding it does not mutate. So poisoning carries no
186    /// information, and propagating it would surface as a spurious `Err` from
187    /// the *oracle* — a rule failure attributed to the adapter under test.
188    fn read_guard(&self) -> std::sync::RwLockReadGuard<'_, State> {
189        self.state.read().unwrap_or_else(PoisonError::into_inner)
190    }
191
192    /// Writes through the lock, recovering from poisoning. See
193    /// [`read_guard`](Self::read_guard).
194    fn write_guard(&self) -> std::sync::RwLockWriteGuard<'_, State> {
195        self.state.write().unwrap_or_else(PoisonError::into_inner)
196    }
197}
198
199/// An in-flight write against a [`MemoryProjectionStore`].
200///
201/// Owned, and not a live transaction: it holds a materialised delta plus the
202/// stamp of the store instance that minted it. Nothing it holds is visible
203/// through the store until [`commit`](crate::ProjectionStore::commit) or
204/// [`reset`](crate::ProjectionStore::reset) takes it.
205///
206/// Dropping it discards it and leaves the store usable — there is nothing to
207/// release, because nothing was ever handed to the store.
208#[derive(Debug, Clone)]
209pub struct MemoryProjectionBatch {
210    stamp: u64,
211    writes: BTreeMap<String, u64>,
212    clear_all: bool,
213}
214
215impl MemoryProjectionBatch {
216    /// Queues a row.
217    pub fn write(&mut self, key: impl Into<String>, value: u64) {
218        self.writes.insert(key.into(), value);
219    }
220
221    /// Queues removal of every row in the read model.
222    ///
223    /// This is what a caller puts in the batch they hand to
224    /// [`reset`](crate::ProjectionStore::reset): the port never learns which
225    /// rows are the read model, so the caller supplies the deletes.
226    pub fn delete_all(&mut self) {
227        self.writes.clear();
228        self.clear_all = true;
229    }
230
231    /// Reads a row through the open batch — pending writes layered over
232    /// `committed`.
233    ///
234    /// Gated on `conformance` because its only caller is, and a private method
235    /// whose caller is behind a feature is dead code in every build that does
236    /// not ask for it. That combination is reachable and ordinary — `default`
237    /// without `conformance` is what an application using the projection
238    /// runner resolves — and it failed `RUSTFLAGS="-D warnings"`
239    /// with *method `read_through` is never used*.
240    ///
241    /// **Not `#[expect(dead_code)]`**, which would be actively wrong: `expect`
242    /// fires when the lint it names does *not*, so it would be correct in the
243    /// builds where the method is dead and an `unfulfilled_lint_expectation`
244    /// warning in the `conformance` builds where it is used. `#[allow]` would
245    /// work and loses on two counts — it keeps compiling the body into every
246    /// consumer's build, and it silences the next method to go genuinely dead
247    /// here. A `cfg` that matches the caller's says the true thing.
248    #[cfg(feature = "conformance")]
249    fn read_through(&self, committed: Option<u64>, key: &str) -> Option<u64> {
250        if let Some(pending) = self.writes.get(key) {
251            return Some(*pending);
252        }
253        if self.clear_all {
254            return None;
255        }
256        committed
257    }
258
259    /// Applies this batch to `rows`.
260    fn apply_to(self, rows: &mut BTreeMap<String, u64>) {
261        if self.clear_all {
262            rows.clear();
263        }
264        rows.extend(self.writes);
265    }
266}
267
268/// [`MemoryProjectionStore`]'s error type, which is uninhabited.
269///
270/// An uninhabited error is worth having: it proves the contract does not
271/// *require* a fallible read path, and it documents at the type level that this
272/// store has no failure modes of its own. Populating it would delete that claim.
273///
274/// Nothing the conformance suite needs is lost.
275/// [`CommitError`] and [`ResetError`] are still meaningfully fallible here — a
276/// foreign batch and a regressing position are both reachable — and the
277/// adapter-failure paths a suite must also exercise come from hostile stores
278/// written for that purpose, never from the oracle.
279///
280/// Distinct from [`MemoryStoreError`](crate::MemoryStoreError), whose `Display`
281/// names the event store.
282#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
283#[error("unreachable: the in-memory projection store cannot fail")]
284pub enum MemoryProjectionStoreError {}
285
286impl SendProjectionStore for MemoryProjectionStore {
287    type Error = MemoryProjectionStoreError;
288
289    // The concrete type, spelled straight out. Under the GAT this line was
290    // `type Batch<'a> = MemoryProjectionBatch;` and the methods below still had
291    // to say `Self::Batch<'_>` literally or hit `error[E0195]`. There is no
292    // lifetime left to mismatch, so an implementer copying this writes their own
293    // type in both places and it compiles.
294    type Batch = MemoryProjectionBatch;
295
296    async fn begin(&self) -> Result<Self::Batch, Self::Error> {
297        Ok(self.open())
298    }
299
300    async fn checkpoint(&self, id: &ProjectionId) -> Result<Checkpoint, Self::Error> {
301        Ok(self
302            .read_guard()
303            .checkpoints
304            .get(id.as_str())
305            .copied()
306            .unwrap_or(Checkpoint::NeverRun))
307    }
308
309    async fn commit(
310        &self,
311        batch: Self::Batch,
312        id: &ProjectionId,
313        position: SequencePosition,
314        authority: Authority,
315    ) -> Result<(), CommitError<Self::Error>> {
316        if batch.stamp != self.stamp {
317            return Err(CommitError::ForeignBatch);
318        }
319
320        // One guard, held across the check and both writes. Everything below is
321        // infallible, so there is no path that mutates and then fails.
322        let mut state = self.write_guard();
323
324        let recorded = state
325            .checkpoints
326            .get(id.as_str())
327            .copied()
328            .unwrap_or(Checkpoint::NeverRun);
329        if let Some(current) = considered_through(recorded)
330            && position < current
331        {
332            return Err(CommitError::CheckpointRegression {
333                current,
334                attempted: position,
335            });
336        }
337
338        let checkpoint = match authority {
339            Authority::Rebuilding => Checkpoint::Rebuilding { through: position },
340            // `Live` and any variant added later: a commit that does not claim a
341            // rebuild is claiming the rows are authoritative.
342            _ => Checkpoint::Live { through: position },
343        };
344
345        batch.apply_to(&mut state.rows);
346        state.checkpoints.insert(id.to_string(), checkpoint);
347        Ok(())
348    }
349
350    async fn reset(
351        &self,
352        batch: Self::Batch,
353        id: &ProjectionId,
354    ) -> Result<(), ResetError<Self::Error>> {
355        if batch.stamp != self.stamp {
356            return Err(ResetError::ForeignBatch);
357        }
358
359        // This store has no protection policy, so it never returns `Refused`.
360        // That is not a gap: a rule needing a refusal is served by a store
361        // written to refuse, and an oracle that refused arbitrarily would be a
362        // worse oracle.
363        let mut state = self.write_guard();
364
365        batch.apply_to(&mut state.rows);
366        // *Removing* the key is what returns the projection to `NeverRun`.
367        // Writing a sentinel position would reintroduce exactly the ambiguity
368        // the three-variant enum exists to forbid.
369        state.checkpoints.remove(id.as_str());
370        Ok(())
371    }
372
373    async fn rollback(&self, batch: Self::Batch) -> Result<(), Self::Error> {
374        drop(batch);
375        Ok(())
376    }
377}
378
379#[cfg(feature = "conformance")]
380impl crate::projection::ProjectionProbe for MemoryProjectionStore {
381    /// `true`, because this store applies on write and a batch can therefore be
382    /// read back through before it commits.
383    const READS_THROUGH_BATCH: bool = true;
384
385    async fn probe_write(
386        &self,
387        batch: &mut Self::Batch,
388        key: &str,
389        value: u64,
390    ) -> Result<(), Self::Error> {
391        batch.write(key, value);
392        Ok(())
393    }
394
395    async fn probe_delete_all(&self, batch: &mut Self::Batch) -> Result<(), Self::Error> {
396        batch.delete_all();
397        Ok(())
398    }
399
400    async fn probe_read(&self, key: &str) -> Result<Option<u64>, Self::Error> {
401        Ok(self.get(key))
402    }
403
404    async fn probe_read_through(
405        &self,
406        batch: &mut Self::Batch,
407        key: &str,
408    ) -> Result<Option<u64>, Self::Error> {
409        Ok(batch.read_through(self.get(key), key))
410    }
411}
412
413/// The position a checkpoint has been considered through, if any.
414///
415/// `NeverRun` has none, which is why a first commit at any position is accepted
416/// and only a *regression* against a recorded position is refused.
417const fn considered_through(checkpoint: Checkpoint) -> Option<SequencePosition> {
418    match checkpoint {
419        Checkpoint::NeverRun => None,
420        Checkpoint::Live { through } | Checkpoint::Rebuilding { through } => Some(through),
421    }
422}
423
424/// A fresh per-instance stamp.
425///
426/// Process-local and monotonic, which is all the foreign-batch check needs: a
427/// batch cannot outlive the process that minted it. A durable adapter has the
428/// harder job — mint at database creation, and re-mint when that state is
429/// restored or cloned.
430fn next_stamp() -> u64 {
431    static COUNTER: AtomicU64 = AtomicU64::new(1);
432    COUNTER.fetch_add(1, Ordering::Relaxed)
433}