@ashishpandeyone/cdk-lambda-web-function 0.1.10 → 0.1.12

package/.jsii

@@ -9745,7 +9745,7 @@
   },
   "name": "@ashishpandeyone/cdk-lambda-web-function",
   "readme": {
-    "markdown": "# CDK constructs for AWS Lambda Web Functions\n\n<!--BEGIN STABILITY BANNER-->\n\n---\n\n![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n\n<!--END STABILITY BANNER-->\n\n[AWS Lambda Web Functions](https://docs.aws.amazon.com/lambda/latest/dg/web-functions.html) run an ordinary Node.js HTTP server (Express, Fastify, Hono, `node:http`) on Lambda and give it an HTTPS endpoint, optionally served from several regions. `WebFunction` deploys one, following the conventions of `aws-cdk-lib/aws-lambda` where the two services overlap.\n\n```ts fixture=bare\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\nimport { WebFunction, WebFunctionAuthType, WebFunctionEndpointType } from '@ashishpandeyone/cdk-lambda-web-function';\n\nconst fn = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    endpointType: WebFunctionEndpointType.MULTI_REGION,\n    regions: ['us-east-1', 'eu-west-1'],\n  },\n});\n\nnew CfnOutput(this, 'Url', { value: fn.endpoint.url }); // https://<id>.lambda-web.global.on.aws\n```\n\nThe stack's region is the function's **home region**. Multi-region endpoints need a stack with an explicit `env.region`.\n\n## Installation\n\n```bash\nnpm install @ashishpandeyone/cdk-lambda-web-function\n```\n\nIt needs `aws-cdk-lib` 2.273.0 or later and `constructs` 10.5.1 or later (peer dependencies), and Node.js 22 or later. The package is published for TypeScript and JavaScript only.\n\n## Writing the server\n\n1. Listen on the host and port in **`AWS_LAMBDA_HTTP_ENDPOINT`** (`0.0.0.0:3000` today). `PORT` is not set.\n2. Start listening within **10 seconds**, or initialisation fails with `Application.TimeoutListenError`.\n3. Put the entry file at the root of your bundle as **`index.js`**, or set `entrypoint`.\n4. The runtime has **no AWS SDK**: bundle the clients you import.\n5. Code runs on **arm64**.\n\n```js\nconst express = require('express');\n\nconst app = express();\napp.get('/', (req, res) => res.json({ hello: 'world', region: process.env.AWS_REGION }));\n\nconst [host, port] = process.env.AWS_LAMBDA_HTTP_ENDPOINT.split(':');\napp.listen(Number(port), host);\n```\n\nRequests carry `lambda-web-request-id` and `lambda-web-endpoint-name` headers.\n\n## Regions and endpoints\n\nEach `WebFunction` has a default endpoint, `fn.endpoint`, configured with the `endpoint` property. [Add more](#more-endpoints) with `fn.addEndpoint()`.\n\n| `endpointType` | URL | Routing |\n|---|---|---|\n| `HOME_REGION` (default) | `https://<id>.<cell>.lambda-web.<home>.on.aws` | home region only |\n| `MULTI_REGION` | one global `https://<id>.lambda-web.global.on.aws` | nearest region |\n| `PER_REGION` | one URL per region, from `fn.endpoint.regionalUrl(region)` | the region in the hostname |\n\n```ts\nconst perRegion = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    endpointType: WebFunctionEndpointType.PER_REGION,\n    regions: ['us-east-1', 'eu-west-1'],\n  },\n});\n\nnew CfnOutput(this, 'UsEast1Url', { value: perRegion.endpoint.regionalUrl('us-east-1') });\n// perRegion.endpoint.regions is ['<home region>', 'eu-west-1', 'us-east-1']\n```\n\n- `MULTI_REGION` and `PER_REGION` need at least one region besides the home region; `HOME_REGION` takes none.\n- A MultiRegion endpoint takes about a minute to create.\n- Lambda routes a `MULTI_REGION` endpoint by latency, not by health: it doesn't fail over when a region has problems.\n\n### More endpoints\n\nA 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:\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.NONE,              // the default endpoint is public\n  endpoint: { rateLimit: 1000 },                   // requests per second\n});\n\nconst internal = api.addEndpoint('Internal', {\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpointType: WebFunctionEndpointType.MULTI_REGION,\n  regions: ['us-east-1', 'eu-west-1'],\n  description: 'Service-to-service traffic',\n  maxEnvironments: 50,\n});\ninternal.grantInvoke(consumerRole);\nnew CfnOutput(this, 'InternalUrl', { value: internal.url });\n```\n\n- `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.\n- **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.\n- Endpoints can serve the same regions. The construct owns one `.local` log group per region, whichever endpoints serve it.\n\n### Changing regions or the endpoint type\n\nAn endpoint's type and regions can't change in place: a change creates a **new endpoint with a new URL**, and the old one is deleted once the new one is live. Two endpoints of one function can't share a name, so:\n\n| `endpointName` | Physical name | Changing `regions` or `endpointType` |\n|---|---|---|\n| omitted (recommended) | `default-<hash>` for `fn.endpoint`, `<id>-<hash>` for added endpoints; the hash covers the type and regions | works: new endpoint, new URL |\n| 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) |\n\nThe construct warns at synth time when `endpointName` is set.\n\n## Authentication and invoking\n\n| `authType` | Meaning |\n|---|---|\n| `AWS_IAM` | Callers sign requests (SigV4 or SigV4a, signing name `lambda`) and need `lambda:InvokeWebFunctionEndpoint` |\n| `NONE` | **Public**: Lambda does no authentication; your application does (JWT, sessions). The `Authorization` header reaches your application untouched. The construct warns at synth time |\n\n```ts\nfn.grants.invoke(consumerRole); // or fn.grantInvoke(consumerRole), as on lambda.Function\n```\n\nThe 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()`.\n\n| Endpoint | How to sign |\n|---|---|\n| `HOME_REGION` | SigV4 for the home region |\n| `PER_REGION` | SigV4 for the hostname's region, or SigV4a |\n| `MULTI_REGION` | **SigV4a with region set `*`**: you can't know which region will serve the request |\n\n```js\nimport { SignatureV4a } from '@smithy/signature-v4a';\nimport { Sha256 } from '@aws-crypto/sha256-js';\nimport { fromNodeProviderChain } from '@aws-sdk/credential-providers';\n\nconst host = new URL(url).hostname; // url: the endpoint's URL\nconst signer = new SignatureV4a({ service: 'lambda', region: '*', sha256: Sha256, credentials: fromNodeProviderChain() });\nconst signed = await signer.sign(\n  { method: 'GET', protocol: 'https:', hostname: host, path: '/', headers: { host } },\n  { signingRegion: '*' },\n);\nconst response = await fetch(`https://${host}/`, { headers: signed.headers });\n```\n\n### Other accounts and AWS services\n\nA caller in another account needs permission twice: in its own IAM policy, and in the function's **resource policy**. `grantInvoke` handles the function's side: a role in the function's account only gets an IAM policy statement, while a principal in another account or an AWS service also gets a statement in the resource policy.\n\n```ts\nfn.grantInvoke(iam.Role.fromRoleArn(this, 'Partner', 'arn:aws:iam::444455556666:role/caller'));\n```\n\nFor principals you can't grant to (a whole account, an organization, an AWS service with conditions), use `addPermission`. The `id` becomes the statement's `Sid`:\n\n```ts\nfn.addPermission('PartnerAccount', { principal: new iam.AccountPrincipal('444455556666') });\nfn.addPermission('MyOrg', { principal: new iam.OrganizationPrincipal('o-a1b2c3d4e5'), endpoint: fn.endpoint });\nfn.addPermission('Cdn', {\n  principal: new iam.ServicePrincipal('cloudfront.amazonaws.com'),\n  sourceArn: `arn:aws:cloudfront::${this.account}:distribution/EDFDVBD6EXAMPLE`,\n});\n```\n\n`addPermission` allows calling every endpoint unless you pass `endpoint`. For other actions, such as letting another account create revisions, use `fn.addToResourcePolicy(statement)`. Statements use the endpoint ARN for invoking and the function ARN for actions on the function.\n\n- **Each stack writes only its own statements.** A Web Function has a single resource policy, and Web Functions have no `AddPermission`. So each stack that adds statements gets a custom resource (`Custom::LambdaWebResourcePolicyStatements`). It reads the policy, replaces the statements that stack wrote before, and writes the policy back, retrying if another writer changed it in the meantime. Statements from other stacks, and ones added outside CloudFormation, are kept. Writers include the function's stack, a stack with a CloudFront distribution, and a stack that imports the function in the same account.\n- **Sids are unique in the policy.** `addPermission`'s `id` becomes the statement's `Sid`, and other statements get a generated one (`Cdk<hash><n>`). If another stack or tool already uses that `Sid` for different content, the deployment fails with the `Sid`.\n- **Don't also attach an `AWS::Lambda::ResourcePolicy` yourself.** That resource replaces the whole document on every update, dropping every other writer's statements.\n- **Public policies are rejected.** Lambda refuses a policy that lets anyone call the function, and the construct fails synthesis first. A `*` principal is only accepted with a condition that pins the caller, such as `aws:PrincipalOrgID` (`iam.OrganizationPrincipal`) or `aws:SourceAccount`. For a public endpoint, use `authType: NONE`.\n- **Scope AWS services to your resource.** Lambda accepts a service principal with no condition, which would let that service call the endpoint on behalf of any account. The construct warns unless you give `sourceArn` or `sourceAccount` (or an `aws:SourceArn`, `aws:SourceAccount`, `aws:SourceOrgID` or `aws:SourceOrgPaths` condition).\n- Lambda copies the policy to every region the function's endpoints serve from. The copy is eventually consistent, and in tests changes applied in every region within seconds.\n\n### CloudFront\n\nPut a CloudFront distribution (`aws-cdk-lib/aws-cloudfront`) in front of an `AWS_IAM` endpoint to serve the public with a custom domain, caching and AWS WAF. Viewers don't sign anything, and only your distribution may call the endpoint:\n\n```ts\nnew cloudfront.Distribution(this, 'Cdn', {\n  defaultBehavior: {\n    origin: WebFunctionOrigin.withOriginAccessControl(fn.endpoint),\n    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,\n    allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,\n    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,\n    originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,\n  },\n});\n```\n\n`withOriginAccessControl` adds:\n- an origin access control (origin type `lambda`, signing behavior `always-amz-auth`, the only one CloudFront accepts for Web Function origins), one per stack and signing protocol: SigV4 for a regional domain, SigV4a for a `MULTI_REGION` endpoint's global domain;\n- a statement in the function's resource policy that allows `cloudfront.amazonaws.com` to call this endpoint on behalf of this distribution only (`aws:SourceArn`).\n\nSome things to know:\n- **Forward everything except `Host`.** The endpoint answers 404 when `Host` is the distribution's domain, so use `ALL_VIEWER_EXCEPT_HOST_HEADER` (not `ALL_VIEWER`), or a policy of your own without `Host`.\n- **Your application can still authenticate viewers.** CloudFront signs in its own headers and passes the viewer's `Authorization` header (a JWT, for example) through unchanged, but only when `Authorization` is in the cache policy. CloudFront drops it from `GET` and `HEAD` requests otherwise:\n\n  ```ts\n  const forwardAuthorization = new cloudfront.CachePolicy(this, 'ForwardAuthorization', {\n    headerBehavior: cloudfront.CacheHeaderBehavior.allowList('Authorization'),\n    minTtl: Duration.seconds(0),\n    defaultTtl: Duration.seconds(0),\n    maxTtl: Duration.seconds(1), // a cache key with headers needs caching enabled; 0/0/1 keeps it off in practice\n  });\n  ```\n- Request bodies work without clients sending `x-amz-content-sha256`: CloudFront signs `POST`, `PUT` and `PATCH` requests with an unsigned payload.\n- A `PER_REGION` endpoint's origin calls one region: the home region, or the one you pass as `region`. Use one origin per region, for example in an origin group.\n- A `MULTI_REGION` endpoint can't include opt-in regions (such as `me-central-1`), because CloudFront can't sign for them. The construct fails synthesis.\n- The distribution can be in another stack, in the function's account. Its stack writes the CloudFront statement into the function's resource policy, so the function's stack doesn't depend on it.\n- That stack can also be in another region, for example us-east-1 for an ACM certificate. CDK then passes the endpoint's domain and ARN with its cross-region references: SSM parameters plus custom resources of its own.\n- **Those references are strong by default.** A change that replaces the endpoint gives it a new domain and ARN. That includes a new endpoint type or region set, or a renamed function. The function's stack can't update a value while the distribution's stack still uses the old one, the same as with `Fn::ImportValue` in one region. Deploy such a change in two steps, or use weak references: CDK's synth warning `@aws-cdk/core:crossStackReferencesDefaultStrong` explains how.\n- Lambda@Edge origin-request and origin-response triggers aren't supported on behaviors with this origin.\n- The endpoint stays reachable at its own domain for signed requests your policies allow. Until a new distribution finishes deploying, requests through it can get a transient 403.\n- `new WebFunctionOrigin(endpoint)` is for a public (`NONE`) endpoint, for example behind AWS WAF. Lambda doesn't authenticate those requests, so the endpoint's own domain stays public too.\n\n### Functions defined elsewhere\n\nImport a Web Function defined in another stack or app to grant access to it, read its metrics, or reference its revisions:\n\n```ts\nconst orders = WebFunction.fromWebFunctionArn(this, 'Orders', 'arn:aws:lambda:us-east-1:111122223333:web-function/orders');\norders.grantInvoke(consumerRole);             // every endpoint of the function\n\nconst live = WebFunction.fromWebFunctionAttributes(this, 'Live', {\n  webFunctionName: 'orders',                  // in this stack's account and region\n  endpointName: 'live',                       // grantInvoke allows this endpoint only\n});\nlive.metricConcurrentRequests().createAlarm(this, 'Busy', { threshold: 60, evaluationPeriods: 3 });\n```\n\nAn imported function's metrics default to its own region. Its endpoints, revisions and log groups stay with the stack that defines it.\n\nAn imported function works like a `WebFunction` here. `grantInvoke` and `addToResourcePolicy` write the importing stack's statements into the function's resource policy, in the function's region. This works only when the function is in the stack's account. For a function in another account, `grantInvoke` adds to the caller's IAM policy only, and `addToResourcePolicy` adds nothing and warns, so ask that account to allow the caller.\n\n## Configuration\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('build'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  entrypoint: 'server.js',               // default index.js\n  webFunctionName: 'orders-api',         // default: generated from the construct path\n  description: 'Orders HTTP API',\n  environment: { TABLE_NAME: table.tableName },\n  timeout: Duration.seconds(60),         // per request: 3 seconds to 15 minutes, default 30 seconds\n  maxConcurrencyPerEnvironment: 32,      // requests per environment at once: 1-128, default 64\n});\n\napi.addEnvironment('FEATURE_FLAG', 'on');\ntable.grantReadWriteData(api);           // the default role trusts lambda.amazonaws.com\n```\n\n- **Each execution environment has 2 vCPUs and 2 GB of memory.** There's no memory setting as on Lambda functions; scale with `maxConcurrencyPerEnvironment` and more environments instead.\n- Requests handled by one environment share module-level state, so keep handlers concurrency-safe.\n- Environment variable names starting with `AWS_` are reserved.\n- **The default execution role can only write to the function's own log groups**: the home region's, and the `.local` copy in every region it serves from. That's the minimum AWS documents for Web Functions. It doesn't use `AWSLambdaBasicExecutionRole`, which can also create any log group. Pass `role` to use your own, and include those log permissions.\n- **Renaming the function replaces it and changes its URL.** A generated name depends on the construct path, so moving the construct renames it too.\n\n### Defaults for every function (property injection)\n\nTo give every function under a scope the same defaults, register a property injector for `WebFunction.PROPERTY_INJECTION_ID`, as you would for aws-cdk-lib's constructs. For example, a team's log retention:\n\n```ts\nclass TeamDefaults implements IPropertyInjector {\n  public readonly constructUniqueId = WebFunction.PROPERTY_INJECTION_ID;\n  public inject(originalProps: WebFunctionProps): WebFunctionProps {\n    // The team's defaults, with explicit props winning.\n    return Object.assign({ logRetention: logs.RetentionDays.ONE_MONTH }, originalProps);\n  }\n}\nPropertyInjectors.of(this).add(new TeamDefaults()); // or on the app, for every stack\n```\n\n- An injector applies to functions created under the scope it's added to. The nearest one wins.\n- `NodejsWebFunction` has its own ID (`NodejsWebFunction.PROPERTY_INJECTION_ID`). Its injector runs first, then `WebFunction`'s, as with aws-cdk-lib's `NodejsFunction` and `Function`.\n\n### Bundling TypeScript with `NodejsWebFunction`\n\n`NodejsWebFunction` is a `WebFunction` that bundles your server from a TypeScript or JavaScript entry file with esbuild, like `NodejsFunction` does for Lambda functions:\n\n```ts\nnew NodejsWebFunction(this, 'Api', {\n  entry: 'src/server.ts',\n  authType: WebFunctionAuthType.AWS_IAM,\n  bundling: {\n    minify: true,                                       // default true\n    sourceMap: true,                                    // default true\n    format: lambdaNodejs.OutputFormat.ESM,              // default ESM (index.mjs); CJS gives index.js\n    externalModules: [],                                // default: bundle everything you import\n  },\n});\n```\n\n- **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`).\n- **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.\n- **ESM bundles include a `require` shim**, so CommonJS dependencies that load Node.js built-ins (Express, for example) work.\n- **The AWS SDK is bundled like any other dependency**, since the runtime has none. Only the clients you import are included.\n- **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).\n- **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 } })`.\n\n### Code\n\n`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.\n\nLambda 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. The bucket is emptied and deleted with the stack.\n\nCopying code, managing the function's log groups in every region, looking up regional URLs, cleaning up old revisions, creating rollback alarms in other regions and emptying the code bucket all run in one custom resource Lambda per stack. Its logs go to a log group the stack owns, kept for a month and deleted with the stack.\n\n## Revisions\n\nAny 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.\n\nEarlier 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.\n\n```ts\nnew WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  revisionRetention: 5,\n});\n```\n\n### Routing to earlier revisions\n\nReference 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:\n\n```ts\nconst previous = WebFunctionRevision.fromRevisionAttributes(this, 'Previous', {\n  webFunction: fn,\n  revisionId: 'rev-a1b2c',\n});\n\n// Keep the default endpoint on the previous revision, and send 10% to the new one:\nfn.endpoint.routeTraffic(previous, [{ revision: fn.currentRevision, weight: 0.1 }]);\n\n// Or a second endpoint that stays on the previous revision while fn.endpoint moves on:\nfn.addEndpoint('Stable', { authType: WebFunctionAuthType.AWS_IAM, revision: previous });\n```\n\n- An endpoint routes to at most two revisions. The additional revision's `weight` is a whole percentage, from 0.01 to 0.99.\n- To promote, remove `routeTraffic` (or `revision`) and deploy: the endpoint serves the current revision again.\n- 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.\n\n### Canary and linear deployments\n\nBy 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.\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    // 10% of the traffic for 10 minutes, then all of it; back if more than 2% of requests get a 5XX.\n    deployment: WebFunctionDeployment.canary({ percent: 10, bake: Duration.minutes(10), rollbackOn: { serverErrorRate: 2 } }),\n  },\n});\n\n// 25% more every 5 minutes, watching an alarm of your own. Each endpoint has its own deployment.\n// errorRate: any cloudwatch.IAlarm, e.g. on a metric your application publishes.\napi.addEndpoint('Public', {\n  authType: WebFunctionAuthType.NONE,\n  deployment: WebFunctionDeployment.linear({ percent: 25, interval: Duration.minutes(5), alarms: [errorRate] }),\n});\n```\n\n| | Steps | Limits |\n|---|---|---|\n| `allAtOnce()` (default) | 100% | |\n| `canary({ percent, bake })` | `percent`, then 100% after `bake` | `percent` 1–99, `bake` 1–45 minutes |\n| `linear({ percent, interval })` | `percent` more every `interval` | `percent` 5–50, `interval` from 1 minute, at most 45 minutes in all |\n\nHow it works:\n\n- 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.\n- 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.\n- 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.\n- A rollback of the stack, for any reason, moves the traffic back at once, without waiting or checking alarms.\n- 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.\n- A deployment can take up to an hour: CloudFormation waits for it before it updates the endpoint. Deployments of different endpoints run in parallel.\n- 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.\n\n#### Rollback alarms\n\n`rollbackOn` makes the endpoint create alarms on its own error rates, and the deployment watches them alongside any `alarms` you pass:\n\n| `rollbackOn` | Default | |\n|---|---|---|\n| `serverErrorRate` | none | roll back when more than this % of requests get a 5XX |\n| `clientErrorRate` | none | the same for 4XX (including 429s from `rateLimit` and `maxEnvironments`) |\n| `minimumRequests` | 10 | periods with fewer requests don't count, so one failed request out of two doesn't roll back |\n| `period`, `evaluationPeriods` | 1 minute, 2 | consecutive periods over the threshold before rolling back |\n\n- **One alarm per threshold in every region the endpoint serves from.** Metrics are published in the region that served the request, and an alarm can only watch metrics in its own region. The home region's alarm is a normal CloudFormation alarm; the others are created and deleted with the endpoint by a custom resource, and named `LambdaWeb-<function>-<endpoint>-5xx-rate` (or `-4xx-rate`). `endpoint.rollbackAlarms` lists them all, e.g. to add notifications to the home region's.\n- **The alarms see the whole endpoint.** Lambda Web Function metrics have no revision dimension, so at 10% a new revision's errors are about a tenth of the endpoint's: set the threshold low enough to notice that, or alarm on metrics your application publishes with its version.\n- **5XX includes the platform's 503s** while the endpoint scales up for a sudden burst, not only your application's errors.\n- **A step should outlast the alarm.** CloudWatch needs `period` × `evaluationPeriods`, plus a couple of minutes of delay, to fire; the construct warns when a canary's bake or a linear interval is shorter.\n\nThe 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.\n\n## Metrics\n\nEndpoints and functions have helpers for their CloudWatch metrics (namespace `AWS/Lambda/Web`), like `lambda.Function`'s:\n\n```ts\nfn.endpoint.metricServerErrorRate().createAlarm(this, 'ErrorRate', { threshold: 1, evaluationPeriods: 3 });\nfn.endpoint.metricRequestThrottles().createAlarm(this, 'Throttled', { threshold: 10, evaluationPeriods: 3 });\nfn.metricConcurrentRequests().createAlarm(this, 'Saturated', { threshold: 60, evaluationPeriods: 3 });\n```\n\n| Endpoint | Metric |\n|---|---|\n| `metricRequests()` | `ExecutedRequests` (there's no separate 2XX count) |\n| `metricClientErrors()`, `metricServerErrors()` | `HTTPResponseStatusClass4XX`, `HTTPResponseStatusClass5XX` |\n| `metricClientErrorRate()`, `metricServerErrorRate()` | 4XX or 5XX as a % of requests (math expression) |\n| `metricActiveEnvironments()` | `EndpointActiveEnvironments`, to compare with `maxEnvironments` |\n| `metricRequestThrottles()`, `metricEnvironmentThrottles()` | 429s from `rateLimit` and from `maxEnvironments` |\n\n| Function | Metric |\n|---|---|\n| `metricConcurrentRequests()` | `EnvironmentConcurrentRequests` (maximum), to compare with `maxConcurrencyPerEnvironment` |\n| `metricMaxMemoryUsage()` | `EnvironmentMaxMemoryUsage` (maximum) |\n| `metricActiveTime()`, `metricCpuTime()`, `metricResponseBytes()` | `EnvironmentActiveTime`, `EnvironmentCPUTime`, `ResponseBytes` |\n\n- **Metrics stay in the region that served the request**; unlike logs, they aren't copied to the home region. Every helper takes `region`. Dashboards can show any region, but an alarm can only use metrics from its own stack's region.\n- 4XX, 5XX and the throttle metrics only exist once they're non-zero: alarm on them with `treatMissingData: NOT_BREACHING`. The rate helpers count missing errors as 0.\n- There's no latency metric. Publish one from your application (e.g. with the CloudWatch embedded metric format).\n\n## Logs in every region\n\nWeb Functions log in two tiers:\n\n```text\n every serving region               home region\n ┌──────────────────┐              ┌──────────────────────────────────────────┐\n │ <group>.local    │── copied ───►│ <group>   every region's logs            │\n │ (that region's   │  (seconds)   │ streams …[rev]<instance>-<acct>-<region> │\n │  environments)   │              │ <group>.local  (home-region traffic)     │\n └──────────────────┘              └──────────────────────────────────────────┘\n```\n\n**Query `fn.logGroup`**, the home-region group that receives every region's logs. The service would create missing groups without retention and never delete them, so the construct creates and owns all of them: both home-region groups, and `<group>.local` in every other region any of its endpoints serves from.\n\n```ts\nnew WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  logRetention: logs.RetentionDays.THREE_MONTHS,    // default ONE_MONTH, every group in every region\n  logRemovalPolicy: RemovalPolicy.DESTROY,           // default RETAIN\n  applicationLogLevelV2: lambda.ApplicationLogLevel.WARN,\n  systemLogLevelV2: lambda.SystemLogLevel.INFO,      // DEBUG, INFO or WARN\n});\n```\n\n- The default group is `/aws/lambda/web/<function name>`. Log lines are JSON; application lines carry `requestId`, `endpointName` and `region`.\n- Every event is stored twice (`.local` plus the home-region copy), so expect about double log ingestion, plus cross-region transfer.\n- With `DESTROY`, deletion waits about a minute after the function is gone, because environments flush their last lines late.\n- Subscribe only to `fn.logGroup`: subscribing to the `.local` groups as well delivers every event twice.\n\n## cdk-nag\n\nThe library acknowledges the [cdk-nag](https://github.com/cdklabs/cdk-nag) AwsSolutions findings on the resources it creates, each with a reason, so they don't show up in your reports:\n\n| Finding | Resource | Reason |\n|---|---|---|\n| IAM5 (wildcards) | the default execution role | log streams of the function's own log groups, in every region it serves from |\n| IAM5 | the deployment handlers' role (canary and linear deployments) | their own log group, `cloudwatch:DescribeAlarms` (composite alarms need `*`), and the revisions and endpoints of the functions they deploy |\n| IAM4, IAM5, SF1, SF2 | the CDK Provider framework behind deployments | CDK's own functions and waiter state machine |\n| S1 (access logs) | the stack's code bucket | it only holds copies of the stack's code assets |\n\n- **This works with both cdk-nag versions**, without depending on cdk-nag. cdk-nag 3 reads CDK's `Validations.of(...).acknowledge()`, one ID per finding. cdk-nag 2 reads `cdk_nag` metadata in the template.\n- **Your own statements and resources are still checked.** That includes statements you add to the function's role (`addToRolePolicy`, grants) and your CloudFront distribution's settings.\n- Only the AwsSolutions pack is covered; findings from the HIPAA, NIST and PCI packs aren't acknowledged.\n\n## Upgrading\n\n### From 0.1.5 to 0.1.7, with a resource policy\n\nVersions 0.1.5 to 0.1.7 wrote the function's resource policy with an `AWS::Lambda::ResourcePolicy`. Later versions don't (0.1.7 has the same code as 0.1.6). When an update removes that resource, CloudFormation deletes the function's **whole** resource policy at the end of the update, including the statements the new version just wrote. Callers that rely on the policy then get 403: other accounts, AWS services, and CloudFront.\n\nIf your function has a resource policy (from `addPermission`, a grant to another account or an AWS service, or `WebFunctionOrigin`), first deploy once on the version you have, with the old resource retained:\n\n```ts\n(fn.node.findChild('ResourcePolicy') as CfnResource).applyRemovalPolicy(RemovalPolicy.RETAIN);\n```\n\nThen upgrade, without changing your statements in the same deployment. The new version takes over the statements it writes itself. A statement you removed in the same deployment would stay in the policy.\n\n## Limitations\n\n- Not yet supported: VPC access (network connectors), KMS encryption, and tracing.\n- **Hotswap skips Web Functions without a warning.** `cdk deploy --hotswap` and `cdk watch`, which hotswaps by default, report `(no changes)` for a code or configuration change and the endpoint keeps serving the old revision. Use `cdk watch --hotswap-fallback` (or `cdk deploy --hotswap-fallback`): it deploys Web Function changes through CloudFormation, in about 40 seconds for a home-region endpoint.\n- Fixed limits: 512 MB of code (unzipped) and 32 KB of environment variables per revision, 512 MB of `/tmp` per execution environment, and 128 KiB of headers per request.\n- 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).\n\n## Development\n\nTooling is pinned in `mise.toml` (Node 24, AWS CDK CLI). Personal settings, such as the AWS profile for the live end-to-end tests, go in a git-ignored `mise.local.toml`.\n\n```bash\nmise install\nnpx projen build      # compile, unit tests, lint, API docs\nnpx projen e2e        # deploy, verify and destroy real stacks in three regions (needs AWS credentials)\n```\n"
+    "markdown": "# CDK constructs for AWS Lambda Web Functions\n\n<!--BEGIN STABILITY BANNER-->\n\n---\n\n![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n\n<!--END STABILITY BANNER-->\n\n[AWS Lambda Web Functions](https://docs.aws.amazon.com/lambda/latest/dg/web-functions.html) run an ordinary Node.js HTTP server (Express, Fastify, Hono, `node:http`) on Lambda and give it an HTTPS endpoint, optionally served from several regions. `WebFunction` deploys one, following the conventions of `aws-cdk-lib/aws-lambda` where the two services overlap.\n\n```ts fixture=bare\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\nimport { WebFunction, WebFunctionAuthType, WebFunctionEndpointType } from '@ashishpandeyone/cdk-lambda-web-function';\n\nconst fn = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    endpointType: WebFunctionEndpointType.MULTI_REGION,\n    regions: ['us-east-1', 'eu-west-1'],\n  },\n});\n\nnew CfnOutput(this, 'Url', { value: fn.endpoint.url }); // https://<id>.lambda-web.global.on.aws\n```\n\nThe stack's region is the function's **home region**. Multi-region endpoints need a stack with an explicit `env.region`.\n\n## Installation\n\n```bash\nnpm install @ashishpandeyone/cdk-lambda-web-function\n```\n\nIt needs `aws-cdk-lib` 2.273.0 or later and `constructs` 10.5.1 or later (peer dependencies), and Node.js 22 or later. The package is published for TypeScript and JavaScript only.\n\n## Writing the server\n\n1. Listen on the host and port in **`AWS_LAMBDA_HTTP_ENDPOINT`** (`0.0.0.0:3000` today). `PORT` is not set.\n2. Start listening within **10 seconds**, or initialisation fails with `Application.TimeoutListenError`.\n3. Put the entry file at the root of your bundle as **`index.js`**, or set `entrypoint`.\n4. The runtime has **no AWS SDK**: bundle the clients you import.\n5. Code runs on **arm64**.\n\n```js\nconst express = require('express');\n\nconst app = express();\napp.get('/', (req, res) => res.json({ hello: 'world', region: process.env.AWS_REGION }));\n\nconst [host, port] = process.env.AWS_LAMBDA_HTTP_ENDPOINT.split(':');\napp.listen(Number(port), host);\n```\n\nRequests carry `lambda-web-request-id` and `lambda-web-endpoint-name` headers.\n\n## Regions and endpoints\n\nEach `WebFunction` has a default endpoint, `fn.endpoint`, configured with the `endpoint` property. [Add more](#more-endpoints) with `fn.addEndpoint()`.\n\n| `endpointType` | URL | Routing |\n|---|---|---|\n| `HOME_REGION` (default) | `https://<id>.<cell>.lambda-web.<home>.on.aws` | home region only |\n| `MULTI_REGION` | one global `https://<id>.lambda-web.global.on.aws` | nearest region |\n| `PER_REGION` | one URL per region, from `fn.endpoint.regionalUrl(region)` | the region in the hostname |\n\n```ts\nconst perRegion = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    endpointType: WebFunctionEndpointType.PER_REGION,\n    regions: ['us-east-1', 'eu-west-1'],\n  },\n});\n\nnew CfnOutput(this, 'UsEast1Url', { value: perRegion.endpoint.regionalUrl('us-east-1') });\n// perRegion.endpoint.regions is ['<home region>', 'eu-west-1', 'us-east-1']\n```\n\n- `MULTI_REGION` and `PER_REGION` need at least one region besides the home region; `HOME_REGION` takes none.\n- A MultiRegion endpoint takes about a minute to create.\n- Lambda routes a `MULTI_REGION` endpoint by latency, not by health: it doesn't fail over when a region has problems.\n\n### More endpoints\n\nA 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:\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.NONE,              // the default endpoint is public\n  endpoint: { rateLimit: 1000 },                   // requests per second\n});\n\nconst internal = api.addEndpoint('Internal', {\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpointType: WebFunctionEndpointType.MULTI_REGION,\n  regions: ['us-east-1', 'eu-west-1'],\n  description: 'Service-to-service traffic',\n  maxEnvironments: 50,\n});\ninternal.grantInvoke(consumerRole);\nnew CfnOutput(this, 'InternalUrl', { value: internal.url });\n```\n\n- `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.\n- **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.\n- Endpoints can serve the same regions. The construct owns one `.local` log group per region, whichever endpoints serve it.\n\n### Changing regions or the endpoint type\n\nAn endpoint's type and regions can't change in place: a change creates a **new endpoint with a new URL**, and the old one is deleted once the new one is live. Two endpoints of one function can't share a name, so:\n\n| `endpointName` | Physical name | Changing `regions` or `endpointType` |\n|---|---|---|\n| omitted (recommended) | `default-<hash>` for `fn.endpoint`, `<id>-<hash>` for added endpoints; the hash covers the type and regions | works: new endpoint, new URL |\n| 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) |\n\nThe construct warns at synth time when `endpointName` is set.\n\n## Authentication and invoking\n\n| `authType` | Meaning |\n|---|---|\n| `AWS_IAM` | Callers sign requests (SigV4 or SigV4a, signing name `lambda`) and need `lambda:InvokeWebFunctionEndpoint` |\n| `NONE` | **Public**: Lambda does no authentication; your application does (JWT, sessions). The `Authorization` header reaches your application untouched. The construct warns at synth time |\n\n```ts\nfn.grants.invoke(consumerRole); // or fn.grantInvoke(consumerRole), as on lambda.Function\n```\n\nThe 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()`.\n\n| Endpoint | How to sign |\n|---|---|\n| `HOME_REGION` | SigV4 for the home region |\n| `PER_REGION` | SigV4 for the hostname's region, or SigV4a |\n| `MULTI_REGION` | **SigV4a with region set `*`**: you can't know which region will serve the request |\n\n```js\nimport { SignatureV4a } from '@smithy/signature-v4a';\nimport { Sha256 } from '@aws-crypto/sha256-js';\nimport { fromNodeProviderChain } from '@aws-sdk/credential-providers';\n\nconst host = new URL(url).hostname; // url: the endpoint's URL\nconst signer = new SignatureV4a({ service: 'lambda', region: '*', sha256: Sha256, credentials: fromNodeProviderChain() });\nconst signed = await signer.sign(\n  { method: 'GET', protocol: 'https:', hostname: host, path: '/', headers: { host } },\n  { signingRegion: '*' },\n);\nconst response = await fetch(`https://${host}/`, { headers: signed.headers });\n```\n\n### Other accounts and AWS services\n\nA caller in another account needs permission twice: in its own IAM policy, and in the function's **resource policy**. `grantInvoke` handles the function's side: a role in the function's account only gets an IAM policy statement, while a principal in another account or an AWS service also gets a statement in the resource policy.\n\n```ts\nfn.grantInvoke(iam.Role.fromRoleArn(this, 'Partner', 'arn:aws:iam::444455556666:role/caller'));\n```\n\nFor principals you can't grant to (a whole account, an organization, an AWS service with conditions), use `addPermission`. The `id` becomes the statement's `Sid`:\n\n```ts\nfn.addPermission('PartnerAccount', { principal: new iam.AccountPrincipal('444455556666') });\nfn.addPermission('MyOrg', { principal: new iam.OrganizationPrincipal('o-a1b2c3d4e5'), endpoint: fn.endpoint });\nfn.addPermission('Cdn', {\n  principal: new iam.ServicePrincipal('cloudfront.amazonaws.com'),\n  sourceArn: `arn:aws:cloudfront::${this.account}:distribution/EDFDVBD6EXAMPLE`,\n});\n```\n\n`addPermission` allows calling every endpoint unless you pass `endpoint`. For other actions, such as letting another account create revisions, use `fn.addToResourcePolicy(statement)`. Statements use the endpoint ARN for invoking and the function ARN for actions on the function.\n\n- **Each stack writes only its own statements.** A Web Function has a single resource policy, and Web Functions have no `AddPermission`. So each stack that adds statements gets a custom resource (`Custom::LambdaWebResourcePolicyStatements`). It reads the policy, replaces the statements that stack wrote before, and writes the policy back, retrying if another writer changed it in the meantime. Statements from other stacks, and ones added outside CloudFormation, are kept. Writers include the function's stack, a stack with a CloudFront distribution, and a stack that imports the function in the same account.\n- **Sids are unique in the policy.** `addPermission`'s `id` becomes the statement's `Sid`, and other statements get a generated one (`Cdk<hash><n>`). If another stack or tool already uses that `Sid` for different content, the deployment fails with the `Sid`.\n- **Don't also attach an `AWS::Lambda::ResourcePolicy` yourself.** That resource replaces the whole document on every update, dropping every other writer's statements.\n- **Public policies are rejected.** Lambda refuses a policy that lets anyone call the function, and the construct fails synthesis first. A `*` principal is only accepted with a condition that pins the caller, such as `aws:PrincipalOrgID` (`iam.OrganizationPrincipal`) or `aws:SourceAccount`. For a public endpoint, use `authType: NONE`.\n- **Scope AWS services to your resource.** Lambda accepts a service principal with no condition, which would let that service call the endpoint on behalf of any account. The construct warns unless you give `sourceArn` or `sourceAccount` (or an `aws:SourceArn`, `aws:SourceAccount`, `aws:SourceOrgID` or `aws:SourceOrgPaths` condition).\n- Lambda copies the policy to every region the function's endpoints serve from. The copy is eventually consistent, and in tests changes applied in every region within seconds.\n\n### CloudFront\n\nPut a CloudFront distribution (`aws-cdk-lib/aws-cloudfront`) in front of an `AWS_IAM` endpoint to serve the public with a custom domain, caching and AWS WAF. Viewers don't sign anything, and only your distribution may call the endpoint:\n\n```ts\nnew cloudfront.Distribution(this, 'Cdn', {\n  defaultBehavior: {\n    origin: WebFunctionOrigin.withOriginAccessControl(fn.endpoint),\n    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,\n    allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,\n    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,\n    originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,\n  },\n});\n```\n\n`withOriginAccessControl` adds:\n- an origin access control (origin type `lambda`, signing behavior `always-amz-auth`, the only one CloudFront accepts for Web Function origins), one per stack and signing protocol: SigV4 for a regional domain, SigV4a for a `MULTI_REGION` endpoint's global domain;\n- a statement in the function's resource policy that allows `cloudfront.amazonaws.com` to call this endpoint on behalf of this distribution only (`aws:SourceArn`).\n\nSome things to know:\n- **Forward everything except `Host`.** The endpoint answers 404 when `Host` is the distribution's domain, so use `ALL_VIEWER_EXCEPT_HOST_HEADER` (not `ALL_VIEWER`), or a policy of your own without `Host`.\n- **Your application can still authenticate viewers.** CloudFront signs in its own headers and passes the viewer's `Authorization` header (a JWT, for example) through unchanged, but only when `Authorization` is in the cache policy. CloudFront drops it from `GET` and `HEAD` requests otherwise:\n\n  ```ts\n  const forwardAuthorization = new cloudfront.CachePolicy(this, 'ForwardAuthorization', {\n    headerBehavior: cloudfront.CacheHeaderBehavior.allowList('Authorization'),\n    minTtl: Duration.seconds(0),\n    defaultTtl: Duration.seconds(0),\n    maxTtl: Duration.seconds(1), // a cache key with headers needs caching enabled; 0/0/1 keeps it off in practice\n  });\n  ```\n- Request bodies work without clients sending `x-amz-content-sha256`: CloudFront signs `POST`, `PUT` and `PATCH` requests with an unsigned payload.\n- A `PER_REGION` endpoint's origin calls one region: the home region, or the one you pass as `region`. Use one origin per region, for example in an origin group.\n- A `MULTI_REGION` endpoint can't include opt-in regions (such as `me-central-1`), because CloudFront can't sign for them. The construct fails synthesis.\n- The distribution can be in another stack, in the function's account. Its stack writes the CloudFront statement into the function's resource policy, so the function's stack doesn't depend on it.\n- That stack can also be in another region, for example us-east-1 for an ACM certificate. CDK then passes the endpoint's domain and ARN with its cross-region references: SSM parameters plus custom resources of its own.\n- **Those references are strong by default.** A change that replaces the endpoint gives it a new domain and ARN. That includes a new endpoint type or region set, or a renamed function. The function's stack can't update a value while the distribution's stack still uses the old one, the same as with `Fn::ImportValue` in one region. Deploy such a change in two steps, or use weak references: CDK's synth warning `@aws-cdk/core:crossStackReferencesDefaultStrong` explains how.\n- Lambda@Edge origin-request and origin-response triggers aren't supported on behaviors with this origin.\n- The endpoint stays reachable at its own domain for signed requests your policies allow. Until a new distribution finishes deploying, requests through it can get a transient 403.\n- `new WebFunctionOrigin(endpoint)` is for a public (`NONE`) endpoint, for example behind AWS WAF. Lambda doesn't authenticate those requests, so the endpoint's own domain stays public too.\n\n### Functions defined elsewhere\n\nImport a Web Function defined in another stack or app to grant access to it, read its metrics, or reference its revisions:\n\n```ts\nconst orders = WebFunction.fromWebFunctionArn(this, 'Orders', 'arn:aws:lambda:us-east-1:111122223333:web-function/orders');\norders.grantInvoke(consumerRole);             // every endpoint of the function\n\nconst live = WebFunction.fromWebFunctionAttributes(this, 'Live', {\n  webFunctionName: 'orders',                  // in this stack's account and region\n  endpointName: 'live',                       // grantInvoke allows this endpoint only\n});\nlive.metricConcurrentRequests().createAlarm(this, 'Busy', { threshold: 60, evaluationPeriods: 3 });\n```\n\nAn imported function's metrics default to its own region. Its endpoints, revisions and log groups stay with the stack that defines it.\n\nAn imported function works like a `WebFunction` here. `grantInvoke` and `addToResourcePolicy` write the importing stack's statements into the function's resource policy, in the function's region. This works only when the function is in the stack's account. For a function in another account, `grantInvoke` adds to the caller's IAM policy only, and `addToResourcePolicy` adds nothing and warns, so ask that account to allow the caller.\n\n## Configuration\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('build'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  entrypoint: 'server.js',               // default index.js\n  webFunctionName: 'orders-api',         // default: generated from the construct path\n  description: 'Orders HTTP API',\n  environment: { TABLE_NAME: table.tableName },\n  timeout: Duration.seconds(60),         // per request: 3 seconds to 15 minutes, default 30 seconds\n  maxConcurrencyPerEnvironment: 32,      // requests per environment at once: 1-128, default 64\n});\n\napi.addEnvironment('FEATURE_FLAG', 'on');\ntable.grantReadWriteData(api);           // the default role trusts lambda.amazonaws.com\n```\n\n- **Each execution environment has 2 vCPUs and 2 GB of memory.** There's no memory setting as on Lambda functions; scale with `maxConcurrencyPerEnvironment` and more environments instead.\n- Requests handled by one environment share module-level state, so keep handlers concurrency-safe.\n- Environment variable names starting with `AWS_` are reserved.\n- **The default execution role can only write to the function's own log groups**: the home region's, and the `.local` copy in every region it serves from. That's the minimum AWS documents for Web Functions. It doesn't use `AWSLambdaBasicExecutionRole`, which can also create any log group. Pass `role` to use your own, and include those log permissions.\n- **Renaming the function replaces it and changes its URL.** A generated name depends on the construct path, so moving the construct renames it too.\n\n### Encryption\n\nLambda encrypts each revision's code and environment variables with an AWS owned key. To use your own key, pass `encryptionKey`:\n\n```ts\ndeclare const keyStack: Stack;     // deploys first\ndeclare const replicaStack: Stack; // in us-east-1, deploys before this stack\n\nconst key = new kms.Key(keyStack, 'Key', { multiRegion: true });\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('build'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: { endpointType: WebFunctionEndpointType.PER_REGION, regions: ['us-east-1'] },\n  encryptionKey: key,\n});\n\n// One replica per region the endpoint serves from, with Lambda's statement in its own policy.\nnew kms.CfnReplicaKey(replicaStack, 'KeyReplica', {\n  primaryKeyArn: key.keyArn,\n  keyPolicy: new iam.PolicyDocument({\n    statements: [\n      new iam.PolicyStatement({ principals: [new iam.AccountRootPrincipal()], actions: ['kms:*'], resources: ['*'] }),\n      api.encryptionKeyPolicyStatement(),\n    ],\n  }),\n});\n```\n\n- **A key defined in your app gets Lambda's statement automatically.** It allows `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions through `aws:SourceArn` and the encryption context Lambda sets. For an imported key, add `encryptionKeyPolicyStatement()` to its policy yourself.\n- **`PER_REGION` and `MULTI_REGION` endpoints need a multi-Region key**, with a replica in every region they serve from. The replicas must exist before the endpoint, so put the key and its replicas in stacks that deploy before the function's. Replica policies aren't copied from the primary, so each one needs `encryptionKeyPolicyStatement()`. With a single-Region key, the endpoint fails to activate in its other regions and the whole deployment rolls back. The construct fails synthesis instead, when it can tell: a key in your app without `multiRegion`, or an imported key whose ID doesn't start with `mrk-`.\n- **CloudFormation's role creates the revisions**, so it needs `kms:DescribeKey`, `kms:GenerateDataKey` and `kms:Decrypt` on the key. A key's default policy delegates to IAM, and CDK's default deployment role is allowed.\n- **Changing the key creates a new revision.** Earlier revisions keep their key, including the ones kept as rollback targets (`revisionRetention`). Keep the old key enabled while any of them might serve traffic again.\n- **Disabling the key, or removing Lambda's access, stops new execution environments from starting.** Running ones keep their decrypted copy for a while, so this doesn't contain traffic immediately.\n\nLog groups are encrypted by CloudWatch Logs. To use your own key for them too, pass `logEncryptionKey`. It can be the same key:\n\n```ts\ndeclare const key: kms.Key;              // multiRegion: true, in the function's region\ndeclare const replica: kms.CfnReplicaKey; // in us-east-1\n\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('build'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: { endpointType: WebFunctionEndpointType.PER_REGION, regions: ['us-east-1'] },\n  logEncryptionKey: key,\n});\n\n// The replica's policy also allows CloudWatch Logs in its region, for this function's groups.\nreplica.keyPolicy = new iam.PolicyDocument({\n  statements: [\n    new iam.PolicyStatement({ principals: [new iam.AccountRootPrincipal()], actions: ['kms:*'], resources: ['*'] }),\n    api.logEncryptionKeyPolicyStatement('us-east-1'),\n  ],\n});\n```\n\n- **CloudWatch Logs only uses a key in the group's own region.** The groups in the key's region use the key. Groups in other regions use the multi-Region key's replica there, which has the same key ID. With a single-Region key, synthesis fails as soon as a group is in another region.\n- **A key defined in your app gets CloudWatch Logs' statement for its own region.** It allows `logs.<region>.amazonaws.com` to use the key for this function's log groups only. Add `logEncryptionKeyPolicyStatement(region)` to each replica's policy, and to an imported key's.\n- **The construct's provider sets the key on each group, and needs `kms:DescribeKey` on it to do so.** The construct grants that through IAM, which a key's default policy allows. If a key's policy doesn't delegate to IAM, allow the provider's role in the key policy.\n- **Adding or changing the key encrypts new events only.** Existing events stay encrypted with the key they were written with. Removing `logEncryptionKey` sets the groups back to CloudWatch Logs' encryption.\n- **Retained log groups need their key to stay readable.** The default `logRemovalPolicy` is `RETAIN`, so keep the key while you keep the logs.\n\n### Defaults for every function (property injection)\n\nTo give every function under a scope the same defaults, register a property injector for `WebFunction.PROPERTY_INJECTION_ID`, as you would for aws-cdk-lib's constructs. For example, a team's log retention:\n\n```ts\nclass TeamDefaults implements IPropertyInjector {\n  public readonly constructUniqueId = WebFunction.PROPERTY_INJECTION_ID;\n  public inject(originalProps: WebFunctionProps): WebFunctionProps {\n    // The team's defaults, with explicit props winning.\n    return Object.assign({ logRetention: logs.RetentionDays.ONE_MONTH }, originalProps);\n  }\n}\nPropertyInjectors.of(this).add(new TeamDefaults()); // or on the app, for every stack\n```\n\n- An injector applies to functions created under the scope it's added to. The nearest one wins.\n- `NodejsWebFunction` has its own ID (`NodejsWebFunction.PROPERTY_INJECTION_ID`). Its injector runs first, then `WebFunction`'s, as with aws-cdk-lib's `NodejsFunction` and `Function`.\n\n### Bundling TypeScript with `NodejsWebFunction`\n\n`NodejsWebFunction` is a `WebFunction` that bundles your server from a TypeScript or JavaScript entry file with esbuild, like `NodejsFunction` does for Lambda functions:\n\n```ts\nnew NodejsWebFunction(this, 'Api', {\n  entry: 'src/server.ts',\n  authType: WebFunctionAuthType.AWS_IAM,\n  bundling: {\n    minify: true,                                       // default true\n    sourceMap: true,                                    // default true\n    format: lambdaNodejs.OutputFormat.ESM,              // default ESM (index.mjs); CJS gives index.js\n    externalModules: [],                                // default: bundle everything you import\n  },\n});\n```\n\n- **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`).\n- **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.\n- **ESM bundles include a `require` shim**, so CommonJS dependencies that load Node.js built-ins (Express, for example) work.\n- **The AWS SDK is bundled like any other dependency**, since the runtime has none. Only the clients you import are included.\n- **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).\n- **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 } })`.\n\n### Code\n\n`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.\n\nLambda 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. The bucket is emptied and deleted with the stack.\n\nCopying code, managing the function's log groups in every region, looking up regional URLs, cleaning up old revisions, creating rollback alarms in other regions and emptying the code bucket all run in one custom resource Lambda per stack. Its logs go to a log group the stack owns, kept for a month and deleted with the stack.\n\n## Revisions\n\nAny 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.\n\nEarlier 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.\n\n```ts\nnew WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  revisionRetention: 5,\n});\n```\n\n### Routing to earlier revisions\n\nReference 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:\n\n```ts\nconst previous = WebFunctionRevision.fromRevisionAttributes(this, 'Previous', {\n  webFunction: fn,\n  revisionId: 'rev-a1b2c',\n});\n\n// Keep the default endpoint on the previous revision, and send 10% to the new one:\nfn.endpoint.routeTraffic(previous, [{ revision: fn.currentRevision, weight: 0.1 }]);\n\n// Or a second endpoint that stays on the previous revision while fn.endpoint moves on:\nfn.addEndpoint('Stable', { authType: WebFunctionAuthType.AWS_IAM, revision: previous });\n```\n\n- An endpoint routes to at most two revisions. The additional revision's `weight` is a whole percentage, from 0.01 to 0.99.\n- To promote, remove `routeTraffic` (or `revision`) and deploy: the endpoint serves the current revision again.\n- 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.\n\n### Canary and linear deployments\n\nBy 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.\n\n```ts\nconst api = new WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  endpoint: {\n    // 10% of the traffic for 10 minutes, then all of it; back if more than 2% of requests get a 5XX.\n    deployment: WebFunctionDeployment.canary({ percent: 10, bake: Duration.minutes(10), rollbackOn: { serverErrorRate: 2 } }),\n  },\n});\n\n// 25% more every 5 minutes, watching an alarm of your own. Each endpoint has its own deployment.\n// errorRate: any cloudwatch.IAlarm, e.g. on a metric your application publishes.\napi.addEndpoint('Public', {\n  authType: WebFunctionAuthType.NONE,\n  deployment: WebFunctionDeployment.linear({ percent: 25, interval: Duration.minutes(5), alarms: [errorRate] }),\n});\n```\n\n| | Steps | Limits |\n|---|---|---|\n| `allAtOnce()` (default) | 100% | |\n| `canary({ percent, bake })` | `percent`, then 100% after `bake` | `percent` 1–99, `bake` 1–45 minutes |\n| `linear({ percent, interval })` | `percent` more every `interval` | `percent` 5–50, `interval` from 1 minute, at most 45 minutes in all |\n\nHow it works:\n\n- 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.\n- 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.\n- 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.\n- A rollback of the stack, for any reason, moves the traffic back at once, without waiting or checking alarms.\n- 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.\n- A deployment can take up to an hour: CloudFormation waits for it before it updates the endpoint. Deployments of different endpoints run in parallel.\n- 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.\n\n#### Rollback alarms\n\n`rollbackOn` makes the endpoint create alarms on its own error rates, and the deployment watches them alongside any `alarms` you pass:\n\n| `rollbackOn` | Default | |\n|---|---|---|\n| `serverErrorRate` | none | roll back when more than this % of requests get a 5XX |\n| `clientErrorRate` | none | the same for 4XX (including 429s from `rateLimit` and `maxEnvironments`) |\n| `minimumRequests` | 10 | periods with fewer requests don't count, so one failed request out of two doesn't roll back |\n| `period`, `evaluationPeriods` | 1 minute, 2 | consecutive periods over the threshold before rolling back |\n\n- **One alarm per threshold in every region the endpoint serves from.** Metrics are published in the region that served the request, and an alarm can only watch metrics in its own region. The home region's alarm is a normal CloudFormation alarm; the others are created and deleted with the endpoint by a custom resource, and named `LambdaWeb-<function>-<endpoint>-5xx-rate` (or `-4xx-rate`). `endpoint.rollbackAlarms` lists them all, e.g. to add notifications to the home region's.\n- **The alarms see the whole endpoint.** Lambda Web Function metrics have no revision dimension, so at 10% a new revision's errors are about a tenth of the endpoint's: set the threshold low enough to notice that, or alarm on metrics your application publishes with its version.\n- **5XX includes the platform's 503s** while the endpoint scales up for a sudden burst, not only your application's errors.\n- **A step should outlast the alarm.** CloudWatch needs `period` × `evaluationPeriods`, plus a couple of minutes of delay, to fire; the construct warns when a canary's bake or a linear interval is shorter.\n\nThe 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.\n\n## Metrics\n\nEndpoints and functions have helpers for their CloudWatch metrics (namespace `AWS/Lambda/Web`), like `lambda.Function`'s:\n\n```ts\nfn.endpoint.metricServerErrorRate().createAlarm(this, 'ErrorRate', { threshold: 1, evaluationPeriods: 3 });\nfn.endpoint.metricRequestThrottles().createAlarm(this, 'Throttled', { threshold: 10, evaluationPeriods: 3 });\nfn.metricConcurrentRequests().createAlarm(this, 'Saturated', { threshold: 60, evaluationPeriods: 3 });\n```\n\n| Endpoint | Metric |\n|---|---|\n| `metricRequests()` | `ExecutedRequests` (there's no separate 2XX count) |\n| `metricClientErrors()`, `metricServerErrors()` | `HTTPResponseStatusClass4XX`, `HTTPResponseStatusClass5XX` |\n| `metricClientErrorRate()`, `metricServerErrorRate()` | 4XX or 5XX as a % of requests (math expression) |\n| `metricActiveEnvironments()` | `EndpointActiveEnvironments`, to compare with `maxEnvironments` |\n| `metricRequestThrottles()`, `metricEnvironmentThrottles()` | 429s from `rateLimit` and from `maxEnvironments` |\n\n| Function | Metric |\n|---|---|\n| `metricConcurrentRequests()` | `EnvironmentConcurrentRequests` (maximum), to compare with `maxConcurrencyPerEnvironment` |\n| `metricMaxMemoryUsage()` | `EnvironmentMaxMemoryUsage` (maximum) |\n| `metricActiveTime()`, `metricCpuTime()`, `metricResponseBytes()` | `EnvironmentActiveTime`, `EnvironmentCPUTime`, `ResponseBytes` |\n\n- **Metrics stay in the region that served the request**; unlike logs, they aren't copied to the home region. Every helper takes `region`. Dashboards can show any region, but an alarm can only use metrics from its own stack's region.\n- 4XX, 5XX and the throttle metrics only exist once they're non-zero: alarm on them with `treatMissingData: NOT_BREACHING`. The rate helpers count missing errors as 0.\n- There's no latency metric. Publish one from your application (e.g. with the CloudWatch embedded metric format).\n\n## Logs in every region\n\nWeb Functions log in two tiers:\n\n```text\n every serving region               home region\n ┌──────────────────┐              ┌──────────────────────────────────────────┐\n │ <group>.local    │── copied ───►│ <group>   every region's logs            │\n │ (that region's   │  (seconds)   │ streams …[rev]<instance>-<acct>-<region> │\n │  environments)   │              │ <group>.local  (home-region traffic)     │\n └──────────────────┘              └──────────────────────────────────────────┘\n```\n\n**Query `fn.logGroup`**, the home-region group that receives every region's logs. The service would create missing groups without retention and never delete them, so the construct creates and owns all of them: both home-region groups, and `<group>.local` in every other region any of its endpoints serves from.\n\n```ts\nnew WebFunction(this, 'Api', {\n  runtime: lambda.Runtime.NODEJS_24_X,\n  code: lambda.Code.fromAsset('dist'),\n  authType: WebFunctionAuthType.AWS_IAM,\n  logRetention: logs.RetentionDays.THREE_MONTHS,    // default ONE_MONTH, every group in every region\n  logRemovalPolicy: RemovalPolicy.DESTROY,           // default RETAIN\n  applicationLogLevelV2: lambda.ApplicationLogLevel.WARN,\n  systemLogLevelV2: lambda.SystemLogLevel.INFO,      // DEBUG, INFO or WARN\n});\n```\n\n- The default group is `/aws/lambda/web/<function name>`. Log lines are JSON; application lines carry `requestId`, `endpointName` and `region`.\n- Every event is stored twice (`.local` plus the home-region copy), so expect about double log ingestion, plus cross-region transfer.\n- With `DESTROY`, deletion waits about a minute after the function is gone, because environments flush their last lines late.\n- Subscribe only to `fn.logGroup`: subscribing to the `.local` groups as well delivers every event twice.\n\n## cdk-nag\n\nThe library acknowledges the [cdk-nag](https://github.com/cdklabs/cdk-nag) AwsSolutions findings on the resources it creates, each with a reason, so they don't show up in your reports:\n\n| Finding | Resource | Reason |\n|---|---|---|\n| IAM5 (wildcards) | the default execution role | log streams of the function's own log groups, in every region it serves from |\n| IAM5 | the deployment handlers' role (canary and linear deployments) | their own log group, `cloudwatch:DescribeAlarms` (composite alarms need `*`), and the revisions and endpoints of the functions they deploy |\n| IAM4, IAM5, SF1, SF2 | the CDK Provider framework behind deployments | CDK's own functions and waiter state machine |\n| S1 (access logs) | the stack's code bucket | it only holds copies of the stack's code assets |\n\n- **This works with both cdk-nag versions**, without depending on cdk-nag. cdk-nag 3 reads CDK's `Validations.of(...).acknowledge()`, one ID per finding. cdk-nag 2 reads `cdk_nag` metadata in the template.\n- **Your own statements and resources are still checked.** That includes statements you add to the function's role (`addToRolePolicy`, grants) and your CloudFront distribution's settings.\n- Only the AwsSolutions pack is covered; findings from the HIPAA, NIST and PCI packs aren't acknowledged.\n\n## Upgrading\n\n### From 0.1.5 to 0.1.7, with a resource policy\n\nVersions 0.1.5 to 0.1.7 wrote the function's resource policy with an `AWS::Lambda::ResourcePolicy`. Later versions don't (0.1.7 has the same code as 0.1.6). When an update removes that resource, CloudFormation deletes the function's **whole** resource policy at the end of the update, including the statements the new version just wrote. Callers that rely on the policy then get 403: other accounts, AWS services, and CloudFront.\n\nIf your function has a resource policy (from `addPermission`, a grant to another account or an AWS service, or `WebFunctionOrigin`), first deploy once on the version you have, with the old resource retained:\n\n```ts\n(fn.node.findChild('ResourcePolicy') as CfnResource).applyRemovalPolicy(RemovalPolicy.RETAIN);\n```\n\nThen upgrade, without changing your statements in the same deployment. The new version takes over the statements it writes itself. A statement you removed in the same deployment would stay in the policy.\n\n## Limitations\n\n- Not yet supported: VPC access (network connectors), KMS encryption, and tracing.\n- **Hotswap skips Web Functions without a warning.** `cdk deploy --hotswap` and `cdk watch`, which hotswaps by default, report `(no changes)` for a code or configuration change and the endpoint keeps serving the old revision. Use `cdk watch --hotswap-fallback` (or `cdk deploy --hotswap-fallback`): it deploys Web Function changes through CloudFormation, in about 40 seconds for a home-region endpoint.\n- Fixed limits: 512 MB of code (unzipped) and 32 KB of environment variables per revision, 512 MB of `/tmp` per execution environment, and 128 KiB of headers per request.\n- 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).\n\n## Development\n\nTooling is pinned in `mise.toml` (Node 24, AWS CDK CLI). Personal settings, such as the AWS profile for the live end-to-end tests, go in a git-ignored `mise.local.toml`.\n\n```bash\nmise install\nnpx projen build      # compile, unit tests, lint, API docs\nnpx projen e2e        # deploy, verify and destroy real stacks in three regions (needs AWS credentials)\n```\n"
   },
   "repository": {
     "type": "git",
@@ -9853,7 +9853,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 162
+        "line": 192
       },
       "methods": [
         {
@@ -9865,7 +9865,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 185
+            "line": 215
           },
           "name": "grantInvoke",
           "parameters": [
@@ -9890,7 +9890,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 190
+            "line": 220
           },
           "name": "metric",
           "parameters": [
@@ -9922,7 +9922,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 193
+            "line": 223
           },
           "name": "metricActiveTime",
           "parameters": [
@@ -9948,7 +9948,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 199
+            "line": 229
           },
           "name": "metricConcurrentRequests",
           "parameters": [
@@ -9974,7 +9974,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 196
+            "line": 226
           },
           "name": "metricCpuTime",
           "parameters": [
@@ -10000,7 +10000,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 202
+            "line": 232
           },
           "name": "metricMaxMemoryUsage",
           "parameters": [
@@ -10026,7 +10026,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 205
+            "line": 235
           },
           "name": "metricResponseBytes",
           "parameters": [
@@ -10059,7 +10059,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 175
+            "line": 205
           },
           "name": "webFunctionArn",
           "type": {
@@ -10078,7 +10078,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 168
+            "line": 198
           },
           "name": "webFunctionName",
           "type": {
@@ -10675,7 +10675,7 @@
         },
         "locationInModule": {
           "filename": "src/web-function.ts",
-          "line": 452
+          "line": 488
         },
         "parameters": [
           {
@@ -10704,7 +10704,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 388
+        "line": 418
       },
       "methods": [
         {
@@ -10714,7 +10714,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 398
+            "line": 428
           },
           "name": "fromWebFunctionArn",
           "parameters": [
@@ -10751,7 +10751,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 412
+            "line": 442
           },
           "name": "fromWebFunctionAttributes",
           "parameters": [
@@ -10788,7 +10788,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 405
+            "line": 435
           },
           "name": "fromWebFunctionName",
           "parameters": [
@@ -10825,7 +10825,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 552
+            "line": 602
           },
           "name": "addEndpoint",
           "parameters": [
@@ -10859,7 +10859,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 560
+            "line": 610
           },
           "name": "addEnvironment",
           "parameters": [
@@ -10890,7 +10890,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 589
+            "line": 639
           },
           "name": "addPermission",
           "parameters": [
@@ -10918,7 +10918,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 571
+            "line": 621
           },
           "name": "addToRolePolicy",
           "parameters": [
@@ -10930,6 +10930,23 @@
             }
           ]
         },
+        {
+          "docs": {
+            "remarks": "It's added to `encryptionKey` when the key is defined in this app. Add it to every replica of a multi-Region key\nyourself: replicas don't share their primary's policy.",
+            "stability": "experimental",
+            "summary": "The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets)."
+          },
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 669
+          },
+          "name": "encryptionKeyPolicyStatement",
+          "returns": {
+            "type": {
+              "fqn": "aws-cdk-lib.aws_iam.PolicyStatement"
+            }
+          }
+        },
         {
           "docs": {
             "remarks": "Shortcut for `grants.invoke(grantee)`, as on `lambda.Function`.\n[disable-awslint:no-grants]",
@@ -10938,7 +10955,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 579
+            "line": 629
           },
           "name": "grantInvoke",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase",
@@ -10955,6 +10972,34 @@
               "fqn": "aws-cdk-lib.aws_iam.Grant"
             }
           }
