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

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