aws / aws/aws-durable-execution-docs

docs: add dedicated Saga / compensation pattern page

Open
#160 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.