sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ NetApp/ VolumesReplication.ts

import * as netapp from "@distilled.cloud/gcp/netapp_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import { createInternalLabels, diffLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  fieldMask,
  fingerprint,
  listAtNested,
  listLabeledPages,
  normalizeLocation,
  parseName,
  replaceOnIdentity,
  ResourceNotReady,
  ResourceNotResolved,
  storagePoolOf,
  toPhysicalId,
  userLabels,
  volumeOf,
  waitForDeleteOperation,
  waitForOperation,
  waitUntilExists,
  waitUntilGone,
  waitUntilReady,
} from "./internal.ts";

const DEFAULT_SCHEDULE = "HOURLY";
const STOPPED = "STOPPED";
const ENABLED_MIRROR_STATES = new Set([
  "PREPARING",
  "MIRRORED",
  "TRANSFERRING",
  "BASELINE_TRANSFERRING",
  "PENDING_PEERING",
]);

export type ReplicationTieringPolicy = {
  /**
   * Enable or pause auto-tiering on the destination volume.
   * @default "PAUSED"
   */
  tierAction?: netapp.TieringPolicyTierActionEnum | (string & {});
  /**
   * Days before data is eligible for tiering (2-183).
   * @default 31
   */
  coolingThresholdDays?: number;
  /**
   * Hot-tier bypass for Flex service level.
   * @default false
   */
  hotTierBypassModeEnabled?: boolean;
};

export type DestinationVolumeParameters = {
  /**
   * Destination storage pool. Full name
   * `projects/{project}/locations/{location}/storagePools/{pool}`
   * recommended (destination pools are usually in another region). A
   * bare id is expanded in the source volume location.
   */
  storagePool: string;
  /**
   * Share name of the destination volume. Defaults to the source share
   * name.
   */
  shareName?: string;
  /**
   * Description of the destination volume.
   */
  description?: string;
  /**
   * Destination volume id. Defaults to the source volume id.
   */
  volumeId?: string;
  /**
   * Auto-tiering policy for the destination volume. Requires auto-tiering
   * on the destination pool.
   */
  tieringPolicy?: ReplicationTieringPolicy;
};

export type VolumesReplicationProps = {
  /**
   * Source volume. Full name
   * `projects/{project}/locations/{location}/volumes/{volume}` or the
   * volume id (combined with `location`). Immutable — changing it
   * replaces the replication.
   */
  volume: string;
  /**
   * Region used when `volume` is a bare id. Immutable — changing it
   * replaces the replication. `US-CENTRAL1` is accepted and normalized
   * to `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, profile region, `us-central1`)
   */
  location?: string;
  /**
   * Replication id (the `{replication}` segment of
   * `.../volumes/{volume}/replications/{replication}`). If omitted, a
   * unique RFC1035 name is generated from the stack, stage, and logical
   * id. Immutable — changing it replaces the replication.
   */
  replicationId?: string;
  /**
   * Replication interval.
   * @default "HOURLY"
   */
  replicationSchedule?: netapp.ReplicationReplicationScheduleEnum | (string & {});
  /**
   * Destination volume parameters. Input-only on create. Changing
   * `storagePool`, `volumeId`, or `shareName` replaces the replication.
   */
  destinationVolumeParameters: DestinationVolumeParameters;
  /**
   * Human-readable description.
   */
  description?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
  /**
   * On-prem cluster location for hybrid replication.
   */
  clusterLocation?: string;
  /**
   * Whether the mirror is running. `false` force-stops the relationship
   * so the destination volume becomes read-write. Resuming overwrites
   * destination changes with the source.
   * @default true
   */
  replicationEnabled?: boolean;
  /**
   * Force-stop while a transfer is in progress. Required to delete a
   * replication that is still PREPARING or TRANSFERRING.
   * @default true
   */
  forceStopping?: boolean;
  /**
   * Delete the destination volume when this replication is destroyed.
   * The destination volume is created as a side effect and is otherwise
   * left behind.
   * @default false
   */
  deleteDestinationVolume?: boolean;
  /**
   * Wait until `mirrorState` is MIRRORED (or STOPPED when disabling).
   * Baseline transfers can take hours — leave false unless the volume
   * is empty.
   * @default false
   */
  waitForMirror?: boolean;
};

