aws-lambda-web-functions

# AWS Lambda Web Functions > The AWS MCP server is recommended for sandboxed execution and audit logging. > > **If `aws lambda-web` is not recognized, update the AWS CLI (see [references/deployment.md](references/deployment.md)).** A missing command means an outdated CLI, not an unavailable feature. Help users build and deploy Node.js HTTP applications on AWS Lambda Web Functions. Your app listens on a port, handles HTTP natively, and gets a global HTTPS URL. Develop locally with `node index.js`, deploy the same code to AWS. ## When to Use Web Functions - Interactive HTTP traffic someone is waiting on: web app, HTTP API, or SSR site. - The app is already a port-listening HTTP server (Express, Fastify, Hono) and should stay one — no handler rewrite, no adapter library. - Handlers are I/O-bound (database, cache, another API, a model endpoint), so many requests share one execution environment and time spent waiting on I/O is not billed as CPU. - Response streaming matters: SSE, chunked transfer, or proxying LLM tokens as they are produced. - The endpoint should be reachable worldwide on one hostname without assembling CloudFront, API Gateway and Route53 by hand. - Traffic is spiky or unpredictable and should scale to zero. ### Hard preconditions Any "no" rules Web Functions out. Invoke the `aws-serverless` skill to find a suitable service. - Runtime is Node.js — `nodejs24.x`. Python, Java, Go, .NET and Rust are not supported. Confirm the supported runtime list with `aws lambda-web help` or the AWS docs before routing a caller away. - Every native dependency has an **arm64 (Graviton)** build. - The work is an HTTP request/response (or stream) that a caller is waiting on. Queue, event-stream source (Kinesis, DynamoDB Streams), schedule, or event trigger are not supported. - One request completes within the 900 s (15 min) request timeout. - The app fits a 512 MB package and a 2 vCPU / 2 GB environment (see Service Limits). - Environments are stateless — any environment can serve any request. There is no affinity between an end user's session and a specific environment. - The app tolerates sharing an environment with concurrent requests. Strict per-request isolation is not supported. ## Use Cases "What I'm building" → how it lands here. | The user is building | Shape on Web Functions | |---|---| | JSON HTTP API or REST backend | Express or Hono router, I/O-bound handlers, DynamoDB or RDS behind it → [architecture-patterns.md](references/architecture-patterns.md) | | Server-side-rendered site or app | Render HTML per request from `index.js`; no bundler needed unless you author JSX → [architecture-patterns.md](references/architecture-patterns.md) | | LLM or AI gateway streaming tokens to a browser | SSE or chunked responses; raise `timeoutSeconds` to cover the whole stream, not just the first byte → [architecture-patterns.md](references/architecture-patterns.md) | | Webhook receiver (Stripe, GitHub, Slack) | Verify the sender's signature against a signing secret from Secrets Manager **before** acting on the payload, then acknowledge fast and finish the work after responding — the environment stays running → [architecture-patterns.md](references/architecture-patterns.md) | | Mobile or web backend-for-frontend aggregating several services | One environment fans several requests out concurrently, and time spent waiting is not billed as CPU | | Single-page app plus its API from one deployment | `express.static` for the bundle, `/*splat` fallback for client routes → [static-assets.md](references/static-assets.md) | | Internal service-to-service HTTP endpoint | `authType: IamAuth`, so only SigV4-signed callers reach it → [iam-and-security.md](references/iam-and-security.md) | | Globally low-latency endpoint on a single hostname | `MultiRegion` endpoint plus a region-agnostic app → [domains-and-routing.md](references/domains-and-routing.md) | | App that calls RDS, ElastiCache or other private VPC resources | An egress network connector referenced from the revision; the endpoint stays public → [networking.md](references/networking.md) | ## Workflow Default to the `aws lambda-web` CLI — it's the quickest path. Use `aws lambda-web deploy` when the user asks for a single command or says they already deploy with it. It packages, uploads and creates or updates a project directory in one command, and `--hello-world` scaffolds and deploys a starter app (see Deploy (CLI) below). Otherwise, including for updates to an existing function, use the steps below. Use CloudFormation, CDK, SAM or Terraform when the user wants infrastructure-as-code or a repeatable production stack (see [references/infrastructure-as-code.md](references/infrastructure-as-code.md)). 1. **Scaffold** - Express is inline below; for **Hono** or **Fastify**, read [references/frameworks.md](references/frameworks.md) 2. **Choose endpoint auth** — **ask the user before deploying** (see below); endpoints are public unless they pick `IamAuth` 3. **Test locally** — `node index.js` 4. **Package** — ZIP with production deps (up to 512 MB) 5. **Deploy** — `aws lambda-web create-web-function` 6. **Verify** — get endpoint URL, then curl 7. **Iterate** — create a new revision > **Public by default.** A `ApplicationManaged` endpoint is reachable by **anyone on the internet with the URL** — there is no AWS-layer auth and no built-in WAF, and the URL is not a secret. Before deploying, **ask the user** which they want: > > - **`ApplicationManaged`** (public) — the **app** must implement its own authentication/authorization, input validation, and rate limiting. > - **`IamAuth`** (internal) — only callers with valid IAM credentials (SigV4-signed) can reach it. > > If the endpoint is public, the app owns its security. See [references/iam-and-security.md](references/iam-and-security.md) for the security checklist (auth, input validation, rate limiting, WAF/CloudFront, least-privilege role, secrets). ## Quick Start (Express) ```javascript // index.js import express from 'express'; import helmet from 'helmet'; import { fileURLToPath } from 'url'; import { dirname, join } from 'path'; const __dirname = dirname(fileURLToPath(import.meta.url)); const app = express(); // The runtime probes this exact host:port for readiness. const [HOST, PORT] = (process.env.AWS_LAMBDA_HTTP_ENDPOINT || '0.0.0.0:3000').split(':'); app.use(helmet()); app.use(express.static(join(__dirname, 'public'))); app.use(express.json({ limit: '10mb' })); app.get('/api/health', (req, res) => res.json({ status: 'ok' })); app.listen(PORT, HOST, () => console.log(`Listening on ${HOST}:${PORT}`)); ``` ```json { "name": "my-web-app", "type": "module", "scripts": { "start": "node index.js", "dev": "node --watch index.js" }, "dependencies": { "express": "^5.0.0", "helmet": "^8.0.0" } } ``` `helmet` sets the security response headers (HSTS, CSP, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`) that no AWS layer sets for you here. On an `ApplicationManaged` endpoint the app is the only thing that can set them, so it belongs in the scaffold rather than being added later. ## Resource Naming All resources are project-scoped. Derive names from the function name: | Resource | Default Pattern | Example | |---|---|---| | Function | `{name}` | `my-api` | | IAM Role | `{name}-web-role` | `my-api-web-role` | | S3 bucket | `{name}-web-{account}` | `my-api-web-1234567890` | | S3 key | `{name}/function.zip` | `my-api/function.zip` | | DynamoDB | `{name}-{purpose}` | `my-api-items` | Function names must be unique across **all Regions** in the account — the same name cannot exist in two Regions, and a collision fails at create time with a conflict error. **Ask the user** which S3 strategy they prefer: - **Separate bucket per project** (default) — fully isolated, easy cleanup - **Shared bucket across projects** (e.g., `{account}-web-code`) — fewer resources, key-prefix isolation - **Custom** — user provides their own bucket name and key prefix `aws lambda-web deploy` names its own role (`awscli-lambdaweb-{name}`) and bucket (`awscli-lambdaweb-{account}-{region}-an`). ## Deploy (CLI) The `aws lambda-web` CLI is the primary, supported path — use it by default. The flow is: one-time S3 code bucket (versioning + Lambda read access), then `npm ci --omit=dev` → `zip` → `aws s3 cp` → `aws lambda-web create-web-function` with `--revision-config` and `--endpoint-config`, then wait for the endpoint to reach `Active`. If the project has a build step, run it **before** the prune — `npm ci --omit=dev` removes the bundler. When the user asks for one command or already deploys with it, `aws lambda-web deploy --name {name} --code . --create --auth-type {auth-type}` (ask the user which auth type) zips, uploads, and creates the function, a code bucket, a role and a `dev` endpoint; rerun it without `--create` to ship changes. Install dependencies first. For the full commands, `EndpointConfig` and `RevisionConfig` field rules, packaging, timeout, concurrency, environment variables, logging config and every `deploy` flag, see [references/deployment.md](references/deployment.md). First-time setup (bucket, execution role, first deploy) is in [references/getting-started.md](references/getting-started.md). For CloudFormation, CDK or SAM, see [references/infrastructure-as-code.md](references/infrastructure-as-code.md). ### Multi-Region Multi-region is supported: a `MultiRegion` endpoint serves your revision from several regions behind **one hostname**, with Route53 routing each caller to the nearest region. `PerRegion` additionally gives each region its own domain name. Both require `autoDeploymentMode: Disabled`, and the app must be region-agnostic — consecutive requests from one client can land in different regions, so keep state in a replicated store, never in the execution environment or `/tmp`. See [references/domains-and-routing.md](references/domains-and-routing.md) for endpoint types, domains, traffic routing and the multi-region setup commands. ### VPC Egress By default a revision reaches the public internet over IPv4 and nothing private. To reach your VPC, put a version-qualified egress network connector ARN (`aws lambda-core create-network-connector`, compute type `WebFunction`) in the revision's `serviceConfig.egressNetworkConnectorArn`, serve it from a `HomeRegion` endpoint, and read the field back after every revision. See [references/networking.md](references/networking.md), or [references/infrastructure-as-code.md](references/infrastructure-as-code.md) to declare the connector and the revision in one stack. ## Verify ```bash aws lambda-web get-web-function-endpoint \ --function-name {name} --endpoint-name default --region {region} # curl the domainName from the response curl https://{domainName}/api/health ``` A revision that fails to start still goes `Active`, so curl a real route after every deploy. `aws lambda-web deploy` prints the endpoint as `endpointUrl` and names its first endpoint `dev`. > Prefer waiters (`aws lambda-web wait ...`) over polling loops or `sleep`. Available: `web-function-active`, `web-function-revision-active`, `web-function-endpoint-active`, `web-function-endpoint-updated`, `web-function-endpoint-deleted`, `web-function-deleted` ## Update Code ```bash zip -r function.zip index.js package.json node_modules/ public/ \ -x "*.test.*" -x ".git/*" -x ".env" -x "node_modules/.cache/*" aws s3 cp function.zip s3://{bucket}/{name}/function.zip aws lambda-web create-web-function-revision \ --function-name {name} \ --build-config '{ "codeConfig": {"s3Object": {"bucket": "{bucket}", "key": "{name}/function.zip"}}, "runtimeConfig": {"runtime": "nodejs24.x"} }' \ --service-config '{"executionRoleArn": "arn:aws:iam::{account}:role/{name}-web-role"}' \ --region {region} ``` ## Service Limits Subject to change — check the [Lambda quotas page](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) for the authoritative values. | Scope | Resource | Limit | |-------|----------|-------| | Account | Regional vCPU limit | 2,000 | | Account | Regional account rate limit | 100,000 RPS | | Account | Regional per-endpoint maximum rate limit | 10,000 RPS | | Per function | Endpoints | 10 | | Per function | Revisions retained | 50 (oldest unreferenced revisions are deleted automatically) | | Per function | Environment variables | 32 KB total | | Per function | Deployment package | 512 MB | | Per function | Function and endpoint name | 64 characters | | Per endpoint | Endpoint rate limit | Limited by Regional per-endpoint maximum rate limit (above). User can optionally configure a lower rate limit on individual endpoints via `throttleConfig.rateLimit` | | Per endpoint | Active revisions | 2 | | Per environment | vCPU | 2 | | Per environment | Memory | 2 GB | | Per environment | Concurrency | 1–128 requests (see [scaling-and-concurrency.md](references/scaling-and-concurrency.md)) | | Per environment | Network bandwidth | 1 Gbps | | Per environment | `/tmp` | 512 MB | | Per environment | File descriptors | 1,024 | | Per environment | Processes and threads | 1,024 | | Per environment | Init timeout | 10 seconds | | Per request | Timeout | 3–900 s (default 30 s) | | Per request | Header count | 6,300 | ## Cost Model Four billing dimensions: **CPU, memory, requests, and data transfer**. Check the [Lambda pricing page](https://aws.amazon.com/lambda/pricing/) for current rates — do not quote rates from memory. What decides an architecture is the shape of the bill: - **Active CPU, not wall-clock duration.** Time a request spends blocked on I/O — a database call, another API, a model endpoint — is not billed as CPU. Event Functions bill GB-seconds of wall-clock duration instead, so the same handler bills differently on each. - **Memory is billed on consumption, not on a provisioned setting.** An environment is 2 vCPU and 2 GB (see Service Limits) and there is no memory dial, so the familiar Event Functions move of raising memory to shorten duration has no equivalent here. - **Concurrency is the density lever.** One environment serves up to `maxConcurrencyPerEnvironment` requests, so an I/O-bound app keeps many requests in flight per environment instead of occupying one environment each. Two consequences worth planning around: - **I/O-bound workloads are the economical case.** A handler that spends most of its life waiting on the network, sharing an environment with other requests, costs less here than the same handler billed per-invoke on wall-clock duration. - **CPU-bound workloads give that advantage back.** Heavy rendering, image processing or crypto burns billable CPU wherever it runs, and an environment is allocated 2 vCPU — of which a single-threaded Node process uses only one (see Anti-Patterns). For sustained high-volume CPU work, especially where committed-use discounts apply, compare **`aws-lambda-managed-instances`**. An endpoint's scaling controls `scalingConfig.maxEnvironments` and `throttleConfig.rateLimit` can be used to limit potential cost. Set them only when the user asks for a cap. See [scaling-and-concurrency.md](references/scaling-and-concurrency.md) for more details. ## IAM Setup Trust policy principal: `lambda.amazonaws.com` IAM actions use the `lambda:` prefix. Resource ARN: `arn:aws:lambda:{region}:{account}:web-function/{name}` Action names match the API operations — `lambda:CreateWebFunction`, `lambda:CreateWebFunctionRevision`, `lambda:CreateWebFunctionEndpoint`, `lambda:UpdateWebFunctionEndpoint`, plus the `Get*`, `List*`, and `Delete*` variants. See [references/iam-and-security.md](references/iam-and-security.md) for the full policy. Resource ARN must include `/*` wildcard for endpoint/revision operations: ```