sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AppConfig/ Extension.ts

import * as appconfig from "@distilled.cloud/aws/appconfig";
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, hasAlchemyTags } from "alchemy/Tags";
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 { readAppConfigTags, syncAppConfigTags } from "./internal.ts";

/**
 * The workflow points at which AppConfig invokes an extension's actions.
 * `PRE_*` action points run synchronously and can validate or modify the
 * operation; `ON_*` action points are notifications fired as a deployment
 * progresses.
 */
export type ExtensionActionPoint =
  | "PRE_CREATE_HOSTED_CONFIGURATION_VERSION"
  | "PRE_START_DEPLOYMENT"
  | "AT_DEPLOYMENT_TICK"
  | "ON_DEPLOYMENT_START"
  | "ON_DEPLOYMENT_STEP"
  | "ON_DEPLOYMENT_BAKING"
  | "ON_DEPLOYMENT_COMPLETE"
  | "ON_DEPLOYMENT_ROLLED_BACK";

/**
 * A single action AppConfig performs when the owning action point fires.
 */
export interface ExtensionAction {
  /** Name of the action (unique within the extension). */
  name: string;
  /** Description of what the action does. */
  description?: string;
  /**
   * ARN of the integration target: a Lambda function, SNS topic, SQS queue,
   * or EventBridge event bus.
   */
  uri: string;
  /**
   * ARN of an IAM role AppConfig assumes to invoke the target. Required for
   * Lambda, SNS, and SQS targets; not used for EventBridge targets.
   */
  roleArn?: string;
}

/**
 * A parameter the extension accepts. Values are supplied per association via
 * {@link ExtensionAssociationProps.parameters}.
 */
export interface ExtensionParameter {
  /** Description of the parameter. */
  description?: string;
  /** Whether every association must supply a value. */
  required?: boolean;
  /** Whether the value may be supplied at deployment time. */
  dynamic?: boolean;
}

export interface ExtensionProps {
  /**
   * Name of the extension. If omitted, a deterministic physical name is
   * generated. Changing the name replaces the extension.
   */
  extensionName?: string;
  /**
   * Description of the extension.
   */
  description?: string;
  /**
   * The actions to perform, keyed by the action point that triggers them.
   */
  actions: { [P in ExtensionActionPoint]?: ExtensionAction[] };
  /**
   * Parameters accepted by the extension, keyed by parameter name. Values are
   * supplied when the extension is associated with a resource.
   */
  parameters?: Record<string, ExtensionParameter>;
  /**
   * User-defined tags for the extension.
   */
  tags?: Record<string, string>;
}

export interface Extension extends Resource<
  "AWS.AppConfig.Extension",
  ExtensionProps,
  {
    extensionId: string;
    extensionName: string;
    extensionArn: string;
    versionNumber: number;
  },
  never,
  Providers
> {}

/**
 * An AWS AppConfig extension — a set of actions AppConfig performs at
 * specific points of the configuration workflow (before a version is
 * created, before/while/after a deployment). Actions can invoke Lambda
 * functions, publish to SNS/SQS, or emit EventBridge events.
 *
 * Associate the extension with an application, environment, or configuration
 * profile using {@link ExtensionAssociation}.
 *
 * ### Creating an Extension
 * **Example:** Notify a Lambda when a deployment completes
 * ```typescript
 * const extension = yield* AppConfig.Extension("DeployHook", {
 *   actions: {
 *     ON_DEPLOYMENT_COMPLETE: [
 *       {
 *         name: "notify",
 *         uri: fn.functionArn,
 *         roleArn: role.roleArn,
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * **Example:** Validate content before a deployment starts
 * ```typescript
 * const extension = yield* AppConfig.Extension("PreflightCheck", {
 *   description: "Reject deployments outside business hours",
 *   actions: {
 *     PRE_START_DEPLOYMENT: [
 *       { name: "preflight", uri: fn.functionArn, roleArn: role.roleArn },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Extension = Resource<Extension>("AWS.AppConfig.Extension");

const toWireActions = (
  actions: ExtensionProps["actions"],
): { [key: string]: appconfig.Action[] | undefined } =>
  Object.fromEntries(
    Object.entries(actions).map(([point, list]) => [
      point,
      list?.map((action) => ({
        Name: action.name,
        Description: action.description,
        Uri: action.uri,
        RoleArn: action.roleArn,
      })),
    ]),
  );

const toWireParameters = (
  parameters: ExtensionProps["parameters"],
): { [key: string]: appconfig.Parameter | undefined } | undefined =>
  parameters === undefined
    ? undefined
    : Object.fromEntries(
        Object.entries(parameters).map(([name, parameter]) => [
          name,
          {
            Description: parameter.description,
            Required: parameter.required,
            Dynamic: parameter.dynamic,
          },
        ]),
      );

/** Stable JSON for order-insensitive comparison of wire action/param maps. */
const stableJson = (value: unknown): string =>
  JSON.stringify(value, (_, v) =>
    v !== null && typeof v === "object" && !Array.isArray(v)
      ? Object.fromEntries(
          Object.entries(v as Record<string, unknown>)
            .filter(([, fieldValue]) => fieldValue !== undefined)
            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
        )
      : v,
  );

