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

import * as redshift from "@distilled.cloud/aws/redshift";
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 type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import { durationToDays, unwrapRedactedString } from "../IAM/common.ts";
import type { Providers } from "../Providers.ts";
import { applyRedshiftTagDelta, redshiftArn, sameStringSet, toTagRecord } from "./internal.ts";

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

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

/**
 * Creating a provisioned Redshift cluster requires either a
 * `masterUserPassword` or `manageMasterPassword: true`.
 */
export class RedshiftMasterPasswordRequired extends Data.TaggedError(
  "RedshiftMasterPasswordRequired",
)<{
  readonly clusterIdentifier: string;
}> {}

export interface ClusterProps {
  /**
   * Unique identifier of the cluster. Must be 1-63 lowercase alphanumeric
   * characters or hyphens, starting with a letter. If omitted, a
   * deterministic physical name is generated. Changing the identifier
   * replaces the cluster.
   */
  clusterIdentifier?: string;
  /**
   * Node type of the cluster, e.g. `ra3.large`, `ra3.xlplus` or
   * `dc2.large`. Changing the node type triggers an in-place resize.
   * @default "ra3.large"
   */
  nodeType?: string;
  /**
   * Number of compute nodes. `1` provisions a single-node cluster; any
   * larger value provisions a multi-node cluster. Changing the count
   * triggers an in-place resize.
   * @default 1
   */
  numberOfNodes?: number;
  /**
   * Admin username for the cluster database. Changing the username replaces
   * the cluster.
   * @default "awsuser"
   */
  masterUsername?: string;
  /**
   * Admin password. Must be 8-64 characters with at least one uppercase
   * letter, one lowercase letter and one number. Provide this or set
   * `manageMasterPassword`.
   */
  masterUserPassword?: Redacted.Redacted<string>;
  /**
   * Let Amazon Redshift manage the admin password in Secrets Manager
   * instead of supplying `masterUserPassword`. The secret ARN is surfaced
   * as the `masterPasswordSecretArn` attribute.
   * @default false
   */
  manageMasterPassword?: boolean;
  /**
   * Name of the initial database created in the cluster. Changing the
   * database name replaces the cluster.
   * @default "dev"
   */
  dbName?: string;
  /**
   * Name of the {@link ClusterSubnetGroup} the cluster's nodes are placed
   * into. Changing the subnet group replaces the cluster.
   * @default the default cluster subnet group
   */
  clusterSubnetGroupName?: string;
  /**
   * VPC security group IDs that control network access to the cluster
   * endpoint.
   * @default the VPC's default security group
   */
  vpcSecurityGroupIds?: string[];
  /**
   * Name of the {@link ClusterParameterGroup} applied to the cluster.
   * @default the family's default parameter group
   */
  clusterParameterGroupName?: string;
  /**
   * Whether the cluster endpoint is reachable from the public internet.
   * @default false
   */
  publiclyAccessible?: boolean;
  /**
   * Whether data at rest is encrypted. RA3 node types are always encrypted.
   * @default true
   */
  encrypted?: boolean;
  /**
   * Customer-managed KMS key used for encryption at rest.
   * @default AWS-owned Redshift key
   */
  kmsKeyId?: string;
  /**
   * Port the cluster database accepts connections on. Changing the port
   * replaces the cluster.
   * @default 5439
   */
  port?: number;
  /**
   * Availability Zone the cluster is provisioned in. Changing the AZ
   * replaces the cluster.
   * @default chosen by Redshift
   */
  availabilityZone?: string;
  /**
   * Weekly maintenance window, e.g. `sun:05:00-sun:05:30` (UTC).
   */
  preferredMaintenanceWindow?: string;
  /**
   * How long automated snapshots are retained, e.g. `"7 days"` or
   * `Duration.days(7)` (a bare number is milliseconds). Rounded to whole
   * days on the wire; zero disables automated snapshots.
   */
  automatedSnapshotRetentionPeriod?: Duration.Input;
  /**
   * Whether major engine upgrades may be applied during the maintenance
   * window.
   * @default true
   */
  allowVersionUpgrade?: boolean;
  /**
   * Whether enhanced VPC routing forces COPY/UNLOAD traffic through the
   * VPC.
   * @default false
   */
  enhancedVpcRouting?: boolean;
  /**
   * IAM role ARNs the cluster can assume for COPY/UNLOAD and federated
   * queries (max 50).
   */
  iamRoles?: string[];
  /**
   * User-defined tags for the cluster.
   */
  tags?: Record<string, string>;
}

