The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 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 | ::: |