aws / aws/aws-durable-execution-docs
docs: add dedicated Saga / compensation pattern page
- Dominant language
- Python
- Stars
- 13
- Forks
- 13
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 25
Description
## Problem
How to implement the saga / compensation pattern (durable distributed transactions with automatic rollback of already-completed steps when a later step fails). The SDK already supports this pattern via existing primitives (`context.step()`, `context.parallel()`, standard error handling), but there is no dedicated guide showing how to assemble those primitives into a saga.
## Current docs state
- The [SDK Developer Guide home](https://docs.aws.amazon.com/durable-execution/) lists **"Saga patterns"** as a use case, but the link does not lead to a dedicated saga page.
- [AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/saga.html) documents the saga pattern for **Step Functions**, not for Durable Functions / the Durable Execution SDK.
- There is **no dedicated page** in the Durable Execution SDK docs showing how to implement a saga using `context.step()` and compensation logic.
- An SDK-level saga utility is being tracked in [GitHub Discussions #158](https://github.com/aws/aws-durable-execution-docs/discussions/158), but nothing in the published docs points customers there.
## Suggested improvement
1. **Add a "Saga pattern" page** under Patterns in the SDK docs. It should cover:
- A plain-English description of the saga pattern (forward steps + compensating steps, compensations run in reverse order on failure).
- A minimal runnable example using existing SDK primitives: forward steps wrapped in `context.step()`, compensating actions also wrapped in `context.step()` so they are themselves durable, and a `try/except` (or equivalent) block that iterates registered compensations in reverse on failure.
- A parallel-saga variant using `context.parallel()` for independent forward steps.
- Guidance on idempotency of compensating actions and how replay interacts with partial compensation.
- Explicit callouts for common pitfalls: non-durable compensations, compensations that depend on in-memory state lost on replay, and ordering assumptions.
2. **Link from the SDK Developer Guide home "Saga patterns" use case** directly to the new page so the existing entry point is no longer a dead end.
4. **Cross-link** from the new saga page to related pages: error handling, `context.step()` reference, and Best Practices → Determinism and replay (since compensation correctness depends on replay semantics).
## Severity
Low (by report classification) — but high-leverage: saga is a frequent first-ask in competitive comparisons with Temporal, and a dedicated page directly unblocks customer evaluations.
## Affected docs
- [SDK Developer Guide home](https://docs.aws.amazon.com/durable-execution/) (update the "Saga patterns" use case link)
- New page: SDK docs → Patterns → Saga pattern
Contributor guide
Assessment
This issue has not been assessed yet.