sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudControl/ Resource.ts

import * as cloudcontrol from "@distilled.cloud/aws/cloudcontrol";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource as makeResource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

export interface CloudControlResourceProps {
  /**
   * The CloudFormation resource type name, e.g. `"AWS::SNS::Topic"` or
   * `"AWS::SSM::Parameter"`. Changing the type replaces the resource. See the
   * Cloud Control API's supported resource types in the AWS documentation.
   */
  typeName: string;
  /**
   * A specific version of the resource type to use. Defaults to the account's
   * default version.
   */
  typeVersionId?: string;
  /**
   * The desired state of the resource as a plain object matching the CFN
   * resource type's property schema (e.g. `{ Name, Type, Value }` for
   * `AWS::SSM::Parameter`). Only the keys you specify are managed — on update,
   * a JSON Patch is computed over exactly these keys, so create-only
   * properties you never change are left untouched.
   */
  desiredState: Record<string, unknown>;
  /**
   * ARN of an IAM role Cloud Control assumes to perform the operation.
   * Defaults to the deploying principal's credentials.
   */
  roleArn?: string;
}

export interface CloudControlResource extends makeResource<
  "AWS.CloudControl.Resource",
  CloudControlResourceProps,
  {
    /** The CloudFormation resource type name (e.g. `AWS::SSM::Parameter`). */
    typeName: string;
    /** The resource's primary identifier assigned by Cloud Control. */
    identifier: string;
    /** The observed properties of the resource as a plain object. */
    properties: Record<string, unknown>;
  },
  never,
  Providers
> {}

/**
 * A generic AWS resource managed through the Cloud Control API — the escape
 * hatch that covers hundreds of CloudFormation resource types with a single
 * Alchemy resource.
 *
 * Provide a CloudFormation `typeName` and a `desiredState` object; the provider
 * drives Cloud Control's asynchronous create/update/delete and polls the
 * request token (bounded) until it reaches `SUCCESS`, surfacing a `FAILED`
 * operation as a typed error rather than hanging. Updates are expressed as an
 * RFC 6902 JSON Patch computed over the keys you specify.
 * ### Managing a Resource
 * **Example:** SSM Parameter
 * ```typescript
 * const param = yield* CloudControl.Resource("Greeting", {
 *   typeName: "AWS::SSM::Parameter",
 *   desiredState: {
 *     Name: "/app/greeting",
 *     Type: "String",
 *     Value: "hello",
 *   },
 * });
 * // param.identifier -> "/app/greeting"
 * // param.properties.Value -> "hello"
 * ```
 *
 * **Example:** SNS Topic
 * ```typescript
 * const topic = yield* CloudControl.Resource("Alerts", {
 *   typeName: "AWS::SNS::Topic",
 *   desiredState: { TopicName: "alerts", DisplayName: "Alerts" },
 * });
 * // topic.identifier -> "arn:aws:sns:us-west-2:...:alerts"
 * ```
 *
 * @resource
 */
export const Resource = makeResource<CloudControlResource>("AWS.CloudControl.Resource");

class ResourceRequestNotSettled extends Data.TaggedError("ResourceRequestNotSettled")<{
  readonly requestToken: string;
  readonly status: string;
}> {}

class ResourceRequestFailed extends Data.TaggedError("ResourceRequestFailed")<{
  readonly typeName: string;
  readonly operation: string;
  readonly errorCode: string | undefined;
  readonly statusMessage: string | undefined;
}> {}

/** Unwrap distilled's sensitive-string decoding to a plain string. */
const plain = (value: string | Redacted.Redacted<string> | undefined): string | undefined =>
  value === undefined || typeof value === "string" ? value : Redacted.value(value);

const parseProperties = (
  properties: string | Redacted.Redacted<string> | undefined,
): Record<string, unknown> => {
  const raw = plain(properties);
  if (raw === undefined) return {};
  try {
    const parsed = JSON.parse(raw);
    return parsed !== null && typeof parsed === "object" ? parsed : {};
  } catch {
    return {};
  }
};