export type VolumesReplication = Resource<
  "GCP.NetApp.VolumesReplication",
  VolumesReplicationProps,
  {
    /** Full resource name. */
    name: string;
    /** Replication id (last path segment). */
    replicationId: string;
    /** Source volume resource name. */
    volume: string;
    /** Project id. */
    project: string;
    /** Location id of the source volume. */
    location: string;
    /** Human-readable description. */
    description: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Replication interval. */
    replicationSchedule: string | undefined;
    /** On-prem cluster location, if set. */
    clusterLocation: string | undefined;
    /** Destination volume resource name. */
    destinationVolume: string | undefined;
    /** Source volume resource name reported by the API. */
    sourceVolume: string | undefined;
    /** SOURCE or DESTINATION. */
    role: string | undefined;
    /** Mirror state (PREPARING, MIRRORED, STOPPED, …). */
    mirrorState: string | undefined;
    /** Resource state (CREATING, READY, …). */
    state: string | undefined;
    /** Server-reported state details. */
    stateDetails: string | undefined;
    /** Whether the most recent scheduled transfer succeeded. */
    healthy: boolean | undefined;
    /** Hybrid replication type, if this is a hybrid relationship. */
    hybridReplicationType: string | undefined;
    /** Whether the mirror is currently running. */
    replicationEnabled: boolean;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud NetApp Volumes cross-region replication. Creating it also
 * creates a destination volume in the destination pool.
 *
 * Changing `replicationId`, `volume`, `location`, or destination
 * identity (`storagePool` / `volumeId` / `shareName`) replaces the
 * replication. Schedule, description, labels, `clusterLocation`, and
 * `replicationEnabled` update in place.
 *
 * ### Creating a Replication
 * **Example:** Hourly mirror into another region
 * ```typescript
 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
 *   volume: sourceVolume.name,
 *   replicationSchedule: "HOURLY",
 *   destinationVolumeParameters: {
 *     storagePool: destPool.name,
 *     volumeId: "app-dr",
 *     shareName: "app",
 *   },
 *   labels: { env: "prod" },
 * });
 * ```
 *
 * **Example:** Ten-minute schedule with description
 * ```typescript
 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
 *   volume: sourceVolume.name,
 *   replicationSchedule: "EVERY_10_MINUTES",
 *   destinationVolumeParameters: {
 *     storagePool: destPool.name,
 *   },
 *   description: "us-central1 to us-east1",
 * });
 * ```
 *
 * ### Updating a Replication
 * **Example:** Pause the mirror
 * ```typescript
 * const replica = yield* GCP.NetApp.VolumesReplication("Dr", {
 *   volume: sourceVolume.name,
 *   replicationSchedule: "HOURLY",
 *   destinationVolumeParameters: {
 *     storagePool: destPool.name,
 *   },
 *   replicationEnabled: false,
 * });
 * ```
 *
 * @resource
 * @category NetApp
 */
export const VolumesReplication = Resource<VolumesReplication>("GCP.NetApp.VolumesReplication");

const resourceName = (volume: string, replicationId: string) =>
  `${volume}/replications/${replicationId}`;

const desiredSchedule = (value: string | undefined) => (value ?? DEFAULT_SCHEDULE).toUpperCase();

const destFingerprint = (params: DestinationVolumeParameters | undefined) =>
  fingerprint({
    storagePool: params?.storagePool,
    volumeId: params?.volumeId,
    shareName: params?.shareName,
  });

const isMirrorRunning = (mirrorState: string | undefined) =>
  ENABLED_MIRROR_STATES.has((mirrorState ?? "").toUpperCase());

const toAttrs = (replication: netapp.Replication, project: string, region: string) => {
  const name = replication.name ?? "";
  const parsed = parseName(name, "replications", region);
  return {
    name,
    replicationId: parsed.id,
    volume: parsed.parent,
    project: parsed.project || project,
    location: parsed.location,
    description: replication.description,
    labels: userLabels(replication.labels),
    replicationSchedule: replication.replicationSchedule,
    clusterLocation: replication.clusterLocation,
    destinationVolume: replication.destinationVolume,
    sourceVolume: replication.sourceVolume,
    role: replication.role,
    mirrorState: replication.mirrorState,
    state: replication.state,
    stateDetails: replication.stateDetails,
    healthy: replication.healthy,
    hybridReplicationType: replication.hybridReplicationType,
    replicationEnabled: isMirrorRunning(replication.mirrorState),
    createTime: replication.createTime,
  };
};

const destBody = (
  params: DestinationVolumeParameters,
  project: string,
  location: string,
): netapp.DestinationVolumeParameters => ({
  storagePool: storagePoolOf(params.storagePool, project, location),
  shareName: params.shareName,
  description: params.description,
  volumeId: params.volumeId,
  tieringPolicy: params.tieringPolicy,
});

const getByName = (name: string) =>
  name.length === 0 || name.includes("//")
    ? Effect.undefined
    : netapp
        .getProjectsLocationsVolumesReplications({ name })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listOwned = (project: string) =>
  listAtNested(project, "volumes/-", (parent) =>
    listLabeledPages(
      netapp.listProjectsLocationsVolumesReplications.pages({
        parent,
        pageSize: 1000,
      }),
      (page) => page.replications,
      (item) => item.labels,
    ),
  );

const waitUntilMirror = (name: string, enabled: boolean) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (value): value is netapp.Replication => value !== undefined,
      () => new ResourceNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (value) => {
        const mirror = (value.mirrorState ?? "").toUpperCase();
        return enabled
          ? mirror === "MIRRORED" || mirror === "TRANSFERRING"
          : mirror === STOPPED || mirror === "ABORTED";
      },
      (value) => new ResourceNotReady({ resourceName: name, state: value.mirrorState ?? "" }),
    ),
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.NetApp.ResourceNotReady" ||
        error._tag === "GCP.NetApp.ResourceNotResolved",
      times: 120,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

