§learn

Actions

Build the new state first, then let the executor commit domain rows and event rows in one transaction. Retries, errors, and what an action may not do.

An action is one unit of business work. It does not write to the database. It stages new and changed objects on its plan. Only after perform returns does the executor open one transaction, write every staged change, write the event rows, and commit.

Two steps

   executor.execute::<WalletDepositMoneyAction>(principal, params)
                              │
   ┌─── Step 1 - perform()   (no transaction yet) ──────────────┐
   │   read from repositories                                   │
   │   build new models                                         │
   │   attach events to them                                    │
   │   stage:  plan.add(notification) / plan.update(wallet)     │
   │   return a result                                          │
   └────────────────────────────────────────────────────────────┘
                              │
   ┌─── Step 2 - persist     (one transaction per shard) ───────┐
   │   group staged changes by shard                            │
   │   repositories write the business rows                     │
   │   the event rows are written to eventlog.events            │
   │   commit  -or-  roll back                                  │
   │   on a stale record, run the whole action again            │
   └────────────────────────────────────────────────────────────┘

Step 1 only builds values. Step 2 is the only place a transaction is opened, and it always wraps every staged change together with its event rows.

Three things follow from the split, and they are most of why it exists.

perform does not write, so it cannot half-write. It is handed a plan, not a transaction. If it returns an error, or panics, no transaction was ever opened, so there is nothing to roll back.

Running it again is cheap and correct. When a version check fails, step 2 rolls back and the executor runs step 1 again from the top, with a fresh plan. It reads the row it lost the race on again, so the second try is built on the winner’s state, not patched onto the loser’s. An action that only reads, computes and stages is safe to run twice. One that called another service inside perform is not, which is the real reason to keep perform free of side effects.

Sharding stays out of the action. Grouping by shard happens in step 2, so perform stages objects without knowing which database each lands on. The same action works on one database and on eight.

The cost is one thing to keep in mind: plan.update(x) has not written x. It returns x as it will be written, at the next version, so later code in the same perform sees the new version. But the database has not seen it, and won’t until perform returns.

Writing an action

use std::sync::Arc;

use ekbatan::action::ActionPlan;
use ekbatan::blocking::{Action, Repository};
use ekbatan::{Error, ShardedId};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};

use crate::model::Wallet;
use crate::repository::WalletRepository;

#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Params {
    pub wallet_id: ShardedId<Wallet>,
    pub amount: Decimal,
    pub recipient: Option<String>,
}

pub struct WalletDepositMoneyAction {
    wallet_repository: Arc<WalletRepository>,
}

impl WalletDepositMoneyAction {
    pub fn new(wallet_repository: Arc<WalletRepository>) -> Self {
        WalletDepositMoneyAction { wallet_repository }
    }
}

impl Action for WalletDepositMoneyAction {
    type Params = Params;
    type Result = Wallet;

    fn perform(
        &self,
        plan: &mut ActionPlan,
        _principal: Option<&str>,
        params: &Params,
    ) -> Result<Wallet, Error> {
        let wallet = self.wallet_repository.get_by_id(&params.wallet_id)?;
        let updated = wallet.deposit(params.amount)?;
        plan.update(updated)
    }
}

In async code the action implements AsyncAction, perform is async fn, and each read is awaited. What it stages is the same, and so is everything else on this page. A blocking Action is also an AsyncAction, so either kind registers in the same registry and runs in either executor.

Typed parameters in, a model out. The action reads through a repository, gets a new wallet with an event already attached (that happened inside wallet.deposit), and stages it. No database write happens in perform.

Params and Result are the action’s input and output types. The compiler holds the call site to them: execute::<WalletDepositMoneyAction> takes these params and returns a Wallet.

The params are written to the event row as JSON, so they must serialize to a JSON object: a struct. An action with no input uses an empty struct (struct Params {}); a bare value such as a number or () is refused when the action runs. rename_all = "camelCase" writes the keys the way Ekbatan for Java does.

Nothing finds actions for you. You register each one when you build the executor:

