sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Spanner/ InstanceConfig.ts

import * as spanner from "@distilled.cloud/gcp/spanner_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 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 {
  configIdOf,
  configNameOf,
  instanceConfigName,
  parseResourceName,
  retryConcurrentChanges,
  toConfigId,
  waitForOperation,
} from "./operations.ts";

export type ReplicaInfo = {
  /** Replica location (e.g. `us-central1`). */
  location?: string;
  /** Replica type (`READ_WRITE`, `READ_ONLY`, `WITNESS`). */
  type?: spanner.ReplicaInfoTypeEnum | (string & {});
  /** Whether this location is the default leader. */
  defaultLeaderLocation?: boolean;
};

export type InstanceConfigProps = {
  /**
   * Instance config id (the `{config}` segment of
   * `projects/{project}/instanceConfigs/{config}`). User-managed ids must
   * start with `custom-` and match `custom-[-a-z0-9]*[a-z0-9]` (2–64
   * characters). If omitted, a unique `custom-` name is generated.
   * Immutable — changing it replaces the config.
   */
  instanceConfigId?: string;
  /**
   * User-facing display name. Defaults to the instance config id.
   */
  displayName?: string;
  /**
   * Google-managed base config id (`regional-us-central1`) or full name.
   * Immutable — changing it replaces the config.
   * @default `regional-{region}` for the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  baseConfig?: string;
  /**
   * Replica placement. Must include every replica from `baseConfig` plus
   * at least one of its optional replicas. When omitted, Alchemy copies
   * the base replicas and appends the first optional replica.
   * Immutable — changing them replaces the config.
   */
  replicas?: ReplicaInfo[];
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
};

export type InstanceConfig = Resource<
  "GCP.Spanner.InstanceConfig",
  InstanceConfigProps,
  {
    /** Full resource name `projects/{project}/instanceConfigs/{config}`. */
    name: string;
    /** Instance config id (last path segment). */
    instanceConfigId: string;
    /** Project id. */
    project: string;
    /** User-facing display name. */
    displayName: string | undefined;
    /** `GOOGLE_MANAGED` or `USER_MANAGED`. */
    configType: string | undefined;
    /** Replica placement. */
    replicas: ReplicaInfo[];
    /** Optional replicas advertised by Google-managed configs. */
    optionalReplicas: ReplicaInfo[];
    /** Full base config name. */
    baseConfig: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Allowed `default_leader` values. */
    leaderOptions: string[];
    /** Whether a create/update is in flight. */
    reconciling: boolean | undefined;
    /** Current state (`CREATING`, `READY`). */
    state: string | undefined;
    /** Whether free instances can be created in this config. */
    freeInstanceAvailability: string | undefined;
    /** Quorum type (`REGION`, `DUAL_REGION`, `MULTI_REGION`). */
    quorumType: string | undefined;
    /** Storage limit in bytes per processing unit. */
    storageLimitPerProcessingUnit: string | undefined;
  },
  never,
  Providers
>;

/**
 * A user-managed Cloud Spanner instance configuration.
 *
 * User-managed configs clone a Google-managed `baseConfig` and add at
 * least one optional read-only replica. Only `displayName` and `labels`
 * update in place; changing `instanceConfigId`, `baseConfig`, or
 * `replicas` replaces the config. Create, update, and delete are
 * long-running. Google-managed configs cannot be created or deleted.
 *
 * ### Creating an Instance Config
 * **Example:** Clone `regional-us-central1` with an optional replica
 * ```typescript
 * const config = yield* GCP.Spanner.InstanceConfig("Custom", {
 *   baseConfig: "regional-us-central1",
 *   displayName: "custom-us-central1",
 *   labels: { env: "test" },
 * });
 * ```
 *
 * **Example:** Explicit id and replica list
 * ```typescript
 * const config = yield* GCP.Spanner.InstanceConfig("Custom", {
 *   instanceConfigId: "custom-us-central1-ro",
 *   baseConfig: "regional-us-central1",
 *   replicas: [
 *     { location: "us-central1", type: "READ_WRITE" },
 *     { location: "us-central1", type: "READ_WRITE" },
 *     { location: "us-central1", type: "READ_WRITE" },
 *     { location: "us-east1", type: "READ_ONLY" },
 *   ],
 * });
 * ```
 *
 * @resource
 * @category Spanner
 */
export const InstanceConfig = Resource<InstanceConfig>("GCP.Spanner.InstanceConfig");

export class InstanceConfigNotResolved extends Data.TaggedError(
  "GCP.Spanner.InstanceConfigNotResolved",
)<{
  resourceName: string;
}> {}

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

export class InstanceConfigStillExists extends Data.TaggedError(
  "GCP.Spanner.InstanceConfigStillExists",
)<{
  resourceName: string;
}> {}

export class InstanceConfigNoOptionalReplicas extends Data.TaggedError(
  "GCP.Spanner.InstanceConfigNoOptionalReplicas",
)<{
  baseConfig: string;
}> {}

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

const replicaOf = (replica: spanner.ReplicaInfo): ReplicaInfo => ({
  location: replica.location,
  type: replica.type,
  defaultLeaderLocation: replica.defaultLeaderLocation,
});

const replicasOf = (items: spanner.ReplicaInfoList | undefined): ReplicaInfo[] =>
  (items ?? []).map(replicaOf);

const replicaKey = (replicas: ReplicaInfo[] | undefined) =>
  JSON.stringify(
    (replicas ?? [])
      .map((replica) => ({
        location: (replica.location ?? "").toLowerCase(),
        type: (replica.type ?? "").toUpperCase(),
        defaultLeaderLocation: replica.defaultLeaderLocation === true,
      }))
      .sort(
        (left, right) =>
          left.location.localeCompare(right.location) || left.type.localeCompare(right.type),
      ),
  );

