aws / aws/aws-durable-execution-docs

Expand StepSemantics docs to explain checkpoint ordering for at-most-once vs at-least-once

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

Description

## Problem

The current [Step reference docs](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/) describe `StepSemantics.AT_MOST_ONCE_PER_RETRY` as: "Executes the step at most once per retry attempt. If the function replays before the result is checkpointed, the SDK skips the step and raises StepInterruptedError."

This is correct but doesn't explain *how* the guarantee is achieved. Users reading the [fraud detection best practices blog post](https://aws.amazon.com/blogs/compute/best-practices-for-lambda-durable-functions-using-a-fraud-detection-example/) are asking questions like:

- "Is there a failure window where the side effect has already happened, but the success checkpoint has not yet been persisted?"
- "If checkpoints are batched, could the step be retried even though the external side effect already occurred?"

## Proposed solution

Expand the `StepSemantics` section in the Step reference with a "How it works" subsection covering:

1. **Checkpoint ordering:** START and SUCCEED checkpoints for the same step are never in the same batch
2. **At-most-once behavior:** The START checkpoint must complete (synchronous) before the step body runs. Both START and SUCCEED are synchronous checkpoints.
3. **At-least-once behavior:** The step body may start running before the START checkpoint completes (asynchronous).
4. A diagram showing the checkpoint flow for each mode would help clarify the difference.

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.