aws-lambda-durable-functions

AWS Lambda durable functions

建構高韌性的多步驟應用程式與 AI 工作流，最長可持續執行達 1 年，並能在遭遇中斷時依然可靠地延續執行進度。

最佳搭配 AWS MCP server，但非必要條件。本 Skill 中所有的 AWS 操作皆使用標準 AWS CLI 指令，只要在已設定 AWS 憑證的環境下均可正常運作。

Critical Rules

在撰寫任何程式碼前，請務必先閱讀以下規則。每一條都是硬性約束，若違反將導致函數在運行時無聲無息地失效。

1. Durable execution 必須在建立函數時即啟用，無法事後改造（retrofitted）。 必須新建一個已啟用 durable execution 的 Lambda 函數，並將業務邏輯遷移至新函數中；切勿嘗試在現有函數中直接安裝 SDK 並包覆 handler，這將無法正常運作。
2. Durable functions 必須使用限定的 ARN（qualified ARN）來呼叫 — 也就是包含特定版本號、別名（alias）或字面上的 $LATEST 後綴。未限定（unqualified）的函數名稱會呼叫失敗。範例請參閱下方的 Invocation Requirements（呼叫需求）章節。
3. Durable 操作不可嵌套。 您無法在某個步驟的 callback 內部直接呼叫 context.step()、context.wait() 或 context.invoke()。請改用 context.runInChildContext() 來對多個操作進行分組。
4. 所有非確定性（non-deterministic）程式碼都必須在步驟（step）內部執行。 若在步驟之外執行 Date.now()、Math.random()、UUID 產生、API 呼叫或資料庫查詢，會在重放（replay）時產生不同的數值，進而破壞執行狀態的一致性。
5. 閉包狀態變更（Closure mutations）會在重放時遺失 - 請改為透過步驟的回傳值（return values）來傳遞資料
6. 步驟之外的副作用（Side effects）會在重放時重複執行 - 請使用具備重放感知能力的 context.logger 進行日誌紀錄

When to Load Reference Files

根據使用者目前的開發需求，載入對應的參考檔案：

• 入門指南、基礎設定、範例、ESLint 或 Jest 設定 -> 請參閱 getting-started.md
• 理解重放模型（replay model）、確定性（determinism）或非確定性錯誤 -> 請參閱 replay-model-rules.md
• 建立步驟、原子操作或重試邏輯 -> 請參閱 step-operations.md
• 等待、延遲、回調（callbacks）、外部系統整合或輪詢（polling） -> 請參閱 wait-operations.md
• 平行執行、Map 操作、批次處理或並行（concurrency） -> 請參閱 concurrent-operations.md
• 錯誤處理、重試策略、Saga 模式或補償事務（compensating transactions） -> 請參閱 error-handling.md
• 進階錯誤處理、超時處理、斷路器（circuit breakers）或條件式重試 -> 請參閱 advanced-error-handling.md
• 測試、本地測試、雲端測試、Test Runner 或不穩定測試（flaky tests） -> 請參閱 testing-patterns.md
• 部署、CloudFormation、CDK、SAM、日誌組（log groups）、發布或基礎設施即程式碼（IaC） -> 請參閱 deployment-iac.md
• 進階模式、GenAI Agent、完成策略（completion policies）、步驟語意或自訂序列化 -> 請參閱 advanced-patterns.md
• 排錯（troubleshooting）、執行停滯、執行失敗、除錯執行 ID、執行歷史紀錄、執行錯誤、為什麼執行失敗、執行超時、未收到回調、診斷執行狀況或根因分析 -> 請參閱 troubleshooting-executions.md

Quick Reference

Basic Handler Pattern

TypeScript:

import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(async (event, context: DurableContext) => {
  const result = await context.step('process', async () => processData(event));
  return result;
});

Python:

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    result = context.step(lambda _: process_data(event), name='process')
    return result

Python API Differences