+        },
+        {
+          "docs": {
+            "remarks": "It's added to `logEncryptionKey` for the key's own region when the key is defined in this app. Add it to the\nreplica in every other region the function serves from yourself: replicas don't share their primary's policy.",
+            "stability": "experimental",
+            "summary": "The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`)."
+          },
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 692
+          },
+          "name": "logEncryptionKeyPolicyStatement",
+          "parameters": [
+            {
+              "docs": {
+                "summary": "the region of the key or replica."
+              },
+              "name": "region",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "aws-cdk-lib.aws_iam.PolicyStatement"
+            }
+          }
         }
       ],
       "name": "WebFunction",
@@ -10968,7 +11013,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 393
+            "line": 423
           },
           "name": "PROPERTY_INJECTION_ID",
           "static": true,
@@ -10984,7 +11029,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 423
+            "line": 453
           },
           "name": "currentRevision",
           "type": {
@@ -11000,7 +11045,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 426
+            "line": 456
           },
           "name": "endpoint",
           "type": {
@@ -11015,7 +11060,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 435
+            "line": 471
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -11031,7 +11076,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 429
+            "line": 459
           },
           "name": "grants",
           "type": {
@@ -11047,7 +11092,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 441
+            "line": 477
           },
           "name": "logGroup",
           "type": {
@@ -11063,7 +11108,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 420
+            "line": 450
           },
           "name": "revisionId",
           "type": {
@@ -11078,7 +11123,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 432
+            "line": 462
           },
           "name": "role",
           "type": {
@@ -11093,7 +11138,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 417
+            "line": 447
           },
           "name": "webFunctionArn",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase",
