Skip to content

Commit 60819fd

Browse files
hidetaka-dchidetaka-dc
committed
chore: upgrade dependencies and fix examples script
- Upgrade Jest from 24.9.0 to 29.7.0 - Upgrade TypeScript from 3.6.2 to 5.5.0 - Upgrade ESLint from 6.3.0 to 8.57.0 - Upgrade Rollup from 1.20.3 to 4.9.0 - Remove AWS SDK v3 mock file (no longer needed) - Fix examples/aws-test.js to use correct eventType variable - Update configuration files for modern toolchain - Add ESM support and modern TypeScript features
1 parent 83da325 commit 60819fd

12 files changed

Lines changed: 4631 additions & 4578 deletions

File tree

‎.eslintrc.yml‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,16 @@ extends:
33
- plugin:@typescript-eslint/recommended
44
plugins:
55
- "@typescript-eslint"
6+
- n
67

78
parser: "@typescript-eslint/parser"
89
env:
9-
es6: true
10+
es2022: true
1011
node: true
1112
parserOptions:
1213
sourceType: 'module'
13-
ecmaFeatures:
14-
ts: true
14+
ecmaVersion: 2022
15+
project: './tsconfig.json'
1516
globals:
1617
describe: false
1718
it: false
@@ -22,4 +23,6 @@ globals:
2223
jasmine: false
2324
expect: false
2425
rules:
25-
"@typescript-eslint/explicit-function-return-type": off
26+
"@typescript-eslint/explicit-function-return-type": "off"
27+
"@typescript-eslint/no-unused-vars": "error"
28+
"@typescript-eslint/no-explicit-any": "warn"

‎README.md‎

Lines changed: 298 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,323 @@
1-
# Lambda@edge function controller
1+
# Lambda@Edge Function Controller
22

3-
Simply manager for Lambda@edge.
3+
A simple and efficient controller for managing AWS Lambda@Edge functions in CloudFront distributions.
44

5-
## Getting started
5+
## Overview
66

