saga

Documentation

Overview

Package saga provides a lightweight in-process saga coordinator for cross-domain atomic operations. It executes a sequence of steps and runs compensation (undo) functions in reverse order if any step fails.

It is NOT crash-safe: for durable sagas, wrap execution inside a pkg/jobs job.

Example:

err := saga.New("dispense_charge").
    Step("create_invoice",  createInvoice, voidInvoice).
    Step("debit_ar_ledger", debitAR,       reverseAR).
    Step("deduct_stock",    deductStock,   restock).
    Execute(ctx, saga.State{"patient_id": pid, "items": items})

Index

• type Saga
  • func New(name string) *Saga
  • func (s *Saga) Execute(ctx context.Context, state State) error
  • func (s *Saga) Idempotent() *Saga
  • func (s *Saga) Step(name string, do, undo StepFn) *Saga
  • func (s *Saga) WithLogger(l *slog.Logger) *Saga
• type State
• type StepFn
• type UndoError
  • func (e *UndoError) Error() string
  • func (e *UndoError) Unwrap() error
• type UndoFailure

Types

type Saga

type Saga struct {
	// contains filtered or unexported fields
}

Saga is a named sequence of steps with compensating actions.

func New

func New(name string) *Saga

New creates a new Saga with the given name.

func (*Saga) Execute

func (s *Saga) Execute(ctx context.Context, state State) error

Execute runs all steps in order. If a step returns an error, execution stops and completed steps are compensated in reverse order (the failing step's undo is NOT called). If any undo also fails, an UndoError is returned wrapping the original cause and all undo failures.

If ctx is already cancelled before execution begins, ctx.Err() is returned immediately. Context cancellation between steps is checked before each step.

func (*Saga) Idempotent

func (s *Saga) Idempotent() *Saga

Idempotent marks the most recently added step as safe to retry once inline. Reserved for future use; v1 does not retry automatically.

func (*Saga) Step

func (s *Saga) Step(name string, do, undo StepFn) *Saga

Step appends a named step with its do and undo functions. undo may be nil if the step has no compensation logic.

func (*Saga) WithLogger

func (s *Saga) WithLogger(l *slog.Logger) *Saga

WithLogger sets a logger for step-level diagnostics. Defaults to slog.Default().

type State

type State map[string]any

State is the shared mutable map passed through every step. Steps read their inputs from it and write outputs into it so later steps can consume them. State is NOT safe for concurrent access; steps run sequentially.

type StepFn

type StepFn func(ctx context.Context, state State) error

StepFn is a function that executes one saga step.

type UndoError

type UndoError struct {
	Cause    error
	Failures []UndoFailure
}

UndoError is returned when the original step error was accompanied by one or more failures in the compensation chain. Cause is the original step error; Failures lists every undo that also errored.

func (*UndoError) Error

func (e *UndoError) Error() string

func (*UndoError) Unwrap

func (e *UndoError) Unwrap() error

type UndoFailure

type UndoFailure struct {
	Step string
	Err  error
}

UndoFailure records one compensation step that failed during rollback.