resonate-saga-pattern-go

Resonate Saga Pattern — Go

Version note. The Go SDK's first tagged release is 0.1.0. The tag is 0.1.0, not v0.1.0, so go get …@latest does not resolve to it — pin the tag explicitly: go get github.com/resonatehq/[email protected]. APIs may still change before a 1.0. There is no Go saga example repo yet, so all snippets use only documented SDK surface verified against the 0.1.0 tag source.

Overview

A saga is a long-running transaction split into discrete steps, each with a compensating action. Forward steps execute top-to-bottom; on any failure, completed compensations run bottom-to-top. Because the whole workflow body re-runs on resume, the completed []Step slice is reconstructed deterministically on replay — each ctx.Run call short-circuits its settled durable promise in the same order, so the slice is rebuilt identically before reaching the point of failure.

For the language-agnostic mental model — including choreography vs orchestration, idempotency requirements, and when not to use sagas — see resonate-saga-pattern-typescript.

When to use

• Multi-step workflow where intermediate state is visible to other systems between steps
• Each step is individually compensable (inventory hold, payment charge, shipment create)
• You need "all or nothing" consistency without a distributed 2PC transaction
• Steps span services and may take seconds to minutes each
• Compensation logic exists and is idempotent for every committed step

Basic shape

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"

    resonate "github.com/resonatehq/resonate-sdk-go"
)

// Step is a string enum for the forward steps that have been committed.
// Using type Step string + a switch gives idiomatic Go compensation dispatch.
type Step string

const (
    StepInventory Step = "inventory"
    StepPayment   Step = "payment"
    StepShipment  Step = "shipment"
)

type OrderArgs struct {
    OrderID string `json:"order_id"`
}

type SagaResult struct {
    Status      string   `json:"status"`
    OrderID     string   `json:"order_id"`
    Compensated []string `json:"compensated,omitempty"`
}

type CompensateArgs struct {
    Step    Step   `json:"step"`
    OrderID string `json:"order_id"`
}

// placeOrder is the saga orchestrator. It runs forward steps in sequence,
// tracking each committed step. On the first failure it runs compensations in
// reverse, each as its own durable ctx.Run so they are retryable.
func placeOrder(ctx *resonate.Context, args OrderArgs) (SagaResult, error) {
    var completed []Step

    // --- forward path ---
    fInv, err := ctx.Run(reserveInventory, args.OrderID)
    if err != nil {
        return SagaResult{}, err
    }
    if err := fInv.Await(nil); err != nil {
        return compensateAll(ctx, args.OrderID, completed, err)
    }
    completed = append(completed, StepInventory)

    fPay, err := ctx.Run(chargePayment, args.OrderID)
    if err != nil {
        return SagaResult{}, err
    }
    if err := fPay.Await(nil); err != nil {
        return compensateAll(ctx, args.OrderID, completed, err)
    }
    completed = append(completed, StepPayment)

    fShip, err := ctx.Run(createShipment, args.OrderID)
    if err != nil {
        return SagaResult{}, err
    }
    if err := fShip.Await(nil); err != nil {
        return compensateAll(ctx, args.OrderID, completed, err)
    }
    completed = append(completed, StepShipment)

    return SagaResult{Status: "success", OrderID: args.OrderID}, nil
}

// compensateAll iterates completed steps in reverse and runs each compensation
// as a durable ctx.Run. Returns a SagaResult with status "failed" on success,
// or propagates the compensation error if a compensation itself fails fatally.
func compensateAll(
    ctx *resonate.Context,
    orderID string,
    completed []Step,
    forwardErr error,
) (SagaResult, error) {
    _ = forwardErr // log or inspect as needed

    var names []string
    for i := len(completed) - 1; i >= 0; i-- {
        step := completed[i]
        f, err := ctx.Run(compensate, CompensateArgs{Step: step, OrderID: orderID},
            resonate.RunOpts{
                Timeout: 10 * time.Minute,
                RetryPolicy: resonate.ExponentialRetry{
                    MaxAttempts: 5,
                    Base:        200 * time.Millisecond,
                    Max:         30 * time.Second,
                    Jitter:      true,
                },
            },
        )
        if err != nil {
            return SagaResult{}, fmt.Errorf("dispatch compensation for %s: %w", step, err)
        }
        if err := f.Await(nil); err != nil {
            // A compensation that exhausts retries is a real inconsistency — log and alert.
            return SagaResult{}, fmt.Errorf("compensation for %s failed: %w", step, err)
        }
        names = append(names, string(step))
    }

    return SagaResult{
        Status:      "failed",
        OrderID:     orderID,
        Compensated: names,
    }, nil
}

// compensate dispatches to the correct undo action via a switch on Step.
// Each branch must be idempotent — compensations may be retried.
func compensate(_ *resonate.Context, args CompensateArgs) (struct{}, error) {
    switch args.Step {
    case StepShipment:
        // cancelShipment(args.OrderID)
        return struct{}{}, nil
    case StepPayment:
        // refundPayment(args.OrderID)
        return struct{}{}, nil
    case StepInventory:
        // releaseInventory(args.OrderID)
        return struct{}{}, nil
    default:
        return struct{}{}, resonate.NewNonRetryable(
            fmt.Errorf("unknown saga step %q — programming error", args.Step),
        )
    }
}

// Forward leaf stubs — replace with real service calls.
func reserveInventory(_ *resonate.Context, orderID string) (struct{}, error) {
    _ = orderID
    return struct{}{}, nil
}

func chargePayment(_ *resonate.Context, orderID string) (struct{}, error) {
    _ = orderID
    return struct{}{}, nil
}

func createShipment(_ *resonate.Context, orderID string) (struct{}, error) {
    _ = orderID
    // Simulate a transient failure to trigger compensation.
    return struct{}{}, errors.New("shipment service unavailable")
}

func main() {
    r, err := resonate.New(resonate.Config{URL: "http://localhost:8001"})
    if err != nil {
        log.Fatalf("resonate.New: %v", err)
    }
    defer func() { _ = r.Stop() }()

    // Only the workflow needs registration; leaves reached via ctx.Run do not.
    placeOrderFn, err := resonate.Register(r, "placeOrder", placeOrder)
    if err != nil {
        log.Fatalf("Register: %v", err)
    }

    h, err := placeOrderFn.Run(context.Background(), "order-1", OrderArgs{OrderID: "order-1"})
    if err != nil {
        log.Fatalf("Run: %v", err)
    }
    res, err := h.Result(context.Background())
    if err != nil {
        log.Fatalf("Result: %v", err)
    }
    fmt.Printf("saga: %+v\n", res)
}