Python SDK 與 TypeScript SDK 在幾個主要面向有所不同：

• 步驟（Steps）：使用 @durable_step 裝飾器 + context.step(my_step(args))，或採用內聯方式 context.step(lambda _: ..., name='...')。建議優先使用裝飾器以實現自動步驟命名。
• 等待（Wait）：context.wait(duration=Duration.from_seconds(n), name='...')
• 例外（Exceptions）：ExecutionError（永久性錯誤）、InvocationError（暫時性錯誤）、CallbackError（回調失敗）
• 測試（Testing）：直接使用 DurableFunctionTestRunner 類別——使用 handler 進行實例化，透過 context manager 呼叫 run(input=...)

Invocation Requirements

Durable functions 強制需要使用限定的 ARN（qualified ARNs）（版本號、別名或 $LATEST）：

# Valid
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:live output.json

# Invalid - will fail
aws lambda invoke --function-name my-function output.json

IAM Permissions

您的 Lambda 執行角色（execution role）必須附加 AWSLambdaBasicDurableExecutionRolePolicy 託管策略（managed policy）。該策略包含：

• lambda:CheckpointDurableExecution - 持久化儲存執行狀態
• lambda:GetDurableExecutionState - 檢索／讀取執行狀態
• CloudWatch Logs 相關權限

以下情境需要額外權限：

• Durable 呼叫：針對目標函數 ARN 授予 lambda:InvokeFunction 權限
• 外部回調：外部系統需要 lambda:SendDurableExecutionCallbackSuccess 與 lambda:SendDurableExecutionCallbackFailure 權限

Validation Guidelines

撰寫或審查 durable function 程式碼時，務必檢查是否違反以下重放模型（replay model）規範：

1. 步驟之外存在非確定性程式碼：Date.now()、Math.random()、產生 UUID、API 呼叫及資料庫查詢都必須放在步驟內部
2. 步驟函數中嵌套 durable 操作：不可在步驟函數內部呼叫 context.step()、context.wait() 或 context.invoke()——請改用 context.runInChildContext()
3. 無法持久化的閉包狀態變更：在步驟內部修改的變數不會在重放時保留——請改為讓步驟回傳數值
4. 步驟之外的副作用會在重放時重複執行：請使用 context.logger 進行日誌紀錄（它具備重放感知能力，會自動去重）

實作或修改 durable functions 的測試時，務必確認以下幾點：

1. 所有操作皆具備清晰易懂的名稱
2. 測試必須透過名稱（NAME）獲取操作，絕不要透過索引號（index）
3. 重放行為須透過多次呼叫進行驗證
4. 使用 LocalDurableTestRunner 進行本地測試

Security Considerations

• 檢查點資料加密：執行狀態會自動持久化儲存。請在關聯的 CloudWatch Log Groups 上啟用 KMS 加密，以保護靜態的檢查點資料。
• 步驟回傳值中的敏感資料：步驟的回傳值會被紀錄為檢查點並持久化儲存。切勿從步驟回傳金鑰、原始憑證或個人身分識別資訊（PII）——請將敏感資料儲存於 Secrets Manager 或 SSM Parameter Store，並僅回傳引用標示。
• 輸入驗證：在 handler 入口處、將資料傳遞給步驟前，即完成 event payload 的驗證與淨化（sanitize）。
• 憑證管理：請在步驟內部從 AWS Secrets Manager 或 SSM Parameter Store 取得機密資訊。
• 回調 Payload 驗證：透過 waitForCallback 接收到的資料來自外部系統——在處理前請務必進行驗證與淨化。
• 日誌紀錄：非開發環境中請避免使用 DEBUG 日誌層級，以免洩漏步驟結果與執行狀態。請啟用 CloudWatch Logs 的 KMS 加密。

Resources

• AWS Lambda durable functions Documentation
• JavaScript SDK Repository
• Python SDK Repository
• IAM Policy Reference