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

main
ts 603 lines 20.8 KB
Raw
1 import * as compute from "@distilled.cloud/gcp/compute_v1";
2 import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { tagRecord } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import { GcpEnvironment } from "../Environment.ts";
13 import {
14 createInternalLabels,
15 hasAlchemyLabels,
16 stripInternalLabels,
17 toLabels,
18 } from "../Labels.ts";
19 import type { Providers } from "../Providers.ts";
20 import { waitRegionOperation } from "./operations.ts";
21
22 const DEFAULT_COOL_DOWN_SEC = 60;
23 const DEFAULT_MIN_REPLICAS = 0;
24 const DEFAULT_MODE = "ON";
25 const DEFAULT_CPU_TARGET = 0.6;
26 const MAX_NAME_LENGTH = 63;
27
28 export type RegionAutoscalerAutoscalingPolicy = {
29 /**
30 * Maximum number of instances the autoscaler may scale out to. Required.
31 */
32 maxNumReplicas: number;
33 /**
34 * Minimum number of instances the autoscaler may scale in to.
35 * @default 0
36 */
37 minNumReplicas?: number;
38 /**
39 * Initialization period in seconds before metrics are trusted.
40 * @default 60
41 */
42 coolDownPeriodSec?: number;
43 /**
44 * Stabilization period in seconds before scale-in.
45 */
46 stabilizationPeriodSec?: number;
47 /**
48 * Operating mode.
49 * @default "ON"
50 */
51 mode?: "OFF" | "ON" | "ONLY_SCALE_OUT" | "ONLY_UP" | (string & {});
52 /**
53 * CPU utilization signal. When no signal is set, GCP defaults to
54 * CPU `0.6`.
55 */
56 cpuUtilization?: compute.AutoscalingPolicyCpuUtilization;
57 /** Load-balancing utilization signal. */
58 loadBalancingUtilization?: compute.AutoscalingPolicyLoadBalancingUtilization;
59 /** Custom Cloud Monitoring metric signals. */
60 customMetricUtilizations?: compute.AutoscalingPolicyCustomMetricUtilization[];
61 /** Throttle abrupt scale-in. */
62 scaleInControl?: compute.AutoscalingPolicyScaleInControl;
63 /** Named scaling schedules (up to 128). */
64 scalingSchedules?: Record<string, compute.AutoscalingPolicyScalingSchedule | undefined>;
65 };
66
67 export type RegionAutoscalerProps = {
68 /**
69 * Autoscaler name (RFC1035, 1-63 characters). If omitted, a unique name
70 * is generated from the stack, stage, and logical id. Changing the name
71 * replaces the autoscaler.
72 */
73 autoscalerName?: string;
74 /**
75 * Region of the managed instance group (e.g. `us-central1`). Immutable —
76 * changing it replaces the autoscaler. `US-CENTRAL1` is accepted and
77 * normalized to `us-central1`.
78 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
79 */
80 region?: string;
81 /**
82 * URL or name of the regional managed instance group to scale
83 * (`projects/{project}/regions/{region}/instanceGroupManagers/{name}`).
84 */
85 target: string;
86 /**
87 * Optional description. Compute autoscalers have no labels field, so
88 * Alchemy ownership (`alchemy-stack` / `alchemy-stage` / `alchemy-id`)
89 * and user labels are stored in a `[alchemy …]` prefix for `list` / nuke.
90 */
91 description?: string;
92 /**
93 * User labels. Encoded into the description marker alongside Alchemy
94 * ownership labels (the API has no `labels` field).
95 */
96 labels?: Record<string, string>;
97 /**
98 * Autoscaling policy. `maxNumReplicas` is required; other fields take
99 * GCP defaults when omitted.
100 */
101 autoscalingPolicy: RegionAutoscalerAutoscalingPolicy;
102 };
103
104 export type RegionAutoscaler = Resource<
105 "GCP.Compute.RegionAutoscaler",
106 RegionAutoscalerProps,
107 {
108 /** Autoscaler name. */
109 autoscalerName: string;
110 /** Server-assigned numeric id. */
111 autoscalerId: string | undefined;
112 /** Project id. */
113 project: string;
114 /** Region short name (`us-central1`). */
115 region: string;
116 /** Target managed instance group URL. */
117 target: string;
118 /** User-facing description (ownership marker stripped). */
119 description: string | undefined;
120 /** User labels decoded from the description marker. */
121 labels: Record<string, string>;
122 /** Autoscaling policy currently applied. */
123 autoscalingPolicy: compute.AutoscalingPolicy | undefined;
124 /** Server-reported status (`PENDING`, `ACTIVE`, `ERROR`, `DELETING`). */
125 status: string | undefined;
126 /** Human-readable status details. */
127 statusDetails: ReadonlyArray<compute.AutoscalerStatusDetails>;
128 /** Recommended MIG size, if the autoscaler has produced one. */
129 recommendedSize: number | undefined;
130 /** Compute Engine self-link. */
131 selfLink: string | undefined;
132 /** RFC3339 creation timestamp. */
133 creationTimestamp: string | undefined;
134 },
135 never,
136 Providers
137 >;
138
139 /**
140 * A regional Compute Engine autoscaler for a managed instance group.
141 *
142 * Changing `autoscalerName` or `region` replaces the autoscaler. Policy,
143 * target, description, and labels update in place via
144 * `regionAutoscalers.patch`. Compute Engine has no labels on this
145 * resource, so Alchemy stamps ownership into the description (`[alchemy
146 * alchemy-stack=… alchemy-stage=… alchemy-id=…]`) so `list` /
147 * `pnpm nuke:gcp` can find them.
148 *
149 * ### Creating a Region Autoscaler
150 * **Example:** CPU policy with generated name
151 * ```typescript
152 * const scaler = yield* GCP.Compute.RegionAutoscaler("Web", {
153 * target: mig.selfLink,
154 * autoscalingPolicy: {
155 * minNumReplicas: 1,
156 * maxNumReplicas: 5,
157 * coolDownPeriodSec: 60,
158 * cpuUtilization: { utilizationTarget: 0.6 },
159 * },
160 * });
161 * ```
162 *
163 * **Example:** Named autoscaler, labels, and OFF mode
164 * ```typescript
165 * const scaler = yield* GCP.Compute.RegionAutoscaler("Web", {
166 * autoscalerName: "web-scaler",
167 * region: "us-central1",
168 * target:
169 * "projects/{project}/regions/us-central1/instanceGroupManagers/web",
170 * description: "scale the web MIG",
171 * labels: { env: "prod" },
172 * autoscalingPolicy: {
173 * minNumReplicas: 0,
174 * maxNumReplicas: 3,
175 * mode: "OFF",
176 * cpuUtilization: { utilizationTarget: 0.5 },
177 * },
178 * });
179 * ```
180 *
181 * ### Updating Policy
182 * **Example:** Raise the replica cap and CPU target
183 * ```typescript
184 * const scaler = yield* GCP.Compute.RegionAutoscaler("Web", {
185 * autoscalerName: "web-scaler",
186 * target: mig.selfLink,
187 * autoscalingPolicy: {
188 * minNumReplicas: 1,
189 * maxNumReplicas: 10,
190 * cpuUtilization: { utilizationTarget: 0.5 },
191 * },
192 * });
193 * ```
194 *
195 * @resource
196 * @category Compute
197 */
198 export const RegionAutoscaler = Resource<RegionAutoscaler>("GCP.Compute.RegionAutoscaler");
199
200 export class RegionAutoscalerNotResolved extends Data.TaggedError(
201 "GCP.Compute.RegionAutoscalerNotResolved",
202 )<{
203 autoscalerName: string;
204 region: string;
205 }> {}
206
207 export class RegionAutoscalerStillExists extends Data.TaggedError(
208 "GCP.Compute.RegionAutoscalerStillExists",
209 )<{
210 autoscalerName: string;
211 region: string;
212 }> {}
213
214 const lastSegment = (value: string | undefined): string => {
215 if (value === undefined || value.length === 0) return "";
216 const parts = value.split("/").filter((part) => part.length > 0);
217 return parts[parts.length - 1] ?? value;
218 };
219
220 const normalizeRegion = (region: string | undefined, defaultRegion: string) =>
221 lastSegment(region ?? defaultRegion).toLowerCase();
222
223 const rfc1035Name = (name: string) => {
224 let next = name
225 .toLowerCase()
226 .replace(/[^a-z0-9-]/g, "-")
227 .replace(/-+/g, "-")
228 .replace(/^-+|-+$/g, "");
229 if (!/^[a-z]/.test(next)) {
230 next = `a${next}`;
231 }
232 next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, "");
233 return next.length > 0 ? next : "autoscaler";
234 };
235
236 const toName = (id: string, name: string | undefined, existing?: string) =>
237 Effect.gen(function* () {
238 return rfc1035Name(
239 name ??
240 existing ??
241 (yield* createPhysicalName({
242 id,
243 maxLength: MAX_NAME_LENGTH,
244 lowercase: true,
245 })),
246 );
247 });
248
249 const toTargetUrl = (project: string, region: string, target: string) =>
250 target.includes("/")
251 ? target
252 : `projects/${project}/regions/${region}/instanceGroupManagers/${target}`;
253
254 const encodeDescription = (user: string | undefined, labels: Record<string, string>): string => {
255 const packed = Object.entries(labels)
256 .sort(([left], [right]) => left.localeCompare(right))
257 .map(([key, value]) => `${key}=${value}`)
258 .join(" ");
259 const marker = `[alchemy ${packed}]`;
260 const trimmed = user?.trim();
261 return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
262 };
263
264 const parseDescription = (
265 description: string | undefined,
266 ): { labels: Record<string, string>; user: string | undefined } => {
267 if (!description?.startsWith("[alchemy ")) {
268 return { labels: {}, user: description };
269 }
270 const end = description.indexOf("]");
271 if (end < 0) return { labels: {}, user: description };
272 const labels: Record<string, string> = {};
273 for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
274 const eq = part.indexOf("=");
275 if (eq > 0) {
276 labels[part.slice(0, eq)] = part.slice(eq + 1);
277 }
278 }
279 const rest = description
280 .slice(end + 1)
281 .replace(/^\n/, "")
282 .trim();
283 return {
284 labels,
285 user: rest.length > 0 ? rest : undefined,
286 };
287 };
288
289 const hasOwnershipMarker = (description: string | undefined) =>
290 Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));
291
292 const userLabels = (
293 labels: Record<string, string | undefined> | null | undefined,
294 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
295
296 const toAttrs = (autoscaler: compute.Autoscaler, project: string) => {
297 const decoded = parseDescription(autoscaler.description);
298 return {
299 autoscalerName: autoscaler.name ?? lastSegment(autoscaler.selfLink),
300 autoscalerId: autoscaler.id,
301 project,
302 region: lastSegment(autoscaler.region).toLowerCase(),
303 target: autoscaler.target ?? "",
304 description: decoded.user,
305 labels: userLabels(decoded.labels),
306 autoscalingPolicy: autoscaler.autoscalingPolicy,
307 status: autoscaler.status,
308 statusDetails: autoscaler.statusDetails ?? [],
309 recommendedSize: autoscaler.recommendedSize,
310 selfLink: autoscaler.selfLink,
311 creationTimestamp: autoscaler.creationTimestamp,
312 };
313 };
314
315 const hasSignal = (policy: RegionAutoscalerAutoscalingPolicy) =>
316 policy.cpuUtilization !== undefined ||
317 policy.loadBalancingUtilization !== undefined ||
318 (policy.customMetricUtilizations?.length ?? 0) > 0;
319
320 const desiredPolicy = (policy: RegionAutoscalerAutoscalingPolicy): compute.AutoscalingPolicy => ({
321 maxNumReplicas: policy.maxNumReplicas,
322 minNumReplicas: policy.minNumReplicas ?? DEFAULT_MIN_REPLICAS,
323 coolDownPeriodSec: policy.coolDownPeriodSec ?? DEFAULT_COOL_DOWN_SEC,
324 stabilizationPeriodSec: policy.stabilizationPeriodSec,
325 mode: policy.mode ?? DEFAULT_MODE,
326 cpuUtilization:
327 policy.cpuUtilization ??
328 (hasSignal(policy) ? undefined : { utilizationTarget: DEFAULT_CPU_TARGET }),
329 loadBalancingUtilization: policy.loadBalancingUtilization,
330 customMetricUtilizations: policy.customMetricUtilizations,
331 scaleInControl: policy.scaleInControl,
332 scalingSchedules: policy.scalingSchedules,
333 });
334
335 const sortedValue = (value: unknown): unknown => {
336 if (Array.isArray(value)) return value.map(sortedValue);
337 if (value !== null && typeof value === "object") {
338 return Object.fromEntries(
339 Object.entries(value as Record<string, unknown>)
340 .filter(([, entry]) => entry !== undefined)
341 .sort(([left], [right]) => left.localeCompare(right))
342 .map(([key, entry]) => [key, sortedValue(entry)]),
343 );
344 }
345 return value;
346 };
347
348 const canonCpu = (cpu: compute.AutoscalingPolicyCpuUtilization | undefined) => {
349 if (cpu === undefined) return undefined;
350 const predictive =
351 cpu.predictiveMethod === undefined || cpu.predictiveMethod === "NONE"
352 ? undefined
353 : cpu.predictiveMethod;
354 return {
355 utilizationTarget: cpu.utilizationTarget,
356 predictiveMethod: predictive,
357 };
358 };
359
360 const canonPolicy = (policy: compute.AutoscalingPolicy | undefined) => {
361 if (policy === undefined) return undefined;
362 return sortedValue({
363 maxNumReplicas: policy.maxNumReplicas,
364 minNumReplicas: policy.minNumReplicas ?? DEFAULT_MIN_REPLICAS,
365 coolDownPeriodSec: policy.coolDownPeriodSec ?? DEFAULT_COOL_DOWN_SEC,
366 stabilizationPeriodSec: policy.stabilizationPeriodSec,
367 mode: policy.mode ?? DEFAULT_MODE,
368 cpuUtilization: canonCpu(policy.cpuUtilization),
369 loadBalancingUtilization: policy.loadBalancingUtilization
370 ? { utilizationTarget: policy.loadBalancingUtilization.utilizationTarget }
371 : undefined,
372 customMetricUtilizations: (policy.customMetricUtilizations ?? []).map((metric) => ({
373 metric: metric.metric,
374 filter: metric.filter,
375 utilizationTarget: metric.utilizationTarget,
376 utilizationTargetType: metric.utilizationTargetType,
377 singleInstanceAssignment: metric.singleInstanceAssignment,
378 })),
379 scaleInControl: policy.scaleInControl
380 ? {
381 maxScaledInReplicas: policy.scaleInControl.maxScaledInReplicas
382 ? {
383 fixed: policy.scaleInControl.maxScaledInReplicas.fixed,
384 percent: policy.scaleInControl.maxScaledInReplicas.percent,
385 }
386 : undefined,
387 timeWindowSec: policy.scaleInControl.timeWindowSec,
388 }
389 : undefined,
390 scalingSchedules: policy.scalingSchedules,
391 });
392 };
393
394 const samePolicy = (
395 observed: compute.AutoscalingPolicy | undefined,
396 desired: compute.AutoscalingPolicy,
397 ) => JSON.stringify(canonPolicy(observed)) === JSON.stringify(canonPolicy(desired));
398
399 const getByName = (project: string, region: string, autoscaler: string) =>
400 compute
401 .getRegionAutoscalers({ project, region, autoscaler })
402 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
403
404 const waitPresent = (project: string, region: string, autoscalerName: string) =>
405 getByName(project, region, autoscalerName).pipe(
406 Effect.flatMap((autoscaler) =>
407 autoscaler === undefined
408 ? Effect.fail(new RegionAutoscalerNotResolved({ autoscalerName, region }))
409 : Effect.succeed(autoscaler),
410 ),
411 Effect.retry({
412 while: (error) => error._tag === "GCP.Compute.RegionAutoscalerNotResolved",
413 times: 8,
414 schedule: Schedule.exponential("250 millis"),
415 }),
416 Effect.catchTag("GCP.Compute.RegionAutoscalerNotResolved", () => Effect.undefined),
417 );
418
419 const waitGone = (project: string, region: string, autoscalerName: string) =>
420 getByName(project, region, autoscalerName).pipe(
421 Effect.flatMap((autoscaler) =>
422 autoscaler === undefined
423 ? Effect.void
424 : Effect.fail(new RegionAutoscalerStillExists({ autoscalerName, region })),
425 ),
426 Effect.retry({
427 while: (error) => error._tag === "GCP.Compute.RegionAutoscalerStillExists",
428 times: 8,
429 schedule: Schedule.spaced("1 second"),
430 }),
431 );
432
433 export const RegionAutoscalerProvider = () =>
434 Provider.succeed(RegionAutoscaler, {
435 stables: [
436 "autoscalerName",
437 "autoscalerId",
438 "project",
439 "region",
440 "selfLink",
441 "creationTimestamp",
442 ],
443
444 diff: Effect.fn(function* ({ news, olds, output }) {
445 if (!isResolved(news)) return undefined;
446 const env = yield* GcpEnvironment.current;
447 const previousName = olds?.autoscalerName ?? output?.autoscalerName;
448 const nextName = news.autoscalerName ?? previousName;
449 const previousRegion = normalizeRegion(olds?.region ?? output?.region, env.region);
450 const nextRegion = normalizeRegion(news.region ?? previousRegion, env.region);
451 const nameChanged =
452 previousName !== undefined && nextName !== undefined && previousName !== nextName;
453 const regionChanged = previousRegion !== nextRegion;
454 if (!nameChanged && !regionChanged) {
455 return undefined;
456 }
457 return {
458 action: "replace" as const,
459 // A MIG can only have one autoscaler; always delete the old row first.
460 deleteFirst: true,
461 };
462 }),
463
464 read: Effect.fn(function* ({ id, olds, output, previous }) {
465 const env = yield* GcpEnvironment.current;
466 const autoscalerName = yield* toName(id, olds?.autoscalerName, output?.autoscalerName);
467 const region = normalizeRegion(olds?.region ?? output?.region, env.region);
468 const existing = yield* getByName(env.project, region, autoscalerName);
469 if (existing === undefined) return undefined;
470 const attrs = toAttrs(existing, env.project);
471 const { labels } = parseDescription(existing.description);
472 return (yield* hasAlchemyLabels(id, labels))
473 ? attrs
474 : unownedUnlessPrevious(attrs, previous, "autoscalerName");
475 }),
476
477 list: () =>
478 Effect.gen(function* () {
479 const env = yield* GcpEnvironment.current;
480 const pages = yield* compute.aggregatedListAutoscalers
481 .pages({
482 project: env.project,
483 maxResults: 500,
484 returnPartialSuccess: true,
485 })
486 .pipe(Stream.runCollect);
487 return Array.from(pages).flatMap((page) =>
488 Object.values(page.items ?? {}).flatMap((scoped) =>
489 (scoped?.autoscalers ?? [])
490 .filter(
491 (autoscaler) =>
492 (autoscaler.region ?? "").length > 0 &&
493 hasOwnershipMarker(autoscaler.description),
494 )
495 .map((autoscaler) => toAttrs(autoscaler, env.project)),
496 ),
497 );
498 }),
499
500 reconcile: Effect.fn(function* ({ id, news, output }) {
501 const env = yield* GcpEnvironment.current;
502 const autoscalerName = yield* toName(id, news.autoscalerName, output?.autoscalerName);
503 const region = normalizeRegion(news.region ?? output?.region, env.region);
504 const target = toTargetUrl(env.project, region, news.target);
505 const desiredLabels = {
506 ...toLabels(news.labels),
507 ...(yield* createInternalLabels(id)),
508 };
509 const description = encodeDescription(news.description, desiredLabels);
510 const policy = desiredPolicy(news.autoscalingPolicy);
511
512 let current = yield* getByName(env.project, region, autoscalerName);
513
514 if (current === undefined) {
515 yield* compute
516 .insertRegionAutoscalers({
517 project: env.project,
518 region,
519 body: {
520 name: autoscalerName,
521 target,
522 description,
523 autoscalingPolicy: policy,
524 },
525 })
526 .pipe(
527 Effect.catchTag("Conflict", () => Effect.undefined),
528 Effect.flatMap((operation) =>
529 operation === undefined
530 ? Effect.void
531 : waitRegionOperation(env.project, region, operation, {
532 ignore: ["RESOURCE_ALREADY_EXISTS"],
533 }).pipe(Effect.asVoid),
534 ),
535 );
536 current = yield* waitPresent(env.project, region, autoscalerName);
537 }
538
539 if (current === undefined) {
540 return yield* new RegionAutoscalerNotResolved({
541 autoscalerName,
542 region,
543 });
544 }
545
546 const descriptionChanged = (current.description ?? "") !== description;
547 const policyChanged = !samePolicy(current.autoscalingPolicy, policy);
548 const targetChanged =
549 lastSegment(current.target) !== lastSegment(target) && (current.target ?? "") !== target;
550
551 if (descriptionChanged || policyChanged || targetChanged) {
552 yield* compute
553 .patchRegionAutoscalers({
554 project: env.project,
555 region,
556 autoscaler: autoscalerName,
557 body: {
558 name: autoscalerName,
559 target,
560 description,
561 autoscalingPolicy: policy,
562 },
563 })
564 .pipe(
565 Effect.flatMap((operation) => waitRegionOperation(env.project, region, operation)),
566 Effect.retry({
567 while: (error) => error._tag === "Conflict",
568 times: 5,
569 schedule: Schedule.exponential("250 millis"),
570 }),
571 );
572 current = (yield* getByName(env.project, region, autoscalerName)) ?? current;
573 }
574
575 return toAttrs(current, env.project);
576 }),
577
578 delete: Effect.fn(function* ({ output }) {
579 yield* compute
580 .deleteRegionAutoscalers({
581 project: output.project,
582 region: output.region,
583 autoscaler: output.autoscalerName,
584 })
585 .pipe(
586 Effect.catchTag("NotFound", () => Effect.undefined),
587 Effect.flatMap((operation) =>
588 operation === undefined
589 ? Effect.void
590 : waitRegionOperation(output.project, output.region, operation, {
591 ignore: ["RESOURCE_NOT_FOUND"],
592 }).pipe(Effect.asVoid),
593 ),
594 Effect.catchTag("NotFound", () => Effect.void),
595 Effect.retry({
596 while: (error) => error._tag === "Conflict",
597 times: 5,
598 schedule: Schedule.spaced("1 second"),
599 }),
600 );
601 yield* waitGone(output.project, output.region, output.autoscalerName);
602 }),
603 });