aws-lambda-durable-functions

作者: aws

使用AWS Lambda持久函数构建弹性、长时间运行的多步骤应用程序,具备自动状态持久化、重试逻辑和编排功能,用于…

npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-lambda-durable-functions

AWS Lambda durable functions

Durable functions are Lambda functions that checkpoint progress and can run multi-step workflows for up to one year, suspending without compute charges during waits and callbacks.

Use the developer guides for APIs

Do not write SDK method signatures, configuration objects, or IaC properties from memory. Read the relevant page first. The SDK guide covers TypeScript, Python, Java, Go, Rust, and C#, and the API names differ between languages.

AWS Durable Execution SDK Developer Guide:

TopicLink
Key concepts and quickstarthttps://docs.aws.amazon.com/durable-execution/getting-started/key-concepts/
Steps (retries, step semantics)https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/
Waitshttps://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait/
Wait for condition (polling)https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait-for-condition/
Callbacks and wait for callbackhttps://docs.aws.amazon.com/durable-execution/sdk-reference/operations/callback/
Invoke (function chaining)https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/invoke/
Parallelhttps://docs.aws.amazon.com/durable-execution/sdk-reference/operations/parallel/
Map (concurrency, completion policies)https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/
Child contextshttps://docs.aws.amazon.com/durable-execution/sdk-reference/operations/child-context/
Errorshttps://docs.aws.amazon.com/durable-execution/sdk-reference/error-handling/errors/
Retrieshttps://docs.aws.amazon.com/durable-execution/sdk-reference/error-handling/retries/
Serializationhttps://docs.aws.amazon.com/durable-execution/sdk-reference/state/serialization/
Logginghttps://docs.aws.amazon.com/durable-execution/sdk-reference/observability/logging/
Python language guidehttps://docs.aws.amazon.com/durable-execution/sdk-reference/languages/python/
TypeScript language guidehttps://docs.aws.amazon.com/durable-execution/sdk-reference/languages/typescript/
Testing (local and cloud runners)https://docs.aws.amazon.com/durable-execution/testing/
Writing testshttps://docs.aws.amazon.com/durable-execution/testing/authoring/
Test assertionshttps://docs.aws.amazon.com/durable-execution/testing/assertions/
Best practices (determinism, idempotency, state)https://docs.aws.amazon.com/durable-execution/patterns/best-practices/

Lambda durable functions guide, for the Lambda service side:

TopicLink
Deploying with CloudFormation, AWS CDK, AWS SAM, Terraformhttps://docs.aws.amazon.com/lambda/latest/dg/durable-getting-started-iac.html
Invoking (sync, async, execution names)https://docs.aws.amazon.com/lambda/latest/dg/durable-invoking.html
Security and permissionshttps://docs.aws.amazon.com/lambda/latest/dg/durable-security.html
Monitoring and execution historyhttps://docs.aws.amazon.com/lambda/latest/dg/durable-monitoring.html
Best practiceshttps://docs.aws.amazon.com/lambda/latest/dg/durable-best-practices.html
Supported runtimeshttps://docs.aws.amazon.com/lambda/latest/dg/durable-supported-runtimes.html

Works best with the AWS MCP Server for reading these pages, but it is not required.

Critical rules: Lambda

  1. Durable execution is enabled only when a function is created. It cannot be added to an existing function. Create a new function with durable execution (DurableConfig in IaC) and move the logic into it.
  2. The handler must be wrapped with the SDK (withDurableExecution in TypeScript, @durable_execution in Python). A plain handler deployed to a durable function fails every execution, so when moving existing code, wrap it rather than copying it unchanged.
  3. Invoke with a qualified ARN: a version, an alias, or $LATEST (for example my-function:live). An unqualified function name fails.
  4. The execution role needs lambda:CheckpointDurableExecution, lambda:GetDurableExecutionState, and CloudWatch Logs permissions. The managed policy AWSLambdaBasicDurableExecutionRolePolicy grants these on all resources and is fine for getting started; for production, use a policy scoped to the function's ARN. Durable invokes also need lambda:InvokeFunction on the target. External systems that complete callbacks need lambda:SendDurableExecutionCallbackSuccess and lambda:SendDurableExecutionCallbackFailure, plus lambda:SendDurableExecutionCallbackHeartbeat if they send heartbeats.

Critical rules: the replay model

Durable functions use checkpoint and replay. After a wait, failure, or resume, the handler re-runs from the beginning. Completed operations return their checkpointed results without re-executing, and code outside operations runs again on every replay.

  1. Code outside steps must be deterministic. Put timestamps, random values, UUIDs, API calls, and database queries in a step.
  2. Never call durable operations inside a step. Use a child context to group operations.
  3. Closure mutations inside steps are lost on replay. Return values from steps instead.
  4. Side effects outside steps repeat on every replay. Put them in steps. The context logger is replay-aware and safe anywhere.
  5. Don't sleep in the handler. Use a durable wait or callback, which suspends the execution without compute charges.
  6. For human approval or an external job that can report back, use wait for callback (waitForCallback / wait_for_callback). Use wait for condition only when the external system can only be polled.
  7. For sagas, run compensations as named steps, in reverse order, from the catch block around the forward steps.
  8. Steps default to at-least-once (AtLeastOncePerRetry), so a crash before the checkpoint re-runs the step. For non-idempotent calls, say so and use AtMostOncePerRetry with retries disabled or an idempotency key.
  9. Express map and parallel failure tolerance in the form the user gives it. A percentage becomes a tolerated failure percentage in the completion config, not a computed count.

When the user asks for code, a test, or a template, show it inline in your answer, even if you also write it to a file. When writing or reviewing durable function code, check it against these rules. When writing tests, name every operation and look operations up by name, not by index.

Troubleshooting executions

Diagnosis is read-only. Read the execution and its history (aws lambda get-durable-execution, aws lambda get-durable-execution-history) and report what you find. Never stop an execution or change its state unless the user explicitly asks.

Security

  • Step results and callback payloads are checkpointed. Do not return secrets, credentials, or PII from steps. Store them in Secrets Manager or SSM Parameter Store, retrieve them inside steps, and return references.
  • Validate event payloads at the handler entry point, and validate callback payloads, which come from external systems.
  • Encrypt the function's CloudWatch Logs log group with KMS, and avoid DEBUG logging outside development because it can expose step results.

When the guides and the SDK disagree

Trust the installed SDK source and tell the user about the discrepancy.