7+
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.
8+
9+
## Features
10+
11+
- **Simple API**: Easy-to-use methods for attaching and detaching Lambda@Edge functions
12+
- **Event Type Support**: Supports all Lambda@Edge event types (viewer-request, viewer-response, origin-request, origin-response)
13+
- **Automatic Configuration**: Automatically generates and updates CloudFront distribution configurations
14+
- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
15+
- **AWS SDK v3**: Built with the latest AWS SDK for JavaScript v3
16+
- **Logging**: Built-in logging with Bunyan for debugging and monitoring
17+
- **Flexible Configuration**: Support for custom AWS clients and configurations
18+
19+
## Use Cases
20+
21+
- **A/B Testing**: Quickly switch between different Lambda@Edge functions for testing
22+
- **Feature Flags**: Enable/disable features at the edge without redeploying
23+
- **Security Updates**: Rapidly deploy security patches to edge functions
24+
- **Performance Optimization**: Test different edge function configurations
25+
- **Development Workflow**: Manage edge functions across different environments
26+
- **Disaster Recovery**: Quickly rollback to previous edge function versions
27+
28+
## Installation
29+
30+
```bash
31+
npm install lambda-edge-controller
32+
# or
33+
yarn add lambda-edge-controller
34+
```
35+
36+
## Quick Start
37+
38+
### Basic Usage
39+
40+
```typescript
41+
import { LambdaEdgeController } from 'lambda-edge-controller';
42+
43+
// Create a controller instance
44+
const controller = new LambdaEdgeController(
45+
'arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1',
46+
'viewer-request'
47+
);
48+
49+
// Attach the Lambda@Edge function to a CloudFront distribution
50+
await controller.attachEdgeFunction('E1234567890ABCD');
51+
52+
// Detach the Lambda@Edge function from a CloudFront distribution
53+
await controller.detachEdgeFunction('E1234567890ABCD');
54+
```
55+
56+
### Advanced Usage with Custom Configuration
57+
58+
```typescript
59+
import { LambdaEdgeController } from 'lambda-edge-controller';
60+
import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
61+
62+
// Create a custom CloudFront client
63+
const cloudfrontClient = new CloudFrontClient({
64+
region: 'us-east-1',
65+
credentials: {
66+
accessKeyId: 'YOUR_ACCESS_KEY',
67+
secretAccessKey: 'YOUR_SECRET_KEY'
68+
}
69+
});
70+
71+
// Create controller with custom client
72+
const controller = new LambdaEdgeController(
73+
'arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1',
74+
'viewer-request',
75+
{ cloudfront: cloudfrontClient }
76+
);
77+
78+
// Enable debug logging
79+
controller.enableDebugger();
80+
81+
// Attach edge function
82+
await controller.attachEdgeFunction('E1234567890ABCD');
83+
```
84+
85+
## API Reference
86+
87+
### Constructor
88+
89+
```typescript
90+
new LambdaEdgeController(
91+
lambdaArn: string,
92+
eventType?: EventType,
93+
client?: ControllerClient
94+
)
95+
```
96+
97+
**Parameters:**
98+
- `lambdaArn`: The ARN of your Lambda@Edge function
99+
- `eventType`: The CloudFront event type (default: 'viewer-request')
100+
- `client`: Optional custom AWS clients
101+
102+
**Event Types:**
103+
- `viewer-request`: Function executes before CloudFront forwards a request to the origin
104+
- `viewer-response`: Function executes before CloudFront returns the response to the viewer
105+
- `origin-request`: Function executes before CloudFront forwards the request to the origin
106+
- `origin-response`: Function executes after CloudFront receives the response from the origin
107+
108+
### Methods
109+
110+
#### `attachEdgeFunction(distributionId: string): Promise<any>`
111+
Attaches the Lambda@Edge function to the specified CloudFront distribution.
112+
113+
#### `detachEdgeFunction(distributionId: string): Promise<any>`
114+
Removes the Lambda@Edge function from the specified CloudFront distribution.
115+
116+
#### `enableDebugger(): this`
117+
Enables detailed logging for debugging purposes.
118+
119+
#### `disableDebugger(): this`
120+
Disables detailed logging.
121+
122+
## Testing with Examples
123+
124+
The project includes comprehensive examples and testing utilities in the `examples/` directory.
125+
126+
### Setup for Testing
127+
128+
1. **Install dependencies:**
129+
```bash
130+
# Install project dependencies
131+
npm install
132+
133+
# Install examples dependencies
134+
cd examples
135+
npm install
136+
```
137+
138+
2. **Build the library:**
139+
```bash
140+
# From project root
141+
npm run build
142+
```
143+
144+
3. **Configure environment:**
145+
```bash
146+
cd examples
147+
npm run setup
148+
# This creates a .env file from env.example
149+
```
150+
151+
4. **Edit .env file:**
152+
```bash
153+
# Required settings
154+
LAMBDA_ARN=arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1
155+
CLOUDFRONT_DISTRIBUTION_ID=E1234567890ABCD
156+
157+
# Optional settings
158+
EVENT_TYPE=viewer-request
159+
AWS_REGION=us-east-1
160+
AWS_PROFILE=default
161+
DEBUG=true
162+
```
163+
164+
### Running Tests
165+
166+
#### Unit Tests
167+
```bash
168+
# Run all unit tests
169+
npm test
170+
171+
# Run tests in watch mode
172+
npm run test:watch
173+
174+
# Run tests with coverage
175+
npm run test:dev
7176
```
8-
$ git clone YOUR_REPO_URI
9-
$ cd YOUR_REPO_URI
10177

11-
// Put your GitHub Personal Access Token
12-
$ mv .envrc.example .envrc
13-
$ vim .envrc
14-
export CONVENTIONAL_GITHUB_RELEASER_TOKEN=PUT_YOUR_GITHUB_ACCESS_TOKEN
178+
#### Integration Tests
179+
```bash
180+
# Run the comprehensive integration test
181+
cd examples
182+
npm test
183+
184+
# Or directly
185+
node aws-test.js
186+
```
15187

16-
// Install
17-
$ yarn
18-
or
19-
$ npm install
188+
#### Manual Testing
189+
```bash
190+
# Test specific functionality
191+
node -e "
192+
const { LambdaEdgeController } = require('../dist/index.js');
193+
const controller = new LambdaEdgeController('your-lambda-arn', 'viewer-request');
194+
console.log('Controller created successfully');
195+
"
20196
```
21197

198+
### Test Coverage
199+
200+
The examples directory provides:
22201

