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

SagaEvent

sealed interface SagaEvent

Events emitted during saga execution for monitoring and logging.

These events provide a structured way to observe saga execution lifecycle, enabling monitoring, logging, and metrics collection. All step-related events use TypedValue to preserve enum type information when enum step names are used.

Event Lifecycle

SagaStarted - Saga execution begins
For each step:

StepStarted - Step execution begins
StepCompleted, StepFailed, or StepSkipped - Step outcome

If a step fails:

CompensationStarted - Compensation begins for a completed step
CompensationCompleted or CompensationFailed - Compensation result

If a step is skipped:

Remaining steps are skipped, no compensation triggered

SagaCompleted or SagaAborted - Saga finishes

Usage Example

enum class OrderSteps { VALIDATE, PAYMENT, SHIP }
enum class SkipReason { ALREADY_PROCESSED }

saga.addMonitor { event ->
    when (event) {
        is SagaEvent.StepStarted -> {
            // Type-safe enum access
            when (event.stepAs<OrderSteps>()) {
                OrderSteps.VALIDATE -> log.info("Validating order...")
                OrderSteps.PAYMENT -> log.info("Processing payment...")
                OrderSteps.SHIP -> log.info("Shipping order...")
                null -> log.info("Starting: ${event.stepName}")
            }
        }
        is SagaEvent.StepSkipped -> {
            if (event.reasonAs<SkipReason>() == SkipReason.ALREADY_PROCESSED) {
                metrics.recordDuplicate()
            }
        }
        is SagaEvent.StepFailed -> log.error("Step failed: ${event.stepName}", event.error)
        else -> log.debug("Saga event: $event")
    }
}

Inheritors

CompensationCompleted

CompensationFailed

SagaCompleted

SagaAborted

Types

CompensationCompleted

data class CompensationCompleted(val step: TypedValue, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when compensation completes successfully.

CompensationFailed

data class CompensationFailed(val step: TypedValue, val error: Throwable, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when compensation fails.

CompensationStarted

data class CompensationStarted(val step: TypedValue, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when compensation starts for a completed step.

SagaAborted

data class SagaAborted(val error: SagaExecutionError, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when the saga is aborted due to a failure.

SagaCompleted

data class SagaCompleted<out R>(val result: R, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when the saga completes successfully.

SagaStarted

data class SagaStarted(val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when saga execution starts.

StepCompleted

data class StepCompleted<out R>(val step: TypedValue, val result: R, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when a saga step completes successfully.

StepFailed

data class StepFailed(val step: TypedValue, val error: Throwable, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when a saga step fails.

StepSkipped

data class StepSkipped(val step: TypedValue, val skipReason: TypedValue, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when a saga step is skipped.

StepStarted

data class StepStarted(val step: TypedValue, val timestamp: Long = System.currentTimeMillis()) : SagaEvent

Emitted when a saga step starts execution.

Properties

timestamp

abstract val timestamp: Long

Timestamp when the event occurred (milliseconds since epoch).