@@ -11109,13 +11154,45 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 416
+            "line": 446
           },
           "name": "webFunctionName",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase",
           "type": {
             "primitive": "string"
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "The customer managed key of the function's revisions, if any."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 465
+          },
+          "name": "encryptionKey",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_kms.IKey"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "The customer managed key of the function's log groups, if any."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 468
+          },
+          "name": "logEncryptionKey",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_kms.IKey"
+          }
         }
       ],
       "symbolId": "src/web-function:WebFunction"
@@ -11132,7 +11209,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 211
+        "line": 241
       },
       "name": "WebFunctionAttributes",
       "properties": [
@@ -11146,7 +11223,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 233
+            "line": 263
           },
           "name": "endpointName",
           "optional": true,
@@ -11164,7 +11241,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 219
+            "line": 249
           },
           "name": "webFunctionArn",
           "optional": true,
@@ -11182,7 +11259,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 226
+            "line": 256
           },
           "name": "webFunctionName",
           "optional": true,
@@ -11270,7 +11347,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 274
+        "line": 304
       },
       "methods": [
         {
@@ -11281,7 +11358,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 297
+            "line": 327
           },
           "name": "addToResourcePolicy",
           "overrides": "aws-cdk-lib.aws_iam.IResourceWithPolicyV2",
@@ -11308,7 +11385,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 287
+            "line": 317
           },
           "name": "grantInvoke",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11335,7 +11412,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 328
