AWS Lambda and Serverless Explained — Architecture, Triggers, and Real-World Patterns

import boto3
import json
import os
from PIL import Image
import io

# ✅ Initialise the S3 client OUTSIDE the handler.
# This runs once when the container boots (cold start),
# then gets reused across all warm invocations — saving ~50ms per call.
s3_client = boto3.client('s3')

# Target width for all resized thumbnails
THUMBNAIL_WIDTH = 200


def handler(event, context):
    """
    Triggered by an S3 PUT event whenever a new image is uploaded
    to the 'uploads-raw' bucket. Resizes it and saves a thumbnail
    to the 'uploads-thumbnails' bucket.
    """

    # The event payload from S3 contains a list of records —
    # each record represents one file upload.
    for record in event['Records']:
        source_bucket = record['s3']['bucket']['name']
        object_key    = record['s3']['object']['key']  # e.g. 'photos/sunset.jpg'

        print(f"Processing: s3://{source_bucket}/{object_key}")

        # Download the original image bytes into memory (no temp file needed)
        response      = s3_client.get_object(Bucket=source_bucket, Key=object_key)
        image_bytes   = response['Body'].read()

        # Open image with Pillow and calculate proportional height
        original_img  = Image.open(io.BytesIO(image_bytes))
        original_w, original_h = original_img.size
        ratio         = THUMBNAIL_WIDTH / original_w
        new_height    = int(original_h * ratio)

        thumbnail     = original_img.resize((THUMBNAIL_WIDTH, new_height))

        # Save resized image to an in-memory buffer — Lambda has no persistent disk
        output_buffer = io.BytesIO()
        thumbnail.save(output_buffer, format='JPEG', quality=85)
        output_buffer.seek(0)  # Rewind buffer to the start before uploading

        # Write thumbnail to the destination bucket under the same key name
        destination_bucket = os.environ['THUMBNAIL_BUCKET']  # Read from env vars, not hardcoded
        s3_client.put_object(
            Bucket      = destination_bucket,
            Key         = object_key,
            Body        = output_buffer,
            ContentType = 'image/jpeg'
        )

        print(f"Thumbnail saved: s3://{destination_bucket}/{object_key} ({THUMBNAIL_WIDTH}x{new_height})")

    # Lambda expects a return value when invoked synchronously (e.g. via API Gateway).
    # For async triggers like S3, the return value is ignored — but it's good practice.
    return {
        'statusCode': 200,
        'body': json.dumps({'processed': len(event['Records'])})
    }

import json
import boto3
import uuid
import os
from datetime import datetime, timezone

# DynamoDB resource initialised at cold-start — reused on warm invocations
dynamodb    = boto3.resource('dynamodb')
orders_table = dynamodb.Table(os.environ['ORDERS_TABLE_NAME'])


def handler(event, context):
    """
    Handles POST /orders from API Gateway (Lambda Proxy Integration).
    Creates a new order record in DynamoDB and returns the order ID.

    API Gateway event shape (key fields):
      event['httpMethod']         -> 'POST'
      event['path']               -> '/orders'
      event['body']               -> Raw JSON string of the request body
      event['requestContext']     -> Metadata including caller identity
    """

    http_method = event.get('httpMethod', '')

    # Route guard — this function only handles order creation
    if http_method != 'POST':
        return _build_response(405, {'error': f'Method {http_method} not allowed'})

    # API Gateway sends the body as a raw string — we must parse it
    try:
        request_body = json.loads(event.get('body') or '{}')
    except json.JSONDecodeError:
        return _build_response(400, {'error': 'Request body must be valid JSON'})

    # Validate required fields before touching the database
    required_fields = ['customer_id', 'items', 'total_amount']
    missing_fields  = [f for f in required_fields if f not in request_body]
    if missing_fields:
        return _build_response(400, {'error': f'Missing required fields: {missing_fields}'})

    # Build the order record
    order_id    = str(uuid.uuid4())  # Unique ID for this order
    created_at  = datetime.now(timezone.utc).isoformat()  # ISO 8601, always UTC

    order_record = {
        'order_id':      order_id,
        'customer_id':   request_body['customer_id'],
        'items':         request_body['items'],
        'total_amount':  str(request_body['total_amount']),  # DynamoDB doesn't support float natively
        'status':        'PENDING',
        'created_at':    created_at
    }

    # Write to DynamoDB — put_item overwrites if the key already exists,
    # so ConditionExpression ensures we never silently stomp an existing order
    orders_table.put_item(
        Item=order_record,
        ConditionExpression='attribute_not_exists(order_id)'
    )

    print(f"Order created: {order_id} for customer {request_body['customer_id']}")

    return _build_response(201, {
        'order_id':   order_id,
        'status':     'PENDING',
        'created_at': created_at
    })


def _build_response(status_code, body_dict):
    """
    Constructs the response object API Gateway expects.
    CORS headers are included so browser-based clients can call this API.
    Without these headers, browsers silently block the response.
    """
    return {
        'statusCode': status_code,
        'headers': {
            'Content-Type':                'application/json',
            'Access-Control-Allow-Origin': '*'  # Tighten to your domain in production
        },
        'body': json.dumps(body_dict)
    }

# AWS SAM (Serverless Application Model) template — the standard way to
# define Lambda functions as Infrastructure-as-Code.
# Run: sam build && sam deploy --guided

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Description: Orders API — production-grade Lambda configuration

Globals:
  Function:
    # Runtime for all functions in this template unless overridden
    Runtime: python3.12
    # Timeout generous enough for DynamoDB + downstream calls, not infinite
    Timeout: 30
    # Environment variables available to all functions
    Environment:
      Variables:
        LOG_LEVEL:          INFO
        ORDERS_TABLE_NAME:  !Ref OrdersTable

Resources:

  OrdersApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: orders-api-handler
      CodeUri:       src/
      Handler:       orders_api_handler.handler

      # 512 MB gives ~4x CPU vs 128 MB — worth it for JSON parsing + DynamoDB calls
      # Run AWS Lambda Power Tuning tool to find YOUR optimal memory setting
      MemorySize: 512

      # Provisioned concurrency: 5 containers always warm for the production alias
      # This eliminates cold starts for the first 5 concurrent requests
      # Cost: ~$0.0000041 per GB-second × 5 containers × all hours in month
      AutoPublishAlias: live
      ProvisionedConcurrencyConfig:
        ProvisionedConcurrentExecutions: 5

      # IAM permissions — principle of least privilege
      # Only grant what this specific function actually needs
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref OrdersTable

      # API Gateway trigger — Lambda Proxy Integration (recommended)
      Events:
        CreateOrder:
          Type:  Api
          Properties:
            Path:   /orders
            Method: POST

        # OPTIONS method needed for browser CORS preflight requests
        CreateOrderOptions:
          Type:  Api
          Properties:
            Path:   /orders
            Method: OPTIONS

  OrdersTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName:    orders
      BillingMode:  PAY_PER_REQUEST  # Serverless billing — no provisioned capacity to manage
      AttributeDefinitions:
        - AttributeName: order_id
          AttributeType: S
      KeySchema:
        - AttributeName: order_id
          KeyType:        HASH

      # Point-in-time recovery — always enable for production data
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true

Outputs:
  OrdersApiEndpoint:
    Description: "API Gateway endpoint for the Orders API"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/orders"