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

main
ts 499 lines 17.2 KB
Raw
1 import * as aiplatform from "@distilled.cloud/gcp/aiplatform_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 type { Providers } from "../Providers.ts";
13 import {
14 lastSegment,
15 normalizeLocation,
16 parentOf,
17 parseResourceName,
18 rfc1035,
19 resourceNameFromOperation,
20 waitForOperation,
21 } from "./internal.ts";
22 import { listLocations } from "./names.ts";
23 import { settlePendingCreates } from "./operations.ts";
24 import type { EncryptionSpec } from "./shared.ts";
25
26 export type MachineSpec = {
27 /** Machine type, for example `n1-standard-4`. Immutable. */
28 machineType?: string;
29 /** Accelerator type. Immutable. */
30 acceleratorType?: string;
31 /** Accelerators per replica. Immutable. */
32 acceleratorCount?: number;
33 };
34
35 export type AutoscalingMetricSpec = {
36 /** Resource metric name. */
37 metricName?: string;
38 /** Target utilization percent (1–100). Defaults to 60. */
39 target?: number;
40 };
41
42 export type DedicatedResources = {
43 /**
44 * Minimum always-on replicas. Must be >= 1.
45 * @default 1
46 */
47 minReplicaCount?: number;
48 /**
49 * Maximum replicas under load. Defaults to `minReplicaCount`.
50 */
51 maxReplicaCount?: number;
52 /**
53 * Replicas required for the deploy to succeed.
54 */
55 requiredReplicaCount?: number;
56 /**
57 * Schedule the workload on spot VMs.
58 */
59 spot?: boolean;
60 /**
61 * Metric specs that override the default 60% CPU/accelerator targets.
62 */
63 autoscalingMetricSpecs?: AutoscalingMetricSpec[];
64 /**
65 * Single-machine spec. Immutable — changing it replaces the pool.
66 * @default { machineType: "n1-standard-2" }
67 */
68 machineSpec?: MachineSpec;
69 };
70
71 export type DeploymentResourcePoolProps = {
72 /**
73 * Pool id (the `{deployment_resource_pool}` segment). If omitted, a
74 * unique name is generated. Must match
75 * `[a-z]([a-z0-9-]{0,61}[a-z0-9])?`. Immutable — changing it replaces
76 * the pool.
77 */
78 deploymentResourcePoolId?: string;
79 /**
80 * Region. Immutable — changing it replaces the pool.
81 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
82 */
83 location?: string;
84 /**
85 * Dedicated machine resources shared by deployed models.
86 */
87 dedicatedResources?: DedicatedResources;
88 /**
89 * Disable container stdout/stderr logging. Vertex AI accepts but does not
90 * apply updates to it, so changing it replaces the pool.
91 */
92 disableContainerLogging?: boolean;
93 /**
94 * Runtime service account email.
95 */
96 serviceAccount?: string;
97 /**
98 * Customer-managed encryption. Immutable — changing it replaces the
99 * pool.
100 */
101 encryptionSpec?: EncryptionSpec;
102 };
103
104 export type DeploymentResourcePool = Resource<
105 "GCP.AIPlatform.DeploymentResourcePool",
106 DeploymentResourcePoolProps,
107 {
108 /** Full resource name `.../deploymentResourcePools/{pool}`. */
109 name: string;
110 /** Pool id (last path segment). */
111 deploymentResourcePoolId: string;
112 /** Project id. */
113 project: string;
114 /** Location id. */
115 location: string;
116 /** Dedicated resources. */
117 dedicatedResources: DedicatedResources | undefined;
118 /** Whether container logging is disabled. */
119 disableContainerLogging: boolean;
120 /** Runtime service account. */
121 serviceAccount: string | undefined;
122 /** Customer-managed KMS key, if any. */
123 kmsKeyName: string | undefined;
124 /** RFC3339 creation timestamp. */
125 createTime: string | undefined;
126 },
127 never,
128 Providers
129 >;
130
131 /**
132 * A Vertex AI DeploymentResourcePool — dedicated machines shared by
133 * multiple DeployedModels.
134 *
135 * Deployment resource pools have no labels field. Generated ids are
136 * prefixed with `alch-` so `list` / nuke can find them. Location, pool
137 * id, machine spec, and CMEK are immutable. Replica counts, logging, and
138 * service account update in place.
139 *
140 * ### Creating a Pool
141 * **Example:** Single n1-standard-2 replica
142 * ```typescript
143 * const pool = yield* GCP.AIPlatform.DeploymentResourcePool("Shared", {
144 * dedicatedResources: {
145 * minReplicaCount: 1,
146 * maxReplicaCount: 1,
147 * machineSpec: { machineType: "n1-standard-2" },
148 * },
149 * });
150 * ```
151 *
152 * ### Scaling a Pool
153 * **Example:** Raise max replicas
154 * ```typescript
155 * // Same logical id, changed props: the engine updates it in place.
156 * const pool = yield* GCP.AIPlatform.DeploymentResourcePool("Shared", {
157 * dedicatedResources: {
158 * minReplicaCount: 1,
159 * maxReplicaCount: 2,
160 * machineSpec: { machineType: "n1-standard-2" },
161 * },
162 * });
163 * ```
164 *
165 * @resource
166 * @category AIPlatform
167 */
168 export const DeploymentResourcePool = Resource<DeploymentResourcePool>(
169 "GCP.AIPlatform.DeploymentResourcePool",
170 );
171
172 export class DeploymentResourcePoolNotResolved extends Data.TaggedError(
173 "GCP.AIPlatform.DeploymentResourcePoolNotResolved",
174 )<{
175 resourceName: string;
176 }> {}
177
178 export class DeploymentResourcePoolStillExists extends Data.TaggedError(
179 "GCP.AIPlatform.DeploymentResourcePoolStillExists",
180 )<{
181 resourceName: string;
182 }> {}
183
184 const DEFAULT_MACHINE_TYPE = "n1-standard-2";
185 const OWNED_ID_PREFIX = "alch-";
186
187 const resourceName = (project: string, location: string, poolId: string) =>
188 `projects/${project}/locations/${location}/deploymentResourcePools/${poolId}`;
189
190 const ownedId = (value: string) => {
191 const base = rfc1035(value);
192 if (base.startsWith(OWNED_ID_PREFIX)) return base.slice(0, 63);
193 return `${OWNED_ID_PREFIX}${base}`.slice(0, 63).replace(/-+$/g, "");
194 };
195
196 const isOwnedId = (poolId: string) => poolId.startsWith(OWNED_ID_PREFIX);
197
198 const toId = (id: string, poolId: string | undefined, existing?: string) =>
199 Effect.gen(function* () {
200 if (poolId !== undefined) return rfc1035(poolId);
201 if (existing !== undefined) return existing;
202 return ownedId(
203 yield* createPhysicalName({
204 id,
205 maxLength: 58,
206 lowercase: true,
207 }),
208 );
209 });
210
211 const dedicatedOf = (
212 resources: DedicatedResources | aiplatform.GoogleCloudAiplatformV1DedicatedResources | undefined,
213 ): DedicatedResources | undefined => {
214 if (resources === undefined) return undefined;
215 return {
216 minReplicaCount: resources.minReplicaCount,
217 maxReplicaCount: resources.maxReplicaCount,
218 requiredReplicaCount: resources.requiredReplicaCount,
219 spot: resources.spot,
220 autoscalingMetricSpecs: resources.autoscalingMetricSpecs?.map((spec) => ({
221 metricName: spec.metricName,
222 target: spec.target,
223 })),
224 machineSpec: resources.machineSpec
225 ? {
226 machineType: resources.machineSpec.machineType,
227 acceleratorType: resources.machineSpec.acceleratorType,
228 acceleratorCount: resources.machineSpec.acceleratorCount,
229 }
230 : undefined,
231 };
232 };
233
234 const desiredDedicated = (
235 resources: DedicatedResources | undefined,
236 ): aiplatform.GoogleCloudAiplatformV1DedicatedResources => ({
237 minReplicaCount: resources?.minReplicaCount ?? 1,
238 maxReplicaCount: resources?.maxReplicaCount ?? resources?.minReplicaCount ?? 1,
239 requiredReplicaCount: resources?.requiredReplicaCount,
240 spot: resources?.spot,
241 autoscalingMetricSpecs: resources?.autoscalingMetricSpecs,
242 machineSpec: {
243 machineType: resources?.machineSpec?.machineType ?? DEFAULT_MACHINE_TYPE,
244 acceleratorType: resources?.machineSpec?.acceleratorType,
245 acceleratorCount: resources?.machineSpec?.acceleratorCount,
246 },
247 });
248
249 const toAttrs = (
250 pool: aiplatform.GoogleCloudAiplatformV1DeploymentResourcePool,
251 project: string,
252 ) => {
253 const name = pool.name ?? "";
254 const parsed = parseResourceName(name, "deploymentResourcePools");
255 return {
256 name,
257 deploymentResourcePoolId: parsed.id,
258 project: parsed.project || project,
259 location: parsed.location,
260 dedicatedResources: dedicatedOf(pool.dedicatedResources),
261 disableContainerLogging: pool.disableContainerLogging === true,
262 serviceAccount: pool.serviceAccount,
263 kmsKeyName: pool.encryptionSpec?.kmsKeyName,
264 createTime: pool.createTime,
265 };
266 };
267
268 const getByName = (name: string) =>
269 aiplatform
270 .getProjectsLocationsDeploymentResourcePools({ name })
271 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
272
273 const listPools = (project: string, region: string) => {
274 const collect = (parent: string) =>
275 aiplatform.listProjectsLocationsDeploymentResourcePools.pages({ parent, pageSize: 100 }).pipe(
276 Stream.flatMap((page) => Stream.fromIterable(page.deploymentResourcePools ?? [])),
277 Stream.runCollect,
278 Effect.map((chunk) => Array.from(chunk)),
279 );
280 const fallback = Effect.forEach(listLocations(region), (location) =>
281 collect(`projects/${project}/locations/${location}`),
282 ).pipe(Effect.map((pages) => pages.flat()));
283 // Vertex AI has no `locations/-` wildcard; scan known locations.
284 return fallback.pipe(Effect.catchTag("NotFound", () => Effect.succeed([])));
285 };
286
287 /**
288 * Look a pool up by name. A pool is invisible while its create operation
289 * is pending (minutes on a fresh project), so on a miss wait for any
290 * pending create of this pool id and look again — otherwise an
291 * interrupted create's recovery read / delete reports it gone and leaks it.
292 */
293 const getSettled = (name: string) =>
294 Effect.gen(function* () {
295 const existing = yield* getByName(name);
296 if (existing !== undefined) return existing;
297 const parsed = parseResourceName(name, "deploymentResourcePools");
298 const settled = yield* settlePendingCreates({
299 parent: parentOf(parsed.project, parsed.location),
300 collection: "deploymentResourcePools",
301 resourceId: parsed.id,
302 });
303 return settled ? yield* getByName(name) : undefined;
304 });
305
306 const findOwned = (hinted: string | undefined) =>
307 Effect.gen(function* () {
308 if (hinted === undefined || hinted.length === 0) return undefined;
309 return yield* getSettled(hinted);
310 });
311
312 const waitUntilExists = (name: string) =>
313 getByName(name).pipe(
314 Effect.flatMap((pool) =>
315 pool
316 ? Effect.succeed(pool)
317 : Effect.fail(new DeploymentResourcePoolNotResolved({ resourceName: name })),
318 ),
319 Effect.retry({
320 while: (error) => error._tag === "GCP.AIPlatform.DeploymentResourcePoolNotResolved",
321 times: 8,
322 schedule: Schedule.spaced("2 seconds"),
323 }),
324 );
325
326 const waitUntilGone = (name: string) =>
327 getByName(name).pipe(
328 Effect.flatMap((pool) =>
329 pool === undefined
330 ? Effect.void
331 : Effect.fail(new DeploymentResourcePoolStillExists({ resourceName: name })),
332 ),
333 Effect.retry({
334 while: (error) => error._tag === "GCP.AIPlatform.DeploymentResourcePoolStillExists",
335 times: 10,
336 schedule: Schedule.spaced("3 seconds"),
337 }),
338 );
339
340 const machineKey = (spec: MachineSpec | undefined) =>
341 `${spec?.machineType ?? DEFAULT_MACHINE_TYPE}|${spec?.acceleratorType ?? ""}|${spec?.acceleratorCount ?? 0}`;
342
343 export const DeploymentResourcePoolProvider = () =>
344 Provider.succeed(DeploymentResourcePool, {
345 stables: ["name", "deploymentResourcePoolId", "project", "location", "createTime"],
346
347 diff: Effect.fn(function* ({ news, olds, output }) {
348 const env = yield* GcpEnvironment.current;
349 if (!isResolved(news)) return undefined;
350 const previousId = olds?.deploymentResourcePoolId ?? output?.deploymentResourcePoolId;
351 const nextId = news.deploymentResourcePoolId ?? previousId;
352 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
353 const nextLocation = normalizeLocation(
354 news.location ?? olds?.location ?? output?.location,
355 env.region,
356 );
357 const previousMachine = machineKey(
358 olds?.dedicatedResources?.machineSpec ?? output?.dedicatedResources?.machineSpec,
359 );
360 const nextMachine = machineKey(
361 news.dedicatedResources?.machineSpec ??
362 olds?.dedicatedResources?.machineSpec ??
363 output?.dedicatedResources?.machineSpec,
364 );
365 const previousKey = olds?.encryptionSpec?.kmsKeyName ?? output?.kmsKeyName ?? "";
366 const nextKey = news.encryptionSpec?.kmsKeyName ?? previousKey;
367 const replace =
368 (previousId !== undefined && nextId !== undefined && rfc1035(nextId) !== previousId) ||
369 previousLocation !== nextLocation ||
370 previousMachine !== nextMachine ||
371 previousKey !== nextKey ||
372 (olds !== undefined &&
373 (news.disableContainerLogging === true) !== (olds.disableContainerLogging === true));
374 if (!replace) return undefined;
375 return {
376 action: "replace" as const,
377 deleteFirst:
378 previousLocation === nextLocation &&
379 previousId !== undefined &&
380 rfc1035(nextId ?? previousId) === previousId,
381 };
382 }),
383
384 read: Effect.fn(function* ({ id, olds, output }) {
385 const env = yield* GcpEnvironment.current;
386 const poolId = yield* toId(
387 id,
388 olds?.deploymentResourcePoolId,
389 output?.deploymentResourcePoolId,
390 );
391 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
392 const name = output?.name ?? resourceName(env.project, location, poolId);
393 const existing = yield* getSettled(name);
394 if (existing === undefined) return undefined;
395 const attrs = toAttrs(existing, env.project);
396 return isOwnedId(attrs.deploymentResourcePoolId) || output?.name === existing.name
397 ? attrs
398 : Unowned(attrs);
399 }),
400
401 list: () =>
402 Effect.gen(function* () {
403 const env = yield* GcpEnvironment.current;
404 const pools = yield* listPools(env.project, env.region);
405 return pools
406 .filter((pool) => isOwnedId(lastSegment(pool.name ?? "")))
407 .map((pool) => toAttrs(pool, env.project));
408 }),
409
410 reconcile: Effect.fn(function* ({ id, news, output }) {
411 const env = yield* GcpEnvironment.current;
412 const location = normalizeLocation(news.location ?? output?.location, env.region);
413 const poolId = yield* toId(
414 id,
415 news.deploymentResourcePoolId,
416 output?.deploymentResourcePoolId,
417 );
418 const name = resourceName(env.project, location, poolId);
419 const dedicated = desiredDedicated(news.dedicatedResources);
420 const serviceAccount = news.serviceAccount;
421 const disableContainerLogging = news.disableContainerLogging === true;
422
423 let current = yield* findOwned(output?.name ?? name);
424
425 if (current === undefined) {
426 const created = yield* aiplatform
427 .createProjectsLocationsDeploymentResourcePools({
428 parent: parentOf(env.project, location),
429 body: {
430 deploymentResourcePoolId: poolId,
431 deploymentResourcePool: {
432 dedicatedResources: dedicated,
433 disableContainerLogging,
434 serviceAccount,
435 encryptionSpec: news.encryptionSpec,
436 },
437 },
438 })
439 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
440 if (created !== undefined) {
441 const done = yield* waitForOperation(created);
442 const createdName = resourceNameFromOperation(done) ?? name;
443 current = yield* waitUntilExists(createdName);
444 }
445 if (current === undefined) {
446 current = yield* findOwned(name);
447 }
448 }
449
450 if (current === undefined) {
451 return yield* new DeploymentResourcePoolNotResolved({ resourceName: name });
452 }
453
454 const currentName = current.name ?? name;
455 const observed = dedicatedOf(current.dedicatedResources);
456 const minChanged = (observed?.minReplicaCount ?? 1) !== (dedicated.minReplicaCount ?? 1);
457 const maxChanged =
458 (observed?.maxReplicaCount ?? observed?.minReplicaCount ?? 1) !==
459 (dedicated.maxReplicaCount ?? dedicated.minReplicaCount ?? 1);
460 const saChanged =
461 serviceAccount !== undefined && (current.serviceAccount ?? "") !== serviceAccount;
462
463 if (minChanged || maxChanged || saChanged) {
464 const patched = yield* aiplatform.patchProjectsLocationsDeploymentResourcePools({
465 name: currentName,
466 updateMask: [
467 minChanged ? "dedicated_resources.min_replica_count" : undefined,
468 maxChanged ? "dedicated_resources.max_replica_count" : undefined,
469 saChanged ? "service_account" : undefined,
470 ]
471 .filter((field): field is string => field !== undefined)
472 .join(","),
473 body: {
474 name: currentName,
475 dedicatedResources: dedicated,
476 serviceAccount,
477 },
478 });
479 yield* waitForOperation(patched);
480 current = yield* waitUntilExists(currentName);
481 }
482
483 return toAttrs(current, env.project);
484 }),
485
486 delete: Effect.fn(function* ({ output }) {
487 const existing = yield* getSettled(output.name);
488 if (existing === undefined) return;
489 const operation = yield* aiplatform
490 .deleteProjectsLocationsDeploymentResourcePools({
491 name: output.name,
492 })
493 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
494 if (operation !== undefined) {
495 yield* waitForOperation(operation, { notFoundOk: true });
496 }
497 yield* waitUntilGone(output.name);
498 }),
499 });