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}