transfers_on_sqlite/main.rs
1//! A consuming application, on a real database.
2//!
3//! `course-subscriptions` is the canonical DCB example and it runs against
4//! `MemoryEventStore`. That proves the *semantics*. It cannot prove the thing
5//! an application actually needs, because an in-memory store has no disk to
6//! survive: that the typed layer and `happenstance-sqlite` compose at all, and
7//! that what they write is still there afterwards.
8//!
9//! Until this package existed, **nothing in the workspace compiled the typed
10//! layer against a durable adapter.** `happenstance-sqlite` depends only on
11//! `happenstance-core` and its tests drive the conformance suite directly; the
12//! worked example depends only on `happenstance` and runs in memory. The two
13//! halves a consumer puts together were each tested alone, and the seam between
14//! them was tested by nobody. This program is that seam, exercised.
15//!
16//! Run with `cargo run -p transfers-on-sqlite`.
17//!
18//! # What this proves that the memory store cannot
19//!
20//! 1. **`commit` accepts a `SqliteEventStore`.** The typed command loop is
21//! generic over `EventStore`; the adapter implements `SendEventStore` and
22//! reaches the weaker bound through `trait_variant`'s blanket impl. That is
23//! a sentence the type checker had never been asked to agree with.
24//! 2. **`run_projection` drives a `SqliteProjectionStore`,** into a read-model
25//! table this application owns, in the same file as the event log.
26//! 3. **Everything survives the handles being dropped.** Halfway through, every
27//! store, connection and folded value this run built goes out of scope. What
28//! is read afterwards comes off disk.
29//! 4. **The checkpoint survives with it.** Re-running the projection against
30//! the reopened file applies *zero* events — the resume point is durable, so
31//! a restarted application does not replay its whole log.
32//!
33//! # What the reopen does not prove, stated so nobody reads more into it
34//!
35//! It is **one process**. Every handle is dropped and every connection closed,
36//! and what is read back afterwards is read through fresh connections onto the
37//! file — which is a real durability claim, because SQLite keeps no cache
38//! across a closed connection. It is not a claim about surviving a *crash*, a
39//! power loss, or an `fsync` policy. Those belong to the conformance suite's
40//! reopen rule and to the adapter's own durability verdicts, which own the
41//! fault injection this program has none of.
42//!
43//! # The domain, and why it is not the worked example's
44//!
45//! A transfer moves money between two accounts. It is the smallest decision
46//! that genuinely spans two entities: the funds check belongs to the payer, the
47//! credit belongs to the payee, and the two events must land together or not at
48//! all. So the boundary is a tuple of two `Balance` models — one per account —
49//! composed into one query and checked by one append condition, and the append
50//! carries two events.
51//!
52//! That is deliberately *not* a second copy of the course-subscriptions domain.
53//! Copying it would have duplicated four hundred lines to change one import,
54//! and `examples/course-subscriptions/tests/runs.rs` reads that file with
55//! `include_str!` to assert how it is written — a shared domain crate would
56//! have to move it out from under those assertions. A different domain of the
57//! same shape costs less and says more.
58
59#![allow(clippy::print_stdout, reason = "the transcript is the point")]
60
61use std::num::NonZeroU32;
62use std::path::{Path, PathBuf};
63
64use anyhow::{Result, bail};
65use happenstance::bytes::Bytes;
66use happenstance::{
67 Boundary, Chunk, Codec, CodecError, CommandError, DecisionModel, Delivered, DomainEvent,
68 EventStore, EventType, InvalidTag, Json, Projection, ProjectionId, Query, ReadOptions, Retry,
69 Tag, Tags, collect, commit, read_decision_model, run_projection,
70};
71use happenstance_sqlite::connection::open_configured;
72use happenstance_sqlite::event_store::{SqliteEventStore, SqliteEventStoreError};
73use happenstance_sqlite::projection_store::{
74 SqliteBatch, SqliteProjectionStore, SqliteProjectionStoreError,
75};
76use rusqlite::Connection;
77use rusqlite::types::Value;
78use serde::{Deserialize, Serialize};
79
80/// How many times a command may be attempted before it gives up.
81///
82/// Spelled at every call site for the reason `course-subscriptions` gives: a
83/// loop whose only exit is success is a hang with better manners. This run is
84/// single-writer, so the bound is never spent. Built at compile time, the
85/// same way: `attempts` is `const fn`.
86const ATTEMPTS: Retry = Retry::attempts(NonZeroU32::new(3).unwrap());
87
88/// How many events one projection chunk commits at a time.
89///
90/// Small enough that the first run commits more than once, which is the only
91/// way a checkpoint's *intermediate* positions are ever written.
92const CHUNK: usize = 2;
93
94/// The read model this application owns.
95///
96/// It is the application's table, not the adapter's: `SqliteProjectionStore`
97/// migrates `projection_checkpoint` and `projection_meta` and stops there. A
98/// projection store that invented your read model's schema would be a framework
99/// rather than a port.
100const READ_MODEL_DDL: &str = "
101CREATE TABLE IF NOT EXISTS account_balance (
102 account TEXT PRIMARY KEY,
103 balance INTEGER NOT NULL
104) STRICT;
105";
106
107#[tokio::main(flavor = "current_thread")]
108async fn main() -> Result<()> {
109 let path = database_path();
110 remove_database(&path);
111
112 println!("== the database this run writes to ==");
113 println!(" {}", path.display());
114
115 before_the_reopen(&path).await?;
116 after_the_reopen(&path).await?;
117
118 remove_database(&path);
119 Ok(())
120}
121
122/// Everything before the reopen, inside one scope.
123///
124/// The scope is load-bearing. Every store, connection and decision model this
125/// function builds is dropped when it returns, so nothing the second half reads
126/// can have come from a value this one was still holding.
127async fn before_the_reopen(path: &Path) -> Result<()> {
128 let events = SqliteEventStore::open(path)?;
129 let models = SqliteProjectionStore::open(path)?;
130 let app = open_configured(path)?;
131 app.execute_batch(READ_MODEL_DDL)?;
132
133 println!("\n== opening two accounts ==");
134 open_account(&events, "a1").await?;
135 open_account(&events, "a2").await?;
136 println!(" a1 and a2 opened");
137
138 println!("\n== depositing 100 into a1 ==");
139 deposit(&events, "a1", 100).await?;
140 println!(" deposited");
141
142 println!("\n== transferring 40 from a1 to a2 ==");
143 transfer(&events, "a1", "a2", 40).await?;
144 println!(" transferred: one append, two events, both accounts checked");
145
146 println!("\n== transferring 500 from a1 to a2 ==");
147 match transfer(&events, "a1", "a2", 500).await {
148 Ok(()) => bail!("an overdrawn transfer should have been rejected"),
149 Err(err) => println!(" rejected: {err}"),
150 }
151
152 println!("\n== projecting balances into the same file ==");
153 let mut balances = Balances::new();
154 let chunk = Chunk::of(CHUNK.try_into()?);
155 let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
156 println!(" applied {} event(s)", done.applied);
157 print_read_model(&app)?;
158
159 Ok(())
160}
161
162/// Everything after the reopen, against the same file.
163///
164/// Nothing is carried in from above but the path.
165async fn after_the_reopen(path: &Path) -> Result<()> {
166 println!("\n== everything above is dropped; reopening the same file ==");
167 let events = SqliteEventStore::open(path)?;
168 let models = SqliteProjectionStore::open(path)?;
169 let app = open_configured(path)?;
170 println!(" reopened");
171
172 println!("\n== the read model, straight off disk ==");
173 print_read_model(&app)?;
174
175 println!("\n== the same balances, folded again from the event log ==");
176 for account in ["a1", "a2"] {
177 let balance = fold_balance(&events, account).await?;
178 println!(" {account}: {}", balance.held);
179 }
180
181 println!("\n== the checkpoint survived too ==");
182 let mut balances = Balances::new();
183 let chunk = Chunk::of(CHUNK.try_into()?);
184 let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
185 println!(
186 " re-running the projection applied {} event(s) — the log is not replayed",
187 done.applied
188 );
189
190 println!("\n== the reopened store is live, not merely readable ==");
191 transfer(&events, "a2", "a1", 15).await?;
192 let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
193 println!(
194 " transferred 15 back, and the projection applied {} event(s)",
195 done.applied
196 );
197 print_read_model(&app)?;
198
199 println!("\n== final log ==");
200 print_log(&events).await?;
201
202 Ok(())
203}
204
205// ---------------------------------------------------------------------------
206// Identity, validated once at the edge
207// ---------------------------------------------------------------------------
208
209/// An account identifier, validated once into the tag its events carry.
210///
211/// The same resolution `course-subscriptions` reaches and for the same reason:
212/// `DomainEvent::tags` is infallible and `Tag::key_value` can refuse, so a
213/// domain type whose tags come from runtime values holds the validated form
214/// rather than rebuilding it on every call.
215#[derive(Debug, Clone, Serialize, Deserialize)]
216#[serde(try_from = "String", into = "String")]
217struct AccountId {
218 id: String,
219 tag: Tag,
220}
221
222impl AccountId {
223 /// Validates `id` into the tag every event for this account is written with.
224 fn new(id: &str) -> Result<Self, InvalidTag> {
225 Ok(Self {
226 id: id.to_owned(),
227 tag: Tag::key_value("account", id)?,
228 })
229 }
230
231 /// The identifier as the application wrote it.
232 fn as_str(&self) -> &str {
233 &self.id
234 }
235}
236
237impl TryFrom<String> for AccountId {
238 type Error = InvalidTag;
239
240 fn try_from(id: String) -> Result<Self, InvalidTag> {
241 Self::new(&id)
242 }
243}
244
245impl From<AccountId> for String {
246 fn from(account: AccountId) -> Self {
247 account.id
248 }
249}
250
251// ---------------------------------------------------------------------------
252// The domain
253// ---------------------------------------------------------------------------
254
255/// Everything that can happen to an account.
256///
257/// One enum, so a query and a fold cannot name different sets. A fourth variant
258/// is a compile error in every fold below that has not been taught it — there
259/// is no `_ =>` arm anywhere in this file, and that absence is the guarantee.
260#[derive(Debug, Serialize, Deserialize)]
261enum Ledger {
262 /// An account exists and can hold money.
263 AccountOpened {
264 /// The account now open.
265 account: AccountId,
266 },
267 /// Money arrived.
268 Deposited {
269 /// The account credited.
270 account: AccountId,
271 /// How much, in whole units.
272 amount: u32,
273 },
274 /// Money left.
275 Withdrawn {
276 /// The account debited.
277 account: AccountId,
278 /// How much, in whole units.
279 amount: u32,
280 },
281}
282
283const ACCOUNT_OPENED: EventType = EventType::from_static("AccountOpened");
284const DEPOSITED: EventType = EventType::from_static("Deposited");
285const WITHDRAWN: EventType = EventType::from_static("Withdrawn");
286
287impl DomainEvent for Ledger {
288 const EVENT_TYPES: &'static [EventType] = &[ACCOUNT_OPENED, DEPOSITED, WITHDRAWN];
289
290 fn event_type(&self) -> EventType {
291 match self {
292 Self::AccountOpened { .. } => ACCOUNT_OPENED,
293 Self::Deposited { .. } => DEPOSITED,
294 Self::Withdrawn { .. } => WITHDRAWN,
295 }
296 }
297
298 fn tags(&self) -> Tags {
299 match self {
300 Self::AccountOpened { account }
301 | Self::Deposited { account, .. }
302 | Self::Withdrawn { account, .. } => [account.tag.clone()].into_iter().collect(),
303 }
304 }
305
306 fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
307 codec.encode(self)
308 }
309
310 fn decode<C: Codec>(
311 codec: &C,
312 _event_type: &EventType,
313 data: &Bytes,
314 ) -> Result<Self, CodecError> {
315 codec.decode(data)
316 }
317}
318
319/// Why a decision refused.
320///
321/// Every variant carries the value the transcript prints — `a1 holds 60, needs
322/// 500` and never `insufficient funds` — so a reader can act on the refusal
323/// where it is printed.
324#[derive(Debug, thiserror::Error)]
325enum Refusal {
326 /// An account cannot be opened twice.
327 #[error("account {account} is already open")]
328 AlreadyOpen {
329 /// The account that already exists.
330 account: String,
331 },
332 /// Money cannot move through an account nobody opened.
333 #[error("account {account} does not exist")]
334 NotOpen {
335 /// The account nobody opened.
336 account: String,
337 },
338 /// An account may not go overdrawn.
339 #[error("account {account} holds {held}, needs {needed}")]
340 Overdrawn {
341 /// The account that cannot cover the debit.
342 account: String,
343 /// What it currently holds.
344 held: u64,
345 /// What the transfer asked for.
346 needed: u32,
347 },
348 /// An account cannot pay itself.
349 #[error("account {account} cannot transfer to itself")]
350 SelfTransfer {
351 /// The account on both ends.
352 account: String,
353 },
354}
355
356// ---------------------------------------------------------------------------
357// The decision model
358// ---------------------------------------------------------------------------
359
360/// One account: whether it exists, and what it holds.
361///
362/// The whole consistency concern for a deposit, and *half* of one for a
363/// transfer. That it is the same type in both places is the point — a decision
364/// model is a value, not a per-handler blob.
365#[derive(Debug, Clone)]
366struct Balance {
367 scope: Tags,
368 opened: bool,
369 held: u64,
370}
371
372impl Balance {
373 /// Validates the scope once, here, where the caller already writes a `?`.
374 fn new(account: &AccountId) -> Result<Self, InvalidTag> {
375 Ok(Self {
376 scope: Tags::from_pairs([("account", account.as_str())])?,
377 opened: false,
378 held: 0,
379 })
380 }
381}
382
383impl DecisionModel for Balance {
384 type Event = Ledger;
385
386 fn scope(&self) -> &Tags {
387 &self.scope
388 }
389
390 fn apply(&mut self, event: Self::Event) {
391 match event {
392 Ledger::AccountOpened { .. } => self.opened = true,
393 Ledger::Deposited { amount, .. } => {
394 self.held = self.held.saturating_add(u64::from(amount));
395 }
396 Ledger::Withdrawn { amount, .. } => {
397 self.held = self.held.saturating_sub(u64::from(amount));
398 }
399 }
400 }
401}
402
403// ---------------------------------------------------------------------------
404// The command handlers
405// ---------------------------------------------------------------------------
406
407/// Opens an account, rejecting a second opening of the same one.
408async fn open_account(events: &SqliteEventStore, account: &str) -> Result<()> {
409 let account = AccountId::new(account)?;
410 let boundary = Balance::new(&account)?;
411
412 commit(events, boundary, ATTEMPTS, |balance: &Balance| {
413 if balance.opened {
414 return Err(Refusal::AlreadyOpen {
415 account: account.id.clone(),
416 });
417 }
418 Ok(vec![Ledger::AccountOpened {
419 account: account.clone(),
420 }])
421 })
422 .await
423 .map(|_| ())
424 .map_err(rejected)
425}
426
427/// Credits an account that exists.
428async fn deposit(events: &SqliteEventStore, account: &str, amount: u32) -> Result<()> {
429 let account = AccountId::new(account)?;
430 let boundary = Balance::new(&account)?;
431
432 commit(events, boundary, ATTEMPTS, |balance: &Balance| {
433 if !balance.opened {
434 return Err(Refusal::NotOpen {
435 account: account.id.clone(),
436 });
437 }
438 Ok(vec![Ledger::Deposited {
439 account: account.clone(),
440 amount,
441 }])
442 })
443 .await
444 .map(|_| ())
445 .map_err(rejected)
446}
447
448/// Moves money between two accounts, atomically.
449///
450/// The case that motivates both DCB and composition. *Can the payer cover it*
451/// is one consistency concern; *does the payee exist* is another, on a
452/// different entity. The tuple below is both, OR'd into one query and checked
453/// by one append condition — and the two events it produces land in a single
454/// `append`, which on this adapter is a single `BEGIN IMMEDIATE` transaction. A
455/// crash between the debit and the credit is not a state this store can be
456/// found in.
457async fn transfer(events: &SqliteEventStore, from: &str, to: &str, amount: u32) -> Result<()> {
458 let from = AccountId::new(from)?;
459 let to = AccountId::new(to)?;
460
461 // Two models with the same scope would compose into a query that nominates
462 // each event twice and a fold that counts it twice. Refused here, in the
463 // domain, rather than left to produce a plausible wrong number.
464 if from.as_str() == to.as_str() {
465 return Err(Refusal::SelfTransfer {
466 account: from.id.clone(),
467 }
468 .into());
469 }
470
471 let boundary = (Balance::new(&from)?, Balance::new(&to)?);
472
473 commit(
474 events,
475 boundary,
476 ATTEMPTS,
477 |(payer, payee): &(Balance, Balance)| {
478 if !payer.opened {
479 return Err(Refusal::NotOpen {
480 account: from.id.clone(),
481 });
482 }
483 if !payee.opened {
484 return Err(Refusal::NotOpen {
485 account: to.id.clone(),
486 });
487 }
488 if payer.held < u64::from(amount) {
489 return Err(Refusal::Overdrawn {
490 account: from.id.clone(),
491 held: payer.held,
492 needed: amount,
493 });
494 }
495 Ok(vec![
496 Ledger::Withdrawn {
497 account: from.clone(),
498 amount,
499 },
500 Ledger::Deposited {
501 account: to.clone(),
502 amount,
503 },
504 ])
505 },
506 )
507 .await
508 .map(|_| ())
509 .map_err(rejected)
510}
511
512// ---------------------------------------------------------------------------
513// The projection
514// ---------------------------------------------------------------------------
515
516/// Balances, kept as a table rather than folded on every read.
517///
518/// The fold carries **no state of its own**, and that is deliberate rather than
519/// minimal. After a reopen the runner resumes from the checkpoint, so a
520/// projection holding a running total in memory would start from zero and write
521/// absolute numbers wrong by everything it did not replay. Writing a *delta*
522/// against the row makes the table authoritative and the resume correct — which
523/// is the shape a durable projection has to have, and a shape a memory store
524/// never forces anybody to discover.
525#[derive(Debug)]
526struct Balances {
527 id: ProjectionId,
528 scope: Tags,
529}
530
531/// The projection's name, validated by the compiler.
532const ACCOUNT_BALANCE: ProjectionId = ProjectionId::from_static("account_balance");
533
534impl Balances {
535 /// The projection over every account.
536 fn new() -> Self {
537 Self {
538 id: ACCOUNT_BALANCE,
539 scope: Tags::empty(),
540 }
541 }
542}
543
544impl Projection for Balances {
545 type Event = Ledger;
546 type Store = SqliteProjectionStore;
547 type Error = SqliteProjectionStoreError;
548
549 fn id(&self) -> &ProjectionId {
550 &self.id
551 }
552
553 fn scope(&self) -> &Tags {
554 &self.scope
555 }
556
557 async fn apply(
558 &mut self,
559 event: Delivered<Ledger>,
560 batch: &mut SqliteBatch,
561 ) -> Result<(), SqliteProjectionStoreError> {
562 let (account, delta) = match event.into_event() {
563 Ledger::AccountOpened { account } => (account, 0),
564 Ledger::Deposited { account, amount } => (account, i64::from(amount)),
565 Ledger::Withdrawn { account, amount } => (account, -i64::from(amount)),
566 };
567
568 batch.push(
569 "INSERT INTO account_balance (account, balance) VALUES (?1, ?2) \
570 ON CONFLICT(account) \
571 DO UPDATE SET balance = account_balance.balance + excluded.balance",
572 [Value::Text(account.into()), Value::Integer(delta)],
573 );
574
575 Ok(())
576 }
577}
578
579// ---------------------------------------------------------------------------
580// Reading, after the reopen
581// ---------------------------------------------------------------------------
582
583/// Folds one account's balance straight out of the event log.
584///
585/// The read half of the typed layer, spelled out: derive the query from the
586/// model, read what it nominates, and absorb each event through the same
587/// `Boundary` the command loop uses. It exists here to say that the read model
588/// printed beside it is a *cache* and the log is the record — the two numbers
589/// agreeing is the assertion.
590async fn fold_balance(events: &SqliteEventStore, account: &str) -> Result<Balance> {
591 let account = AccountId::new(account)?;
592 let mut balance = Balance::new(&account)?;
593
594 let query = balance.query()?;
595 let (found, _) = read_decision_model(events, &query).await?;
596 for event in &found {
597 balance.absorb(event, &Json)?;
598 }
599
600 Ok(balance)
601}
602
603/// Prints the read-model table as the application's own query sees it.
604fn print_read_model(app: &Connection) -> Result<()> {
605 let mut statement =
606 app.prepare("SELECT account, balance FROM account_balance ORDER BY account")?;
607 let rows = statement.query_map([], |row| {
608 Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
609 })?;
610
611 for row in rows {
612 let (account, balance) = row?;
613 println!(" {account}: {balance}");
614 }
615
616 Ok(())
617}
618
619/// Prints every event in the store, in the order the store assigned.
620async fn print_log(events: &SqliteEventStore) -> Result<()> {
621 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
622
623 for event in log {
624 println!(
625 " {:>3} {:<15} {:?}",
626 event.position.get(),
627 event.event_type().as_str(),
628 event.tags()
629 );
630 }
631
632 Ok(())
633}
634
635// ---------------------------------------------------------------------------
636// The file this run owns
637// ---------------------------------------------------------------------------
638
639/// Where this run's database lives.
640///
641/// Under the process id, so two concurrent runs — a `cargo run` and the test
642/// that spawns the binary — never meet on one file.
643fn database_path() -> PathBuf {
644 std::env::temp_dir().join(format!("happenstance-transfers-{}.db", std::process::id()))
645}
646
647/// Removes the database and the two files WAL mode keeps beside it.
648///
649/// Deleting only the `.db` and leaving `-wal` behind is how a "fresh" run
650/// starts on the tail of the last one.
651fn remove_database(path: &Path) {
652 for suffix in ["", "-wal", "-shm"] {
653 let mut name = path.as_os_str().to_owned();
654 name.push(suffix);
655 drop(std::fs::remove_file(PathBuf::from(name)));
656 }
657}
658
659/// Renders a command failure as the message the transcript prints.
660///
661/// `CommandError::Refused` carries the handler's *own* refusal, and that is
662/// what a reader must see: `CommandError`'s own `Display` says "the decision
663/// refused", which is a category rather than a value.
664fn rejected(err: CommandError<SqliteEventStoreError, Refusal>) -> anyhow::Error {
665 match err {
666 CommandError::Refused(refusal) => refusal.into(),
667 other => other.into(),
668 }
669}