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

main
ts 513 lines 17.1 KB
Raw
1 import * as compute from "@distilled.cloud/gcp/compute_v1";
2 import { Unowned } 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 * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import { GcpEnvironment } from "../Environment.ts";
12 import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
13 import type { Providers } from "../Providers.ts";
14 import { waitZoneOperation } from "./operations.ts";
15
16 export type NamedPort = {
17 /** RFC1035 name for this port mapping (e.g. `"http"`). */
18 name: string;
19 /** TCP port number (`1`–`65535`). */
20 port: number;
21 };
22
23 export type InstanceGroupProps = {
24 /**
25 * Name of the instance group. Must be 1–63 characters and comply with
26 * RFC1035. If omitted, a unique name is generated from the stack, stage,
27 * and logical id. Changing this replaces the group.
28 */
29 instanceGroupName?: string;
30 /**
31 * Zone of the instance group (e.g. `"us-central1-a"`). Immutable —
32 * changing it replaces the group.
33 * @default "us-central1-a"
34 */
35 zone?: string;
36 /**
37 * Optional description. Unmanaged instance groups have no labels API, so
38 * Alchemy stamps ownership (`alchemy-stack` / `alchemy-stage` /
39 * `alchemy-id`) into this field for `list` / nuke. Changing the
40 * user-facing description replaces the group.
41 */
42 description?: string;
43 /**
44 * VPC network URL or name (`default`, `global/networks/default`, or
45 * `projects/{project}/global/networks/{name}`). Immutable — changing it
46 * replaces the group.
47 */
48 network?: string;
49 /**
50 * Named ports applied to every instance in the group.
51 */
52 namedPorts?: NamedPort[];
53 /**
54 * Member instance URLs or names. When omitted, membership is left as-is.
55 * When set (including `[]`), observed members are added/removed to match.
56 */
57 instances?: string[];
58 };
59
60 export type InstanceGroup = Resource<
61 "GCP.Compute.InstanceGroup",
62 InstanceGroupProps,
63 {
64 /** Instance group name. */
65 instanceGroupName: string;
66 /** Zone (short name, e.g. `"us-central1-a"`). */
67 zone: string;
68 /** Project id. */
69 project: string;
70 /** User-facing description (ownership marker stripped). */
71 description: string | undefined;
72 /** Network URL, if set. */
73 network: string | undefined;
74 /** Subnetwork URL, if set. */
75 subnetwork: string | undefined;
76 /** Named ports currently configured on the group. */
77 namedPorts: NamedPort[];
78 /** Number of member instances. */
79 size: number;
80 /** Server-generated resource URL. */
81 selfLink: string | undefined;
82 /** Server-generated numeric id. */
83 id: string | undefined;
84 /** RFC3339 creation timestamp. */
85 creationTimestamp: string | undefined;
86 },
87 never,
88 Providers
89 >;
90
91 /**
92 * A zonal unmanaged Compute Engine instance group.
93 *
94 * Unmanaged groups hold an explicit list of VMs and optional named ports
95 * for load balancing. They have no labels API — Alchemy records ownership
96 * in the description so `list` / `pnpm nuke:gcp` can find them.
97 *
98 * ### Creating an Instance Group
99 * **Example:** Generated name
100 * ```typescript
101 * const group = yield* GCP.Compute.InstanceGroup("web", {
102 * namedPorts: [{ name: "http", port: 80 }],
103 * });
104 * ```
105 *
106 * **Example:** Explicit name, zone, and named ports
107 * ```typescript
108 * const group = yield* GCP.Compute.InstanceGroup("web", {
109 * instanceGroupName: "web-backends",
110 * zone: "us-central1-a",
111 * description: "HTTP backends",
112 * namedPorts: [
113 * { name: "http", port: 80 },
114 * { name: "https", port: 443 },
115 * ],
116 * });
117 * ```
118 *
119 * @resource
120 * @category Compute
121 */
122 export const InstanceGroup = Resource<InstanceGroup>("GCP.Compute.InstanceGroup");
123
124 export class InstanceGroupNotResolved extends Data.TaggedError(
125 "GCP.Compute.InstanceGroupNotResolved",
126 )<{
127 instanceGroupName: string;
128 zone: string;
129 }> {}
130
131 export class InstanceGroupStillExists extends Data.TaggedError(
132 "GCP.Compute.InstanceGroupStillExists",
133 )<{
134 instanceGroupName: string;
135 zone: string;
136 }> {}
137
138 const DEFAULT_ZONE = "us-central1-a";
139
140 const lastSegment = (value: string) => {
141 const parts = value.split("/").filter((part) => part.length > 0);
142 return parts[parts.length - 1] ?? value;
143 };
144
145 const rfc1035Name = (name: string) => {
146 let next = name
147 .toLowerCase()
148 .replace(/[^a-z0-9-]/g, "-")
149 .replace(/-+/g, "-")
150 .replace(/^-+|-+$/g, "");
151 if (!/^[a-z]/.test(next)) {
152 next = `g${next}`;
153 }
154 next = next.slice(0, 63).replace(/-+$/g, "");
155 return next.length > 0 ? next : "group";
156 };
157
158 const toName = (id: string, name: string | undefined, existing?: string) =>
159 Effect.gen(function* () {
160 return rfc1035Name(
161 name ??
162 existing ??
163 (yield* createPhysicalName({
164 id,
165 maxLength: 63,
166 lowercase: true,
167 })),
168 );
169 });
170
171 const encodeDescription = (user: string | undefined, labels: Record<string, string>) => {
172 const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
173 const trimmed = user?.trim();
174 return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
175 };
176
177 const parseDescription = (description: string | undefined) => {
178 if (!description?.startsWith("[alchemy ")) {
179 return { user: description, labels: {} as Record<string, string> };
180 }
181 const end = description.indexOf("]");
182 if (end < 0) {
183 return { user: description, labels: {} as Record<string, string> };
184 }
185 const labels: Record<string, string> = {};
186 for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
187 const eq = part.indexOf("=");
188 if (eq > 0) {
189 labels[part.slice(0, eq)] = part.slice(eq + 1);
190 }
191 }
192 const rest = description
193 .slice(end + 1)
194 .replace(/^\n/, "")
195 .trim();
196 return {
197 user: rest.length > 0 ? rest : undefined,
198 labels,
199 };
200 };
201
202 const hasOwnershipMarker = (description: string | undefined) =>
203 Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));
204
205 const toNetworkUrl = (project: string, network: string | undefined) => {
206 if (network === undefined || network.length === 0) return undefined;
207 if (network.includes("/")) return network;
208 return `projects/${project}/global/networks/${network}`;
209 };
210
211 const toInstanceUrl = (project: string, zone: string, instance: string) =>
212 instance.includes("/") ? instance : `projects/${project}/zones/${zone}/instances/${instance}`;
213
214 const canonPorts = (ports: readonly NamedPort[] | undefined): NamedPort[] =>
215 [...(ports ?? [])]
216 .map((port) => ({ name: port.name, port: port.port }))
217 .sort((a, b) => a.name.localeCompare(b.name) || a.port - b.port);
218
219 const samePorts = (
220 left: readonly NamedPort[] | undefined,
221 right: readonly NamedPort[] | undefined,
222 ) => JSON.stringify(canonPorts(left)) === JSON.stringify(canonPorts(right));
223
224 const fromApiPorts = (ports: readonly compute.NamedPort[] | undefined): NamedPort[] =>
225 canonPorts(
226 (ports ?? [])
227 .filter(
228 (port): port is { name: string; port: number } =>
229 typeof port.name === "string" && typeof port.port === "number",
230 )
231 .map((port) => ({ name: port.name, port: port.port })),
232 );
233
234 const toAttrs = (group: compute.InstanceGroup, project: string) => {
235 const { user } = parseDescription(group.description);
236 return {
237 instanceGroupName: group.name ?? lastSegment(group.selfLink ?? ""),
238 zone: lastSegment(group.zone ?? DEFAULT_ZONE),
239 project,
240 description: user,
241 network: group.network,
242 subnetwork: group.subnetwork,
243 namedPorts: fromApiPorts(group.namedPorts),
244 size: group.size ?? 0,
245 selfLink: group.selfLink,
246 id: group.id,
247 creationTimestamp: group.creationTimestamp,
248 };
249 };
250
251 const getByName = (project: string, zone: string, instanceGroup: string) =>
252 compute
253 .getInstanceGroups({ project, zone, instanceGroup })
254 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
255
256 const listMembers = (project: string, zone: string, instanceGroup: string) =>
257 compute.listInstancesInstanceGroups
258 .items({
259 project,
260 zone,
261 instanceGroup,
262 body: { instanceState: "ALL" },
263 })
264 .pipe(
265 Stream.runCollect,
266 Effect.map((chunk) =>
267 Array.from(chunk)
268 .map((item) => item.instance)
269 .filter((url): url is string => typeof url === "string"),
270 ),
271 Effect.catchTag("NotFound", () => Effect.succeed([] as string[])),
272 );
273
274 const waitGone = (project: string, zone: string, instanceGroupName: string) =>
275 getByName(project, zone, instanceGroupName).pipe(
276 Effect.flatMap((group) =>
277 group === undefined
278 ? Effect.void
279 : Effect.fail(new InstanceGroupStillExists({ instanceGroupName, zone })),
280 ),
281 Effect.retry({
282 while: (error) => error._tag === "GCP.Compute.InstanceGroupStillExists",
283 times: 8,
284 schedule: Schedule.spaced("1 second"),
285 }),
286 );
287
288 const runOp = <E, R>(
289 project: string,
290 zone: string,
291 start: Effect.Effect<compute.Operation, E, R>,
292 ) =>
293 start.pipe(
294 Effect.flatMap((operation) =>
295 waitZoneOperation(project, zone, operation, {
296 ignore: ["RESOURCE_ALREADY_EXISTS"],
297 }),
298 ),
299 );
300
301 export const InstanceGroupProvider = () =>
302 Provider.succeed(InstanceGroup, {
303 stables: ["instanceGroupName", "zone", "project", "id", "selfLink", "creationTimestamp"],
304
305 diff: Effect.fn(function* ({ news, olds, output }) {
306 if (!isResolved(news)) return undefined;
307 const previousName = olds?.instanceGroupName ?? output?.instanceGroupName;
308 const nextName = news.instanceGroupName ?? previousName;
309 const previousZone = olds?.zone ?? output?.zone;
310 const nextZone = news.zone ?? DEFAULT_ZONE;
311 const previousNetwork = olds?.network ?? output?.network;
312 const nextNetwork = news.network;
313 const nameChanged =
314 previousName !== undefined && nextName !== undefined && previousName !== nextName;
315 const zoneChanged =
316 previousZone !== undefined && lastSegment(previousZone) !== lastSegment(nextZone);
317 const networkChanged =
318 nextNetwork !== undefined &&
319 previousNetwork !== undefined &&
320 lastSegment(previousNetwork) !== lastSegment(nextNetwork);
321 const descriptionChanged =
322 olds !== undefined && (olds.description ?? "") !== (news.description ?? "");
323 if (!nameChanged && !zoneChanged && !networkChanged && !descriptionChanged) {
324 return undefined;
325 }
326 const sameIdentity =
327 previousName === nextName && lastSegment(previousZone ?? "") === lastSegment(nextZone);
328 return {
329 action: "replace" as const,
330 deleteFirst: sameIdentity,
331 };
332 }),
333
334 read: Effect.fn(function* ({ id, olds, output }) {
335 const env = yield* GcpEnvironment.current;
336 const instanceGroupName = yield* toName(
337 id,
338 olds?.instanceGroupName,
339 output?.instanceGroupName,
340 );
341 const zone = lastSegment(olds?.zone ?? output?.zone ?? DEFAULT_ZONE);
342 const existing = yield* getByName(env.project, zone, instanceGroupName);
343 if (existing === undefined) return undefined;
344 const attrs = toAttrs(existing, env.project);
345 const { labels } = parseDescription(existing.description);
346 return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
347 }),
348
349 list: () =>
350 Effect.gen(function* () {
351 const env = yield* GcpEnvironment.current;
352 const pages = yield* compute.aggregatedListInstanceGroups
353 .pages({
354 project: env.project,
355 maxResults: 500,
356 returnPartialSuccess: true,
357 })
358 .pipe(Stream.runCollect);
359 return Array.from(pages).flatMap((page) =>
360 Object.values(page.items ?? {}).flatMap((scoped) =>
361 (scoped?.instanceGroups ?? [])
362 .filter((group) => hasOwnershipMarker(group.description))
363 .map((group) => toAttrs(group, env.project)),
364 ),
365 );
366 }),
367
368 reconcile: Effect.fn(function* ({ id, news, output }) {
369 const env = yield* GcpEnvironment.current;
370 const instanceGroupName = yield* toName(
371 id,
372 news.instanceGroupName,
373 output?.instanceGroupName,
374 );
375 const zone = lastSegment(news.zone ?? output?.zone ?? DEFAULT_ZONE);
376 const namedPorts = canonPorts(news.namedPorts);
377 const network = toNetworkUrl(env.project, news.network);
378 const desiredLabels = yield* createInternalLabels(id);
379 const description = encodeDescription(news.description, desiredLabels);
380
381 let current = yield* getByName(env.project, zone, instanceGroupName);
382
383 if (current === undefined) {
384 yield* compute
385 .insertInstanceGroups({
386 project: env.project,
387 zone,
388 body: {
389 name: instanceGroupName,
390 description,
391 namedPorts: namedPorts.length > 0 ? namedPorts : undefined,
392 network,
393 },
394 })
395 .pipe(
396 Effect.catchTag("Conflict", () => Effect.undefined),
397 Effect.flatMap((operation) =>
398 operation === undefined
399 ? Effect.void
400 : waitZoneOperation(env.project, zone, operation, {
401 ignore: ["RESOURCE_ALREADY_EXISTS"],
402 }).pipe(Effect.asVoid),
403 ),
404 );
405 current = yield* getByName(env.project, zone, instanceGroupName).pipe(
406 Effect.flatMap((group) =>
407 group === undefined
408 ? Effect.fail(new InstanceGroupNotResolved({ instanceGroupName, zone }))
409 : Effect.succeed(group),
410 ),
411 Effect.retry({
412 while: (error) => error._tag === "GCP.Compute.InstanceGroupNotResolved",
413 times: 8,
414 schedule: Schedule.exponential("250 millis"),
415 }),
416 Effect.catchTag("GCP.Compute.InstanceGroupNotResolved", () => Effect.undefined),
417 );
418 }
419
420 if (current === undefined) {
421 return yield* new InstanceGroupNotResolved({
422 instanceGroupName,
423 zone,
424 });
425 }
426
427 if (!samePorts(fromApiPorts(current.namedPorts), namedPorts)) {
428 yield* runOp(
429 env.project,
430 zone,
431 compute.setNamedPortsInstanceGroups({
432 project: env.project,
433 zone,
434 instanceGroup: instanceGroupName,
435 body: {
436 namedPorts,
437 fingerprint: current.fingerprint,
438 },
439 }),
440 ).pipe(
441 Effect.retry({
442 while: (error) => error._tag === "Conflict",
443 times: 5,
444 schedule: Schedule.exponential("250 millis"),
445 }),
446 );
447 current = (yield* getByName(env.project, zone, instanceGroupName)) ?? current;
448 }
449
450 if (news.instances !== undefined) {
451 const observed = yield* listMembers(env.project, zone, instanceGroupName);
452 const desired = news.instances.map((instance) =>
453 toInstanceUrl(env.project, zone, instance),
454 );
455 const observedKeys = new Set(observed.map(lastSegment));
456 const desiredKeys = new Set(desired.map(lastSegment));
457 const toAdd = desired.filter((instance) => !observedKeys.has(lastSegment(instance)));
458 const toRemove = observed.filter((instance) => !desiredKeys.has(lastSegment(instance)));
459 if (toAdd.length > 0) {
460 yield* runOp(
461 env.project,
462 zone,
463 compute.addInstancesInstanceGroups({
464 project: env.project,
465 zone,
466 instanceGroup: instanceGroupName,
467 body: {
468 instances: toAdd.map((instance) => ({ instance })),
469 },
470 }),
471 );
472 }
473 if (toRemove.length > 0) {
474 yield* runOp(
475 env.project,
476 zone,
477 compute.removeInstancesInstanceGroups({
478 project: env.project,
479 zone,
480 instanceGroup: instanceGroupName,
481 body: {
482 instances: toRemove.map((instance) => ({ instance })),
483 },
484 }),
485 );
486 }
487 current = (yield* getByName(env.project, zone, instanceGroupName)) ?? current;
488 }
489
490 return toAttrs(current, env.project);
491 }),
492
493 delete: Effect.fn(function* ({ output }) {
494 yield* compute
495 .deleteInstanceGroups({
496 project: output.project,
497 zone: output.zone,
498 instanceGroup: output.instanceGroupName,
499 })
500 .pipe(
501 Effect.catchTag("NotFound", () => Effect.undefined),
502 Effect.flatMap((operation) =>
503 operation === undefined
504 ? Effect.void
505 : waitZoneOperation(output.project, output.zone, operation, {
506 ignore: ["RESOURCE_NOT_FOUND"],
507 }).pipe(Effect.asVoid),
508 ),
509 Effect.catchTag("NotFound", () => Effect.void),
510 );
511 yield* waitGone(output.project, output.zone, output.instanceGroupName);
512 }),
513 });