+            "line": 358
           },
           "name": "metric",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11367,7 +11444,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 343
+            "line": 373
           },
           "name": "metricActiveTime",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11394,7 +11471,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 358
+            "line": 388
           },
           "name": "metricConcurrentRequests",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11420,7 +11497,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 348
+            "line": 378
           },
           "name": "metricCpuTime",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11448,7 +11525,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 367
+            "line": 397
           },
           "name": "metricMaxMemoryUsage",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11474,7 +11551,7 @@
           },
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 372
+            "line": 402
           },
           "name": "metricResponseBytes",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11505,7 +11582,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 276
+            "line": 306
           },
           "name": "webFunctionArn",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11522,7 +11599,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 275
+            "line": 305
           },
           "name": "webFunctionName",
           "overrides": "@ashishpandeyone/cdk-lambda-web-function.IWebFunction",
@@ -11538,7 +11615,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 279
+            "line": 309
           },
           "name": "webFunctionRef",
           "overrides": "aws-cdk-lib.interfaces.aws_lambda.IWebFunctionRef",
@@ -12600,7 +12677,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 26
+        "line": 27
       },
       "name": "WebFunctionOptions",
       "properties": [
@@ -12613,7 +12690,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 30
+            "line": 31
           },
           "name": "authType",
           "type": {
@@ -12630,7 +12707,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 119
+            "line": 149
           },
           "name": "applicationLogLevelV2",
           "optional": true,
