Skip to main content

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}