aws-lambda-web-functions

Files (14)

• SKILL.md
• architecture-patterns.md · references/
• deployment.md · references/
• domains-and-routing.md · references/
• frameworks.md · references/
• getting-started.md · references/
• iam-and-security.md · references/
• infrastructure-as-code.md · references/
• migration.md · references/
• networking.md · references/
• observability.md · references/
• scaling-and-concurrency.md · references/
• static-assets.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# 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

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws