sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Bigtable/ InstancesClustersBackup.ts

import * as bigtable from "@distilled.cloud/gcp/bigtableadmin_v2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  clusterIdOf,
  clusterNameOf,
  instanceIdOf,
  listAlchemyInstances,
  MAX_BACKUP_ID_LENGTH,
  parentOwned,
  parseResourceName,
  tableNameOf,
  toPhysicalId,
  waitForOperation,
  collectPages,
} from "./operations.ts";

const DEFAULT_EXPIRE_MS = 7 * 24 * 60 * 60 * 1000;

export type InstancesClustersBackupProps = {
  /**
   * Parent instance. Full name `projects/{project}/instances/{instance}`
   * or the instance id. Immutable — changing it replaces the backup.
   */
  instance: string;
  /**
   * Cluster that stores the backup. Full name
   * `projects/{project}/instances/{instance}/clusters/{cluster}` or the
   * cluster id. Immutable — changing it replaces the backup.
   */
  cluster: string;
  /**
   * Source table. Full name
   * `projects/{project}/instances/{instance}/tables/{table}` or the table
   * id. Immutable — changing it replaces the backup.
   */
  sourceTable: string;
  /**
   * Backup id (the `{backup}` segment of
   * `.../clusters/{cluster}/backups/{backup}`). If omitted, a unique name
   * is generated from the stack, stage, and logical id. Must be 1-50
   * characters. Immutable — changing it replaces the backup.
   */
  backupId?: string;
  /**
   * RFC3339 expiration. Must be at least 6 hours and at most 90 days
   * after creation. Defaults to 7 days from reconcile time when omitted
   * on create.
   */
  expireTime?: string;
  /**
   * Backup type (`STANDARD` or `HOT`). Immutable — changing it replaces
   * the backup.
   */
  backupType?: bigtable.BackupBackupTypeEnum | (string & {});
  /**
   * Time at which a hot backup converts to standard. Only valid for
   * `HOT` backups; must be at least 24 hours after creation.
   */
  hotToStandardTime?: string;
};

