Crate architecturekit 

Building blocks for DDD-based applications with CQRS and event sourcing, on top of EventSourcingDB.

Modules

testing

Given-when-then for deciders, and a database in a container for the tests that need a real one. The module needs the feature testing, and Database the feature testcontainers, which turns on testing as well, so that a test that only checks a decider builds without Docker.

Structs

Decider

A decision on a command, given the state of its subject: the events to write, or an error if the command is refused.

DomainError

A business rule that refused a command, with a message for the caller.

EmptyRange

The bounds of a read leave no room for an event, such as one before "0", one after "0" and before "1", or one after the largest revision, 2^63-1. No event can ever lie in such a range, so it is a mistake of whoever chose the bounds, which usually come from a request, and it belongs to no category. A range that is only empty for now, such as the one after the last event written so far, is no such mistake, since events can still come there, so reading hands out no events for it, without an error.

Envelope

An event as a projection gets it: the metadata of the event as the database recorded it, and its data, as Projection::Event says.

EventOn

An event together with the subject it is written to, for Store::write.

EventSchema

The schema of an event type, for registration with the database.

Failure

What failed, as in reading "/books/42", and the error that caused it, if there is one, such as the error of the client SDK.

NotARevision

A value that was meant to be a revision, but is not one.

Precondition

A condition that must hold for the events of a command to be written.

ReadOptions

Narrows down which events Store::read hands out, or turns around the order it hands them out in. A read has one lower bound, one upper bound, and one order, so options that contradict each other can not be written:

Store

Reads from and writes to EventSourcingDB, through the client SDK.

StoreBuilder

Builds a Store, which Store::builder creates.

SubjectScheme

How a subject is composed: literal segments and placeholders in braces, as in /tenant/{tenant}/workshop/{workshop}.

SubjectValuesError

The values that SubjectScheme::check refuses, with a message that may reach the caller of an API.

Subjects

What a read or a projection reads: a subject, and whether the subjects below it belong to it. Create it with tree or exact, so that every read says which of the two it means, rather than relying on a default.

UpcastEvent

A stored event as upcasters see it: its type and its data, which an upcaster changes, and its subject, ID, time and source, which it reads.

Upcasters

The set of upcasters for the event types of an application, which translate stored events of an older type into a newer shape, before any state or projection sees them.

Enums

Category

What a failure means for its caller, on two axes: whether it is a matter of the domain or of the machinery, and whether trying again unchanged could help.

Error

Any failure of architecturekit, where D is the error of a decider, so that a function that calls several operations can pass their failures on with ?.

ExecuteError

Why executing a command failed, where D is the error of its decider.

IfLatestEventIsMissing

What LowerBound::FromLatestEvent reads if the subject has no event of the type yet.

LoadError

Why loading a state failed.

LowerBound

Where the events of a read start.

Order

The order in which a read hands out the events.

Permanent

A failure of the category Category::Permanent: trying again will not help.

PreconditionsError

Why a command declares its preconditions in a way they can not be honored (see check_preconditions).

ProjectionError

Why a projection failed.

ReadError

Why reading events failed.

ReadOptionsError

Why the options of a read are refused (see check_read_options).

RegisterSchemasError

Why registering the schemas of events failed.

Transient

A failure of the category Category::Transient: trying again later, unchanged, may succeed.

UpperBound

Where the events of a read end.

WriteError

Why writing events failed.

Traits

Categorized

An error that names its Category.

Command

A command, which knows the subject it acts on, and the conditions under which its events may be written.

Event

The data of an event, which describes what has happened.

Events

The events a state evolves by, as one enum with a variant per event type.

Projected

What a projection can get as its events: an enum with #[derive(Events)], or eventsourcingdb::Event, the event as it is stored. The kit implements it for both, and for nothing else.

Projection

A projection that applies events, and is rebuilt from the first event on every start, which is right for a view kept in memory. A projection whose target can hold a checkpoint is a ResumableProjection as well, and one whose target can make data and checkpoint durable together is a TransactionalProjection instead.

ResumableProjection

A projection whose target can hold a checkpoint, but not together with the data, so that it goes on from there on the next start. It writes the checkpoint after the data, so an event may be applied twice after a crash, and apply has to be idempotent.

Schema

The JSON schema of a type, which describes exactly what serde writes for it.

State

The state a command decides on, together with the rule that builds it from events.

Transaction

One unit of work of a TransactionalProjection. Commit has to make the applied events and the ID of the last one durable together, or neither. Rollback is not called after commit fails, so commit has to roll back itself if it can not finish. A panic in apply is rolled back like an error.

TransactionalProjection

A projection whose target can make data and checkpoint durable together, as a relational database can. It applies events only within a Transaction.

Functions

check_preconditions

Checks that a command declares its preconditions in a way they can be honored, before anything is read, as executing a command does.

check_read_options

Checks the options of a read as Store::read checks them before it asks the database. Use it to check bounds that come from a request before a side effect that must not happen for a read that is refused, such as recording who reads. The database may still refuse a read that passes, such as one from a latest event that comes after the upper bound.

compare_revisions

Compares two revisions as numbers, since event IDs are decimal strings, and “10” sorts before “9” as text.

parse_revision

Reads a revision, which is an event ID of EventSourcingDB, as a number.

replay

Folds a sequence of events into a state, starting from Default. It is meant for tests, where the history is at hand as typed events.

replay_stored

Folds stored events into a state, running the upcasters on the way, exactly as reading from the database would. It is meant for tests of upcasters, which need the shape of an older version.

step

Takes a state a single event further, by the same rules as replay. It starts from the given state instead of Default, and leaves that as it is, so that the state before and after the event are both at hand, for example for a history that tells what an event changed.

step_stored

Takes a state a single stored event further, running the upcasters on the way, exactly as reading from the database would. If the upcasters turn the event into several, the state evolves by all of them. Otherwise, it behaves like step.

Derive Macros

Event

Derives architecturekit::Event and architecturekit::Schema for the data of an event. See architecturekit::Event.

Events

Derives architecturekit::Events for the enum of the events a state evolves by. See architecturekit::Events.

Schema

Derives architecturekit::Schema for a type in the data of an event. See architecturekit::Schema.