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

import * as dax from "@distilled.cloud/aws/dax";
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 type { Providers } from "../Providers.ts";
import { readDaxTags, sameStringSet } from "./internal.ts";

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

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

export interface ClusterProps {
  /**
   * Name of the cluster. Must be 1-20 alphanumeric characters or hyphens.
   * If omitted, a deterministic physical name is generated. Changing the
   * name replaces the cluster.
   */
  clusterName?: string;
  /**
   * Compute and memory capacity of the nodes, e.g. `"dax.t3.small"` (the
   * cheapest supported node type) or `"dax.r5.large"`. Changing the node
   * type replaces the cluster.
   * @default "dax.t3.small"
   */
  nodeType?: string;
  /**
   * Number of nodes in the cluster (1 = a single node; 2+ = one primary
   * plus read replicas). AWS recommends at least 3 nodes (spanning multiple
   * Availability Zones) for production. Updated in place via
   * IncreaseReplicationFactor / DecreaseReplicationFactor.
   * @default 1
   */
  replicationFactor?: number;
  /**
   * ARN of the IAM role that DAX assumes to access DynamoDB tables on your
   * behalf. The role's trust policy must allow `dax.amazonaws.com` to assume
   * it. Changing the role replaces the cluster.
   */
  iamRoleArn: string;
  /**
   * Human-readable description of the cluster.
   */
  description?: string;
  /**
   * Availability Zones the nodes are placed into. Must be a subset of the
   * AZs covered by the subnet group and match `replicationFactor` in length
   * when provided. Changing the AZs replaces the cluster.
   * @default DAX spreads nodes across the subnet group's AZs
   */
  availabilityZones?: string[];
  /**
   * Name of the {@link SubnetGroup} the cluster's nodes are placed into.
   * Changing the subnet group replaces the cluster.
   * @default the default DAX subnet group
   */
  subnetGroupName?: string;
  /**
   * VPC security groups that control network access to the cluster
   * endpoint.
   * @default the VPC's default security group
   */
  securityGroupIds?: string[];
  /**
   * Weekly maintenance window, e.g. `"sun:23:00-mon:01:30"` (UTC).
   */
  preferredMaintenanceWindow?: string;
  /**
   * SNS topic ARN to publish cluster events to.
   */
  notificationTopicArn?: string;
  /**
   * Name of the {@link ParameterGroup} applied to the cluster.
   * @default the default DAX parameter group
   */
  parameterGroupName?: string;
  /**
   * Whether server-side encryption (encryption at rest) is enabled.
   * Changing this replaces the cluster.
   * @default false
   */
  sseEnabled?: boolean;
  /**
   * Encryption in transit for the cluster endpoint — `"NONE"` or `"TLS"`.
   * Changing this replaces the cluster.
   * @default "NONE"
   */
  clusterEndpointEncryptionType?: dax.ClusterEndpointEncryptionType;
  /**
   * IP address type — `"ipv4"`, `"ipv6"` or `"dual_stack"`. Changing this
   * replaces the cluster.
   * @default "ipv4"
   */
  networkType?: dax.NetworkType;
  /**
   * User-defined tags for the cluster.
   */
  tags?: Record<string, string>;
}

