AWS durable-functions documentation change
Summary
Complete restructuring and expansion of the Durable Functions key concepts documentation. Adds detailed sections on durable execution, timeouts, DurableContext, operations, checkpoints, replay, determinism, and a replay walkthrough with code examples in TypeScript, Python, and Java. Updates navigation links and table of contents.
Security assessment
The changes are purely documentation improvements and restructuring. There is no mention of security vulnerabilities, patches, or incidents. The content focuses on explaining core concepts, execution models, and SDK usage without addressing security features, vulnerabilities, or security-related configurations. The changes are routine documentation updates to improve clarity and completeness.
Diff
diff --git a/durable-functions/getting-started/key-concepts.md b/durable-functions/getting-started/key-concepts.md index e991bf2f7..41e197b2d 100644 --- a//durable-functions/getting-started/key-concepts.md +++ b//durable-functions/getting-started/key-concepts.md @@ -15,3 +15,3 @@ Search - * [ SDK Reference ](../../sdk-reference/operations/step/) - * [ Testing ](../../testing/basic-tests/) - * [ Patterns ](../../patterns/best-practices/) + * [ SDK Reference ](../../sdk-reference/) + * [ Testing ](../../testing/) + * [ Patterns ](../../patterns/) @@ -29,3 +29,18 @@ Getting Started - * [ Key Concepts ](././) - * [ Quick Start ](../quick-start/) - * SDK Reference SDK Reference + * Key Concepts [ Key Concepts ](././) On this page + * Durable execution + * Timeouts + * Durable functions + * DurableContext + * Operations + * Checkpoints + * Replay + * Determinism + * Rules for deterministic durable operations + * Replay Walkthrough + * [ Quickstart ](../quickstart/) + * [ Quickstart for Container Image ](../quickstart-container-image/) + * [ Manage Executions ](../manage-executions/) + * [ Development Environment ](../development-environment/) + * [ SDK Reference ](../../sdk-reference/) + +SDK Reference @@ -48 +63,13 @@ Getting Started - * Testing Testing + * [ Configuration ](../../sdk-reference/configuration/) + +Configuration + * [ Custom Lambda Client ](../../sdk-reference/configuration/custom-lambda-client/) + * [ Language Guides ](../../sdk-reference/languages/) + +Language Guides + * [ TypeScript ](../../sdk-reference/languages/typescript/) + * [ Python ](../../sdk-reference/languages/python/) + * [ Java ](../../sdk-reference/languages/java/) + * [ Testing ](../../testing/) + +Testing @@ -53 +80,3 @@ Getting Started - * Patterns Patterns + * [ Patterns ](../../patterns/) + +Patterns @@ -60,0 +90 @@ On this page + * Timeouts @@ -61,0 +92 @@ On this page + * DurableContext @@ -65,5 +96,3 @@ On this page - * How replay works in practice - * The two SDKs - * Execution SDK (aws-durable-execution-sdk-python) - * Testing SDK (aws-durable-execution-sdk-python-testing) - * Decorators + * Determinism + * Rules for deterministic durable operations + * Replay Walkthrough @@ -78 +107,56 @@ On this page -# Key Concepts +# Key Concepts¶ + +## Durable execution¶ + +A durable execution is the complete lifecycle of an AWS Lambda durable function. It uses a checkpoint and replay mechanism to track progress, suspend execution, and recover from failures. When functions resume after suspension or interruptions, previously completed checkpoints replay and the function continues execution. + +The execution lifecycle could include multiple invocations of the Lambda function to complete, particularly after suspensions or failure recovery. With these replays the execution can run for extended periods (up to one year) while maintaining reliable progress despite interruptions. + +### Timeouts¶ + +The [execution timeout](https://docs.aws.amazon.com/lambda/latest/api/API_DurableConfig.html#lambda-Type-DurableConfig-ExecutionTimeout) and Lambda function [Timeout](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Timeout) are different settings. The Lambda function timeout controls how long each individual invocation can run (maximum 15 minutes). The execution timeout controls the total elapsed time for the entire durable execution (maximum 1 year). + +## Durable functions¶ + +A durable function is a Lambda function configured with the [`DurableConfig`](https://docs.aws.amazon.com/lambda/latest/dg/durable-configuration.html) object at creation time. Lambda will then apply the checkpoint and replay mechanism to the function's execution to make it durable at invocation time. + +## DurableContext¶ + +`DurableContext` is the context object your durable function receives instead of the standard Lambda `Context`. It exposes all durable operations and provides methods for creating checkpoints, managing execution flow, and coordinating with external systems. + +Your durable function receives a `DurableContext` instead of the default Lambda context: + +TypeScriptPythonJava + + + import { DurableContext, withDurableExecution } from "@aws/durable-execution-sdk-js"; + + export const handler = withDurableExecution( + async (event: any, context: DurableContext) => { + // Your function receives DurableContext instead of Lambda context + // Use context.step(), context.wait(), etc. + const result = await context.step("my-step", async () => { + return "step completed"; + }); + return result; + }, + ); + + + + from aws_durable_execution_sdk_python import DurableContext, durable_execution, durable_step, StepContext + + + @durable_step + def my_step(ctx: StepContext, data: dict) -> str: + # Your business logic + return f"step completed with {data}" + + + @durable_execution + def handler(event: dict, context: DurableContext): + # Your function receives DurableContext instead of Lambda context + # Use context.step(), context.wait(), etc. + result = context.step(my_step(event["data"])) + return result + @@ -80 +163,0 @@ On this page -## Durable execution @@ -82 +165,2 @@ On this page -A durable execution represents the complete lifecycle of a Lambda durable function. The SDK uses a checkpoint and replay mechanism to track progress, suspend execution, and recover from failures. A single execution may span multiple Lambda invocations. + import software.amazon.lambda.durable.DurableContext; + import software.amazon.lambda.durable.DurableHandler; @@ -84 +168 @@ A durable execution represents the complete lifecycle of a Lambda durable functi -## Durable functions + public class DurableContextExample extends DurableHandler<Object, String> { @@ -86 +170,7 @@ A durable execution represents the complete lifecycle of a Lambda durable functi -A durable function is a Lambda function decorated with `@durable_execution` that can be checkpointed and resumed. The function receives a `DurableContext` that provides methods for durable operations. + @Override + public String handleRequest(Object input, DurableContext context) { + // Your function receives DurableContext instead of Lambda context + // Use context.step(), context.wait(), etc. + return context.step("my-step", String.class, ctx -> "step completed"); + } + } @@ -88 +178,2 @@ A durable function is a Lambda function decorated with `@durable_execution` that -## Operations + +## Operations¶ @@ -92,7 +183,24 @@ Operations are units of work in a durable execution. Each operation type serves - * **Steps** \- Execute code and checkpoint the result with retry support - * **Waits** \- Pause execution for a specified duration without blocking Lambda - * **Callbacks** \- Wait for external systems to respond with results - * **Invoke** \- Call other durable functions to compose complex workflows - * **Child contexts** \- Isolate nested workflows for better organization - * **Parallel** \- Execute multiple operations concurrently with completion criteria - * **Map** \- Process collections in parallel with batching and failure tolerance + * [Steps](../../sdk-reference/operations/step/) Execute business logic with automatic checkpointing and configurable retry + * [Waits](../../sdk-reference/operations/wait/) Suspend execution for a duration without consuming compute resources + * [Callbacks](../../sdk-reference/operations/callback/) Suspend execution and wait for an external system to submit a result + * [Invoke](../../sdk-reference/operations/invoke/) Invoke another Lambda function and checkpoint the result + * [Parallel](../../sdk-reference/operations/parallel/) Execute multiple independent operations concurrently + * [Map](../../sdk-reference/operations/map/) Execute an operation on each item in an array concurrently with optional concurrency control + * [Child context](../../sdk-reference/operations/child-context/) Group operations into an isolated context for sub-workflow organization and concurrent determinism + * [Wait for condition](../../sdk-reference/operations/wait-for-condition/) Poll for a condition with automatic checkpointing between attempts + + + +## Checkpoints¶ + +A checkpoint is a saved record of a completed durable operation: its type, name, inputs, result, and timestamp. The SDK creates checkpoints automatically as your function executes operations. Together, the checkpoints form a log that Lambda uses to resume execution after a suspension or interruption. + +When your code calls a durable operation, the SDK follows this sequence: + + 1. **Check for an existing checkpoint** if this operation already completed in a previous invocation, the SDK returns the stored result without re-executing + 2. **Execute the operation** if no checkpoint exists, the SDK runs the operation code + 3. **Serialize the result** the SDK serializes the result for storage + 4. **Persist the checkpoint** the SDK calls the Lambda checkpoint API to durably store the result before continuing + 5. **Return the result** execution continues to the next operation + + @@ -99,0 +208 @@ Operations are units of work in a durable execution. Each operation type serves +Once the SDK persists a checkpoint, that operation's result is safe. If your function is interrupted at any point, the SDK can replay up to the last persisted checkpoint on the next invocation. @@ -100,0 +210 @@ Operations are units of work in a durable execution. Each operation type serves +## Replay¶ @@ -102 +212 @@ Operations are units of work in a durable execution. Each operation type serves -## Checkpoints +Lambda keeps a running log of all durable operations as your function executes. When your function needs to pause or encounters an interruption, Lambda saves this checkpoint log and stops the execution. When it's time to resume, Lambda invokes your function again from the beginning and replays the checkpoint log: @@ -104 +214,4 @@ Operations are units of work in a durable execution. Each operation type serves -Checkpoints are saved states of execution that allow resumption. When your function calls `context.step()` or other operations, the SDK creates a checkpoint and sends it to AWS. If Lambda recycles your environment or your function waits for an external event, execution can resume from the last checkpoint. + 1. **Load checkpoint log** the SDK retrieves the checkpoint log for the execution from Lambda + 2. **Run from beginning** your handler runs from the start, not from where it paused + 3. **Skip completed operations** as your code calls durable operations, the SDK checks each against the checkpoint log and returns stored results without re-executing the operation code + 4. **Resume at interruption point** when the SDK reaches an operation without a checkpoint, it executes normally and creates new checkpoints from that point forward @@ -106 +218,0 @@ Checkpoints are saved states of execution that allow resumption. When your funct -## Replay @@ -108 +219,0 @@ Checkpoints are saved states of execution that allow resumption. When your funct -When your function resumes, completed operations don't re-execute. Instead, they return their checkpointed results instantly. This means your function code runs multiple times, but side effects only happen once per operation. @@ -110 +221 @@ When your function resumes, completed operations don't re-execute. Instead, they -Because your code runs again on replay, it must be **deterministic** — avoid random values, timestamps, or external API calls outside of steps, as these can produce different values on replay. +The SDK enforces determinism by validating that operation names and types match the checkpoint log during replay. Your orchestration code must make the same sequence of durable operation calls on every invocation. @@ -112 +223,13 @@ Because your code runs again on replay, it must be **deterministic** — avoid r -## How replay works in practice