sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Bigtable/ Cluster.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 {
  clusterLocation,
  clusterName,
  DEFAULT_SERVE_NODES,
  DEFAULT_ZONE,
  lastSegment,
  listAlchemyInstances,
  MAX_CLUSTER_ID_LENGTH,
  MIN_CLUSTER_ID_LENGTH,
  parentOwned,
  parseResourceName,
  toPhysicalId,
  waitForOperation,
  zoneOf,
  collectPages,
} from "./operations.ts";

const DEFAULT_STORAGE_TYPE = "SSD";

export type AutoscalingLimits = {
  /** Minimum nodes the autoscaler can scale down to. */
  minServeNodes?: number;
  /** Maximum nodes the autoscaler can scale up to. */
  maxServeNodes?: number;
};

export type AutoscalingTargets = {
  /**
   * Target CPU utilization percent (`10`–`80`).
   */
  cpuUtilizationPercent?: number;
  /**
   * Target storage utilization in GiB per node. SSD default `2560`;
   * HDD default `8192`.
   */
  storageUtilizationGibPerNode?: number;
};

export type ClusterAutoscalingConfig = {
  /** Minimum and maximum node counts. */
  autoscalingLimits?: AutoscalingLimits;
  /** CPU and storage utilization targets. */
  autoscalingTargets?: AutoscalingTargets;
};

export type ClusterConfig = {
  /** Autoscaling configuration. Mutually exclusive with `serveNodes`. */
  clusterAutoscalingConfig?: ClusterAutoscalingConfig;
};

export type EncryptionConfig = {
  /**
   * Cloud KMS key
   * `projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}`.
   * Must be in the same region as the cluster. Immutable — changing it
   * replaces the cluster.
   */
  kmsKeyName?: string;
};

export type ClusterResourceProps = {
  /**
   * Parent instance id (the `{instance}` segment of
   * `projects/{project}/instances/{instance}`). Full resource names are
   * accepted and reduced to the last path segment. Immutable — changing
   * it replaces the cluster.
   */
  instance: string;
  /**
   * Cluster id (the `{cluster}` segment of
   * `projects/{project}/instances/{instance}/clusters/{cluster}`). If
   * omitted, a unique name is generated from the stack, stage, and
   * logical id. Must be 6-30 characters and match
   * `[a-z][-a-z0-9]*`. Immutable — changing it replaces the cluster.
   */
  clusterId?: string;
  /**
   * Zone where nodes and storage reside (e.g. `us-central1-b`). Full
   * location names `projects/{project}/locations/{zone}` are accepted.
   * Immutable — changing it replaces the cluster.
   * @default "us-central1-b"
   */
  location?: string;
  /**
   * Storage type used by this cluster (`SSD` or `HDD`). Immutable —
   * changing it replaces the cluster.
   * @default "SSD"
   */
  defaultStorageType?: bigtable.ClusterDefaultStorageTypeEnum | (string & {});
  /**
   * Manual node count. Mutually exclusive with
   * `clusterConfig.clusterAutoscalingConfig`. Ignored while
   * autoscaling is enabled.
   * @default 1
   */
  serveNodes?: number;
  /**
   * Node scaling factor. Immutable — changing it replaces the cluster.
   */
  nodeScalingFactor?: bigtable.ClusterNodeScalingFactorEnum | (string & {});
  /**
   * Customer-managed encryption. Immutable — changing it replaces the
   * cluster.
   */
  encryptionConfig?: EncryptionConfig;
  /**
   * Cluster configuration. Set `clusterAutoscalingConfig` to enable
   * autoscaling (and omit `serveNodes`).
   */
  clusterConfig?: ClusterConfig;
};

