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

main
ts 318 lines 10.6 KB
Raw
1 import * as datalineage from "@distilled.cloud/gcp/datalineage_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 * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import { GcpEnvironment } from "../Environment.ts";
9 import type { Providers } from "../Providers.ts";
10 import {
11 createOwnership,
12 desiredAttributes,
13 findOwnedRun,
14 hasAlchemyAttributeMap,
15 listOwnedProcesses,
16 listRuns,
17 normalizeLocation,
18 ownedByAlchemy,
19 parseName,
20 processOf,
21 replaceOnIdentity,
22 sameJson,
23 sameText,
24 toPhysicalId,
25 userAttributes,
26 waitForOperation,
27 waitUntilGone,
28 } from "./internal.ts";
29
30 export type ProcessesRunProps = {
31 /**
32 * Parent process. Full name
33 * `projects/{project}/locations/{location}/processes/{process}` or the
34 * process id (combined with `location`). Immutable — changing it
35 * replaces the run.
36 */
37 process: string;
38 /**
39 * Run id (the `{run}` segment of
40 * `.../processes/{process}/runs/{run}`). If omitted, a unique name is
41 * generated. Max 200 characters: letters, digits, underscores, hyphens,
42 * colons, periods. Immutable — changing it replaces the run.
43 */
44 runId?: string;
45 /**
46 * Region used when `process` is a bare id.
47 * @default the stack's GCP region (`GCP.Region`, profile region, `us-central1`)
48 */
49 location?: string;
50 /**
51 * RFC3339 start time. Required by the API; Alchemy reuses the observed
52 * value on updates when omitted.
53 */
54 startTime?: string;
55 /**
56 * RFC3339 end time.
57 */
58 endTime?: string;
59 /**
60 * Run state.
61 * @default "STARTED"
62 */
63 state?: datalineage.GoogleCloudDatacatalogLineageV1RunStateEnum | (string & {});
64 /**
65 * Human-readable name shown in UIs. Max 200 characters.
66 */
67 displayName?: string;
68 /**
69 * Non-semantic attributes. Runs have no labels field, so Alchemy stamps
70 * `alchemy-stack` / `alchemy-stage` / `alchemy-id` here for `list` /
71 * nuke and strips them from attributes.
72 */
73 attributes?: Record<string, unknown>;
74 };
75
76 export type ProcessesRun = Resource<
77 "GCP.DataLineage.ProcessesRun",
78 ProcessesRunProps,
79 {
80 /** Full resource name `.../processes/{process}/runs/{run}`. */
81 name: string;
82 /** Run id (last path segment). */
83 runId: string;
84 /** Parent process resource name. */
85 process: string;
86 /** Project id. */
87 project: string;
88 /** Location id. */
89 location: string;
90 /** RFC3339 start time. */
91 startTime: string | undefined;
92 /** RFC3339 end time. */
93 endTime: string | undefined;
94 /** Run state (`STARTED`, `COMPLETED`, …). */
95 state: string | undefined;
96 /** Human-readable display name. */
97 displayName: string | undefined;
98 /** User attributes (Alchemy ownership keys stripped). */
99 attributes: Record<string, unknown>;
100 },
101 never,
102 Providers
103 >;
104
105 /**
106 * A Data Lineage run — one execution of a process that produces lineage
107 * events.
108 *
109 * Runs have no labels field, so Alchemy stamps ownership into
110 * `attributes` for `list` / nuke. Parent process, `runId`, and location
111 * are identity. State, timestamps, display name, and attributes update
112 * in place.
113 *
114 * ### Creating a Run
115 * **Example:** Started run under a process
116 * ```typescript
117 * const run = yield* GCP.DataLineage.ProcessesRun("Nightly", {
118 * process: process.name,
119 * startTime: "2024-01-01T00:00:00Z",
120 * state: "STARTED",
121 * attributes: { env: "dev" },
122 * });
123 * ```
124 *
125 * **Example:** Completed run
126 * ```typescript
127 * const run = yield* GCP.DataLineage.ProcessesRun("Nightly", {
128 * process: process.name,
129 * startTime: "2024-01-01T00:00:00Z",
130 * endTime: "2024-01-01T01:00:00Z",
131 * state: "COMPLETED",
132 * displayName: "nightly 2024-01-01",
133 * });
134 * ```
135 *
136 * @resource
137 * @category DataLineage
138 */
139 export const ProcessesRun = Resource<ProcessesRun>("GCP.DataLineage.ProcessesRun");
140
141 /** Alias matching the Data Lineage resource name. */
142 export const Run = ProcessesRun;
143 export type Run = ProcessesRun;
144
145 export class ProcessesRunNotResolved extends Data.TaggedError(
146 "GCP.DataLineage.ProcessesRunNotResolved",
147 )<{
148 resourceName: string;
149 }> {}
150
151 const resourceName = (process: string, runId: string) => `${process}/runs/${runId}`;
152
153 const nowIso = () => Effect.sync(() => new Date().toISOString());
154
155 const toAttrs = (
156 run: datalineage.GoogleCloudDatacatalogLineageV1Run,
157 project: string,
158 region: string,
159 ) => {
160 const name = run.name ?? "";
161 const parsed = parseName(name, "runs", region);
162 return {
163 name,
164 runId: parsed.id,
165 process: parsed.parent,
166 project: parsed.project || project,
167 location: parsed.location,
168 startTime: run.startTime,
169 endTime: run.endTime,
170 state: run.state,
171 displayName: run.displayName,
172 attributes: userAttributes(run.attributes),
173 };
174 };
175
176 const getByName = (name: string) =>
177 name.length === 0
178 ? Effect.undefined
179 : datalineage
180 .getProjectsLocationsProcessesRuns({ name })
181 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
182
183 export const ProcessesRunProvider = () =>
184 Provider.succeed(ProcessesRun, {
185 stables: ["name", "runId", "process", "project", "location"],
186
187 diff: Effect.fn(function* ({ news, olds, output }) {
188 if (!isResolved(news)) return undefined;
189 const env = yield* GcpEnvironment.current;
190 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
191 const nextLocation = normalizeLocation(
192 news.location ?? olds?.location ?? output?.location,
193 env.region,
194 );
195 const previousProcess = olds?.process ?? output?.process;
196 return replaceOnIdentity({
197 previousId: olds?.runId ?? output?.runId,
198 nextId: news.runId,
199 previousParent: previousProcess,
200 nextParent: news.process,
201 extra: output !== undefined && previousLocation !== nextLocation,
202 });
203 }),
204
205 read: Effect.fn(function* ({ id, olds, output }) {
206 const env = yield* GcpEnvironment.current;
207 const parentRef = olds?.process ?? output?.process;
208 // A recovery read of an interrupted create gets persisted props whose
209 // unresolved parent reference was stripped; without the parent there
210 // is no name to look up, so report nothing found rather than calling
211 // the API with an empty path segment.
212 if (output?.name === undefined && (typeof parentRef !== "string" || parentRef.length === 0)) {
213 return undefined;
214 }
215 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
216 const process = processOf(olds?.process ?? output?.process ?? "", env.project, location);
217 const runId = yield* toPhysicalId(id, olds?.runId, output?.runId);
218 const name = output?.name ?? resourceName(process, runId);
219 const existing = (yield* getByName(name)) ?? (yield* findOwnedRun(id, process));
220 if (existing === undefined) return undefined;
221 const attrs = toAttrs(existing, env.project, env.region);
222 return (yield* ownedByAlchemy(id, existing.attributes)) ? attrs : Unowned(attrs);
223 }),
224
225 list: () =>
226 Effect.gen(function* () {
227 const env = yield* GcpEnvironment.current;
228 const processes = yield* listOwnedProcesses(env.project, env.region);
229 const groups = yield* Effect.forEach(processes, (process) => listRuns(process.name ?? ""), {
230 concurrency: 4,
231 });
232 return groups
233 .flat()
234 .filter((run) => hasAlchemyAttributeMap(run.attributes))
235 .map((run) => toAttrs(run, env.project, env.region));
236 }),
237
238 reconcile: Effect.fn(function* ({ id, news, output }) {
239 const env = yield* GcpEnvironment.current;
240 const location = normalizeLocation(news.location ?? output?.location, env.region);
241 const process = processOf(news.process, env.project, location);
242 const runId = yield* toPhysicalId(id, news.runId, output?.runId);
243 const name = output?.name ?? resourceName(process, runId);
244 const ownership = yield* createOwnership(id);
245 const attributes = desiredAttributes(news.attributes, ownership);
246
247 let current = (yield* getByName(name)) ?? (yield* findOwnedRun(id, process));
248
249 if (current === undefined) {
250 const startTime = news.startTime ?? (yield* nowIso());
251 const created = yield* datalineage
252 .createProjectsLocationsProcessesRuns({
253 parent: process,
254 body: {
255 name,
256 startTime,
257 endTime: news.endTime,
258 state: news.state ?? "STARTED",
259 displayName: news.displayName,
260 attributes,
261 },
262 })
263 .pipe(
264 Effect.catchTag("Conflict", () =>
265 getByName(name).pipe(
266 Effect.flatMap((row) => (row ? Effect.succeed(row) : findOwnedRun(id, process))),
267 ),
268 ),
269 );
270 current = created ?? undefined;
271 }
272
273 if (current === undefined) {
274 return yield* new ProcessesRunNotResolved({ resourceName: name });
275 }
276
277 const resolvedName = current.name ?? name;
278 const startTime = news.startTime ?? current.startTime ?? (yield* nowIso());
279 const endTime = news.endTime ?? current.endTime;
280 const state = news.state ?? current.state ?? "STARTED";
281 const displayName = news.displayName ?? current.displayName;
282 const startChanged = !sameText(current.startTime, startTime);
283 const endChanged = !sameText(current.endTime, endTime);
284 const stateChanged = !sameText(current.state, state);
285 const displayNameChanged = !sameText(current.displayName, displayName);
286 const attributesChanged = !sameJson(current.attributes, attributes);
287
288 if (startChanged || endChanged || stateChanged || displayNameChanged || attributesChanged) {
289 current = yield* datalineage.patchProjectsLocationsProcessesRuns({
290 name: resolvedName,
291 body: {
292 name: resolvedName,
293 startTime,
294 endTime,
295 state,
296 displayName,
297 attributes,
298 },
299 });
300 }
301
302 return toAttrs(current, env.project, env.region);
303 }),
304
305 delete: Effect.fn(function* ({ output }) {
306 if (!output.name) return;
307 const operation = yield* datalineage
308 .deleteProjectsLocationsProcessesRuns({
309 name: output.name,
310 allowMissing: true,
311 })
312 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
313 if (operation !== undefined) {
314 yield* waitForOperation(operation, { notFoundOk: true });
315 }
316 yield* waitUntilGone(getByName(output.name), output.name);
317 }),
318 });