export interface Cluster extends Resource<
  "AWS.Redshift.Cluster",
  ClusterProps,
  {
    /**
     * Unique identifier of the cluster.
     */
    clusterIdentifier: string;
    /**
     * ARN of the cluster.
     */
    clusterArn: string;
    /**
     * ARN of the cluster's namespace (used by datashares and the Data API).
     */
    clusterNamespaceArn: string | undefined;
    /**
     * Current cluster status (e.g. `"available"`).
     */
    clusterStatus: string;
    /**
     * Node type of the cluster (e.g. `"ra3.large"`).
     */
    nodeType: string;
    /**
     * Number of compute nodes in the cluster.
     */
    numberOfNodes: number;
    /**
     * Name of the initial database.
     */
    dbName: string;
    /**
     * Admin (master) user name.
     */
    masterUsername: string | undefined;
    /**
     * DNS address of the cluster endpoint (pgwire host).
     */
    endpointAddress: string | undefined;
    /**
     * Port of the cluster endpoint (5439 by default).
     */
    endpointPort: number | undefined;
    /**
     * ID of the VPC the cluster runs in.
     */
    vpcId: string | undefined;
    /**
     * Availability zone the cluster is placed in.
     */
    availabilityZone: string | undefined;
    /**
     * Name of the cluster subnet group the cluster is placed in, if any.
     */
    clusterSubnetGroupName: string | undefined;
    /**
     * Whether the cluster endpoint is reachable from the public internet.
     */
    publiclyAccessible: boolean | undefined;
    /**
     * Whether the cluster's data is encrypted at rest.
     */
    encrypted: boolean | undefined;
    /**
     * KMS key encrypting the cluster, if any.
     */
    kmsKeyId: string | undefined;
    /**
     * ARN of the Secrets Manager secret holding the admin password when
     * `manageMasterPassword` is enabled.
     */
    masterPasswordSecretArn: string | undefined;
    /**
     * Tags on the cluster (including internal Alchemy tags).
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A provisioned Amazon Redshift data-warehouse cluster.
 *
 * Clusters take roughly 5-10 minutes to provision and are billed hourly per
 * node while they exist (`ra3.large` and `dc2.large` are the smallest node
 * types). For serverless data warehousing see the `RedshiftServerless`
 * namespace instead. Destroy clusters you are not using.
 * ### Creating a Cluster
 * **Example:** Single-Node Cluster
 * ```typescript
 * const cluster = yield* Redshift.Cluster("Warehouse", {
 *   nodeType: "ra3.large",
 *   numberOfNodes: 1,
 *   masterUsername: "admin",
 *   masterUserPassword: warehousePassword,
 *   dbName: "analytics",
 * });
 * ```
 * **Example:** Cluster in a VPC Subnet Group
 * ```typescript
 * const subnetGroup = yield* Redshift.ClusterSubnetGroup("WarehouseSubnets", {
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 * });
 * const cluster = yield* Redshift.Cluster("Warehouse", {
 *   nodeType: "ra3.large",
 *   numberOfNodes: 2,
 *   masterUsername: "admin",
 *   manageMasterPassword: true,
 *   clusterSubnetGroupName: subnetGroup.clusterSubnetGroupName,
 *   publiclyAccessible: false,
 *   encrypted: true,
 * });
 * ```
 *
 * @resource
 */
export const Cluster = Resource<Cluster>("AWS.Redshift.Cluster");

const DEFAULT_NODE_TYPE = "ra3.large";
const DEFAULT_MASTER_USERNAME = "awsuser";
const DEFAULT_DB_NAME = "dev";

/**
 * Retry an effect while the cluster is mid-transition
 * (`InvalidClusterStateFault`), bounded to ~5 minutes.
 *
 * Expressed as an explicitly-typed module-scope helper: inlining
 * `Effect.retry` in a lifecycle operation leaves `Retry.Return`'s
 * conditional type unresolved in the provider's inferred layer type, which
 * declaration emit widens to an `unknown` R — poisoning `AWS.providers()`
 * for every downstream consumer.
 */
const retryWhileClusterTransitioning = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "InvalidClusterStateFault",
    schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(20)]),
  });

