@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 418 lines 14.4 KB
Raw
1 /**
2 * Endpoint reconciliation shared by `AWS.Lambda.WebFunction` (its built-in
3 * endpoint) and `AWS.Lambda.WebFunctionEndpoint` (additional endpoints).
4 *
5 * NOT exported from `index.ts`.
6 */
7 import * as LambdaWeb from "@distilled.cloud/aws/lambda-web";
8 import { deepEqual } from "alchemy/Diff";
9 import * as Data from "effect/Data";
10 import * as Effect from "effect/Effect";
11 import * as Schedule from "effect/Schedule";
12 import { AWSEnvironment } from "../Environment.ts";
13
14 export class WebFunctionNotReady extends Data.TaggedError("WebFunctionNotReady")<{
15 functionName: string;
16 resource: string;
17 state?: string;
18 }> {
19 override get message() {
20 return `Lambda web function ${this.functionName}: ${this.resource} is ${this.state ?? "not ready"}`;
21 }
22 }
23
24 export class WebFunctionFailed extends Data.TaggedError("WebFunctionFailed")<{
25 functionName: string;
26 resource: string;
27 reason?: string;
28 }> {
29 override get message() {
30 return `Lambda web function ${this.functionName}: ${this.resource} failed: ${this.reason ?? "unknown reason"}`;
31 }
32 }
33
34 export type WebFunctionAuthType = "ApplicationManaged" | "IamAuth";
35
36 /**
37 * Send part of an endpoint's traffic to a new revision and keep the rest on
38 * the revision it served before.
39 */
40 export interface WebFunctionCanary {
41 /**
42 * Percent of traffic (0–100) for the revision this deploy publishes. `0`
43 * rolls back: all traffic returns to the previous revision. `100`
44 * promotes, the same as removing `canary`.
45 */
46 weight: number;
47 }
48
49 /** The settings of one endpoint, as declared on either resource. */
50 export interface WebFunctionEndpointSpec {
51 endpointName: string;
52 authType: WebFunctionAuthType;
53 regions?: readonly string[];
54 maxEnvironments?: number;
55 rateLimit?: number;
56 description?: string;
57 canary?: WebFunctionCanary;
58 }
59
60 /** How an endpoint splits traffic between at most two revisions. */
61 export interface WebFunctionRevisionWeight {
62 revisionId: string;
63 weight: number;
64 }
65
66 /** A setting is outside the range Lambda accepts. */
67 export class WebFunctionInvalidConfig extends Data.TaggedError("WebFunctionInvalidConfig")<{
68 resourceId: string;
69 setting: string;
70 message: string;
71 }> {}
72
73 /**
74 * Check settings against Lambda's limits at plan time, so a bad value fails
75 * before anything is created instead of mid-deploy.
76 */
77 export const validateWebFunctionSettings = (
78 resourceId: string,
79 settings: {
80 rateLimit?: number;
81 maxEnvironments?: number;
82 maxConcurrencyPerEnvironment?: number;
83 timeoutSeconds?: number;
84 canary?: WebFunctionCanary;
85 },
86 ): Effect.Effect<void, WebFunctionInvalidConfig> => {
87 const invalid = (setting: string, message: string) =>
88 Effect.fail(
89 new WebFunctionInvalidConfig({
90 resourceId,
91 setting,
92 message: `"${resourceId}": ${message}`,
93 }),
94 );
95 const { rateLimit, maxEnvironments, maxConcurrencyPerEnvironment, timeoutSeconds, canary } =
96 settings;
97 if (
98 canary !== undefined &&
99 (!Number.isInteger(canary.weight) || canary.weight < 0 || canary.weight > 100)
100 ) {
101 return invalid(
102 "canary",
103 `canary weight ${canary.weight} is not allowed: use a whole number from 0 to 100.`,
104 );
105 }
106 if (rateLimit !== undefined) {
107 const step = rateLimit <= 1000 ? 100 : 1000;
108 if (
109 !Number.isInteger(rateLimit) ||
110 rateLimit < 0 ||
111 rateLimit > 10_000 ||
112 rateLimit % step !== 0
113 ) {
114 const lower = Math.max(0, Math.floor(rateLimit / step) * step);
115 const upper = Math.min(10_000, Math.ceil(rateLimit / step) * step);
116 return invalid(
117 "rateLimit",
118 `rateLimit ${rateLimit} is not allowed: use 0–1,000 in steps of 100 or 1,000–10,000 in steps of 1,000 (e.g. ${lower} or ${upper}).`,
119 );
120 }
121 }
122 if (
123 maxEnvironments !== undefined &&
124 (!Number.isInteger(maxEnvironments) || maxEnvironments < 2 || maxEnvironments > 10_000)
125 ) {
126 return invalid(
127 "maxEnvironments",
128 `maxEnvironments ${maxEnvironments} is not allowed: use a whole number from 2 to 10,000.`,
129 );
130 }
131 if (
132 maxConcurrencyPerEnvironment !== undefined &&
133 (!Number.isInteger(maxConcurrencyPerEnvironment) ||
134 maxConcurrencyPerEnvironment < 1 ||
135 maxConcurrencyPerEnvironment > 128)
136 ) {
137 return invalid(
138 "maxConcurrencyPerEnvironment",
139 `maxConcurrencyPerEnvironment ${maxConcurrencyPerEnvironment} is not allowed: use a whole number from 1 to 128.`,
140 );
141 }
142 if (timeoutSeconds !== undefined && (timeoutSeconds < 3 || timeoutSeconds > 900)) {
143 return invalid(
144 "timeout",
145 `timeout of ${timeoutSeconds} seconds is not allowed: use 3 seconds to 15 minutes.`,
146 );
147 }
148 return Effect.void;
149 };
150
151 export type WebFunctionEndpointType = "HomeRegion" | "MultiRegion";
152
153 export const endpointTypeOf = (regions: readonly string[] | undefined): WebFunctionEndpointType =>
154 regions !== undefined && regions.length > 0 ? "MultiRegion" : "HomeRegion";
155
156 export const normalizeRegions = (regions: readonly string[] | undefined) =>
157 [...new Set(regions ?? [])].sort();
158
159 /** Endpoint type and Regions are immutable: changing them recreates the endpoint. */
160 export const endpointIdentityChanged = (
161 olds: { regions?: readonly string[] },
162 news: { regions?: readonly string[] },
163 ) =>
164 endpointTypeOf(olds.regions) !== endpointTypeOf(news.regions) ||
165 !deepEqual(normalizeRegions(olds.regions), normalizeRegions(news.regions));
166
167 /**
168 * Endpoint names allow letters, digits, `-` and `_`, up to 64 characters,
169 * and can't begin or end with `-` or `_`.
170 */
171 export const toEndpointName = (id: string) =>
172 id
173 .replaceAll(/[^A-Za-z0-9_-]/g, "-")
174 .replace(/^[-_]+|[-_]+$/g, "")
175 .slice(0, 64);
176
177 /** The `endpointConfig` for `CreateWebFunction` (the built-in endpoint). */
178 export const createEndpointConfig = (spec: WebFunctionEndpointSpec): LambdaWeb.EndpointConfig => {
179 const endpointType = endpointTypeOf(spec.regions);
180 return {
181 endpointName: spec.endpointName,
182 description: spec.description,
183 endpointType,
184 ...(endpointType === "MultiRegion" ? { regions: normalizeRegions(spec.regions) } : {}),
185 authType: spec.authType,
186 autoDeploymentMode: "Disabled",
187 ...(spec.maxEnvironments === undefined
188 ? {}
189 : { scalingConfig: { maxEnvironments: spec.maxEnvironments } }),
190 ...(spec.rateLimit === undefined ? {} : { throttleConfig: { rateLimit: spec.rateLimit } }),
191 };
192 };
193
194 export const getEndpoint = (functionName: string, endpointName: string) =>
195 LambdaWeb.getWebFunctionEndpoint({ functionName, endpointName }).pipe(
196 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
197 );
198
199 /**
200 * The rate limit and environment cap an endpoint enforces, as observed.
201 * Both endpoint resources report them so `alchemy drift` detects
202 * out-of-band changes.
203 */
204 export const endpointLimits = (endpoint: LambdaWeb.GetWebFunctionEndpointResponse) => ({
205 rateLimit: endpoint.throttleConfig?.rateLimit,
206 maxEnvironments: endpoint.scalingConfig?.maxEnvironments,
207 });
208
209 /** Revisions an endpoint sends traffic to. */
210 export const servedRevisions = (endpoint: {
211 revisionWeights: readonly WebFunctionRevisionWeight[];
212 }) => endpoint.revisionWeights.filter((w) => w.weight > 0);
213
214 /**
215 * The newest revision an endpoint serves: the canary while one runs,
216 * otherwise the only revision. `published` (the revision the last deploy
217 * published) decides when the endpoint serves two.
218 */
219 export const latestRevisionId = (
220 endpoint: { revisionWeights: readonly WebFunctionRevisionWeight[] },
221 published?: string,
222 ) => {
223 const served = servedRevisions(endpoint);
224 if (published !== undefined && served.some((w) => w.revisionId === published)) {
225 return published;
226 }
227 return [...served].sort((a, b) => a.weight - b.weight)[0]?.revisionId ?? "";
228 };
229
230 /**
231 * Split traffic between the revision this deploy publishes (`revisionId`)
232 * and the stable one the endpoint serves now. The stable revision is the
233 * served revision other than the one the previous deploy published, so a
234 * second code change during a canary replaces the canary and keeps the
235 * stable revision. Without `published` (adoption), the heavier one is
236 * stable.
237 */
238 const revisionWeightsFor = ({
239 observed,
240 revisionId,
241 published,
242 canary,
243 }: {
244 observed: { revisionWeights: readonly WebFunctionRevisionWeight[] } | undefined;
245 revisionId: string;
246 published: string | undefined;
247 canary: WebFunctionCanary | undefined;
248 }): WebFunctionRevisionWeight[] => {
249 const all = [{ revisionId, weight: 100 }];
250 if (canary === undefined || canary.weight >= 100 || observed === undefined) return all;
251 const served = servedRevisions(observed);
252 const stable =
253 published === undefined
254 ? [...served].sort((a, b) => b.weight - a.weight)[0]?.revisionId
255 : (served.find((w) => w.revisionId !== published) ?? served[0])?.revisionId;
256 // Nothing to compare against yet (first deploy), or the code is back on
257 // the stable revision.
258 if (stable === undefined || stable === revisionId) return all;
259 if (canary.weight <= 0) return [{ revisionId: stable, weight: 100 }];
260 return [
261 { revisionId: stable, weight: 100 - canary.weight },
262 { revisionId, weight: canary.weight },
263 ];
264 };
265
266 const byRevision = (weights: readonly WebFunctionRevisionWeight[]) =>
267 [...weights].sort((a, b) => a.revisionId.localeCompare(b.revisionId));
268
269 /** Settings `UpdateWebFunctionEndpoint` changes in place. */
270 const desiredSettings = (
271 spec: WebFunctionEndpointSpec,
272 revisionWeights: WebFunctionRevisionWeight[],
273 ) => ({
274 description: spec.description ?? "",
275 authType: spec.authType,
276 autoDeploymentMode: "Disabled" as const,
277 revisionWeights,
278 // `{}` clears a previously set value.
279 scalingConfig:
280 spec.maxEnvironments === undefined ? {} : { maxEnvironments: spec.maxEnvironments },
281 throttleConfig: spec.rateLimit === undefined ? {} : { rateLimit: spec.rateLimit },
282 });
283
284 const settingsMatch = (
285 observed: LambdaWeb.GetWebFunctionEndpointResponse,
286 desired: ReturnType<typeof desiredSettings>,
287 ) =>
288 (observed.description ?? "") === desired.description &&
289 observed.authType === desired.authType &&
290 observed.autoDeploymentMode === desired.autoDeploymentMode &&
291 deepEqual(byRevision(servedRevisions(observed)), byRevision(desired.revisionWeights)) &&
292 observed.scalingConfig?.maxEnvironments === desired.scalingConfig.maxEnvironments &&
293 observed.throttleConfig?.rateLimit === desired.throttleConfig.rateLimit;
294
295 /** Another update to the same function or endpoint is in progress. */
296 const retryConflict = <A, E extends { _tag: string }, R>(self: Effect.Effect<A, E, R>) =>
297 self.pipe(
298 Effect.retry({
299 while: (e) => e._tag === "ConflictException",
300 schedule: Schedule.spaced("2 seconds"),
301 times: 15,
302 }),
303 );
304
305 const waitForSettled = (
306 functionName: string,
307 endpointName: string,
308 session: { note: (note: string) => Effect.Effect<void> },
309 ) =>
310 Effect.gen(function* () {
311 const endpoint = yield* getEndpoint(functionName, endpointName);
312 if (endpoint?.state === "Failed" || endpoint?.updateStatus === "Failed") {
313 return yield* new WebFunctionFailed({
314 functionName,
315 resource: `endpoint ${endpointName}`,
316 reason: endpoint.updateStatusReason ?? endpoint.stateReason,
317 });
318 }
319 if (endpoint?.state === "Active" && endpoint.updateStatus !== "InProgress") {
320 return endpoint;
321 }
322 return yield* new WebFunctionNotReady({
323 functionName,
324 resource: `endpoint ${endpointName}`,
325 state: endpoint?.updateStatus === "InProgress" ? "updating" : (endpoint?.state ?? "missing"),
326 });
327 }).pipe(
328 Effect.tapError((e) =>
329 e._tag === "WebFunctionNotReady" ? session.note(e.message) : Effect.void,
330 ),
331 Effect.retry({
332 while: (e) => e._tag === "WebFunctionNotReady",
333 schedule: Schedule.spaced("2 seconds"),
334 times: 90,
335 }),
336 );
337
338 /** Delete an endpoint and wait until it is gone. Idempotent. */
339 export const deleteEndpoint = (functionName: string, endpointName: string) =>
340 Effect.gen(function* () {
341 yield* LambdaWeb.deleteWebFunctionEndpoint({ functionName, endpointName }).pipe(
342 retryConflict,
343 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
344 );
345 yield* Effect.gen(function* () {
346 const endpoint = yield* getEndpoint(functionName, endpointName);
347 if (endpoint === undefined) return;
348 return yield* new WebFunctionNotReady({
349 functionName,
350 resource: `endpoint ${endpointName}`,
351 state: endpoint.state,
352 });
353 }).pipe(
354 Effect.retry({
355 while: (e) => e._tag === "WebFunctionNotReady",
356 schedule: Schedule.spaced("2 seconds"),
357 times: 45,
358 }),
359 );
360 });
361
362 /**
363 * Converge one endpoint on `spec`, routing traffic to `revisionId` (all of
364 * it, or `spec.canary.weight` percent with the rest on the stable
365 * revision): observe it, recreate it when its type or Regions disagree,
366 * create it when missing, update the in-place settings that differ, and
367 * wait until it settles. `published` is the revision the previous deploy
368 * published to this endpoint.
369 */
370 export const syncEndpoint = Effect.fn(function* ({
371 functionName,
372 spec,
373 revisionId,
374 published,
375 session,
376 }: {
377 functionName: string;
378 spec: WebFunctionEndpointSpec;
379 revisionId: string;
380 published?: string;
381 session: { note: (note: string) => Effect.Effect<void> };
382 }) {
383 const endpointType = endpointTypeOf(spec.regions);
384 // Lambda adds the home Region to a MultiRegion endpoint itself.
385 const { region: homeRegion } = yield* AWSEnvironment.current;
386 const remoteRegions = (regions: readonly string[] | undefined) =>
387 normalizeRegions(regions?.filter((r) => r !== homeRegion));
388
389 let endpoint = yield* getEndpoint(functionName, spec.endpointName);
390 if (
391 endpoint !== undefined &&
392 (endpoint.endpointType !== endpointType ||
393 (endpointType === "MultiRegion" &&
394 !deepEqual(remoteRegions(endpoint.regions), remoteRegions(spec.regions))))
395 ) {
396 yield* deleteEndpoint(functionName, spec.endpointName);
397 endpoint = undefined;
398 }
399
400 const settings = desiredSettings(
401 spec,
402 revisionWeightsFor({ observed: endpoint, revisionId, published, canary: spec.canary }),
403 );
404 if (endpoint === undefined) {
405 yield* LambdaWeb.createWebFunctionEndpoint({
406 functionName,
407 ...createEndpointConfig(spec),
408 revisionWeights: settings.revisionWeights,
409 }).pipe(retryConflict);
410 } else if (!settingsMatch(endpoint, settings)) {
411 yield* LambdaWeb.updateWebFunctionEndpoint({
412 functionName,
413 endpointName: spec.endpointName,
414 ...settings,
415 }).pipe(retryConflict);
416 }
417 return yield* waitForSettled(functionName, spec.endpointName, session);
418 });