sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ AlloyDB/ Backup.ts

import * as alloydb from "@distilled.cloud/gcp/alloydb_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import {
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import type { EncryptionConfig } from "./Cluster.ts";
import { waitForDeleteOperation, waitForOperation } from "./operations.ts";

const DEFAULT_BACKUP_TYPE = "ON_DEMAND";
const MAX_NAME_LENGTH = 63;

export type BackupProps = {
  /**
   * Source cluster id or full resource name
   * (`projects/{project}/locations/{location}/clusters/{cluster}`).
   * Immutable — changing it replaces the backup.
   */
  clusterName: string;
  /**
   * Region of the backup (`us-central1`, …). Ignored when
   * `clusterName` is a full resource name unless set explicitly.
   * Immutable — changing it replaces the backup. `US-CENTRAL1` is
   * accepted and normalized to `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * Backup id (the `{backup}` segment of
   * `projects/{project}/locations/{location}/backups/{backup}`). If
   * omitted, a unique RFC1035 name is generated. Must match
   * `[a-z]([a-z0-9-]{0,61}[a-z0-9])?`. Immutable — changing it
   * replaces the backup.
   */
  backupId?: string;
  /**
   * User-facing display name.
   */
  displayName?: string;
  /**
   * User-provided description. Changing it replaces the backup.
   */
  description?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
  /**
   * Arbitrary client annotations (distinct from labels).
   */
  annotations?: Record<string, string>;
  /**
   * Backup type. User-created backups are `ON_DEMAND`. Immutable.
   * @default "ON_DEMAND"
   */
  type?: alloydb.BackupTypeEnum | (string & {});
  /**
   * Customer-managed encryption. Immutable — changing it replaces the
   * backup.
   */
  encryptionConfig?: EncryptionConfig;
  /**
   * Resource Manager tags bound at create time. Immutable.
   */
  tags?: Record<string, string>;
};

export type Backup = Resource<
  "GCP.AlloyDB.Backup",
  BackupProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/backups/{backup}`. */
    name: string;
    /** Backup id (last path segment). */
    backupId: string;
    /** Source cluster resource name. */
    clusterName: string;
    /** Source cluster id. */
    clusterId: string;
    /** Project id. */
    project: string;
    /** Region id (`us-central1`, …). */
    location: string;
    /** User-facing display name. */
    displayName: string | undefined;
    /** User-provided description. */
    description: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Client annotations. */
    annotations: Record<string, string>;
    /** Serving state (`READY`, `CREATING`, `FAILED`, …). */
    state: string | undefined;
    /** Backup type (`ON_DEMAND`, `AUTOMATED`, `CONTINUOUS`). */
    type: string;
    /** Size in bytes, as a decimal string. */
    sizeBytes: string | undefined;
    /** Customer-managed encryption, if any. */
    encryptionConfig: EncryptionConfig | undefined;
    /** Database engine major version of the source cluster. */
    databaseVersion: string | undefined;
    /** System-generated UID of the source cluster. */
    clusterUid: string | undefined;
    /** System-generated UID of the backup. */
    uid: string | undefined;
    /** Whether the service is reconciling intended vs actual state. */
    reconciling: boolean;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
    /** RFC3339 time when creation finished. */
    createCompletionTime: string | undefined;
    /** RFC3339 time after which the backup may be garbage collected. */
    expiryTime: string | undefined;
    /** HTTP etag. */
    etag: string | undefined;
  },
  never,
  Providers
>;

/**
 * An on-demand AlloyDB backup of a cluster.
 *
 * Changing `backupId`, `location`, `clusterName`, `type`,
 * `encryptionConfig`, `tags`, or `description` replaces the backup.
 * `displayName`, `labels`, and `annotations` update in place.
 *
 * Creating a backup typically takes several minutes and is skipIf-gated
 * in live tests behind `GCP_TEST_ALLOYDB`.
 *
 * ### Creating a Backup
 * **Example:** On-demand backup of a cluster
 * ```typescript
 * const cluster = yield* GCP.AlloyDB.Cluster("AppDb", {
 *   pscConfig: { pscEnabled: true },
 *   automatedBackupPolicy: { enabled: false },
 *   continuousBackupConfig: { enabled: false },
 * });
 * const backup = yield* GCP.AlloyDB.Backup("Nightly", {
 *   clusterName: cluster.name,
 *   displayName: "nightly",
 *   labels: { env: "prod" },
 * });
 * ```
 *
 * **Example:** Explicit id and description
 * ```typescript
 * const backup = yield* GCP.AlloyDB.Backup("Nightly", {
 *   clusterName: cluster.name,
 *   backupId: "app-db-nightly",
 *   displayName: "app-db-nightly",
 *   description: "manual snapshot",
 * });
 * ```
 *
 * @resource
 * @category AlloyDB
 */
export const Backup = Resource<Backup>("GCP.AlloyDB.Backup");

export class BackupNotResolved extends Data.TaggedError("GCP.AlloyDB.BackupNotResolved")<{
  resourceName: string;
}> {}

export class BackupClusterMissing extends Data.TaggedError("GCP.AlloyDB.BackupClusterMissing")<{
  message: string;
}> {}

export class BackupNotReady extends Data.TaggedError("GCP.AlloyDB.BackupNotReady")<{
  resourceName: string;
  state: string;
}> {}

export class BackupFailed extends Data.TaggedError("GCP.AlloyDB.BackupFailed")<{
  resourceName: string;
  state: string;
}> {}

export class BackupStillExists extends Data.TaggedError("GCP.AlloyDB.BackupStillExists")<{
  resourceName: string;
}> {}

const lastSegment = (value: string | undefined) => {
  if (value === undefined || value.length === 0) return "";
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const normalizeLocation = (location: string) => lastSegment(location).toLowerCase();

const normalizeType = (type: string | undefined) => {
  const value = (type ?? DEFAULT_BACKUP_TYPE).toUpperCase();
  return value === "TYPE_UNSPECIFIED" ? DEFAULT_BACKUP_TYPE : value;
};

const rfc1035 = (name: string): string => {
  let next = name
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (!/^[a-z]/.test(next)) next = `b${next}`;
  next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, "");
  if (next.length === 0) return "backup";
  if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, MAX_NAME_LENGTH - 1)}0`;
  return next.slice(0, MAX_NAME_LENGTH);
};

