sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DMS/ ReplicationInstance.ts

import * as dms from "@distilled.cloud/aws/database-migration-service";
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 * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

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

export interface ReplicationInstanceProps {
  /**
   * Replication-instance identifier. Must be lowercase, 1-63 characters,
   * begin with a letter, and contain only letters, digits, and hyphens. If
   * omitted, a deterministic physical name is generated. Changing it replaces
   * the instance.
   */
  replicationInstanceIdentifier?: string;
  /**
   * Compute and memory class, e.g. `"dms.t3.small"`, `"dms.c5.large"`.
   */
  replicationInstanceClass: string;
  /**
   * Storage in gigabytes allocated to the replication instance.
   * @default service-chosen for the instance class
   */
  allocatedStorage?: number;
  /**
   * VPC security group IDs controlling network access to the instance.
   */
  vpcSecurityGroupIds?: string[];
  /**
   * Availability Zone the instance is created in. Changing it replaces the
   * instance.
   */
  availabilityZone?: string;
  /**
   * Subnet group the instance is placed in. Changing it replaces the
   * instance.
   */
  replicationSubnetGroupIdentifier?: string;
  /**
   * Weekly maintenance window in `ddd:hh24:mi-ddd:hh24:mi` (UTC) format.
   */
  preferredMaintenanceWindow?: string;
  /**
   * Whether to provision the instance across multiple Availability Zones.
   * @default false
   */
  multiAZ?: boolean;
  /**
   * DMS engine version.
   * @default latest
   */
  engineVersion?: string;
  /**
   * Whether minor engine upgrades are applied automatically during the
   * maintenance window.
   * @default true
   */
  autoMinorVersionUpgrade?: boolean;
  /**
   * Customer-managed KMS key for storage encryption. Changing it replaces the
   * instance.
   * @default AWS-owned DMS key
   */
  kmsKeyId?: string;
  /**
   * Whether the instance gets a public IP address. Changing it replaces the
   * instance.
   * @default true
   */
  publiclyAccessible?: boolean;
  /**
   * Network type: `"IPV4"`, `"IPV6"`, or `"DUAL"`. Changing it replaces the
   * instance.
   */
  networkType?: string;
  /**
   * User-defined tags for the instance.
   */
  tags?: Record<string, string>;
}