const toAttrs = (config: spanner.InstanceConfig, project: string): InstanceConfig["Attributes"] => {
  const name = config.name ?? "";
  const parsed = parseResourceName(name);
  return {
    name,
    instanceConfigId: parsed.instanceConfigId,
    project,
    displayName: config.displayName,
    configType: config.configType,
    replicas: replicasOf(config.replicas),
    optionalReplicas: replicasOf(config.optionalReplicas),
    baseConfig: config.baseConfig,
    labels: userLabels(config.labels),
    leaderOptions: config.leaderOptions ?? [],
    reconciling: config.reconciling,
    state: config.state,
    freeInstanceAvailability: config.freeInstanceAvailability,
    quorumType: config.quorumType,
    storageLimitPerProcessingUnit: config.storageLimitPerProcessingUnit,
  };
};

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

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((config) =>
      config
        ? Effect.succeed(config)
        : Effect.fail(new InstanceConfigNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Spanner.InstanceConfigNotResolved",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const isReady = (config: spanner.InstanceConfig) =>
  (config.state ?? "STATE_UNSPECIFIED") === "READY" && config.reconciling !== true;

const waitUntilReady = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (config): config is spanner.InstanceConfig => config !== undefined,
      () => new InstanceConfigNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (config) => isReady(config),
      (config) =>
        new InstanceConfigNotReady({
          resourceName: name,
          state: config.state ?? "STATE_UNSPECIFIED",
        }),
    ),
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.Spanner.InstanceConfigNotReady" ||
        error._tag === "GCP.Spanner.InstanceConfigNotResolved",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
  );

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

const desiredReplicas = (
  project: string,
  region: string,
  news: InstanceConfigProps,
): Effect.Effect<
  ReplicaInfo[],
  InstanceConfigNoOptionalReplicas | spanner.GetProjectsInstanceConfigsError,
  spanner.GcpOpContext
> =>
  Effect.gen(function* () {
    if (news.replicas !== undefined && news.replicas.length > 0) {
      return news.replicas;
    }
    const baseName = configNameOf(project, news.baseConfig, region);
    const base = yield* spanner.getProjectsInstanceConfigs({ name: baseName });
    const extra = (base.optionalReplicas ?? [])[0];
    if (extra === undefined) {
      return yield* new InstanceConfigNoOptionalReplicas({
        baseConfig: baseName,
      });
    }
    return [...replicasOf(base.replicas), replicaOf(extra)];
  });

export const InstanceConfigProvider = () =>
  Provider.succeed(InstanceConfig, {
    stables: ["name", "instanceConfigId", "project", "baseConfig", "configType"],

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

      const previousId = olds?.instanceConfigId ?? output?.instanceConfigId;
      const nextId = news.instanceConfigId ?? previousId;
      const previousBase = configIdOf(olds?.baseConfig ?? output?.baseConfig, env.region);
      const nextBase = configIdOf(news.baseConfig ?? output?.baseConfig, env.region);
      const replicasChanged =
        news.replicas !== undefined &&
        olds?.replicas !== undefined &&
        replicaKey(news.replicas) !== replicaKey(olds.replicas);

      const idChanged = previousId !== undefined && nextId !== undefined && previousId !== nextId;
      const replace = idChanged || previousBase !== nextBase || replicasChanged;
      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          previousBase !== nextBase ||
          replicasChanged ||
          (previousId !== undefined && nextId === previousId),
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceConfigId = yield* toConfigId(
        id,
        olds?.instanceConfigId,
        output?.instanceConfigId,
      );
      const name = output?.name ?? instanceConfigName(env.project, instanceConfigId);
      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* spanner.listProjectsInstanceConfigs
          .pages({
            parent: `projects/${env.project}`,
            pageSize: 1000,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.instanceConfigs ?? [])),
            Stream.filter(
              (config) =>
                (config.configType ?? "") === "USER_MANAGED" &&
                Object.keys(config.labels ?? {}).some((key) => key.startsWith("alchemy-")),
            ),
            Stream.map((config) => toAttrs(config, env.project)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("NotFound", () => Effect.succeed([])),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceConfigId = yield* toConfigId(
        id,
        news.instanceConfigId,
        output?.instanceConfigId,
      );
      const name = instanceConfigName(env.project, instanceConfigId);
      const displayName = news.displayName?.trim() || instanceConfigId;
      const baseConfig = configNameOf(env.project, news.baseConfig, env.region);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };

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

      if (current === undefined) {
        const replicas = yield* desiredReplicas(env.project, env.region, news);
        const created = yield* spanner
          .createProjectsInstanceConfigs({
            parent: `projects/${env.project}`,
            body: {
              instanceConfigId,
              instanceConfig: {
                name,
                displayName,
                baseConfig,
                replicas,
                labels: desiredLabels,
              },
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created, { alreadyExistsOk: true });
        }
        current = yield* waitUntilExists(name);
      }

      if (!isReady(current)) {
        current = yield* waitUntilReady(name);
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const displayNameChanged = (current.displayName ?? "") !== displayName;

      if (labelsChanged || displayNameChanged) {
        const fieldMask = [
          labelsChanged ? "labels" : undefined,
          displayNameChanged ? "display_name" : undefined,
        ].filter((field): field is string => field !== undefined);
        const patched = yield* retryConcurrentChanges(
          spanner.patchProjectsInstanceConfigs({
            name,
            body: {
              instanceConfig: {
                name,
                displayName,
                labels: desiredLabels,
              },
              updateMask: fieldMask.join(","),
            },
          }),
        );
        yield* waitForOperation(patched);
        current = yield* waitUntilReady(name);
      }

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

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