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

main
ts 457 lines 15.2 KB
Raw
1 import * as dataplex from "@distilled.cloud/gcp/dataplex_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 { tagRecord } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import { GcpEnvironment } from "../Environment.ts";
10 import { createInternalLabels, diffLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
11 import type { Providers } from "../Providers.ts";
12 import {
13 DataplexNotResolved,
14 MAX_NAME_LENGTH,
15 collectPages,
16 expandParent,
17 fingerprint,
18 hasAlchemyLabelMap,
19 lastSegment,
20 listAtLocation,
21 normalizeLocation,
22 parseName,
23 replaceOnIdentity,
24 retryQuota,
25 rfc1035,
26 userLabels,
27 waitUntilExists,
28 waitUntilGone,
29 } from "./internal.ts";
30
31 export type EntrySource = {
32 /** Name of the resource in the source system. */
33 resource?: string;
34 /** Name of the source system. */
35 system?: string;
36 /** Platform containing the source system. */
37 platform?: string;
38 /** User-friendly display name. */
39 displayName?: string;
40 /** Description of the data resource. */
41 description?: string;
42 /**
43 * User-defined source labels. Alchemy ownership labels are merged in
44 * automatically — Entries have no top-level labels field.
45 */
46 labels?: Record<string, string>;
47 /** Ancestor entries in the source system. */
48 ancestors?: Array<{ name?: string; type?: string }>;
49 /** Time the resource was created in the source system. */
50 createTime?: string;
51 /** Time the resource was last updated in the source system. */
52 updateTime?: string;
53 };
54
55 export type EntryGroupsEntryProps = {
56 /**
57 * Parent Entry Group. Full name
58 * `projects/{project}/locations/{location}/entryGroups/{entryGroup}`
59 * or the entry-group id (combined with `location`). Immutable —
60 * changing it replaces the entry.
61 */
62 entryGroup: string;
63 /**
64 * Entry id (the `{entry}` segment of
65 * `.../entryGroups/{entryGroup}/entries/{entry}`). May contain slashes
66 * (up to 4000 characters). If omitted, a unique name is generated from
67 * the stack, stage, and logical id. Immutable — changing it replaces
68 * the entry.
69 */
70 entryId?: string;
71 /**
72 * Region used when `entryGroup` is a bare id. Immutable — changing it
73 * replaces the entry.
74 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
75 */
76 location?: string;
77 /**
78 * Entry type resource name
79 * `projects/{project}/locations/{location}/entryTypes/{entryType}`.
80 * Immutable — changing it replaces the entry.
81 */
82 entryType: string;
83 /**
84 * Parent entry resource name. Immutable — changing it replaces the
85 * entry.
86 */
87 parentEntry?: string;
88 /**
89 * Fully qualified name used by an external system.
90 */
91 fullyQualifiedName?: string;
92 /**
93 * Aspects attached to the entry, keyed by
94 * `{project}.{location}.{aspectType}` (or with `@{path}`).
95 */
96 aspects?: dataplex.GoogleCloudDataplexV1AspectMap;
97 /**
98 * Source-system metadata. Labels on `entrySource` receive Alchemy
99 * ownership stamps.
100 */
101 entrySource?: EntrySource;
102 /**
103 * Convenience labels merged into `entrySource.labels`.
104 */
105 labels?: Record<string, string>;
106 };
107
108 export type EntryGroupsEntry = Resource<
109 "GCP.Dataplex.EntryGroupsEntry",
110 EntryGroupsEntryProps,
111 {
112 /** Full resource name. */
113 name: string;
114 /** Entry id (path after `/entries/`). */
115 entryId: string;
116 /** Parent entry group resource name. */
117 entryGroup: string;
118 /** Parent entry group id. */
119 entryGroupId: string;
120 /** Project id. */
121 project: string;
122 /** Location id. */
123 location: string;
124 /** Entry type resource name. */
125 entryType: string | undefined;
126 /** Parent entry resource name. */
127 parentEntry: string | undefined;
128 /** Fully qualified name. */
129 fullyQualifiedName: string | undefined;
130 /** Aspects attached to the entry. */
131 aspects: dataplex.GoogleCloudDataplexV1AspectMap | undefined;
132 /** Source-system metadata. */
133 entrySource: EntrySource | undefined;
134 /** User labels from `entrySource` (Alchemy ownership labels stripped). */
135 labels: Record<string, string>;
136 /** RFC3339 creation timestamp. */
137 createTime: string | undefined;
138 /** RFC3339 last-update timestamp. */
139 updateTime: string | undefined;
140 },
141 never,
142 Providers
143 >;
144
145 /**
146 * A Dataplex Universal Catalog Entry — a metadata record for a data
147 * resource.
148 *
149 * Entries have no top-level labels field, so Alchemy stamps ownership
150 * into `entrySource.labels`. Changing `entryId`, `entryGroup`,
151 * `location`, `entryType`, or `parentEntry` replaces the entry. FQN,
152 * aspects, and source metadata update in place.
153 *
154 * ### Creating an Entry
155 * **Example:** Entry in a group
156 * ```typescript
157 * const entry = yield* GCP.Dataplex.EntryGroupsEntry("Orders", {
158 * entryGroup: group.name,
159 * entryType:
160 * "projects/dataplex-types/locations/global/entryTypes/generic",
161 * labels: { env: "prod" },
162 * });
163 * ```
164 *
165 * ### Updating an Entry
166 * **Example:** Fully qualified name and labels
167 * ```typescript
168 * // Same logical id as before; only the changed props differ.
169 * const entry = yield* GCP.Dataplex.EntryGroupsEntry("Orders", {
170 * entryGroup: group.name,
171 * entryType:
172 * "projects/dataplex-types/locations/global/entryTypes/generic",
173 * fullyQualifiedName: "app.orders",
174 * labels: { env: "prod", team: "data" },
175 * });
176 * ```
177 *
178 * @resource
179 * @category Dataplex
180 */
181 export const EntryGroupsEntry = Resource<EntryGroupsEntry>("GCP.Dataplex.EntryGroupsEntry");
182
183 const resolveParent = (
184 project: string,
185 entryGroup: string,
186 location: string | undefined,
187 defaultLocation: string,
188 ) => {
189 const parent = expandParent(
190 entryGroup,
191 project,
192 normalizeLocation(location, defaultLocation),
193 "entryGroups",
194 );
195 const parsed = parseName(`${parent}/entries/_`, "entries");
196 return {
197 parent: parsed.parent,
198 location: parsed.location,
199 project: parsed.project || project,
200 entryGroupId: lastSegment(parsed.parent),
201 };
202 };
203
204 const resourceName = (parent: string, entryId: string) => `${parent}/entries/${entryId}`;
205
206 const toEntryId = (id: string, explicit: string | undefined, existing: string | undefined) =>
207 Effect.gen(function* () {
208 if (explicit !== undefined) return explicit;
209 if (existing !== undefined) return existing;
210 return rfc1035(
211 yield* createPhysicalName({
212 id,
213 maxLength: MAX_NAME_LENGTH,
214 lowercase: true,
215 }),
216 "entry",
217 );
218 });
219
220 const sourceLabels = (news: EntryGroupsEntryProps, ownership: Record<string, string>) => ({
221 ...toLabels(news.entrySource?.labels),
222 ...toLabels(news.labels),
223 ...ownership,
224 });
225
226 const toSource = (
227 source: dataplex.GoogleCloudDataplexV1EntrySource | undefined,
228 ): EntrySource | undefined => {
229 if (source === undefined) return undefined;
230 return {
231 resource: source.resource,
232 system: source.system,
233 platform: source.platform,
234 displayName: source.displayName,
235 description: source.description,
236 labels: userLabels(source.labels),
237 ancestors: source.ancestors,
238 createTime: source.createTime,
239 updateTime: source.updateTime,
240 };
241 };
242
243 const toAttrs = (entry: dataplex.GoogleCloudDataplexV1Entry, project: string) => {
244 const name = entry.name ?? "";
245 const parsed = parseName(name, "entries");
246 const group = parseName(parsed.parent, "entryGroups");
247 return {
248 name,
249 entryId: parsed.id,
250 entryGroup: parsed.parent,
251 entryGroupId: group.id,
252 project: parsed.project || project,
253 location: parsed.location,
254 entryType: entry.entryType,
255 parentEntry: entry.parentEntry,
256 fullyQualifiedName: entry.fullyQualifiedName,
257 aspects: entry.aspects,
258 entrySource: toSource(entry.entrySource),
259 labels: userLabels(entry.entrySource?.labels),
260 createTime: entry.createTime,
261 updateTime: entry.updateTime,
262 };
263 };
264
265 const getByName = (name: string) =>
266 retryQuota(dataplex.getProjectsLocationsEntryGroupsEntries({ name, view: "ALL" })).pipe(
267 Effect.catchTag("NotFound", () => Effect.undefined),
268 );
269
270 const listEntriesUnder = (parent: string, project: string) =>
271 collectPages(
272 dataplex.listProjectsLocationsEntryGroupsEntries.pages({
273 parent,
274 pageSize: 100,
275 }),
276 (page) => page.entries,
277 ).pipe(
278 Effect.map((items) =>
279 items
280 .filter((item) => hasAlchemyLabelMap(item.entrySource?.labels))
281 .map((item) => toAttrs(item, project)),
282 ),
283 Effect.catchTag("NotFound", () => Effect.succeed([])),
284 );
285
286 export const EntryGroupsEntryProvider = () =>
287 Provider.succeed(EntryGroupsEntry, {
288 stables: [
289 "name",
290 "entryId",
291 "entryGroup",
292 "entryGroupId",
293 "project",
294 "location",
295 "entryType",
296 "parentEntry",
297 "createTime",
298 ],
299
300 diff: Effect.fn(function* ({ news, olds, output }) {
301 if (!isResolved(news)) return undefined;
302 const env = yield* GcpEnvironment.current;
303 const previousType = olds?.entryType ?? output?.entryType ?? "";
304 const nextType = news.entryType ?? previousType;
305 const previousParentEntry = olds?.parentEntry ?? output?.parentEntry ?? "";
306 const nextParentEntry = news.parentEntry ?? previousParentEntry;
307 return replaceOnIdentity({
308 previousId: olds?.entryId ?? output?.entryId,
309 nextId: news.entryId ?? olds?.entryId ?? output?.entryId,
310 previousLocation: normalizeLocation(olds?.location ?? output?.location, env.region),
311 nextLocation: normalizeLocation(
312 news.location ?? olds?.location ?? output?.location,
313 env.region,
314 ),
315 previousParent: olds?.entryGroup ?? output?.entryGroup,
316 nextParent: news.entryGroup ?? olds?.entryGroup ?? output?.entryGroup,
317 extra: nextType !== previousType || nextParentEntry !== previousParentEntry,
318 });
319 }),
320
321 read: Effect.fn(function* ({ id, olds, output }) {
322 const env = yield* GcpEnvironment.current;
323 const resolved = resolveParent(
324 env.project,
325 olds?.entryGroup ?? output?.entryGroup ?? "",
326 olds?.location ?? output?.location,
327 env.region,
328 );
329 const entryId = yield* toEntryId(id, olds?.entryId, output?.entryId);
330 const name = output?.name ?? resourceName(resolved.parent, entryId);
331 const existing = yield* getByName(name);
332 if (existing === undefined) return undefined;
333 const attrs = toAttrs(existing, env.project);
334 return (yield* hasAlchemyLabels(id, tagRecord(existing.entrySource?.labels)))
335 ? attrs
336 : Unowned(attrs);
337 }),
338
339 list: () =>
340 Effect.gen(function* () {
341 const env = yield* GcpEnvironment.current;
342 const groups = yield* listAtLocation(env.project, env.region, (parent) =>
343 collectPages(
344 dataplex.listProjectsLocationsEntryGroups.pages({
345 parent,
346 pageSize: 1000,
347 }),
348 (page) => page.entryGroups,
349 ).pipe(Effect.map((items) => items.filter((item) => hasAlchemyLabelMap(item.labels)))),
350 );
351 const nested = yield* Effect.forEach(
352 groups,
353 (group) => (group.name ? listEntriesUnder(group.name, env.project) : Effect.succeed([])),
354 { concurrency: 4 },
355 );
356 return nested.flat();
357 }),
358
359 reconcile: Effect.fn(function* ({ id, news, output }) {
360 const env = yield* GcpEnvironment.current;
361 const resolved = resolveParent(
362 env.project,
363 news.entryGroup,
364 news.location ?? output?.location,
365 env.region,
366 );
367 const entryId = yield* toEntryId(id, news.entryId, output?.entryId);
368 const name = resourceName(resolved.parent, entryId);
369 const ownership = yield* createInternalLabels(id);
370 const desiredSourceLabels = sourceLabels(news, ownership);
371 const desiredSource: dataplex.GoogleCloudDataplexV1EntrySource = {
372 resource: news.entrySource?.resource,
373 system: news.entrySource?.system,
374 platform: news.entrySource?.platform,
375 displayName: news.entrySource?.displayName,
376 description: news.entrySource?.description,
377 labels: desiredSourceLabels,
378 ancestors: news.entrySource?.ancestors,
379 createTime: news.entrySource?.createTime,
380 updateTime: news.entrySource?.updateTime,
381 };
382
383 let current = yield* getByName(output?.name ?? name);
384
385 if (current === undefined) {
386 const created = yield* dataplex
387 .createProjectsLocationsEntryGroupsEntries({
388 parent: resolved.parent,
389 entryId,
390 body: {
391 entryType: news.entryType,
392 parentEntry: news.parentEntry,
393 fullyQualifiedName: news.fullyQualifiedName,
394 aspects: news.aspects,
395 entrySource: desiredSource,
396 },
397 })
398 .pipe(
399 retryQuota,
400 Effect.catchTag("Conflict", () => getByName(name)),
401 );
402 current = created ?? undefined;
403 if (current === undefined) {
404 current = yield* waitUntilExists(getByName(name), name);
405 }
406 }
407
408 if (current === undefined) {
409 return yield* new DataplexNotResolved({ resourceName: name });
410 }
411
412 const observedLabels = tagRecord(current.entrySource?.labels);
413 const { upsert, removed } = diffLabels(observedLabels, desiredSourceLabels);
414 const labelsChanged = upsert.length > 0 || removed.length > 0;
415 const fqnChanged = (current.fullyQualifiedName ?? "") !== (news.fullyQualifiedName ?? "");
416 const aspectsChanged =
417 news.aspects !== undefined && fingerprint(news.aspects) !== fingerprint(current.aspects);
418 const sourceChanged =
419 (current.entrySource?.resource ?? "") !== (news.entrySource?.resource ?? "") ||
420 (current.entrySource?.system ?? "") !== (news.entrySource?.system ?? "") ||
421 (current.entrySource?.platform ?? "") !== (news.entrySource?.platform ?? "") ||
422 (current.entrySource?.displayName ?? "") !== (news.entrySource?.displayName ?? "") ||
423 (current.entrySource?.description ?? "") !== (news.entrySource?.description ?? "");
424
425 if (labelsChanged || fqnChanged || aspectsChanged || sourceChanged) {
426 current = yield* retryQuota(
427 dataplex.patchProjectsLocationsEntryGroupsEntries({
428 name: current.name ?? name,
429 updateMask: [
430 fqnChanged ? "fullyQualifiedName" : undefined,
431 aspectsChanged ? "aspects" : undefined,
432 labelsChanged || sourceChanged ? "entrySource" : undefined,
433 ]
434 .filter((field): field is string => field !== undefined)
435 .join(","),
436 body: {
437 name: current.name ?? name,
438 fullyQualifiedName: news.fullyQualifiedName,
439 aspects: news.aspects ?? current.aspects,
440 entrySource: desiredSource,
441 },
442 }),
443 );
444 }
445
446 return toAttrs(current, env.project);
447 }),
448
449 delete: Effect.fn(function* ({ output }) {
450 yield* retryQuota(
451 dataplex.deleteProjectsLocationsEntryGroupsEntries({
452 name: output.name,
453 }),
454 ).pipe(Effect.catchTag("NotFound", () => Effect.void));
455 yield* waitUntilGone(getByName(output.name), output.name);
456 }),
457 });