@ashishpandeyone/cdk-lambda-web-function 0.1.0 → 0.1.2

package/README.md

@@ -59,7 +59,7 @@ Requests carry `lambda-web-request-id` and `lambda-web-endpoint-name` headers.
 
 ## Regions and endpoints
 
-Each `WebFunction` has one endpoint, `fn.endpoint`:
+Each `WebFunction` has a default endpoint, `fn.endpoint`, configured with the `endpoint` property. [Add more](#more-endpoints) with `fn.addEndpoint()`.
 
 | `endpointType` | URL | Routing |
 |---|---|---|
@@ -84,6 +84,34 @@ new CfnOutput(this, 'UsEast1Url', { value: perRegion.endpoint.regionalUrl('us-ea
 
 - `MULTI_REGION` and `PER_REGION` need at least one region besides the home region; `HOME_REGION` takes none.
 - A MultiRegion endpoint takes about a minute to create.
+- Lambda routes a `MULTI_REGION` endpoint by latency, not by health: it doesn't fail over when a region has problems.
+
+### More endpoints
+
+A function can have up to 10 endpoints, each with its own URL, authentication, regions and limits. For example, a public endpoint next to an IAM-only global one:
+
+```ts
+const api = new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('dist'),
+  authType: WebFunctionAuthType.NONE,              // the default endpoint is public
+  endpoint: { rateLimit: 1000 },                   // requests per second
+});
+
+const internal = api.addEndpoint('Internal', {
+  authType: WebFunctionAuthType.AWS_IAM,
+  endpointType: WebFunctionEndpointType.MULTI_REGION,
+  regions: ['us-east-1', 'eu-west-1'],
+  description: 'Service-to-service traffic',
+  maxEnvironments: 50,
+});
+internal.grantInvoke(consumerRole);
+new CfnOutput(this, 'InternalUrl', { value: internal.url });
+```
+
+- `rateLimit` takes 0 (blocks all traffic), 100–1,000 in steps of 100, or 2,000–10,000 in steps of 1,000; excess requests get HTTP 429. `maxEnvironments` takes 2–10,000.
+- **Both limits apply separately in each region** an endpoint serves from: a 3-region endpoint with `rateLimit: 1000` accepts up to 1,000 requests per second in each region.
+- Endpoints can serve the same regions. The construct owns one `.local` log group per region, whichever endpoints serve it.
 
 ### Changing regions or the endpoint type
 
@@ -91,7 +119,7 @@ An endpoint's type and regions can't change in place: a change creates a **new e
 
 | `endpointName` | Physical name | Changing `regions` or `endpointType` |
 |---|---|---|
-| omitted (recommended) | `default-<hash of type and regions>` | works: new endpoint, new URL |
+| omitted (recommended) | `default-<hash>` for `fn.endpoint`, `<id>-<hash>` for added endpoints; the hash covers the type and regions | works: new endpoint, new URL |
 | set, e.g. `'live'` | `live` | also change the name in the same deployment, or it fails with *The endpoint live already exists* (the stack rolls back and the old endpoint keeps serving) |
 
 The construct warns at synth time when `endpointName` is set.
@@ -107,7 +135,7 @@ The construct warns at synth time when `endpointName` is set.
 fn.grants.invoke(consumerRole); // or fn.grantInvoke(consumerRole), as on lambda.Function
 ```
 
-The grant is on the endpoint's home-region ARN, which IAM evaluates in every region the endpoint serves from, including the global URL.
+The grant is on the endpoint's home-region ARN, which IAM evaluates in every region the endpoint serves from, including the global URL. `fn.grants` covers the default endpoint only; grant other endpoints with their own `grantInvoke()` or `grants.invoke()`.
 
 | Endpoint | How to sign |
 |---|---|
@@ -151,15 +179,114 @@ table.grantReadWriteData(api);           // the default role trusts lambda.amazo
 - Environment variable names starting with `AWS_` are reserved.
 - **Renaming the function replaces it and changes its URL.** A generated name depends on the construct path, so moving the construct renames it too.
 
+### Bundling TypeScript with `NodejsWebFunction`
+
+`NodejsWebFunction` is a `WebFunction` that bundles your server from a TypeScript or JavaScript entry file with esbuild, like `NodejsFunction` does for Lambda functions:
+
+```ts
+new NodejsWebFunction(this, 'Api', {
+  entry: 'src/server.ts',
+  authType: WebFunctionAuthType.AWS_IAM,
+  bundling: {
+    minify: true,                                       // default true
+    sourceMap: true,                                    // default true
+    format: lambdaNodejs.OutputFormat.ESM,              // default ESM (index.mjs); CJS gives index.js
+    externalModules: [],                                // default: bundle everything you import
+  },
+});
+```
+
+- **Defaults:** `runtime` is `NODEJS_24_X`, and the esbuild target follows the runtime (`node24`). The project root is the directory of the nearest lock file above `entry` (override it with `depsLockFilePath` or `projectRoot`).
+- **It also sets what a `lambda.Code` can't:** the entry point that matches the bundle, and `NODE_OPTIONS=--enable-source-maps` when source maps are on, appended to any `NODE_OPTIONS` you set, so stack traces point at your `.ts` files (e.g. `/var/task/src/server.ts:22:12`). Source map paths are relative to the project root, so no build-machine paths are deployed.
+- **ESM bundles include a `require` shim**, so CommonJS dependencies that load Node.js built-ins (Express, for example) work.
+- **The AWS SDK is bundled like any other dependency**, since the runtime has none. Only the clients you import are included.
+- **Bundling runs locally** when esbuild is installed in your project, and otherwise in Docker (an arm64 AWS SAM build image; set `forceDockerBundling` to always use Docker).
+- **Not yet supported:** installing native modules next to the bundle (`nodeModules`) and command hooks. For native dependencies, use `WebFunction` with `Code.fromAsset(..., { bundling: { image, command } })`.
+
 ### Code
 
 `code` takes any `lambda.Code` that produces a zip in S3: `fromAsset`, `fromBucket`/`fromBucketV2`, `fromCustomCommand`, `fromDockerBuild`. Inline code and container images fail at synth time.
 
 Lambda Web Functions download code as the `lambda.amazonaws.com` service principal, from a **versioned** bucket, and the CDK bootstrap bucket allows neither. So each stack gets a small code bucket, and the code is copied into it on deploy.
 
-### Updates
+## Revisions
+
+Any change to code or configuration creates a new **revision** (`fn.currentRevision`), and endpoints switch to it once it's ready. A failed deployment rolls back to the previous revision. If nothing changed, nothing is deployed.
+
+Earlier revisions are kept, so you can roll back or route traffic to them. After each deployment, the construct deletes the oldest beyond `revisionRetention` (default 20, up to 50). It never deletes a revision an endpoint routes to, or one the previous deployment used, which a rollback returns to.
+
+```ts
+new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('dist'),
+  authType: WebFunctionAuthType.AWS_IAM,
+  revisionRetention: 5,
+});
+```
+
+### Routing to earlier revisions
+
+Reference an earlier revision by its ID (for example from a `CfnOutput` of `fn.currentRevision.revisionId`, or `aws lambda-web list-web-function-revisions`). Then pin an endpoint to it, or split traffic between two revisions:
+
+```ts
+const previous = WebFunctionRevision.fromRevisionAttributes(this, 'Previous', {
+  webFunction: fn,
+  revisionId: 'rev-a1b2c',
+});
+
+// Keep the default endpoint on the previous revision, and send 10% to the new one:
+fn.endpoint.routeTraffic(previous, [{ revision: fn.currentRevision, weight: 0.1 }]);
+
+// Or a second endpoint that stays on the previous revision while fn.endpoint moves on:
+fn.addEndpoint('Stable', { authType: WebFunctionAuthType.AWS_IAM, revision: previous });
+```
+
+- An endpoint routes to at most two revisions. The additional revision's `weight` is a whole percentage, from 0.01 to 0.99.
+- To promote, remove `routeTraffic` (or `revision`) and deploy: the endpoint serves the current revision again.
+- Lambda Web Function metrics have no revision dimension. To compare a split's revisions, log a version you control (for example an environment variable) from your application.
+
+### Canary and linear deployments
+
+By default an endpoint moves all its traffic to a new revision at once. With `deployment`, it moves in steps instead, watching CloudWatch alarms: if one goes into ALARM, the endpoint goes back to the revision it served before and the deployment fails, so CloudFormation rolls the stack back.
+
+```ts
+// errorRate: a cloudwatch.IAlarm, for example on the share of 5xx responses
+const api = new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('dist'),
+  authType: WebFunctionAuthType.AWS_IAM,
+  endpoint: {
+    // 10% of the traffic for 10 minutes, then all of it.
+    deployment: WebFunctionDeployment.canary({ percent: 10, bake: Duration.minutes(10), alarms: [errorRate] }),
+  },
+});
+
+// 25% more every 5 minutes. Each endpoint has its own deployment.
+api.addEndpoint('Public', {
+  authType: WebFunctionAuthType.NONE,
+  deployment: WebFunctionDeployment.linear({ percent: 25, interval: Duration.minutes(5), alarms: [errorRate] }),
+});
+```
+
+| | Steps | Limits |
+|---|---|---|
+| `allAtOnce()` (default) | 100% | |
+| `canary({ percent, bake })` | `percent`, then 100% after `bake` | `percent` 1–99, `bake` 1–45 minutes |
+| `linear({ percent, interval })` | `percent` more every `interval` | `percent` 5–50, `interval` from 1 minute, at most 45 minutes in all |
+
+How it works:
+
+- Each deployment that creates a revision (code or configuration) moves the traffic from the revision the endpoint serves at that moment, which is also what it goes back to. If someone switched the endpoint outside CloudFormation, the deployment starts from there.
+- Each step waits until every region of a `MULTI_REGION` or `PER_REGION` endpoint has applied it (usually about 15 seconds), and if a region fails to update, the endpoint goes back as for an alarm. The bake or interval counts from the start of the step.
+- Alarms are checked before the first step (an alarm already in ALARM stops the deployment before any traffic moves), throughout every step, and once the new revision has all the traffic. They can be in any region, and composite alarms work. `INSUFFICIENT_DATA` doesn't stop a deployment.
+- A rollback of the stack, for any reason, moves the traffic back at once, without waiting or checking alarms.
+- A stack's first deployment, and a new endpoint (including one renamed by a region change), serve the revision at once: there's nothing to move from.
+- A deployment can take up to an hour: CloudFormation waits for it before it updates the endpoint. Deployments of different endpoints run in parallel.
+- A canary or linear endpoint always moves to the current revision, so it can't also use `revision`, `additionalRevisions` or `routeTraffic()`. Use `allAtOnce()` to deploy a fix immediately, for example while an alarm is in ALARM.
+
+Lambda Web Function metrics have no revision dimension, so an alarm sees the whole endpoint: at 10%, a new revision's errors are a tenth of the endpoint's. Alarm on a rate, with a threshold low enough to notice that, or publish metrics from your application that carry its version. A bake should be longer than an alarm needs to fire (its period times its evaluation periods).
 
-Any change to code or configuration creates a new **revision**. The endpoint switches to it once it's ready, and the old revision is deleted after the deployment succeeds; a failed deployment rolls back to it. If nothing changed, nothing is deployed.
+The deployment runs in a few resources per stack, created on first use: two Lambda functions, a Step Functions state machine that calls them every 15 seconds, and a log group.
 
 ## Logs in every region
 
@@ -195,10 +322,9 @@ new WebFunction(this, 'Api', {
 
 ## Limitations
 
-- One endpoint per function; no traffic splitting between revisions.
 - Not yet supported: importing existing functions, VPC access (network connectors), resource-policy permissions, KMS encryption, metrics helpers, tracing, and a CloudFront origin.
 - `cdk deploy --hotswap` and `cdk watch` don't support Web Functions.
-- Quotas per account and region: 50 revisions and 10 endpoints per function, 200 Arm vCPUs, 10,000 requests per second.
+- Quotas: 10 endpoints and about 50 revisions per function (Lambda cleans up older revisions automatically), and 10,000 requests per second per endpoint. Per account and region: 100,000 requests per second and 2,000 Arm64 vCPUs (each execution environment uses 2). The account quotas are adjustable, and new accounts start lower. See [Lambda quotas](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html).
 - The stack's custom resource provider Lambda keeps its own log group after the stack is deleted, as with other CDK custom resources.
 
 ## Development