Saga Best Practices

1. Make Compensations Idempotent

Compensations might run more than once (retries). They should produce the same result regardless.

# ✓ Good: Idempotent refund
refund(orderId) → if not already refunded, refund

# ✗ Bad: Non-idempotent
refund(orderId) → always issue refund (double refund!)

2. Keep Steps Small

Each step should do one thing. Don't combine multiple operations in a single step.

3. Test the Rollback Path

Your compensation code is as important as your forward code. Test it thoroughly.

4. Use Checkpoints for Long Sagas

For sagas with many steps, checkpoints prevent re-running completed steps after a crash.

5. Monitor Saga Executions

naos saga status --all
naos audit --filter saga

6. Handle Compensation Failures

Have a plan for when compensations fail. Manual resolution should be documented.

7. Set Timeouts

Don't let saga steps run forever:

sagas:
  order:
    timeout: 300    # 5 minutes total
    stepTimeout: 60 # 1 minute per step