@@ -12648,7 +12725,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 65
+            "line": 66
           },
           "name": "description",
           "optional": true,
@@ -12656,6 +12733,25 @@
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- an AWS owned key",
+            "remarks": "A `PER_REGION` or `MULTI_REGION` endpoint needs a **multi-Region key** with a replica in every region it serves\nfrom, and each replica's policy must allow Lambda to decrypt (see `encryptionKeyPolicyStatement()`). A key defined\nin this app gets that statement added to its own policy.\n\nChanging the key creates a new revision. Earlier revisions, including the ones kept as rollback targets, still\nneed their key.\n[disable-awslint:prefer-ref-interface]",
+            "stability": "experimental",
+            "summary": "A customer managed KMS key for the function's revisions: their code and environment variables."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 91
+          },
+          "name": "encryptionKey",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_kms.IKey"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -12666,7 +12762,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 39
+            "line": 40
           },
           "name": "endpoint",
           "optional": true,
@@ -12685,7 +12781,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 82
+            "line": 98
           },
           "name": "environment",
           "optional": true,
@@ -12698,6 +12794,25 @@
             }
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- CloudWatch Logs' own encryption",
+            "remarks": "CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the\nreplica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its\nregion (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.\n\nRemoving the key decrypts nothing: the groups keep their existing events encrypted with it.\n[disable-awslint:prefer-ref-interface]",
+            "stability": "experimental",
+            "summary": "A customer managed KMS key for the function's log groups, in every region it serves from."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/web-function.ts",
+            "line": 142
+          },
+          "name": "logEncryptionKey",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_kms.IKey"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -12709,7 +12824,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 112
+            "line": 128
           },
           "name": "logRemovalPolicy",
           "optional": true,
