sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RDS/ DBParameterGroup.ts

import * as rds from "@distilled.cloud/aws/rds";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } 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";

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

export interface DBParameterGroupProps {
  /**
   * Name of the parameter group. If omitted, Alchemy generates one.
   */
  dbParameterGroupName?: string;
  /**
   * Parameter group family, for example `aurora-postgresql16`.
   */
  family: string;
  /**
   * Human-readable description.
   */
  description?: string;
  /**
   * Instance parameter overrides, e.g. `{ time_zone: "Australia/Sydney" }`.
   *
   * This map is the group's entire user-owned surface: entries are written,
   * and undeclared user overrides are reset to engine defaults. Omitting the
   * map is equivalent to `{}`, including on adoption and unchanged-input deploys.
   *
   * Values must be in the form RDS reports back (it canonicalises some — a
   * boolean set as `ON` reads back as `1`). Reconciliation waits for those
   * reported values and fails if they do not converge within the observation budget.
   *
   * Static parameters are applied with `pending-reboot`, dynamic parameters
   * with `immediate`.
   */
  parameters?: Record<string, string>;
  /**
   * User-defined tags.
   */
  tags?: Record<string, string>;
}

export interface DBParameterGroup extends Resource<
  "AWS.RDS.DBParameterGroup",
  DBParameterGroupProps,
  {
    /**
     * Name of the parameter group.
     */
    dbParameterGroupName: string;
    /**
     * ARN of the parameter group.
     */
    dbParameterGroupArn: string | undefined;
    /**
     * Parameter group family (e.g. `aurora-postgresql16`).
     */
    family: string;
    /**
     * Description of the parameter group.
     */
    description: string | undefined;
    /**
     * Observed user overrides and explicitly managed engine defaults.
     * Omitting `parameters` removes all user overrides during reconciliation.
     * These are group settings; static values still require an instance reboot.
     */
    parameters: Record<string, string>;
    /**
     * Tags on the parameter group.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An RDS DB parameter group — instance-level engine settings, applied to a
 * `DBInstance` (as opposed to the cluster-wide `DBClusterParameterGroup`).
 *
 * Name, family, and description changes force a replacement (RDS has no
 * modify API for these); parameters and tags update in place.
 * ### Creating a Parameter Group
 * **Example:** Parameter Group for Aurora Postgres 16 Instances
 * ```typescript
 * const instanceParams = yield* DBParameterGroup("InstanceParams", {
 *   family: "aurora-postgresql16",
 *   description: "Instance-level settings for the app database",
 * });
 * ```
 *
 * **Example:** Set Engine Parameters
 * ```typescript
 * const params = yield* DBParameterGroup("MysqlParams", {
 *   family: "mysql8.4",
 *   parameters: {
 *     time_zone: "Australia/Sydney",
 *     max_connections: "200",
 *   },
 * });
 * ```
 * Dynamic parameters apply immediately, static ones on the next reboot.
 * Cluster-wide settings belong on `DBClusterParameterGroup` instead — Postgres
 * `timezone`, for example, is a cluster parameter on Aurora.
 *
 * **Example:** Attach to an Instance
 * ```typescript
 * const writer = yield* DBInstance("Writer", {
 *   dbClusterIdentifier: cluster.dbClusterIdentifier,
 *   dbInstanceClass: "db.serverless",
 *   engine: "aurora-postgresql",
 *   dbParameterGroupName: instanceParams.dbParameterGroupName,
 * });
 * ```
 *
 * @resource
 */
export const DBParameterGroup = Resource<DBParameterGroup>("AWS.RDS.DBParameterGroup");

/**
 * A parameter modify/reset issued immediately after another change fails with
 * `InvalidDBParameterGroupStateFault` ("has pending changes") until the prior
 * change settles — retry it on a short bounded schedule.
 */
const retryWhileParameterGroupBusy = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "InvalidDBParameterGroupStateFault",
    schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
  });

class DBParameterGroupNotSettled extends Data.TaggedError("DBParameterGroupNotSettled")<{
  resourceName: string;
}> {}

