@ashishpandeyone/cdk-lambda-web-function 0.1.3 → 0.1.5

package/README.md

@@ -16,7 +16,7 @@
 
 <!--END STABILITY BANNER-->
 
-[AWS Lambda Web Functions](https://aws.amazon.com/lambda/) 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.
+[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.
 
 ```ts fixture=bare
 import * as lambda from 'aws-cdk-lib/aws-lambda';
@@ -37,10 +37,18 @@ new CfnOutput(this, 'Url', { value: fn.endpoint.url }); // https://<id>.lambda-w
 
 The stack's region is the function's **home region**. Multi-region endpoints need a stack with an explicit `env.region`.
 
+## Installation
+
+```bash
+npm install @ashishpandeyone/cdk-lambda-web-function
+```
+
+It 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.
+
 ## Writing the server
 
 1. Listen on the host and port in **`AWS_LAMBDA_HTTP_ENDPOINT`** (`0.0.0.0:3000` today). `PORT` is not set.
-2. Start listening within **about 9 seconds**, or initialisation fails with `Application.TimeoutListenError`.
+2. Start listening within **10 seconds**, or initialisation fails with `Application.TimeoutListenError`.
 3. Put the entry file at the root of your bundle as **`index.js`**, or set `entrypoint`.
 4. The runtime has **no AWS SDK**: bundle the clients you import.
 5. Code runs on **arm64**.
@@ -148,6 +156,7 @@ import { SignatureV4a } from '@smithy/signature-v4a';
 import { Sha256 } from '@aws-crypto/sha256-js';
 import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
 
+const host = new URL(url).hostname; // url: the endpoint's URL
 const signer = new SignatureV4a({ service: 'lambda', region: '*', sha256: Sha256, credentials: fromNodeProviderChain() });
 const signed = await signer.sign(
   { method: 'GET', protocol: 'https:', hostname: host, path: '/', headers: { host } },
@@ -156,6 +165,51 @@ const signed = await signer.sign(
 const response = await fetch(`https://${host}/`, { headers: signed.headers });
 ```
 
+### Other accounts and AWS services
+
+A 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.
+
+```ts
+fn.grantInvoke(iam.Role.fromRoleArn(this, 'Partner', 'arn:aws:iam::444455556666:role/caller'));
+```
+
+For 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`:
+
+```ts
+fn.addPermission('PartnerAccount', { principal: new iam.AccountPrincipal('444455556666') });
+fn.addPermission('MyOrg', { principal: new iam.OrganizationPrincipal('o-a1b2c3d4e5'), endpoint: fn.endpoint });
+fn.addPermission('Cdn', {
+  principal: new iam.ServicePrincipal('cloudfront.amazonaws.com'),
+  sourceArn: `arn:aws:cloudfront::${this.account}:distribution/EDFDVBD6EXAMPLE`,
+});
+```
+
+`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.
+
+- **One resource policy per function, written by the function's stack.** The construct creates it (`AWS::Lambda::ResourcePolicy`) with the first statement. CloudFormation can't attach a second one: another stack, or a `CfnResourcePolicy` of your own on the function, fails at change-set validation with "already exists". If you attached one yourself, move its statements into `addPermission` or `addToResourcePolicy`. Each update of the policy replaces any statements added outside CloudFormation.
+- **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`.
+- **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).
+- 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.
+
+### Functions defined elsewhere
+
+Import a Web Function defined in another stack or app to grant access to it, read its metrics, or reference its revisions:
+
+```ts
+const orders = WebFunction.fromWebFunctionArn(this, 'Orders', 'arn:aws:lambda:us-east-1:111122223333:web-function/orders');
+orders.grantInvoke(consumerRole);             // every endpoint of the function
+
+const live = WebFunction.fromWebFunctionAttributes(this, 'Live', {
+  webFunctionName: 'orders',                  // in this stack's account and region
+  endpointName: 'live',                       // grantInvoke allows this endpoint only
+});
+live.metricConcurrentRequests().createAlarm(this, 'Busy', { threshold: 60, evaluationPeriods: 3 });
+```
+
+An imported function's metrics default to its own region. Its endpoints, revisions and log groups stay with the stack that defines it.
+
+An imported function's `grantInvoke` adds to the caller's IAM policy only, which is all a caller in the function's account needs. A caller in another account also needs the function's resource policy to allow it, which only the function's own stack can change: `addToResourcePolicy` on an imported function adds nothing and warns.
+
 ## Configuration
 
 ```ts
@@ -175,6 +229,7 @@ api.addEnvironment('FEATURE_FLAG', 'on');
 table.grantReadWriteData(api);           // the default role trusts lambda.amazonaws.com
 ```
 
+- **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.
 - Requests handled by one environment share module-level state, so keep handlers concurrency-safe.
 - Environment variable names starting with `AWS_` are reserved.
 - **Renaming the function replaces it and changes its URL.** A generated name depends on the construct path, so moving the construct renames it too.
@@ -207,7 +262,9 @@ new NodejsWebFunction(this, 'Api', {
 
 `code` takes any `lambda.Code` that produces a zip in S3: `fromAsset`, `fromBucket`/`fromBucketV2`, `fromCustomCommand`, `fromDockerBuild`. Inline code and container images fail at synth time.
 
-Lambda Web Functions download code as the `lambda.amazonaws.com` service principal, from a **versioned** bucket, and the CDK bootstrap bucket allows neither. So each stack gets a small code bucket, and the code is copied into it on deploy.
+Lambda Web Functions download code as the `lambda.amazonaws.com` service principal, from a **versioned** bucket, and the CDK bootstrap bucket allows neither. So each stack gets a small code bucket, and the code is copied into it on deploy. The bucket is emptied and deleted with the stack.
+
+Copying 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.
 
 ## Revisions
 
@@ -343,7 +400,7 @@ Web Functions log in two tiers:
  └──────────────────┘              └──────────────────────────────────────────┘
 ```
 
-**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 of the endpoint.
+**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.
 
 ```ts
 new WebFunction(this, 'Api', {
@@ -364,10 +421,10 @@ new WebFunction(this, 'Api', {
 
 ## Limitations
 
-- Not yet supported: importing existing functions, VPC access (network connectors), resource-policy permissions, KMS encryption, metrics helpers, tracing, and a CloudFront origin.
-- `cdk deploy --hotswap` and `cdk watch` don't support Web Functions.
+- Not yet supported: VPC access (network connectors), KMS encryption, tracing, and a CloudFront origin.
+- **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.
+- 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.
 - Quotas: 10 endpoints and about 50 revisions per function (Lambda cleans up older revisions automatically), and 10,000 requests per second per endpoint. Per account and region: 100,000 requests per second and 2,000 Arm64 vCPUs (each execution environment uses 2). The account quotas are adjustable, and new accounts start lower. See [Lambda quotas](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html).
-- The stack's custom resource provider Lambda keeps its own log group after the stack is deleted, as with other CDK custom resources.
 
 ## Development