let executor = ActionExecutor::builder()
    .namespace("example.wallet")
    .database_registry(registry.clone())
    .action_registry(
        ActionRegistry::builder()
            .with_action(WalletCreateAction::new(Arc::new(SystemClock)))
            .with_action(WalletDepositMoneyAction::new(wallets.clone()))
            .with_action(WalletCloseAction::new(wallets.clone()))
            .build(),
    )
    .repository_registry(
        RepositoryRegistry::builder()
            .with_repository(wallets.clone())
            .build(),
    )
    .build()?;

Running an action that was not registered is an error. So is staging a type that has no repository in the repository registry: the executor would have no way to write it.

Calling it:

let wallet = executor.execute::<WalletDepositMoneyAction>(
    Some("alice"),
    wallet_deposit_money_action::Params {
        wallet_id: id,
        amount: Decimal::new(2550, 2),
        recipient: None,
    },
)?;

The executor opens one transaction, writes the wallet row at its next version, writes the WalletMoneyDepositedEvent row into eventlog.events, and commits. If anything fails, both roll back together.

The plan

plan.add(entity)?;          // staged for INSERT; returns it unchanged
plan.update(entity)?;       // staged for UPDATE; returns it at its next version
plan.add_all(items)?;
plan.update_all(items)?;

Three rules:

One instance, many calls

There is one instance of each action, shared by every call running at the same time. That is why perform takes &self, and why an action must be Send + Sync. Its only state is what its constructor was given: repositories, a clock. Everything that belongs to one call, its plan, its principal and its params, is passed to perform.

Running work in parallel inside perform is allowed. Wait for every result, then stage. For reads, it is often simpler to do the parallel work before execute, in the caller.

Errors

perform returns Result<Self::Result, Error>. An Err aborts the action: nothing it staged is written.

Retries on a stale record

By default, an action that loses a race on a row (Error::StaleRecord) is run once more, after 100 ms. That is enough for ordinary contention, and not enough to hide a real problem. To change it for one call:

let config = ExecutionConfiguration::builder()
    .with_retry(RetryOn::stale_record(), RetryConfig::new(3, Duration::from_millis(50)));
let wallet = executor.execute_with::<WalletDepositMoneyAction>(None, params, &config)?;

Or for every call, with default_execution_configuration(...) on the executor builder.

Details worth knowing:

What an action may not do

Write directly. A repository’s add and update methods can be called from anywhere, perform included, and nothing stops you. But such a write runs outside the action’s transaction, is not undone if the action fails, and writes no event. Inside an action, stage.

Run another action inside perform. Actions do not nest. An action is one self-contained unit of work with one transaction, and nesting would blur that, hide the coupling, and make the flow hard to follow. Nothing in the framework prevents it (an action could hold an executor), but the inner action would commit on its own, before the outer one, and stay committed if the outer one failed.

What you probably meant instead:

That works where nesting does not because after the commit there is no outer transaction left to break.

Call the blocking API from async code. The blocking executor waits on its own runtime; from inside an async function it blocks that thread, and on a single-threaded runtime it panics. Use ekbatan::aio there. See Blocking or async?.

Actions over two shards

Refused unless you ask. An action whose staged changes are on two shards fails with Error::CrossShard, naming two of them. The check runs on what was staged, between perform and the first transaction, so nothing has been written when it fires.

let config = ExecutionConfiguration::builder().allow_cross_shard(true);
executor.execute_with::<TransferAction>(None, params, &config)?;

With that, each shard gets its own transaction and commits on its own. There is no two-phase commit, and none can be turned on: the shards are separate databases. A failure rolls back only its own shard. The shards that already committed stay committed, and the executor logs that as an error.

Be careful with retries here. If a later shard fails with a stale record, the default retry runs the whole action again, including the part that already committed on the earlier shards. Turn retries off for such a call (.no_retry()) unless perform stages nothing new when its work is already done.

So a partial commit here is the dual-write trap again: two systems that can disagree, both of them yours. Allow it per call, not as the executor’s default, so the risk is visible where it is taken. If a partial commit would need undoing, the honest answer is a saga.

See also