sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ElastiCache/ ReplicationGroup.ts

import * as elasticache from "@distilled.cloud/aws/elasticache";
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";
import { readElastiCacheTags, sameStringSet, tagsToWire } from "./internal.ts";

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

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

export interface ReplicationGroupProps {
  /** Replication group identifier. Generated deterministically when omitted. */
  replicationGroupId?: string;
  /** Required human-readable description. */
  description: string;
  /** Cache engine. */
  engine: "valkey" | "redis";
  engineVersion?: string;
  /** ElastiCache node type. Must start with `cache.`, for example `cache.t4g.micro`. @default cache.t4g.micro */
  nodeType?: `cache.${string}`;
  subnetGroupName?: string;
  securityGroupIds?: string[];
  /** Shard count. Changes use online resharding. */
  numNodeGroups?: number;
  /** Read replicas per shard, from 0 through 5. */
  replicasPerNodeGroup?: number;
  automaticFailoverEnabled?: boolean;
  multiAzEnabled?: boolean;
  parameterGroupName?: string;
  port?: number;
  maintenanceWindow?: string;
  snapshotRetentionLimit?: number;
  snapshotWindow?: string;
  autoMinorVersionUpgrade?: boolean;
  /** Enables TLS for client connections. @default true */
  transitEncryptionEnabled?: boolean;
  transitEncryptionMode?: elasticache.TransitEncryptionMode;
  atRestEncryptionEnabled?: boolean;
  kmsKeyId?: string;
  networkType?: elasticache.NetworkType;
  ipDiscovery?: elasticache.IpDiscovery;
  /** User group IDs for Valkey/Redis RBAC. */
  userGroupIds?: string[];
  /** Snapshot used only while creating a new group. */
  snapshotName?: string;
  snapshotArns?: string[];
  /** Optional final snapshot created before destroy. */
  finalSnapshotName?: string;
  tags?: Record<string, string>;
}

