The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type * as LambdaWeb from "@distilled.cloud/aws/lambda-web"; |
| 2 | import { deepEqual, isResolved } from "alchemy/Diff"; |
| 3 | import * as Provider from "alchemy/Provider"; |
| 4 | import { Resource } from "alchemy/Resource"; |
| 5 | import * as Effect from "effect/Effect"; |
| 6 | import type { Providers } from "../Providers.ts"; |
| 7 | import { connectorOfRevision, releaseEgressConnector, sameConnector } from "./WebFunctionEgress.ts"; |
| 8 | import { |
| 9 | deleteEndpoint, |
| 10 | endpointIdentityChanged, |
| 11 | endpointLimits, |
| 12 | getEndpoint, |
| 13 | latestRevisionId, |
| 14 | servedRevisions, |
| 15 | syncEndpoint, |
| 16 | toEndpointName, |
| 17 | validateWebFunctionSettings, |
| 18 | type WebFunctionAuthType, |
| 19 | type WebFunctionCanary, |
| 20 | type WebFunctionEndpointType, |
| 21 | type WebFunctionRevisionWeight, |
| 22 | } from "./WebFunctionEndpointSync.ts"; |
| 23 | |
| 24 | export const WebFunctionEndpointTypeId = "AWS.Lambda.WebFunctionEndpoint" as const; |
| 25 | export type WebFunctionEndpointTypeId = typeof WebFunctionEndpointTypeId; |
| 26 | |
| 27 | /** The parts of a Web Function an endpoint routes to. */ |
| 28 | export interface WebFunctionRef { |
| 29 | functionName: string; |
| 30 | revisionId: string; |
| 31 | } |
| 32 | |
| 33 | /** |
| 34 | * A resource or its declaration (e.g. a `WebFunction` class), which is |
| 35 | * yielded for you. |
| 36 | */ |
| 37 | type Ref<T> = T | Effect.Effect<T, never, Providers>; |
| 38 | |
| 39 | export interface WebFunctionEndpointProps { |
| 40 | /** |
| 41 | * The Web Function this endpoint serves: the `AWS.Lambda.WebFunction` |
| 42 | * resource, or its class declaration. The endpoint routes traffic to the |
| 43 | * function's latest revision and follows it on every deploy. Changing |
| 44 | * the function recreates the endpoint, which gets a new URL. |
| 45 | */ |
| 46 | function: Ref<WebFunctionRef>; |
| 47 | /** |
| 48 | * Name of the endpoint. Your server receives it in the |
| 49 | * `lambda-web-endpoint-name` request header. Letters, digits, `-` and |
| 50 | * `_`, up to 64 characters. Changing it recreates the endpoint, which gets |
| 51 | * a new URL. |
| 52 | * @default the logical ID |
| 53 | */ |
| 54 | endpointName?: string; |
| 55 | /** |
| 56 | * Who may call the endpoint. `"ApplicationManaged"` forwards every request |
| 57 | * (a public endpoint; authenticate in your application). `"IamAuth"` |
| 58 | * requires SigV4-signed requests from principals with |
| 59 | * `lambda:InvokeWebFunctionEndpoint`. Changes apply in place. |
| 60 | */ |
| 61 | authType: WebFunctionAuthType; |
| 62 | /** |
| 63 | * Additional AWS Regions to serve from. When set, the endpoint is |
| 64 | * `MultiRegion`: one global domain with latency-based routing across the |
| 65 | * home Region and these Regions. Changing it recreates the endpoint, which |
| 66 | * gets a new URL. |
| 67 | */ |
| 68 | regions?: string[]; |
| 69 | /** |
| 70 | * Maximum number of execution environments this endpoint uses per Region |
| 71 | * (2–10,000). Endpoints scale independently. Changes apply in place. |
| 72 | */ |
| 73 | maxEnvironments?: number; |
| 74 | /** |
| 75 | * Maximum requests per second this endpoint accepts, enforced per Region. |
| 76 | * Excess requests receive HTTP 429; `0` disables the endpoint. Changes |
| 77 | * apply in place. |
| 78 | */ |
| 79 | rateLimit?: number; |
| 80 | /** |
| 81 | * Roll out deploys gradually on this endpoint: the revision a deploy |
| 82 | * publishes gets `weight` percent of traffic and the revision the |
| 83 | * endpoint served before keeps the rest. Set it to `100` (or remove |
| 84 | * `canary`) to promote, or `0` to roll back. Independent of the function's |
| 85 | * own `canary`. |
| 86 | */ |
| 87 | canary?: WebFunctionCanary; |
| 88 | /** |
| 89 | * Description of the endpoint. |
| 90 | */ |
| 91 | description?: string; |
| 92 | } |
| 93 | |
| 94 | export interface WebFunctionEndpoint extends Resource< |
| 95 | WebFunctionEndpointTypeId, |
| 96 | WebFunctionEndpointProps, |
| 97 | { |
| 98 | /** Name of the Web Function the endpoint serves. */ |
| 99 | functionName: string; |
| 100 | /** ARN of the Web Function the endpoint serves. */ |
| 101 | functionArn: string; |
| 102 | /** Auth type of the endpoint. */ |
| 103 | authType: WebFunctionAuthType; |
| 104 | /** |
| 105 | * `HomeRegion`, or `MultiRegion` when `regions` is set: one global |
| 106 | * domain that routes each request to the nearest Region. |
| 107 | */ |
| 108 | endpointType: WebFunctionEndpointType; |
| 109 | /** Name of the endpoint. */ |
| 110 | endpointName: string; |
| 111 | /** ARN of the endpoint, the resource for `lambda:InvokeWebFunctionEndpoint`. */ |
| 112 | endpointArn: string; |
| 113 | /** Lambda-allocated domain of the endpoint. */ |
| 114 | domainName: string; |
| 115 | /** HTTPS URL of the endpoint (`https://<domainName>`). */ |
| 116 | url: string; |
| 117 | /** |
| 118 | * The function's latest revision, which the endpoint routes all traffic |
| 119 | * to, or `canary.weight` percent while a canary runs. |
| 120 | */ |
| 121 | revisionId: string; |
| 122 | /** |
| 123 | * How the endpoint splits traffic: one revision at 100, or the stable |
| 124 | * revision and the canary while a canary runs. |
| 125 | */ |
| 126 | revisionWeights: WebFunctionRevisionWeight[]; |
| 127 | /** |
| 128 | * Requests per second the endpoint allows, as observed. Lets |
| 129 | * `alchemy drift` detect out-of-band changes. |
| 130 | */ |
| 131 | rateLimit?: number; |
| 132 | /** |
| 133 | * Cap on the endpoint's execution environments, as observed. Lets |
| 134 | * `alchemy drift` detect out-of-band changes. |
| 135 | */ |
| 136 | maxEnvironments?: number; |
| 137 | }, |
| 138 | never, |
| 139 | Providers |
| 140 | > {} |
| 141 | |
| 142 | const WebFunctionEndpointResource = Resource<WebFunctionEndpoint>(WebFunctionEndpointTypeId); |
| 143 | |
| 144 | /** Yield a `function` declaration so the endpoint references the resource. */ |
| 145 | /** The settings Lambda limits, as numbers (Outputs resolve at deploy). */ |
| 146 | const checkEndpointProps = (id: string, props: WebFunctionEndpointProps) => |
| 147 | validateWebFunctionSettings(`AWS.Lambda.WebFunctionEndpoint "${id}"`, { |
| 148 | rateLimit: typeof props.rateLimit === "number" ? props.rateLimit : undefined, |
| 149 | maxEnvironments: typeof props.maxEnvironments === "number" ? props.maxEnvironments : undefined, |
| 150 | canary: typeof props.canary?.weight === "number" ? props.canary : undefined, |
| 151 | }); |
| 152 | |
| 153 | const resolveEndpointProps = ( |
| 154 | id: string, |
| 155 | props: WebFunctionEndpointProps | Effect.Effect<WebFunctionEndpointProps, never, Providers>, |
| 156 | ): Effect.Effect<WebFunctionEndpointProps, never, Providers> => |
| 157 | Effect.gen(function* () { |
| 158 | const resolved = Effect.isEffect(props) ? yield* props : props; |
| 159 | if (globalThis.__ALCHEMY_RUNTIME__) return resolved; |
| 160 | const fn = Effect.isEffect(resolved.function) ? yield* resolved.function : resolved.function; |
| 161 | // Declaration props can't fail: surface the invalid value as a defect, |
| 162 | // which still stops the plan with its message. |
| 163 | yield* checkEndpointProps(id, resolved).pipe( |
| 164 | Effect.catchTag("WebFunctionInvalidConfig", (e) => Effect.die(e)), |
| 165 | ); |
| 166 | return { ...resolved, function: fn }; |
| 167 | }); |
| 168 | |
| 169 | /** |
| 170 | * An additional HTTPS endpoint for an `AWS.Lambda.WebFunction`. |
| 171 | * |
| 172 | * Every Web Function has a built-in endpoint, configured on the function. |
| 173 | * Add a `WebFunctionEndpoint` for each extra way in: its own URL, auth type, |
| 174 | * environment cap, and rate limit. Endpoints scale independently of each |
| 175 | * other but serve the same code, so a burst on one can't use up another's |
| 176 | * environments. Your server tells them apart by the |
| 177 | * `lambda-web-endpoint-name` request header, which callers can't forge. |
| 178 | * |
| 179 | * ### Adding an endpoint |
| 180 | * **Example:** A public webhook endpoint next to a private one |
| 181 | * ```typescript |
| 182 | * const api = yield* AWS.Lambda.WebFunction("Api", { |
| 183 | * main: "./src/server.ts", |
| 184 | * authType: "IamAuth", |
| 185 | * }); |
| 186 | * |
| 187 | * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", { |
| 188 | * function: api, |
| 189 | * authType: "ApplicationManaged", |
| 190 | * rateLimit: 100, |
| 191 | * maxEnvironments: 2, |
| 192 | * }); |
| 193 | * |
| 194 | * webhooks.url; // https://<id>.<shard>.lambda-web.<region>.on.aws |
| 195 | * ``` |
| 196 | * |
| 197 | * **Example:** With a class-form Web Function |
| 198 | * Pass the class itself (here `Api`, declared with |
| 199 | * `class Api extends AWS.Lambda.WebFunction<Api>()(...)`); the endpoint |
| 200 | * yields it for you. |
| 201 | * ```typescript |
| 202 | * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", { |
| 203 | * function: Api, |
| 204 | * authType: "ApplicationManaged", |
| 205 | * }); |
| 206 | * ``` |
| 207 | * |
| 208 | * ### Canary deploys |
| 209 | * **Example:** Roll out to the public endpoint more slowly |
| 210 | * ```typescript |
| 211 | * // The function's own endpoint takes each deploy at once; this one |
| 212 | * // sends 5% to the new revision until you raise or remove `canary`. |
| 213 | * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", { |
| 214 | * function: api, |
| 215 | * authType: "ApplicationManaged", |
| 216 | * canary: { weight: 5 }, |
| 217 | * }); |
| 218 | * ``` |
| 219 | * |
| 220 | * ### Routing by endpoint |
| 221 | * **Example:** Serve only webhook routes on the public endpoint |
| 222 | * ```typescript |
| 223 | * // src/server.ts (a Hono app) |
| 224 | * app.use(async (c, next) => { |
| 225 | * const endpoint = c.req.header("lambda-web-endpoint-name"); |
| 226 | * if (endpoint === "Webhooks" && !c.req.path.startsWith("/webhooks/")) { |
| 227 | * return c.notFound(); |
| 228 | * } |
| 229 | * await next(); |
| 230 | * }); |
| 231 | * ``` |
| 232 | * |
| 233 | * @resource |
| 234 | */ |
| 235 | export const WebFunctionEndpoint: typeof WebFunctionEndpointResource = Object.assign( |
| 236 | ( |
| 237 | id: string, |
| 238 | props: WebFunctionEndpointProps | Effect.Effect<WebFunctionEndpointProps, never, Providers>, |
| 239 | ) => WebFunctionEndpointResource(id, resolveEndpointProps(id, props)), |
| 240 | WebFunctionEndpointResource, |
| 241 | ); |
| 242 | |
| 243 | /** A declared `function` resolves to the resource before the provider runs. */ |
| 244 | const functionOf = (props: WebFunctionEndpointProps): WebFunctionRef => |
| 245 | props.function as WebFunctionRef; |
| 246 | |
| 247 | export const WebFunctionEndpointProvider = () => |
| 248 | Provider.effect( |
| 249 | WebFunctionEndpoint, |
| 250 | Effect.gen(function* () { |
| 251 | const nameOf = (id: string, props: { endpointName?: string } | undefined) => |
| 252 | props?.endpointName ?? toEndpointName(id); |
| 253 | |
| 254 | const toAttributes = ( |
| 255 | functionName: string, |
| 256 | endpoint: LambdaWeb.GetWebFunctionEndpointResponse, |
| 257 | revisionId: string, |
| 258 | ): WebFunctionEndpoint["Attributes"] => ({ |
| 259 | functionName, |
| 260 | functionArn: endpoint.functionArn, |
| 261 | authType: endpoint.authType as WebFunctionAuthType, |
| 262 | endpointType: endpoint.endpointType as WebFunctionEndpointType, |
| 263 | endpointName: endpoint.endpointName, |
| 264 | endpointArn: endpoint.endpointArn, |
| 265 | domainName: endpoint.domainName, |
| 266 | url: `https://${endpoint.domainName}`, |
| 267 | revisionId, |
| 268 | revisionWeights: servedRevisions(endpoint), |
| 269 | ...endpointLimits(endpoint), |
| 270 | }); |
| 271 | |
| 272 | return { |
| 273 | stables: ["functionName", "endpointName", "endpointArn"], |
| 274 | diff: Effect.fn(function* ({ id, olds, news, output }) { |
| 275 | if (!isResolved(news)) return; |
| 276 | yield* validateWebFunctionSettings(`AWS.Lambda.WebFunctionEndpoint "${id}"`, { |
| 277 | rateLimit: news.rateLimit, |
| 278 | maxEnvironments: news.maxEnvironments, |
| 279 | canary: news.canary, |
| 280 | }); |
| 281 | if (!output || !olds) return undefined; |
| 282 | // A different function, name, type, or Region set is a different |
| 283 | // endpoint (and URL). The name is shared with the old endpoint on |
| 284 | // the same function, so the old one must go first. |
| 285 | const sameFunction = functionOf(news).functionName === output.functionName; |
| 286 | const sameName = nameOf(id, news) === output.endpointName; |
| 287 | if (!sameFunction || !sameName) { |
| 288 | return { action: "replace" }; |
| 289 | } |
| 290 | if (endpointIdentityChanged(olds, news)) { |
| 291 | return { action: "replace", deleteFirst: true }; |
| 292 | } |
| 293 | if (deepEqual(olds, news)) return { action: "noop" }; |
| 294 | }), |
| 295 | read: Effect.fn(function* ({ id, olds, output }) { |
| 296 | const functionName = |
| 297 | output?.functionName ?? (olds ? functionOf(olds).functionName : undefined); |
| 298 | if (functionName === undefined) return undefined; |
| 299 | const endpointName = output?.endpointName ?? nameOf(id, olds); |
| 300 | const endpoint = yield* getEndpoint(functionName, endpointName); |
| 301 | // Endpoints carry their function's tags: ownership follows the |
| 302 | // function's. |
| 303 | return endpoint === undefined |
| 304 | ? undefined |
| 305 | : toAttributes(functionName, endpoint, latestRevisionId(endpoint, output?.revisionId)); |
| 306 | }), |
| 307 | reconcile: Effect.fn(function* ({ id, news, output, session }) { |
| 308 | // Values that were Outputs at plan are resolved now. |
| 309 | yield* checkEndpointProps(id, news); |
| 310 | const functionName = functionOf(news).functionName; |
| 311 | const endpointName = output?.endpointName ?? nameOf(id, news); |
| 312 | const previous = yield* getEndpoint(functionName, endpointName); |
| 313 | const revisionId = functionOf(news).revisionId; |
| 314 | const endpoint = yield* syncEndpoint({ |
| 315 | functionName, |
| 316 | spec: { |
| 317 | endpointName, |
| 318 | authType: news.authType, |
| 319 | regions: news.regions, |
| 320 | maxEnvironments: news.maxEnvironments, |
| 321 | rateLimit: news.rateLimit, |
| 322 | description: news.description, |
| 323 | canary: news.canary, |
| 324 | }, |
| 325 | revisionId, |
| 326 | published: output?.revisionId, |
| 327 | session, |
| 328 | }); |
| 329 | // Moving off a revision whose egress connector the new one no |
| 330 | // longer uses (e.g. `vpc` removed) may leave it unused. |
| 331 | const stillServed = new Set(servedRevisions(endpoint).map((w) => w.revisionId)); |
| 332 | for (const { revisionId: previousRevisionId } of previous |
| 333 | ? servedRevisions(previous) |
| 334 | : []) { |
| 335 | if (stillServed.has(previousRevisionId)) continue; |
| 336 | const previousConnector = yield* connectorOfRevision(functionName, previousRevisionId); |
| 337 | const currentConnector = yield* connectorOfRevision(functionName, revisionId); |
| 338 | if ( |
| 339 | previousConnector !== undefined && |
| 340 | !sameConnector(previousConnector, currentConnector) |
| 341 | ) { |
| 342 | yield* releaseEgressConnector({ |
| 343 | functionName, |
| 344 | connectorArn: previousConnector, |
| 345 | session, |
| 346 | }); |
| 347 | } |
| 348 | } |
| 349 | yield* session.note(`https://${endpoint.domainName}`); |
| 350 | return toAttributes(functionName, endpoint, revisionId); |
| 351 | }), |
| 352 | delete: Effect.fn(function* ({ output }) { |
| 353 | // Deleting the function deletes its endpoints too; a missing |
| 354 | // function or endpoint is already deleted. |
| 355 | yield* deleteEndpoint(output.functionName, output.endpointName); |
| 356 | }), |
| 357 | }; |
| 358 | }), |
| 359 | ); |