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

main
ts 547 lines 18.3 KB
Raw
1 import * as tpu from "@distilled.cloud/gcp/tpu_v2";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { tagRecord } from "alchemy/Tags";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import * as Stream from "effect/Stream";
10 import { GcpEnvironment } from "../Environment.ts";
11 import { createInternalLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
12 import type { Providers } from "../Providers.ts";
13 import {
14 encodeDescription,
15 hasAlchemyLabelMap,
16 hasOwnershipMarker,
17 normalizeLocation,
18 parseDescription,
19 parseName,
20 replaceOnIdentity,
21 ResourceNotResolved,
22 toPhysicalId,
23 waitForOperation,
24 waitUntilExists,
25 waitUntilGone,
26 } from "./internal.ts";
27 import { toNodeBody, type NodeProps } from "./Node.ts";
28
29 export type MultisliceParams = {
30 /**
31 * Prefix for generated node ids (`np` → `np-0`, `np-1`, …). Defaults to
32 * the queued resource id.
33 */
34 nodeIdPrefix?: string;
35 /**
36 * Number of nodes to provision. Must be greater than 1.
37 */
38 nodeCount?: number;
39 };
40
41 export type NodeSpec = {
42 /**
43 * Parent location
44 * (`projects/{project}/locations/{location}`). Defaults to the queued
45 * resource parent.
46 */
47 parent?: string;
48 /**
49 * Unqualified node id when requesting a single node. Mutually exclusive
50 * with `multisliceParams`.
51 */
52 nodeId?: string;
53 /**
54 * Multislice request. Mutually exclusive with `nodeId`.
55 */
56 multisliceParams?: MultisliceParams;
57 /**
58 * Node configuration. Alchemy ownership labels are merged into
59 * `node.labels` (QueuedResource has no labels field of its own).
60 */
61 node?: NodeProps;
62 };
63
64 export type QueueingPolicy = {
65 /** Absolute time after which the request fails if still unfulfilled. */
66 validUntilTime?: string;
67 /** Relative duration after which resources may be created. */
68 validAfterDuration?: string;
69 /** Absolute interval during which resources may be created. */
70 validInterval?: {
71 /** Inclusive start (RFC3339). */
72 startTime?: string;
73 /** Exclusive end (RFC3339). */
74 endTime?: string;
75 };
76 /** Absolute time after which resources may be created. */
77 validAfterTime?: string;
78 /** Relative duration after which the request fails if still unfulfilled. */
79 validUntilDuration?: string;
80 };
81
82 export type Guaranteed = {
83 /**
84 * Minimum duration the resources must be allocated (`3600s`, …).
85 */
86 minDuration?: string;
87 };
88
89 export type QueuedResourceProps = {
90 /**
91 * Queued resource id (the `{queuedResource}` segment of
92 * `projects/{project}/locations/{location}/queuedResources/{queuedResource}`).
93 * If omitted, a unique RFC1035 name is generated from the stack, stage,
94 * and logical id. Immutable — changing it replaces the resource.
95 */
96 queuedResourceId?: string;
97 /**
98 * Zone (`us-central1-c`, …). Immutable — changing it replaces the
99 * resource.
100 * @default "us-central1-c"
101 */
102 location?: string;
103 /**
104 * Reservation to provision in
105 * (`projects/{project}/locations/{zone}/reservations/{reservation}`).
106 * Immutable.
107 */
108 reservationName?: string;
109 /**
110 * Request the Spot tier. Immutable.
111 * @default false
112 */
113 spot?: boolean;
114 /**
115 * Guaranteed tier. Immutable.
116 */
117 guaranteed?: Guaranteed;
118 /**
119 * When the request may be fulfilled. Immutable.
120 */
121 queueingPolicy?: QueueingPolicy;
122 /**
123 * TPU node specification. Omit to request a default v2-8 node with the
124 * standard runtime. Alchemy ownership is stamped on each nested node's
125 * labels and description (QueuedResource has no labels API).
126 */
127 nodeSpec?: NodeSpec[];
128 /**
129 * Delete running nodes belonging to this request before deleting the
130 * queued resource.
131 * @default true
132 */
133 forceDestroy?: boolean;
134 };
135
136 export type QueuedResource = Resource<
137 "GCP.TPU.QueuedResource",
138 QueuedResourceProps,
139 {
140 /** Full resource name `projects/{project}/locations/{location}/queuedResources/{queuedResource}`. */
141 name: string;
142 /** Queued resource id (last path segment). */
143 queuedResourceId: string;
144 /** Project id. */
145 project: string;
146 /** Zone id. */
147 location: string;
148 /** Reservation name, if any. */
149 reservationName: string | undefined;
150 /** Whether the Spot tier is set. */
151 spot: boolean;
152 /** Guaranteed tier configuration. */
153 guaranteed: Guaranteed | undefined;
154 /** Queueing policy. */
155 queueingPolicy: QueueingPolicy | undefined;
156 /** Node specification currently stored on the request. */
157 nodeSpec: NodeSpec[];
158 /** Server-reported state (`ACCEPTED`, `WAITING_FOR_RESOURCES`, …). */
159 state: string | undefined;
160 /** Who initiated the current state (`USER`, `SERVICE`). */
161 stateInitiator: string | undefined;
162 /** Error that caused `FAILED`, if any. */
163 failedError: string | undefined;
164 /** RFC3339 creation timestamp. */
165 createTime: string | undefined;
166 },
167 never,
168 Providers
169 >;
170
171 /**
172 * A Cloud TPU queued resource request. The request sits in a queue until
173 * capacity is available, then provisions the requested TPU node(s).
174 *
175 * Queued resources have no labels field — Alchemy stamps ownership onto
176 * each nested `nodeSpec.node` labels and description so `list` / nuke can
177 * find them. The resource is create-only: changing identity or the node
178 * spec replaces it.
179 *
180 * ### Creating a Queued Resource
181 * **Example:** Default v2-8 request
182 * ```typescript
183 * const request = yield* GCP.TPU.QueuedResource("Trainer", {});
184 * ```
185 *
186 * **Example:** Spot request with an explicit node spec
187 * ```typescript
188 * const request = yield* GCP.TPU.QueuedResource("Trainer", {
189 * location: "us-central1-c",
190 * spot: true,
191 * nodeSpec: [{
192 * nodeId: "app-tpu",
193 * node: {
194 * acceleratorType: "v2-8",
195 * runtimeVersion: "tpu-ubuntu2204-base",
196 * labels: { env: "prod" },
197 * },
198 * }],
199 * });
200 * ```
201 *
202 * @resource
203 * @category TPU
204 */
205 export const QueuedResource = Resource<QueuedResource>("GCP.TPU.QueuedResource");
206
207 const resourceName = (project: string, location: string, queuedResourceId: string) =>
208 `projects/${project}/locations/${location}/queuedResources/${queuedResourceId}`;
209
210 const parentOf = (project: string, location: string) => `projects/${project}/locations/${location}`;
211
212 const intervalOf = (interval: tpu.Interval | QueueingPolicy["validInterval"] | undefined) => {
213 if (interval === undefined) return undefined;
214 return { startTime: interval.startTime, endTime: interval.endTime };
215 };
216
217 const queueingOf = (
218 policy: tpu.QueueingPolicy | QueueingPolicy | undefined,
219 ): QueueingPolicy | undefined => {
220 if (policy === undefined) return undefined;
221 return {
222 validUntilTime: policy.validUntilTime,
223 validAfterDuration: policy.validAfterDuration,
224 validInterval: intervalOf(policy.validInterval),
225 validAfterTime: policy.validAfterTime,
226 validUntilDuration: policy.validUntilDuration,
227 };
228 };
229
230 const queueingKey = (policy: QueueingPolicy | undefined) =>
231 JSON.stringify({
232 validUntilTime: policy?.validUntilTime ?? "",
233 validAfterDuration: policy?.validAfterDuration ?? "",
234 validIntervalStart: policy?.validInterval?.startTime ?? "",
235 validIntervalEnd: policy?.validInterval?.endTime ?? "",
236 validAfterTime: policy?.validAfterTime ?? "",
237 validUntilDuration: policy?.validUntilDuration ?? "",
238 });
239
240 const guaranteedOf = (
241 guaranteed: tpu.Guaranteed | Guaranteed | undefined,
242 ): Guaranteed | undefined => {
243 if (guaranteed === undefined) return undefined;
244 return { minDuration: guaranteed.minDuration };
245 };
246
247 const networkTagsOf = (node: tpu.Node | NodeProps) => {
248 if ("networkTags" in node && node.networkTags) {
249 return [...node.networkTags];
250 }
251 if ("tags" in node && node.tags) {
252 return [...node.tags];
253 }
254 return undefined;
255 };
256
257 const stringRecordOf = (map: Record<string, string | undefined> | undefined) =>
258 map
259 ? Object.fromEntries(
260 Object.entries(map).filter((entry): entry is [string, string] => entry[1] !== undefined),
261 )
262 : undefined;
263
264 const nodeSpecOf = (spec: tpu.NodeSpec | NodeSpec, parent: string): NodeSpec => ({
265 parent: spec.parent ?? parent,
266 nodeId: spec.nodeId,
267 multisliceParams: spec.multisliceParams
268 ? {
269 nodeIdPrefix: spec.multisliceParams.nodeIdPrefix,
270 nodeCount: spec.multisliceParams.nodeCount,
271 }
272 : undefined,
273 node: spec.node
274 ? {
275 description: spec.node.description,
276 labels: stringRecordOf(spec.node.labels),
277 metadata: stringRecordOf(spec.node.metadata),
278 networkTags: networkTagsOf(spec.node),
279 runtimeVersion: spec.node.runtimeVersion,
280 acceleratorType: spec.node.acceleratorType,
281 acceleratorConfig: spec.node.acceleratorConfig,
282 cidrBlock: spec.node.cidrBlock,
283 serviceAccount: spec.node.serviceAccount,
284 networkConfig: spec.node.networkConfig,
285 networkConfigs: spec.node.networkConfigs,
286 bootDiskConfig: spec.node.bootDiskConfig,
287 dataDisks: spec.node.dataDisks,
288 schedulingConfig: spec.node.schedulingConfig,
289 shieldedInstanceConfig: spec.node.shieldedInstanceConfig,
290 }
291 : undefined,
292 });
293
294 const nodeSpecKey = (spec: NodeSpec) =>
295 JSON.stringify({
296 parent: spec.parent ?? "",
297 nodeId: spec.nodeId ?? "",
298 prefix: spec.multisliceParams?.nodeIdPrefix ?? "",
299 count: spec.multisliceParams?.nodeCount ?? "",
300 runtime: spec.node?.runtimeVersion ?? "",
301 accelerator: spec.node?.acceleratorType ?? "",
302 topology: spec.node?.acceleratorConfig?.topology ?? "",
303 cidr: spec.node?.cidrBlock ?? "",
304 });
305
306 const specsKey = (specs: readonly NodeSpec[]) => JSON.stringify(specs.map(nodeSpecKey));
307
308 const nestedNodes = (resource: tpu.QueuedResource) => resource.tpu?.nodeSpec ?? [];
309
310 const nestedOwnershipLabels = (resource: tpu.QueuedResource) => {
311 const labels: Record<string, string> = {};
312 for (const spec of nestedNodes(resource)) {
313 Object.assign(labels, tagRecord(spec.node?.labels));
314 Object.assign(labels, parseDescription(spec.node?.description).labels);
315 }
316 return labels;
317 };
318
319 const hasNestedOwnership = (resource: tpu.QueuedResource) => {
320 for (const spec of nestedNodes(resource)) {
321 if (hasAlchemyLabelMap(spec.node?.labels)) return true;
322 if (hasOwnershipMarker(spec.node?.description)) return true;
323 }
324 return false;
325 };
326
327 const desiredSpecs = (
328 news: QueuedResourceProps,
329 parent: string,
330 desiredLabels: Record<string, string>,
331 ): tpu.NodeSpec[] => {
332 const specs =
333 news.nodeSpec !== undefined && news.nodeSpec.length > 0
334 ? news.nodeSpec
335 : [{ node: {} as NodeProps }];
336 return specs.map((spec) => {
337 const node = spec.node ?? {};
338 const description = encodeDescription(desiredLabels, node.description);
339 const labels = { ...toLabels(node.labels), ...desiredLabels };
340 return {
341 parent: spec.parent ?? parent,
342 nodeId: spec.nodeId,
343 multisliceParams: spec.multisliceParams,
344 node: toNodeBody({ ...node, labels }, labels, { description }),
345 };
346 });
347 };
348
349 const toAttrs = (resource: tpu.QueuedResource, project: string) => {
350 const name = resource.name ?? "";
351 const parsed = parseName(name, "queuedResources");
352 const parent = parentOf(parsed.project || project, parsed.location);
353 return {
354 name,
355 queuedResourceId: parsed.id,
356 project: parsed.project || project,
357 location: parsed.location,
358 reservationName: resource.reservationName,
359 spot: resource.spot !== undefined,
360 guaranteed: guaranteedOf(resource.guaranteed),
361 queueingPolicy: queueingOf(resource.queueingPolicy),
362 nodeSpec: (resource.tpu?.nodeSpec ?? []).map((spec) => {
363 const mapped = nodeSpecOf(spec, parent);
364 if (mapped.node?.description !== undefined) {
365 mapped.node = {
366 ...mapped.node,
367 description: parseDescription(mapped.node.description).description,
368 labels: mapped.node.labels
369 ? Object.fromEntries(
370 Object.entries(mapped.node.labels).filter(([key]) => !key.startsWith("alchemy-")),
371 )
372 : undefined,
373 };
374 }
375 return mapped;
376 }),
377 state: resource.state?.state,
378 stateInitiator: resource.state?.stateInitiator,
379 failedError: resource.state?.failedData?.error?.message,
380 createTime: resource.createTime,
381 };
382 };
383
384 const isPlaceholder = (resource: tpu.QueuedResource) => {
385 const name = resource.name ?? "";
386 return (
387 name.length === 0 || name.endsWith("/queuedResources/-") || name.endsWith("/queuedResources/")
388 );
389 };
390
391 const getByName = (name: string) =>
392 tpu
393 .getProjectsLocationsQueuedResources({ name })
394 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
395
396 const specIdentityChanged = (
397 previous: QueuedResourceProps | { nodeSpec?: NodeSpec[] } | undefined,
398 next: QueuedResourceProps,
399 parent: string,
400 ) => {
401 const previousSpecs = (previous?.nodeSpec ?? []).map((spec) => nodeSpecOf(spec, parent));
402 const nextSpecs =
403 next.nodeSpec !== undefined && next.nodeSpec.length > 0
404 ? next.nodeSpec.map((spec) => nodeSpecOf(spec, parent))
405 : previousSpecs;
406 if (previousSpecs.length === 0) return false;
407 return specsKey(previousSpecs) !== specsKey(nextSpecs);
408 };
409
410 export const QueuedResourceProvider = () =>
411 Provider.succeed(QueuedResource, {
412 stables: ["name", "queuedResourceId", "project", "location", "createTime"],
413
414 diff: Effect.fn(function* ({ news, olds, output }) {
415 if (!isResolved(news)) return undefined;
416
417 const previousId = olds?.queuedResourceId ?? output?.queuedResourceId;
418 const nextId = news.queuedResourceId ?? previousId;
419 const previousLocation = normalizeLocation(olds?.location ?? output?.location);
420 const nextLocation = normalizeLocation(news.location ?? output?.location);
421 const parent = `projects/_/locations/${nextLocation}`;
422 const previousReservation = olds?.reservationName ?? output?.reservationName ?? "";
423 const nextReservation = news.reservationName ?? previousReservation;
424 const previousSpot = olds?.spot ?? output?.spot ?? false;
425 const nextSpot = news.spot ?? previousSpot;
426 const previousGuaranteed =
427 guaranteedOf(olds?.guaranteed ?? output?.guaranteed)?.minDuration ?? "";
428 const nextGuaranteed =
429 guaranteedOf(news.guaranteed ?? olds?.guaranteed ?? output?.guaranteed)?.minDuration ??
430 previousGuaranteed;
431 const previousQueueing = queueingKey(
432 queueingOf(olds?.queueingPolicy ?? output?.queueingPolicy),
433 );
434 const nextQueueing = queueingKey(
435 queueingOf(news.queueingPolicy ?? olds?.queueingPolicy ?? output?.queueingPolicy),
436 );
437
438 return replaceOnIdentity({
439 previousId,
440 nextId,
441 previousLocation,
442 nextLocation,
443 extra:
444 previousReservation !== nextReservation ||
445 previousSpot !== nextSpot ||
446 previousGuaranteed !== nextGuaranteed ||
447 previousQueueing !== nextQueueing ||
448 specIdentityChanged(olds ?? output, news, parent),
449 });
450 }),
451
452 read: Effect.fn(function* ({ id, olds, output }) {
453 const env = yield* GcpEnvironment.current;
454 const queuedResourceId = yield* toPhysicalId(
455 id,
456 olds?.queuedResourceId,
457 output?.queuedResourceId,
458 );
459 const location = normalizeLocation(olds?.location ?? output?.location);
460 const name = output?.name ?? resourceName(env.project, location, queuedResourceId);
461 const existing = yield* getByName(name);
462 if (existing === undefined) return undefined;
463 const attrs = toAttrs(existing, env.project);
464 const nested = nestedOwnershipLabels(existing);
465 return (yield* hasAlchemyLabels(id, nested)) ? attrs : Unowned(attrs);
466 }),
467
468 list: () =>
469 Effect.gen(function* () {
470 const env = yield* GcpEnvironment.current;
471 return yield* tpu.listProjectsLocationsQueuedResources
472 .pages({
473 parent: `projects/${env.project}/locations/-`,
474 pageSize: 1000,
475 })
476 .pipe(
477 Stream.flatMap((page) => Stream.fromIterable(page.queuedResources ?? [])),
478 Stream.filter((resource) => !isPlaceholder(resource) && hasNestedOwnership(resource)),
479 Stream.map((resource) => toAttrs(resource, env.project)),
480 Stream.runCollect,
481 Effect.map((chunk) => Array.from(chunk)),
482 Effect.catchTag("NotFound", () => Effect.succeed([])),
483 );
484 }),
485
486 reconcile: Effect.fn(function* ({ id, news, output }) {
487 const env = yield* GcpEnvironment.current;
488 const queuedResourceId = yield* toPhysicalId(
489 id,
490 news.queuedResourceId,
491 output?.queuedResourceId,
492 );
493 const location = normalizeLocation(news.location ?? output?.location);
494 const parent = parentOf(env.project, location);
495 const name = resourceName(env.project, location, queuedResourceId);
496 const desiredLabels = yield* createInternalLabels(id);
497
498 let current = yield* getByName(output?.name ?? name);
499
500 if (current === undefined) {
501 const created = yield* tpu
502 .createProjectsLocationsQueuedResources({
503 parent,
504 queuedResourceId,
505 body: {
506 reservationName: news.reservationName,
507 spot: news.spot === true ? {} : undefined,
508 guaranteed: news.guaranteed,
509 queueingPolicy: news.queueingPolicy,
510 tpu: { nodeSpec: desiredSpecs(news, parent, desiredLabels) },
511 },
512 })
513 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
514 if (created !== undefined) {
515 yield* waitForOperation(created);
516 }
517 current = yield* waitUntilExists(getByName(name), name);
518 }
519
520 if (current === undefined) {
521 return yield* new ResourceNotResolved({ resourceName: name });
522 }
523
524 return toAttrs(current, env.project);
525 }),
526
527 delete: Effect.fn(function* ({ output, olds }) {
528 const force = olds?.forceDestroy !== false;
529 const operation = yield* tpu
530 .deleteProjectsLocationsQueuedResources({
531 name: output.name,
532 force,
533 })
534 .pipe(
535 Effect.catchTag("NotFound", () => Effect.undefined),
536 Effect.retry({
537 while: (error) => error._tag === "Conflict",
538 times: 8,
539 schedule: Schedule.spaced("5 seconds"),
540 }),
541 );
542 if (operation !== undefined) {
543 yield* waitForOperation(operation, { notFoundOk: true });
544 }
545 yield* waitUntilGone(getByName(output.name), output.name);
546 }),
547 });