/** RFC 6901 escape for a JSON Pointer path segment. */
const escapePointer = (key: string): string => key.replace(/~/g, "~0").replace(/\//g, "~1");

/**
 * Build an RFC 6902 JSON Patch that converges the observed properties to the
 * user-specified desired state. Only keys present in `desired` are touched —
 * create-only properties the user never changes are left alone (patching them
 * would trigger `NotUpdatableException`).
 */
const buildPatch = (
  observed: Record<string, unknown>,
  desired: Record<string, unknown>,
): Array<{ op: "add" | "replace"; path: string; value: unknown }> =>
  Object.entries(desired).flatMap(([key, value]) => {
    const hasKey = Object.prototype.hasOwnProperty.call(observed, key);
    if (hasKey && deepEqual(observed[key], value)) {
      return [];
    }
    return [
      {
        op: hasKey ? ("replace" as const) : ("add" as const),
        path: `/${escapePointer(key)}`,
        value,
      },
    ];
  });

/**
 * Normalize `AWS::SSM::Document` state before diffing. SSM returns JSON
 * `Content` as a formatted string, so compare it structurally, and omits
 * the write-only `UpdateMethod`, which selects how a real change is applied
 * rather than describing persistent document state — resend it only
 * alongside an actual change.
 *
 * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ssm-document.html
 */
const resourcePatch = (
  typeName: string,
  observed: Record<string, unknown>,
  desired: Record<string, unknown>,
) => {
  if (typeName !== "AWS::SSM::Document") return buildPatch(observed, desired);
  const { UpdateMethod, ...document } = desired;
  const normalizeDocument = (value: Record<string, unknown>) =>
    value.DocumentFormat === "JSON" && typeof value.Content === "string"
      ? { ...value, Content: JSON.parse(value.Content) }
      : value;
  const patch = buildPatch(normalizeDocument(observed), normalizeDocument(document));
  return patch.length > 0 && UpdateMethod !== undefined
    ? [...patch, ...buildPatch(observed, { UpdateMethod })]
    : patch;
};

export const CloudControlResourceProvider = () =>
  Provider.effect(
    Resource,
    Effect.gen(function* () {
      /**
       * Poll a Cloud Control request token until the operation settles.
       * Operations are typically fast (seconds); budget ~5 min (60 * 5s).
       * Returns the terminal ProgressEvent, failing on FAILED.
       */
      const waitForRequest = Effect.fn(function* (requestToken: string, typeName: string) {
        const event = yield* cloudcontrol
          .getResourceRequestStatus({ RequestToken: requestToken })
          .pipe(
            Effect.map((r) => r.ProgressEvent),
            Effect.flatMap((e) => {
              const status = e?.OperationStatus;
              if (
                status === "PENDING" ||
                status === "IN_PROGRESS" ||
                status === "CANCEL_IN_PROGRESS"
              ) {
                return Effect.fail(
                  new ResourceRequestNotSettled({
                    requestToken,
                    status: status ?? "UNKNOWN",
                  }),
                );
              }
              return Effect.succeed(e);
            }),
            Effect.retry({
              while: (e) => e._tag === "ResourceRequestNotSettled",
              schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(60)]),
            }),
          );
        if (event?.OperationStatus !== "SUCCESS") {
          return yield* new ResourceRequestFailed({
            typeName,
            operation: event?.Operation ?? "UNKNOWN",
            errorCode: event?.ErrorCode,
            statusMessage: event?.StatusMessage,
          });
        }
        return event;
      });

      /** Read live resource properties; a missing resource reads as absent. */
      const getResource = Effect.fn(function* (typeName: string, identifier: string) {
        return yield* cloudcontrol.getResource({ TypeName: typeName, Identifier: identifier }).pipe(
          Effect.map((r) => r.ResourceDescription),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      return {
        stables: ["typeName", "identifier"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          if ((olds?.typeName ?? undefined) !== (news?.typeName ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ output }) {
          if (output?.identifier === undefined) return undefined;
          const description = yield* getResource(output.typeName, output.identifier);
          if (description?.Identifier === undefined) return undefined;
          return {
            typeName: output.typeName,
            identifier: description.Identifier,
            properties: parseProperties(description.Properties),
          };
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const typeName = news.typeName;

          // 1. Observe — cloud state is authoritative; output is only an id
          // cache.
          let identifier = output?.identifier;
          let description =
            identifier !== undefined ? yield* getResource(typeName, identifier) : undefined;

          // 2. Ensure — create if missing, then poll to SUCCESS.
          if (description === undefined) {
            const created = yield* cloudcontrol.createResource({
              TypeName: typeName,
              TypeVersionId: news.typeVersionId,
              RoleArn: news.roleArn,
              DesiredState: JSON.stringify(news.desiredState),
            });
            const settled = yield* waitForRequest(created.ProgressEvent!.RequestToken!, typeName);
            identifier = settled.Identifier!;
            description = yield* getResource(typeName, identifier);
          } else {
            // 3. Sync — patch only the drifted user-specified keys.
            identifier = description.Identifier!;
            const patch = resourcePatch(
              typeName,
              parseProperties(description.Properties),
              news.desiredState,
            );
            if (patch.length > 0) {
              const updated = yield* cloudcontrol.updateResource({
                TypeName: typeName,
                TypeVersionId: news.typeVersionId,
                RoleArn: news.roleArn,
                Identifier: identifier,
                PatchDocument: JSON.stringify(patch),
              });
              yield* waitForRequest(updated.ProgressEvent!.RequestToken!, typeName);
              description = yield* getResource(typeName, identifier);
            }
          }

          // 4. Return fresh attributes.
          yield* session.note(identifier);
          return {
            typeName,
            identifier,
            properties: parseProperties(description?.Properties),
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          const deleted = yield* cloudcontrol
            .deleteResource({
              TypeName: output.typeName,
              Identifier: output.identifier,
            })
            .pipe(
              Effect.map((r) => r.ProgressEvent),
              Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
            );
          if (deleted?.RequestToken !== undefined) {
            yield* waitForRequest(deleted.RequestToken, output.typeName).pipe(
              // A resource already gone by the time deletion settles is not an
              // error.
              Effect.catchTag("ResourceRequestFailed", (e) =>
                e.errorCode === "NotFound" ? Effect.void : Effect.fail(e),
              ),
            );
          }
        }),

        // Cloud Control's ListResources requires a TypeName; there is no
        // global enumeration across every managed type, so the generic
        // escape-hatch resource is not listable.
        list: () => Effect.succeed([]),
      };
    }),
  );