const resourceName = (project: string, location: string, backupId: string) =>
  `projects/${project}/locations/${location}/backups/${backupId}`;

const clusterNameOf = (project: string, location: string, clusterId: string) =>
  `projects/${project}/locations/${location}/clusters/${clusterId}`;

const parseBackupName = (name: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const backupsAt = parts.lastIndexOf("backups");
  const locationsAt = parts.lastIndexOf("locations");
  const projectsAt = parts.lastIndexOf("projects");
  return {
    project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
    location: locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : "",
    backupId: backupsAt >= 0 && parts[backupsAt + 1] ? parts[backupsAt + 1]! : lastSegment(name),
  };
};

const parseClusterRef = (cluster: string, fallbackProject: string, fallbackLocation: string) => {
  const trimmed = cluster.trim();
  if (trimmed.length === 0) {
    return {
      project: fallbackProject,
      location: normalizeLocation(fallbackLocation),
      clusterId: "",
      clusterName: "",
    };
  }
  if (trimmed.includes("/clusters/") || trimmed.includes("projects/")) {
    const parts = trimmed.split("/").filter((part) => part.length > 0);
    const clustersAt = parts.lastIndexOf("clusters");
    const locationsAt = parts.lastIndexOf("locations");
    const projectsAt = parts.lastIndexOf("projects");
    const clusterId = clustersAt >= 0 && parts[clustersAt + 1] ? parts[clustersAt + 1]! : "";
    const project =
      projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : fallbackProject;
    const location = normalizeLocation(
      (locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1] : undefined) ??
        fallbackLocation,
    );
    return {
      project,
      location,
      clusterId,
      clusterName: clusterNameOf(project, location, clusterId),
    };
  }
  const location = normalizeLocation(fallbackLocation);
  const clusterId = lastSegment(trimmed);
  return {
    project: fallbackProject,
    location,
    clusterId,
    clusterName: clusterNameOf(fallbackProject, location, clusterId),
  };
};

const userLabels = (
  labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));

const stringMapOf = (
  map: Record<string, string | undefined> | null | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(map ?? {}).filter(
      (entry): entry is [string, string] => entry[1] !== undefined && entry[1].length > 0,
    ),
  );

const toId = (id: string, backupId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return (
      backupId ??
      existing ??
      rfc1035(
        yield* createPhysicalName({
          id,
          maxLength: MAX_NAME_LENGTH,
          lowercase: true,
        }),
      )
    );
  });

const fingerprint = (value: unknown): string => JSON.stringify(value ?? null);

const toEncryptionConfig = (
  config: alloydb.EncryptionConfig | EncryptionConfig | undefined,
): EncryptionConfig | undefined => {
  const kmsKeyName = config?.kmsKeyName;
  if (kmsKeyName === undefined || kmsKeyName.length === 0) return undefined;
  return { kmsKeyName };
};

const isAvailable = (state: string | undefined) => (state ?? "").toUpperCase() === "READY";

const isFailed = (state: string | undefined) => (state ?? "").toUpperCase() === "FAILED";