export interface ReplicationGroup extends Resource<
  "AWS.ElastiCache.ReplicationGroup",
  ReplicationGroupProps,
  {
    replicationGroupId: string;
    replicationGroupArn: string;
    status: string;
    engine: string;
    engineVersion: string | undefined;
    nodeType: string | undefined;
    configurationEndpointAddress: string | undefined;
    configurationEndpointPort: number | undefined;
    primaryEndpointAddress: string | undefined;
    primaryEndpointPort: number | undefined;
    readerEndpointAddress: string | undefined;
    readerEndpointPort: number | undefined;
    transitEncryptionEnabled: boolean;
    nodeGroupIds: string[];
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/** Invalid desired topology rejected before AWS can start a partial create. */
export class InvalidReplicationGroupConfiguration extends Data.TaggedError(
  "InvalidReplicationGroupConfiguration",
)<{ message: string }> {}

export const validateReplicationGroupProps = (
  props: ReplicationGroupProps,
): InvalidReplicationGroupConfiguration | undefined => {
  const invalid = (message: string) => new InvalidReplicationGroupConfiguration({ message });
  if (
    props.port !== undefined &&
    (!Number.isInteger(props.port) || props.port < 1 || props.port > 65_535)
  ) {
    return invalid("port must be an integer from 1 through 65535");
  }
  if (
    props.numNodeGroups !== undefined &&
    (!Number.isInteger(props.numNodeGroups) || props.numNodeGroups < 1)
  ) {
    return invalid("numNodeGroups must be an integer of at least 1");
  }
  if (
    props.replicasPerNodeGroup !== undefined &&
    (!Number.isInteger(props.replicasPerNodeGroup) ||
      props.replicasPerNodeGroup < 0 ||
      props.replicasPerNodeGroup > 5)
  ) {
    return invalid("replicasPerNodeGroup must be an integer from 0 through 5");
  }
  if (props.automaticFailoverEnabled === true && (props.replicasPerNodeGroup ?? 0) < 1) {
    return invalid("automaticFailoverEnabled requires replicasPerNodeGroup to be at least 1");
  }
  if (props.multiAzEnabled === true && (props.replicasPerNodeGroup ?? 0) < 1) {
    return invalid("multiAzEnabled requires replicasPerNodeGroup to be at least 1");
  }
  if (props.multiAzEnabled === true && props.automaticFailoverEnabled !== true) {
    return invalid("multiAzEnabled requires automaticFailoverEnabled to be true");
  }
  if (props.transitEncryptionMode !== undefined && props.transitEncryptionEnabled === false) {
    return invalid("transitEncryptionMode requires transitEncryptionEnabled");
  }
  return undefined;
};

/**
 * A provisioned Valkey or Redis OSS replication group.
 *
 * ### Creating a Highly Available Cache
 * **Example:** Valkey with a replica in a VPC
 * ```typescript
 * const cache = yield* ReplicationGroup("Cache", {
 *   description: "application cache",
 *   engine: "valkey",
 *   subnetGroupName: subnets.subnetGroupName,
 *   securityGroupIds: [cacheSecurityGroup.groupId],
 *   replicasPerNodeGroup: 1,
 *   automaticFailoverEnabled: true,
 *   multiAzEnabled: true,
 *   transitEncryptionEnabled: true,
 * });
 * ```
 *
 * @resource
 */
export const ReplicationGroup = Resource<ReplicationGroup>("AWS.ElastiCache.ReplicationGroup");

const DEFAULT_NODE_TYPE = "cache.t4g.micro";

export const ReplicationGroupProvider = () =>
  Provider.effect(
    ReplicationGroup,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<ReplicationGroupProps>) =>
        props.replicationGroupId
          ? Effect.succeed(props.replicationGroupId)
          : createPhysicalName({ id, maxLength: 40, lowercase: true });
      const readGroup = Effect.fn(function* (name: string) {
        const response = yield* elasticache
          .describeReplicationGroups({ ReplicationGroupId: name })
          .pipe(Effect.catchTag("ReplicationGroupNotFoundFault", () => Effect.undefined));
        return response?.ReplicationGroups?.[0];
      });
      const waitForAvailable = Effect.fn(function* (name: string) {
        return yield* readGroup(name).pipe(
          Effect.flatMap((group) =>
            group?.Status === "available"
              ? Effect.succeed(group)
              : Effect.fail(
                  new ReplicationGroupNotReady({
                    message: `Replication group '${name}' is not available`,
                  }),
                ),
          ),
          Effect.retry({
            schedule: Schedule.max([
              Schedule.fixed("15 seconds"),
              // Engine upgrades can remain in "modifying" for more than
              // fifteen minutes before ElastiCache reports "available".
              Schedule.recurs(100),
            ]),
          }),
        );
      });
      const waitForDeleted = Effect.fn(function* (name: string) {
        return yield* readGroup(name).pipe(
          Effect.flatMap((group) =>
            group === undefined
              ? Effect.void
              : Effect.fail(
                  new ReplicationGroupNotReady({
                    message: `Replication group '${name}' is still deleting`,
                  }),
                ),
          ),
          Effect.retry({
            schedule: Schedule.max([
              Schedule.fixed("15 seconds"),
              // Multi-AZ failover deletes can remain visible longer than the
              // normal fifteen-minute lifecycle window.
              Schedule.recurs(100),
            ]),
          }),
        );
      });
      const retryWhileCacheTransitioning = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
        effect.pipe(
          Effect.retry({
            while: (error) =>
              (error as { _tag?: string })._tag === "InvalidReplicationGroupStateFault" ||
              (error as { _tag?: string })._tag === "InvalidCacheClusterStateFault",
            schedule: Schedule.max([
              Schedule.fixed("15 seconds"),
              // AWS can report the group as available before its member
              // clusters accept tag changes after an in-place update.
              Schedule.recurs(100),
            ]),
          }),
        );
      const attrs = Effect.fn(function* (group: elasticache.ReplicationGroup) {
        if (!group.ReplicationGroupId || !group.ARN || !group.Status || !group.Engine) {
          return yield* new ReplicationGroupUnexpectedResponse({
            message: "ElastiCache replication group is missing its id, ARN, status, or engine",
          });
        }
        const engineVersion = group.MemberClusters?.[0]
          ? (yield* elasticache.describeCacheClusters({
              CacheClusterId: group.MemberClusters[0],
            })).CacheClusters?.[0]?.EngineVersion
          : undefined;
        const primary = group.NodeGroups?.[0]?.PrimaryEndpoint;
        const reader = group.NodeGroups?.[0]?.ReaderEndpoint;
        return {
          replicationGroupId: group.ReplicationGroupId,
          replicationGroupArn: group.ARN,
          status: group.Status,
          engine: group.Engine,
          engineVersion,
          nodeType: group.CacheNodeType,
          configurationEndpointAddress: group.ConfigurationEndpoint?.Address,
          configurationEndpointPort: group.ConfigurationEndpoint?.Port,
          primaryEndpointAddress: primary?.Address,
          primaryEndpointPort: primary?.Port,
          readerEndpointAddress: reader?.Address,
          readerEndpointPort: reader?.Port,
          transitEncryptionEnabled: group.TransitEncryptionEnabled ?? false,
          nodeGroupIds: (group.NodeGroups ?? [])
            .map((nodeGroup) => nodeGroup.NodeGroupId)
            .filter((id): id is string => id !== undefined),
          tags: yield* readElastiCacheTags(group.ARN),
        };
      });
      const replacement = (
        olds: Partial<ReplicationGroupProps>,
        news: Partial<ReplicationGroupProps>,
      ) =>
        olds.subnetGroupName !== news.subnetGroupName ||
        olds.port !== news.port ||
        olds.kmsKeyId !== news.kmsKeyId ||
        olds.atRestEncryptionEnabled !== news.atRestEncryptionEnabled ||
        olds.networkType !== news.networkType ||
        olds.snapshotName !== news.snapshotName ||
        // AWS cannot enable cluster mode on an existing non-cluster-mode
        // replication group, so scaling from one shard must replace it.
        ((olds.numNodeGroups ?? 1) <= 1 && (news.numNodeGroups ?? 1) > 1) ||
        !sameStringSet(olds.snapshotArns, news.snapshotArns);

      return {
        stables: ["replicationGroupId", "replicationGroupArn"],
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
          if (replacement(olds ?? {}, news ?? {})) return { action: "replace" } as const;
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const group = yield* readGroup(
            output?.replicationGroupId ?? (yield* toName(id, olds ?? {})),
          );
          if (!group?.ARN) return undefined;
          const result = yield* attrs(group);
          return (yield* hasAlchemyTags(id, result.tags)) ? result : Unowned(result);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news!;
          const invalid = validateReplicationGroupProps(props);
          if (invalid) return yield* invalid;
          const name = output?.replicationGroupId ?? (yield* toName(id, props));
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...props.tags,
          };
          let group = yield* readGroup(name);
          if (!group) {
            yield* elasticache
              .createReplicationGroup({
                ReplicationGroupId: name,
                ReplicationGroupDescription: props.description,
                Engine: props.engine,
                EngineVersion: props.engineVersion,
                CacheNodeType: props.nodeType ?? DEFAULT_NODE_TYPE,
                CacheSubnetGroupName: props.subnetGroupName,
                SecurityGroupIds: props.securityGroupIds,
                NumNodeGroups: props.numNodeGroups,
                ReplicasPerNodeGroup: props.replicasPerNodeGroup,
                AutomaticFailoverEnabled: props.automaticFailoverEnabled,
                MultiAZEnabled: props.multiAzEnabled,
                CacheParameterGroupName: props.parameterGroupName,
                Port: props.port,
                PreferredMaintenanceWindow: props.maintenanceWindow,
                SnapshotRetentionLimit: props.snapshotRetentionLimit,
                SnapshotWindow: props.snapshotWindow,
                AutoMinorVersionUpgrade: props.autoMinorVersionUpgrade,
                TransitEncryptionEnabled: props.transitEncryptionEnabled ?? true,
                TransitEncryptionMode: props.transitEncryptionMode,
                AtRestEncryptionEnabled: props.atRestEncryptionEnabled,
                KmsKeyId: props.kmsKeyId,
                NetworkType: props.networkType,
                IpDiscovery: props.ipDiscovery,
                UserGroupIds: props.userGroupIds,
                SnapshotName: props.snapshotName,
                SnapshotArns: props.snapshotArns,
                Tags: tagsToWire(desiredTags),
              })
              .pipe(Effect.catchTag("ReplicationGroupAlreadyExistsFault", () => Effect.void));
          }
          group = yield* waitForAvailable(name);
          const update: elasticache.ModifyReplicationGroupMessage = {
            ReplicationGroupId: name,
            ApplyImmediately: true,
          };
          let changed = false;
          const set = <K extends keyof elasticache.ModifyReplicationGroupMessage>(
            key: K,
            desired: elasticache.ModifyReplicationGroupMessage[K],
            observed: unknown,
          ) => {
            if (desired !== undefined && desired !== observed) {
              update[key] = desired;
              changed = true;
            }
          };
          set("ReplicationGroupDescription", props.description, group.Description);
          set("CacheNodeType", props.nodeType, group.CacheNodeType);
          set("Engine", props.engine, group.Engine);
          set(
            "AutoMinorVersionUpgrade",
            props.autoMinorVersionUpgrade,
            group.AutoMinorVersionUpgrade,
          );
          set("PreferredMaintenanceWindow", props.maintenanceWindow, undefined);
          set("SnapshotRetentionLimit", props.snapshotRetentionLimit, group.SnapshotRetentionLimit);
          set("SnapshotWindow", props.snapshotWindow, group.SnapshotWindow);
          set("CacheParameterGroupName", props.parameterGroupName, undefined);
          set("IpDiscovery", props.ipDiscovery, group.IpDiscovery);
          set("TransitEncryptionMode", props.transitEncryptionMode, group.TransitEncryptionMode);
          // ElastiCache reports VPC security groups and engine version on a
          // member cluster, not on the replication-group response.
          const member = group.MemberClusters?.[0]
            ? (yield* elasticache.describeCacheClusters({
                CacheClusterId: group.MemberClusters[0],
              })).CacheClusters?.[0]
            : undefined;
          const existingSecurityGroups = (member?.SecurityGroups ?? [])
            .map((membership) => membership.SecurityGroupId)
            .filter((id): id is string => id !== undefined);
          set("EngineVersion", props.engineVersion, member?.EngineVersion);
          if (
            props.securityGroupIds &&
            !sameStringSet(props.securityGroupIds, existingSecurityGroups)
          ) {
            update.SecurityGroupIds = props.securityGroupIds;
            changed = true;
          }
          const existingUsers = group.UserGroupIds ?? [];
          if (props.userGroupIds && !sameStringSet(props.userGroupIds, existingUsers)) {
            update.UserGroupIdsToAdd = props.userGroupIds.filter(
              (id) => !existingUsers.includes(id),
            );
            update.UserGroupIdsToRemove = existingUsers.filter(
              (id) => !props.userGroupIds!.includes(id),
            );
            changed = true;
          }
          if (changed) {
            yield* elasticache.modifyReplicationGroup(update);
            group = yield* waitForAvailable(name);
          }
          const currentNodeGroups = group.NodeGroups?.length ?? 1;
          if (props.numNodeGroups !== undefined && props.numNodeGroups !== currentNodeGroups) {
            yield* elasticache.modifyReplicationGroupShardConfiguration({
              ReplicationGroupId: name,
              NodeGroupCount: props.numNodeGroups,
              ApplyImmediately: true,
              ...(props.numNodeGroups < currentNodeGroups
                ? {
                    NodeGroupsToRemove: (group.NodeGroups ?? [])
                      .slice(props.numNodeGroups)
                      .map((node) => node.NodeGroupId)
                      .filter((id): id is string => id !== undefined),
                  }
                : {}),
            });
            group = yield* waitForAvailable(name);
          }
          const setAutomaticFailover = Effect.fn(function* (enabled: boolean) {
            const current = group;
            if (!current) {
              return yield* Effect.die(
                `Replication group '${name}' disappeared while updating automatic failover`,
              );
            }
            if ((current.AutomaticFailover === "enabled") === enabled) return;
            yield* retryWhileCacheTransitioning(
              elasticache.modifyReplicationGroup({
                ReplicationGroupId: name,
                AutomaticFailoverEnabled: enabled,
                ApplyImmediately: true,
              }),
            );
            group = yield* waitForAvailable(name);
          });
          const setMultiAz = Effect.fn(function* (enabled: boolean) {
            const current = group;
            if (!current) {
              return yield* Effect.die(
                `Replication group '${name}' disappeared while updating Multi-AZ`,
              );
            }
            if ((current.MultiAZ === "enabled") === enabled) return;
            yield* retryWhileCacheTransitioning(
              elasticache.modifyReplicationGroup({
                ReplicationGroupId: name,
                MultiAZEnabled: enabled,
                ApplyImmediately: true,
              }),
            );
            group = yield* waitForAvailable(name);
          });
          if (props.replicasPerNodeGroup !== undefined) {
            const replicaCount = Math.max(
              ...(group.NodeGroups ?? []).map((node) =>
                Math.max(0, (node.NodeGroupMembers?.length ?? 1) - 1),
              ),
              0,
            );
            // AWS rejects HA before the first replica exists, and rejects
            // removing the final replica while either HA setting is on.
            if (props.replicasPerNodeGroup === 0 && replicaCount > 0) {
              yield* setMultiAz(false);
              yield* setAutomaticFailover(false);
            }
            if (props.replicasPerNodeGroup > replicaCount) {
              yield* elasticache.increaseReplicaCount({
                ReplicationGroupId: name,
                NewReplicaCount: props.replicasPerNodeGroup,
                ApplyImmediately: true,
              });
              group = yield* waitForAvailable(name);
            } else if (props.replicasPerNodeGroup < replicaCount) {
              yield* elasticache.decreaseReplicaCount({
                ReplicationGroupId: name,
                NewReplicaCount: props.replicasPerNodeGroup,
                ApplyImmediately: true,
              });
              group = yield* waitForAvailable(name);
            }
          }
          if (props.automaticFailoverEnabled !== undefined) {
            yield* setAutomaticFailover(props.automaticFailoverEnabled);
          }
          if (props.multiAzEnabled !== undefined) {
            yield* setMultiAz(props.multiAzEnabled);
          }
          if (group.ARN) {
            const { removed, upsert } = diffTags(
              yield* retryWhileCacheTransitioning(readElastiCacheTags(group.ARN)),
              desiredTags,
            );
            if (upsert.length)
              yield* retryWhileCacheTransitioning(
                elasticache.addTagsToResource({
                  ResourceName: group.ARN,
                  Tags: upsert,
                }),
              );
            if (removed.length)
              yield* retryWhileCacheTransitioning(
                elasticache.removeTagsFromResource({
                  ResourceName: group.ARN,
                  TagKeys: removed,
                }),
              );
            // AWS can accept a tag update before ListTagsForResource is
            // available again. Do not report the resource as reconciled
            // until callers can observe the finished tag state.
            yield* retryWhileCacheTransitioning(readElastiCacheTags(group.ARN));
          }
          yield* session.note(name);
          return yield* attrs(group);
        }),
        delete: Effect.fn(function* ({ olds, output }) {
          yield* retryWhileCacheTransitioning(
            elasticache
              .deleteReplicationGroup({
                ReplicationGroupId: output.replicationGroupId,
                FinalSnapshotIdentifier: olds.finalSnapshotName,
              })
              .pipe(Effect.catchTag("ReplicationGroupNotFoundFault", () => Effect.void)),
          );
          yield* waitForDeleted(output.replicationGroupId);
        }),
        list: () =>
          elasticache.describeReplicationGroups.pages({}).pipe(
            Stream.runCollect,
            Effect.map((pages) =>
              Array.from(pages).flatMap((page) => page.ReplicationGroups ?? []),
            ),
            Effect.flatMap((groups) =>
              Effect.forEach(
                groups.filter((group) => group.ARN),
                attrs,
              ),
            ),
          ),
      };
    }),
  );