New serverless pattern - New serverless pattern - lambda-durable-functions-rest-api-js

lambda-durable-rest-api-sam-js/.gitignore

@@ -0,0 +1,24 @@
+# SAM
+.aws-sam/
+samconfig.toml
+
+# Node.js
+node_modules/
+package-lock.json
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test outputs
+response.json

lambda-durable-rest-api-sam-js/README.md

@@ -0,0 +1,111 @@
+# AWS Lambda durable function - REST API call with Node.js
+
+This pattern demonstrates a AWS Lambda durable function that calls an external REST API using Node.js.
+
+Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/lambda-durable-rest-api-sam-js
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed
+* [Node.js 24.x](https://nodejs.org/) installed locally (required for `sam build` to resolve npm dependencies and package the Lambda function)
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ``` 
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+1. Change directory to the pattern directory:
+    ```
+    cd lambda-durable-rest-api-sam-js
+    ```
+
+1. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yaml file:
+    ```
+    sam build
+    sam deploy --guided
+    ```
+1. During the prompts:
+    * Enter a stack name
+    * Enter the desired AWS Region
+    * Allow SAM CLI to create IAM roles with the required permissions.
+
+    Once you have run `sam deploy --guided` mode once and saved arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults.
+
+1. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for testing.
+
+## How it works
+
+This pattern demonstrates AWS Lambda Durable Execution for calling external REST APIs. The function uses the `withDurableExecution` wrapper to mark the Lambda handler as a Durable Execution workflow. All steps defined with `context.step()` are automatically retryable.
+
+**Note**: This pattern requires Node.js 24.x runtime which has native support for Durable Execution.
+
+## Testing
+
+1. Get the function name from the stack outputs:
+```bash
+aws sam describe-stacks --stack-name <your-stack-name> \
+  --query 'Stacks[0].Outputs[?OutputKey==`FunctionName`].OutputValue' --output text
+```
+
+2. Invoke the function with default URL:
+```bash
+aws lambda invoke \
+  --function-name <function-name> \
+  --payload '{}' \
+  response.json && cat response.json
+```
+
+3. Invoke with a custom URL:
+```bash
+aws lambda invoke \
+  --function-name <function-name> \
+  --payload '{"url": "https://jsonplaceholder.typicode.com/users/1"}' \
+  response.json && cat response.json
+```
+
+Example JSON Lambda test event:
+```json
+{
+  "url": "https://jsonplaceholder.typicode.com/posts/1"
+}
+```
+
+Expected response (success):
+```json
+{
+  "statusCode": 200,
+  "headers": {"Content-Type": "application/json"},
+  "body": "{\"message\": \"API call successful\", \"url\": \"https://jsonplaceholder.typicode.com/posts/1\", \"data\": {...}}"
+}
+```
+
+The execution is durable - if the API call fails, AWS Lambda will automatically retry the `callRestApi` step without re-executing the entire function.
+
+## Cleanup
+
+1. Delete the stack:
+    ```bash
+    aws sam delete-stack --stack-name <your-stack-name>
+    ```
+1. Confirm the stack has been deleted:
+    ```bash
+    aws sam list-stacks --query "StackSummaries[?contains(StackName,'<your-stack-name>')].StackStatus"
+    ```
+
+## Learn More
+
+- [AWS Lambda durable functions Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)
+- [Durable Execution SDK (Python)](https://github.com/aws/aws-durable-execution-sdk-js)
+- [Callback Operations](https://docs.aws.amazon.com/lambda/latest/dg/durable-callback.html)
+---
+
+Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0
+

lambda-durable-rest-api-sam-js/example-pattern.json

@@ -0,0 +1,64 @@
+{
+  "title": "AWS Lambda durable failures - REST API call (Node.js)",
+  "description": "An AWS Lambda function that calls an external REST API using Durable Execution SDK for automatic retries and state management.",
+  "language": "Node.js",
+  "level": "200",
+  "framework": "SAM",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "This pattern demonstrates AWS Lambda durable execution for calling external REST APIs.",
+      "Uses the withDurableExecution wrapper to mark the Lambda handler as a durable workflow.",
+      "Uses context.step() to make the REST API call automatically retryable.",
+      "AWS automatically handles failures, retries, and state persistence without external services."
+    ]
+  },
+  "gitHub": {
+    "template": {
+      "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/lambda-durable-rest-api-sam-js",
+      "templateURL": "serverless-patterns/lambda-durable-rest-api-sam-js",
+      "projectFolder": "lambda-durable-rest-api-sam-js",
+      "templateFile": "template.yaml"
+    }
+  },
+  "resources": {
+    "bullets": [
+      {
+        "text": "AWS Lambda durable execution",
+        "link": "https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html"
+      },
+      {
+        "text": "AWS Lambda Developer Guide",
+        "link": "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+      },
+      {
+        "text": "Node.js Fetch API",
+        "link": "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API"
+      }
+    ]
+  },
+  "deploy": {
+    "text": [
+      "sam build",
+      "sam deploy --guided"
+    ]
+  },
+  "testing": {
+    "text": [
+      "See the GitHub repo for detailed testing instructions."
+    ]
+  },
+  "cleanup": {
+    "text": [
+      "Delete the stack: <code>aws cloudformation delete-stack --stack-name STACK_NAME</code>."
+    ]
+  },
+  "authors": [
+    {
+      "name": "Theophilus Ajayi",
+      "image": "https://drive.google.com/file/d/1hUrUxWk2JqDTbPhl0DgUeUVd2uFWnAby/view?usp=drivesdk",
+      "bio": "Technical Account Manager @ AWS",
+      "linkedin": "tolutheo"
+    }
+  ]
+}

lambda-durable-rest-api-sam-js/src/app.mjs

@@ -0,0 +1,116 @@
+/**
+ * AWS Lambda durable function - Calls REST API using AWS durable execution SDK
+ */
+import {
+  withDurableExecution,
+  createRetryStrategy,
+} from '@aws/durable-execution-sdk-js';
+
+const DEFAULT_API_URL = process.env.API_URL || 'https://jsonplaceholder.typicode.com/posts/1';
+const MAX_RESPONSE_SIZE = 1_000_000; // 1 MB limit
+
+// Retry strategy: 3 attempts, exponential backoff starting at 2s, max 30s, with jitter
+const stepConfig = {
+  retryStrategy: createRetryStrategy({
+    maxAttempts: 3,
+    initialDelay: { seconds: 2 },
+    maxDelay: { seconds: 30 },
+    backoffRate: 2.0,
+  }),
+};
+
+export const handler = withDurableExecution(async (event, context) => {
+  context.logger.info('Starting durable REST API call');
+
+  // Get API URL from event or use default
+  const apiUrl = event.url || DEFAULT_API_URL;
+
+  context.logger.info(`Using API URL: ${apiUrl}`);
+
+  // Execute the REST API call as a durable step
+  // Transient failures (timeouts, connection errors) propagate as exceptions,
+  // allowing the durable execution SDK to automatically retry the step.
+  let result;
+  try {
+    result = await context.step('Call REST API', async (stepCtx) => {
+      stepCtx.logger.info(`Calling REST API: ${apiUrl}`);
+
+      const response = await fetch(apiUrl, {
+        method: 'GET',
+        signal: AbortSignal.timeout(30000) // 30 second timeout
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      // Validate response size before reading body
+      const contentLength = response.headers.get('Content-Length');
+      if (contentLength && parseInt(contentLength) > MAX_RESPONSE_SIZE) {
+        stepCtx.logger.error(`Response too large: ${contentLength} bytes`);
+        return {
+          status: 'error',
+          error: `Response size ${contentLength} bytes exceeds limit of ${MAX_RESPONSE_SIZE} bytes`
+        };
+      }
+
+      const text = await response.text();
+      if (text.length > MAX_RESPONSE_SIZE) {
+        stepCtx.logger.error('Response body exceeded size limit');
+        return {
+          status: 'error',
+          error: `Response body exceeds limit of ${MAX_RESPONSE_SIZE} bytes`
+        };
+      }
+
+      const data = JSON.parse(text);
+
+      stepCtx.logger.info(`API call successful: ${response.status}`);
+      return {
+        status: 'success',
+        statusCode: response.status,
+        data: data
+      };
+    }, stepConfig);
+  } catch (error) {
+    context.logger.error(`Step failed after retries: ${error.message}`);
+    return {
+      statusCode: 502,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        error: 'API call failed after retries',
+        url: apiUrl,
+        details: error.message
+      })
+    };
+  }
+
+  // Pause for 2 seconds without consuming CPU cycles or incurring usage charges
+  await context.wait({ seconds: 2 });
+
+  // Context logger is replay aware and will not log the same message multiple times
+  context.logger.info('Waited for 2 seconds without consuming CPU.');
+
+  // Return response based on result
+  if (result.status === 'success') {
+    return {
+      statusCode: 200,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        message: 'API call successful',
+        url: apiUrl,
+        data: result.data
+      })
+    };
+  } else {
+    return {
+      statusCode: 500,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        error: 'API call failed',
+        url: apiUrl,
+        details: result.error
+      })
+    };
+  }
+});

lambda-durable-rest-api-sam-js/src/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "lambda-durable-rest-api",
+  "version": "1.0.0",
+  "description": "Lambda Durable Function - REST API Call with Node.js",
+  "type": "module",
+  "main": "app.mjs",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@aws/durable-execution-sdk-js": "^1.0.0"
+  },
+  "keywords": [
+    "aws",
+    "lambda",
+    "durable",
+    "rest-api"
+  ],
+  "author": "",
+  "license": "MIT-0"
+}

lambda-durable-rest-api-sam-js/template.yaml

@@ -0,0 +1,38 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: Lambda Durable Function - Call REST API with Node.js
+
+Resources:
+  DurableFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: src/
+      Handler: app.handler
+      Runtime: nodejs24.x
+      Timeout: 300
+      DurableConfig:
+        ExecutionTimeout: 900  # 15 minutes - allows durablefunction to be invoked syncronously and asynchronously
+        RetentionPeriodInDays: 7
+      MemorySize: 128
+      Architectures:
+        - x86_64
+      LoggingConfig:
+        LogGroup: !Ref DurableFunctionLogGroup
+      Environment:
+        Variables:
+          API_URL: https://jsonplaceholder.typicode.com/posts/1
+
+  DurableFunctionLogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      LogGroupName: !Sub /aws/lambda/${AWS::StackName}-DurableFunction
+      RetentionInDays: 30
+
+Outputs:
+  FunctionArn:
+    Description: Lambda Function ARN
+    Value: !GetAtt DurableFunction.Arn
+
+  FunctionName:
+    Description: Lambda Function Name
+    Value: !Ref DurableFunction