rebuilding_read_models/main.rs
1//! Operating derived state: four views over one log, on one SQLite file.
2//!
3//! `transfers-on-sqlite` proves a projection survives a reopen. It runs *one*
4//! view, and a single view is the one arrangement in which none of the
5//! questions an operator actually has can be asked: it is never skewed against
6//! a peer, never rebuilt, never reset, and never the one that breaks while the
7//! others must keep going.
8//!
9//! This program has four views over one log and does the four things to them
10//! that a running system eventually demands.
11//!
12//! Run with `cargo run -p rebuilding-read-models`.
13//!
14//! # What this demonstrates that the other examples cannot
15//!
16//! 1. **Two views sit at two checkpoints, and a reader must tolerate it.** A
17//! checkpoint is per `(store, ProjectionId)`. Halfway through, this program
18//! advances one view and not the other and then joins the two tables, so
19//! the stale row is visible rather than argued about.
20//! 2. **A view added late is backfilled beside the one it replaces.** The
21//! typed runner always claims `Authority::Live`, so a rebuild is bought
22//! with a *second* `ProjectionId` writing a *second* table — blue and
23//! green — and the swap is the application's, at the moment it chooses. It
24//! rides in the old id's reset batch, so retirement and swap are one
25//! transaction, and a swap that fails leaves the old view whole.
26//! 3. **Reset is a real operation, and rebuilding is chunk-size invariant.**
27//! `ProjectionStore::reset` clears the read model and the checkpoint as one
28//! unit and leaves `Checkpoint::NeverRun` behind — not a checkpoint at the
29//! first position, which is how event 1 gets skipped permanently and
30//! silently. Rebuilt at chunk 1 and at chunk 500, the rows are identical.
31//! 4. **One poisoned view does not stall the others.** The failure is the one
32//! that actually happens in production: a projection written against a
33//! field the log does not carry. It fails to *decode*, names the position
34//! it failed at, commits nothing, and the other three carry on — because
35//! the failure policy is this application's and not the runner's.
36//!
37//! # What it does not demonstrate, stated so nobody reads more into it
38//!
39//! It is one process and it never crashes. `transfers-on-sqlite` owns the
40//! durability claim and `tickets-over-http` owns the two-process one; the
41//! subject here is what an operator does to a view that is already working.
42//! Nor is the poisoned view a claim about fault *injection*: nothing here
43//! interrupts a commit halfway. That belongs to the conformance suite. The one
44//! promotion that fails on purpose fails on a statement, inside a transaction
45//! that is then rolled back — an operator's typo, not a crash.
46//!
47//! # The domain, and why it is not another ledger
48//!
49//! Order fulfilment, because it is the smallest domain that naturally wants
50//! *several* views of one log that disagree about what matters — stock is
51//! per-SKU, status is per-order, and the dispatch count is per-day and belongs
52//! to neither. Three shapes over one event set is the situation the
53//! projection port exists for, and one shape cannot demonstrate it.
54
55use std::io::{self, Write as _};
56use std::path::{Path, PathBuf};
57
58use anyhow::{Result, bail};
59use happenstance::bytes::Bytes;
60use happenstance::{
61 Checkpoint, Chunk, Codec, CodecError, CommandError, DecisionModel, Delivered, DomainEvent,
62 EventStore, EventType, InvalidTag, Json, Projection, ProjectionError, ProjectionId,
63 ProjectionStore, Query, ReadOptions, Retry, Tag, Tags, checkpoint_id, collect, commit,
64 run_projection,
65};
66use happenstance_sqlite::connection::open_configured;
67use happenstance_sqlite::event_store::{SqliteEventStore, SqliteEventStoreError};
68use happenstance_sqlite::projection_store::{
69 SqliteBatch, SqliteProjectionStore, SqliteProjectionStoreError,
70};
71use rusqlite::Connection;
72use rusqlite::types::Value;
73use serde::{Deserialize, Serialize};
74
75/// How many times a command may be attempted before it gives up.
76///
77/// Spelled at every call site for the reason `course-subscriptions` gives: a
78/// loop whose only exit is success is a hang with better manners. This run is
79/// single-writer, so the bound is never spent.
80const ATTEMPTS: u32 = 3;
81
82/// The chunk the ordinary catch-up runs use.
83///
84/// Small enough that a first run commits more than once, which is the only way
85/// a checkpoint's *intermediate* positions are ever written.
86const CHUNK: usize = 4;
87
88/// The two chunk sizes a rebuild is run at, to show the rows do not depend on
89/// how the replay was divided.
90///
91/// One is the smallest legal chunk — a commit per event — and the other is
92/// larger than this log will ever be, so the whole replay lands in a single
93/// batch. If those two disagree, the fold is carrying state it should not.
94const REBUILD_CHUNKS: [usize; 2] = [1, 500];
95
96/// The two days this run dispatches on.
97///
98/// Literals rather than a clock. A transcript that changes with the calendar
99/// is a transcript nobody can diff, and the daily view exists to be counted,
100/// not to be current.
101const DAYS: [&str; 2] = ["2026-09-01", "2026-09-02"];
102
103/// The five read-model tables this application owns.
104///
105/// They are the application's tables, not the adapter's: `SqliteProjectionStore`
106/// migrates `projection_checkpoint` and `projection_meta` and stops there. A
107/// projection store that invented your read model's schema would be a framework
108/// rather than a port — which is also why the blue/green swap below is plain
109/// SQL this file writes, and not a method somebody else designed.
110const READ_MODEL_DDL: &str = "
111CREATE TABLE IF NOT EXISTS stock_on_hand (
112 sku TEXT PRIMARY KEY,
113 on_hand INTEGER NOT NULL
114) STRICT;
115CREATE TABLE IF NOT EXISTS order_status (
116 order_ref TEXT PRIMARY KEY,
117 status TEXT NOT NULL,
118 sku TEXT NOT NULL,
119 quantity INTEGER NOT NULL
120) STRICT;
121CREATE TABLE IF NOT EXISTS daily_dispatches (
122 day TEXT PRIMARY KEY,
123 dispatched INTEGER NOT NULL
124) STRICT;
125CREATE TABLE IF NOT EXISTS daily_dispatches_v2 (
126 day TEXT PRIMARY KEY,
127 dispatched INTEGER NOT NULL
128) STRICT;
129CREATE TABLE IF NOT EXISTS couriered (
130 order_ref TEXT PRIMARY KEY,
131 courier TEXT NOT NULL
132) STRICT;
133";
134
135#[tokio::main(flavor = "current_thread")]
136async fn main() -> Result<()> {
137 let path = database_path();
138 remove_database(&path);
139
140 writeln!(io::stdout().lock(), "== the database this run writes to ==")?;
141 writeln!(io::stdout().lock(), " {}", path.display())?;
142
143 // The run is a function so that every store, connection and projection it
144 // builds is dropped before the file is removed — on Windows an open handle
145 // is what makes the cleanup silently fail and the next run start on the
146 // tail of this one.
147 let outcome = run(&path).await;
148 remove_database(&path);
149 outcome
150}
151
152/// Everything this program does, inside one scope over one file.
153async fn run(path: &Path) -> Result<()> {
154 let events = SqliteEventStore::open(path)?;
155 let models = SqliteProjectionStore::open(path)?;
156 let app = open_configured(path)?;
157 app.execute_batch(READ_MODEL_DDL)?;
158
159 seed_the_log(&events).await?;
160 two_views_two_checkpoints(&events, &models, &app).await?;
161 a_third_view_added_late(&events, &models, &app).await?;
162 reset_and_rebuild(&events, &models, &app).await?;
163 one_poisoned_view(&events, &models).await?;
164
165 writeln!(io::stdout().lock(), "\n== final log ==")?;
166 print_log(&events).await?;
167
168 Ok(())
169}
170
171// ---------------------------------------------------------------------------
172// The five things this program does
173// ---------------------------------------------------------------------------
174
175/// Writes the events every view below is derived from.
176///
177/// One refusal is exercised on the way, so the log is the product of decisions
178/// rather than of appends: an order for more units than the shelf holds is
179/// rejected against the same boundary that would have let it through.
180async fn seed_the_log(events: &SqliteEventStore) -> Result<()> {
181 writeln!(io::stdout().lock(), "\n== seeding the fulfilment log ==")?;
182
183 receive_stock(events, "sku-1", 13).await?;
184 receive_stock(events, "sku-2", 6).await?;
185 place_order(events, "o-1", "sku-1", 3).await?;
186 place_order(events, "o-2", "sku-1", 2).await?;
187 place_order(events, "o-3", "sku-2", 4).await?;
188 dispatch_order(events, "o-1", DAYS[0]).await?;
189 dispatch_order(events, "o-2", DAYS[0]).await?;
190 writeln!(
191 io::stdout().lock(),
192 " two SKUs received, three orders placed, two dispatched"
193 )?;
194
195 match place_order(events, "o-9", "sku-2", 5).await {
196 Ok(()) => bail!("an order against an emptied shelf should have been rejected"),
197 Err(err) => writeln!(io::stdout().lock(), " rejected: {err}")?,
198 }
199
200 Ok(())
201}
202
203/// Advances one view and not the other, and shows what a reader then sees.
204///
205/// The skew is not a defect being confessed to — it is the arrangement. A
206/// checkpoint is per `(store, ProjectionId)`, so two views over one log are
207/// two independent positions, and an application that joins them is reading
208/// two different moments. Printing both checkpoints beside the rows is the
209/// only way to say that without it sounding theoretical.
210async fn two_views_two_checkpoints(
211 events: &SqliteEventStore,
212 models: &SqliteProjectionStore,
213 app: &Connection,
214) -> Result<()> {
215 writeln!(
216 io::stdout().lock(),
217 "\n== two views over one log, at two checkpoints =="
218 )?;
219
220 let mut stock = StockOnHand::new();
221 let mut status = OrderStatus::new();
222 let applied_stock = drive(events, models, &mut stock, CHUNK).await?;
223 let applied_status = drive(events, models, &mut status, CHUNK).await?;
224 writeln!(
225 io::stdout().lock(),
226 " stock_on_hand applied {applied_stock}, order_status applied {applied_status}"
227 )?;
228
229 // Both are caught up here, which is the only state in which the skew below
230 // is attributable to what this function does next rather than to how they
231 // were built.
232 print_checkpoint(models, &stock).await?;
233 print_checkpoint(models, &status).await?;
234
235 writeln!(
236 io::stdout().lock(),
237 "\n -- a fourth order is placed, and only one view is run --"
238 )?;
239 place_order(events, "o-4", "sku-1", 5).await?;
240 let applied_stock = drive(events, models, &mut stock, CHUNK).await?;
241 writeln!(
242 io::stdout().lock(),
243 " stock_on_hand applied {applied_stock}, order_status was not run"
244 )?;
245 print_checkpoint(models, &stock).await?;
246 print_checkpoint(models, &status).await?;
247
248 writeln!(io::stdout().lock(), "\n stock_on_hand:")?;
249 print_table(app, "SELECT sku, on_hand FROM stock_on_hand ORDER BY sku")?;
250 writeln!(io::stdout().lock(), " order_status:")?;
251 print_table(
252 app,
253 "SELECT order_ref, status FROM order_status ORDER BY order_ref",
254 )?;
255 writeln!(
256 io::stdout().lock(),
257 " o-4's five units are already off the shelf and it has no status row:\n \
258 a join across these two tables is a join across two moments"
259 )?;
260
261 writeln!(
262 io::stdout().lock(),
263 "\n -- order_status is brought level --"
264 )?;
265 let applied_status = drive(events, models, &mut status, CHUNK).await?;
266 writeln!(
267 io::stdout().lock(),
268 " order_status applied {applied_status}"
269 )?;
270 print_checkpoint(models, &stock).await?;
271 print_checkpoint(models, &status).await?;
272
273 Ok(())
274}
275
276/// Backfills a view that did not exist when the log was written, then promotes it.
277///
278/// The typed runner always claims `Authority::Live`, so there is no in-place
279/// rebuild to reach for and this is not a limitation being worked around: a
280/// second `ProjectionId` writing a second table is blue/green, and it is the
281/// arrangement that lets the old view keep answering queries the whole time.
282///
283/// The promotion is plain SQL this file writes, because the read model belongs
284/// to this application. **The `ProjectionId` deliberately does not change with
285/// it.** `daily_dispatches_v2` keeps its name after the swap, because the
286/// checkpoint is keyed by that name and the derived query (`checkpoint_id`) —
287/// renaming it to look tidy would throw the resume point away and replay the
288/// whole log. The table is not part of the query, so the swap keeps the key.
289///
290/// The swap is pushed into the *old* id's reset batch rather than run beside
291/// it, and that is what makes it one transaction. It is attempted once with
292/// the new table's name mistyped first, to show what that buys: the drop runs,
293/// the rename fails, and the old view keeps its rows and its checkpoint.
294async fn a_third_view_added_late(
295 events: &SqliteEventStore,
296 models: &SqliteProjectionStore,
297 app: &Connection,
298) -> Result<()> {
299 writeln!(
300 io::stdout().lock(),
301 "\n== a third view, added after the fact =="
302 )?;
303
304 let mut blue = DailyDispatches::counting_orders();
305 let applied = drive(events, models, &mut blue, CHUNK).await?;
306 writeln!(
307 io::stdout().lock(),
308 " daily_dispatches backfilled from zero: applied {applied}"
309 )?;
310 print_table(
311 app,
312 "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
313 )?;
314
315 writeln!(
316 io::stdout().lock(),
317 "\n -- the count was wrong: it wanted units, not orders --"
318 )?;
319 let mut green = DailyDispatches::counting_units();
320 let applied = drive(events, models, &mut green, CHUNK).await?;
321 writeln!(
322 io::stdout().lock(),
323 " daily_dispatches_v2 backfilled beside it: applied {applied}"
324 )?;
325 print_table(
326 app,
327 "SELECT day, dispatched FROM daily_dispatches_v2 ORDER BY day",
328 )?;
329 writeln!(
330 io::stdout().lock(),
331 " both views are live at once, and neither has stopped answering"
332 )?;
333
334 // From here blue's runner is stopped and green's is paused: neither is
335 // driven again until green comes back as `promoted`. A runner still
336 // scheduled under blue's id would replay the whole log into whichever
337 // table has the name it writes to once its checkpoint is reset.
338 writeln!(
339 io::stdout().lock(),
340 "\n -- a promotion whose rename fails --"
341 )?;
342 match retire(models, &blue, &MISTYPED_PROMOTION).await {
343 Ok(()) => bail!("a promotion from a table that does not exist was committed"),
344 Err(err) => writeln!(io::stdout().lock(), " refused: {err}")?,
345 }
346 print_checkpoint(models, &blue).await?;
347 print_table(
348 app,
349 "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
350 )?;
351 writeln!(
352 io::stdout().lock(),
353 " the drop ran and was rolled back with the rename: blue is untouched"
354 )?;
355
356 writeln!(
357 io::stdout().lock(),
358 "\n -- promoted, and the checkpoint comes with it --"
359 )?;
360 // The swap is blue's reset batch, so retiring blue and renaming green into
361 // its place are one transaction. A reader sees the old table until the
362 // reset commits and the new one after it, never an empty one between. Done
363 // as a retirement and then a separate swap, the gap between the two is a
364 // view with no rows and an id at `NeverRun` — which the attempt above
365 // would have left behind for good.
366 retire(models, &blue, &PROMOTION).await?;
367 let mut promoted = DailyDispatches::promoted();
368 // The resume below rests on this: the promoted view derives green's
369 // checkpoint id, because it shares green's name, event type and scope.
370 // Only its table changed, and the table is not part of the query.
371 if checkpoint_id(&promoted)? != checkpoint_id(&green)? {
372 bail!("the promoted view would not resume from green's checkpoint");
373 }
374 print_checkpoint(models, &promoted).await?;
375
376 dispatch_order(events, "o-3", DAYS[1]).await?;
377 let applied = drive(events, models, &mut promoted, CHUNK).await?;
378 writeln!(
379 io::stdout().lock(),
380 " one more dispatch, and the promoted view applied {applied} — not the whole log"
381 )?;
382 print_table(
383 app,
384 "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
385 )?;
386
387 Ok(())
388}
389
390/// Clears a view and builds it again, twice, at two very different chunk sizes.
391///
392/// `reset` is the operation that makes a read model disposable, and it clears
393/// the rows and the checkpoint as **one** unit of work: a delete that succeeded
394/// while the checkpoint survived would leave a view that is empty and believes
395/// it is current. What it leaves behind is `Checkpoint::NeverRun`, which is a
396/// different thing from a checkpoint at the first position — an operator who
397/// substitutes one for the other makes the next run resume *after* event 1, and
398/// event 1 is then skipped permanently and silently.
399///
400/// The two chunk sizes are the assertion. Chunk 1 commits once per event and
401/// chunk 500 commits the whole replay at once; if the rows differ, the fold is
402/// carrying state across events that it should be writing into the row.
403async fn reset_and_rebuild(
404 events: &SqliteEventStore,
405 models: &SqliteProjectionStore,
406 app: &Connection,
407) -> Result<()> {
408 /// The query both rebuilds are compared through.
409 const ROWS: &str = "SELECT sku, on_hand FROM stock_on_hand ORDER BY sku";
410
411 writeln!(
412 io::stdout().lock(),
413 "\n== reset, and rebuilt at two chunk sizes =="
414 )?;
415 let mut rebuilt = Vec::with_capacity(REBUILD_CHUNKS.len());
416
417 for chunk in REBUILD_CHUNKS {
418 let mut stock = StockOnHand::new();
419 retire(models, &stock, &["DELETE FROM stock_on_hand"]).await?;
420 let cleared = models.checkpoint(&checkpoint_id(&stock)?).await?;
421 let applied = drive(events, models, &mut stock, chunk).await?;
422 writeln!(
423 io::stdout().lock(),
424 " cleared to {}, rebuilt at chunk {chunk}: applied {applied}",
425 render_checkpoint(cleared)
426 )?;
427 rebuilt.push(render_table(app, ROWS)?);
428 }
429
430 match rebuilt.as_slice() {
431 [small, large] if small == large => {
432 let mut out = io::stdout().lock();
433 writeln!(out, " both rebuilds produced the same rows:")?;
434 write!(out, "{small}")?;
435 Ok(())
436 }
437 [small, large] => {
438 bail!("a rebuild's rows depend on its chunk size\nchunk 1:\n{small}chunk 500:\n{large}")
439 }
440 // Unreachable while `REBUILD_CHUNKS` has two entries. Spelled as a
441 // refusal rather than as an index, because an index would turn a
442 // changed constant into a panic in a program whose whole subject is
443 // not losing data quietly.
444 other => bail!("expected two rebuilds, got {}", other.len()),
445 }
446}
447
448/// Breaks one view and shows the other three keep moving.
449///
450/// The failure is the one that actually happens: somebody writes a projection
451/// against a field the log does not carry. It is not injected and nothing is
452/// corrupted — the events are exactly as they were written, and the *reader*
453/// is what disagrees with them. That failure surfaces as a decode error naming
454/// the position it stopped at, the chunk is rolled back, and the checkpoint
455/// stays where it was, which for a view that never ran is nowhere.
456///
457/// What this program does next is the part no library can decide: it records
458/// the failure and runs the others. `run_projection` drives one projection and
459/// halts on its first failure, which is the right primitive — a runner that
460/// swallowed the error would be deciding, for every application at once, that
461/// a wrong read model is better than a stalled one.
462async fn one_poisoned_view(
463 events: &SqliteEventStore,
464 models: &SqliteProjectionStore,
465) -> Result<()> {
466 writeln!(
467 io::stdout().lock(),
468 "\n== one poisoned view does not stall the others =="
469 )?;
470
471 let mut couriered = Couriered::new();
472 let (stopped_at, why) = poison(events, models, &mut couriered).await?;
473 writeln!(
474 io::stdout().lock(),
475 " couriered stopped at position {stopped_at}: {why}"
476 )?;
477 // Every `.await` is resolved before the `writeln!` that prints its result:
478 // the locked handle is taken before the format arguments are evaluated, so
479 // an `.await` inside them would hold the guard across a suspension.
480 let key = checkpoint_id(&couriered)?;
481 let checkpoint = render_checkpoint(models.checkpoint(&key).await?);
482 writeln!(
483 io::stdout().lock(),
484 " its checkpoint is {checkpoint} — the chunk was rolled back and nothing was committed"
485 )?;
486
487 writeln!(
488 io::stdout().lock(),
489 "\n -- an event arrives while that view is broken --"
490 )?;
491 cancel_order(events, "o-4").await?;
492
493 let mut stock = StockOnHand::new();
494 let mut status = OrderStatus::new();
495 let mut daily = DailyDispatches::promoted();
496 let applied = drive(events, models, &mut stock, CHUNK).await?;
497 writeln!(io::stdout().lock(), " stock_on_hand applied {applied}")?;
498 let applied = drive(events, models, &mut status, CHUNK).await?;
499 writeln!(io::stdout().lock(), " order_status applied {applied}")?;
500 let applied = drive(events, models, &mut daily, CHUNK).await?;
501 writeln!(io::stdout().lock(), " daily_dispatches applied {applied}")?;
502
503 let (still_stuck, _) = poison(events, models, &mut couriered).await?;
504 writeln!(
505 io::stdout().lock(),
506 " couriered is still stuck at position {still_stuck}"
507 )?;
508
509 Ok(())
510}
511
512// ---------------------------------------------------------------------------
513// Identity, validated once at the edge
514// ---------------------------------------------------------------------------
515
516/// A stock-keeping unit, validated once into the tag its events carry.
517///
518/// The resolution `course-subscriptions` and `transfers-on-sqlite` both reach,
519/// and for the same reason: `DomainEvent::tags` is infallible while
520/// `Tag::key_value` can refuse, so a domain type whose tags come from runtime
521/// values holds the validated form instead of rebuilding it on every call.
522#[derive(Debug, Clone, Serialize, Deserialize)]
523#[serde(try_from = "String", into = "String")]
524struct Sku {
525 /// The identifier as the application wrote it.
526 id: String,
527 /// The same value, validated into the tag every event for it carries.
528 tag: Tag,
529}
530
531impl Sku {
532 /// Validates `id` into the tag every event for this SKU is written with.
533 fn new(id: &str) -> Result<Self, InvalidTag> {
534 Ok(Self {
535 id: id.to_owned(),
536 tag: Tag::key_value("sku", id)?,
537 })
538 }
539
540 /// The identifier as the application wrote it.
541 fn as_str(&self) -> &str {
542 &self.id
543 }
544}
545
546impl TryFrom<String> for Sku {
547 type Error = InvalidTag;
548
549 fn try_from(id: String) -> Result<Self, InvalidTag> {
550 Self::new(&id)
551 }
552}
553
554impl From<Sku> for String {
555 fn from(sku: Sku) -> Self {
556 sku.id
557 }
558}
559
560/// An order reference, validated once into the tag its events carry.
561#[derive(Debug, Clone, Serialize, Deserialize)]
562#[serde(try_from = "String", into = "String")]
563struct OrderId {
564 /// The reference as the application wrote it.
565 id: String,
566 /// The same value, validated into the tag every event for it carries.
567 tag: Tag,
568}
569
570impl OrderId {
571 /// Validates `id` into the tag every event for this order is written with.
572 fn new(id: &str) -> Result<Self, InvalidTag> {
573 Ok(Self {
574 id: id.to_owned(),
575 tag: Tag::key_value("order", id)?,
576 })
577 }
578
579 /// The reference as the application wrote it.
580 fn as_str(&self) -> &str {
581 &self.id
582 }
583}
584
585impl TryFrom<String> for OrderId {
586 type Error = InvalidTag;
587
588 fn try_from(id: String) -> Result<Self, InvalidTag> {
589 Self::new(&id)
590 }
591}
592
593impl From<OrderId> for String {
594 fn from(order: OrderId) -> Self {
595 order.id
596 }
597}
598
599// ---------------------------------------------------------------------------
600// The domain: one enum, named once
601// ---------------------------------------------------------------------------
602
603/// Everything that can happen while a shelf is emptied into orders.
604///
605/// One enum, so a query and a fold cannot name different sets. There is no
606/// `_ =>` arm anywhere in this file: a fifth variant is a compile error in
607/// every decision model and every projection that has not been told what it
608/// means, and that absence is the guarantee.
609#[derive(Debug, Serialize, Deserialize)]
610enum Fulfilment {
611 /// Stock arrived on the shelf.
612 StockReceived {
613 /// What arrived.
614 sku: Sku,
615 /// How many units.
616 quantity: u32,
617 },
618 /// An order took units off the shelf and is waiting to go out.
619 OrderPlaced {
620 /// The order now waiting.
621 order: OrderId,
622 /// What it holds.
623 sku: Sku,
624 /// How many units it holds.
625 quantity: u32,
626 },
627 /// An order left the building.
628 OrderDispatched {
629 /// The order that went.
630 order: OrderId,
631 /// What it held.
632 sku: Sku,
633 /// How many units it held.
634 quantity: u32,
635 /// The day it went, as a plain `YYYY-MM-DD` string.
636 day: String,
637 },
638 /// An order was called off and its units went back on the shelf.
639 OrderCancelled {
640 /// The order called off.
641 order: OrderId,
642 /// What it was holding.
643 sku: Sku,
644 /// How many units go back.
645 quantity: u32,
646 },
647}
648
649/// The four names this log carries, declared once and returned by name.
650///
651/// `Handover` below re-declares one of them: it is a *narrower* view of the same
652/// log, and sharing the constant is what stops the two lists drifting apart.
653const STOCK_RECEIVED: EventType = EventType::from_static("StockReceived");
654/// See [`STOCK_RECEIVED`].
655const ORDER_PLACED: EventType = EventType::from_static("OrderPlaced");
656/// See [`STOCK_RECEIVED`].
657const ORDER_DISPATCHED: EventType = EventType::from_static("OrderDispatched");
658/// See [`STOCK_RECEIVED`].
659const ORDER_CANCELLED: EventType = EventType::from_static("OrderCancelled");
660
661impl DomainEvent for Fulfilment {
662 const EVENT_TYPES: &'static [EventType] = &[
663 STOCK_RECEIVED,
664 ORDER_PLACED,
665 ORDER_DISPATCHED,
666 ORDER_CANCELLED,
667 ];
668
669 fn event_type(&self) -> EventType {
670 match self {
671 Self::StockReceived { .. } => STOCK_RECEIVED,
672 Self::OrderPlaced { .. } => ORDER_PLACED,
673 Self::OrderDispatched { .. } => ORDER_DISPATCHED,
674 Self::OrderCancelled { .. } => ORDER_CANCELLED,
675 }
676 }
677
678 fn tags(&self) -> Tags {
679 match self {
680 Self::StockReceived { sku, .. } => [sku.tag.clone()].into_iter().collect(),
681 Self::OrderPlaced { order, sku, .. }
682 | Self::OrderDispatched { order, sku, .. }
683 | Self::OrderCancelled { order, sku, .. } => {
684 [order.tag.clone(), sku.tag.clone()].into_iter().collect()
685 }
686 }
687 }
688
689 fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
690 codec.encode(self)
691 }
692
693 fn decode<C: Codec>(
694 codec: &C,
695 _event_type: &EventType,
696 data: &Bytes,
697 ) -> Result<Self, CodecError> {
698 codec.decode(data)
699 }
700}
701
702/// The event set the `couriered` view was written against, and the log is not.
703///
704/// It declares the same event *type* as `Fulfilment`'s dispatch variant and a
705/// different *shape*: a `courier` this application has never written. Nothing
706/// about that is detectable at compile time — the type name matches, the query
707/// nominates the right events, and the mistake surfaces where every schema
708/// mistake surfaces, at the first payload that has to be decoded.
709///
710/// It is a separate enum rather than a variant of `Fulfilment` because it
711/// belongs to a different reader. That is the whole situation being modelled:
712/// two teams, one log, and a disagreement about what was written.
713#[derive(Debug, Serialize, Deserialize)]
714enum Handover {
715 /// A dispatch, as a later reader expected it to have been recorded.
716 OrderDispatched {
717 /// The order that went.
718 order: OrderId,
719 /// Who carried it. **Never written by this application.**
720 courier: String,
721 },
722}
723
724impl DomainEvent for Handover {
725 const EVENT_TYPES: &'static [EventType] = &[ORDER_DISPATCHED];
726
727 fn event_type(&self) -> EventType {
728 match self {
729 Self::OrderDispatched { .. } => ORDER_DISPATCHED,
730 }
731 }
732
733 fn tags(&self) -> Tags {
734 match self {
735 Self::OrderDispatched { order, .. } => [order.tag.clone()].into_iter().collect(),
736 }
737 }
738
739 fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
740 codec.encode(self)
741 }
742
743 fn decode<C: Codec>(
744 codec: &C,
745 _event_type: &EventType,
746 data: &Bytes,
747 ) -> Result<Self, CodecError> {
748 codec.decode(data)
749 }
750}
751
752/// Why a decision refused.
753///
754/// Every variant carries the value the transcript prints — `sku-2 holds 2,
755/// needs 5` and never `out of stock` — so a reader can act on the refusal
756/// where it is printed instead of opening a second document to learn what
757/// happened.
758#[derive(Debug, thiserror::Error)]
759enum Refusal {
760 /// A receipt of nothing is not a receipt.
761 #[error("cannot receive zero units of {sku}")]
762 ZeroQuantity {
763 /// The SKU nothing arrived for.
764 sku: String,
765 },
766 /// An order reference may be used once.
767 #[error("order {order} has already been placed")]
768 AlreadyPlaced {
769 /// The reference already in use.
770 order: String,
771 },
772 /// The shelf cannot cover the order.
773 #[error("{sku} holds {on_hand}, needs {needed}")]
774 OutOfStock {
775 /// The SKU that cannot cover it.
776 sku: String,
777 /// What is on the shelf.
778 on_hand: i64,
779 /// What the order asked for.
780 needed: u32,
781 },
782 /// Nothing can happen to an order nobody placed.
783 #[error("order {order} has not been placed")]
784 NotPlaced {
785 /// The reference nobody placed.
786 order: String,
787 },
788 /// An order goes out once.
789 #[error("order {order} has already been dispatched")]
790 AlreadyDispatched {
791 /// The order already gone.
792 order: String,
793 },
794 /// A cancelled order is finished.
795 #[error("order {order} has already been cancelled")]
796 AlreadyCancelled {
797 /// The order already called off.
798 order: String,
799 },
800}
801
802// ---------------------------------------------------------------------------
803// The decision models: one per consistency concern
804// ---------------------------------------------------------------------------
805
806/// What is on the shelf for one SKU.
807///
808/// Scoped to a single `sku` tag, so the query this model derives nominates
809/// every event ever written about that SKU and nothing else.
810#[derive(Debug, Clone)]
811struct Stock {
812 /// The tags every event inside this boundary carries.
813 scope: Tags,
814 /// Units currently on the shelf, after placements and cancellations.
815 on_hand: i64,
816}
817
818impl Stock {
819 /// Validates the scope once, here, where the caller already writes a `?`.
820 fn new(sku: &Sku) -> Result<Self, InvalidTag> {
821 Ok(Self {
822 scope: Tags::from_pairs([("sku", sku.as_str())])?,
823 on_hand: 0,
824 })
825 }
826}
827
828impl DecisionModel for Stock {
829 type Event = Fulfilment;
830
831 fn scope(&self) -> &Tags {
832 &self.scope
833 }
834
835 fn apply(&mut self, event: Self::Event) {
836 match event {
837 Fulfilment::StockReceived { quantity, .. }
838 | Fulfilment::OrderCancelled { quantity, .. } => {
839 self.on_hand = self.on_hand.saturating_add(i64::from(quantity));
840 }
841 Fulfilment::OrderPlaced { quantity, .. } => {
842 self.on_hand = self.on_hand.saturating_sub(i64::from(quantity));
843 }
844 // A dispatch moves nothing: the units left the shelf when the order
845 // was placed, and counting them again here would show a shelf going
846 // negative for stock that was already reserved. The arm exists
847 // because the fold is exhaustive over the enum, and that
848 // exhaustiveness is the whole guarantee.
849 Fulfilment::OrderDispatched { .. } => {}
850 }
851 }
852}
853
854/// One order's own history.
855///
856/// Scoped to a single `order` tag. It is what makes a dispatch buildable from
857/// folded state rather than from arguments the caller has to repeat: the SKU
858/// and the quantity come out of the order's own placement.
859#[derive(Debug, Clone)]
860struct Order {
861 /// The tags every event inside this boundary carries.
862 scope: Tags,
863 /// What this order holds, once it has been placed.
864 held: Option<(Sku, u32)>,
865 /// Whether it has already gone out.
866 dispatched: bool,
867 /// Whether it has already been called off.
868 cancelled: bool,
869}
870
871impl Order {
872 /// Validates the scope once, here, where the caller already writes a `?`.
873 fn new(order: &OrderId) -> Result<Self, InvalidTag> {
874 Ok(Self {
875 scope: Tags::from_pairs([("order", order.as_str())])?,
876 held: None,
877 dispatched: false,
878 cancelled: false,
879 })
880 }
881}
882
883impl DecisionModel for Order {
884 type Event = Fulfilment;
885
886 fn scope(&self) -> &Tags {
887 &self.scope
888 }
889
890 fn apply(&mut self, event: Self::Event) {
891 match event {
892 Fulfilment::OrderPlaced { sku, quantity, .. } => self.held = Some((sku, quantity)),
893 Fulfilment::OrderDispatched { .. } => self.dispatched = true,
894 Fulfilment::OrderCancelled { .. } => self.cancelled = true,
895 // A stock receipt carries no `order` tag, so this model's query
896 // never nominates one. The arm exists for exhaustiveness.
897 Fulfilment::StockReceived { .. } => {}
898 }
899 }
900}
901
902// ---------------------------------------------------------------------------
903// The four command handlers
904// ---------------------------------------------------------------------------
905
906/// Puts units on the shelf.
907async fn receive_stock(events: &SqliteEventStore, sku: &str, quantity: u32) -> Result<()> {
908 let sku = Sku::new(sku)?;
909 let boundary = Stock::new(&sku)?;
910
911 commit(
912 events,
913 boundary,
914 Retry::attempts(ATTEMPTS.try_into()?),
915 |_shelf: &Stock| {
916 if quantity == 0 {
917 return Err(Refusal::ZeroQuantity {
918 sku: sku.id.clone(),
919 });
920 }
921 Ok(vec![Fulfilment::StockReceived {
922 sku: sku.clone(),
923 quantity,
924 }])
925 },
926 )
927 .await
928 .map(|_| ())
929 .map_err(rejected)
930}
931
932/// Takes units off the shelf for an order that does not exist yet.
933///
934/// The one decision here that spans two entities: *can the shelf cover it* is
935/// the SKU's concern and *is this reference already in use* is the order's, and
936/// the tuple is both, OR'd into one query and checked by one append condition.
937/// This example does not dwell on it — `handles-and-quotas` is where the
938/// composition argument is made — but the shelf number every view below is
939/// derived from is only trustworthy because this boundary is drawn correctly.
940async fn place_order(
941 events: &SqliteEventStore,
942 order: &str,
943 sku: &str,
944 quantity: u32,
945) -> Result<()> {
946 let order = OrderId::new(order)?;
947 let sku = Sku::new(sku)?;
948 let boundary = (Stock::new(&sku)?, Order::new(&order)?);
949
950 commit(
951 events,
952 boundary,
953 Retry::attempts(ATTEMPTS.try_into()?),
954 |(shelf, existing): &(Stock, Order)| {
955 if existing.held.is_some() {
956 return Err(Refusal::AlreadyPlaced {
957 order: order.id.clone(),
958 });
959 }
960 if shelf.on_hand < i64::from(quantity) {
961 return Err(Refusal::OutOfStock {
962 sku: sku.id.clone(),
963 on_hand: shelf.on_hand,
964 needed: quantity,
965 });
966 }
967 Ok(vec![Fulfilment::OrderPlaced {
968 order: order.clone(),
969 sku: sku.clone(),
970 quantity,
971 }])
972 },
973 )
974 .await
975 .map(|_| ())
976 .map_err(rejected)
977}
978
979/// Sends an order out, on a named day.
980async fn dispatch_order(events: &SqliteEventStore, order: &str, day: &str) -> Result<()> {
981 let order = OrderId::new(order)?;
982 let boundary = Order::new(&order)?;
983
984 commit(
985 events,
986 boundary,
987 Retry::attempts(ATTEMPTS.try_into()?),
988 |state: &Order| {
989 let Some((sku, quantity)) = state.held.clone() else {
990 return Err(Refusal::NotPlaced {
991 order: order.id.clone(),
992 });
993 };
994 if state.dispatched {
995 return Err(Refusal::AlreadyDispatched {
996 order: order.id.clone(),
997 });
998 }
999 if state.cancelled {
1000 return Err(Refusal::AlreadyCancelled {
1001 order: order.id.clone(),
1002 });
1003 }
1004 Ok(vec![Fulfilment::OrderDispatched {
1005 order: order.clone(),
1006 sku,
1007 quantity,
1008 day: day.to_owned(),
1009 }])
1010 },
1011 )
1012 .await
1013 .map(|_| ())
1014 .map_err(rejected)
1015}
1016
1017/// Calls an order off and puts its units back.
1018async fn cancel_order(events: &SqliteEventStore, order: &str) -> Result<()> {
1019 let order = OrderId::new(order)?;
1020 let boundary = Order::new(&order)?;
1021
1022 commit(
1023 events,
1024 boundary,
1025 Retry::attempts(ATTEMPTS.try_into()?),
1026 |state: &Order| {
1027 let Some((sku, quantity)) = state.held.clone() else {
1028 return Err(Refusal::NotPlaced {
1029 order: order.id.clone(),
1030 });
1031 };
1032 if state.dispatched {
1033 return Err(Refusal::AlreadyDispatched {
1034 order: order.id.clone(),
1035 });
1036 }
1037 if state.cancelled {
1038 return Err(Refusal::AlreadyCancelled {
1039 order: order.id.clone(),
1040 });
1041 }
1042 Ok(vec![Fulfilment::OrderCancelled {
1043 order: order.clone(),
1044 sku,
1045 quantity,
1046 }])
1047 },
1048 )
1049 .await
1050 .map(|_| ())
1051 .map_err(rejected)
1052}
1053
1054// ---------------------------------------------------------------------------
1055// The four views
1056// ---------------------------------------------------------------------------
1057
1058/// Units on the shelf, per SKU.
1059///
1060/// The fold carries **no state of its own** and writes a *delta* against the
1061/// row. That is deliberate rather than minimal: a runner resumes from its
1062/// checkpoint, so a projection holding a running total in memory would start
1063/// from zero and write absolute numbers wrong by everything it did not replay.
1064/// It is also what makes the chunk-size invariance above true.
1065#[derive(Debug)]
1066struct StockOnHand {
1067 /// Which read model this is, within the projection store.
1068 id: ProjectionId,
1069 /// Every event, so the tags constrain nothing.
1070 scope: Tags,
1071}
1072
1073/// The stock view's projection id. A free `const`, so the compiler validates
1074/// it: an invalid id here is a build error, not a crash at start-up.
1075const STOCK_ON_HAND: ProjectionId = ProjectionId::from_static("stock_on_hand");
1076
1077impl StockOnHand {
1078 /// The view over every SKU.
1079 fn new() -> Self {
1080 Self {
1081 id: STOCK_ON_HAND,
1082 scope: Tags::empty(),
1083 }
1084 }
1085}
1086
1087impl Projection for StockOnHand {
1088 type Event = Fulfilment;
1089 type Store = SqliteProjectionStore;
1090 type Error = SqliteProjectionStoreError;
1091
1092 fn id(&self) -> &ProjectionId {
1093 &self.id
1094 }
1095
1096 fn scope(&self) -> &Tags {
1097 &self.scope
1098 }
1099
1100 async fn apply(
1101 &mut self,
1102 event: Delivered<Fulfilment>,
1103 batch: &mut SqliteBatch,
1104 ) -> Result<(), SqliteProjectionStoreError> {
1105 let (sku, delta) = match event.into_event() {
1106 Fulfilment::StockReceived { sku, quantity }
1107 | Fulfilment::OrderCancelled { sku, quantity, .. } => (sku, i64::from(quantity)),
1108 Fulfilment::OrderPlaced { sku, quantity, .. } => (sku, -i64::from(quantity)),
1109 Fulfilment::OrderDispatched { sku, .. } => (sku, 0),
1110 };
1111
1112 batch.push(
1113 "INSERT INTO stock_on_hand (sku, on_hand) VALUES (?1, ?2) \
1114 ON CONFLICT(sku) \
1115 DO UPDATE SET on_hand = stock_on_hand.on_hand + excluded.on_hand",
1116 [Value::Text(sku.into()), Value::Integer(delta)],
1117 );
1118
1119 Ok(())
1120 }
1121}
1122
1123/// Where each order has got to.
1124///
1125/// Unlike the shelf, this view writes an *absolute* value: the status is the
1126/// last one seen, not an accumulation, so replaying it from any checkpoint
1127/// lands on the same answer.
1128#[derive(Debug)]
1129struct OrderStatus {
1130 /// Which read model this is, within the projection store.
1131 id: ProjectionId,
1132 /// Every event, so the tags constrain nothing.
1133 scope: Tags,
1134}
1135
1136/// The order view's projection id.
1137const ORDER_STATUS: ProjectionId = ProjectionId::from_static("order_status");
1138
1139impl OrderStatus {
1140 /// The view over every order.
1141 fn new() -> Self {
1142 Self {
1143 id: ORDER_STATUS,
1144 scope: Tags::empty(),
1145 }
1146 }
1147}
1148
1149impl Projection for OrderStatus {
1150 type Event = Fulfilment;
1151 type Store = SqliteProjectionStore;
1152 type Error = SqliteProjectionStoreError;
1153
1154 fn id(&self) -> &ProjectionId {
1155 &self.id
1156 }
1157
1158 fn scope(&self) -> &Tags {
1159 &self.scope
1160 }
1161
1162 async fn apply(
1163 &mut self,
1164 event: Delivered<Fulfilment>,
1165 batch: &mut SqliteBatch,
1166 ) -> Result<(), SqliteProjectionStoreError> {
1167 let (order, status, sku, quantity) = match event.into_event() {
1168 Fulfilment::OrderPlaced {
1169 order,
1170 sku,
1171 quantity,
1172 } => (order, "placed", sku, quantity),
1173 Fulfilment::OrderDispatched {
1174 order,
1175 sku,
1176 quantity,
1177 ..
1178 } => (order, "dispatched", sku, quantity),
1179 Fulfilment::OrderCancelled {
1180 order,
1181 sku,
1182 quantity,
1183 } => (order, "cancelled", sku, quantity),
1184 // Nominated and ignored. The derived query is the event set crossed
1185 // with the scope, and this view's scope is empty, so a stock
1186 // receipt arrives here whether it is wanted or not — the checkpoint
1187 // still advances past it, which is what "the position considered"
1188 // means.
1189 Fulfilment::StockReceived { .. } => return Ok(()),
1190 };
1191
1192 batch.push(
1193 "INSERT INTO order_status (order_ref, status, sku, quantity) \
1194 VALUES (?1, ?2, ?3, ?4) \
1195 ON CONFLICT(order_ref) DO UPDATE SET status = excluded.status",
1196 [
1197 Value::Text(order.into()),
1198 Value::Text(status.to_owned()),
1199 Value::Text(sku.into()),
1200 Value::Integer(i64::from(quantity)),
1201 ],
1202 );
1203
1204 Ok(())
1205 }
1206}
1207
1208/// The upsert into the first table, and into the second.
1209///
1210/// Two constants rather than one `format!` over a table name, and the reason is
1211/// [`SqliteBatch::push`], which takes `&'static str`. Interpolating a
1212/// table name here was *safe* — it was a `&'static str` chosen by one of the
1213/// three constructors below and could never hold user input — but that safety
1214/// lived in a comment, and a comment is what the signature stopped accepting.
1215/// The two statements differ in one identifier, which is exactly the amount of
1216/// duplication that buys the property.
1217///
1218/// [`push_raw_sql`](SqliteBatch::push_raw_sql) is the escape hatch for
1219/// a statement whose *shape* is decided at run time — an `IN (…)` list sized by
1220/// how many keys are being written. This one's shape is not: only which of two
1221/// fixed statements runs is decided at run time, and that is a choice between
1222/// constants rather than a statement built from a value.
1223const UPSERT_DAILY_DISPATCHES: &str = "INSERT INTO daily_dispatches (day, dispatched) VALUES (?1, ?2) \
1224 ON CONFLICT(day) \
1225 DO UPDATE SET dispatched = daily_dispatches.dispatched + excluded.dispatched";
1226
1227/// The same statement against the backfill's own table. See
1228/// [`UPSERT_DAILY_DISPATCHES`] for why this is a second constant.
1229const UPSERT_DAILY_DISPATCHES_V2: &str = "INSERT INTO daily_dispatches_v2 (day, dispatched) VALUES (?1, ?2) \
1230 ON CONFLICT(day) \
1231 DO UPDATE SET dispatched = daily_dispatches_v2.dispatched + excluded.dispatched";
1232
1233/// The blue/green swap, run as the retiring view's reset batch.
1234///
1235/// No `DELETE` first: the drop takes blue's rows with it. A delete naming
1236/// `daily_dispatches` would be a hazard rather than a redundancy anywhere after
1237/// the rename, because the name by then belongs to green.
1238const PROMOTION: [&str; 2] = [
1239 "DROP TABLE daily_dispatches",
1240 "ALTER TABLE daily_dispatches_v2 RENAME TO daily_dispatches",
1241];
1242
1243/// The same swap with the new table's name mistyped, so it fails *after* the
1244/// drop has run — the one point at which a promotion split across two
1245/// transactions would already have committed blue's retirement.
1246const MISTYPED_PROMOTION: [&str; 2] = [
1247 "DROP TABLE daily_dispatches",
1248 "ALTER TABLE daily_dispatch_v2 RENAME TO daily_dispatches",
1249];
1250
1251/// How much went out each day, counted one of two ways.
1252///
1253/// One type with two configurations rather than two types, because the blue
1254/// and green halves of a rebuild differ in exactly the way a real one does:
1255/// the fold changed its mind about what it was counting, and everything else
1256/// stayed put.
1257#[derive(Debug)]
1258struct DailyDispatches {
1259 /// Which read model this is. **It does not change when the table is
1260 /// promoted** — the checkpoint is keyed by this name and the derived
1261 /// query, and renaming it to match the promoted table would discard the
1262 /// resume point.
1263 id: ProjectionId,
1264 /// Every event, so the tags constrain nothing.
1265 scope: Tags,
1266 /// The upsert this instance issues, and with it the table it writes into.
1267 upsert: &'static str,
1268 /// What one dispatch adds to its day.
1269 counting: Counting,
1270}
1271
1272/// What one dispatch adds to its day's total.
1273#[derive(Debug, Clone, Copy)]
1274enum Counting {
1275 /// One per order that went out.
1276 Orders,
1277 /// One per unit that went out.
1278 Units,
1279}
1280
1281/// The first attempt's projection id.
1282const DAILY_DISPATCHES: ProjectionId = ProjectionId::from_static("daily_dispatches");
1283
1284/// The replacement's projection id, kept across the promotion: the checkpoint
1285/// travels with the id, not with the table.
1286const DAILY_DISPATCHES_V2: ProjectionId = ProjectionId::from_static("daily_dispatches_v2");
1287
1288impl DailyDispatches {
1289 /// The first attempt: one per order.
1290 fn counting_orders() -> Self {
1291 Self {
1292 id: DAILY_DISPATCHES,
1293 scope: Tags::empty(),
1294 upsert: UPSERT_DAILY_DISPATCHES,
1295 counting: Counting::Orders,
1296 }
1297 }
1298
1299 /// The replacement, backfilled beside the first into its own table.
1300 fn counting_units() -> Self {
1301 Self {
1302 id: DAILY_DISPATCHES_V2,
1303 scope: Tags::empty(),
1304 upsert: UPSERT_DAILY_DISPATCHES_V2,
1305 counting: Counting::Units,
1306 }
1307 }
1308
1309 /// The replacement after the swap: the same id, the promoted table.
1310 fn promoted() -> Self {
1311 Self {
1312 id: DAILY_DISPATCHES_V2,
1313 scope: Tags::empty(),
1314 upsert: UPSERT_DAILY_DISPATCHES,
1315 counting: Counting::Units,
1316 }
1317 }
1318}
1319
1320impl Projection for DailyDispatches {
1321 type Event = Fulfilment;
1322 type Store = SqliteProjectionStore;
1323 type Error = SqliteProjectionStoreError;
1324
1325 fn id(&self) -> &ProjectionId {
1326 &self.id
1327 }
1328
1329 fn scope(&self) -> &Tags {
1330 &self.scope
1331 }
1332
1333 async fn apply(
1334 &mut self,
1335 event: Delivered<Fulfilment>,
1336 batch: &mut SqliteBatch,
1337 ) -> Result<(), SqliteProjectionStoreError> {
1338 let (day, delta) = match event.into_event() {
1339 Fulfilment::OrderDispatched { day, quantity, .. } => match self.counting {
1340 Counting::Orders => (day, 1),
1341 Counting::Units => (day, i64::from(quantity)),
1342 },
1343 // Nominated and ignored, for the reason `order_status` gives.
1344 Fulfilment::StockReceived { .. }
1345 | Fulfilment::OrderPlaced { .. }
1346 | Fulfilment::OrderCancelled { .. } => return Ok(()),
1347 };
1348
1349 // Which of the two constants runs is the whole of what this instance's
1350 // configuration decides. SQLite binds values and not identifiers, so a
1351 // table name can only ever reach a statement by being part of its text —
1352 // which is why the statement, and not the name, is the thing chosen.
1353 batch.push(self.upsert, [Value::Text(day), Value::Integer(delta)]);
1354
1355 Ok(())
1356 }
1357}
1358
1359/// The view that was written against a field the log does not carry.
1360///
1361/// It compiles, its query is well formed, and it nominates exactly the events
1362/// it means to. The disagreement is in the payload, and the payload is the one
1363/// thing no signature describes.
1364#[derive(Debug)]
1365struct Couriered {
1366 /// Which read model this is, within the projection store.
1367 id: ProjectionId,
1368 /// Every dispatch, so the tags constrain nothing.
1369 scope: Tags,
1370}
1371
1372/// The courier view's projection id.
1373const COURIERED: ProjectionId = ProjectionId::from_static("couriered");
1374
1375impl Couriered {
1376 /// The view over every dispatch.
1377 fn new() -> Self {
1378 Self {
1379 id: COURIERED,
1380 scope: Tags::empty(),
1381 }
1382 }
1383}
1384
1385impl Projection for Couriered {
1386 type Event = Handover;
1387 type Store = SqliteProjectionStore;
1388 type Error = SqliteProjectionStoreError;
1389
1390 fn id(&self) -> &ProjectionId {
1391 &self.id
1392 }
1393
1394 fn scope(&self) -> &Tags {
1395 &self.scope
1396 }
1397
1398 async fn apply(
1399 &mut self,
1400 event: Delivered<Handover>,
1401 batch: &mut SqliteBatch,
1402 ) -> Result<(), SqliteProjectionStoreError> {
1403 let Handover::OrderDispatched { order, courier } = event.into_event();
1404
1405 batch.push(
1406 "INSERT INTO couriered (order_ref, courier) VALUES (?1, ?2) \
1407 ON CONFLICT(order_ref) DO UPDATE SET courier = excluded.courier",
1408 [Value::Text(order.into()), Value::Text(courier)],
1409 );
1410
1411 Ok(())
1412 }
1413}
1414
1415// ---------------------------------------------------------------------------
1416// Driving views, and reporting on them
1417// ---------------------------------------------------------------------------
1418
1419/// Brings one view up to date and reports how much it applied.
1420///
1421/// Generic over the projection rather than written four times, and generic is
1422/// as far as it can go: `Projection` has an associated event type and an
1423/// associated store, so there is no `dyn Projection` to put in a registry and
1424/// no loop to write. A heterogeneous set of views is a sequence of calls, and
1425/// that is a property of the port, not a shortcoming of this file.
1426///
1427/// `P::Error: Send + Sync` because `anyhow` asks it of every error `?` moves
1428/// in, and a projection's own error carries no such bound by design: a
1429/// `!Send` application is allowed one.
1430async fn drive<P>(
1431 events: &SqliteEventStore,
1432 models: &SqliteProjectionStore,
1433 projection: &mut P,
1434 chunk: usize,
1435) -> Result<usize>
1436where
1437 P: Projection<Store = SqliteProjectionStore>,
1438 P::Error: Send + Sync,
1439{
1440 let chunk = Chunk::of(chunk.try_into()?);
1441 let progress = run_projection(events, models, projection, &Json, chunk).await?;
1442 Ok(progress.applied)
1443}
1444
1445/// Runs the broken view, which is expected to fail, and says where it stopped.
1446///
1447/// Returns the position and the decoder's own message. A run that *succeeded*
1448/// would be the interesting failure — it would mean the log had grown a
1449/// `courier` field nobody in this file wrote — so it is refused out loud
1450/// rather than reported as a pass.
1451async fn poison(
1452 events: &SqliteEventStore,
1453 models: &SqliteProjectionStore,
1454 projection: &mut Couriered,
1455) -> Result<(u64, String)> {
1456 let chunk = Chunk::of(CHUNK.try_into()?);
1457 match run_projection(events, models, projection, &Json, chunk).await {
1458 Ok(progress) => bail!(
1459 "the couriered view decoded {} event(s) it could not have",
1460 progress.applied
1461 ),
1462 Err(ProjectionError::Decode {
1463 position, source, ..
1464 }) => Ok((position.get(), error_chain(&source))),
1465 // `ProjectionError` is `#[non_exhaustive]`. A read failure or a commit
1466 // failure here would be a different defect wearing this one's clothes.
1467 Err(other) => bail!("expected a decode failure, got: {other}"),
1468 }
1469}
1470
1471/// Renders an error and everything under it, joined by `: `.
1472///
1473/// `CodecError`'s own `Display` says the payload could not be decoded, which
1474/// is a category. The value a reader needs — *which field was missing* — is
1475/// one link down the source chain, and a message that stops at the top of that
1476/// chain is the same defect `rejected` exists to avoid one layer up.
1477fn error_chain(error: &dyn core::error::Error) -> String {
1478 let mut rendered = error.to_string();
1479 let mut source = error.source();
1480
1481 while let Some(cause) = source {
1482 rendered.push_str(": ");
1483 rendered.push_str(&cause.to_string());
1484 source = cause.source();
1485 }
1486
1487 rendered
1488}
1489
1490/// Clears a view's rows and its checkpoint as one unit of work.
1491///
1492/// The statements are the *application's*, because the read model is: the port
1493/// takes a batch and commits it alongside the checkpoint reset, and it has no
1494/// idea which tables this program invented. Used for the two things reset is
1495/// actually for — retiring a view, and preparing a rebuild — and a retirement
1496/// may carry a blue/green swap, which is what puts the swap in the same
1497/// transaction as the checkpoint it retires.
1498///
1499/// A slice of statements rather than one string of several: the batch runs one
1500/// statement per `push`, and rusqlite refuses a push that holds two with
1501/// `MultipleStatement` — at commit, after the batch has left this function.
1502///
1503/// It takes the projection rather than an id, so the reset names the id the
1504/// runner commits under, `checkpoint_id`. A reset of `projection.id()`, the
1505/// bare name, clears a row the runner never wrote and leaves its checkpoint
1506/// standing.
1507async fn retire<P: Projection>(
1508 models: &SqliteProjectionStore,
1509 projection: &P,
1510 statements: &[&'static str],
1511) -> Result<()> {
1512 let key = checkpoint_id(projection)?;
1513 let mut batch = models.begin().await?;
1514 for statement in statements {
1515 batch.push(statement, []);
1516 }
1517 models.reset(batch, &key).await?;
1518 Ok(())
1519}
1520
1521/// Prints where a view has got to, under its name.
1522///
1523/// Read through `checkpoint_id` for the reason `retire` resets through it:
1524/// the bare name reads `never run` whatever the runner did.
1525async fn print_checkpoint<P: Projection>(
1526 models: &SqliteProjectionStore,
1527 projection: &P,
1528) -> Result<()> {
1529 let name = projection.id();
1530 let checkpoint = render_checkpoint(models.checkpoint(&checkpoint_id(projection)?).await?);
1531 writeln!(io::stdout().lock(), " {name} is {checkpoint}")?;
1532 Ok(())
1533}
1534
1535/// Renders a checkpoint as the transcript prints it.
1536fn render_checkpoint(checkpoint: Checkpoint) -> String {
1537 match checkpoint {
1538 Checkpoint::NeverRun => "never run".to_owned(),
1539 Checkpoint::Live { through } => format!("live through {through}"),
1540 Checkpoint::Rebuilding { through } => format!("rebuilding through {through}"),
1541 // `Checkpoint` is `#[non_exhaustive]`, so the wildcard is required. It
1542 // is not laziness: a fourth state added upstream must not silently
1543 // render as one of these three.
1544 other => format!("{other:?}"),
1545 }
1546}
1547
1548// ---------------------------------------------------------------------------
1549// Reading what the views wrote
1550// ---------------------------------------------------------------------------
1551
1552/// Prints a read-model query's rows, three spaces in.
1553fn print_table(app: &Connection, sql: &str) -> Result<()> {
1554 let rows = render_table(app, sql)?;
1555 write!(io::stdout().lock(), "{rows}")?;
1556 Ok(())
1557}
1558
1559/// Renders a read-model query's rows, so two of them can be compared.
1560///
1561/// Every column comes back as a `rusqlite::types::Value` rather than as a
1562/// typed `get`, because this one function serves five tables with different
1563/// column types and a typed read would need one function per table.
1564fn render_table(app: &Connection, sql: &str) -> Result<String> {
1565 let mut statement = app.prepare(sql)?;
1566 let columns = statement.column_count();
1567 let mut rows = statement.query([])?;
1568 let mut rendered = String::new();
1569
1570 while let Some(row) = rows.next()? {
1571 let mut cells = Vec::with_capacity(columns);
1572 for index in 0..columns {
1573 cells.push(render_cell(&row.get::<_, Value>(index)?));
1574 }
1575 rendered.push_str(" ");
1576 rendered.push_str(&cells.join(" "));
1577 rendered.push('\n');
1578 }
1579
1580 Ok(rendered)
1581}
1582
1583/// Renders one cell of a read-model row.
1584fn render_cell(value: &Value) -> String {
1585 match value {
1586 Value::Null => "NULL".to_owned(),
1587 Value::Integer(number) => format!("{number}"),
1588 Value::Real(number) => format!("{number}"),
1589 Value::Text(text) => text.clone(),
1590 Value::Blob(bytes) => format!("<{} bytes>", bytes.len()),
1591 }
1592}
1593
1594/// Prints every event in the store, in the order the store assigned.
1595async fn print_log(events: &SqliteEventStore) -> Result<()> {
1596 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
1597
1598 for event in log {
1599 writeln!(
1600 io::stdout().lock(),
1601 " {:>3} {:<16} {:?}",
1602 event.position.get(),
1603 event.event_type().as_str(),
1604 event.tags()
1605 )?;
1606 }
1607
1608 Ok(())
1609}
1610
1611// ---------------------------------------------------------------------------
1612// The file this run owns
1613// ---------------------------------------------------------------------------
1614
1615/// Where this run's database lives.
1616///
1617/// Under the process id, so a `cargo run` and the test that spawns the binary
1618/// never meet on one file.
1619fn database_path() -> PathBuf {
1620 std::env::temp_dir().join(format!("happenstance-rebuilding-{}.db", std::process::id()))
1621}
1622
1623/// Removes the database and the two files WAL mode keeps beside it.
1624///
1625/// Deleting only the `.db` and leaving `-wal` behind is how a "fresh" run
1626/// starts on the tail of the last one.
1627fn remove_database(path: &Path) {
1628 for suffix in ["", "-wal", "-shm"] {
1629 let mut name = path.as_os_str().to_owned();
1630 name.push(suffix);
1631 drop(std::fs::remove_file(PathBuf::from(name)));
1632 }
1633}
1634
1635/// Renders a command failure as the message the transcript prints.
1636///
1637/// `CommandError::Refused` carries the handler's *own* refusal, and that is
1638/// what a reader must see: `CommandError`'s own `Display` says "the decision
1639/// refused", which is a category rather than a value.
1640fn rejected(err: CommandError<SqliteEventStoreError, Refusal>) -> anyhow::Error {
1641 match err {
1642 CommandError::Refused(refusal) => refusal.into(),
1643 other => other.into(),
1644 }
1645}