sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ MemoryDB/ ParameterGroup.ts

import * as memorydb from "@distilled.cloud/aws/memorydb";
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 { readMemoryDbTags } from "./internal.ts";

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

export interface ParameterGroupProps {
  /**
   * Name of the parameter group. Must be 1-40 characters. If omitted, a
   * deterministic physical name is generated. Changing the name replaces the
   * parameter group.
   */
  parameterGroupName?: string;
  /**
   * Parameter group family the group belongs to, e.g. `"memorydb_valkey7"`,
   * `"memorydb_valkey8"`, `"memorydb_redis7"`. Changing the family replaces
   * the parameter group.
   */
  family: string;
  /**
   * Human-readable description of the parameter group. The MemoryDB API has
   * no update for descriptions, so changing it replaces the parameter group.
   */
  description?: string;
  /**
   * Engine parameter overrides (name → value), e.g.
   * `{ "maxmemory-policy": "allkeys-lru" }`. Parameters removed from this map
   * are reset to the engine default.
   * @default {} (engine defaults)
   */
  parameters?: Record<string, string>;
  /**
   * User-defined tags for the parameter group.
   */
  tags?: Record<string, string>;
}

export interface ParameterGroup extends Resource<
  "AWS.MemoryDB.ParameterGroup",
  ParameterGroupProps,
  {
    /** Name of the parameter group. */
    parameterGroupName: string;
    /** ARN of the parameter group. */
    parameterGroupArn: string;
    /** Parameter group family (e.g. `memorydb_valkey7`). */
    family: string | undefined;
    /** Description of the parameter group. */
    description: string | undefined;
    /** Tags on the parameter group (user + internal Alchemy tags). */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A MemoryDB parameter group — a named collection of engine parameter
 * overrides applied to every node of any {@link Cluster} that references it
 * via `parameterGroupName`.
 *
 * Parameter groups are free and provision instantly. Parameters not listed
 * keep their engine defaults; removing a parameter from `parameters` resets
 * it to the default.
 * ### Creating a Parameter Group
 * **Example:** Parameter Group with an Eviction Policy
 * ```typescript
 * const params = yield* ParameterGroup("CacheParams", {
 *   family: "memorydb_valkey7",
 *   description: "LRU eviction for the session cache",
 *   parameters: { "maxmemory-policy": "allkeys-lru" },
 * });
 * const cluster = yield* Cluster("Cache", {
 *   aclName: acl.aclName,
 *   parameterGroupName: params.parameterGroupName,
 * });
 * ```
 *
 * @resource
 */
export const ParameterGroup = Resource<ParameterGroup>("AWS.MemoryDB.ParameterGroup");

export const ParameterGroupProvider = () =>
  Provider.effect(
    ParameterGroup,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<ParameterGroupProps>) =>
        props.parameterGroupName
          ? Effect.succeed(props.parameterGroupName)
          : createPhysicalName({ id, maxLength: 40, lowercase: true });

      const readGroup = Effect.fn(function* (name: string) {
        const response = yield* memorydb
          .describeParameterGroups({ ParameterGroupName: name })
          .pipe(Effect.catchTag("ParameterGroupNotFoundFault", () => Effect.undefined));
        return response?.ParameterGroups?.[0];
      });

      // Observed engine parameters (name → value), paginated.
      const readParameters = Effect.fn(function* (name: string) {
        const parameters = new Map<string, string>();
        yield* memorydb.describeParameters.pages({ ParameterGroupName: name }).pipe(
          Stream.runForEach((page) =>
            Effect.sync(() => {
              for (const parameter of page.Parameters ?? []) {
                if (parameter.Name !== undefined) {
                  parameters.set(parameter.Name, parameter.Value ?? "");
                }
              }
            }),
          ),
        );
        return parameters;
      });

      const toAttrs = Effect.fn(function* (group: memorydb.ParameterGroup) {
        if (!group.Name || !group.ARN) {
          return yield* new MemoryDBParameterGroupUnexpectedResponse({
            message: `Parameter group '${group.Name}' is missing its ARN`,
          });
        }
        return {
          parameterGroupName: group.Name,
          parameterGroupArn: group.ARN,
          family: group.Family,
          description: group.Description,
          tags: yield* readMemoryDbTags(group.ARN),
        };
      });

      return {
        stables: ["parameterGroupName", "parameterGroupArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? { family: "" };
          const o = olds ?? { family: "" };
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          if (n.family !== o.family) {
            return { action: "replace" } as const;
          }
          // Descriptions have no update API.
          if ((n.description ?? undefined) !== (o.description ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.parameterGroupName ?? (yield* toName(id, olds ?? { family: "" }));
          const group = yield* readGroup(name);
          if (!group?.ARN) return undefined;
          const attrs = yield* toAttrs(group);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

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

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

          // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
          if (observed === undefined) {
            yield* memorydb
              .createParameterGroup({
                ParameterGroupName: name,
                Family: props.family,
                Description: props.description,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("ParameterGroupAlreadyExistsFault", () => Effect.void));
            observed = yield* readGroup(name);
          }
          if (observed === undefined) {
            return yield* new MemoryDBParameterGroupUnexpectedResponse({
              message: `Parameter group '${name}' not found after create`,
            });
          }

          // 3. Sync parameters — diff desired values against OBSERVED cloud
          // values and apply only the delta. Parameters dropped from the
          // desired map (present in olds) are reset to the engine default.
          const observedParams = yield* readParameters(name);
          const changed = Object.entries(desired).filter(
            ([key, value]) => observedParams.get(key) !== value,
          );
          if (changed.length > 0) {
            yield* memorydb.updateParameterGroup({
              ParameterGroupName: name,
              ParameterNameValues: changed.map(([ParameterName, ParameterValue]) => ({
                ParameterName,
                ParameterValue,
              })),
            });
          }
          const removed = Object.keys(olds?.parameters ?? {}).filter((key) => !(key in desired));
          if (removed.length > 0) {
            yield* memorydb
              .resetParameterGroup({
                ParameterGroupName: name,
                ParameterNames: removed,
              })
              .pipe(
                // A parameter already at its default resets to a no-op; a
                // group busy applying the previous update settles quickly.
                Effect.retry({
                  while: (e): boolean => e._tag === "InvalidParameterGroupStateFault",
                  schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(8)]),
                }),
              );
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const arn = observed.ARN;
          if (arn) {
            const observedTags = yield* readMemoryDbTags(arn);
            const { removed: removedTags, upsert } = diffTags(observedTags, desiredTags);
            if (upsert.length > 0) {
              yield* memorydb.tagResource({ ResourceArn: arn, Tags: upsert });
            }
            if (removedTags.length > 0) {
              yield* memorydb.untagResource({
                ResourceArn: arn,
                TagKeys: removedTags,
              });
            }
          }

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

        delete: Effect.fn(function* ({ output }) {
          // A parameter group still referenced by a cluster (or mid-update)
          // rejects deletion with InvalidParameterGroupStateFault — retry
          // bounded. NotFound is success (idempotent delete).
          yield* memorydb
            .deleteParameterGroup({
              ParameterGroupName: output.parameterGroupName,
            })
            .pipe(
              Effect.catchTag("ParameterGroupNotFoundFault", () => Effect.void),
              Effect.retry({
                while: (e): boolean => e._tag === "InvalidParameterGroupStateFault",
                schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
              }),
            );
        }),

        list: () =>
          memorydb.describeParameterGroups.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.ParameterGroups ?? []).filter(
                  (group) =>
                    group.Name !== undefined &&
                    group.ARN !== undefined &&
                    // The engine-default groups (default.memorydb-*) are
                    // AWS-owned and cannot be deleted.
                    !group.Name.startsWith("default."),
                ),
              ),
            ),
            Effect.flatMap(Effect.forEach((group) => toAttrs(group), { concurrency: 4 })),
          ),
      };
    }),
  );