@@ -12727,7 +12842,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 104
+            "line": 120
           },
           "name": "logRetention",
           "optional": true,
@@ -12746,7 +12861,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 97
+            "line": 113
           },
           "name": "maxConcurrencyPerEnvironment",
           "optional": true,
@@ -12765,7 +12880,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 51
+            "line": 52
           },
           "name": "revisionRetention",
           "optional": true,
@@ -12784,7 +12899,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 75
+            "line": 76
           },
           "name": "role",
           "optional": true,
@@ -12802,7 +12917,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 126
+            "line": 156
           },
           "name": "systemLogLevelV2",
           "optional": true,
@@ -12820,7 +12935,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 89
+            "line": 105
           },
           "name": "timeout",
           "optional": true,
@@ -12839,7 +12954,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 58
+            "line": 59
           },
           "name": "webFunctionName",
           "optional": true,
@@ -13090,7 +13205,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 239
+        "line": 269
       },
       "name": "WebFunctionPermission",
       "properties": [
@@ -13104,7 +13219,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 246
+            "line": 276
           },
           "name": "principal",
           "type": {
@@ -13122,7 +13237,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 253
+            "line": 283
           },
           "name": "endpoint",
           "optional": true,
@@ -13140,7 +13255,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 268
+            "line": 298
           },
           "name": "sourceAccount",
           "optional": true,
@@ -13158,7 +13273,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 261
+            "line": 291
           },
           "name": "sourceArn",
           "optional": true,
@@ -13183,7 +13298,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/web-function.ts",
-        "line": 132
+        "line": 162
       },
       "name": "WebFunctionProps",
       "properties": [
@@ -13197,7 +13312,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 144
+            "line": 174
           },
           "name": "code",
           "type": {
@@ -13213,7 +13328,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 136
+            "line": 166
           },
           "name": "runtime",
           "type": {
@@ -13230,7 +13345,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/web-function.ts",
-            "line": 151
+            "line": 181
           },
           "name": "entrypoint",
           "optional": true,
@@ -13562,6 +13677,6 @@
       "symbolId": "src/web-function-deployment:WebFunctionRollbackOptions"
     }
   },
-  "version": "0.1.10",
-  "fingerprint": "jNpRieNrldxUoisjGaK6PE0jlDtSXgs8VYo6J+/40Ao="
+  "version": "0.1.12",
+  "fingerprint": "eEKvgpGlRCGfraL+IN8F5JTtpuZ3CcK+GeIj4jZ3Q94="
 }