ArchitectureKit for Rust: The Compiler Checks Your Events
A Rust program that compiles has already passed a reviewer who never gets tired. With ArchitectureKit for Rust 1.0, released on November 13th, that reviewer now checks your events too: which ones can occur, what shape their data has, and whether your code handles every one of them.
ArchitectureKit is the kit of building blocks for Domain-Driven Design, CQRS, and Event Sourcing on top of EventSourcingDB, our database built for storing events, which we introduced for Go in September. It is now one kit in two languages, open source under the MIT license, and in Rust it gains a reviewer that Go's type system cannot offer: a compiler that knows every event a book can have. Not everything that can go wrong in an event-sourced application shows up in the types, though. What the compiler cannot see is checked at runtime, by EventSourcingDB and by the kit on top of it, and between compile time and runtime, very little is left to luck.
Events the Compiler Knows#
Our example is a public library that lends books. In Event Sourcing, the library does not store the current state of a book, but every change to it as an event – acquired, borrowed, returned – and whenever it needs the current state, it rebuilds it from those events. The events of each book are filed under a subject, a path such as /books/42.
Each event is a struct whose data serde writes as JSON. Deriving Event gives it its event type, the name under which EventSourcingDB stores it, which you choose yourself, usually under a domain you own:
use architecturekit::Event;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Event)]
#[event(type = "io.eventsourcingdb.library.book-acquired")]
struct BookAcquired {
title: String,
}
#[derive(Serialize, Deserialize, Event)]
#[event(type = "io.eventsourcingdb.library.book-borrowed")]
struct BookBorrowed {
reader_id: String,
}
#[derive(Serialize, Deserialize, Event)]
#[event(type = "io.eventsourcingdb.library.book-returned")]
struct BookReturned {}
The events a book can have are listed in an enum, one variant per event type. The state of a book starts from its Default and evolves by each of its events in turn, which is all that rebuilding it means. The list of events is a type, not a convention, so evolve has to handle every variant, as long as its match names each one rather than ending in _:
use architecturekit::{Events, State};
#[derive(Events)]
enum BookEvent {
Acquired(BookAcquired),
Borrowed(BookBorrowed),
Returned(BookReturned),
}
#[derive(Clone, Default)]
struct Book {
is_acquired: bool,
is_borrowed: bool,
}
impl State for Book {
type Event = BookEvent;
fn evolve(self, event: &BookEvent) -> Self {
match event {
BookEvent::Acquired(_) => Book { is_acquired: true, ..self },
BookEvent::Borrowed(_) => Book { is_borrowed: true, ..self },
BookEvent::Returned(_) => Book { is_borrowed: false, ..self },
}
}
}
Now add an event – a book can get lost – as a variant Lost(BookLost), and forget to handle it in evolve. The program no longer builds:
error[E0004]: non-exhaustive patterns: `&BookEvent::Lost(_)` not covered
--> src/main.rs:45:11
|
45 | match event {
| ^^^^^ pattern `&BookEvent::Lost(_)` not covered
This is ordinary Rust, but it is exactly the check that event-sourced code needs most. In a language without exhaustive matching, a forgotten event type tends to fall into a default branch, and the state comes out wrong without anyone noticing. Here, it surfaces before anything runs. The opposite case, a stored event whose type the enum does not list, is caught at runtime: reading the state fails, so the state never skips an event in silence.
Schemas That Follow the Types#
The derives are a convenience, not magic. For each struct, they generate its event type and the JSON schema of its data, and for the enum, the mapping between its variants and the stored events. Two variants of the same event type do not compile.
The schemas are what EventSourcingDB checks events against. The kit's entry point is the store, which reads and writes events through EventSourcingDB's client. It takes the client, with the address and the API token of the database, and the source that every event it writes is attributed to. Registering the schemas of all book events takes one more line when the application starts:
use architecturekit::{Store, eventsourcingdb::Client};
let client = Client::new("http://localhost:3000".parse()?, "secret");
let store = Store::builder(client, "https://library.eventsourcingdb.io").build();
store.register_schemas(BookEvent::schemas()).await?;
From then on, EventSourcingDB rejects every event whose data does not match its registered schema, no matter which program wrote it. A field of a type whose schema the derive cannot work out, such as an enum of your own, needs a schema written by hand, and until it has one, the code does not compile. A recursive type compiles, but panics as soon as its schema is built. Either way, a schema is never guessed.
A registered schema cannot change, since every event already stored has to keep matching it. That is why the rules of the derive are fixed, and a type derives the same schema in every version of the kit. Change the fields of an event whose schema is registered, and registering the schemas fails when the application starts: a new shape is a new event type, with an upcaster that brings the old events up to date, as Versioning Events explains.
The type is the one source: the compiler keeps the code consistent with it, and the database makes sure every stored event matches it.
A Decision Is Just a Function#
A command describes what someone wants to do. It names the subject whose state it is decided on, and the preconditions its events are written with, which come back further below, where the compiler's view ends:
use architecturekit::{Command, Precondition, Subject};
#[derive(Clone)]
struct BorrowBook {
book: Subject,
reader_id: String,
}
impl Command for BorrowBook {
fn subject(&self) -> Subject {
self.book.clone()
}
fn preconditions(&self) -> Vec<Precondition> {
vec![Precondition::on_state_read()]
}
}
The kit reads the events of the command's subject, rebuilds the state, and hands the command and the state to the decision. It either returns the events the command causes, or refuses it with a reason. It is asynchronous, so that a decision can await something such as another state, though this one needs nothing and stays a pure function:
use architecturekit::{Decider, DomainError};
fn borrow_book() -> Decider<BorrowBook, Book, DomainError> {
Decider::new(|command: BorrowBook, book: Book| async move {
if !book.is_acquired {
return Err(DomainError::new(format!("{} does not exist", command.book)));
}
if book.is_borrowed {
return Err(DomainError::new(format!("{} is already borrowed", command.book)));
}
Ok(vec![BookEvent::Borrowed(BookBorrowed { reader_id: command.reader_id })])
})
}
There is nothing framework-like about this. It is the shape that Decide, Evolve, Repeat describes, as plain Rust, while the kit takes care of reading the events and writing the new ones. If Event Sourcing itself is new to you, our introduction to Event Sourcing explains the idea behind it from the ground up.
What the Compiler Cannot See#
Types describe what a program does, not what happens around it. Two members of the library can ask for the same book at the same moment. And reads in an event-sourced application usually come not from the events themselves but from views, read models that a projection fills from the events after they were written, which is what CQRS means in practice. So a member who looks at the catalog right after borrowing a book may get there before the view has caught up. Neither is visible to a compiler, so both are checked at runtime: the first by the database, the second by the kit, with the help of the database.
On the way in, every command writes its events together with its preconditions, and the database checks them at the moment of writing. on_state_read, as in BorrowBook above, writes only if no other event has reached the subject since its state was read: optimistic concurrency, without a lock.
Since we announced the Go edition, the kit has grown here in both languages, and every command declares at least one precondition, so that writing without a check is always a decision, never an oversight. A command that really should write without one says so with Precondition::unconditionally(). Preconditions are values that a command returns while the program runs, so it is the kit that refuses a command without one, when executing it, not the compiler.
Unlike in the Go announcement, where a command was never tried again, the store can now decide again on the new state when the check fails, though only if you build it that way, in place of the plain store above, since a retry can also hide contention:
let store = Store::builder(client, "https://library.eventsourcingdb.io")
.conflict_retries(3)
.build();
It does so only when on_state_read did not hold, where deciding again is what would have happened had the command arrived a moment later. A revision is the ID of an event, which the database counts up with every event it writes. A conflict that comes from a revision the caller handed over is never decided again, since the caller has to learn about it: a form that showed the book at revision 7 can be sent back with it, to be written only if nothing has happened to the book since. Since EventSourcingDB 1.3, the database names the precondition that did not hold, which is how the kit knows whether deciding again can help at all.
On the way out, a command answers with the revision it wrote, and a query can wait until its view has reached that revision. Over HTTP, the caller asks for this with the header Wait-For-Revision. If the view does not get there in time, the answer says which revision it shows, rather than failing. For the many reads where a moment of delay does not matter, nothing changes. For the few where a caller depends on its own write, reading it becomes a request rather than a hope.
Errors That Say What to Do#
A failed command is a value: the compiler warns if you drop it, and you cannot reach the written events without deciding what to do about the error. Nearly every error of the kit has a category that says what to do about it.
A refusal by the decider is final, since a business rule said no, so you show it to the user. A transient failure, such as a conflict or a database that cannot be reached, may pass when trying again. A permanent one means something is broken and will not pass at all. The few errors that fit none say what they are instead, above all a write whose outcome is unknown, whose events may have been stored, and which must not be tried again blindly:
use architecturekit::{Categorized, Category};
let command = BorrowBook { book: Subject::new("/books/42"), reader_id: "23".to_owned() };
match store.execute(&borrow_book(), command).await {
Ok(written) => println!("Written: {} event(s)", written.len()),
Err(error) => match error.category() {
Some(Category::Domain) => println!("Refused: {error}"),
Some(Category::Transient) => println!("Try again later: {error}"),
_ => println!("Failed: {error}"),
},
}
Over HTTP, the same categories become status codes. With the feature axum, ? in a handler answers a refusal with 422, a conflict with 409, any other transient failure with 503, and a permanent failure or a write whose outcome is unknown with 500. Whenever the cause may name internals, the answer carries a fixed message, and the cause goes to the log. The handler stays an ordinary axum handler, because the kit offers building blocks rather than routes.
Tests Without a Database#
Since a decision is a function, testing it needs neither a database nor mocks, which Testing Without Mocks argues in general. The feature testing brings given-when-then for deciders: given some events, when a command, then the expected events, a refusal, or the preconditions it writes with:
use architecturekit::{Category, testing::given};
#[tokio::test]
async fn refuses_to_borrow_a_borrowed_book() {
given(
&borrow_book(),
[
BookEvent::Acquired(BookAcquired { title: "2001".to_owned() }),
BookEvent::Borrowed(BookBorrowed { reader_id: "17".to_owned() }),
],
)
.when(BorrowBook { book: Subject::new("/books/42"), reader_id: "23".to_owned() })
.await
.then_failed_in(Category::Domain);
}
then_failed_in checks the category rather than the message, so the test survives when someone rewords the message. Where a test does need a real database, such as to run a command from end to end, the feature testcontainers starts one in a container that the tests of a program share, and Ryuk, the reaper of Testcontainers, removes it once the program ends. A test whose projection reads everything gets a database of its own.
Two Guards, One Kit#
We started with a reviewer who never gets tired. In ArchitectureKit for Rust, the compiler checks what lives in the types: which events a book can have, that each has a schema, that every case is handled, and that every failure is a value you deal with. At runtime, EventSourcingDB and the kit check what only happens then – the database, whether the data matches its schema and who wrote first, and the kit, with the revisions the database hands out, whether a view has caught up. Between the two guards, very little in an event-sourced application is left to luck.
ArchitectureKit is one product in two languages, Go and Rust, each with documentation of its own that follows the idioms of its language rather than translating the other. If you'd like to try it yourself, the quickstart takes you from an empty project to a first command, and the tutorial First Steps with ArchitectureKit goes further, up to an HTTP API with axum and tests for its decisions. All you need is Rust 1.88 or later and Docker, with which the quickstart starts EventSourcingDB for you.
