@thunder-so/thunder 1.3.1 → 1.3.2

package/docs/lambda-basic.md

@@ -0,0 +1,178 @@
+# Deploy a Serverless API with AWS Lambda and API Gateway
+
+Run your Node.js backend on [AWS Lambda](https://aws.amazon.com/lambda/) with an [API Gateway HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) as the public endpoint. No servers to provision, scales to zero when idle, and pay only for what you use.
+
+Works with any framework that exports a Lambda handler: [Express.js](https://expressjs.com/), [Hono](https://hono.dev/), [Fastify](https://fastify.dev/), [NestJS](https://nestjs.com/), [Koa](https://koajs.com/), and more.
+
+## AWS Resources
+
+| Resource | Purpose |
+|---|---|
+| [Lambda Function](https://aws.amazon.com/lambda/) | Runs your server code |
+| [API Gateway HTTP API](https://aws.amazon.com/api-gateway/) | Public HTTP endpoint, routes all traffic to Lambda |
+| [CloudWatch Logs](https://aws.amazon.com/cloudwatch/) | Function logs, retained for 1 month |
+| [ACM Certificate](https://aws.amazon.com/certificate-manager/) | SSL for custom domain (optional) |
+| [Route53](https://aws.amazon.com/route53/) | DNS A + AAAA records (optional) |
+
+## Prerequisites
+
+- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) configured
+- [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) bootstrapped:
+  ```bash
+  cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1
+  ```
+- Your function built to a `dist/` directory with an `index.handler` export
+
+## Installation
+
+```bash
+bun add @thunder-so/thunder --development
+# or
+npm install @thunder-so/thunder --save-dev
+```
+
+## Handler Requirements
+
+Your Lambda handler must follow the [AWS Lambda handler signature](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html). For HTTP APIs, use the v2 payload format:
+
+```typescript
+// src/index.ts
+export const handler = async (event: any) => {
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ message: 'Hello from Lambda' }),
+  };
+};
+```
+
+For Express/Hono/Fastify, use an adapter like [`@hono/node-server`](https://hono.dev/docs/getting-started/aws-lambda) or [`serverless-http`](https://github.com/dougmoscrop/serverless-http):
+
+```typescript
+// src/index.ts (Hono example)
+import { Hono } from 'hono';
+import { handle } from 'hono/aws-lambda';
+
+const app = new Hono();
+app.get('/', (c) => c.json({ message: 'Hello' }));
+
+export const handler = handle(app);
+```
+
+## Stack File
+
+```typescript
+import { Cdk, Lambda, type LambdaProps } from '@thunder-so/thunder';
+
+const config: LambdaProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'api',
+  environment: 'dev',
+
+  rootDir: '.',
+
+  functionProps: {
+    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
+    architecture: Cdk.aws_lambda.Architecture.ARM_64,
+    codeDir: 'dist',       // directory containing your built handler
+    handler: 'index.handler',
+    memorySize: 512,
+    timeout: 10,
+  },
+};
+
+new Lambda(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## Deploy
+
+```bash
+# Build your app first
+npm run build
+
+# Deploy
+npx cdk deploy --app "npx tsx stack/dev.ts" --profile default
+```
+
+CDK outputs the API Gateway URL:
+
+```
+Outputs:
+myapp-api-dev-stack.ApiGatewayUrl = https://abc123.execute-api.us-east-1.amazonaws.com
+```
+
+## Custom Domain (Optional)
+
+1. [Create a Route53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)
+2. [Request an ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) in the **same region as your function**
+
+```typescript
+const config: LambdaProps = {
+  // ...
+  domain: 'api.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+> Unlike Static, the Lambda certificate must be **regional** (same region as the function), not global.
+
+## Environment Variables
+
+```typescript
+functionProps: {
+  // ...
+  variables: [
+    { NODE_ENV: 'production' },
+    { API_BASE_URL: 'https://api.example.com' },
+  ],
+},
+```
+
+## Secrets from AWS Secrets Manager
+
+Store sensitive values in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and inject them as environment variables at deploy time:
+
+```bash
+aws secretsmanager create-secret \
+  --name "/myapp/DATABASE_URL" \
+  --secret-string "postgres://user:pass@host/db"
+```
+
+```typescript
+functionProps: {
+  // ...
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123' },
+  ],
+},
+```
+
+Thunder automatically grants the Lambda execution role `secretsmanager:GetSecretValue` on each secret.
+
+## Stack Outputs
+
+| Output | Description |
+|---|---|
+| `ApiGatewayUrl` | API Gateway endpoint URL |
+| `LambdaFunction` | Lambda function name |
+| `LambdaFunctionUrl` | Direct Lambda URL (only if `url: true`) |
+| `Route53Domain` | Custom domain URL (only if domain is configured) |
+
+## Destroy
+
+```bash
+npx cdk destroy --app "npx tsx stack/dev.ts" --profile default
+```
+
+## Next Steps
+
+- [lambda-containers.md](./lambda-containers.md) - Container images and Bun runtime with Lambda
+- [lambda-full.md](./lambda-full.md) - Full configuration reference

package/docs/lambda-containers.md

@@ -0,0 +1,179 @@
+# AWS Lambda with Container Images and Bun Runtime
+
+Deploy AWS Lambda functions as Docker container images to use custom runtimes like [Bun](https://bun.sh/), ship larger packages, or include system-level dependencies. Thunder builds and pushes the image to [Amazon ECR](https://aws.amazon.com/ecr/) automatically during `cdk deploy`.
+
+Use container Lambda when:
+
+- Your deployment package exceeds the 250 MB zip limit
+- You need a runtime not natively supported by Lambda (e.g. Bun)
+- You want to use system-level dependencies (native modules, binaries)
+## Node.js Container Image
+
+### 1. Create a Dockerfile
+
+```dockerfile
+# Dockerfile
+FROM public.ecr.aws/lambda/nodejs:22 AS builder
+WORKDIR ${LAMBDA_TASK_ROOT}
+
+COPY . .
+RUN npm ci
+RUN npm run build
+
+FROM public.ecr.aws/lambda/nodejs:22
+WORKDIR ${LAMBDA_TASK_ROOT}
+
+COPY --from=builder /var/task/dist/ ./
+COPY --from=builder /var/task/node_modules ./node_modules
+
+CMD ["index.handler"]
+```
+
+### 2. Stack File
+
+```typescript
+import { Cdk, Lambda, type LambdaProps } from '@thunder-so/thunder';
+
+const config: LambdaProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'api',
+  environment: 'prod',
+  rootDir: '.',
+
+  functionProps: {
+    dockerFile: 'Dockerfile',   // path relative to rootDir
+    memorySize: 1792,
+    timeout: 10,
+    variables: [{ NODE_ENV: 'production' }],
+  },
+};
+
+new Lambda(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+> When `dockerFile` is set, `runtime`, `architecture`, `codeDir`, `handler`, `include`, and `exclude` are ignored - the Dockerfile controls the build entirely.
+
+## Bun Runtime Container Image
+
+[Bun](https://bun.sh/) is a fast JavaScript runtime with native TypeScript support. Since Lambda doesn't have a managed Bun runtime, you deploy it as a container.
+
+### 1. Create the Bun Dockerfile
+
+```dockerfile
+# Dockerfile.bun
+
+# Stage 1: Build the Bun Lambda bootstrap
+FROM oven/bun:latest AS bun
+WORKDIR /tmp
+RUN apt-get update && apt-get install -y curl
+RUN curl -fsSL https://raw.githubusercontent.com/oven-sh/bun/main/packages/bun-lambda/runtime.ts -o runtime.ts
+RUN bun install aws4fetch
+RUN bun build --compile runtime.ts --outfile bootstrap
+
+# Stage 2: Build your app
+FROM oven/bun:latest AS builder
+WORKDIR /tmp
+COPY . .
+RUN bun install
+RUN bun run build
+
+# Stage 3: Runtime image
+FROM public.ecr.aws/lambda/provided:al2023
+WORKDIR ${LAMBDA_TASK_ROOT}
+
+COPY --from=bun /usr/local/bin/bun /opt/bun
+COPY --from=bun /tmp/bootstrap ${LAMBDA_RUNTIME_DIR}
+COPY --from=builder /tmp/dist/ ./
+COPY --from=builder /tmp/node_modules ./node_modules
+COPY --from=builder /tmp/lambda-bun.js ./lambda-bun.js
+
+CMD ["lambda-bun.fetch"]
+```
+
+### 2. Create the Bun Handler Shim
+
+Bun's Lambda runtime expects a `fetch`-compatible handler:
+
+```javascript
+// lambda-bun.js
+const { handler } = require('./index.js');
+exports.fetch = handler;
+```
+
+If you're using [Hono](https://hono.dev/) with Bun:
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.get('/', (c) => c.json({ ok: true }));
+
+export default app;  // Bun's fetch handler
+```
+
+### 3. Stack File
+
+```typescript
+import { Cdk, Lambda, type LambdaProps } from '@thunder-so/thunder';
+
+const config: LambdaProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'api',
+  environment: 'prod',
+  rootDir: '.',
+
+  functionProps: {
+    dockerFile: 'Dockerfile.bun',
+    memorySize: 512,
+    timeout: 10,
+    keepWarm: true,
+  },
+};
+
+new Lambda(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+## Docker Build Arguments
+
+Pass build-time arguments to your Dockerfile:
+
+```typescript
+functionProps: {
+  dockerFile: 'Dockerfile',
+  dockerBuildArgs: ['NODE_ENV=production', 'APP_VERSION=1.2.3'],
+},
+```
+
+In your Dockerfile:
+```dockerfile
+ARG NODE_ENV
+ARG APP_VERSION
+```
+
+## Keep Warm
+
+Container Lambdas have longer cold starts than zip-based functions. Use `keepWarm` to schedule an EventBridge ping every 5 minutes:
+
+```typescript
+functionProps: {
+  dockerFile: 'Dockerfile',
+  keepWarm: true,
+},
+```
+
+This creates an [EventBridge rule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) that invokes the function with a synthetic API Gateway v2 event.
+
+## Notes on Container Deployments
+
+- The entire `rootDir` is used as the Docker build context
+- CDK builds and pushes the image to [Amazon ECR](https://aws.amazon.com/ecr/) automatically during `cdk deploy`
+- `timeout`, `memorySize`, `tracing`, `keepWarm`, `variables`, and `secrets` all work the same as zip deployments
+- For more on Lambda container images, see the [AWS docs](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html)
+
+## Related
+
+- [lambda-basic.md](./lambda-basic.md) - Basic zip-based deployment
+- [lambda-full.md](./lambda-full.md) - Full configuration reference

package/docs/lambda-full.md

@@ -0,0 +1,185 @@
+# Lambda Configuration Reference
+
+Complete reference for every option available in the `Lambda` construct. Covers zip and container deployments, concurrency, secrets, custom domains, and VPC integration. For a quick start see [lambda-basic.md](./lambda-basic.md).
+
+## Examples
+
+### Zip Deployment
+
+```typescript
+import { Cdk, Lambda, type LambdaProps } from '@thunder-so/thunder';
+
+const config: LambdaProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'api',
+  environment: 'prod',
+  rootDir: '.',
+
+  domain: 'api.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+
+  functionProps: {
+    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
+    architecture: Cdk.aws_lambda.Architecture.ARM_64,
+    codeDir: 'dist',
+    handler: 'index.handler',
+    include: ['package.json'],
+    exclude: ['**/*.test.js'],
+    memorySize: 1792,
+    timeout: 10,
+    tracing: true,
+    reservedConcurrency: 10,
+    provisionedConcurrency: 2,
+    keepWarm: true,
+    url: true,
+    variables: [
+      { NODE_ENV: 'production' },
+      { LOG_LEVEL: 'info' },
+    ],
+    secrets: [
+      { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+    ],
+  },
+};
+
+new Lambda(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+### Container Deployment
+
+```typescript
+import { Cdk, Lambda, type LambdaProps } from '@thunder-so/thunder';
+
+const config: LambdaProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'api',
+  environment: 'prod',
+  rootDir: '.',
+
+  domain: 'api.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+
+  functionProps: {
+    dockerFile: 'Dockerfile',
+    dockerBuildArgs: ['NODE_ENV=production'],
+    memorySize: 1792,
+    timeout: 10,
+    tracing: true,
+    keepWarm: true,
+    variables: [
+      { NODE_ENV: 'production' },
+    ],
+    secrets: [
+      { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+    ],
+  },
+};
+
+new Lambda(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+## Property Reference
+
+### Identity (`AppProps`)
+
+| Property | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `env.account` | `string` | Yes | - | AWS account ID |
+| `env.region` | `string` | Yes | - | AWS region |
+| `application` | `string` | Yes | - | Project name |
+| `service` | `string` | Yes | - | Service name |
+| `environment` | `string` | Yes | - | Environment label |
+| `rootDir` | `string` | No | `.` | Root of your app |
+| `debug` | `boolean` | No | `false` | Enable verbose logging |
+
+### Custom Domain
+
+| Property | Type | Description |
+|---|---|---|
+| `domain` | `string` | Public domain, e.g. `api.example.com` |
+| `regionalCertificateArn` | `string` | ACM certificate ARN - **must be in the same region as the function** |
+| `hostedZoneId` | `string` | Route53 hosted zone ID |
+
+### `functionProps`
+
+#### Zip Deployment
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `runtime` | `Runtime` | `NODEJS_20_X` | Lambda runtime. See [supported runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) |
+| `architecture` | `Architecture` | `ARM_64` | `ARM_64` or `X86_64`. ARM is cheaper and often faster |
+| `codeDir` | `string` | `.` | Directory containing your built handler, relative to `rootDir` |
+| `handler` | `string` | `index.handler` | Handler in `file.export` format |
+| `include` | `string[]` | - | Extra files to copy into `codeDir` before packaging (e.g. `package.json`) |
+| `exclude` | `string[]` | `['**/*.svg', '**/*.map', ...]` | Glob patterns to exclude from the zip |
+
+#### Container Deployment
+
+| Property | Type | Description |
+|---|---|---|
+| `dockerFile` | `string` | Path to Dockerfile relative to `rootDir`. Enables container mode. |
+| `dockerBuildArgs` | `string[]` | Build args in `KEY=VALUE` format, passed to `docker build --build-arg` |
+
+When `dockerFile` is set, `runtime`, `architecture`, `codeDir`, `handler`, `include`, and `exclude` are ignored.
+
+#### Performance
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `memorySize` | `number` | `1792` | Memory in MB. Also controls proportional CPU allocation. [Pricing](https://aws.amazon.com/lambda/pricing/) |
+| `timeout` | `number` | `10` | Max execution time in seconds (max 900) |
+| `tracing` | `boolean` | `false` | Enable [AWS X-Ray](https://aws.amazon.com/xray/) tracing |
+
+#### Concurrency
+
+| Property | Type | Description |
+|---|---|---|
+| `reservedConcurrency` | `number` | Hard cap on simultaneous executions. Prevents the function from consuming all account concurrency. |
+| `provisionedConcurrency` | `number` | Pre-warmed instances. Eliminates cold starts for latency-sensitive workloads. Incurs additional cost. |
+
+See [Lambda concurrency docs](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html).
+
+#### Warm-up
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `keepWarm` | `boolean` | `false` | Creates an EventBridge rule that pings the function every 5 minutes to prevent cold starts |
+| `url` | `boolean` | `false` | Enables a [Lambda Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html) (public, no auth) in addition to API Gateway |
+
+#### Environment
+
+| Property | Type | Description |
+|---|---|---|
+| `variables` | `Array<{ [key: string]: string }>` | Plain environment variables |
+| `secrets` | `{ key: string; resource: string }[]` | Secrets Manager ARNs injected as env vars. Lambda is automatically granted read access. |
+
+### VPC
+
+| Property | Type | Description |
+|---|---|---|
+| `vpc` | `IVpc \| IVpcLink` | Attach the Lambda to an existing VPC. Useful for accessing RDS, ElastiCache, or other private resources. |
+
+## API Gateway Details
+
+- Uses [HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) (v2) - lower latency and cost than REST API
+- Routes `GET` and `HEAD /{proxy+}` to the Lambda function
+- No CORS preflight configured by default (add it in your handler if needed)
+- Custom domain uses a regional endpoint with TLS 1.2
+
+## Stack Outputs
+
+| Output | Description |
+|---|---|
+| `ApiGatewayUrl` | API Gateway endpoint |
+| `LambdaFunction` | Lambda function name |
+| `LambdaFunctionUrl` | Lambda Function URL (only if `url: true`) |
+| `Route53Domain` | Custom domain URL (only if domain is configured) |
+
+## Related
+
+- [lambda-basic.md](./lambda-basic.md) - Quick start
+- [lambda-containers.md](./lambda-containers.md) - Container images and Bun runtime with Lambda