export type Cluster = Resource<
  "GCP.Bigtable.Cluster",
  ClusterResourceProps,
  {
    /** Full resource name `projects/{project}/instances/{instance}/clusters/{cluster}`. */
    name: string;
    /** Cluster id (last path segment). */
    clusterId: string;
    /** Parent instance resource name. */
    instance: string;
    /** Parent instance id. */
    instanceId: string;
    /** Project id. */
    project: string;
    /** Zone id (`us-central1-b`, …). */
    location: string;
    /** Storage type (`SSD`, `HDD`). */
    defaultStorageType: string | undefined;
    /** Current node count. */
    serveNodes: number | undefined;
    /** Node scaling factor. */
    nodeScalingFactor: string | undefined;
    /** CMEK configuration, if any. */
    encryptionConfig: EncryptionConfig | undefined;
    /** Cluster configuration currently applied. */
    clusterConfig: ClusterConfig | undefined;
    /** Server-reported state (`READY`, `CREATING`, `RESIZING`, …). */
    state: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Bigtable cluster — a resizable group of nodes in one zone
 * that serves every table in the parent instance.
 *
 * An instance always has at least one cluster (created with the
 * instance). Use this resource to add additional clusters or to manage
 * an existing cluster's node count and autoscaling. You cannot delete
 * the last cluster in an instance.
 *
 * Changing `clusterId`, `instance`, `location`, `defaultStorageType`,
 * `nodeScalingFactor`, or `encryptionConfig.kmsKeyName` replaces the
 * cluster. `serveNodes` and `clusterConfig.clusterAutoscalingConfig`
 * update in place.
 *
 * Clusters have no labels field. `list` enumerates clusters on
 * alchemy-labeled instances so `pnpm nuke:gcp` can find leaked rows.
 *
 * Provisioning typically takes several minutes.
 *
 * ### Creating a Cluster
 * **Example:** Additional cluster on an existing instance
 * ```typescript
 * const replica = yield* GCP.Bigtable.Cluster("Replica", {
 *   instance: instance.instanceId,
 *   location: "us-central1-b",
 *   serveNodes: 1,
 * });
 * ```
 *
 * **Example:** Explicit id and HDD storage
 * ```typescript
 * const replica = yield* GCP.Bigtable.Cluster("Replica", {
 *   instance: "app-instance",
 *   clusterId: "app-replica",
 *   location: "us-central1-c",
 *   defaultStorageType: "HDD",
 *   serveNodes: 1,
 * });
 * ```
 *
 * ### Autoscaling
 * **Example:** Autoscaling between 1 and 3 nodes
 * ```typescript
 * const replica = yield* GCP.Bigtable.Cluster("Replica", {
 *   instance: "app-instance",
 *   location: "us-central1-f",
 *   clusterConfig: {
 *     clusterAutoscalingConfig: {
 *       autoscalingLimits: { minServeNodes: 1, maxServeNodes: 3 },
 *       autoscalingTargets: { cpuUtilizationPercent: 50 },
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 * @category Bigtable
 */
export const Cluster = Resource<Cluster>("GCP.Bigtable.Cluster");

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

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

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

const instanceIdOf = (value: string) => lastSegment(value);

const normalizeStorage = (storage: string | undefined) => {
  const value = (storage ?? DEFAULT_STORAGE_TYPE).toUpperCase();
  return value === "STORAGE_TYPE_UNSPECIFIED" ? DEFAULT_STORAGE_TYPE : value;
};

const normalizeScaling = (factor: string | undefined) => (factor ?? "").toUpperCase();

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

const encryptionKey = (config: bigtable.EncryptionConfig | EncryptionConfig | undefined) =>
  encryptionOf(config)?.kmsKeyName ?? "";

const autoscalingOf = (
  config: bigtable.ClusterAutoscalingConfig | ClusterAutoscalingConfig | undefined,
): ClusterAutoscalingConfig | undefined => {
  if (config === undefined) return undefined;
  const limits = config.autoscalingLimits;
  const targets = config.autoscalingTargets;
  if (limits === undefined && targets === undefined) return undefined;
  return {
    autoscalingLimits: limits
      ? {
          minServeNodes: limits.minServeNodes,
          maxServeNodes: limits.maxServeNodes,
        }
      : undefined,
    autoscalingTargets: targets
      ? {
          cpuUtilizationPercent: targets.cpuUtilizationPercent,
          storageUtilizationGibPerNode: targets.storageUtilizationGibPerNode,
        }
      : undefined,
  };
};

const clusterConfigOf = (
  config: bigtable.ClusterConfig | ClusterConfig | undefined,
): ClusterConfig | undefined => {
  const autoscaling = autoscalingOf(config?.clusterAutoscalingConfig);
  if (autoscaling === undefined) return undefined;
  return { clusterAutoscalingConfig: autoscaling };
};

const autoscalingKey = (config: bigtable.ClusterConfig | ClusterConfig | undefined) => {
  const autoscaling = clusterConfigOf(config)?.clusterAutoscalingConfig;
  return JSON.stringify({
    minServeNodes: autoscaling?.autoscalingLimits?.minServeNodes ?? null,
    maxServeNodes: autoscaling?.autoscalingLimits?.maxServeNodes ?? null,
    cpuUtilizationPercent: autoscaling?.autoscalingTargets?.cpuUtilizationPercent ?? null,
    storageUtilizationGibPerNode:
      autoscaling?.autoscalingTargets?.storageUtilizationGibPerNode ?? null,
  });
};

const toAttrs = (cluster: bigtable.Cluster, project: string) => {
  const name = cluster.name ?? "";
  const parsed = parseResourceName(name);
  return {
    name,
    clusterId: parsed.clusterId,
    instance: parsed.instance,
    instanceId: parsed.instanceId,
    project: parsed.project || project,
    location: zoneOf(cluster.location || DEFAULT_ZONE),
    defaultStorageType: cluster.defaultStorageType,
    serveNodes: cluster.serveNodes,
    nodeScalingFactor: cluster.nodeScalingFactor,
    encryptionConfig: encryptionOf(cluster.encryptionConfig),
    clusterConfig: clusterConfigOf(cluster.clusterConfig),
    state: cluster.state,
  };
};

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

const isBusy = (state: string | undefined) =>
  state === "CREATING" ||
  state === "RESIZING" ||
  state === "STATE_NOT_KNOWN" ||
  state === undefined;

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

const waitUntilReady = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (cluster): cluster is bigtable.Cluster => cluster !== undefined,
      () => new ClusterNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (cluster) => !isBusy(cluster.state),
      (cluster) =>
        new ClusterNotReady({
          resourceName: name,
          state: cluster.state ?? "STATE_NOT_KNOWN",
        }),
    ),
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.Bigtable.ClusterNotReady" ||
        error._tag === "GCP.Bigtable.ClusterNotResolved",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((cluster) =>
      cluster === undefined
        ? Effect.void
        : Effect.fail(new ClusterStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Bigtable.ClusterStillExists",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
  );

const toCreateBody = (
  news: ClusterResourceProps,
  project: string,
  zone: string,
  storage: string,
): bigtable.Cluster => {
  const autoscaling = clusterConfigOf(news.clusterConfig);
  return {
    location: clusterLocation(project, zone),
    defaultStorageType: storage,
    nodeScalingFactor: news.nodeScalingFactor,
    encryptionConfig: news.encryptionConfig,
    serveNodes: autoscaling === undefined ? (news.serveNodes ?? DEFAULT_SERVE_NODES) : undefined,
    clusterConfig: autoscaling,
  };
};

export const ClusterProvider = () =>
  Provider.succeed(Cluster, {
    stables: ["name", "clusterId", "instance", "instanceId", "project", "location"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;

      const previousId = olds?.clusterId ?? output?.clusterId;
      const nextId = news.clusterId ?? previousId;
      const previousInstance = instanceIdOf(
        olds?.instance ?? output?.instance ?? output?.instanceId ?? "",
      );
      const nextInstance = instanceIdOf(news.instance);
      const previousZone = zoneOf(olds?.location ?? output?.location);
      const nextZone = zoneOf(news.location ?? output?.location);
      const previousStorage = normalizeStorage(
        olds?.defaultStorageType ?? output?.defaultStorageType,
      );
      const nextStorage = normalizeStorage(news.defaultStorageType ?? output?.defaultStorageType);
      const previousScaling = normalizeScaling(
        olds?.nodeScalingFactor ?? output?.nodeScalingFactor,
      );
      const nextScaling = normalizeScaling(news.nodeScalingFactor ?? output?.nodeScalingFactor);
      const previousCmek = encryptionKey(olds?.encryptionConfig ?? output?.encryptionConfig);
      const nextCmek = encryptionKey(news.encryptionConfig ?? output?.encryptionConfig);

      const replace =
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        (previousInstance.length > 0 &&
          nextInstance.length > 0 &&
          previousInstance !== nextInstance) ||
        previousZone !== nextZone ||
        previousStorage !== nextStorage ||
        (previousScaling.length > 0 && nextScaling.length > 0 && previousScaling !== nextScaling) ||
        previousCmek !== nextCmek;

      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          previousInstance === nextInstance && previousId !== undefined && nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceId = instanceIdOf(
        olds?.instance ?? output?.instance ?? output?.instanceId ?? "",
      );
      if (instanceId.length === 0) return undefined;
      const clusterId = yield* toPhysicalId(
        id,
        olds?.clusterId,
        output?.clusterId,
        MAX_CLUSTER_ID_LENGTH,
        MIN_CLUSTER_ID_LENGTH,
      );
      const name = output?.name ?? clusterName(env.project, instanceId, clusterId);
      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);
        const labeled = new Set(
          instances.map((instance) => instance.name ?? "").filter((name) => name.length > 0),
        );
        if (labeled.size === 0) return [];
        const clusters = yield* collectPages(
          bigtable.listProjectsInstancesClusters.pages({
            parent: `projects/${env.project}/instances/-`,
          }),
          (page) => page.clusters,
        );
        return clusters
          .filter((cluster) => labeled.has(parseResourceName(cluster.name ?? "").instance))
          .map((cluster) => toAttrs(cluster, env.project));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceId = instanceIdOf(news.instance);
      const clusterId = yield* toPhysicalId(
        id,
        news.clusterId,
        output?.clusterId,
        MAX_CLUSTER_ID_LENGTH,
        MIN_CLUSTER_ID_LENGTH,
      );
      const zone = zoneOf(news.location ?? output?.location);
      const storage = normalizeStorage(news.defaultStorageType);
      const name = clusterName(env.project, instanceId, clusterId);
      const desiredAutoscaling = clusterConfigOf(news.clusterConfig);

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

      if (current === undefined) {
        const created = yield* bigtable
          .createProjectsInstancesClusters({
            parent: `projects/${env.project}/instances/${instanceId}`,
            clusterId,
            body: toCreateBody(news, env.project, zone, storage),
          })
          .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 observedAutoscaling = clusterConfigOf(current.clusterConfig);
      const autoscalingChanged =
        desiredAutoscaling !== undefined &&
        autoscalingKey(current.clusterConfig) !== autoscalingKey(news.clusterConfig);
      const disableAutoscaling =
        desiredAutoscaling === undefined &&
        news.serveNodes !== undefined &&
        observedAutoscaling !== undefined;
      const serveNodesChanged =
        desiredAutoscaling === undefined &&
        news.serveNodes !== undefined &&
        (current.serveNodes ?? DEFAULT_SERVE_NODES) !== news.serveNodes;

      if (autoscalingChanged) {
        const patched = yield* bigtable.partialUpdateClusterProjectsInstancesClusters({
          name,
          updateMask: "cluster_config.cluster_autoscaling_config",
          body: {
            name,
            clusterConfig: desiredAutoscaling,
          },
        });
        yield* waitForOperation(patched);
        current = yield* waitUntilReady(name);
      } else if (disableAutoscaling || serveNodesChanged) {
        const serveNodes = news.serveNodes ?? current.serveNodes ?? DEFAULT_SERVE_NODES;
        if (disableAutoscaling) {
          const patched = yield* bigtable.partialUpdateClusterProjectsInstancesClusters({
            name,
            updateMask: "serve_nodes,cluster_config.cluster_autoscaling_config",
            body: {
              name,
              serveNodes,
              clusterConfig: {},
            },
          });
          yield* waitForOperation(patched);
        } else {
          const updated = yield* bigtable.updateProjectsInstancesClusters({
            name,
            body: {
              name,
              location: current.location ?? clusterLocation(env.project, zone),
              serveNodes,
              defaultStorageType: current.defaultStorageType ?? storage,
            },
          });
          yield* waitForOperation(updated);
        }
        current = yield* waitUntilReady(name);
      }

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

    delete: Effect.fn(function* ({ output }) {
      const result = yield* bigtable.deleteProjectsInstancesClusters({ name: output.name }).pipe(
        Effect.retry({
          while: (error) => error._tag === "Conflict",
          times: 8,
          schedule: Schedule.spaced("5 seconds"),
        }),
        Effect.as("deleted" as const),
        Effect.catchTags({
          NotFound: () => Effect.succeed("deleted" as const),
          // The instance's last cluster goes away with the instance.
          LastClusterDeletion: () => Effect.succeed("kept" as const),
        }),
      );
      if (result === "deleted") {
        yield* waitUntilGone(output.name);
      }
    }),
  });