export interface Cluster extends Resource<
  "AWS.DAX.Cluster",
  ClusterProps,
  {
    /** Name of the DAX cluster. */
    clusterName: string;
    /** ARN of the DAX cluster. */
    clusterArn: string;
    /** Current cluster status (e.g. `available`, `creating`). */
    status: string;
    /** Compute/memory node type of the cluster's nodes. */
    nodeType: string;
    /** Total number of nodes in the cluster. */
    totalNodes: number | undefined;
    /** Number of nodes currently in `available` status. */
    activeNodes: number | undefined;
    /** Hostname of the cluster discovery endpoint. */
    discoveryEndpointAddress: string | undefined;
    /** Port of the cluster discovery endpoint. */
    discoveryEndpointPort: number | undefined;
    /** Full `dax://` (or `daxs://` for TLS) discovery endpoint URL clients connect to. */
    discoveryEndpointUrl: string | undefined;
    /** Name of the subnet group the cluster's nodes are placed into. */
    subnetGroupName: string | undefined;
    /** ARN of the IAM role DAX assumes to reach DynamoDB. */
    iamRoleArn: string | undefined;
    /** Name of the parameter group attached to the cluster. */
    parameterGroupName: string | undefined;
    /** Security group IDs attached to the cluster's nodes. */
    securityGroupIds: string[];
    /** Endpoint encryption in transit (`NONE` or `TLS`). */
    clusterEndpointEncryptionType: string | undefined;
    /** Current tags on the cluster. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon DAX cluster — a fully managed, in-memory write-through cache for
 * DynamoDB.
 *
 * Clusters are VPC-only and take roughly 5-10 minutes to provision; they are
 * billed per node-hour while they exist. Place them in a {@link SubnetGroup}
 * and give them an IAM role that DAX assumes to reach DynamoDB. Destroy
 * clusters you are not using.
 * ### Creating a Cluster
 * **Example:** Single-Node Development Cluster
 * ```typescript
 * const role = yield* IAM.Role("DaxRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: { Service: "dax.amazonaws.com" },
 *       Action: ["sts:AssumeRole"],
 *     }],
 *   },
 *   managedPolicyArns: ["arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"],
 * });
 * const subnetGroup = yield* SubnetGroup("DaxSubnets", {
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 * });
 * const cluster = yield* Cluster("Cache", {
 *   nodeType: "dax.t3.small",
 *   replicationFactor: 1,
 *   iamRoleArn: role.roleArn,
 *   subnetGroupName: subnetGroup.subnetGroupName,
 * });
 * ```
 *
 * ### Encryption
 * **Example:** Cluster with Encryption At Rest and In Transit
 * ```typescript
 * const cluster = yield* Cluster("SecureCache", {
 *   nodeType: "dax.t3.small",
 *   replicationFactor: 3,
 *   iamRoleArn: role.roleArn,
 *   subnetGroupName: subnetGroup.subnetGroupName,
 *   sseEnabled: true,
 *   clusterEndpointEncryptionType: "TLS",
 * });
 * ```
 *
 * @resource
 */
export const Cluster = Resource<Cluster>("AWS.DAX.Cluster");

const DEFAULT_NODE_TYPE = "dax.t3.small";
const DEFAULT_REPLICATION_FACTOR = 1;

// A freshly created IAM role is not immediately assumable by dax.amazonaws.com
// — CreateCluster rejects with "No permission to assume role" until IAM
// propagates (typically a few seconds). Bounded retry through that window.
const retryIamRolePropagation = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) =>
      e._tag === "InvalidParameterValueException" &&
      ((e as { message?: string }).message?.includes("No permission to assume role") ?? false),
    schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
  });

