The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 418 lines 12.4 KB
Raw
1 ---
2 title: Lambda Web Functions
3 description: Run an HTTP server on AWS Lambda Web Functions — an Effect fetch handler or any Node server, with streaming responses, many concurrent requests per environment, and a built-in HTTPS endpoint.
4 ---
5
6 A **Lambda Web Function** runs your HTTP server on Lambda. Each execution
7 environment serves many requests at once (up to 128), responses stream to
8 the client as you produce them, and every function gets an HTTPS endpoint.
9 It scales to zero when idle.
10
11 Use it for anything that answers HTTP: APIs, server-rendered apps, AI
12 responses streamed token by token. The [AWS websites](/aws/frontend/websites)
13 (Nuxt, SvelteKit, Astro, and the rest) run their server on one by
14 default. For queues, streams, schedules, and
15 other event sources, use a [Lambda Function](/aws/compute/lambda).
16
17 :::caution
18 Web Functions run Node.js 24 on Arm64. They launched in `us-east-1`,
19 `us-east-2`, `us-west-2`, `eu-west-1`, and `ap-northeast-1`, and AWS is
20 adding Regions: check the [Lambda pricing page](https://aws.amazon.com/lambda/pricing/)
21 for where they run today. Code ships through the Alchemy assets bucket, so
22 run `alchemy provider aws bootstrap` once per account and Region.
23 :::
24
25 ## Declare a Web Function
26
27 Create `src/api.ts` and return a `fetch` handler:
28
29 ```typescript
30 // src/api.ts
31 import * as AWS from "@alchemy.run/aws";
32 import * as Effect from "effect/Effect";
33 import * as HttpServerResponse from "effect/http/HttpServerResponse";
34
35 export default class Api extends AWS.Lambda.WebFunction<Api>()(
36 "Api",
37 { main: import.meta.url, authType: "ApplicationManaged" },
38 Effect.gen(function* () {
39 return {
40 fetch: Effect.succeed(HttpServerResponse.text("Hello from Lambda!")),
41 };
42 }),
43 ) {}
44 ```
45
46 Your `fetch` handler runs on a Node HTTP server inside the Web Function, so
47 the same `effect/http` code you'd run anywhere else works unchanged.
48 `authType: "ApplicationManaged"` makes its endpoint public: every request
49 reaches your code.
50
51 ## Deploy it
52
53 Yield the class in your Stack and return its `url`:
54
55 ```typescript
56 // alchemy.run.ts
57 import * as Alchemy from "alchemy";
58 import * as AWS from "@alchemy.run/aws";
59 import * as Effect from "effect/Effect";
60 import Api from "./src/api.ts";
61
62 export default Alchemy.Stack(
63 "MyApp",
64 {
65 providers: AWS.providers(),
66 state: AWS.state(),
67 },
68 Effect.gen(function* () {
69 const api = yield* Api;
70 return { url: api.url };
71 }),
72 );
73 ```
74
75 ```sh
76 bun alchemy deploy
77 ```
78
79 The `url` looks like `https://<id>.<shard>.lambda-web.us-west-2.on.aws`.
80 Every deploy publishes a new revision and moves all traffic to it.
81
82 ## Stream a response
83
84 Return a streamed body and the client receives each chunk as soon as you
85 produce it:
86
87 ```diff lang="typescript"
88 // src/api.ts
89 import * as AWS from "@alchemy.run/aws";
90 import * as Effect from "effect/Effect";
91 import * as HttpServerResponse from "effect/http/HttpServerResponse";
92 +import * as Stream from "effect/Stream";
93
94 export default class Api extends AWS.Lambda.WebFunction<Api>()(
95 "Api",
96 { main: import.meta.url, authType: "ApplicationManaged" },
97 Effect.gen(function* () {
98 return {
99 - fetch: Effect.succeed(HttpServerResponse.text("Hello from Lambda!")),
100 + fetch: Effect.succeed(
101 + HttpServerResponse.stream(
102 + Stream.make("Hello", " from", " Lambda!").pipe(
103 + Stream.tap(() => Effect.sleep("200 millis")),
104 + Stream.encodeText,
105 + ),
106 + { contentType: "text/plain" },
107 + ),
108 + ),
109 };
110 }),
111 ) {}
112 ```
113
114 ## Use AWS resources
115
116 Bindings work the same as on a Lambda Function. Binding an operation
117 grants the function's role exactly that permission:
118
119 ```diff lang="typescript"
120 // src/api.ts
121 import * as AWS from "@alchemy.run/aws";
122 import * as Effect from "effect/Effect";
123 import * as HttpServerResponse from "effect/http/HttpServerResponse";
124
125 export default class Api extends AWS.Lambda.WebFunction<Api>()(
126 "Api",
127 { main: import.meta.url, authType: "ApplicationManaged" },
128 Effect.gen(function* () {
129 + const bucket = yield* AWS.S3.Bucket("Uploads");
130 + const putObject = yield* AWS.S3.PutObject(bucket);
131 return {
132 - fetch: Effect.succeed(HttpServerResponse.text("Hello from Lambda!")),
133 + fetch: Effect.gen(function* () {
134 + yield* putObject({ Key: "hello.txt", Body: "Hello!" });
135 + return HttpServerResponse.text("Saved");
136 + }).pipe(Effect.orDie),
137 };
138 - }),
139 + }).pipe(Effect.provide(AWS.S3.PutObjectHttp)),
140 ) {}
141 ```
142
143 ## Bring an existing server
144
145 You don't need Effect. Point `main` at your own Node server, such as a Hono
146 app. Alchemy bundles it as it is, with no wrapper and no Effect runtime.
147 Listen on the address Lambda passes in `AWS_LAMBDA_HTTP_ENDPOINT`:
148
149 ```typescript
150 // src/server.ts
151 import { serve } from "@hono/node-server";
152 import { Hono } from "hono";
153
154 const app = new Hono();
155 app.get("/", (c) => c.text(`Hello from ${c.req.path}`));
156
157 const [hostname, port] = (process.env.AWS_LAMBDA_HTTP_ENDPOINT ?? "localhost:3000").split(":");
158 serve({ fetch: app.fetch, hostname, port: Number(port) });
159 ```
160
161 ```typescript
162 // alchemy.run.ts
163 import * as Alchemy from "alchemy";
164 import * as AWS from "@alchemy.run/aws";
165 import * as Effect from "effect/Effect";
166
167 export default Alchemy.Stack(
168 "MyApp",
169 { providers: AWS.providers(), state: AWS.state() },
170 Effect.gen(function* () {
171 const api = yield* AWS.Lambda.WebFunction("Api", {
172 main: "./src/server.ts",
173 authType: "ApplicationManaged",
174 });
175 return { url: api.url };
176 }),
177 );
178 ```
179
180 Express, Fastify and plain `node:http` work the same way:
181
182 ```typescript
183 // src/server.ts
184 import express from "express";
185
186 const app = express();
187 app.get("/", (_req, res) => res.send("Hello from Express"));
188
189 const [host, port] = (process.env.AWS_LAMBDA_HTTP_ENDPOINT ?? "localhost:3000").split(":");
190 app.listen(Number(port), host);
191 ```
192
193 For a framework's standalone build output, set `bundle: false` to deploy
194 the directory as it is. Lambda starts `main`, so it must listen on
195 `AWS_LAMBDA_HTTP_ENDPOINT` too:
196
197 ```typescript
198 const site = yield* AWS.Lambda.WebFunction("Site", {
199 main: "./.output/server/index.mjs",
200 bundle: false,
201 authType: "ApplicationManaged",
202 });
203 ```
204
205 ## Tune concurrency and traffic
206
207 Set how many requests one environment serves, the per-request timeout,
208 and caps on environments and requests per second:
209
210 ```typescript
211 const api = yield* AWS.Lambda.WebFunction("Api", {
212 main: "./src/server.ts",
213 authType: "ApplicationManaged",
214 maxConcurrencyPerEnvironment: 128,
215 timeout: Duration.minutes(5),
216 maxEnvironments: 10,
217 rateLimit: 500,
218 });
219 ```
220
221 `maxConcurrencyPerEnvironment` is a cap per environment, not a total: at
222 most `maxEnvironments × maxConcurrencyPerEnvironment` requests are in
223 flight. Lower it for CPU-heavy servers. Requests beyond `rateLimit` get
224 HTTP 429. A value Lambda doesn't accept, such as `rateLimit: 1500`, fails
225 at plan with the allowed range.
226
227 Each environment has 2 GB of memory and 2 vCPUs, and you can't change
228 that. Node's heap defaults to 1 GB; raise it with
229 `env: { NODE_OPTIONS: "--max-old-space-size=1536" }`.
230
231 ## Roll out gradually
232
233 Set `canary` to send a share of traffic to each new deploy while the
234 previous revision keeps the rest:
235
236 ```typescript
237 const api = yield* AWS.Lambda.WebFunction("Api", {
238 main: "./src/server.ts",
239 authType: "ApplicationManaged",
240 canary: { weight: 10 },
241 });
242 ```
243
244 The next deploy that changes code or configuration sends 10% of requests
245 to the new revision and 90% to the one before. Changing `weight` shifts
246 traffic without publishing a new revision. Set it to `100`, or remove
247 `canary`, to promote the new revision. Set it to `0` to roll back: all
248 traffic returns to the previous revision.
249
250 Deploying again during a canary replaces the canary and keeps the
251 previous revision, so traffic never lands on more than two revisions.
252 `api.revisionWeights` shows the current split. Lambda splits each request
253 on its own, so one client can reach both revisions; keep the two
254 compatible with each other.
255
256 Each endpoint has its own split. Set `canary` on a `WebFunctionEndpoint`
257 to roll it out on its own schedule; an endpoint without `canary` moves to
258 each new revision at once.
259
260 ## Serve from several Regions
261
262 List extra Regions to get one global domain that routes each request to
263 the nearest Region:
264
265 ```typescript
266 const api = yield* AWS.Lambda.WebFunction("Api", {
267 main: "./src/server.ts",
268 authType: "ApplicationManaged",
269 regions: ["us-east-1", "eu-west-1"],
270 });
271 ```
272
273 Changing `regions` gives the endpoint a new URL.
274
275 ## Require signed requests
276
277 Set `authType: "IamAuth"` to accept only SigV4-signed requests from
278 callers allowed to call `lambda:InvokeWebFunctionEndpoint`, such as a
279 CloudFront distribution:
280
281 ```typescript
282 const internal = yield* AWS.Lambda.WebFunction("Internal", {
283 main: "./src/server.ts",
284 authType: "IamAuth",
285 });
286 ```
287
288 To let a specific caller in, such as a role in another account, grant it
289 access to the endpoint:
290
291 ```typescript
292 yield* AWS.Lambda.WebFunctionPermission("PartnerInvoke", {
293 endpoint: internal,
294 principal: "arn:aws:iam::444455556666:role/partner-caller",
295 });
296 ```
297
298 ## Put CloudFront in front
299
300 Serve the function through CloudFront for a custom domain, caching, or
301 AWS WAF. Set `webFunction` on the origin and keep `authType: "IamAuth"`:
302
303 ```typescript
304 const api = yield* AWS.Lambda.WebFunction("Api", {
305 main: "./src/server.ts",
306 authType: "IamAuth",
307 });
308
309 const cdn = yield* AWS.CloudFront.Distribution("Cdn", {
310 origins: [{ id: "api", webFunction: api }],
311 defaultCacheBehavior: { targetOriginId: "api" },
312 });
313 ```
314
315 CloudFront signs every request to the function, and only this
316 distribution may call it, so requests to the function's own URL are
317 refused. Requests pass through uncached with their method, query string,
318 cookies and headers, including your app's own `Authorization` header.
319 Set `cachePolicyId` on a behavior to cache a path, such as static assets.
320 This works for a function with `regions` too: Alchemy signs requests to
321 its global domain with SigV4A.
322
323 ## Reach private resources
324
325 Set `vpc` to send the server's outbound traffic through your VPC, for
326 example to reach a database in private subnets:
327
328 ```typescript
329 const api = yield* AWS.Lambda.WebFunction("Api", {
330 main: "./src/server.ts",
331 authType: "ApplicationManaged",
332 vpc: {
333 subnetIds: network.privateSubnetIds,
334 securityGroupIds: [appSg.groupId],
335 },
336 });
337 ```
338
339 Use at least two subnets in different Availability Zones, and allow the
340 security group on the database. Private subnets need a NAT gateway to
341 reach the internet. A function with `vpc` can't also use `regions`.
342 Remove `vpc` and the next deploy deletes the connector once no endpoint
343 serves through it.
344
345 ## Add another endpoint
346
347 Each endpoint is a separate way in, with its own URL, auth, and limits.
348 Add one with `WebFunctionEndpoint`, for example a public endpoint for
349 webhooks next to a private one:
350
351 ```typescript
352 const api = yield* AWS.Lambda.WebFunction("Api", {
353 main: "./src/server.ts",
354 authType: "IamAuth",
355 maxEnvironments: 50,
356 });
357
358 const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", {
359 function: api,
360 authType: "ApplicationManaged",
361 rateLimit: 100,
362 maxEnvironments: 2,
363 });
364 ```
365
366 `api.url` is the function's own endpoint and `webhooks.url` is the new
367 one. Both serve the same code and follow every deploy, but each scales on
368 its own, so a webhook burst can't use up the other endpoint's capacity.
369
370 For a Web Function declared as a class, like `Api` above, pass the class
371 itself:
372
373 ```typescript
374 // alchemy.run.ts
375 import * as Alchemy from "alchemy";
376 import * as AWS from "@alchemy.run/aws";
377 import * as Effect from "effect/Effect";
378 import Api from "./src/api.ts";
379
380 export default Alchemy.Stack(
381 "MyApp",
382 { providers: AWS.providers(), state: AWS.state() },
383 Effect.gen(function* () {
384 const api = yield* Api;
385 const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", {
386 function: Api,
387 authType: "ApplicationManaged",
388 });
389 return { url: api.url, webhooks: webhooks.url };
390 }),
391 );
392 ```
393
394 Your server sees which endpoint a request came through in the
395 `lambda-web-endpoint-name` header. Use it to keep each endpoint to its own
396 routes:
397
398 ```typescript
399 // src/server.ts
400 app.use(async (c, next) => {
401 const endpoint = c.req.header("lambda-web-endpoint-name");
402 if (endpoint === "Webhooks" && !c.req.path.startsWith("/webhooks/")) {
403 return c.notFound();
404 }
405 await next();
406 });
407 ```
408
409 ## Shutdown
410
411 Lambda stops idle environments with `SIGTERM` and gives them 1 second.
412 In-flight responses finish first, then init-level finalizers run, so keep
413 them short.
414
415 :::note
416 Every prop and attribute is listed in the
417 [`WebFunction` reference](/providers/aws/lambda#webfunction).
418 :::