export const ExtensionProvider = () =>
  Provider.effect(
    Extension,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<ExtensionProps>) =>
        props.extensionName
          ? Effect.succeed(props.extensionName)
          : createPhysicalName({ id, maxLength: 64 });

      const readExtension = Effect.fn(function* (extensionId: string) {
        return yield* appconfig
          .getExtension({ ExtensionIdentifier: extensionId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      const findByName = Effect.fn(function* (name: string) {
        const summaries = yield* appconfig.listExtensions.pages({ Name: name }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Items ?? [])),
        );
        // listExtensions returns one summary per version — take the latest.
        const latest = summaries.reduce(
          (acc: appconfig.ExtensionSummary | undefined, summary: appconfig.ExtensionSummary) =>
            acc === undefined || (summary.VersionNumber ?? 0) > (acc.VersionNumber ?? 0)
              ? summary
              : acc,
          undefined,
        );
        return latest?.Id === undefined ? undefined : yield* readExtension(latest.Id);
      });

      const toAttrs = (extension: appconfig.Extension) => ({
        extensionId: extension.Id!,
        extensionName: extension.Name!,
        extensionArn: extension.Arn!,
        versionNumber: extension.VersionNumber ?? 1,
      });

      return {
        stables: ["extensionId", "extensionName", "extensionArn"],

        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 extension = output?.extensionId
            ? yield* readExtension(output.extensionId)
            : yield* findByName(yield* toName(id, olds ?? {}));
          if (extension?.Id === undefined) return undefined;
          const attrs = toAttrs(extension);
          const tags = yield* readAppConfigTags(attrs.extensionArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.extensionName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredActions = toWireActions(news.actions);
          const desiredParameters = toWireParameters(news.parameters);

          // 1. Observe.
          let observed = output?.extensionId ? yield* readExtension(output.extensionId) : undefined;
          if (observed === undefined) {
            observed = yield* findByName(name);
          }

          // 2. Ensure. A freshly created invoke role may not be assumable
          // yet (IAM propagation), which AppConfig surfaces as
          // BadRequestException — absorb that window with a bounded retry.
          if (observed?.Id === undefined) {
            observed = yield* appconfig
              .createExtension({
                Name: name,
                Description: news.description,
                Actions: desiredActions,
                Parameters: desiredParameters,
                Tags: desiredTags,
              })
              .pipe(
                Effect.retry({
                  while: (e): boolean => e._tag === "BadRequestException",
                  schedule: Schedule.fixed("3 seconds"),
                  times: 5,
                }),
              );
          } else if (
            (observed.Description ?? undefined) !== (news.description ?? undefined) ||
            stableJson(observed.Actions ?? {}) !== stableJson(desiredActions) ||
            stableJson(observed.Parameters ?? {}) !== stableJson(desiredParameters ?? {})
          ) {
            // 3. Sync — description, actions, and parameters are mutable
            // (AppConfig records the change as a new extension version).
            observed = yield* appconfig.updateExtension({
              ExtensionIdentifier: observed.Id,
              Description: news.description,
              Actions: desiredActions,
              Parameters: desiredParameters,
            });
          }

          const attrs = toAttrs(observed);

          // 3b. Sync tags against observed cloud tags.
          yield* syncAppConfigTags(attrs.extensionArn, desiredTags);

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

        delete: Effect.fn(function* ({ output }) {
          // Associations must be gone before the extension can be deleted;
          // the engine deletes them first, but the API is eventually
          // consistent, so absorb the dependency-violation window (surfaced
          // as BadRequestException) with a bounded retry.
          yield* appconfig.deleteExtension({ ExtensionIdentifier: output.extensionId }).pipe(
            Effect.retry({
              while: (e): boolean => e._tag === "BadRequestException",
              schedule: Schedule.fixed("3 seconds"),
              times: 5,
            }),
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),

        list: () =>
          Effect.gen(function* () {
            const summaries = yield* appconfig.listExtensions.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Items ?? [])),
            );
            // One summary per version — keep the latest version per id.
            const latest = new Map<string, appconfig.ExtensionSummary>();
            for (const summary of summaries) {
              if (summary.Id === undefined) continue;
              const existing = latest.get(summary.Id);
              if (
                existing === undefined ||
                (summary.VersionNumber ?? 0) > (existing.VersionNumber ?? 0)
              ) {
                latest.set(summary.Id, summary);
              }
            }
            return Array.from(latest.values()).flatMap((summary) =>
              summary.Id !== undefined &&
              summary.Name !== undefined &&
              summary.Arn !== undefined &&
              // AWS-authored extensions (AWS.AppConfig.FeatureFlags,
              // AWS.AppConfig.DeploymentNotificationsTo*, ...) are managed by
              // AWS and cannot be deleted; their ARNs have an empty account
              // segment (arn:aws:appconfig:{region}::extension/...).
              summary.Arn.split(":")[4] !== ""
                ? [
                    {
                      extensionId: summary.Id,
                      extensionName: summary.Name,
                      extensionArn: summary.Arn,
                      versionNumber: summary.VersionNumber ?? 1,
                    },
                  ]
                : [],
            );
          }),
      };
    }),
  );