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

import * as docdbelastic from "@distilled.cloud/aws/docdb-elastic";
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 { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

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

export interface ClusterProps {
  /**
   * Name of the elastic cluster. If omitted, a deterministic physical name
   * is generated. Changing the name replaces the cluster.
   */
  clusterName?: string;
  /**
   * Name of the administrator account for the elastic cluster. Changing the
   * admin user name replaces the cluster.
   */
  adminUserName: string;
  /**
   * Password for the administrator account. Must be 8-100 printable ASCII
   * characters (no `/`, `"` or `@`). The cloud never reports the current
   * password, so password rotation is detected by comparing against the
   * previously deployed value.
   */
  adminUserPassword: Redacted.Redacted<string>;
  /**
   * Authentication type — `"PLAIN_TEXT"` (the password is the literal
   * credential) or `"SECRET_ARN"` (the password is a Secrets Manager ARN).
   * @default "PLAIN_TEXT"
   */
  authType?: string;
  /**
   * Capacity of each shard in vCPUs. Valid values: 2, 4, 8, 16, 32, 64.
   * Updated in place.
   * @default 2
   */
  shardCapacity?: number;
  /**
   * Number of shards in the cluster (1-32). Updated in place.
   * @default 1
   */
  shardCount?: number;
  /**
   * Number of replica instances per shard (1-16).
   * @default 1
   */
  shardInstanceCount?: number;
  /**
   * VPC security groups that control network access to the cluster
   * endpoint.
   * @default the VPC's default security group
   */
  vpcSecurityGroupIds?: string[];
  /**
   * VPC subnet IDs the cluster spans. Must cover at least two Availability
   * Zones (three for production workloads).
   * @default the default VPC's subnets
   */
  subnetIds?: string[];
  /**
   * Customer-managed KMS key for encryption at rest. Changing the key
   * replaces the cluster.
   * @default AWS-owned key
   */
  kmsKeyId?: string;
  /**
   * Weekly maintenance window, e.g. `"sun:23:00-mon:01:30"` (UTC).
   */
  preferredMaintenanceWindow?: string;
  /**
   * How long automatic snapshots are retained, e.g. `"7 days"` or
   * `Duration.days(7)`. Rounded to whole days (1-35) on the wire.
   */
  backupRetentionPeriod?: Duration.Input;
  /**
   * Daily window (UTC, `HH:MM-HH:MM`) when automatic snapshots are taken.
   */
  preferredBackupWindow?: string;
  /**
   * User-defined tags for the cluster.
   */
  tags?: Record<string, string>;
}

export interface Cluster extends Resource<
  "AWS.DocDBElastic.Cluster",
  ClusterProps,
  {
    /** The name of the elastic cluster. */
    clusterName: string;
    /** The ARN of the elastic cluster. */
    clusterArn: string;
    /** The current status of the cluster, e.g. `ACTIVE`. */
    status: string;
    /** The MongoDB-compatible connection endpoint. */
    clusterEndpoint: string | undefined;
    /** The administrator username. */
    adminUserName: string;
    /** The authentication type (`PLAIN_TEXT` or `SECRET_ARN`). */
    authType: string;
    /** vCPU capacity of each shard (2, 4, 8, 16, 32, or 64). */
    shardCapacity: number;
    /** Number of shards in the cluster. */
    shardCount: number;
    /** Number of replica instances per shard. */
    shardInstanceCount: number | undefined;
    /** The VPC security groups attached to the cluster. */
    vpcSecurityGroupIds: string[];
    /** The subnets the cluster is deployed into. */
    subnetIds: string[];
    /** The KMS key used for encryption at rest. */
    kmsKeyId: string;
    /** The weekly window during which maintenance can occur. */
    preferredMaintenanceWindow: string;
    /** Number of days automated backups are retained. */
    backupRetentionPeriod: number | undefined;
    /** The daily window during which automated backups run. */
    preferredBackupWindow: string | undefined;
    /** The tags attached to the cluster. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon DocumentDB elastic cluster — a MongoDB-compatible, sharded
 * document database that scales workloads to millions of reads/writes per
 * second without managing instances.
 *
 * Elastic clusters take roughly 8-10 minutes to provision and bill per
 * shard-vCPU-hour while they exist. They are reachable only from inside a
 * VPC. Destroy clusters you are not using.
 * ### Creating a Cluster
 * **Example:** Minimal Elastic Cluster
 * ```typescript
 * const cluster = yield* Cluster("Documents", {
 *   adminUserName: "admin",
 *   adminUserPassword: Redacted.make("super-secret-password"),
 *   shardCapacity: 2,
 *   shardCount: 1,
 * });
 * ```
 *
 * **Example:** Cluster Pinned to Specific Subnets
 * ```typescript
 * const cluster = yield* Cluster("Documents", {
 *   adminUserName: "admin",
 *   adminUserPassword: Redacted.make("super-secret-password"),
 *   shardCapacity: 2,
 *   shardCount: 1,
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 *   vpcSecurityGroupIds: [securityGroup.securityGroupId],
 *   backupRetentionPeriod: "1 day",
 * });
 * ```
 *
 * @resource
 */
export const Cluster = Resource<Cluster>("AWS.DocDBElastic.Cluster");

const DEFAULT_AUTH_TYPE = "PLAIN_TEXT";
const DEFAULT_SHARD_CAPACITY = 2;
const DEFAULT_SHARD_COUNT = 1;

/** True when two string sets are equal ignoring order and duplicates. */
const sameStringSet = (
  a: readonly string[] | undefined,
  b: readonly string[] | undefined,
): boolean => {
  const left = [...new Set(a ?? [])].sort();
  const right = [...new Set(b ?? [])].sort();
  return left.length === right.length && left.every((v, i) => v === right[i]);
};

const toTagRecord = (
  tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
  );

export const ClusterProvider = () =>
  Provider.effect(
    Cluster,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<ClusterProps>) =>
        props.clusterName
          ? Effect.succeed(props.clusterName)
          : createPhysicalName({ id, maxLength: 50, lowercase: true });

      const getByArn = Effect.fn(function* (arn: string) {
        const response = yield* docdbelastic
          .getCluster({ clusterArn: arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.cluster;
      });

      // Elastic clusters are addressed by ARN (which embeds a server-side
      // UUID), so a name-based lookup scans the paginated list.
      const findByName = Effect.fn(function* (name: string) {
        const matches = yield* docdbelastic.listClusters.items({}).pipe(
          Stream.filter((cluster) => cluster.clusterName === name),
          Stream.take(1),
          Stream.runCollect,
        );
        const summary = Array.from(matches)[0];
        if (summary === undefined) return undefined;
        return yield* getByArn(summary.clusterArn);
      });

      const readCluster = Effect.fn(function* (name: string, arn: string | undefined) {
        if (arn !== undefined) {
          const cluster = yield* getByArn(arn);
          if (cluster !== undefined) return cluster;
        }
        return yield* findByName(name);
      });

      const readTags = Effect.fn(function* (arn: string) {
        const response = yield* docdbelastic
          .listTagsForResource({ resourceArn: arn })
          .pipe(Effect.orElseSucceed(() => undefined));
        return toTagRecord(response?.tags);
      });

      // Bounded readiness wait. Elastic cluster provisioning/modification
      // typically completes in 8-10 minutes; budget ~20 min (80 * 15s).
      const waitForActive = Effect.fn(function* (name: string, arn: string | undefined) {
        const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(80)]);
        return yield* readCluster(name, arn).pipe(
          Effect.flatMap((cluster) => {
            if (cluster === undefined) {
              return Effect.fail(
                new DocDBElasticClusterNotReady({ message: `Elastic cluster '${name}' not found` }),
              );
            }
            if (cluster.status !== "ACTIVE") {
              return Effect.fail(
                new DocDBElasticClusterNotReady({
                  message: `Elastic cluster '${name}' not active (status: ${cluster.status})`,
                }),
              );
            }
            return Effect.succeed(cluster);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      const toAttrs = Effect.fn(function* (cluster: docdbelastic.Cluster) {
        return {
          clusterName: cluster.clusterName,
          clusterArn: cluster.clusterArn,
          status: cluster.status,
          clusterEndpoint: cluster.clusterEndpoint,
          adminUserName: cluster.adminUserName,
          authType: cluster.authType,
          shardCapacity: cluster.shardCapacity,
          shardCount: cluster.shardCount,
          shardInstanceCount: cluster.shardInstanceCount,
          vpcSecurityGroupIds: [...cluster.vpcSecurityGroupIds],
          subnetIds: [...cluster.subnetIds],
          kmsKeyId: cluster.kmsKeyId,
          preferredMaintenanceWindow: cluster.preferredMaintenanceWindow,
          backupRetentionPeriod: cluster.backupRetentionPeriod,
          preferredBackupWindow: cluster.preferredBackupWindow,
          tags: yield* readTags(cluster.clusterArn),
        };
      });

      return {
        stables: ["clusterName", "clusterArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news;
          const o = olds;
          if (n === undefined || o === undefined) return undefined;
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          // Create-only properties force a replacement.
          if (n.adminUserName !== o.adminUserName) {
            return { action: "replace" } as const;
          }
          if ((n.kmsKeyId ?? undefined) !== (o.kmsKeyId ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name =
            output?.clusterName ??
            (yield* toName(
              id,
              olds ?? {
                adminUserName: "",
                adminUserPassword: Redacted.make(""),
              },
            ));
          const cluster = yield* readCluster(name, output?.clusterArn);
          if (cluster === undefined) return undefined;
          const attrs = yield* toAttrs(cluster);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
          const props = news!;
          const name = output?.clusterName ?? (yield* toName(id, props));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...props.tags };

          // 1. Observe — cloud state is authoritative; output is only an
          // ARN cache.
          let observed = yield* readCluster(name, output?.clusterArn);
          let created = false;

          // 2. Ensure — create if missing; tolerate a create race
          // (ConflictException) by re-reading.
          if (observed === undefined) {
            const response = yield* docdbelastic
              .createCluster({
                clusterName: name,
                adminUserName: props.adminUserName,
                adminUserPassword: props.adminUserPassword,
                authType: props.authType ?? DEFAULT_AUTH_TYPE,
                shardCapacity: props.shardCapacity ?? DEFAULT_SHARD_CAPACITY,
                shardCount: props.shardCount ?? DEFAULT_SHARD_COUNT,
                shardInstanceCount: props.shardInstanceCount,
                vpcSecurityGroupIds: props.vpcSecurityGroupIds,
                subnetIds: props.subnetIds,
                kmsKeyId: props.kmsKeyId,
                preferredMaintenanceWindow: props.preferredMaintenanceWindow,
                backupRetentionPeriod: toWireDays(props.backupRetentionPeriod),
                preferredBackupWindow: props.preferredBackupWindow,
                tags: desiredTags,
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
            observed = response?.cluster ?? (yield* findByName(name));
            created = true;
          }
          if (observed === undefined) {
            return yield* new DocDBElasticClusterUnexpectedResponse({
              message: `Elastic cluster '${name}' not found after create`,
            });
          }
          const arn = observed.clusterArn;

          // Provisioning and in-flight modifications both surface as a
          // non-ACTIVE status; wait (bounded) so update calls do not hit
          // ConflictException.
          observed = yield* waitForActive(name, arn);

          // 3. Sync — compute the update delta from OBSERVED state.
          const update: docdbelastic.UpdateClusterInput = { clusterArn: arn };
          let mutated = false;
          if (props.shardCapacity !== undefined && props.shardCapacity !== observed.shardCapacity) {
            update.shardCapacity = props.shardCapacity;
            mutated = true;
          }
          if (props.shardCount !== undefined && props.shardCount !== observed.shardCount) {
            update.shardCount = props.shardCount;
            mutated = true;
          }
          if (
            props.shardInstanceCount !== undefined &&
            props.shardInstanceCount !== observed.shardInstanceCount
          ) {
            update.shardInstanceCount = props.shardInstanceCount;
            mutated = true;
          }
          if (
            props.vpcSecurityGroupIds !== undefined &&
            !sameStringSet(props.vpcSecurityGroupIds, observed.vpcSecurityGroupIds)
          ) {
            update.vpcSecurityGroupIds = props.vpcSecurityGroupIds;
            mutated = true;
          }
          if (
            props.subnetIds !== undefined &&
            !sameStringSet(props.subnetIds, observed.subnetIds)
          ) {
            update.subnetIds = props.subnetIds;
            mutated = true;
          }
          if (
            props.preferredMaintenanceWindow !== undefined &&
            props.preferredMaintenanceWindow !== observed.preferredMaintenanceWindow
          ) {
            update.preferredMaintenanceWindow = props.preferredMaintenanceWindow;
            mutated = true;
          }
          const desiredRetentionDays = toWireDays(props.backupRetentionPeriod);
          if (
            desiredRetentionDays !== undefined &&
            desiredRetentionDays !== observed.backupRetentionPeriod
          ) {
            update.backupRetentionPeriod = desiredRetentionDays;
            mutated = true;
          }
          if (
            props.preferredBackupWindow !== undefined &&
            props.preferredBackupWindow !== observed.preferredBackupWindow
          ) {
            update.preferredBackupWindow = props.preferredBackupWindow;
            mutated = true;
          }
          if ((props.authType ?? DEFAULT_AUTH_TYPE) !== observed.authType) {
            update.authType = props.authType ?? DEFAULT_AUTH_TYPE;
            update.adminUserPassword = props.adminUserPassword;
            mutated = true;
          } else if (
            // The cloud never reports the password; the previously deployed
            // value is the only diff baseline (skipped right after create —
            // the password was just applied).
            !created &&
            olds !== undefined &&
            Redacted.value(props.adminUserPassword) !== Redacted.value(olds.adminUserPassword)
          ) {
            update.adminUserPassword = props.adminUserPassword;
            mutated = true;
          }
          if (mutated) {
            yield* docdbelastic.updateCluster(update);
            observed = yield* waitForActive(name, arn);
          }

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

          yield* session.note(name);
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          // A cluster mid-create/modify rejects deletion with
          // ConflictException — retry (bounded) while it settles. A cluster
          // already deleting (or gone) is success.
          //
          // Only an ACTIVE cluster is deletable: STOPPING, STOPPED and
          // STARTING all reject DeleteCluster with a ValidationException
          // ("Can't delete the cluster because it is in STOPPED state"). Wait
          // (bounded) for a stop/start to settle, then start a STOPPED
          // cluster and wait for ACTIVE before deleting it.
          const settled = yield* getByArn(output.clusterArn).pipe(
            Effect.repeat({
              schedule: Schedule.spaced("15 seconds"),
              until: (cluster) =>
                cluster === undefined ||
                (cluster.status !== "STOPPING" && cluster.status !== "STARTING"),
              times: 60,
            }),
          );
          if (settled === undefined || settled.status === "DELETING") {
            return;
          }
          if (settled.status === "STOPPED") {
            yield* docdbelastic
              .startCluster({ clusterArn: output.clusterArn })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
            yield* waitForActive(settled.clusterName, output.clusterArn);
          }
          yield* docdbelastic.deleteCluster({ clusterArn: output.clusterArn }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            Effect.retry({
              while: (e) => e._tag === "ConflictException",
              schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
            }),
          );
        }),

        list: () =>
          docdbelastic.listClusters.items({}).pipe(
            Stream.runCollect,
            Effect.flatMap((summaries) =>
              Effect.forEach(
                Array.from(summaries),
                (summary) =>
                  getByArn(summary.clusterArn).pipe(
                    Effect.flatMap((cluster) =>
                      cluster === undefined ? Effect.undefined : toAttrs(cluster),
                    ),
                  ),
                { concurrency: 4 },
              ),
            ),
            Effect.map((attrs) => attrs.filter((a): a is NonNullable<typeof a> => a !== undefined)),
          ),
      };
    }),
  );