export const DBParameterGroupProvider = () =>
  Provider.effect(
    DBParameterGroup,
    Effect.gen(function* () {
      const toName = (id: string, props: DBParameterGroupProps) =>
        props.dbParameterGroupName
          ? Effect.succeed(props.dbParameterGroupName)
          : createPhysicalName({ id, maxLength: 255 });

      const readGroup = Effect.fn(function* (name: string) {
        const response = yield* rds
          .describeDBParameterGroups({
            DBParameterGroupName: name,
          })
          .pipe(Effect.catchTag("DBParameterGroupNotFoundFault", () => Effect.undefined));
        return response?.DBParameterGroups?.[0];
      });

      const readTags = Effect.fn(function* (arn: string | undefined) {
        if (!arn) return {};
        const response = yield* rds.listTagsForResource({ ResourceName: arn });
        return Object.fromEntries(
          (response.TagList ?? []).flatMap(({ Key, Value }) =>
            Key !== undefined && Value !== undefined ? [[Key, Value]] : [],
          ),
        );
      });

      // All parameters (defaults + overrides) with their current values and
      // apply types — the observed baseline for the parameter sync.
      const readParameters = Effect.fn(function* (name: string) {
        return yield* rds.describeDBParameters.pages({ DBParameterGroupName: name }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Parameters ?? [])),
        );
      });

      // The subset the user has overridden (Source `user`) — used to compute
      // resets when a prop entry is removed.
      const readUserParameters = Effect.fn(function* (name: string) {
        return yield* rds.describeDBParameters
          .pages({ DBParameterGroupName: name, Source: "user" })
          .pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Parameters ?? [])),
          );
      });

      const toManagedParameterRecord = (
        parameters: rds.Parameter[],
        desired: Record<string, string> = {},
      ): Record<string, string> =>
        Object.fromEntries(
          parameters.flatMap((p) =>
            p.ParameterName !== undefined &&
            p.ParameterValue !== undefined &&
            (p.Source === "user" || Object.hasOwn(desired, p.ParameterName))
              ? [[p.ParameterName, p.ParameterValue]]
              : [],
          ),
        );

      return {
        stables: ["dbParameterGroupArn", "dbParameterGroupName"],
        diff: Effect.fn(function* ({ id, olds, news, output }) {
          if (!isResolved(news)) return undefined;
          if (
            (yield* toName(id, olds ?? ({} as DBParameterGroupProps))) !== (yield* toName(id, news))
          ) {
            return { action: "replace" } as const;
          }
          if (olds?.family !== news.family || olds?.description !== news.description) {
            return { action: "replace" } as const;
          }
          if (output !== undefined) {
            const group = yield* readGroup(output.dbParameterGroupName);
            if (!group) return { action: "update", stables: [] } as const;
            const desired = news.parameters ?? {};
            const parameters = yield* readParameters(output.dbParameterGroupName).pipe(
              Effect.catchTag("DBParameterGroupNotFoundFault", () => Effect.undefined),
            );
            if (parameters === undefined) {
              return { action: "update", stables: [] } as const;
            }
            const observed = toManagedParameterRecord(parameters, desired);
            const desiredTags = {
              ...news.tags,
              ...(yield* createInternalTags(id)),
            };
            if (
              !deepEqual(desired, observed) ||
              !deepEqual(desiredTags, yield* readTags(group.DBParameterGroupArn))
            ) {
              return { action: "update" } as const;
            }
          }
        }),
        list: () =>
          // Collection reads omit per-group tags and parameters; read hydrates them.
          rds.describeDBParameterGroups.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.DBParameterGroups ?? [])
                  .filter(
                    (
                      g,
                    ): g is rds.DBParameterGroup & {
                      DBParameterGroupName: string;
                    } =>
                      g.DBParameterGroupName != null &&
                      // AWS-managed `default.*` groups cannot be deleted
                      // (InvalidDBParameterGroupStateFault) — don't enumerate.
                      !g.DBParameterGroupName.startsWith("default."),
                  )
                  .map((g) => ({
                    dbParameterGroupName: g.DBParameterGroupName,
                    dbParameterGroupArn: g.DBParameterGroupArn,
                    family: g.DBParameterGroupFamily ?? "",
                    description: g.Description,
                    // Like tags: a describe per group would be O(groups) calls.
                    parameters: {} as Record<string, string>,
                    tags: {} as Record<string, string>,
                  })),
              ),
            ),
          ),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name =
            output?.dbParameterGroupName ??
            (yield* toName(id, olds ?? ({ family: "" } as DBParameterGroupProps)));
          const group = yield* readGroup(name);
          if (!group?.DBParameterGroupName) {
            return undefined;
          }
          const parameters = toManagedParameterRecord(
            yield* readParameters(group.DBParameterGroupName),
            olds?.parameters,
          );
          return {
            dbParameterGroupName: group.DBParameterGroupName,
            dbParameterGroupArn: group.DBParameterGroupArn,
            family: group.DBParameterGroupFamily ?? olds?.family ?? "",
            description: group.Description,
            parameters,
            tags: yield* readTags(group.DBParameterGroupArn),
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.dbParameterGroupName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // Observe — fetch live parameter-group state.
          let observed = yield* readGroup(name);

          // Ensure — create if missing. Tolerate
          // `DBParameterGroupAlreadyExistsFault` as a race with a peer
          // reconciler by re-reading.
          if (!observed?.DBParameterGroupName) {
            yield* rds
              .createDBParameterGroup({
                DBParameterGroupName: name,
                DBParameterGroupFamily: news.family,
                Description: news.description ?? `Alchemy parameter group ${name}`,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("DBParameterGroupAlreadyExistsFault", () => Effect.void));
            observed = yield* readGroup(name);
            if (!observed?.DBParameterGroupName) {
              return yield* new RDSDBParameterGroupUnexpectedResponse({
                message: `Failed to create DB parameter group '${name}'`,
              });
            }
          }

          // Omission owns an empty override map, including on adoption.
          const desiredParameters = news.parameters ?? {};
          {
            const byName = new Map(
              (yield* readParameters(name)).flatMap((p) =>
                p.ParameterName !== undefined ? [[p.ParameterName, p] as const] : [],
              ),
            );

            const toModify: rds.Parameter[] = Object.entries(desiredParameters).flatMap(
              ([ParameterName, ParameterValue]) => {
                const current = byName.get(ParameterName);
                if (current?.ParameterValue === ParameterValue) return [];
                return [
                  {
                    ParameterName,
                    ParameterValue,
                    ApplyMethod: current?.ApplyType === "static" ? "pending-reboot" : "immediate",
                  },
                ];
              },
            );
            if (toModify.length > 0) {
              // The API caps a single call at 20 parameters.
              for (let i = 0; i < toModify.length; i += 20) {
                yield* retryWhileParameterGroupBusy(
                  rds.modifyDBParameterGroup({
                    DBParameterGroupName: name,
                    Parameters: toModify.slice(i, i + 20),
                  }),
                );
              }
            }

            // Reset user-overridden parameters that were removed from props.
            const toReset = (yield* readUserParameters(name)).flatMap((p) =>
              p.ParameterName !== undefined && !(p.ParameterName in desiredParameters)
                ? [
                    {
                      ParameterName: p.ParameterName,
                      ApplyMethod:
                        p.ApplyType === "static"
                          ? ("pending-reboot" as const)
                          : ("immediate" as const),
                    },
                  ]
                : [],
            );
            if (toReset.length > 0) {
              for (let i = 0; i < toReset.length; i += 20) {
                yield* retryWhileParameterGroupBusy(
                  rds.resetDBParameterGroup({
                    DBParameterGroupName: name,
                    ResetAllParameters: false,
                    Parameters: toReset.slice(i, i + 20),
                  }),
                );
              }
            }
          }

          const dbParameterGroupArn = observed.DBParameterGroupArn;

          const observedTags = yield* readTags(dbParameterGroupArn);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0 && dbParameterGroupArn) {
            yield* rds.addTagsToResource({
              ResourceName: dbParameterGroupArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0 && dbParameterGroupArn) {
            yield* rds.removeTagsFromResource({
              ResourceName: dbParameterGroupArn,
              TagKeys: removed,
            });
          }

          // A successful modify/reset only acknowledges the request. Read back
          // the managed group values, including absence of undeclared overrides.
          // Reuse the existing parameter-group consistency budget; retry reads
          // for a pending observation, never repeat accepted mutations here.
          const parameters = yield* readParameters(name).pipe(
            Effect.flatMap((parameters) => {
              const observed = toManagedParameterRecord(parameters, desiredParameters);
              return deepEqual(desiredParameters, observed)
                ? Effect.succeed(observed)
                : Effect.fail(new DBParameterGroupNotSettled({ resourceName: name }));
            }),
            Effect.retry({
              while: (error) => error._tag === "DBParameterGroupNotSettled",
              schedule: Schedule.spaced("5 seconds"),
              times: 8,
            }),
          );
          yield* session.note(dbParameterGroupArn ?? name);
          return {
            dbParameterGroupName: observed.DBParameterGroupName,
            dbParameterGroupArn,
            family: observed.DBParameterGroupFamily ?? news.family,
            description: observed.Description,
            parameters,
            tags: desiredTags,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* rds
            .deleteDBParameterGroup({
              DBParameterGroupName: output.dbParameterGroupName,
            })
            .pipe(Effect.catchTag("DBParameterGroupNotFoundFault", () => Effect.void));
        }),
      };
    }),
  );