Saga
Table of Contents
This page defines the service architecture pattern Saga in the pattern language. A long piece of work is a sequence of local steps, each with a compensating step, so work that spans services stays consistent without a distributed transaction. In ORE Studio the workflow engine runs sagas by orchestration.
1. Also known as
- Orchestration-based saga, the form ORE Studio uses: one coordinator drives the steps.
- Choreography-based saga, the alternative not used here: services react to each other's events.
2. Context
One business action writes in several services: provisioning a party, running a report. No transaction spans two services, and holding locks across them would stall the platform.
3. Problem
How does work that writes in several services stay consistent when one of its steps fails?
4. Forces
- No transaction spans services.
- Other readers see the intermediate state; there is no isolation.
- Undoing a completed step may itself fail.
- Some completed work is worth keeping, and undoing it helps nobody.
5. Solution
The work is a list of steps, each a local transaction in one service, and each with a compensating step that undoes its effect. A coordinator runs the steps in order. When a step fails, it runs the compensations of the completed steps in reverse. A definition may choose instead to stop and wait for a retry, when its completed work is worth more than a rollback.
Figure 1: Saga: step 3 fails, so the coordinator compensates steps 2 and 1 in reverse.
Source: [[./pattern_saga.puml][pattern_saga.puml]]. Regenerate with
plantuml -tpng doc/knowledge/service_architecture_patterns/pattern_saga.puml.
Figure 2: Saga: a definition chooses compensate or stop-and-retry; a deadline always stops the run.
Source: [[./pattern_saga_policies.puml][pattern_saga_policies.puml]]. Regenerate with
plantuml -tpng doc/knowledge/service_architecture_patterns/pattern_saga_policies.puml.
6. Failure handling
| Concern | What the pattern does |
|---|---|
| Errors | A step that reports failure triggers the definition's policy: compensate, or stop for a retry. |
| Timeouts | A step that goes silent is failed by its deadline, and the run stops; a silent step's work is unknown, so it is never compensated. |
| Retries | A stopped run resumes at its failed step; completed steps keep their results. |
| Idempotency | Every step and every compensation must converge on repeat. |
| Observability | The run, its steps and their outcomes are the record a person reads. |
7. Pitfalls
- Compensation read as rollback. Other services saw the intermediate state; a compensation is a new action, not an erasure.
- Compensating a step that timed out. It may have finished. Stop and let a person decide.
- A compensation that cannot run. A step whose effect cannot be undone belongs last, or in a stop-and-retry definition.
- Steps that are not idempotent. Recovery re-dispatches steps, and a repeat that accumulates corrupts the run.
8. Security
Each step runs with the identity its service needs, as for any call; the saga adds no authority.
9. Resulting context
- Benefits
- Consistency across services without distributed locks, and a record of every step.
- Liabilities
- No isolation, and every step needs a compensation or a reason it has none.
10. In ORE Studio
- Failure, compensation and retry — the compensate policy walks completed steps in reverse; a deadline stops the run instead.
- Report execution — every step compensates through
reporting.v1.ops.fail_report, which marks the instance failed. - Identity — the fixture compensates the steps that declared a compensation.
- Transporting a package — a bundle that fails is handled by the run's declared policy: stop and retry, or compensate the completed bundles in reverse.
11. Related patterns
- Process Manager — the coordinator that runs the saga.
- Idempotent Receiver — what makes a re-dispatched step safe.
- Timeout — the deadline that stops a silent step.
12. Sources
- Hector Garcia-Molina and Kenneth Salem, "Sagas", Proceedings of the 1987 ACM SIGMOD International Conference on Management of Data, 1987.
- Chris Richardson, Pattern: Saga, microservices.io.
- Microsoft, Azure Architecture Center, Cloud design patterns, Saga distributed transactions pattern.
13. See also
- Service architecture patterns — the structure note that orders this pattern language, and where to read this page in it.