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

import * as dax from "@distilled.cloud/aws/dax";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

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

export interface ParameterGroupProps {
  /**
   * Name of the parameter group. If omitted, a deterministic physical name
   * is generated. Changing the name replaces the parameter group.
   */
  parameterGroupName?: string;
  /**
   * Human-readable description of the parameter group.
   */
  description?: string;
  /**
   * Parameter overrides, e.g. `{ "query-ttl-millis": "60000" }`. DAX exposes
   * two tunable parameters: `query-ttl-millis` and `record-ttl-millis`.
   * DAX has no reset-to-default API, so a key removed from this map keeps
   * its last applied value.
   */
  parameters?: Record<string, string>;
}

export interface ParameterGroup extends Resource<
  "AWS.DAX.ParameterGroup",
  ParameterGroupProps,
  {
    /** Name of the parameter group. */
    parameterGroupName: string;
    /** Description of the parameter group. */
    description: string | undefined;
    /** Current non-default parameter values, keyed by parameter name. */
    parameters: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A DAX parameter group — a named set of DAX engine parameters (item and
 * query cache TTLs) that can be attached to one or more DAX
 * {@link Cluster}s.
 *
 * Parameter groups are free and provision instantly. DAX does not support
 * tags on parameter groups.
 * ### Creating a Parameter Group
 * **Example:** Parameter Group with Custom Cache TTLs
 * ```typescript
 * const params = yield* ParameterGroup("DaxParams", {
 *   description: "5 minute item and query TTLs",
 *   parameters: {
 *     "query-ttl-millis": "300000",
 *     "record-ttl-millis": "300000",
 *   },
 * });
 * ```
 *
 * ### Attaching to a Cluster
 * **Example:** Cluster Using the Parameter Group
 * ```typescript
 * const cluster = yield* Cluster("Cache", {
 *   nodeType: "dax.t3.small",
 *   replicationFactor: 1,
 *   iamRoleArn: role.roleArn,
 *   parameterGroupName: params.parameterGroupName,
 * });
 * ```
 *
 * @resource
 */
export const ParameterGroup = Resource<ParameterGroup>("AWS.DAX.ParameterGroup");

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

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

      // Observed parameter values for the group (bounded pagination — DAX
      // has no paginated distilled ops).
      const readParameters = Effect.fn(function* (name: string) {
        const values: Record<string, string> = {};
        let nextToken: string | undefined;
        for (let page = 0; page < 20; page++) {
          const response = yield* dax.describeParameters({
            ParameterGroupName: name,
            NextToken: nextToken,
          });
          for (const parameter of response.Parameters ?? []) {
            if (parameter.ParameterName !== undefined && parameter.ParameterValue !== undefined) {
              values[parameter.ParameterName] = parameter.ParameterValue;
            }
          }
          nextToken = response.NextToken;
          if (!nextToken) break;
        }
        return values;
      });

      const toAttrs = (
        group: dax.ParameterGroup,
        parameters: Record<string, string>,
        overrides: Record<string, string> | undefined,
      ) => ({
        parameterGroupName: group.ParameterGroupName ?? "",
        description: group.Description,
        // Report only the user's overridden keys with their observed values,
        // not the entire engine parameter list.
        parameters: Object.fromEntries(
          Object.keys(overrides ?? {}).map((key) => [key, parameters[key] ?? ""]),
        ),
      });

      return {
        stables: ["parameterGroupName"],

        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;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.parameterGroupName ?? (yield* toName(id, olds ?? {}));
          const group = yield* readGroup(name);
          if (group?.ParameterGroupName === undefined) return undefined;
          const parameters = yield* readParameters(name);
          // DAX parameter groups do not support tags, so ownership cannot be
          // verified — return the attributes directly.
          return toAttrs(group, parameters, olds?.parameters);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news ?? {};
          const name = output?.parameterGroupName ?? (yield* toName(id, props));

          // 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* dax
              .createParameterGroup({
                ParameterGroupName: name,
                Description: props.description,
              })
              .pipe(Effect.catchTag("ParameterGroupAlreadyExistsFault", () => Effect.void));
            observed = yield* readGroup(name);
          }
          if (observed === undefined) {
            return yield* new ParameterGroupUnexpectedResponse({
              message: `DAX parameter group '${name}' not found after create`,
            });
          }

          // 3. Sync parameters — diff desired overrides against OBSERVED
          // values and apply only the delta. (Description is create-only in
          // the DAX API — UpdateParameterGroup accepts only parameter
          // values.)
          const observedParameters = yield* readParameters(name);
          const delta = Object.entries(props.parameters ?? {}).filter(
            ([key, value]) => observedParameters[key] !== value,
          );
          if (delta.length > 0) {
            yield* dax.updateParameterGroup({
              ParameterGroupName: name,
              ParameterNameValues: delta.map(([ParameterName, ParameterValue]) => ({
                ParameterName,
                ParameterValue,
              })),
            });
            for (const [key, value] of delta) {
              observedParameters[key] = value;
            }
          }

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

        delete: Effect.fn(function* ({ output }) {
          // A parameter group still attached to a cluster rejects deletion
          // with InvalidParameterGroupStateFault — retry (bounded) while the
          // cluster releases it. NotFound is success (idempotent delete).
          yield* dax
            .deleteParameterGroup({
              ParameterGroupName: output.parameterGroupName,
            })
            .pipe(
              Effect.catchTag("ParameterGroupNotFoundFault", () => Effect.void),
              Effect.retry({
                while: (e) => e._tag === "InvalidParameterGroupStateFault",
                schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
              }),
            );
        }),

        list: () =>
          Effect.gen(function* () {
            // Bounded hand-rolled pagination (no distilled paginator).
            const groups: dax.ParameterGroup[] = [];
            let nextToken: string | undefined;
            for (let page = 0; page < 20; page++) {
              const response = yield* dax.describeParameterGroups({
                NextToken: nextToken,
              });
              groups.push(...(response.ParameterGroups ?? []));
              nextToken = response.NextToken;
              if (!nextToken) break;
            }
            return groups
              .filter(
                (group) =>
                  group.ParameterGroupName !== undefined &&
                  // AWS-managed default parameter groups (`default.dax1.0`,
                  // …) always exist and can never be deleted — keep them out
                  // of enumeration for account-wide teardown (nuke).
                  !group.ParameterGroupName.startsWith("default."),
              )
              .map((group) => toAttrs(group, {}, undefined));
          }),
      };
    }),
  );