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 lists "Saga patterns" as a use case, but the link does not lead to a dedicated saga page.
- AWS Prescriptive Guidance 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, but nothing in the published docs points customers there.
Suggested improvement
-
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.
-
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.
-
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
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
context.step()and compensation logic.Suggested improvement
Add a "Saga pattern" page under Patterns in the SDK docs. It should cover:
context.step(), compensating actions also wrapped incontext.step()so they are themselves durable, and atry/except(or equivalent) block that iterates registered compensations in reverse on failure.context.parallel()for independent forward steps.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.
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