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

main
ts 634 lines 21.2 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 NetworkEndpointType =
17 | "GCE_VM_IP"
18 | "GCE_VM_IP_PORT"
19 | "GCE_VM_IP_PORTMAP"
20 | "INTERNET_FQDN_PORT"
21 | "INTERNET_IP_PORT"
22 | "NON_GCP_PRIVATE_IP_PORT"
23 | "PRIVATE_SERVICE_CONNECT"
24 | "SERVERLESS";
25
26 export type NetworkEndpointSpec = {
27 /** VM instance name or URL. Required for `GCE_VM_IP` / `GCE_VM_IP_PORT`. */
28 instance?: string;
29 /** IPv4 address of the endpoint. */
30 ipAddress?: string;
31 /** IPv6 address of the endpoint. */
32 ipv6Address?: string;
33 /** Port. Omitted endpoints use the group's `defaultPort`. */
34 port?: number;
35 /** FQDN. Only valid for FQDN internet endpoints. */
36 fqdn?: string;
37 /** PSC consumer destination port (`GCE_VM_IP_PORTMAP` only). */
38 clientDestinationPort?: number;
39 };
40
41 export type NetworkEndpointGroupProps = {
42 /**
43 * Name of the network endpoint group. Must be 1–63 characters and comply
44 * with RFC1035. If omitted, a unique name is generated from the stack,
45 * stage, and logical id. Changing this replaces the group.
46 */
47 networkEndpointGroupName?: string;
48 /**
49 * Zone of the group (e.g. `"us-central1-a"`). Immutable — changing it
50 * replaces the group. This resource maps to the zonal
51 * `networkEndpointGroups` collection (regional/global NEGs are separate).
52 * @default "us-central1-a"
53 */
54 zone?: string;
55 /**
56 * Optional description. Zonal NEGs have no labels API, so Alchemy stamps
57 * ownership (`alchemy-stack` / `alchemy-stage` / `alchemy-id`) into this
58 * field for `list` / nuke. Changing the user-facing description replaces
59 * the group.
60 */
61 description?: string;
62 /**
63 * VPC network URL or name (`default`, `global/networks/default`, or
64 * `projects/{project}/global/networks/{name}`). Immutable — changing it
65 * replaces the group.
66 * @default "default"
67 */
68 network?: string;
69 /**
70 * Subnetwork URL or name. Immutable — changing it replaces the group.
71 * Optional for auto-mode networks such as `default`.
72 */
73 subnetwork?: string;
74 /**
75 * Type of endpoints in this group. Immutable — changing it replaces the
76 * group.
77 * @default "GCE_VM_IP_PORT"
78 */
79 networkEndpointType?: NetworkEndpointType;
80 /**
81 * Default port used when an endpoint omits `port`. Must not be set for
82 * `GCE_VM_IP`. Immutable — changing it replaces the group.
83 */
84 defaultPort?: number;
85 /**
86 * Member endpoints. When omitted, membership is left as-is. When set
87 * (including `[]`), observed endpoints are attached/detached to match.
88 */
89 networkEndpoints?: NetworkEndpointSpec[];
90 };
91
92 export type NetworkEndpointGroup = Resource<
93 "GCP.Compute.NetworkEndpointGroup",
94 NetworkEndpointGroupProps,
95 {
96 /** Network endpoint group name. */
97 networkEndpointGroupName: string;
98 /** Zone (short name, e.g. `"us-central1-a"`). */
99 zone: string;
100 /** Project id. */
101 project: string;
102 /** User-facing description (ownership marker stripped). */
103 description: string | undefined;
104 /** Network URL, if set. */
105 network: string | undefined;
106 /** Subnetwork URL, if set. */
107 subnetwork: string | undefined;
108 /** Endpoint type. */
109 networkEndpointType: NetworkEndpointType;
110 /** Default port, if set. */
111 defaultPort: number | undefined;
112 /** Number of member endpoints. */
113 size: number;
114 /** Server-generated resource URL. */
115 selfLink: string | undefined;
116 /** Server-generated numeric id. */
117 id: string | undefined;
118 /** RFC3339 creation timestamp. */
119 creationTimestamp: string | undefined;
120 /** Resource kind. */
121 kind: string | undefined;
122 },
123 never,
124 Providers
125 >;
126
127 /**
128 * A zonal Compute Engine network endpoint group (NEG).
129 *
130 * Zonal NEGs hold VM IP/port endpoints (or hybrid `NON_GCP_PRIVATE_IP_PORT`
131 * endpoints) for load balancing. They have no labels API — Alchemy records
132 * ownership in the description so `list` / `pnpm nuke:gcp` can find them.
133 * Serverless, PSC, and internet NEGs use the regional/global collections
134 * and are not this resource.
135 *
136 * ### Creating a Network Endpoint Group
137 * **Example:** Generated name
138 * ```typescript
139 * const neg = yield* GCP.Compute.NetworkEndpointGroup("web", {
140 * defaultPort: 80,
141 * });
142 * ```
143 *
144 * **Example:** Explicit name, zone, and default port
145 * ```typescript
146 * const neg = yield* GCP.Compute.NetworkEndpointGroup("web", {
147 * networkEndpointGroupName: "web-neg",
148 * zone: "us-central1-a",
149 * network: "default",
150 * defaultPort: 80,
151 * description: "HTTP backends",
152 * });
153 * ```
154 *
155 * ### Endpoints
156 * **Example:** Attach VM endpoints
157 * ```typescript
158 * const neg = yield* GCP.Compute.NetworkEndpointGroup("web", {
159 * zone: "us-central1-a",
160 * defaultPort: 80,
161 * networkEndpoints: [
162 * { instance: vm.instanceName, port: 80 },
163 * ],
164 * });
165 * ```
166 *
167 * @resource
168 * @category Compute
169 */
170 export const NetworkEndpointGroup = Resource<NetworkEndpointGroup>(
171 "GCP.Compute.NetworkEndpointGroup",
172 );
173
174 export class NetworkEndpointGroupNotResolved extends Data.TaggedError(
175 "GCP.Compute.NetworkEndpointGroupNotResolved",
176 )<{
177 networkEndpointGroupName: string;
178 zone: string;
179 }> {}
180
181 export class NetworkEndpointGroupStillExists extends Data.TaggedError(
182 "GCP.Compute.NetworkEndpointGroupStillExists",
183 )<{
184 networkEndpointGroupName: string;
185 zone: string;
186 }> {}
187
188 const DEFAULT_ZONE = "us-central1-a";
189 const DEFAULT_NETWORK = "default";
190 const DEFAULT_TYPE: NetworkEndpointType = "GCE_VM_IP_PORT";
191
192 const lastSegment = (value: string) => {
193 const parts = value.split("/").filter((part) => part.length > 0);
194 return parts[parts.length - 1] ?? value;
195 };
196
197 const rfc1035Name = (name: string) => {
198 let next = name
199 .toLowerCase()
200 .replace(/[^a-z0-9-]/g, "-")
201 .replace(/-+/g, "-")
202 .replace(/^-+|-+$/g, "");
203 if (!/^[a-z]/.test(next)) {
204 next = `n${next}`;
205 }
206 next = next.slice(0, 63).replace(/-+$/g, "");
207 return next.length > 0 ? next : "neg";
208 };
209
210 const toName = (id: string, name: string | undefined, existing?: string) =>
211 Effect.gen(function* () {
212 return rfc1035Name(
213 name ??
214 existing ??
215 (yield* createPhysicalName({
216 id,
217 maxLength: 63,
218 lowercase: true,
219 })),
220 );
221 });
222
223 const encodeDescription = (user: string | undefined, labels: Record<string, string>) => {
224 const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
225 const trimmed = user?.trim();
226 return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
227 };
228
229 const parseDescription = (description: string | undefined) => {
230 if (!description?.startsWith("[alchemy ")) {
231 return { user: description, labels: {} as Record<string, string> };
232 }
233 const end = description.indexOf("]");
234 if (end < 0) {
235 return { user: description, labels: {} as Record<string, string> };
236 }
237 const labels: Record<string, string> = {};
238 for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
239 const eq = part.indexOf("=");
240 if (eq > 0) {
241 labels[part.slice(0, eq)] = part.slice(eq + 1);
242 }
243 }
244 const rest = description
245 .slice(end + 1)
246 .replace(/^\n/, "")
247 .trim();
248 return {
249 user: rest.length > 0 ? rest : undefined,
250 labels,
251 };
252 };
253
254 const hasOwnershipMarker = (description: string | undefined) =>
255 Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));
256
257 const zoneToRegion = (zone: string) => {
258 const idx = zone.lastIndexOf("-");
259 return idx > 0 ? zone.slice(0, idx) : zone;
260 };
261
262 const toNetworkUrl = (project: string, network: string | undefined) => {
263 if (network === undefined || network.length === 0) {
264 return `projects/${project}/global/networks/${DEFAULT_NETWORK}`;
265 }
266 if (network.includes("/")) return network;
267 return `projects/${project}/global/networks/${network}`;
268 };
269
270 const toSubnetworkUrl = (project: string, zone: string, subnetwork: string | undefined) => {
271 if (subnetwork === undefined || subnetwork.length === 0) return undefined;
272 if (subnetwork.includes("/")) return subnetwork;
273 return `projects/${project}/regions/${zoneToRegion(zone)}/subnetworks/${subnetwork}`;
274 };
275
276 const toInstanceUrl = (project: string, zone: string, instance: string) =>
277 instance.includes("/") ? instance : `projects/${project}/zones/${zone}/instances/${instance}`;
278
279 const asType = (value: string | undefined): NetworkEndpointType => {
280 switch (value) {
281 case "GCE_VM_IP":
282 case "GCE_VM_IP_PORT":
283 case "GCE_VM_IP_PORTMAP":
284 case "INTERNET_FQDN_PORT":
285 case "INTERNET_IP_PORT":
286 case "NON_GCP_PRIVATE_IP_PORT":
287 case "PRIVATE_SERVICE_CONNECT":
288 case "SERVERLESS":
289 return value;
290 default:
291 return DEFAULT_TYPE;
292 }
293 };
294
295 const toAttrs = (
296 group: compute.NetworkEndpointGroup,
297 project: string,
298 ): NetworkEndpointGroup["Attributes"] => {
299 const { user } = parseDescription(group.description);
300 return {
301 networkEndpointGroupName: group.name ?? lastSegment(group.selfLink ?? ""),
302 zone: lastSegment(group.zone ?? DEFAULT_ZONE),
303 project,
304 description: user,
305 network: group.network,
306 subnetwork: group.subnetwork,
307 networkEndpointType: asType(group.networkEndpointType),
308 defaultPort: group.defaultPort,
309 size: group.size ?? 0,
310 selfLink: group.selfLink,
311 id: group.id,
312 creationTimestamp: group.creationTimestamp,
313 kind: group.kind,
314 };
315 };
316
317 const getByName = (project: string, zone: string, networkEndpointGroup: string) =>
318 compute
319 .getNetworkEndpointGroups({ project, zone, networkEndpointGroup })
320 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
321
322 const toApiEndpoint = (
323 project: string,
324 zone: string,
325 endpoint: NetworkEndpointSpec,
326 ): compute.NetworkEndpoint => ({
327 instance:
328 endpoint.instance !== undefined ? toInstanceUrl(project, zone, endpoint.instance) : undefined,
329 ipAddress: endpoint.ipAddress,
330 ipv6Address: endpoint.ipv6Address,
331 port: endpoint.port,
332 fqdn: endpoint.fqdn,
333 clientDestinationPort: endpoint.clientDestinationPort,
334 });
335
336 const endpointKey = (endpoint: {
337 instance?: string;
338 ipAddress?: string;
339 ipv6Address?: string;
340 port?: number;
341 fqdn?: string;
342 clientDestinationPort?: number;
343 }) =>
344 [
345 endpoint.instance ? lastSegment(endpoint.instance) : "",
346 endpoint.ipAddress ?? "",
347 endpoint.ipv6Address ?? "",
348 endpoint.port ?? "",
349 endpoint.fqdn ?? "",
350 endpoint.clientDestinationPort ?? "",
351 ].join("|");
352
353 const listEndpoints = (project: string, zone: string, networkEndpointGroup: string) =>
354 compute.listNetworkEndpointsNetworkEndpointGroups
355 .items({
356 project,
357 zone,
358 networkEndpointGroup,
359 body: { healthStatus: "SKIP" },
360 })
361 .pipe(
362 Stream.runCollect,
363 Effect.map((chunk) =>
364 Array.from(chunk)
365 .map((item) => item.networkEndpoint)
366 .filter((endpoint): endpoint is compute.NetworkEndpoint => endpoint !== undefined),
367 ),
368 Effect.catchTag("NotFound", () => Effect.succeed([] as compute.NetworkEndpoint[])),
369 );
370
371 const waitGone = (project: string, zone: string, networkEndpointGroupName: string) =>
372 getByName(project, zone, networkEndpointGroupName).pipe(
373 Effect.flatMap((group) =>
374 group === undefined
375 ? Effect.void
376 : Effect.fail(
377 new NetworkEndpointGroupStillExists({
378 networkEndpointGroupName,
379 zone,
380 }),
381 ),
382 ),
383 Effect.retry({
384 while: (error) => error._tag === "GCP.Compute.NetworkEndpointGroupStillExists",
385 times: 8,
386 schedule: Schedule.spaced("1 second"),
387 }),
388 );
389
390 const runOp = <E, R>(
391 project: string,
392 zone: string,
393 start: Effect.Effect<compute.Operation, E, R>,
394 ) =>
395 start.pipe(
396 Effect.flatMap((operation) =>
397 waitZoneOperation(project, zone, operation, {
398 ignore: ["RESOURCE_ALREADY_EXISTS"],
399 }),
400 ),
401 );
402
403 export const NetworkEndpointGroupProvider = () =>
404 Provider.succeed(NetworkEndpointGroup, {
405 stables: [
406 "networkEndpointGroupName",
407 "zone",
408 "project",
409 "networkEndpointType",
410 "id",
411 "selfLink",
412 "creationTimestamp",
413 ],
414
415 diff: Effect.fn(function* ({ news, olds, output }) {
416 if (!isResolved(news)) return undefined;
417 const previousName = olds?.networkEndpointGroupName ?? output?.networkEndpointGroupName;
418 const nextName = news.networkEndpointGroupName ?? previousName;
419 const previousZone = olds?.zone ?? output?.zone;
420 const nextZone = news.zone ?? DEFAULT_ZONE;
421 const previousNetwork = olds?.network ?? output?.network;
422 const nextNetwork = news.network;
423 const previousSubnetwork = olds?.subnetwork ?? output?.subnetwork;
424 const nextSubnetwork = news.subnetwork;
425 const previousType = olds?.networkEndpointType ?? output?.networkEndpointType;
426 const nextType = news.networkEndpointType ?? previousType ?? DEFAULT_TYPE;
427 const previousPort = olds?.defaultPort ?? output?.defaultPort;
428 const nextPort = news.defaultPort;
429 const nameChanged =
430 previousName !== undefined && nextName !== undefined && previousName !== nextName;
431 const zoneChanged =
432 previousZone !== undefined && lastSegment(previousZone) !== lastSegment(nextZone);
433 const networkChanged =
434 nextNetwork !== undefined &&
435 previousNetwork !== undefined &&
436 lastSegment(previousNetwork) !== lastSegment(nextNetwork);
437 const subnetworkChanged =
438 nextSubnetwork !== undefined &&
439 previousSubnetwork !== undefined &&
440 lastSegment(previousSubnetwork) !== lastSegment(nextSubnetwork);
441 const typeChanged = previousType !== undefined && previousType !== nextType;
442 const portChanged =
443 nextPort !== undefined && previousPort !== undefined && nextPort !== previousPort;
444 const descriptionChanged =
445 olds !== undefined && (olds.description ?? "") !== (news.description ?? "");
446 if (
447 !nameChanged &&
448 !zoneChanged &&
449 !networkChanged &&
450 !subnetworkChanged &&
451 !typeChanged &&
452 !portChanged &&
453 !descriptionChanged
454 ) {
455 return undefined;
456 }
457 const sameIdentity =
458 previousName === nextName && lastSegment(previousZone ?? "") === lastSegment(nextZone);
459 return {
460 action: "replace" as const,
461 deleteFirst: sameIdentity,
462 };
463 }),
464
465 read: Effect.fn(function* ({ id, olds, output }) {
466 const env = yield* GcpEnvironment.current;
467 const networkEndpointGroupName = yield* toName(
468 id,
469 olds?.networkEndpointGroupName,
470 output?.networkEndpointGroupName,
471 );
472 const zone = lastSegment(olds?.zone ?? output?.zone ?? DEFAULT_ZONE);
473 const existing = yield* getByName(env.project, zone, networkEndpointGroupName);
474 if (existing === undefined) return undefined;
475 const attrs = toAttrs(existing, env.project);
476 const { labels } = parseDescription(existing.description);
477 return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
478 }),
479
480 list: () =>
481 Effect.gen(function* () {
482 const env = yield* GcpEnvironment.current;
483 const pages = yield* compute.aggregatedListNetworkEndpointGroups
484 .pages({
485 project: env.project,
486 maxResults: 500,
487 returnPartialSuccess: true,
488 })
489 .pipe(Stream.runCollect);
490 return Array.from(pages).flatMap((page) =>
491 Object.values(page.items ?? {}).flatMap((scoped) =>
492 (scoped?.networkEndpointGroups ?? [])
493 .filter((group) => hasOwnershipMarker(group.description))
494 .map((group) => toAttrs(group, env.project)),
495 ),
496 );
497 }),
498
499 reconcile: Effect.fn(function* ({ id, news, output }) {
500 const env = yield* GcpEnvironment.current;
501 const networkEndpointGroupName = yield* toName(
502 id,
503 news.networkEndpointGroupName,
504 output?.networkEndpointGroupName,
505 );
506 const zone = lastSegment(news.zone ?? output?.zone ?? DEFAULT_ZONE);
507 const networkEndpointType = asType(news.networkEndpointType ?? output?.networkEndpointType);
508 const network = toNetworkUrl(
509 env.project,
510 news.network ??
511 (output?.network !== undefined ? lastSegment(output.network) : DEFAULT_NETWORK),
512 );
513 const subnetwork = toSubnetworkUrl(
514 env.project,
515 zone,
516 news.subnetwork ??
517 (output?.subnetwork !== undefined ? lastSegment(output.subnetwork) : undefined),
518 );
519 const desiredLabels = yield* createInternalLabels(id);
520 const description = encodeDescription(news.description, desiredLabels);
521
522 let current = yield* getByName(env.project, zone, networkEndpointGroupName);
523
524 if (current === undefined) {
525 yield* compute
526 .insertNetworkEndpointGroups({
527 project: env.project,
528 zone,
529 body: {
530 name: networkEndpointGroupName,
531 description,
532 network,
533 subnetwork,
534 networkEndpointType,
535 defaultPort: news.defaultPort ?? output?.defaultPort,
536 },
537 })
538 .pipe(
539 Effect.catchTag("Conflict", () => Effect.undefined),
540 Effect.flatMap((operation) =>
541 operation === undefined
542 ? Effect.void
543 : waitZoneOperation(env.project, zone, operation, {
544 ignore: ["RESOURCE_ALREADY_EXISTS"],
545 }).pipe(Effect.asVoid),
546 ),
547 );
548 current = yield* getByName(env.project, zone, networkEndpointGroupName).pipe(
549 Effect.flatMap((group) =>
550 group === undefined
551 ? Effect.fail(
552 new NetworkEndpointGroupNotResolved({
553 networkEndpointGroupName,
554 zone,
555 }),
556 )
557 : Effect.succeed(group),
558 ),
559 Effect.retry({
560 while: (error) => error._tag === "GCP.Compute.NetworkEndpointGroupNotResolved",
561 times: 8,
562 schedule: Schedule.exponential("250 millis"),
563 }),
564 Effect.catchTag("GCP.Compute.NetworkEndpointGroupNotResolved", () => Effect.undefined),
565 );
566 }
567
568 if (current === undefined) {
569 return yield* new NetworkEndpointGroupNotResolved({
570 networkEndpointGroupName,
571 zone,
572 });
573 }
574
575 if (news.networkEndpoints !== undefined) {
576 const observed = yield* listEndpoints(env.project, zone, networkEndpointGroupName);
577 const desired = news.networkEndpoints.map((endpoint) =>
578 toApiEndpoint(env.project, zone, endpoint),
579 );
580 const observedKeys = new Set(observed.map(endpointKey));
581 const desiredKeys = new Set(desired.map(endpointKey));
582 const toAdd = desired.filter((endpoint) => !observedKeys.has(endpointKey(endpoint)));
583 const toRemove = observed.filter((endpoint) => !desiredKeys.has(endpointKey(endpoint)));
584 if (toAdd.length > 0) {
585 yield* runOp(
586 env.project,
587 zone,
588 compute.attachNetworkEndpointsNetworkEndpointGroups({
589 project: env.project,
590 zone,
591 networkEndpointGroup: networkEndpointGroupName,
592 body: { networkEndpoints: toAdd },
593 }),
594 ).pipe(Effect.catchTag("Conflict", () => Effect.void));
595 }
596 if (toRemove.length > 0) {
597 yield* runOp(
598 env.project,
599 zone,
600 compute.detachNetworkEndpointsNetworkEndpointGroups({
601 project: env.project,
602 zone,
603 networkEndpointGroup: networkEndpointGroupName,
604 body: { networkEndpoints: toRemove },
605 }),
606 ).pipe(Effect.catchTag(["NotFound", "Conflict"], () => Effect.void));
607 }
608 current = (yield* getByName(env.project, zone, networkEndpointGroupName)) ?? current;
609 }
610
611 return toAttrs(current, env.project);
612 }),
613
614 delete: Effect.fn(function* ({ output }) {
615 yield* compute
616 .deleteNetworkEndpointGroups({
617 project: output.project,
618 zone: output.zone,
619 networkEndpointGroup: output.networkEndpointGroupName,
620 })
621 .pipe(
622 Effect.catchTag("NotFound", () => Effect.undefined),
623 Effect.flatMap((operation) =>
624 operation === undefined
625 ? Effect.void
626 : waitZoneOperation(output.project, output.zone, operation, {
627 ignore: ["RESOURCE_NOT_FOUND"],
628 }).pipe(Effect.asVoid),
629 ),
630 Effect.catchTag("NotFound", () => Effect.void),
631 );
632 yield* waitGone(output.project, output.zone, output.networkEndpointGroupName);
633 }),
634 });