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

main
ts 599 lines 19.9 KB
Raw
1 import * as netapp from "@distilled.cloud/gcp/netapp_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 Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
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 fieldMask,
14 fingerprint,
15 listAtNested,
16 listLabeledPages,
17 normalizeLocation,
18 parseName,
19 replaceOnIdentity,
20 ResourceNotReady,
21 ResourceNotResolved,
22 storagePoolOf,
23 toPhysicalId,
24 userLabels,
25 volumeOf,
26 waitForDeleteOperation,
27 waitForOperation,
28 waitUntilExists,
29 waitUntilGone,
30 waitUntilReady,
31 } from "./internal.ts";
32
33 const DEFAULT_SCHEDULE = "HOURLY";
34 const STOPPED = "STOPPED";
35 const ENABLED_MIRROR_STATES = new Set([
36 "PREPARING",
37 "MIRRORED",
38 "TRANSFERRING",
39 "BASELINE_TRANSFERRING",
40 "PENDING_PEERING",
41 ]);
42
43 export type ReplicationTieringPolicy = {
44 /**
45 * Enable or pause auto-tiering on the destination volume.
46 * @default "PAUSED"
47 */
48 tierAction?: netapp.TieringPolicyTierActionEnum | (string & {});
49 /**
50 * Days before data is eligible for tiering (2-183).
51 * @default 31
52 */
53 coolingThresholdDays?: number;
54 /**
55 * Hot-tier bypass for Flex service level.
56 * @default false
57 */
58 hotTierBypassModeEnabled?: boolean;
59 };
60
61 export type DestinationVolumeParameters = {
62 /**
63 * Destination storage pool. Full name
64 * `projects/{project}/locations/{location}/storagePools/{pool}`
65 * recommended (destination pools are usually in another region). A
66 * bare id is expanded in the source volume location.
67 */
68 storagePool: string;
69 /**
70 * Share name of the destination volume. Defaults to the source share
71 * name.
72 */
73 shareName?: string;
74 /**
75 * Description of the destination volume.
76 */
77 description?: string;
78 /**
79 * Destination volume id. Defaults to the source volume id.
80 */
81 volumeId?: string;
82 /**
83 * Auto-tiering policy for the destination volume. Requires auto-tiering
84 * on the destination pool.
85 */
86 tieringPolicy?: ReplicationTieringPolicy;
87 };
88
89 export type VolumesReplicationProps = {
90 /**
91 * Source volume. Full name
92 * `projects/{project}/locations/{location}/volumes/{volume}` or the
93 * volume id (combined with `location`). Immutable — changing it
94 * replaces the replication.
95 */
96 volume: string;
97 /**
98 * Region used when `volume` is a bare id. Immutable — changing it
99 * replaces the replication. `US-CENTRAL1` is accepted and normalized
100 * to `us-central1`.
101 * @default the stack's GCP region (`GCP.Region`, profile region, `us-central1`)
102 */
103 location?: string;
104 /**
105 * Replication id (the `{replication}` segment of
106 * `.../volumes/{volume}/replications/{replication}`). If omitted, a
107 * unique RFC1035 name is generated from the stack, stage, and logical
108 * id. Immutable — changing it replaces the replication.
109 */
110 replicationId?: string;
111 /**
112 * Replication interval.
113 * @default "HOURLY"
114 */
115 replicationSchedule?: netapp.ReplicationReplicationScheduleEnum | (string & {});
116 /**
117 * Destination volume parameters. Input-only on create. Changing
118 * `storagePool`, `volumeId`, or `shareName` replaces the replication.
119 */
120 destinationVolumeParameters: DestinationVolumeParameters;
121 /**
122 * Human-readable description.
123 */
124 description?: string;
125 /**
126 * User labels. Alchemy ownership labels are merged in automatically.
127 */
128 labels?: Record<string, string>;
129 /**
130 * On-prem cluster location for hybrid replication.
131 */
132 clusterLocation?: string;
133 /**
134 * Whether the mirror is running. `false` force-stops the relationship
135 * so the destination volume becomes read-write. Resuming overwrites
136 * destination changes with the source.
137 * @default true
138 */
139 replicationEnabled?: boolean;
140 /**
141 * Force-stop while a transfer is in progress. Required to delete a
142 * replication that is still PREPARING or TRANSFERRING.
143 * @default true
144 */
145 forceStopping?: boolean;
146 /**
147 * Delete the destination volume when this replication is destroyed.
148 * The destination volume is created as a side effect and is otherwise
149 * left behind.
150 * @default false
151 */
152 deleteDestinationVolume?: boolean;
153 /**
154 * Wait until `mirrorState` is MIRRORED (or STOPPED when disabling).
155 * Baseline transfers can take hours — leave false unless the volume
156 * is empty.
157 * @default false
158 */
159 waitForMirror?: boolean;
160 };
161
162 export type VolumesReplication = Resource<
163 "GCP.NetApp.VolumesReplication",
164 VolumesReplicationProps,
165 {
166 /** Full resource name. */
167 name: string;
168 /** Replication id (last path segment). */
169 replicationId: string;
170 /** Source volume resource name. */
171 volume: string;
172 /** Project id. */
173 project: string;
174 /** Location id of the source volume. */
175 location: string;
176 /** Human-readable description. */
177 description: string | undefined;
178 /** User labels (Alchemy ownership labels stripped). */
179 labels: Record<string, string>;
180 /** Replication interval. */
181 replicationSchedule: string | undefined;
182 /** On-prem cluster location, if set. */
183 clusterLocation: string | undefined;
184 /** Destination volume resource name. */
185 destinationVolume: string | undefined;
186 /** Source volume resource name reported by the API. */
187 sourceVolume: string | undefined;
188 /** SOURCE or DESTINATION. */
189 role: string | undefined;
190 /** Mirror state (PREPARING, MIRRORED, STOPPED, …). */
191 mirrorState: string | undefined;
192 /** Resource state (CREATING, READY, …). */
193 state: string | undefined;
194 /** Server-reported state details. */
195 stateDetails: string | undefined;
196 /** Whether the most recent scheduled transfer succeeded. */
197 healthy: boolean | undefined;
198 /** Hybrid replication type, if this is a hybrid relationship. */
199 hybridReplicationType: string | undefined;
200 /** Whether the mirror is currently running. */
201 replicationEnabled: boolean;
202 /** RFC3339 creation timestamp. */
203 createTime: string | undefined;
204 },
205 never,
206 Providers
207 >;
208
209 /**
210 * A Cloud NetApp Volumes cross-region replication. Creating it also
211 * creates a destination volume in the destination pool.
212 *
213 * Changing `replicationId`, `volume`, `location`, or destination
214 * identity (`storagePool` / `volumeId` / `shareName`) replaces the
215 * replication. Schedule, description, labels, `clusterLocation`, and
216 * `replicationEnabled` update in place.
217 *
218 * ### Creating a Replication
219 * **Example:** Hourly mirror into another region
220 * ```typescript
221 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
222 * volume: sourceVolume.name,
223 * replicationSchedule: "HOURLY",
224 * destinationVolumeParameters: {
225 * storagePool: destPool.name,
226 * volumeId: "app-dr",
227 * shareName: "app",
228 * },
229 * labels: { env: "prod" },
230 * });
231 * ```
232 *
233 * **Example:** Ten-minute schedule with description
234 * ```typescript
235 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
236 * volume: sourceVolume.name,
237 * replicationSchedule: "EVERY_10_MINUTES",
238 * destinationVolumeParameters: {
239 * storagePool: destPool.name,
240 * },
241 * description: "us-central1 to us-east1",
242 * });
243 * ```
244 *
245 * ### Updating a Replication
246 * **Example:** Pause the mirror
247 * ```typescript
248 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
249 * volume: sourceVolume.name,
250 * replicationSchedule: "HOURLY",
251 * destinationVolumeParameters: {
252 * storagePool: destPool.name,
253 * },
254 * replicationEnabled: false,
255 * });
256 * ```
257 *
258 * @resource
259 * @category NetApp
260 */
261 export const VolumesReplication = Resource<VolumesReplication>("GCP.NetApp.VolumesReplication");
262
263 const resourceName = (volume: string, replicationId: string) =>
264 `${volume}/replications/${replicationId}`;
265
266 const desiredSchedule = (value: string | undefined) => (value ?? DEFAULT_SCHEDULE).toUpperCase();
267
268 const destFingerprint = (params: DestinationVolumeParameters | undefined) =>
269 fingerprint({
270 storagePool: params?.storagePool,
271 volumeId: params?.volumeId,
272 shareName: params?.shareName,
273 });
274
275 const isMirrorRunning = (mirrorState: string | undefined) =>
276 ENABLED_MIRROR_STATES.has((mirrorState ?? "").toUpperCase());
277
278 const toAttrs = (replication: netapp.Replication, project: string, region: string) => {
279 const name = replication.name ?? "";
280 const parsed = parseName(name, "replications", region);
281 return {
282 name,
283 replicationId: parsed.id,
284 volume: parsed.parent,
285 project: parsed.project || project,
286 location: parsed.location,
287 description: replication.description,
288 labels: userLabels(replication.labels),
289 replicationSchedule: replication.replicationSchedule,
290 clusterLocation: replication.clusterLocation,
291 destinationVolume: replication.destinationVolume,
292 sourceVolume: replication.sourceVolume,
293 role: replication.role,
294 mirrorState: replication.mirrorState,
295 state: replication.state,
296 stateDetails: replication.stateDetails,
297 healthy: replication.healthy,
298 hybridReplicationType: replication.hybridReplicationType,
299 replicationEnabled: isMirrorRunning(replication.mirrorState),
300 createTime: replication.createTime,
301 };
302 };
303
304 const destBody = (
305 params: DestinationVolumeParameters,
306 project: string,
307 location: string,
308 ): netapp.DestinationVolumeParameters => ({
309 storagePool: storagePoolOf(params.storagePool, project, location),
310 shareName: params.shareName,
311 description: params.description,
312 volumeId: params.volumeId,
313 tieringPolicy: params.tieringPolicy,
314 });
315
316 const getByName = (name: string) =>
317 name.length === 0 || name.includes("//")
318 ? Effect.undefined
319 : netapp
320 .getProjectsLocationsVolumesReplications({ name })
321 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
322
323 const listOwned = (project: string) =>
324 listAtNested(project, "volumes/-", (parent) =>
325 listLabeledPages(
326 netapp.listProjectsLocationsVolumesReplications.pages({
327 parent,
328 pageSize: 1000,
329 }),
330 (page) => page.replications,
331 (item) => item.labels,
332 ),
333 );
334
335 const waitUntilMirror = (name: string, enabled: boolean) =>
336 getByName(name).pipe(
337 Effect.filterOrFail(
338 (value): value is netapp.Replication => value !== undefined,
339 () => new ResourceNotResolved({ resourceName: name }),
340 ),
341 Effect.filterOrFail(
342 (value) => {
343 const mirror = (value.mirrorState ?? "").toUpperCase();
344 return enabled
345 ? mirror === "MIRRORED" || mirror === "TRANSFERRING"
346 : mirror === STOPPED || mirror === "ABORTED";
347 },
348 (value) => new ResourceNotReady({ resourceName: name, state: value.mirrorState ?? "" }),
349 ),
350 Effect.retry({
351 while: (error) =>
352 error._tag === "GCP.NetApp.ResourceNotReady" ||
353 error._tag === "GCP.NetApp.ResourceNotResolved",
354 times: 120,
355 schedule: Schedule.spaced("5 seconds"),
356 }),
357 );
358
359 export const VolumesReplicationProvider = () =>
360 Provider.succeed(VolumesReplication, {
361 stables: ["name", "replicationId", "volume", "project", "location", "createTime"],
362
363 diff: Effect.fn(function* ({ news, olds, output }) {
364 if (!isResolved(news)) return undefined;
365 const env = yield* GcpEnvironment.current;
366 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
367 const nextLocation = normalizeLocation(
368 news.location ?? olds?.location ?? output?.location,
369 env.region,
370 );
371 const previousVolume = volumeOf(
372 olds?.volume ?? output?.volume ?? "",
373 env.project,
374 previousLocation,
375 );
376 const nextVolume = volumeOf(
377 news.volume ?? olds?.volume ?? output?.volume ?? "",
378 env.project,
379 nextLocation,
380 );
381 const destChanged =
382 olds?.destinationVolumeParameters !== undefined &&
383 destFingerprint(news.destinationVolumeParameters) !==
384 destFingerprint(olds.destinationVolumeParameters);
385 return replaceOnIdentity({
386 previousId: olds?.replicationId ?? output?.replicationId,
387 nextId: news.replicationId ?? olds?.replicationId ?? output?.replicationId,
388 previousLocation,
389 nextLocation,
390 previousParent: previousVolume,
391 nextParent: nextVolume,
392 extra: destChanged,
393 });
394 }),
395
396 read: Effect.fn(function* ({ id, olds, output }) {
397 const env = yield* GcpEnvironment.current;
398 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
399 const volume = volumeOf(olds?.volume ?? output?.volume ?? "", env.project, location);
400 const replicationId = yield* toPhysicalId(
401 id,
402 olds?.replicationId,
403 output?.replicationId,
404 "replication",
405 );
406 const name = output?.name ?? resourceName(volume, replicationId);
407 const existing = yield* getByName(name);
408 if (existing === undefined) return undefined;
409 const attrs = toAttrs(existing, env.project, env.region);
410 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
411 }),
412
413 list: () =>
414 Effect.gen(function* () {
415 const env = yield* GcpEnvironment.current;
416 const items = yield* listOwned(env.project);
417 return items.map((item) => toAttrs(item, env.project, env.region));
418 }),
419
420 reconcile: Effect.fn(function* ({ id, news, output }) {
421 const env = yield* GcpEnvironment.current;
422 const locationHint = normalizeLocation(news.location ?? output?.location, env.region);
423 const volume = volumeOf(news.volume, env.project, locationHint);
424 const location = parseName(volume, "volumes", locationHint).location;
425 const replicationId = yield* toPhysicalId(
426 id,
427 news.replicationId,
428 output?.replicationId,
429 "replication",
430 );
431 const name = output?.name ?? resourceName(volume, replicationId);
432 const schedule = desiredSchedule(news.replicationSchedule);
433 const enabled = news.replicationEnabled ?? true;
434 const desiredLabels = {
435 ...toLabels(news.labels),
436 ...(yield* createInternalLabels(id)),
437 };
438
439 let current = yield* getByName(output?.name ?? name);
440
441 if (current === undefined) {
442 const created = yield* netapp
443 .createProjectsLocationsVolumesReplications({
444 parent: volume,
445 replicationId,
446 body: {
447 description: news.description,
448 labels: desiredLabels,
449 replicationSchedule: schedule,
450 destinationVolumeParameters: destBody(
451 news.destinationVolumeParameters,
452 env.project,
453 location,
454 ),
455 clusterLocation: news.clusterLocation,
456 },
457 })
458 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
459 if (created !== undefined) {
460 yield* waitForOperation(created);
461 }
462 current = yield* waitUntilExists(getByName(name), name);
463 }
464
465 if (current === undefined) {
466 return yield* new ResourceNotResolved({ resourceName: name });
467 }
468
469 current = yield* waitUntilReady(
470 getByName(current.name ?? name),
471 current.name ?? name,
472 (item) => item.state,
473 (item) => item.stateDetails,
474 { times: 120, interval: "5 seconds" },
475 );
476
477 const observedLabels = tagRecord(current.labels);
478 const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
479 const labelsChanged = upsert.length > 0 || removed.length > 0;
480 const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
481 const scheduleChanged = desiredSchedule(current.replicationSchedule) !== schedule;
482 const clusterChanged = (current.clusterLocation ?? "") !== (news.clusterLocation ?? "");
483 const mask = fieldMask([
484 labelsChanged && "labels",
485 descriptionChanged && "description",
486 scheduleChanged && "replicationSchedule",
487 clusterChanged && "clusterLocation",
488 ]);
489
490 if (mask.length > 0) {
491 const operation = yield* netapp.patchProjectsLocationsVolumesReplications({
492 name: current.name ?? name,
493 updateMask: mask,
494 body: {
495 name: current.name ?? name,
496 labels: desiredLabels,
497 description: news.description,
498 replicationSchedule: schedule,
499 clusterLocation: news.clusterLocation,
500 },
501 });
502 yield* waitForOperation(operation);
503 current = yield* waitUntilReady(
504 getByName(current.name ?? name),
505 current.name ?? name,
506 (item) => item.state,
507 (item) => item.stateDetails,
508 { times: 120, interval: "5 seconds" },
509 );
510 }
511
512 const running = isMirrorRunning(current.mirrorState);
513 if (enabled && !running) {
514 const resumed = yield* netapp
515 .resumeProjectsLocationsVolumesReplications({
516 name: current.name ?? name,
517 body: {},
518 })
519 .pipe(Effect.catchTag(["Conflict", "BadRequest"], () => Effect.undefined));
520 if (resumed !== undefined) {
521 yield* waitForOperation(resumed);
522 }
523 current = yield* waitUntilReady(
524 getByName(current.name ?? name),
525 current.name ?? name,
526 (item) => item.state,
527 (item) => item.stateDetails,
528 { times: 120, interval: "5 seconds" },
529 );
530 } else if (!enabled && running) {
531 const stopped = yield* netapp
532 .stopProjectsLocationsVolumesReplications({
533 name: current.name ?? name,
534 body: { force: news.forceStopping ?? true },
535 })
536 .pipe(Effect.catchTag(["Conflict", "BadRequest"], () => Effect.undefined));
537 if (stopped !== undefined) {
538 yield* waitForOperation(stopped);
539 }
540 current = yield* waitUntilReady(
541 getByName(current.name ?? name),
542 current.name ?? name,
543 (item) => item.state,
544 (item) => item.stateDetails,
545 { times: 120, interval: "5 seconds" },
546 );
547 }
548
549 if (news.waitForMirror === true) {
550 current = yield* waitUntilMirror(current.name ?? name, enabled);
551 }
552
553 return toAttrs(current, env.project, env.region);
554 }),
555
556 delete: Effect.fn(function* ({ olds, output }) {
557 if (!output.name || output.name.includes("//")) return;
558 const current = yield* getByName(output.name);
559 if (current !== undefined && (current.mirrorState ?? "").toUpperCase() !== STOPPED) {
560 const stopped = yield* netapp
561 .stopProjectsLocationsVolumesReplications({
562 name: output.name,
563 body: { force: olds?.forceStopping ?? true },
564 })
565 .pipe(Effect.catchTag(["NotFound", "Conflict", "BadRequest"], () => Effect.undefined));
566 if (stopped !== undefined) {
567 yield* waitForDeleteOperation(stopped);
568 }
569 }
570
571 const operation = yield* netapp
572 .deleteProjectsLocationsVolumesReplications({ name: output.name })
573 .pipe(
574 Effect.retry({
575 while: (error) => error._tag === "Conflict",
576 times: 8,
577 schedule: Schedule.spaced("2 seconds"),
578 }),
579 Effect.catchTag("NotFound", () => Effect.undefined),
580 );
581 if (operation !== undefined) {
582 yield* waitForDeleteOperation(operation);
583 }
584 yield* waitUntilGone(getByName(output.name), output.name);
585
586 const destination = output.destinationVolume ?? current?.destinationVolume;
587 if (olds?.deleteDestinationVolume === true && destination) {
588 const deleted = yield* netapp
589 .deleteProjectsLocationsVolumes({
590 name: destination,
591 force: true,
592 })
593 .pipe(Effect.catchTag(["NotFound", "Conflict", "BadRequest"], () => Effect.undefined));
594 if (deleted !== undefined) {
595 yield* waitForDeleteOperation(deleted);
596 }
597 }
598 }),
599 });