export const VolumesReplicationProvider = () =>
  Provider.succeed(VolumesReplication, {
    stables: ["name", "replicationId", "volume", "project", "location", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(
        news.location ?? olds?.location ?? output?.location,
        env.region,
      );
      const previousVolume = volumeOf(
        olds?.volume ?? output?.volume ?? "",
        env.project,
        previousLocation,
      );
      const nextVolume = volumeOf(
        news.volume ?? olds?.volume ?? output?.volume ?? "",
        env.project,
        nextLocation,
      );
      const destChanged =
        olds?.destinationVolumeParameters !== undefined &&
        destFingerprint(news.destinationVolumeParameters) !==
          destFingerprint(olds.destinationVolumeParameters);
      return replaceOnIdentity({
        previousId: olds?.replicationId ?? output?.replicationId,
        nextId: news.replicationId ?? olds?.replicationId ?? output?.replicationId,
        previousLocation,
        nextLocation,
        previousParent: previousVolume,
        nextParent: nextVolume,
        extra: destChanged,
      });
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(olds?.location ?? output?.location, env.region);
      const volume = volumeOf(olds?.volume ?? output?.volume ?? "", env.project, location);
      const replicationId = yield* toPhysicalId(
        id,
        olds?.replicationId,
        output?.replicationId,
        "replication",
      );
      const name = output?.name ?? resourceName(volume, replicationId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project, env.region);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const items = yield* listOwned(env.project);
        return items.map((item) => toAttrs(item, env.project, env.region));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const locationHint = normalizeLocation(news.location ?? output?.location, env.region);
      const volume = volumeOf(news.volume, env.project, locationHint);
      const location = parseName(volume, "volumes", locationHint).location;
      const replicationId = yield* toPhysicalId(
        id,
        news.replicationId,
        output?.replicationId,
        "replication",
      );
      const name = output?.name ?? resourceName(volume, replicationId);
      const schedule = desiredSchedule(news.replicationSchedule);
      const enabled = news.replicationEnabled ?? true;
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };

      let current = yield* getByName(output?.name ?? name);

      if (current === undefined) {
        const created = yield* netapp
          .createProjectsLocationsVolumesReplications({
            parent: volume,
            replicationId,
            body: {
              description: news.description,
              labels: desiredLabels,
              replicationSchedule: schedule,
              destinationVolumeParameters: destBody(
                news.destinationVolumeParameters,
                env.project,
                location,
              ),
              clusterLocation: news.clusterLocation,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* waitUntilExists(getByName(name), name);
      }

      if (current === undefined) {
        return yield* new ResourceNotResolved({ resourceName: name });
      }

      current = yield* waitUntilReady(
        getByName(current.name ?? name),
        current.name ?? name,
        (item) => item.state,
        (item) => item.stateDetails,
        { times: 120, interval: "5 seconds" },
      );

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
      const scheduleChanged = desiredSchedule(current.replicationSchedule) !== schedule;
      const clusterChanged = (current.clusterLocation ?? "") !== (news.clusterLocation ?? "");
      const mask = fieldMask([
        labelsChanged && "labels",
        descriptionChanged && "description",
        scheduleChanged && "replicationSchedule",
        clusterChanged && "clusterLocation",
      ]);

      if (mask.length > 0) {
        const operation = yield* netapp.patchProjectsLocationsVolumesReplications({
          name: current.name ?? name,
          updateMask: mask,
          body: {
            name: current.name ?? name,
            labels: desiredLabels,
            description: news.description,
            replicationSchedule: schedule,
            clusterLocation: news.clusterLocation,
          },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilReady(
          getByName(current.name ?? name),
          current.name ?? name,
          (item) => item.state,
          (item) => item.stateDetails,
          { times: 120, interval: "5 seconds" },
        );
      }

      const running = isMirrorRunning(current.mirrorState);
      if (enabled && !running) {
        const resumed = yield* netapp
          .resumeProjectsLocationsVolumesReplications({
            name: current.name ?? name,
            body: {},
          })
          .pipe(Effect.catchTag(["Conflict", "BadRequest"], () => Effect.undefined));
        if (resumed !== undefined) {
          yield* waitForOperation(resumed);
        }
        current = yield* waitUntilReady(
          getByName(current.name ?? name),
          current.name ?? name,
          (item) => item.state,
          (item) => item.stateDetails,
          { times: 120, interval: "5 seconds" },
        );
      } else if (!enabled && running) {
        const stopped = yield* netapp
          .stopProjectsLocationsVolumesReplications({
            name: current.name ?? name,
            body: { force: news.forceStopping ?? true },
          })
          .pipe(Effect.catchTag(["Conflict", "BadRequest"], () => Effect.undefined));
        if (stopped !== undefined) {
          yield* waitForOperation(stopped);
        }
        current = yield* waitUntilReady(
          getByName(current.name ?? name),
          current.name ?? name,
          (item) => item.state,
          (item) => item.stateDetails,
          { times: 120, interval: "5 seconds" },
        );
      }

      if (news.waitForMirror === true) {
        current = yield* waitUntilMirror(current.name ?? name, enabled);
      }

      return toAttrs(current, env.project, env.region);
    }),

    delete: Effect.fn(function* ({ olds, output }) {
      if (!output.name || output.name.includes("//")) return;
      const current = yield* getByName(output.name);
      if (current !== undefined && (current.mirrorState ?? "").toUpperCase() !== STOPPED) {
        const stopped = yield* netapp
          .stopProjectsLocationsVolumesReplications({
            name: output.name,
            body: { force: olds?.forceStopping ?? true },
          })
          .pipe(Effect.catchTag(["NotFound", "Conflict", "BadRequest"], () => Effect.undefined));
        if (stopped !== undefined) {
          yield* waitForDeleteOperation(stopped);
        }
      }

      const operation = yield* netapp
        .deleteProjectsLocationsVolumesReplications({ name: output.name })
        .pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("2 seconds"),
          }),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      if (operation !== undefined) {
        yield* waitForDeleteOperation(operation);
      }
      yield* waitUntilGone(getByName(output.name), output.name);

      const destination = output.destinationVolume ?? current?.destinationVolume;
      if (olds?.deleteDestinationVolume === true && destination) {
        const deleted = yield* netapp
          .deleteProjectsLocationsVolumes({
            name: destination,
            force: true,
          })
          .pipe(Effect.catchTag(["NotFound", "Conflict", "BadRequest"], () => Effect.undefined));
        if (deleted !== undefined) {
          yield* waitForDeleteOperation(deleted);
        }
      }
    }),
  });