aws-lambda — Cursor rule: what it does, how to install

---
description: Definitive guidelines for writing secure, performant, and maintainable AWS Lambda functions using modern best practices.
globs: **/*
---
# aws-lambda Best Practices

This guide outlines the definitive best practices for developing AWS Lambda functions. Adhere to these principles to build reliable, cost-effective, and secure serverless applications.

## Code Organization and Structure

**1. Single Responsibility Principle:** Each Lambda function must perform one distinct task. Decompose complex workflows into smaller, focused functions orchestrated by services like AWS Step Functions.

**2. Initialize Outside the Handler:** Leverage execution environment reuse by initializing SDK clients, database connections, and heavy dependencies in the global scope.

❌ BAD:
```python
import boto3

def handler(event, context):
    s3 = boto3.client('s3') # Initialized on every invocation
    # ...
```

✅ GOOD:
```python
import boto3

s3 = boto3.client('s3') # Initialized once per execution environment

def handler(event, context):
    # s3 client is reused across invocations
    # ...
```

**3. Use Lambda Layers for Shared Code:** Keep deployment packages small and promote code reuse for common libraries and dependencies.

**4. Configuration via Environment Variables:** Never hardcode operational parameters. Use environment variables for dynamic configuration. For sensitive data, use AWS Secrets Manager or AWS Systems Manager Parameter Store.

**5. Structured JSON Logging:** Output logs in JSON format to CloudWatch. This makes logs easily queryable and analyzable. Use `aws-lambda-powertools` Logger utility.

❌ BAD:
```python
print(f"Processing event: {event}")
```

✅ GOOD:
```python
from aws_lambda_powertools import Logger
logger = Logger()

@logger.inject_lambda_context
def handler(event, context):
    logger.info("Processing event", event=event)
    # ...
```

**6. Infrastructure as Code (AWS CDK v2):** Define your Lambda functions and their surrounding infrastructure (API Gateway, DynamoDB, IAM roles) using AWS CDK v2. This ensures version control, repeatability, and safe deployments.

✅ GOOD:
```python
# Example using AWS CDK v2 (Python)
from aws_cdk import Stack, aws_lambda as lambda_
from constructs import Construct

class MyLambdaStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        lambda_.Function(self, "MyHandler",
            runtime=lambda_.Runtime.PYTHON_3_12,
            handler="index.handler",
            code=lambda_.Code.from_asset("lambda"), # 'lambda' directory contains index.py
            environment={
                "TABLE_NAME": "MyTable",
            },
            # Add more configurations like memory, timeout, IAM roles
        )
```

## Common Patterns and Anti-patterns

**1. Implement Idempotency:** Design functions to produce the same result even if invoked multiple times with the same input. Use `aws-lambda-powertools` for robust idempotency.

❌ BAD:
```python
# No idempotency check, might process duplicate events
def handler(event, context):
    order_id = event['detail']['orderId']
    # Process order, could be duplicated
    # ...
```

✅ GOOD:
```python
from aws_lambda_powertools.utilities.idempotency import idempotent
from aws_lambda_powertools.utilities.idempotency.persistence import DynamoDBPersistenceLayer
import os

persistence_layer = DynamoDBPersistenceLayer(table_name=os.environ["IDEMPOTENCY_TABLE"])

@idempotent(persistence_layer=persistence_layer)
def handler(event, context):
    order_id = event['detail']['orderId']
    # Process order, guaranteed to run once
    # ...
```

**2. Stateless Functions:** Functions must not rely on mutable local state between invocations. Any mutable data belongs in external, durable storage (e.g., DynamoDB, S3).

**3. Orchestrate with Step Functions:** For complex, multi-step workflows, use AWS Step Functions to manage state and coordination. Keep individual Lambda functions simple.

## Performance Considerations

**1. Optimize Memory and CPU:** Memory allocation directly impacts CPU. Use the AWS Lambda Power Tuning tool to find the optimal memory configuration for your function.

**2. Keep Deployment Packages Small:** Minimize cold start times by reducing package size. Use Lambda Layers and only include necessary dependencies.

**3. Use Keep-Alive for Persistent Connections:** Prevent idle connections from being purged, especially for HTTP clients.

✅ GOOD:
```python
import http.client
import ssl

# Global scope for connection reuse
http_client = http.client.HTTPSConnection("example.com", context=ssl._create_unverified_context())

def handler(event, context):
    http_client.request("GET", "/api/data")
    response = http_client.getresponse()
    # ...
```

## Common Pitfalls and Gotchas

**1. Over-privileged IAM Roles:** Apply the principle of least privilege. Grant only the minimum necessary permissions to your function's execution role.

❌ BAD:
```json
{
  "Effect": "Allow",
  "Action": "s3:*", // Too broad
  "Resource": "*"
}
```

✅ GOOD:
```json
{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject"
  ],
  "Resource": "arn:aws:s3:::my-specific-bucket/*" // Specific bucket and actions
}
```

**2. Lack of Input Validation:** Always validate and sanitize all incoming event data to prevent injection attacks and unexpected behavior. Use libraries like Pydantic or `aws-lambda-powertools` Parser utility.

**3. Recursive Invocations:** Avoid functions calling themselves directly or indirectly, as this can lead to infinite loops and escalated costs.

**4. Unhandled Errors:** Ensure all potential errors are caught and handled gracefully. Throw explicit exceptions for unrecoverable issues. Use `async/await` for asynchronous operations.

## Testing Approaches

**1. Unit Testing:** Focus on testing the core business logic of your function in isolation, mocking AWS service interactions.

**2. Integration Testing:** Test your function's interactions with actual AWS services. Use ephemeral resources provisioned by CDK.

**3. End-to-End Testing:** Simulate real-world scenarios, testing the entire flow from event source to final outcome.

**4. Local Development and Testing:** Utilize tools like AWS SAM CLI or LocalStack to test functions locally before deployment.