export type InstancesClustersBackup = Resource<
  "GCP.Bigtable.InstancesClustersBackup",
  InstancesClustersBackupProps,
  {
    /** Full resource name `.../clusters/{cluster}/backups/{backup}`. */
    name: string;
    /** Backup id (last path segment). */
    backupId: string;
    /** Parent cluster resource name. */
    cluster: string;
    /** Parent cluster id. */
    clusterId: string;
    /** Parent instance resource name. */
    instance: string;
    /** Parent instance id. */
    instanceId: string;
    /** Project id. */
    project: string;
    /** Source table resource name. */
    sourceTable: string | undefined;
    /** Copied-from backup name, if this backup is a copy. */
    sourceBackup: string | undefined;
    /** RFC3339 expiration. */
    expireTime: string | undefined;
    /** Backup type (`STANDARD`, `HOT`). */
    backupType: string | undefined;
    /** Hot-to-standard conversion time. */
    hotToStandardTime: string | undefined;
    /** Server-reported state (`CREATING`, `READY`). */
    state: string | undefined;
    /** RFC3339 start time. */
    startTime: string | undefined;
    /** RFC3339 end time. */
    endTime: string | undefined;
    /** Size in bytes (decimal string). */
    sizeBytes: string | undefined;
    /** Encryption info reported by the API. */
    encryptionInfo: bigtable.EncryptionInfo | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Bigtable backup of a table, stored on one cluster.
 *
 * The parent instance, cluster, and source table must already exist.
 * Changing `backupId`, `instance`, `cluster`, `sourceTable`, or
 * `backupType` replaces the backup. `expireTime` and
 * `hotToStandardTime` update in place.
 *
 * Backups have no labels field. Alchemy treats a backup as owned when
 * its parent instance carries Alchemy labels, so `list` /
 * `pnpm nuke:gcp` can find it.
 *
 * ### Creating a Backup
 * **Example:** 7-day backup of an existing table
 * ```typescript
 * const backup = yield* GCP.Bigtable.InstancesClustersBackup("Nightly", {
 *   instance: instance.name,
 *   cluster: "cluster",
 *   sourceTable: table.name,
 * });
 * ```
 *
 * **Example:** Explicit id and expiration
 * ```typescript
 * const backup = yield* GCP.Bigtable.InstancesClustersBackup("Nightly", {
 *   instance: instance.name,
 *   cluster: replica.clusterId,
 *   sourceTable: table.name,
 *   backupId: "nightly",
 *   expireTime: "2026-12-31T00:00:00Z",
 *   backupType: "STANDARD",
 * });
 * ```
 *
 * @resource
 * @category Bigtable
 */
export const InstancesClustersBackup = Resource<InstancesClustersBackup>(
  "GCP.Bigtable.InstancesClustersBackup",
);

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

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

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

const toId = (id: string, backupId: string | undefined, existing?: string) =>
  toPhysicalId(id, backupId, existing, MAX_BACKUP_ID_LENGTH);

const normalizeType = (value: string | undefined) => {
  const next = (value ?? "").toUpperCase();
  return next === "BACKUP_TYPE_UNSPECIFIED" ? "" : next;
};

const defaultExpireTime = () =>
  Effect.sync(() => new Date(Date.now() + DEFAULT_EXPIRE_MS).toISOString());

const toAttrs = (backup: bigtable.Backup, project: string) => {
  const name = backup.name ?? "";
  const parsed = parseResourceName(name);
  return {
    name,
    backupId: parsed.backupId,
    cluster: parsed.cluster,
    clusterId: parsed.clusterId,
    instance: parsed.instance,
    instanceId: parsed.instanceId,
    project: parsed.project || project,
    sourceTable: backup.sourceTable,
    sourceBackup: backup.sourceBackup,
    expireTime: backup.expireTime,
    backupType: backup.backupType,
    hotToStandardTime: backup.hotToStandardTime,
    state: backup.state,
    startTime: backup.startTime,
    endTime: backup.endTime,
    sizeBytes: backup.sizeBytes,
    encryptionInfo: backup.encryptionInfo,
  };
};

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

const isBusy = (state: string | undefined) =>
  state === "CREATING" || state === "STATE_UNSPECIFIED" || state === 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.Bigtable.BackupNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilReady = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (backup): backup is bigtable.Backup => backup !== undefined,
      () => new BackupNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (backup) => !isBusy(backup.state),
      (backup) =>
        new BackupNotReady({
          resourceName: name,
          state: backup.state ?? "STATE_UNSPECIFIED",
        }),
    ),
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.Bigtable.BackupNotReady" ||
        error._tag === "GCP.Bigtable.BackupNotResolved",
      times: 10,
      schedule: Schedule.spaced("8 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.Bigtable.BackupStillExists",
      times: 10,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

export const InstancesClustersBackupProvider = () =>
  Provider.succeed(InstancesClustersBackup, {
    stables: [
      "name",
      "backupId",
      "cluster",
      "clusterId",
      "instance",
      "instanceId",
      "project",
      "sourceTable",
      "startTime",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.backupId ?? output?.backupId;
      const nextId = news.backupId ?? previousId;
      const previousInstance = instanceIdOf(
        olds?.instance ?? output?.instance ?? output?.instanceId ?? "",
      );
      const nextInstance = instanceIdOf(news.instance);
      const previousCluster = clusterIdOf(
        olds?.cluster ?? output?.cluster ?? output?.clusterId ?? "",
      );
      const nextCluster = clusterIdOf(news.cluster);
      const previousTable = parseResourceName(
        olds?.sourceTable ?? output?.sourceTable ?? "",
      ).tableId;
      const nextTable = parseResourceName(
        news.sourceTable.includes("/tables/")
          ? news.sourceTable
          : `projects/_/instances/_/tables/${news.sourceTable}`,
      ).tableId;
      const previousType = normalizeType(olds?.backupType ?? output?.backupType);
      const nextType = normalizeType(news.backupType ?? output?.backupType);
      if (
        (previousId !== undefined && nextId !== undefined && previousId !== nextId) ||
        (previousInstance.length > 0 && previousInstance !== nextInstance) ||
        (previousCluster.length > 0 && previousCluster !== nextCluster) ||
        (previousTable.length > 0 && previousTable !== nextTable) ||
        (news.backupType !== undefined &&
          previousType.length > 0 &&
          nextType.length > 0 &&
          previousType !== nextType)
      ) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const backupId = yield* toId(id, olds?.backupId, output?.backupId);
      const instanceRef = olds?.instance ?? output?.instance;
      const clusterRef = olds?.cluster ?? output?.cluster;
      const name =
        output?.name ??
        (instanceRef && clusterRef
          ? `${clusterNameOf(env.project, instanceRef, clusterRef)}/backups/${backupId}`
          : undefined);
      if (name === undefined) return undefined;
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* parentOwned(attrs.instance)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const instances = (yield* listAlchemyInstances(env.project)).filter(
          (instance): instance is bigtable.Instance & { name: string } =>
            typeof instance.name === "string" && instance.name.length > 0,
        );
        const pages = yield* Effect.forEach(
          instances,
          (instance) =>
            collectPages(
              bigtable.listProjectsInstancesClustersBackups.pages({
                parent: `${instance.name}/clusters/-`,
                pageSize: 1000,
              }),
              (page) => page.backups,
            ).pipe(Effect.catchTag("NotFound", () => Effect.succeed([] as bigtable.Backup[]))),
          { concurrency: 4 },
        );
        return pages.flat().map((backup) => toAttrs(backup, env.project));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const backupId = yield* toId(id, news.backupId, output?.backupId);
      const parent = clusterNameOf(env.project, news.instance, news.cluster);
      const name = `${parent}/backups/${backupId}`;
      const sourceTable = tableNameOf(env.project, news.instance, news.sourceTable);
      const expireTime = news.expireTime ?? (yield* defaultExpireTime());

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

      if (current === undefined) {
        const created = yield* bigtable
          .createProjectsInstancesClustersBackups({
            parent,
            backupId,
            body: {
              sourceTable,
              expireTime,
              backupType: news.backupType,
              hotToStandardTime: news.hotToStandardTime,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created, { alreadyExistsOk: true });
        }
        current = yield* waitUntilExists(name);
      }

      if (isBusy(current.state)) {
        current = yield* waitUntilReady(name);
      }

      const mask: string[] = [];
      const patchBody: bigtable.Backup = {};
      if (news.expireTime !== undefined && (current.expireTime ?? "") !== news.expireTime) {
        patchBody.expireTime = news.expireTime;
        mask.push("expire_time");
      }
      if (
        news.hotToStandardTime !== undefined &&
        (current.hotToStandardTime ?? "") !== news.hotToStandardTime
      ) {
        patchBody.hotToStandardTime = news.hotToStandardTime;
        mask.push("hot_to_standard_time");
      }

      if (mask.length > 0) {
        current = yield* bigtable.patchProjectsInstancesClustersBackups({
          name,
          updateMask: mask.join(","),
          body: patchBody,
        });
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* bigtable.deleteProjectsInstancesClustersBackups({ name: output.name }).pipe(
        Effect.catchTag("NotFound", () => Effect.void),
        Effect.retry({
          while: (error) => error._tag === "Conflict",
          times: 8,
          schedule: Schedule.spaced("2 seconds"),
        }),
      );
      yield* waitUntilGone(output.name);
    }),
  });