export const ClusterProvider = () =>
  Provider.effect(
    Cluster,
    Effect.gen(function* () {
      // DAX cluster names must start with a letter. At its 20-character limit
      // a generated name is all hash and instance suffix, which can start
      // with a digit, so lead with a letter then.
      const toName = (id: string, props: Partial<ClusterProps>) =>
        props.clusterName
          ? Effect.succeed(props.clusterName)
          : createPhysicalName({ id, maxLength: 20, lowercase: true }).pipe(
              Effect.map((name) => (/^[a-z]/.test(name) ? name : `d${name.slice(0, 19)}`)),
            );

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

      // Bounded readiness wait. DAX cluster provisioning/modification
      // typically completes in 5-10 minutes; budget ~15 min (60 * 15s).
      const waitForAvailable = Effect.fn(function* (name: string) {
        const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
        return yield* readCluster(name).pipe(
          Effect.flatMap((cluster) => {
            if (!cluster?.ClusterArn) {
              return Effect.fail(
                new DAXClusterNotReady({ message: `DAX cluster '${name}' not found` }),
              );
            }
            if (cluster.Status !== "available") {
              return Effect.fail(
                new DAXClusterNotReady({
                  message: `DAX cluster '${name}' not available (status: ${cluster.Status})`,
                }),
              );
            }
            return Effect.succeed(cluster);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      // 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* (name: string) {
        const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
        return yield* readCluster(name).pipe(
          Effect.flatMap((cluster) => {
            if (
              cluster !== undefined &&
              cluster.Status !== "available" &&
              cluster.Status !== "deleting"
            ) {
              return Effect.fail(
                new DAXClusterNotReady({
                  message: `DAX cluster '${name}' still settling (status: ${cluster.Status})`,
                }),
              );
            }
            return Effect.succeed(cluster);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      const toAttrs = Effect.fn(function* (cluster: dax.Cluster) {
        if (!cluster.ClusterName || !cluster.ClusterArn) {
          return yield* new DAXClusterUnexpectedResponse({
            message: `DAX cluster '${cluster.ClusterName}' is missing its ARN`,
          });
        }
        return {
          clusterName: cluster.ClusterName,
          clusterArn: cluster.ClusterArn,
          status: cluster.Status ?? "available",
          nodeType: cluster.NodeType ?? DEFAULT_NODE_TYPE,
          totalNodes: cluster.TotalNodes,
          activeNodes: cluster.ActiveNodes,
          discoveryEndpointAddress: cluster.ClusterDiscoveryEndpoint?.Address,
          discoveryEndpointPort: cluster.ClusterDiscoveryEndpoint?.Port,
          discoveryEndpointUrl: cluster.ClusterDiscoveryEndpoint?.URL,
          subnetGroupName: cluster.SubnetGroup,
          iamRoleArn: cluster.IamRoleArn,
          parameterGroupName: cluster.ParameterGroup?.ParameterGroupName,
          securityGroupIds: (cluster.SecurityGroups ?? [])
            .map((g) => g.SecurityGroupIdentifier)
            .filter((g): g is string => g !== undefined),
          clusterEndpointEncryptionType: cluster.ClusterEndpointEncryptionType,
          tags: yield* readDaxTags(cluster.ClusterArn),
        };
      });

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

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? { iamRoleArn: "" };
          const o = olds ?? { iamRoleArn: "" };
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          // Create-only properties force a replacement.
          if ((n.nodeType ?? DEFAULT_NODE_TYPE) !== (o.nodeType ?? DEFAULT_NODE_TYPE)) {
            return { action: "replace" } as const;
          }
          if (n.iamRoleArn !== o.iamRoleArn) {
            return { action: "replace" } as const;
          }
          if (
            n.subnetGroupName !== undefined &&
            o.subnetGroupName !== undefined &&
            n.subnetGroupName !== o.subnetGroupName
          ) {
            return { action: "replace" } as const;
          }
          if ((n.sseEnabled ?? false) !== (o.sseEnabled ?? false)) {
            return { action: "replace" } as const;
          }
          if (
            (n.clusterEndpointEncryptionType ?? "NONE") !==
            (o.clusterEndpointEncryptionType ?? "NONE")
          ) {
            return { action: "replace" } as const;
          }
          if ((n.networkType ?? undefined) !== (o.networkType ?? undefined)) {
            return { action: "replace" } as const;
          }
          if (!sameStringSet(n.availabilityZones, o.availabilityZones)) {
            return { action: "replace" } as const;
          }
        }),

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

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

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

          // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
          if (observed === undefined) {
            yield* dax
              .createCluster({
                ClusterName: name,
                NodeType: props.nodeType ?? DEFAULT_NODE_TYPE,
                ReplicationFactor: desiredReplicationFactor,
                IamRoleArn: props.iamRoleArn,
                Description: props.description,
                AvailabilityZones: props.availabilityZones,
                SubnetGroupName: props.subnetGroupName,
                SecurityGroupIds: props.securityGroupIds,
                PreferredMaintenanceWindow: props.preferredMaintenanceWindow,
                NotificationTopicArn: props.notificationTopicArn,
                ParameterGroupName: props.parameterGroupName,
                SSESpecification:
                  props.sseEnabled !== undefined ? { Enabled: props.sseEnabled } : undefined,
                ClusterEndpointEncryptionType: props.clusterEndpointEncryptionType,
                NetworkType: props.networkType,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(
                retryIamRolePropagation,
                Effect.catchTag("ClusterAlreadyExistsFault", () => Effect.void),
              );
          }

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

          // 3. Sync — compute the update delta from OBSERVED state.
          const update: dax.UpdateClusterRequest = { ClusterName: name };
          let mutated = false;
          if (props.description !== undefined && props.description !== observed.Description) {
            update.Description = props.description;
            mutated = true;
          }
          if (
            props.preferredMaintenanceWindow !== undefined &&
            props.preferredMaintenanceWindow !== observed.PreferredMaintenanceWindow
          ) {
            update.PreferredMaintenanceWindow = props.preferredMaintenanceWindow;
            mutated = true;
          }
          if (
            props.notificationTopicArn !== undefined &&
            props.notificationTopicArn !== observed.NotificationConfiguration?.TopicArn
          ) {
            update.NotificationTopicArn = props.notificationTopicArn;
            mutated = true;
          }
          if (
            props.parameterGroupName !== undefined &&
            props.parameterGroupName !== observed.ParameterGroup?.ParameterGroupName
          ) {
            update.ParameterGroupName = props.parameterGroupName;
            mutated = true;
          }
          const observedSg = (observed.SecurityGroups ?? [])
            .map((g) => g.SecurityGroupIdentifier)
            .filter((g): g is string => g !== undefined);
          if (
            props.securityGroupIds !== undefined &&
            !sameStringSet(props.securityGroupIds, observedSg)
          ) {
            update.SecurityGroupIds = props.securityGroupIds;
            mutated = true;
          }
          if (mutated) {
            yield* dax.updateCluster(update);
            observed = yield* waitForAvailable(name);
          }

          // 3b. Sync replication factor — DAX has dedicated add/remove-node
          // APIs instead of a general update.
          const observedFactor = observed.TotalNodes;
          if (observedFactor !== undefined && observedFactor !== desiredReplicationFactor) {
            if (desiredReplicationFactor > observedFactor) {
              yield* dax.increaseReplicationFactor({
                ClusterName: name,
                NewReplicationFactor: desiredReplicationFactor,
              });
            } else {
              yield* dax.decreaseReplicationFactor({
                ClusterName: name,
                NewReplicationFactor: desiredReplicationFactor,
              });
            }
            observed = yield* waitForAvailable(name);
          }

          // 3c. Sync tags — diff against OBSERVED cloud tags.
          const arn = observed.ClusterArn;
          if (arn) {
            const observedTags = yield* readDaxTags(arn);
            const { removed, upsert } = diffTags(observedTags, desiredTags);
            if (upsert.length > 0) {
              yield* dax.tagResource({ ResourceName: arn, Tags: upsert });
            }
            if (removed.length > 0) {
              yield* dax.untagResource({ ResourceName: arn, TagKeys: removed });
            }
          }

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

        delete: Effect.fn(function* ({ output }) {
          const name = output.clusterName;
          // A cluster mid-create/modify rejects deletion with
          // InvalidClusterStateFault — wait (bounded) for it to settle
          // first. A cluster already deleting (or gone) is success.
          const settled = yield* waitUntilSettled(name).pipe(Effect.orElseSucceed(() => undefined));
          if (settled === undefined) {
            return;
          }
          if (settled.Status !== "deleting") {
            yield* dax.deleteCluster({ ClusterName: name }).pipe(
              Effect.catchTag("ClusterNotFoundFault", () => Effect.void),
              Effect.retry({
                while: (e) => e._tag === "InvalidClusterStateFault",
                schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(20)]),
              }),
              // Exhausted retries: the cluster is in a state (e.g. an
              // out-of-band delete already in flight) where deletion is
              // already converging — treat as success like the NotFound case.
              Effect.catchTag("InvalidClusterStateFault", () => Effect.void),
            );
          }
          // Wait until the cluster is actually gone: a `deleting` cluster
          // still holds its subnet/parameter groups, so dependents deleted
          // right after would fail with SubnetGroupInUseFault. DAX cluster
          // deletion typically takes 5-10 minutes; budget ~15 min (60 * 15s).
          yield* readCluster(name).pipe(
            Effect.flatMap((cluster) =>
              cluster === undefined
                ? Effect.void
                : Effect.fail(
                    new DAXClusterNotReady({
                      message: `DAX cluster '${name}' still deleting (status: ${cluster.Status})`,
                    }),
                  ),
            ),
            Effect.retry({
              schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
            }),
          );
        }),

        list: () =>
          Effect.gen(function* () {
            // Bounded hand-rolled pagination (no distilled paginator).
            const clusters: dax.Cluster[] = [];
            let nextToken: string | undefined;
            for (let page = 0; page < 20; page++) {
              const response = yield* dax.describeClusters({
                NextToken: nextToken,
              });
              clusters.push(...(response.Clusters ?? []));
              nextToken = response.NextToken;
              if (!nextToken) break;
            }
            return yield* Effect.forEach(
              clusters.filter(
                (cluster) => cluster.ClusterName !== undefined && cluster.ClusterArn !== undefined,
              ),
              (cluster) => toAttrs(cluster),
              { concurrency: 4 },
            );
          }),
      };
    }),
  );