23-
## Commit message rule
202+
- **Basic Tests**: Controller creation and configuration validation
203+
- **Advanced Tests**: Custom AWS client configuration
204+
- **Integration Tests**: Real AWS environment testing
205+
- **Error Handling**: Comprehensive error scenarios
206+
- **Configuration Validation**: Environment setup verification
24207

25-
The repository runs commitlint.
26-
We have to follow "Conventional Commit" to make a commit message.
208+
## Development
27209

28-
https://www.conventionalcommits.org/en/v1.0.0-beta.4/
210+
### Prerequisites
211+
212+
- Node.js >= 14.0.0
213+
- AWS credentials with CloudFront permissions
214+
- TypeScript knowledge
215+
216+
### Development Commands
29217

30218
```bash
31-
$ git commit -m "<type>[optional scope]: <description>
219+
# Install dependencies
220+
npm install
221+
222+
# Run linter
223+
npm run lint
224+
npm run lint --fix
225+
226+
# Run tests
227+
npm test
228+
npm run test:watch
229+
230+
# Build
231+
npm run build
232+
233+
# Generate documentation
234+
npm run doc
235+
```
236+
237+
### Required IAM Permissions
238+
239+
```json
240+
{
241+
"Version": "2012-10-17",
242+
"Statement": [
243+
{
244+
"Effect": "Allow",
245+
"Action": [
246+
"cloudfront:GetDistribution",
247+
"cloudfront:UpdateDistribution"
248+
],
249+
"Resource": "*"
250+
}
251+
]
252+
}
253+
```
254+
255+
## Architecture
256+
257+
The library consists of three main components:
258+
259+
1. **LambdaEdgeController**: Main controller class for managing edge functions
260+
2. **ConfigUpdator**: Handles CloudFront configuration updates
261+
3. **Models**: TypeScript interfaces and types
262+
263+
### Class Diagram
264+
265+
```
266+
LambdaEdgeController
267+
├── CloudFrontClient (AWS SDK)
268+
├── ConfigUpdator
269+
└── Logger (Bunyan)
270+
271+
ConfigUpdator
272+
├── Lambda ARN management
273+
├── Event type handling
274+
└── Distribution config updates
275+
```
276+
277+
## Contributing
278+
279+
1. Fork the repository
280+
2. Create a feature branch
281+
3. Follow the commit message convention (Conventional Commits)
282+
4. Run tests and linting
283+
5. Submit a pull request
284+
285+
### Commit Message Format
286+
287+
```bash
288+
git commit -m "<type>[optional scope]: <description>
32289
33290
[optional body]
34291
35292
[optional footer]"
36293
```
37294

38-
## Contribution
295+
**Types:**
296+
- `feat`: New feature
297+
- `fix`: Bug fix
298+
- `docs`: Documentation changes
299+
- `style`: Code style changes
300+
- `refactor`: Code refactoring
301+
- `test`: Adding or updating tests
302+
- `chore`: Maintenance tasks
39303

40-
```bash
41-
// clone
42-
$ git clone git@github.com:hideokamoto/lambda-edge-controller.git
43-
$ cd lambda-edge-controller
304+
## License
305+
306+
MIT License - see [LICENSE](LICENSE) file for details.
307+
308+
## Support
44309

45-
// setup
46-
$ yarn
310+
- **Issues**: [GitHub Issues](https://github.com/hideokamoto/lambda-edge-controller/issues)
311+
- **Documentation**: [Generated Docs](./docs/)
312+
- **Examples**: [Examples Directory](./examples/)
47313

48-
// Unit test
49-
$ yarn test
50-
or
51-
$ yarn run test:watch
314+
## Related Links
52315

53-
// Lint
54-
$ yarn run lint
55-
or
56-
$ yarn run lint --fix
316+
- [AWS Lambda@Edge Documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-at-the-edge.html)
317+
- [CloudFront API Reference](https://docs.aws.amazon.com/cloudfront/latest/APIReference/)
318+
- [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/)
319+
- [Conventional Commits](https://www.conventionalcommits.org/)
57320

58-
// Build
59-
$ yarn run build
321+
---
60322

61-
// Rebuild docs
62-
$ yarn run doc
63-
```
323+
**日本語版**: [README_ja.md](README_ja.md)

0 commit comments

Comments
 (0)