KState-Saga/ca.acendas.kstate.saga/SagaBuilder

SagaBuilder

class SagaBuilder<C, R>

DSL builder for creating standalone saga executors.

SagaBuilder provides a fluent API for defining saga steps, compensation logic, idempotency markers, and monitors. The builder is mutable during construction but produces an immutable SagaExecutor.

Usage Example

val saga = sagaExecutor<OrderContext, OrderResult> {
    step("reserve-inventory") { context ->
        inventoryService.reserve(context.items)  // Can be a suspend call
    }
    compensate { reservationId ->
        inventoryService.release(reservationId)  // Can be a suspend call
    }

    step("charge-payment") { context ->
        paymentService.charge(context.amount)  // Can be a suspend call
    }
    compensate { transactionId ->
        paymentService.refund(transactionId)  // Can be a suspend call
    }
    idempotent(true)

    monitor { event ->
        logger.info("Saga event: $event")
    }
}

// Execute within a coroutine
val result = saga.execute(OrderContext(...))

Step Configuration

Steps are configured using a fluent chain:

step(name) { ... } - Define the step's forward action
compensate { ... } - (Optional) Define compensation for the step
idempotent(true) - (Optional) Mark the step as idempotent

Each call to step() finalizes the previous step and starts a new one.

Parameters

C

The type of context passed to saga steps

R

The type of result produced by saga steps

Constructors

constructor()

Properties

val <C, R> SagaBuilder<C, R>.first: SagaDoStarter<C, R>

Starts the first saga step with "first do 'name' with { ... }" syntax.

val <C, R> SagaBuilder<C, R>.then: SagaDoStarter<C, R>

Alternative: starts any saga step (not necessarily first).

val <C, R> SagaBuilder<C, R>.watching: EventWatcher<C, R>

Starts monitor configuration with "watching" keyword.

Functions

fun <C, R> SagaBuilder<C, R>.asIdempotent(): SagaBuilder<C, R>

Marks the last step as idempotent using simple syntax.

asNonIdempotent

fun <C, R> SagaBuilder<C, R>.asNonIdempotent(): SagaBuilder<C, R>

Marks the last step as non-idempotent.

fun build(): SagaExecutor<C, R>

Build the saga executor.

fun compensate(compensation: suspend (R) -> Unit): SagaBuilder<C, R>

Define compensation logic for the current step.

infix fun <C, R> SagaBuilder<C, R>.compensateWith(compensation: suspend (R) -> Unit): SagaBuilder<C, R>

Adds compensation to the last defined step using simple syntax (suspend function).

fun idempotent(value: Boolean = true): SagaBuilder<C, R>

Mark the current step as idempotent (safe to retry).

fun monitor(monitor: SagaMonitor): SagaBuilder<C, R>

Add a monitor to observe saga events.

fun monitor(handler: suspend (SagaEvent) -> Unit): SagaBuilder<C, R>

Add a monitor using a lambda.

infix fun <C, R> SagaBuilder<C, R>.monitoring(handler: (SagaEvent) -> Unit)

Adds a saga monitor using "monitoring with" syntax.

infix fun <C, R> SagaBuilder<C, R>.monitorWith(monitor: SagaMonitor)

Adds a saga monitor instance.

fun retry(policy: RetryPolicy): SagaBuilder<C, R>

Set retry policy for current step.

fun step(step: TypedValue, timeout: Duration? = null, forward: suspend (C) -> R): SagaBuilder<C, R>

Define a saga step with forward logic and optional timeout.

fun step(name: String, timeout: Duration? = null, forward: suspend (C) -> R): SagaBuilder<C, R>

Define a saga step with string name (convenience overload).

infix fun <C, R> SagaBuilder<C, R>.step(name: String): StepActionBuilder<C, R>

Alternative syntax: "step 'name' does { ... }"

fun timeout(duration: Duration): SagaBuilder<C, R>

Set timeout for current step.