Lambda@Edge Function Controller

A simple and efficient controller for managing AWS Lambda@Edge functions in CloudFront distributions.

Overview

Lambda@Edge Function Controller is a TypeScript library that provides a clean API for attaching and detaching Lambda@Edge functions to/from CloudFront distributions. It handles the complex CloudFront configuration updates automatically, making it easy to manage edge functions in your CDN setup.

Features

• Simple API: Easy-to-use methods for attaching and detaching Lambda@Edge functions
• Event Type Support: Supports all Lambda@Edge event types (viewer-request, viewer-response, origin-request, origin-response)
• Automatic Configuration: Automatically generates and updates CloudFront distribution configurations
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• AWS SDK v3: Built with the latest AWS SDK for JavaScript v3
• Logging: Built-in logging with Bunyan for debugging and monitoring
• Flexible Configuration: Support for custom AWS clients and configurations

Use Cases

• A/B Testing: Quickly switch between different Lambda@Edge functions for testing
• Feature Flags: Enable/disable features at the edge without redeploying
• Security Updates: Rapidly deploy security patches to edge functions
• Performance Optimization: Test different edge function configurations
• Development Workflow: Manage edge functions across different environments
• Disaster Recovery: Quickly rollback to previous edge function versions

Installation

npm install lambda-edge-controller
# or
yarn add lambda-edge-controller

Quick Start

Basic Usage

import{LambdaEdgeController}from'lambda-edge-controller';// Create a controller instanceconstcontroller=newLambdaEdgeController('arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1','viewer-request');// Attach the Lambda@Edge function to a CloudFront distributionawaitcontroller.attachEdgeFunction('E1234567890ABCD');// Detach the Lambda@Edge function from a CloudFront distributionawaitcontroller.detachEdgeFunction('E1234567890ABCD');

Advanced Usage with Custom Configuration

import{LambdaEdgeController}from'lambda-edge-controller';import{CloudFrontClient}from'@aws-sdk/client-cloudfront';// Create a custom CloudFront clientconstcloudfrontClient=newCloudFrontClient({region: 'us-east-1',credentials: {accessKeyId: 'YOUR_ACCESS_KEY',secretAccessKey: 'YOUR_SECRET_KEY'}});// Create controller with custom clientconstcontroller=newLambdaEdgeController('arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1','viewer-request',{cloudfront: cloudfrontClient});// Enable debug loggingcontroller.enableDebugger();// Attach edge functionawaitcontroller.attachEdgeFunction('E1234567890ABCD');

API Reference

Constructor

newLambdaEdgeController(lambdaArn: string,eventType?: EventType,client?: ControllerClient)

Parameters:

• lambdaArn: The ARN of your Lambda@Edge function
• eventType: The CloudFront event type (default: 'viewer-request')
• client: Optional custom AWS clients

Event Types:

• viewer-request: Function executes before CloudFront forwards a request to the origin
• viewer-response: Function executes before CloudFront returns the response to the viewer
• origin-request: Function executes before CloudFront forwards the request to the origin
• origin-response: Function executes after CloudFront receives the response from the origin

Methods

attachEdgeFunction(distributionId: string): Promise<any>

Attaches the Lambda@Edge function to the specified CloudFront distribution.

detachEdgeFunction(distributionId: string): Promise<any>

Removes the Lambda@Edge function from the specified CloudFront distribution.

enableDebugger(): this

Enables detailed logging for debugging purposes.

disableDebugger(): this

Disables detailed logging.

Testing with Examples

The project includes comprehensive examples and testing utilities in the examples/ directory.

Setup for Testing

1. Install dependencies:

# Install project dependencies
npm install
# Install examples dependenciescd examples
npm install

2. Build the library:

# From project root
npm run build

3. Configure environment:

cd examples
npm run setup
# This creates a .env file from env.example

4. Edit .env file:

# Required settings
LAMBDA_ARN=arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1
CLOUDFRONT_DISTRIBUTION_ID=E1234567890ABCD
# Optional settings
EVENT_TYPE=viewer-request
AWS_REGION=us-east-1
AWS_PROFILE=default
DEBUG=true

Running Tests

Unit Tests

# Run all unit tests
npm test# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:dev

Integration Tests

# Run the comprehensive integration testcd examples
npm test# Or directly
node aws-test.js

Manual Testing

# Test specific functionality
node -e "const { LambdaEdgeController } = require('../dist/index.js');const controller = new LambdaEdgeController('your-lambda-arn', 'viewer-request');console.log('Controller created successfully');"

Test Coverage

The examples directory provides:

• Basic Tests: Controller creation and configuration validation
• Advanced Tests: Custom AWS client configuration
• Integration Tests: Real AWS environment testing
• Error Handling: Comprehensive error scenarios
• Configuration Validation: Environment setup verification

Development

Prerequisites

• Node.js >= 14.0.0
• AWS credentials with CloudFront permissions
• TypeScript knowledge

Development Commands

# Install dependencies
npm install
# Run linter
npm run lint
npm run lint --fix
# Run tests
npm test
npm run test:watch
# Build
npm run build
# Generate documentation
npm run doc

Required IAM Permissions

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudfront:GetDistribution",
"cloudfront:UpdateDistribution"
],
"Resource": "*"
}
]
}

Release Process

Prerequisites

• All changes committed and pushed to remote repository
• GitHub access token configured for conventional-github-releaser
• npm account access for publishing

Release Steps

1. Commit and push changes:

git add .
git commit -m "feat: add new feature"# Use conventional commit format
git push origin main

2. Build the library:

npm run build

3. Update version and create release:

npm version patch # or minor, major

This command automatically:

• Updates version in package.json
• Creates Git tag
• Pushes tag to remote repository
• Creates GitHub release
• Updates CHANGELOG.md

4. Verify release artifacts:

# Check if tag was created
git tag -l | tail -3
# Check if CHANGELOG was updated
git log --oneline -2

5. Publish to npm:

npm publish

Version Management

• patch: Bug fixes and minor updates (1.2.1 → 1.2.2)
• minor: New features (1.2.1 → 1.3.0)
• major: Breaking changes (1.2.1 → 2.0.0)

Automated Processes

The release process uses several npm scripts that run automatically:

• postversion: Automatically executes after npm version
• push:tag: Pushes Git tag to remote repository
• create:release: Creates GitHub release with conventional changelog
• create:changelog: Updates local CHANGELOG.md file

Troubleshooting

If the automated release process fails:

# Manually execute release scripts
npm run push:tag
npm run create:release
npm run create:changelog

Check GitHub repository settings and ensure proper authentication tokens are configured.

Architecture

The library consists of three main components:

1. LambdaEdgeController: Main controller class for managing edge functions
2. ConfigUpdator: Handles CloudFront configuration updates
3. Models: TypeScript interfaces and types

Class Diagram

LambdaEdgeController
├── CloudFrontClient (AWS SDK)
├── ConfigUpdator
└── Logger (Bunyan)
ConfigUpdator
├── Lambda ARN management
├── Event type handling
└── Distribution config updates

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the commit message convention (Conventional Commits)
4. Run tests and linting
5. Submit a pull request

Commit Message Format

git commit -m "<type>[optional scope]: <description>[optional body][optional footer]"

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Generated Docs
• Examples: Examples Directory

Related Links

• AWS Lambda@Edge Documentation
• CloudFront API Reference
• AWS SDK for JavaScript v3
• Conventional Commits

---

日本語版: README_ja.md