Struct Saga 

pub struct Saga { /* private fields */ }

Saga: a sequence of steps with structured compensations.

Each step has a forward action and a compensation. If any step fails, all previously-completed compensations run in reverse order. This is the distributed equivalent of structured finalizers.

Design Principles

• Compensations are deterministic: Given the same inputs, compensations produce the same effects. This enables lab testing of failure scenarios.
• Reverse order: Compensations run last-to-first, ensuring that later steps’ effects are undone before earlier steps’.
• Budget-aware: In Phase 1+, compensations will be budget-constrained (they are finalizers, which run under masked cancellation).
• Trace-aware: Each step and compensation emits trace events.

API Pattern

The compensation closure captures its own context. The forward action returns a value for the caller to use in subsequent steps.

use asupersync::remote::Saga;

let mut saga = Saga::new();

// Step 1: Create resource — compensation captures what it needs
let id = "resource-1".to_string();
let id_for_comp = id.clone();
saga.step(
    "create resource",
    || Ok(id),
    move || format!("deleted {id_for_comp}"),
)?;

// Step 2: Configure — no value needed for compensation
saga.step("configure", || Ok(()), || "reset config".into())?;

// Complete on success
saga.complete();

Implementations

impl Saga

pub fn new() -> Self

Creates a new empty saga.

pub fn state(&self) -> SagaState

Returns the current saga state.

pub fn completed_steps(&self) -> StepIndex

Returns the number of completed steps.

pub fn compensation_results(&self) -> &[CompensationResult]

Returns the compensation results (populated after abort).

pub fn step<T>( &mut self, description: &str, action: impl FnOnce() -> Result<T, String>, compensate: impl FnOnce() -> String + Send + 'static, ) -> Result<T, SagaStepError>

Executes a forward step and registers its compensation.

The forward action runs immediately. If it succeeds, the compensation closure is registered for potential rollback. If it fails, the saga enters the compensating state and runs all registered compensations in reverse order.

The compensation closure should capture whatever context it needs to undo the forward action’s effect (e.g., clone the resource ID before passing it to the step).

Errors

Returns SagaStepError if the forward action fails. In that case, compensations have already been executed before this returns.

pub fn complete(&mut self)

Marks the saga as successfully completed.

After completion, the registered compensations are dropped (they are no longer needed since all steps succeeded).

Panics

Panics if the saga is not in Running state.

pub fn abort(&mut self)

Explicitly aborts the saga, running compensations in reverse order.

This is called when the caller wants to roll back, even if no step has failed. For example, when cancellation is requested.

Panics

Panics if the saga is not in Running state.

Trait Implementations

impl Debug for Saga

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Saga

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Saga

fn drop(&mut self)

Executes the destructor for this type.