module std.saga

std.saga — sagas and durable pipelines (§10.6, §11.3, D-5100..D-5189).

The compiler turns every saga and pipeline declaration into ordinary functions that call this module (compiler/src/sema/SagaSema.cpp); nothing here is meant to be called by hand except status, resolve and list.

A saga is a list of steps; after a step undo r => … names its compensation. The generated function nests the steps:

enter(0, …) -> S1 -> guard(0, it, r => U1, x => ( done(0, x) -> enter(1, …) -> S2 -> done(1, it) ))

so the compensations run by themselves, innermost first, when a later step fails (guard). Nothing is kept in memory between steps except the call stack: a node that takes the saga over RE-EXECUTES the steps from the first one. That is sound because every step carries the key sagaId#step as idempotency-key and the rpcs of a step are @idempotent (the analyzer insists on it): a repeated step answers with its first result instead of running again.

Journal (std.kv store oxl.saga, all keys of one saga carry the tag {sagaId} and so live on ONE shard, so a transaction may read and write them together):

s/{id}/h  head: name, encoded arguments, caller, creation time          (written once)
s/{id}/o  lease of the executor: node, expiry, epoch                    (compare-and-set; epoch fences a stale executor)
s/{id}/t  state: running | compensating | done | failed | cancelled | stuck, step cursor, result
s/{id}/c  cancel marker (the caller's deadline passed)
s/{id}/uK compensation of step K was done
a/<saga>/{id}   index of unfinished sagas of a kind; x/{id} index of stuck ones

Who runs a saga: the node that was called when it has a role with runs sagas, otherwise any such node; its recovery loop (serve) claims sagas without an executor and takes over those whose lease expired or whose node SWIM declared dead. Deadline (customer answer 9): when the caller's deadline passes the driver writes the cancel marker (one transaction) and returns Timeout at once; the executor sees the marker before the next step and compensates the finished ones in the background. The marker and the commit of the last step are decided in one transaction: a saga either commits or is cancelled.

Example:

service Ledger {
  @public @idempotent rpc openAcct(id: u64) -> u64
}

impl Ledger {
  rpc openAcct(id) => id + 100
}

saga register(id: u64) -> u64 {
  Ledger.openAcct(id)
}

fn main() io, net, time, db {
  match register(5) {
    u64 v => print("registered {v}")
    CompensationFailed _ => print("stuck")
    NetError _ => print("net error")
  }
  print("stuck sagas: {std.saga.list(.Stuck).len()}")
}

registered 105
stuck sagas: 0

Types

Functions