A lightweight Rust library for designing event-based systems
In an event-based systems, anything that can happen is modeled with an event. Business entities are designed with aggregates, that are atomically modified with events.
Présage is freely inspired by concepts like domain-driven design or command-query responsibility segregation, but tries to be agnostic by making as few assumptions as possible. Specifically, it does not tie you to any persistence approach.
An aggregate represent a business entity that can evolve during the system execution. It is identified by a unique id. An aggregate is always atomically modified to ensure consistency.
To define an aggregate, you need to create a structure or an enumeration that will serve as an
aggregate root and that implements the Aggregate trait:
use presage::{Aggregate, Id};
use uuid::Uuid;
pub struct Todo {
pub id: Id<Todo>,
pub name: String,
pub done: bool,
}
impl Aggregate for Todo {
type Id = Uuid;
type CreationEvent = TodoCreated;
type UpdateEvent = TodoUpdated;
type DeletionEvent = TodoDeleted;
fn id(&self) -> Id<Self> {
self.id
}
fn new(event: TodoCreated) -> Self {
Self {
id: event.id,
name: event.name,
done: false,
}
}
fn apply(&mut self, event: TodoUpdated) {
match event {
TodoUpdated::Renamed { new_name, .. } => self.name = new_name,
TodoUpdated::Done(_) => self.done = true,
}
}
}You must specify the type of the id. It can be anything, as long as each
aggregate has a unique value. When referencing an aggregate, Id<A> should be used as it allows
compile-tile checks. If the type of the id has the Copy trait, Id<A> will also have it. You need
to implement the id function that returns the id of an aggregate.
You also need to specify three aggregate event types: one for creating, one for updating, and one
for deleting the aggregate (see events for how to define events), as well as a function
to create a new aggregate (new) and a function to update an existing aggregate (apply).
An event represent something that happened in the past . It is serialized using the serde crate
when being dispatched, so it can be shared between independent parts of the system. An event must
thus implement serde::Serialize and serde::Deserialize.
Simple events are defined by implementing the Event trait on a structure or an enumeration:
#[derive(serde::Serialize, serde::Deserialize)]
struct SystemStarted(Instant);
impl presage::Event for SystemStarted {
const NAME: &'static str = "system-started";
}The NAME constant identifies the type of the event and must be unique.
To modify the state of the system, specialized events are needed: aggregate events. An aggregate
event affects a single aggregate that must be referenced by its id. If multiple aggregates are
modified, multiple aggregate events must be issued. The AggregateEvent trait allows the
specification of aggregate events:
use presage::{AggregateEvent, Event, Id};
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
pub struct TodoCreated {
pub id: Id<Todo>,
pub name: String,
}
impl Event for TodoCreated {
const NAME: &'static str = "todo-created";
}
impl AggregateEvent for TodoCreated {
type Aggregate = Todo;
fn id(&self) -> Id<Self::Aggregate> {
self.id
}
}Commands are requests to modify the system. They are implemented as structures or enumerations that contain the required information. It is associated with a command handler which produces events when executed.
#[derive(Debug)]
pub struct CreateTodo {
pub id: Id<Todo>,
pub name: String,
}
impl presage::Command for CreateTodo {
const NAME: &'static str = "create-todo";
}Once you have defined commands and events, you need to write handlers for the system to actually do something. A command handler takes a command and returns events, while an event handler takes an event and returns commands.
All handlers require a mutably borrowed context to be passed with the command or event it is handling. The context can be anything you need, and its role is to manage inputs and outputs, for instance to load an aggregate in a command handler.
When defining a handler, you can specify the exact type of the context used a runtime, or use generics to specify the traits the handler is required to implement.
A command handler handles a single command type, identified by its name. It implements
the CommandHandler trait:
use presage::{CommandHandler, Error, Events, BoxedCommand};
struct CreateTodoHandler;
#[async_trait::async_trait]
impl<C, E> CommandHandler<C, E> for CreateTodoHandler
where
E: From<Error>,
{
fn command_name(&self) -> &'static str {
"create-todo"
}
async fn handle(&self, _context: &mut C, command: BoxedCommand) -> Result<Events, E> {
let CreateTodo { id, name } = command.downcast()?;
Ok(events!(TodoCreated { id, name }))
}
}An event handler can be associated with multiple event types, and implements the EventHandler
trait:
use presage::{Commands, Error, EventHandler, SerializedEvent};
use crate::{LoadTodoView, SaveTodoView, TodoView, TodoCreated, TodoUpdated};
struct CreateTodoViewOnTodoEvent;
#[async_trait::async_trait]
impl EventHandler<C, E> for CreateTodoViewOnTodoEvent
where
C: LoadTodoView + SaveTodoView,
E: From<Error>,
{
fn event_names(&self) -> &[&'static str] {
&[TodoCreated::NAME, TodoUpdated::NAME]
}
async fn handle(&self, context: &mut C, event: &SerializedEvent) -> Result<Commands, E> {
if event.name == TodoCreated::NAME {
let TodoCreated { id, name } = event.deserialize()?;
context.save(TodoView { id, name, done: false }).await?;
} else {
let todo_updated: TodoUpdated = event.deserialize()?;
// …
}
Ok(Default::default())
}
}To simplify writing commands, events, and handlers, a few derive and attribute macros are available
with the derive feature (active by default).
The Command, Event, and AggregateEvent can all be derived. By default, the name of the command
or event is derived from the name of the type by converting it to kebab case (e.g., TodoCreated
becomes todo-created). If you want to specify another name, you can use
the #[presage(name = "name")] attribute on the type for which the trait is derived.
To properly derive the AggregateEvent trait, more information is required. The type of the
associated aggregate must be specified by using the #[presage] attribute:#[presage(Todo)]
or #[presage(aggregate = Todo)]. The field containing must be specified, either by declaring it in
on the type with #[presage(id = id_field)] or by adding the #[id] attribute on the field. If the
event is an enumeration, a mix of both approach can be used:
#[derive(Serialize, Deserialize, AggergateEvent)]
#[presage(aggregate = SomeAggregate, id = id)]
enum SomeAggregateEvent {
// No field with the #[id] attribute, the field specified on the type is used
Variant1 { id: Id<SomeAggregate>, /* … */ },
// The id field has a different name, we need to add the #[id] attribute
Variant2 { #[id] id_field: Id<SomeAggregate>, /* … */ },
// Fields of a tuple variant have no name, we need to add the #[id] attribute
Variant3(#[id] Id<SomeAggregate>, /* … */),
}Both CommandHandler and EventHandler can be automatically created using the #[command_handler]
and #[event_handler] attributes on a function, respectively.
For a command handler, the function must have two parameters: the context and the handled command.
For instance, the CreateTodoHandler defined above can be written like this:
#[command_handler]
pub async fn create_todo<C, E>(_context: &mut C, CreateTodo { id, name }: CreateTodo) -> Result<Events, E>
where
E: From<presage::Error>,
{
Ok(events!(TodoCreated { id, name }))
}The #[event_handler] can be used with two different function signatures. If it only handles one
type of event, the function can use the actual event type as second parameter, otherwise it needs to
specify the event names in the attribute and use &SerializedEvent for the type of the second
parameter:
#[event_handler]
pub async fn simple_event_handler<C, E>(context: &mut C, event: SomeEvent) -> Result<Commands, E>
where
E: From<presage::Error>,
{
// …
}
#[event_handler(events = [SomeEvent, "event-name"])]
pub async fn multiple_events_handler<C, E>(context: &mut C, event: &SerializedEvent) -> Result<Commands, E>
where
E: From<presage::Error>,
{
// …
}For both type of handlers, the macro needs to extract the error type from the function signature. If you are using a type alias, you can specify the error type in the attribute:
#[command_handler(error = MyError)]
pub async fn some_handler(context: &mut MyContext, command: SomeCommand) -> MyResult<Events> {
// …
}The command bus is the main entry point when running a system using présage. It takes a context and a command that is then executed. The resulting events are persisted, then any matching event handler is executed. Those event handlers can return new commands which are also executed. The process continues as long as new commands are issued. Be careful to avoid an infinite loop!
A command bus can be created using the new function (or the Default implementation). It can then
be configured by providing a Configuration.
let command_bus = CommandBus::new()
.configure(
Configuration::new()
.event_handler(&some_event_handler)
.command_handler(&some_command_handler)
);The modifications of the system must all be modeled using events. These modifications are persisted
using the trait EventWriter. The actual implementation can persist the results of applying the
events, or it can persist the events themselves. With présage you can choose the approach you
prefer, and you can even mix the two approaches.
The examples folder contains a simple command line todo application using présage. It illustrates most of the concepts discussed in this file.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.