sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DSQL/ Cluster.ts

import {
  diffMigrations,
  migrationsAttrs,
  migrationsInputOf,
  stampedOf,
  type MigrationsInput,
} from "@alchemy.run/sql/Migrations";
import * as dsql from "@distilled.cloud/aws/dsql";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } 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 { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { runDsqlMigrations } from "./Migrations.ts";
import { validateDsqlMigrations } from "./MigrationSql.ts";

export class DSQLClusterNotReady extends Data.TaggedError("DSQLClusterNotReady")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface ClusterProps {
  /**
   * SQL migrations directory, `{ dir, table? }`, or a Drizzle.Schema output.
   * Applied as admin using the deploy identity (requires dsql:DbConnectAdmin
   * and the optional `pg` peer). Files are checked before cluster mutation.
   * DDL runs one statement at a time; completed statements survive retries.
   * CREATE INDEX is adapted to ASYNC and awaited. Explicit transaction
   * control and serial columns are rejected. Use UUIDs or bigint identity
   * columns with an explicit CACHE. Applied migration files are immutable.
   */
  migrations?: MigrationsInput;
  /**
   * Enables deletion protection. While enabled the cluster cannot be deleted;
   * the provider automatically disables it during delete so `stack.destroy()`
   * always succeeds.
   * @default false
   */
  deletionProtectionEnabled?: boolean;
  /**
   * ARN of a customer-managed KMS key used to encrypt the cluster at rest.
   * Changing the key replaces the cluster.
   * @default an AWS-owned key
   */
  kmsEncryptionKey?: string;
  /**
   * User-defined tags for the cluster.
   */
  tags?: Record<string, string>;
}

export interface Cluster extends Resource<
  "AWS.DSQL.Cluster",
  ClusterProps,
  {
    /** Directory used by the current migration configuration. */
    migrationsDir: string | undefined;
    /** Applied-migrations bookkeeping table. */
    migrationsTable: string | undefined;
    /** SHA256 hashes used to detect migration file changes during plan. */
    migrationsHashes: Record<string, string>;
    /** The unique cluster identifier assigned by DSQL. */
    clusterId: string;
    /** The ARN of the cluster. */
    clusterArn: string;
    /** The current status of the cluster, e.g. `ACTIVE`. */
    status: string;
    /**
     * The public cluster endpoint hostname, e.g.
     * `<clusterId>.dsql.<region>.on.aws`. Connect with a Postgres wire client
     * using an IAM-generated auth token as the password.
     */
    endpoint: string;
    /** Whether deletion protection is enabled on the cluster. */
    deletionProtectionEnabled: boolean;
  },
  never,
  Providers
> {}

/**
 * An Amazon Aurora DSQL cluster — a serverless, distributed SQL database with
 * active-active high availability and Postgres wire compatibility.
 *
 * Clusters are pay-per-use with no provisioned capacity, so they have
 * excellent test economics. Create is asynchronous (`CREATING` -> `ACTIVE`),
 * usually completing in under a minute; the provider waits for `ACTIVE`
 * (bounded) before returning.
 * ### Creating a Cluster
 * **Example:** Basic Cluster
 * ```typescript
 * const cluster = yield* Cluster("AppDb", {});
 * // connect to cluster.endpoint on port 5432 as user "admin"
 * ```
 *
 * **Example:** Cluster with Deletion Protection
 * ```typescript
 * const cluster = yield* Cluster("AppDb", {
 *   deletionProtectionEnabled: true,
 * });
 * ```
 *
 * **Example:** Cluster with a Customer-Managed KMS Key
 * ```typescript
 * const cluster = yield* Cluster("AppDb", {
 *   kmsEncryptionKey: key.keyArn,
 * });
 * ```
 *
 * ### Applying SQL migrations
 * **Example:** Drizzle-generated PostgreSQL migrations
 * ```typescript
 * const schema = yield* Drizzle.Schema("Schema", {
 *   schema: "./src/schema.ts",
 *   dialect: "postgres",
 * });
 * const cluster = yield* Cluster("Database", { migrations: schema.out });
 * ```
 *
 * **Example:** Hand-written SQL migrations
 * ```typescript
 * const cluster = yield* Cluster("Database", { migrations: "./migrations" });
 * ```
 *
 * ### Recovering an interrupted migration <!-- api-prose -->
 * DSQL cannot roll back a whole migration. Alchemy records completed statements
 * in `<migrationsTable>__progress` and serializes deploys with
 * `__alchemy_dsql_migration_lock`. Server-rejected statements can be retried;
 * a running index job is resumed on the next deploy. After a disconnect with
 * an uncertain outcome, inspect the indicated statement and database first.
 * With all migrators stopped, set the progress row to `ready`, advancing
 * `next_statement` only if that statement committed (it is zero-based), then
 * remove a stale lock row if one remains. Never clear progress blindly.
 *
 * Automatic conversion of a different tool's existing history is refused
 * because DSQL cannot atomically combine the table DDL and history copy.
 * Convert that history explicitly before adopting an already-migrated database.
 *
 * @resource
 */
export const Cluster = Resource<Cluster>("AWS.DSQL.Cluster");

const activeStatuses = new Set(["ACTIVE", "IDLE"]);

export const ClusterProvider = () =>
  Provider.effect(
    Cluster,
    Effect.gen(function* () {
      const endpointFor = (identifier: string, region: string) =>
        `${identifier}.dsql.${region}.on.aws`;

      const readCluster = Effect.fn(function* (identifier: string) {
        return yield* dsql
          .getCluster({ identifier })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      const readTags = Effect.fn(function* (arn: string) {
        const response = yield* dsql
          .listTagsForResource({ resourceArn: arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return Object.fromEntries(
          Object.entries(response?.tags ?? {}).filter(
            (entry): entry is [string, string] => typeof entry[1] === "string",
          ),
        );
      });

      const findCluster = Effect.fn(function* (id: string, instanceId: string) {
        const summaries = yield* dsql.listClusters.items({}).pipe(Stream.runCollect);
        for (const summary of summaries) {
          const tags = yield* readTags(summary.arn);
          if (tags["alchemy::instance"] === instanceId && (yield* hasAlchemyTags(id, tags))) {
            return yield* readCluster(summary.identifier);
          }
        }
      });

      // Bound readiness to 50 seconds; a later deploy can resume provisioning.
      const waitForActive = Effect.fn(function* (identifier: string) {
        const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]);
        return yield* readCluster(identifier).pipe(
          Effect.flatMap((cluster) => {
            if (cluster === undefined) {
              return Effect.fail(
                new DSQLClusterNotReady({ message: `DSQL cluster '${identifier}' not found` }),
              );
            }
            if (!activeStatuses.has(cluster.status)) {
              return Effect.fail(
                new DSQLClusterNotReady({
                  message: `DSQL cluster '${identifier}' not active (status: ${cluster.status})`,
                }),
              );
            }
            return Effect.succeed(cluster);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      const toAttrs = (
        cluster: dsql.GetClusterOutput | dsql.CreateClusterOutput,
        region: string,
      ): Cluster["Attributes"] => ({
        clusterId: cluster.identifier,
        clusterArn: cluster.arn,
        status: cluster.status,
        endpoint: cluster.endpoint ?? endpointFor(cluster.identifier, region),
        deletionProtectionEnabled: cluster.deletionProtectionEnabled,
        migrationsDir: undefined,
        migrationsTable: undefined,
        migrationsHashes: {},
      });

      return {
        stables: ["clusterId", "clusterArn", "endpoint"],

        diff: Effect.fn(function* ({ olds = {}, news, output }) {
          if (!isResolved(news)) return undefined;
          const input = migrationsInputOf(news);
          if (input) yield* validateDsqlMigrations(input, output?.migrationsHashes);
          // KMS key is create-only; changing it forces a replacement.
          if ((news.kmsEncryptionKey ?? undefined) !== (olds.kmsEncryptionKey ?? undefined)) {
            return { action: "replace" } as const;
          }
          if (yield* diffMigrations({ news, output })) {
            return { action: "update" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, instanceId, output }) {
          const { region } = yield* AWSEnvironment.current;
          const cluster = output?.clusterId
            ? yield* readCluster(output.clusterId)
            : yield* findCluster(id, instanceId);
          if (cluster === undefined || cluster.status === "DELETED") {
            return undefined;
          }
          const tags = yield* readTags(cluster.arn);
          const attrs = {
            ...toAttrs(cluster, region),
            migrationsDir: output?.migrationsDir,
            migrationsTable: output?.migrationsTable,
            migrationsHashes: output?.migrationsHashes ?? {},
          };
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, instanceId, news = {}, output, session }) {
          const input = migrationsInputOf(news);
          if (input) yield* validateDsqlMigrations(input, output?.migrationsHashes);
          const { region } = yield* AWSEnvironment.current;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = {
            ...news.tags,
            ...internalTags,
            "alchemy::instance": instanceId,
          };

          // 1. Observe — cloud state is authoritative; output caches the id.
          let observed =
            output?.clusterId === undefined
              ? yield* findCluster(id, instanceId)
              : yield* readCluster(output.clusterId);

          // 2. Ensure — create if missing. DSQL assigns the identifier.
          let identifier = observed?.identifier ?? output?.clusterId;
          if (observed === undefined) {
            const created = yield* dsql.createCluster({
              clientToken: instanceId,
              deletionProtectionEnabled: news.deletionProtectionEnabled ?? false,
              kmsEncryptionKey: news.kmsEncryptionKey,
              tags: desiredTags,
            });
            identifier = created.identifier;
          }

          // Wait for ACTIVE so subsequent syncs do not hit ConflictException.
          const active = yield* waitForActive(identifier!);
          observed = active;

          // 3. Sync deletion protection against observed state.
          if (
            news.deletionProtectionEnabled !== undefined &&
            news.deletionProtectionEnabled !== observed.deletionProtectionEnabled
          ) {
            yield* dsql.updateCluster({
              identifier: identifier!,
              deletionProtectionEnabled: news.deletionProtectionEnabled,
            });
            observed = yield* waitForActive(identifier!);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = yield* readTags(observed.arn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* dsql.tagResource({
              resourceArn: observed.arn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* dsql.untagResource({
              resourceArn: observed.arn,
              tagKeys: removed,
            });
          }

          yield* session.note(identifier!);
          const attrs = toAttrs(observed, region);
          const run = input
            ? yield* runDsqlMigrations({
                endpoint: attrs.endpoint,
                input,
                stamped: stampedOf(output),
              })
            : undefined;
          return { ...attrs, ...migrationsAttrs({ input, run, output }) };
        }),

        delete: Effect.fn(function* ({ output }) {
          const identifier = output.clusterId;
          const existing = yield* readCluster(identifier);
          if (existing === undefined) return;
          // Deletion protection blocks delete — disable it first.
          if (existing.deletionProtectionEnabled) {
            yield* dsql
              .updateCluster({
                identifier,
                deletionProtectionEnabled: false,
              })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          }
          yield* dsql.deleteCluster({ identifier }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            // A cluster still CREATING rejects delete with ConflictException;
            // retry briefly until it settles into a deletable state.
            Effect.retry({
              while: (e) => e._tag === "ConflictException",
              schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
            }),
          );
        }),

        list: () =>
          Effect.gen(function* () {
            const { region } = yield* AWSEnvironment.current;
            const summaries = yield* dsql.listClusters.items({}).pipe(
              Stream.runCollect,
              Effect.map((c) => Array.from(c)),
            );
            return yield* Effect.forEach(
              summaries,
              (summary) =>
                readCluster(summary.identifier).pipe(
                  Effect.map((cluster) =>
                    cluster === undefined || cluster.status === "DELETED"
                      ? undefined
                      : toAttrs(cluster, region),
                  ),
                ),
              { concurrency: 4 },
            ).pipe(
              Effect.map((attrs) =>
                attrs.filter((a): a is NonNullable<typeof a> => a !== undefined),
              ),
            );
          }),
      };
    }),
  );