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

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

@@ -0,0 +1,48 @@
+# SAM
+.aws-sam/
+samconfig.toml
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

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

@@ -0,0 +1,116 @@
+# AWS Lambda durable functions - REST API Call with Python
+
+This pattern demonstrates a Lambda durable function that calls an external REST API using Python.
+
+Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/lambda-durable-rest-api-sam-py
+
+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
+* [Python 3.14](https://www.python.org/downloads/) installed locally (required for `sam build` to resolve pip 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-py
+    ```
+
+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 two key components:
+
+1. `@durable_step` - Wraps the REST API call, making it automatically retryable
+2. `@durable_execution` - Marks the Lambda handler as a durable execution workflow
+
+AWS Lambda Durable Execution automatically handles failures, retries, and state persistence without requiring external services like DynamoDB or Step Functions.
+
+## Testing
+
+1. Get the function name from the stack outputs:
+```bash
+aws cloudformation 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 `call_rest_api` 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
+
+- [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-python)
+- [Callback Operations](https://docs.aws.amazon.com/lambda/latest/dg/durable-callback.html)
+- [SendDurableExecutionCallbackSuccess API](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/send_durable_execution_callback_success.html)
+
+---
+
+Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0
+

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

@@ -0,0 +1,64 @@
+{
+  "title": "AWS Lambda durable function - REST API Call",
+"description": "An AWS Lambda function that calls an external REST API using Durable Execution SDK for automatic retries and state management.",
+  "language": "Python",
+  "level": "200",
+  "framework": "SAM",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "This pattern demonstrates AWS Lambda durable functions for calling external REST APIs.",
+      "Uses the @durable_step decorator to make the REST API call automatically retryable.",
+      "Uses the @durable_execution decorator to mark the Lambda handler as a durable workflow.",
+      "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-py",
+      "templateURL": "serverless-patterns/lambda-durable-rest-api-sam-py",
+      "projectFolder": "lambda-durable-rest-api-sam-py",
+      "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": "Python Requests Library",
+        "link": "https://requests.readthedocs.io/"
+      }
+    ]
+  },
+  "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-py/src/app.py

@@ -0,0 +1,131 @@
+"""
+AWS Lambda durable function - Calls REST API using AWS durable execution SDK
+"""
+import json
+import os
+import requests
+from aws_durable_execution_sdk_python.config import Duration, StepConfig
+from aws_durable_execution_sdk_python.context import StepContext, durable_step
+from aws_durable_execution_sdk_python.execution import durable_execution
+from aws_durable_execution_sdk_python.retries import (
+    RetryStrategyConfig,
+    create_retry_strategy,
+)
+
+DEFAULT_API_URL = os.environ.get('API_URL', 'https://jsonplaceholder.typicode.com/posts/1')
+
+# Retry strategy: 3 attempts, exponential backoff starting at 2s, max 30s, with jitter
+retry_config = RetryStrategyConfig(
+    max_attempts=3,
+    initial_delay=Duration.from_seconds(2),
+    max_delay=Duration.from_seconds(30),
+    backoff_rate=2.0,
+    retryable_error_types=[
+        requests.exceptions.ConnectionError,
+        requests.exceptions.Timeout,
+        requests.exceptions.HTTPError,
+    ],
+)
+step_config = StepConfig(retry_strategy=create_retry_strategy(retry_config))
+
+
+@durable_step
+def call_rest_api(step_context: StepContext, url: str) -> dict:
+    """
+    Durable step that calls an external REST API.
+    Transient failures (timeouts, connection errors) are raised so the
+    durable execution SDK can automatically retry the step.
+    Only non-retryable errors (oversized response, invalid JSON) are
+    returned as error dicts.
+    """
+    step_context.logger.info(f"Calling REST API: {url}")
+
+    max_response_size = 1_000_000  # 1 MB limit
+
+    response = requests.get(url, timeout=30, stream=True)
+    response.raise_for_status()
+
+    # Validate response size before reading body
+    content_length = response.headers.get('Content-Length')
+    if content_length and int(content_length) > max_response_size:
+        step_context.logger.error(f"Response too large: {content_length} bytes")
+        return {
+            'status': 'error',
+            'error': f'Response size {content_length} bytes exceeds limit of {max_response_size} bytes'
+        }
+
+    # Read body with size limit
+    body = response.content[:max_response_size]
+    if len(response.content) > max_response_size:
+        step_context.logger.error("Response body exceeded size limit")
+        return {
+            'status': 'error',
+            'error': f'Response body exceeds limit of {max_response_size} bytes'
+        }
+
+    data = json.loads(body)
+
+    step_context.logger.info(f"API call successful: {response.status_code}")
+    return {
+        'status': 'success',
+        'status_code': response.status_code,
+        'data': data
+    }
+
+
+@durable_execution
+def lambda_handler(event, context) -> dict:
+    """
+    Lambda handler using AWS Durable Execution
+    """
+    context.logger.info("Starting durable REST API call")
+
+    # Get API URL from event or use default
+    api_url = event.get('url', DEFAULT_API_URL)
+
+    context.logger.info(f"Using API URL: {api_url}")
+
+    # Execute the REST API call as a durable step
+    # Transient failures (timeouts, connection errors) will raise exceptions,
+    # allowing the durable execution SDK to automatically retry the step.
+    try:
+        result = context.step(call_rest_api(api_url), config=step_config)
+    except Exception as e:
+        context.logger.error(f"Step failed after retries: {str(e)}")
+        return {
+            'statusCode': 502,
+            'headers': {'Content-Type': 'application/json'},
+            'body': json.dumps({
+                'error': 'API call failed after retries',
+                'url': api_url,
+                'details': str(e)
+            })
+        }
+
+    # Optional: Add a wait period (demonstrates durable wait without consuming CPU)
+    context.logger.info("Waiting 2 seconds before returning response")
+    context.wait(Duration.from_seconds(2))
+
+    context.logger.info("Durable execution completed")
+
+    # Return response based on result
+    if result['status'] == 'success':
+        return {
+            'statusCode': 200,
+            'headers': {'Content-Type': 'application/json'},
+            'body': json.dumps({
+                'message': 'API call successful',
+                'url': api_url,
+                'data': result['data']
+            })
+        }
+    else:
+        return {
+            'statusCode': 500,
+            'headers': {'Content-Type': 'application/json'},
+            'body': json.dumps({
+                'error': 'API call failed',
+                'url': api_url,
+                'details': result.get('error')
+            })
+        }

lambda-durable-rest-api-sam-py/src/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+aws-durable-execution-sdk-python