§reference

ModelEvent

An event is a record that something happened to a model: opened, deposited, closed. A model carries the events of its change, and each one becomes a row in eventlog.events when the action commits. #[model_event] turns a plain struct into one.

Declaring an event

use ekbatan::model_event;

#[model_event(Wallet)]
pub struct WalletMoneyDepositedEvent {
    pub amount: Decimal,
    pub new_balance: Decimal,
}

#[model_event(Wallet)] names the model the event belongs to. It writes:

The struct can’t have generic parameters. Its field types must implement serde’s Serialize and Deserialize. Your app needs no serde dependency for the derive itself: the macro uses the one inside ekbatan.

The event holds only its own fields. It has no model id: the event log takes the id and the type name from the model the event is attached to.

An event with no fields needs braces:

#[model_event(Wallet)]
pub struct WalletClosedEvent {}

A unit struct (pub struct WalletClosedEvent;) is written as JSON null, and the write is refused with Error::Invalid: an event must be a JSON object.

// ekbatan::AnyModelEvent
pub trait AnyModelEvent: fmt::Debug + Send + Sync + 'static {
    fn event_type(&self) -> &'static str;   // "WalletMoneyDepositedEvent"
    fn type_path(&self) -> &'static str;    // the full path, module included
    fn to_json(&self) -> Result<String, Error>;
    fn as_any(&self) -> &dyn std::any::Any;
}

ekbatan::event_type_name::<WalletMoneyDepositedEvent>() gives the same name as event_type(), from the type alone.

Writing a good event

Put in it what a reader needs to act on, and nothing else. Name it in the past tense: it describes something that already happened.

A request id, a delivery address, a flag: these belong to one run of the action, not to what happened to the wallet. Put them in the action’s params. They are saved on the same row, and a handler reads them from envelope.action_params.

Attaching one

Attach an event inside the model’s own method, as part of the change:

self.copy()
    .with_event(WalletMoneyDepositedEvent { amount, new_balance })
    .balance(new_balance)
    .build()

with_event takes impl ModelEvent<Wallet>. An event declared for another model doesn’t compile there. The model makes the event, the action stages the model, and the executor writes both. See Model: Events.

How an event becomes a row

wallet.deposit(...)          the new wallet carries the event
   |
plan.update(wallet)          the event goes with the wallet
   |
the executor commits         one row in eventlog.events per event, same transaction

Each row’s columns come from four places:

columnfrom
namespacethe executor’s namespace
action_idone new UUID per call, the same on every shard the call writes
action_namethe action’s type name: WalletDepositMoneyAction
action_paramsthe action’s params, as JSON
started_datethe executor’s clock, when this attempt began
completion_date · event_datethe executor’s clock, inside the shard’s transaction
model_idthe id of the model the event is attached to, as text
model_typethat model’s type name: Wallet
event_typethe event’s type name: WalletMoneyDepositedEvent
payloadthe event as JSON, below
deliveredfalse
ida new UUID per row

So a reader can tell which action and which model an event belongs to without opening the payload, and can route on event_type without parsing it. Handlers subscribe by event_type too.

event_type is the struct’s name, without its module path. Renaming the struct changes it, and readers subscribed to the old name stop getting it. Two event types with the same name in different modules are refused when the second is written (Error::Invalid, “Event type simple name collision”), because a reader routes on the name alone.

The full list of columns is on events.

The payload

{"modelId":"0193...","modelName":"Wallet","amount":5.50,"newBalance":15.50}

This is the JSON Ekbatan for Java writes for the same event, checked against values Java wrote: a Java service reads these rows, and a Rust one reads Java’s. Known gaps, all avoidable:

On MySQL the payload and action_params columns are of the JSON type, which keeps a number with a fraction as a double: 10.00 reads back as 10.0. PostgreSQL’s jsonb and MariaDB keep the digits.

Reading it back

The derived Deserialize reads a payload back into the struct. Keys the struct doesn’t declare, such as modelId, are ignored. A missing key is an error, unless the field is an Option.

See also