const toAttrs = (backup: alloydb.Backup, project: string) => {
  const name = backup.name ?? "";
  const parsed = parseBackupName(name);
  const clusterRef = parseClusterRef(
    backup.clusterName ?? "",
    parsed.project || project,
    parsed.location,
  );
  return {
    name,
    backupId: parsed.backupId,
    clusterName: backup.clusterName ?? clusterRef.clusterName,
    clusterId: clusterRef.clusterId,
    project: parsed.project || project,
    location: parsed.location,
    displayName: backup.displayName,
    description: backup.description,
    labels: userLabels(backup.labels),
    annotations: stringMapOf(backup.annotations),
    state: backup.state,
    type: normalizeType(backup.type),
    sizeBytes: backup.sizeBytes,
    encryptionConfig: toEncryptionConfig(backup.encryptionConfig),
    databaseVersion: backup.databaseVersion,
    clusterUid: backup.clusterUid,
    uid: backup.uid,
    reconciling: backup.reconciling === true,
    createTime: backup.createTime,
    updateTime: backup.updateTime,
    createCompletionTime: backup.createCompletionTime,
    expiryTime: backup.expiryTime,
    etag: backup.etag,
  };
};

const isPlaceholder = (backup: alloydb.Backup) => {
  const name = backup.name ?? "";
  return name.endsWith("/backups/-") || name.endsWith("/backups/");
};

