aws / aws/aws-durable-execution-docs

sdk-reference/operations/step: expand at-most-once vs at-least-once with diagram

Open
#142 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
13
Forks
13
Avg merge
3d 2h
Merged PRs (30d)
25

Description

## Context

PR #141 introduced `docs/patterns/best-practices/idempotency.md` with a short prose explanation of at-most-once vs at-least-once execution semantics. A review comment on that PR flagged that the topic could be clearer for new users:

> Do we need a code example and a flow chart to show when retry/replay will occur? I think this section could be unclear to a new user.
>
> — https://github.com/aws/aws-durable-execution-docs/pull/141#discussion_r3131892604

The patterns page is meant to teach best practice, not the underlying mechanism, so the full explanation belongs in the step reference.

## Problem

`docs/sdk-reference/operations/step.md` is thin on the semantics of at-most-once vs at-least-once. A new user cannot work out from the reference alone:

- What happens between the `START` checkpoint and the step body running.
- What happens if Lambda is interrupted before the start checkpoint commits.
- What happens if Lambda is interrupted after the start checkpoint commits but before the step body completes.
- How retries interact with each semantic.
- Why 'per retry' is important and how to combine with a no-retry strategy for end-to-end once-only execution.

## Proposal

Expand the `StepSemantics` section in `docs/sdk-reference/operations/step.md`:

1. Add a mermaid or equivalent sequence diagram showing the timing of:
- Start checkpoint initiation
- Step body execution
- Interruption points (sandbox death, network drop, invocation timeout)
- Replay behaviour under each semantic
2. Add a worked code example that demonstrates the difference.
3. Cross-link from `patterns/best-practices/idempotency.md`.

## Acceptance

- Reader can look at the step reference alone and understand when each semantic re-runs the step versus raises `StepInterrupted`.
- The patterns/best-practices/idempotency.md page links to the reference diagram rather than trying to re-explain the mechanics.

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.