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

main
ts 373 lines 13 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 * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { tagRecord } from "alchemy/Tags";
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 { hasAlchemyLabels } from "../Labels.ts";
13 import type { Providers } from "../Providers.ts";
14 import {
15 alchemyIdFilter,
16 createInternalLabels,
17 hasAlchemyPrefix,
18 labelsDiffer,
19 listLocations,
20 locationOf,
21 lastSegment,
22 normalizeLocation,
23 projectOf,
24 resourceNameFromOperation,
25 toDisplayName,
26 toLabels,
27 userLabels,
28 } from "./names.ts";
29 import { settlePendingCreates, waitForOperation } from "./operations.ts";
30
31 export type IndexEndpointProps = {
32 /**
33 * Vertex AI location (`us-central1`, …). Immutable — changing it
34 * replaces the endpoint. `US-CENTRAL1` is accepted and normalized to
35 * `us-central1`.
36 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
37 */
38 location?: string;
39 /**
40 * Display name (max 128 Unicode characters). Generated from the stack,
41 * stage, and logical id when omitted.
42 */
43 displayName?: string;
44 /**
45 * Human-readable description.
46 */
47 description?: string;
48 /**
49 * User labels. Alchemy ownership labels are merged in automatically.
50 */
51 labels?: Record<string, string>;
52 /**
53 * When true, the deployed index is reachable through a public endpoint.
54 * @default true
55 */
56 publicEndpointEnabled?: boolean;
57 /**
58 * VPC network to peer, as
59 * `projects/{projectNumber}/global/networks/{network}`. Mutually
60 * exclusive with private service connect. Immutable.
61 */
62 network?: string;
63 /**
64 * Customer-managed encryption key. Immutable.
65 */
66 encryptionSpec?: aiplatform.GoogleCloudAiplatformV1EncryptionSpec;
67 /**
68 * Private Service Connect config. Mutually exclusive with `network`.
69 * Immutable.
70 */
71 privateServiceConnectConfig?: aiplatform.GoogleCloudAiplatformV1PrivateServiceConnectConfig;
72 };
73
74 export type IndexEndpoint = Resource<
75 "GCP.AIPlatform.IndexEndpoint",
76 IndexEndpointProps,
77 {
78 /** Full resource name `projects/{project}/locations/{location}/indexEndpoints/{indexEndpoint}`. */
79 name: string;
80 /** IndexEndpoint id (last path segment). */
81 indexEndpointId: string;
82 /** Project id. */
83 project: string;
84 /** Location id. */
85 location: string;
86 /** Display name. */
87 displayName: string | undefined;
88 /** User-provided description. */
89 description: string | undefined;
90 /** User labels (Alchemy ownership labels stripped). */
91 labels: Record<string, string>;
92 /** Whether a public endpoint is enabled. */
93 publicEndpointEnabled: boolean;
94 /** Public endpoint domain, if enabled. */
95 publicEndpointDomainName: string | undefined;
96 /** Peered VPC network, if set. */
97 network: string | undefined;
98 /** Deployed index resource names. */
99 deployedIndexes: string[];
100 /** RFC3339 creation timestamp. */
101 createTime: string | undefined;
102 /** RFC3339 last-update timestamp. */
103 updateTime: string | undefined;
104 },
105 never,
106 Providers
107 >;
108
109 /**
110 * A Vertex AI Matching Engine IndexEndpoint that serves one or more
111 * deployed indexes.
112 *
113 * Changing `location`, `network`, encryption, or private-service-connect
114 * configuration replaces the endpoint. Display name, description, and
115 * labels update in place.
116 *
117 * ### Creating an IndexEndpoint
118 * **Example:** Public endpoint
119 * ```typescript
120 * const endpoint = yield* GCP.AIPlatform.IndexEndpoint("Search", {
121 * displayName: "product-search",
122 * publicEndpointEnabled: true,
123 * labels: { env: "prod" },
124 * });
125 * ```
126 *
127 * @resource
128 * @category AIPlatform
129 */
130 export const IndexEndpoint = Resource<IndexEndpoint>("GCP.AIPlatform.IndexEndpoint");
131
132 export class IndexEndpointNotResolved extends Data.TaggedError(
133 "GCP.AIPlatform.IndexEndpointNotResolved",
134 )<{
135 resourceName: string;
136 }> {}
137
138 export class IndexEndpointStillExists extends Data.TaggedError(
139 "GCP.AIPlatform.IndexEndpointStillExists",
140 )<{
141 resourceName: string;
142 }> {}
143
144 const toAttrs = (endpoint: aiplatform.GoogleCloudAiplatformV1IndexEndpoint, project: string) => {
145 const name = endpoint.name ?? "";
146 return {
147 name,
148 indexEndpointId: lastSegment(name),
149 project: projectOf(name, project),
150 location: locationOf(name),
151 displayName: endpoint.displayName,
152 description: endpoint.description,
153 labels: userLabels(endpoint.labels),
154 publicEndpointEnabled: endpoint.publicEndpointEnabled === true,
155 publicEndpointDomainName: endpoint.publicEndpointDomainName,
156 network: endpoint.network,
157 deployedIndexes: (endpoint.deployedIndexes ?? [])
158 .map((item) => item.index)
159 .filter((value): value is string => typeof value === "string"),
160 createTime: endpoint.createTime,
161 updateTime: endpoint.updateTime,
162 };
163 };
164
165 const getByName = (name: string) =>
166 aiplatform
167 .getProjectsLocationsIndexEndpoints({ name })
168 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
169
170 const listPage = (parent: string, filter?: string) =>
171 aiplatform.listProjectsLocationsIndexEndpoints.pages({ parent, pageSize: 100, filter }).pipe(
172 Stream.runCollect,
173 Effect.map((pages) => Array.from(pages).flatMap((page) => page.indexEndpoints ?? [])),
174 Effect.catchTag("NotFound", () =>
175 Effect.succeed([] as aiplatform.GoogleCloudAiplatformV1IndexEndpoint[]),
176 ),
177 );
178
179 const findVisible = (project: string, location: string, labels: Record<string, string>) =>
180 listPage(`projects/${project}/locations/${location}`, alchemyIdFilter(labels)).pipe(
181 Effect.map((items) => items.find((item) => hasAlchemyPrefix(item.labels)) ?? undefined),
182 );
183
184 /**
185 * Find our resource by its ownership labels. Ids are server-assigned and the
186 * resource is invisible to `list` while its create operation is pending
187 * (minutes on a fresh project), so on a miss wait for pending creates in
188 * this location and look again — otherwise an interrupted create's
189 * recovery read reports it gone and leaks it.
190 */
191 const findOwned = (project: string, location: string, labels: Record<string, string>) =>
192 Effect.gen(function* () {
193 const visible = yield* findVisible(project, location, labels);
194 if (visible !== undefined) return visible;
195 const settled = yield* settlePendingCreates({
196 parent: `projects/${project}/locations/${location}`,
197 collection: "indexEndpoints",
198 });
199 return settled ? yield* findVisible(project, location, labels) : undefined;
200 });
201
202 const waitUntilExists = (name: string) =>
203 getByName(name).pipe(
204 Effect.filterOrFail(
205 (endpoint): endpoint is aiplatform.GoogleCloudAiplatformV1IndexEndpoint =>
206 endpoint !== undefined,
207 () => new IndexEndpointNotResolved({ resourceName: name }),
208 ),
209 Effect.retry({
210 while: (error) => error._tag === "GCP.AIPlatform.IndexEndpointNotResolved",
211 times: 8,
212 schedule: Schedule.spaced("2 seconds"),
213 }),
214 );
215
216 const waitUntilGone = (name: string) =>
217 getByName(name).pipe(
218 Effect.filterOrFail(
219 (endpoint) => endpoint === undefined,
220 () => new IndexEndpointStillExists({ resourceName: name }),
221 ),
222 Effect.asVoid,
223 Effect.retry({
224 while: (error) => error._tag === "GCP.AIPlatform.IndexEndpointStillExists",
225 times: 10,
226 schedule: Schedule.spaced("2 seconds"),
227 }),
228 );
229
230 export const IndexEndpointProvider = () =>
231 Provider.succeed(IndexEndpoint, {
232 stables: ["name", "indexEndpointId", "project", "location", "network", "createTime"],
233
234 diff: Effect.fn(function* ({ news, olds, output }) {
235 const env = yield* GcpEnvironment.current;
236 if (!isResolved(news)) return undefined;
237 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
238 const nextLocation = normalizeLocation(
239 news.location ?? olds?.location ?? output?.location,
240 env.region,
241 );
242 const previousNetwork = olds?.network ?? output?.network ?? "";
243 const nextNetwork = news.network ?? previousNetwork;
244 const previousKms = olds?.encryptionSpec?.kmsKeyName ?? "";
245 const nextKms = news.encryptionSpec?.kmsKeyName ?? previousKms;
246 if (
247 previousLocation !== nextLocation ||
248 previousNetwork !== nextNetwork ||
249 nextKms !== previousKms
250 ) {
251 return { action: "replace" as const, deleteFirst: false };
252 }
253 return undefined;
254 }),
255
256 read: Effect.fn(function* ({ id, olds, output }) {
257 const env = yield* GcpEnvironment.current;
258 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
259 const ownership = yield* createInternalLabels(id);
260 const existing =
261 (output?.name !== undefined ? yield* getByName(output.name) : undefined) ??
262 (yield* findOwned(env.project, location, ownership));
263 if (existing === undefined) return undefined;
264 const attrs = toAttrs(existing, env.project);
265 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
266 }),
267
268 list: () =>
269 Effect.gen(function* () {
270 const env = yield* GcpEnvironment.current;
271 const pages = yield* Effect.forEach(
272 listLocations(env.region),
273 (location) => listPage(`projects/${env.project}/locations/${location}`),
274 { concurrency: 4 },
275 );
276 return pages
277 .flat()
278 .filter((endpoint) => hasAlchemyPrefix(endpoint.labels))
279 .map((endpoint) => toAttrs(endpoint, env.project));
280 }),
281
282 reconcile: Effect.fn(function* ({ id, news, output }) {
283 const env = yield* GcpEnvironment.current;
284 const location = normalizeLocation(news.location ?? output?.location, env.region);
285 const displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
286 const desiredLabels = {
287 ...toLabels(news.labels),
288 ...(yield* createInternalLabels(id)),
289 };
290 const publicEndpointEnabled = news.publicEndpointEnabled ?? true;
291
292 let current =
293 (output?.name !== undefined ? yield* getByName(output.name) : undefined) ??
294 (yield* findOwned(env.project, location, desiredLabels));
295
296 if (current === undefined) {
297 const created = yield* aiplatform
298 .createProjectsLocationsIndexEndpoints({
299 parent: `projects/${env.project}/locations/${location}`,
300 body: {
301 displayName,
302 description: news.description,
303 labels: desiredLabels,
304 publicEndpointEnabled,
305 network: news.network,
306 encryptionSpec: news.encryptionSpec,
307 privateServiceConnectConfig: news.privateServiceConnectConfig,
308 },
309 })
310 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
311 if (created !== undefined) {
312 const done = yield* waitForOperation(created);
313 const name = resourceNameFromOperation(done);
314 current =
315 name !== undefined
316 ? yield* waitUntilExists(name)
317 : yield* findOwned(env.project, location, desiredLabels);
318 }
319 if (current === undefined) {
320 current = yield* findOwned(env.project, location, desiredLabels);
321 }
322 }
323
324 if (current === undefined || current.name === undefined) {
325 return yield* new IndexEndpointNotResolved({
326 resourceName: output?.name ?? `${location}/indexEndpoints`,
327 });
328 }
329
330 const name = current.name;
331 const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
332 const displayChanged = (current.displayName ?? "") !== displayName;
333 const labelsChanged = labelsDiffer(current.labels, desiredLabels);
334
335 if (descriptionChanged || displayChanged || labelsChanged) {
336 current = yield* aiplatform.patchProjectsLocationsIndexEndpoints({
337 name,
338 updateMask: [
339 descriptionChanged ? "description" : undefined,
340 displayChanged ? "display_name" : undefined,
341 labelsChanged ? "labels" : undefined,
342 ]
343 .filter((field): field is string => field !== undefined)
344 .join(","),
345 body: {
346 name,
347 displayName,
348 description: news.description,
349 labels: desiredLabels,
350 },
351 });
352 }
353
354 return toAttrs(current, env.project);
355 }),
356
357 delete: Effect.fn(function* ({ output }) {
358 const operation = yield* aiplatform
359 .deleteProjectsLocationsIndexEndpoints({ name: output.name })
360 .pipe(
361 Effect.retry({
362 while: (error) => error._tag === "Conflict",
363 times: 8,
364 schedule: Schedule.spaced("2 seconds"),
365 }),
366 Effect.catchTag("NotFound", () => Effect.undefined),
367 );
368 if (operation !== undefined) {
369 yield* waitForOperation(operation, { notFoundOk: true });
370 }
371 yield* waitUntilGone(output.name);
372 }),
373 });