export interface ReplicationInstance extends Resource<
  "AWS.DMS.ReplicationInstance",
  ReplicationInstanceProps,
  {
    /** The replication instance identifier (unique per account/region). */
    replicationInstanceIdentifier: string;
    /** The ARN of the replication instance. */
    replicationInstanceArn: string;
    /** The compute class of the instance, e.g. `dms.t3.small`. */
    replicationInstanceClass: string;
    /** The current status of the instance, e.g. `available`. */
    status: string | undefined;
    /** The DMS engine version running on the instance. */
    engineVersion: string | undefined;
    /** The private IP addresses of the instance. */
    privateIpAddresses: string[];
    /** The public IP addresses of the instance (when publicly accessible). */
    publicIpAddresses: string[];
    /** The tags attached to the replication instance. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A DMS replication instance — the managed compute that runs migration and
 * replication tasks. Provisioning takes several minutes and the instance is
 * billed hourly while it exists, so create it only when a migration is
 * running and destroy it promptly.
 * ### Creating a Replication Instance
 * **Example:** Small Instance in a Subnet Group
 * ```typescript
 * const instance = yield* ReplicationInstance("Migration", {
 *   replicationInstanceClass: "dms.t3.small",
 *   allocatedStorage: 50,
 *   replicationSubnetGroupIdentifier: subnetGroup.replicationSubnetGroupIdentifier,
 *   publiclyAccessible: false,
 * });
 * ```
 *
 * @resource
 */
export const ReplicationInstance = Resource<ReplicationInstance>("AWS.DMS.ReplicationInstance");

const toTagRecord = (
  tags: Array<{ Key?: string; Value?: string }> | undefined,
): Record<string, string> =>
  Object.fromEntries(
    (tags ?? [])
      .filter(
        (tag): tag is { Key: string; Value: string } =>
          typeof tag.Key === "string" && typeof tag.Value === "string",
      )
      .map((tag) => [tag.Key, tag.Value]),
  );

export const ReplicationInstanceProvider = () =>
  Provider.effect(
    ReplicationInstance,
    Effect.gen(function* () {
      const toName = (id: string, props: ReplicationInstanceProps) =>
        props.replicationInstanceIdentifier
          ? Effect.succeed(props.replicationInstanceIdentifier)
          : createPhysicalName({ id, maxLength: 60, lowercase: true });

      const findInstance = Effect.fn(function* (identifier: string) {
        const response = yield* dms
          .describeReplicationInstances({
            Filters: [{ Name: "replication-instance-id", Values: [identifier] }],
          })
          .pipe(Effect.catchTag("ResourceNotFoundFault", () => Effect.undefined));
        return response?.ReplicationInstances?.[0];
      });

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

      // Provisioning and modifications both surface as a transitional status;
      // budget ~15 minutes (15s x 60) for the instance to become available.
      const waitForInstance = Effect.fn(function* (identifier: string) {
        const readinessPolicy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
        return yield* findInstance(identifier).pipe(
          Effect.flatMap((instance) => {
            if (!instance?.ReplicationInstanceArn) {
              return Effect.fail(
                new ReplicationInstanceNotReady({
                  message: `DMS replication instance '${identifier}' not found`,
                }),
              );
            }
            if (instance.ReplicationInstanceStatus !== "available") {
              return Effect.fail(
                new ReplicationInstanceNotReady({
                  message: `DMS replication instance '${identifier}' not available (status: ${instance.ReplicationInstanceStatus})`,
                }),
              );
            }
            return Effect.succeed(instance);
          }),
          Effect.retry({ schedule: readinessPolicy }),
        );
      });

      const toAttrs = Effect.fn(function* (instance: dms.ReplicationInstance) {
        const identifier = instance.ReplicationInstanceIdentifier;
        if (!identifier || !instance.ReplicationInstanceArn) {
          return yield* new ReplicationInstanceUnexpectedResponse({
            message: `DMS replication instance '${identifier}' is missing its identifier or ARN`,
          });
        }
        return {
          replicationInstanceIdentifier: identifier,
          replicationInstanceArn: instance.ReplicationInstanceArn,
          replicationInstanceClass: instance.ReplicationInstanceClass ?? "",
          status: instance.ReplicationInstanceStatus,
          engineVersion: instance.EngineVersion,
          privateIpAddresses: [...(instance.ReplicationInstancePrivateIpAddresses ?? [])],
          publicIpAddresses: [...(instance.ReplicationInstancePublicIpAddresses ?? [])],
          tags: yield* readTags(instance.ReplicationInstanceArn),
        };
      });

      return {
        stables: ["replicationInstanceIdentifier", "replicationInstanceArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          if (
            (yield* toName(
              id,
              olds ??
                ({
                  replicationInstanceClass: "",
                } as ReplicationInstanceProps),
            )) !== (yield* toName(id, news))
          ) {
            return { action: "replace" } as const;
          }
          // Create-only properties force a replacement.
          if ((news.publiclyAccessible ?? undefined) !== (olds?.publiclyAccessible ?? undefined)) {
            return { action: "replace" } as const;
          }
          if ((news.kmsKeyId ?? undefined) !== (olds?.kmsKeyId ?? undefined)) {
            return { action: "replace" } as const;
          }
          if ((news.availabilityZone ?? undefined) !== (olds?.availabilityZone ?? undefined)) {
            return { action: "replace" } as const;
          }
          if (
            (news.replicationSubnetGroupIdentifier ?? undefined) !==
            (olds?.replicationSubnetGroupIdentifier ?? undefined)
          ) {
            return { action: "replace" } as const;
          }
          if ((news.networkType ?? undefined) !== (olds?.networkType ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name =
            output?.replicationInstanceIdentifier ??
            (yield* toName(
              id,
              olds ??
                ({
                  replicationInstanceClass: "",
                } as ReplicationInstanceProps),
            ));
          const instance = yield* findInstance(name);
          if (!instance?.ReplicationInstanceArn) return undefined;
          const attrs = yield* toAttrs(instance);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

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

          // 1. Observe — cloud state is authoritative.
          let observed = yield* findInstance(name);

          // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
          if (observed === undefined) {
            yield* dms
              .createReplicationInstance({
                ReplicationInstanceIdentifier: name,
                ReplicationInstanceClass: news.replicationInstanceClass,
                AllocatedStorage: news.allocatedStorage,
                VpcSecurityGroupIds: news.vpcSecurityGroupIds,
                AvailabilityZone: news.availabilityZone,
                ReplicationSubnetGroupIdentifier: news.replicationSubnetGroupIdentifier,
                PreferredMaintenanceWindow: news.preferredMaintenanceWindow,
                MultiAZ: news.multiAZ,
                EngineVersion: news.engineVersion,
                AutoMinorVersionUpgrade: news.autoMinorVersionUpgrade,
                KmsKeyId: news.kmsKeyId,
                PubliclyAccessible: news.publiclyAccessible,
                NetworkType: news.networkType,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("ResourceAlreadyExistsFault", () => Effect.void));
          }

          // Wait for availability so sync/modify calls don't hit
          // InvalidResourceStateFault.
          observed = yield* waitForInstance(name);

          // 3. Sync — compute the modify delta from OBSERVED state. Immutable
          //    properties are handled by diff (replacement), so only mutable
          //    aspects are compared here.
          const modify: dms.ModifyReplicationInstanceMessage = {
            ReplicationInstanceArn: observed.ReplicationInstanceArn!,
            ApplyImmediately: true,
          };
          let dirty = false;
          if (news.replicationInstanceClass !== observed.ReplicationInstanceClass) {
            modify.ReplicationInstanceClass = news.replicationInstanceClass;
            dirty = true;
          }
          if (
            news.allocatedStorage !== undefined &&
            news.allocatedStorage !== observed.AllocatedStorage
          ) {
            modify.AllocatedStorage = news.allocatedStorage;
            dirty = true;
          }
          if (news.multiAZ !== undefined && news.multiAZ !== observed.MultiAZ) {
            modify.MultiAZ = news.multiAZ;
            dirty = true;
          }
          if (news.engineVersion !== undefined && news.engineVersion !== observed.EngineVersion) {
            modify.EngineVersion = news.engineVersion;
            modify.AllowMajorVersionUpgrade = true;
            dirty = true;
          }
          if (
            news.preferredMaintenanceWindow !== undefined &&
            news.preferredMaintenanceWindow !== observed.PreferredMaintenanceWindow
          ) {
            modify.PreferredMaintenanceWindow = news.preferredMaintenanceWindow;
            dirty = true;
          }

          if (dirty) {
            yield* dms.modifyReplicationInstance(modify);
            observed = yield* waitForInstance(name);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const arn = observed.ReplicationInstanceArn!;
          const observedTags = yield* readTags(arn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* dms.addTagsToResource({ ResourceArn: arn, Tags: upsert });
          }
          if (removed.length > 0) {
            yield* dms.removeTagsFromResource({
              ResourceArn: arn,
              TagKeys: removed,
            });
          }

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

        delete: Effect.fn(function* ({ output }) {
          // Converge to "gone", not just "delete requested": a `deleting`
          // instance still holds its replication subnet group, so deleting
          // the group right after fails with InvalidResourceStateFault
          // ("Cannot delete the subnet group ... because at least one
          // replication instance ... is using it"). Each attempt observes the
          // instance; a mid-create/modify instance rejects deletion with
          // InvalidResourceStateFault until it settles, so retry then too.
          // Instance deletion takes ~5-10 minutes; budget ~15 min (15s x 60).
          yield* Effect.gen(function* () {
            const instance = yield* findInstance(output.replicationInstanceIdentifier);
            if (instance === undefined) return;
            if (instance.ReplicationInstanceStatus !== "deleting") {
              yield* dms
                .deleteReplicationInstance({
                  ReplicationInstanceArn: output.replicationInstanceArn,
                })
                .pipe(
                  Effect.catchTags({
                    ResourceNotFoundFault: () => Effect.void,
                    InvalidResourceStateFault: () => Effect.void,
                  }),
                );
            }
            return yield* new ReplicationInstanceNotReady({
              message: `DMS replication instance '${output.replicationInstanceIdentifier}' still exists (status: ${instance.ReplicationInstanceStatus})`,
            });
          }).pipe(
            Effect.retry({
              schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
            }),
          );
        }),

        list: () =>
          dms.describeReplicationInstances.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.ReplicationInstances ?? []).filter(
                  (instance) =>
                    instance.ReplicationInstanceIdentifier !== undefined &&
                    instance.ReplicationInstanceArn !== undefined,
                ),
              ),
            ),
            Effect.flatMap(
              Effect.forEach((instance) => toAttrs(instance), {
                concurrency: 4,
              }),
            ),
          ),
      };
    }),
  );