/**
 * Bounded status polling (~20 minutes; cluster provisioning/resizing
 * typically completes in 5-10). Same explicit-annotation rationale as
 * {@link retryWhileClusterTransitioning}.
 */
const retryUntilSettled = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(80)]),
  });

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

      const readCluster = Effect.fn(function* (identifier: string) {
        const response = yield* redshift
          .describeClusters({ ClusterIdentifier: identifier })
          .pipe(Effect.catchTag("ClusterNotFoundFault", () => Effect.undefined));
        return response?.Clusters?.[0];
      });

      const waitForAvailable = Effect.fn(function* (identifier: string) {
        return yield* retryUntilSettled(
          readCluster(identifier).pipe(
            Effect.flatMap((cluster) => {
              if (cluster === undefined) {
                return Effect.fail(
                  new RedshiftClusterNotReady({ message: `Cluster '${identifier}' not found` }),
                );
              }
              if (cluster.ClusterStatus !== "available") {
                return Effect.fail(
                  new RedshiftClusterNotReady({
                    message: `Cluster '${identifier}' not available (status: ${cluster.ClusterStatus})`,
                  }),
                );
              }
              return Effect.succeed(cluster);
            }),
          ),
        );
      });

      // Wait for a cluster to leave a transitional state before delete.
      // Ends when the cluster is available, deleting, or gone.
      const waitUntilSettled = Effect.fn(function* (identifier: string) {
        return yield* retryUntilSettled(
          readCluster(identifier).pipe(
            Effect.flatMap((cluster) => {
              if (
                cluster !== undefined &&
                cluster.ClusterStatus !== "available" &&
                cluster.ClusterStatus !== "deleting"
              ) {
                return Effect.fail(
                  new RedshiftClusterNotReady({
                    message: `Cluster '${identifier}' still settling (status: ${cluster.ClusterStatus})`,
                  }),
                );
              }
              return Effect.succeed(cluster);
            }),
          ),
        );
      });

      const toAttrs = Effect.fn(function* (cluster: redshift.Cluster) {
        const { accountId, region } = yield* AWSEnvironment.current;
        if (!cluster.ClusterIdentifier) {
          return yield* new RedshiftClusterUnexpectedResponse({
            message: "Cluster is missing its identifier",
          });
        }
        return {
          clusterIdentifier: cluster.ClusterIdentifier,
          clusterArn: redshiftArn(region, accountId, "cluster", cluster.ClusterIdentifier),
          clusterNamespaceArn: cluster.ClusterNamespaceArn,
          clusterStatus: cluster.ClusterStatus ?? "available",
          nodeType: cluster.NodeType ?? DEFAULT_NODE_TYPE,
          numberOfNodes: cluster.NumberOfNodes ?? 1,
          dbName: cluster.DBName ?? DEFAULT_DB_NAME,
          masterUsername: cluster.MasterUsername,
          endpointAddress: cluster.Endpoint?.Address,
          endpointPort: cluster.Endpoint?.Port,
          vpcId: cluster.VpcId,
          availabilityZone: cluster.AvailabilityZone,
          clusterSubnetGroupName: cluster.ClusterSubnetGroupName,
          publiclyAccessible: cluster.PubliclyAccessible,
          encrypted: cluster.Encrypted,
          kmsKeyId: cluster.KmsKeyId,
          masterPasswordSecretArn: cluster.MasterPasswordSecretArn,
          tags: toTagRecord(cluster.Tags),
        };
      });

      return {
        stables: ["clusterIdentifier", "clusterArn", "clusterNamespaceArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? {};
          const o = olds ?? {};
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          // Create-only properties force a replacement.
          if ((n.dbName ?? DEFAULT_DB_NAME) !== (o.dbName ?? DEFAULT_DB_NAME)) {
            return { action: "replace" } as const;
          }
          if (
            (n.masterUsername ?? DEFAULT_MASTER_USERNAME) !==
            (o.masterUsername ?? DEFAULT_MASTER_USERNAME)
          ) {
            return { action: "replace" } as const;
          }
          if (
            n.clusterSubnetGroupName !== undefined &&
            o.clusterSubnetGroupName !== undefined &&
            n.clusterSubnetGroupName !== o.clusterSubnetGroupName
          ) {
            return { action: "replace" } as const;
          }
          if ((n.port ?? undefined) !== (o.port ?? undefined)) {
            return { action: "replace" } as const;
          }
          if ((n.availabilityZone ?? undefined) !== (o.availabilityZone ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const identifier = output?.clusterIdentifier ?? (yield* toName(id, olds ?? {}));
          const cluster = yield* readCluster(identifier);
          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 identifier = output?.clusterIdentifier ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredNodes = news.numberOfNodes ?? 1;
          const desiredNodeType = news.nodeType ?? DEFAULT_NODE_TYPE;
          const clusterType = desiredNodes > 1 ? "multi-node" : "single-node";

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

          // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
          if (observed === undefined) {
            if (!news.masterUserPassword && !news.manageMasterPassword) {
              return yield* new RedshiftMasterPasswordRequired({
                clusterIdentifier: identifier,
              });
            }
            yield* redshift
              .createCluster({
                ClusterIdentifier: identifier,
                NodeType: desiredNodeType,
                ClusterType: clusterType,
                NumberOfNodes: desiredNodes > 1 ? desiredNodes : undefined,
                MasterUsername: news.masterUsername ?? DEFAULT_MASTER_USERNAME,
                MasterUserPassword: news.manageMasterPassword ? undefined : news.masterUserPassword,
                ManageMasterPassword: news.manageMasterPassword,
                DBName: news.dbName ?? DEFAULT_DB_NAME,
                ClusterSubnetGroupName: news.clusterSubnetGroupName,
                VpcSecurityGroupIds: news.vpcSecurityGroupIds,
                ClusterParameterGroupName: news.clusterParameterGroupName,
                PubliclyAccessible: news.publiclyAccessible ?? false,
                Encrypted: news.encrypted ?? true,
                KmsKeyId: news.kmsKeyId,
                Port: news.port,
                AvailabilityZone: news.availabilityZone,
                PreferredMaintenanceWindow: news.preferredMaintenanceWindow,
                AutomatedSnapshotRetentionPeriod: durationToDays(
                  news.automatedSnapshotRetentionPeriod,
                ),
                AllowVersionUpgrade: news.allowVersionUpgrade,
                EnhancedVpcRouting: news.enhancedVpcRouting,
                IamRoles: news.iamRoles,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("ClusterAlreadyExistsFault", () => Effect.undefined));
          }

          // Provisioning and in-flight modifications both surface as a
          // non-available status; wait (bounded) so modify calls do not hit
          // InvalidClusterStateFault.
          observed = yield* waitForAvailable(identifier);

          // 3. Sync — compute the update delta from OBSERVED state.
          const update: redshift.ModifyClusterMessage = {
            ClusterIdentifier: identifier,
          };
          let mutated = false;
          if (
            desiredNodeType !== observed.NodeType ||
            desiredNodes !== (observed.NumberOfNodes ?? 1)
          ) {
            // Resizes must specify node type, count and cluster type
            // together even when only one of them changes.
            update.NodeType = desiredNodeType;
            update.NumberOfNodes = desiredNodes;
            update.ClusterType = clusterType;
            mutated = true;
          }
          const observedSecurityGroups = (observed.VpcSecurityGroups ?? []).flatMap((group) =>
            group.VpcSecurityGroupId ? [group.VpcSecurityGroupId] : [],
          );
          if (
            news.vpcSecurityGroupIds !== undefined &&
            !sameStringSet(news.vpcSecurityGroupIds, observedSecurityGroups)
          ) {
            update.VpcSecurityGroupIds = news.vpcSecurityGroupIds;
            mutated = true;
          }
          if (
            news.clusterParameterGroupName !== undefined &&
            !(observed.ClusterParameterGroups ?? []).some(
              (group) => group.ParameterGroupName === news.clusterParameterGroupName,
            )
          ) {
            update.ClusterParameterGroupName = news.clusterParameterGroupName;
            mutated = true;
          }
          if (
            news.publiclyAccessible !== undefined &&
            news.publiclyAccessible !== observed.PubliclyAccessible
          ) {
            update.PubliclyAccessible = news.publiclyAccessible;
            mutated = true;
          }
          if (news.encrypted !== undefined && news.encrypted !== observed.Encrypted) {
            update.Encrypted = news.encrypted;
            update.KmsKeyId = news.kmsKeyId;
            mutated = true;
          } else if (news.kmsKeyId !== undefined && news.kmsKeyId !== observed.KmsKeyId) {
            update.Encrypted = news.encrypted ?? true;
            update.KmsKeyId = news.kmsKeyId;
            mutated = true;
          }
          if (
            news.preferredMaintenanceWindow !== undefined &&
            news.preferredMaintenanceWindow !== observed.PreferredMaintenanceWindow
          ) {
            update.PreferredMaintenanceWindow = news.preferredMaintenanceWindow;
            mutated = true;
          }
          const desiredRetentionDays = durationToDays(news.automatedSnapshotRetentionPeriod);
          if (
            desiredRetentionDays !== undefined &&
            desiredRetentionDays !== observed.AutomatedSnapshotRetentionPeriod
          ) {
            update.AutomatedSnapshotRetentionPeriod = desiredRetentionDays;
            mutated = true;
          }
          if (
            news.allowVersionUpgrade !== undefined &&
            news.allowVersionUpgrade !== observed.AllowVersionUpgrade
          ) {
            update.AllowVersionUpgrade = news.allowVersionUpgrade;
            mutated = true;
          }
          if (
            news.enhancedVpcRouting !== undefined &&
            news.enhancedVpcRouting !== observed.EnhancedVpcRouting
          ) {
            update.EnhancedVpcRouting = news.enhancedVpcRouting;
            mutated = true;
          }
          // The live password is unobservable — apply it only when the
          // declared value actually changed (olds is a hint, never truth).
          if (
            olds !== undefined &&
            news.masterUserPassword !== undefined &&
            (olds.masterUserPassword === undefined ||
              unwrapRedactedString(news.masterUserPassword) !==
                unwrapRedactedString(olds.masterUserPassword))
          ) {
            update.MasterUserPassword = news.masterUserPassword;
            mutated = true;
          }
          if (
            news.manageMasterPassword === true &&
            observed.MasterPasswordSecretArn === undefined
          ) {
            update.ManageMasterPassword = true;
            mutated = true;
          }

          if (mutated) {
            yield* retryWhileClusterTransitioning(redshift.modifyCluster(update));
            observed = yield* waitForAvailable(identifier);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags (describe
          //     surfaces them inline).
          const { accountId, region } = yield* AWSEnvironment.current;
          const arn = redshiftArn(region, accountId, "cluster", identifier);
          const { removed, upsert } = diffTags(toTagRecord(observed.Tags), desiredTags);
          yield* applyRedshiftTagDelta({ arn, upsert, removed });

          yield* session.note(arn);
          const attrs = yield* toAttrs(observed);
          return { ...attrs, tags: desiredTags };
        }),

        delete: Effect.fn(function* ({ output }) {
          const identifier = output.clusterIdentifier;
          // A cluster mid-create/modify rejects deletion with
          // InvalidClusterStateFault — wait (bounded) for it to settle
          // first. A cluster already deleting (or gone) is success.
          yield* waitUntilSettled(identifier).pipe(Effect.orElseSucceed(() => undefined));
          yield* retryWhileClusterTransitioning(
            redshift
              .deleteCluster({
                ClusterIdentifier: identifier,
                SkipFinalClusterSnapshot: true,
              })
              .pipe(Effect.catchTag("ClusterNotFoundFault", () => Effect.undefined)),
          ).pipe(Effect.catchTag("InvalidClusterStateFault", () => Effect.void));
        }),

        list: () =>
          // Top-level account/region collection: exhaustively paginate
          // describeClusters; tags come inline on each cluster.
          redshift.describeClusters.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.Clusters ?? []).filter((cluster) => cluster.ClusterIdentifier !== undefined),
              ),
            ),
            Effect.flatMap(
              Effect.forEach((cluster) => toAttrs(cluster), {
                concurrency: 4,
              }),
            ),
          ),
      };
    }),
  );