const getByName = (name: string) =>
  alloydb
    .getProjectsLocationsBackups({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((backup) =>
      backup ? Effect.succeed(backup) : Effect.fail(new BackupNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.AlloyDB.BackupNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilReady = (name: string) =>
  Effect.gen(function* () {
    const backup = yield* getByName(name);
    if (backup === undefined) {
      return yield* new BackupNotReady({ resourceName: name, state: "MISSING" });
    }
    if (isFailed(backup.state)) {
      return yield* new BackupFailed({
        resourceName: name,
        state: backup.state ?? "FAILED",
      });
    }
    if (!(isAvailable(backup.state) && backup.reconciling !== true)) {
      return yield* new BackupNotReady({
        resourceName: name,
        state: backup.state ?? "STATE_UNSPECIFIED",
      });
    }
    return backup;
  }).pipe(
    Effect.retry({
      while: (error) => error._tag === "GCP.AlloyDB.BackupNotReady",
      times: 120,
      schedule: Schedule.spaced("15 seconds"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((backup) =>
      backup === undefined
        ? Effect.void
        : Effect.fail(new BackupStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.AlloyDB.BackupStillExists",
      times: 120,
      schedule: Schedule.spaced("15 seconds"),
    }),
  );

const toCreateBody = (
  news: BackupProps,
  desiredLabels: Record<string, string>,
  clusterName: string,
  backupType: string,
): alloydb.Backup => {
  const body: alloydb.Backup = {
    clusterName,
    type: backupType,
    displayName: news.displayName,
    labels: desiredLabels,
  };
  if (news.description !== undefined) {
    body.description = news.description;
  }
  if (news.annotations !== undefined) {
    body.annotations = news.annotations;
  }
  const encryption = toEncryptionConfig(news.encryptionConfig);
  if (encryption !== undefined) {
    body.encryptionConfig = encryption;
  }
  if (news.tags !== undefined) {
    body.tags = news.tags;
  }
  return body;
};

export const BackupProvider = () =>
  Provider.succeed(Backup, {
    stables: [
      "name",
      "backupId",
      "clusterName",
      "clusterId",
      "project",
      "location",
      "uid",
      "createTime",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;

      const previousId = olds?.backupId ?? output?.backupId;
      const nextId = news.backupId ?? previousId;
      const previousCluster = lastSegment(
        olds?.clusterName ?? output?.clusterName ?? output?.clusterId,
      );
      const nextCluster = lastSegment(news.clusterName ?? previousCluster);
      const previousLocation = normalizeLocation(olds?.location ?? output?.location ?? env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location ?? env.region);
      const previousType = normalizeType(olds?.type ?? output?.type);
      const nextType = normalizeType(news.type ?? output?.type);
      const previousKey =
        olds?.encryptionConfig?.kmsKeyName ?? output?.encryptionConfig?.kmsKeyName ?? "";
      const nextKey = news.encryptionConfig?.kmsKeyName ?? previousKey;
      const previousTags = fingerprint(olds?.tags ?? undefined);
      const nextTags = fingerprint(news.tags ?? olds?.tags ?? undefined);

      const replace =
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        (previousCluster.length > 0 && nextCluster.length > 0 && previousCluster !== nextCluster) ||
        previousLocation !== nextLocation ||
        previousType !== nextType ||
        previousKey !== nextKey ||
        (news.tags !== undefined && previousTags !== nextTags) ||
        // PATCH accepts `description` but leaves it unchanged (observed live),
        // so a new description replaces the backup.
        (olds !== undefined && (news.description ?? "") !== (olds.description ?? ""));

      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          previousLocation === nextLocation &&
          previousCluster === nextCluster &&
          previousId !== undefined &&
          nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      if (output?.name) {
        const existing = yield* getByName(output.name);
        if (existing === undefined) return undefined;
        const attrs = toAttrs(existing, env.project);
        return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
      }
      const backupId = yield* toId(id, olds?.backupId, output?.backupId);
      const ref = parseClusterRef(
        olds?.clusterName ?? output?.clusterName ?? output?.clusterId ?? "",
        env.project,
        olds?.location ?? output?.location ?? env.region,
      );
      const location = normalizeLocation(olds?.location ?? output?.location ?? ref.location);
      const name = resourceName(env.project, location, backupId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* alloydb.listProjectsLocationsBackups
          .pages({
            parent: `projects/${env.project}/locations/-`,
            pageSize: 1000,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.backups ?? [])),
            Stream.filter(
              (backup) =>
                !isPlaceholder(backup) &&
                Object.keys(backup.labels ?? {}).some((key) => key.startsWith("alchemy-")),
            ),
            Stream.map((backup) => toAttrs(backup, env.project)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("NotFound", () => Effect.succeed([])),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const backupId = yield* toId(id, news.backupId, output?.backupId);
      const ref = parseClusterRef(
        news.clusterName,
        env.project,
        news.location ?? output?.location ?? env.region,
      );
      if (ref.clusterId.length === 0) {
        return yield* new BackupClusterMissing({
          message: "GCP.AlloyDB.Backup requires `clusterName` (cluster id or full resource name)",
        });
      }
      const location = normalizeLocation(news.location ?? ref.location);
      const name = resourceName(env.project, location, backupId);
      const backupType = normalizeType(news.type);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };

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

      if (current === undefined) {
        const parent = `projects/${env.project}/locations/${location}`;
        const created = yield* alloydb
          .createProjectsLocationsBackups({
            parent,
            backupId,
            body: toCreateBody(news, desiredLabels, ref.clusterName, backupType),
          })
          .pipe(
            // The cluster only accepts backups a few minutes after its
            // primary instance is created.
            Effect.retry({
              while: (error) => error._tag === "ClusterNotReadyForBackup",
              times: 40,
              schedule: Schedule.spaced("15 seconds"),
            }),
            Effect.catchTag("Conflict", () => Effect.undefined),
          );
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* waitUntilExists(name);
      }

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

      if (!isAvailable(current.state) || current.reconciling === true) {
        current = yield* waitUntilReady(name);
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const observedDisplayName = current.displayName ?? output?.displayName ?? olds?.displayName;
      const displayNameChanged = (observedDisplayName ?? "") !== (news.displayName ?? "");
      const annotationsChanged =
        news.annotations !== undefined &&
        fingerprint(stringMapOf(current.annotations)) !== fingerprint(news.annotations);

      if (labelsChanged || displayNameChanged || annotationsChanged) {
        const updateMask = [
          labelsChanged ? "labels" : undefined,
          displayNameChanged ? "displayName" : undefined,
          annotationsChanged ? "annotations" : undefined,
        ].filter((field): field is string => field !== undefined);

        const patched = yield* alloydb
          .patchProjectsLocationsBackups({
            name,
            updateMask: updateMask.join(","),
            body: {
              name,
              labels: desiredLabels,
              displayName: news.displayName,
              annotations: news.annotations,
            },
          })
          .pipe(
            Effect.retry({
              while: (error) => error._tag === "Conflict",
              times: 40,
              schedule: Schedule.spaced("15 seconds"),
            }),
          );
        yield* waitForOperation(patched);
        current = yield* waitUntilReady(name);
      }

      // AlloyDB omits `displayName` from backup reads (like clusters); the
      // desired value is what was applied.
      return toAttrs(
        { ...current, displayName: current.displayName ?? news.displayName },
        env.project,
      );
    }),

    delete: Effect.fn(function* ({ output }) {
      const operation = yield* alloydb.deleteProjectsLocationsBackups({ name: output.name }).pipe(
        Effect.catchTag("NotFound", () => Effect.undefined),
        Effect.retry({
          while: (error) => error._tag === "Conflict",
          times: 40,
          schedule: Schedule.spaced("15 seconds"),
        }),
      );
      if (operation !== undefined) {
        yield* waitForDeleteOperation(operation);
      }
      yield* waitUntilGone(output.name);
    }),
  });