sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DevOpsGuru/ ResourceCollection.ts

import * as devopsguru from "@distilled.cloud/aws/devops-guru";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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 interface TagAppBoundary {
  /**
   * Tag key that defines an application boundary. DevOps Guru requires the
   * key to begin with `devops-guru-` (any casing, e.g.
   * `DevOps-Guru-deployment-application`).
   */
  appBoundaryKey: string;
  /**
   * Tag values that select the resources to analyze. Use `["*"]` to match
   * every resource carrying the key.
   */
  tagValues: string[];
}

export interface ResourceCollectionProps {
  /**
   * Analyze resources belonging to the named CloudFormation stacks. Use
   * `{ stackNames: ["*"] }` to analyze every stack in the account. Mutually
   * exclusive with `tags` — an account's collection uses one filter type at
   * a time.
   */
  cloudFormation?: {
    /** CloudFormation stack names to analyze (`["*"]` for all stacks). */
    stackNames: string[];
  };
  /**
   * Analyze resources carrying the given app-boundary tags. Tag keys must
   * begin with `devops-guru-` (any casing). Mutually exclusive with
   * `cloudFormation`.
   */
  tags?: TagAppBoundary[];
}

export interface ResourceCollection extends Resource<
  "AWS.DevOpsGuru.ResourceCollection",
  ResourceCollectionProps,
  {
    /** CloudFormation stack names DevOps Guru analyzes. */
    cloudFormationStackNames: string[];
    /** App-boundary tag filters DevOps Guru analyzes. */
    tags: TagAppBoundary[];
  },
  never,
  Providers
> {}

/**
 * The DevOps Guru resource collection — the account/region singleton that
 * defines which AWS resources DevOps Guru analyzes for operational insights,
 * either by CloudFormation stack or by app-boundary tag. Configuring a
 * collection is what "enables" DevOps Guru analysis in an account.
 *
 * An account has exactly one collection, so this resource is a
 * capture-and-restore singleton: adopting a collection that Alchemy did not
 * configure requires `--adopt`.
 *
 * ### Defining Coverage
 * **Example:** Analyze specific CloudFormation stacks
 * ```typescript
 * const collection = yield* DevOpsGuru.ResourceCollection("Coverage", {
 *   cloudFormation: { stackNames: ["my-app-prod"] },
 * });
 * ```
 *
 * **Example:** Analyze every stack in the account
 * ```typescript
 * const collection = yield* DevOpsGuru.ResourceCollection("Coverage", {
 *   cloudFormation: { stackNames: ["*"] },
 * });
 * ```
 *
 * **Example:** Analyze resources by app-boundary tag
 * ```typescript
 * const collection = yield* DevOpsGuru.ResourceCollection("Coverage", {
 *   tags: [
 *     { appBoundaryKey: "devops-guru-app", tagValues: ["checkout", "billing"] },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const ResourceCollection = Resource<ResourceCollection>("AWS.DevOpsGuru.ResourceCollection");

/**
 * Concurrent `UpdateResourceCollection` calls conflict server-side — retry
 * the typed conflict tag on a short bounded schedule.
 *
 * Explicitly typed: inlining `Effect.retry` with options in provider
 * lifecycle code can widen the provider layer to `unknown` in declaration
 * emit.
 *
 * @internal
 */
const retryUpdateConflict = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(8)]),
  });

const sameKey = (left: string, right: string) => left.toLowerCase() === right.toLowerCase();

export const ResourceCollectionProvider = () =>
  Provider.effect(
    ResourceCollection,
    Effect.gen(function* () {
      // GetResourceCollection fails with a typed ResourceNotFoundException
      // ("No CustomerResourceFilter present") when nothing has ever been
      // configured — treat that as an empty collection.
      const observeType = Effect.fn(function* (type: devopsguru.ResourceCollectionType) {
        return yield* devopsguru.getResourceCollection.pages({ ResourceCollectionType: type }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed([] as devopsguru.GetResourceCollectionResponse[]),
          ),
        );
      });

      // Observe the full account collection (both filter types).
      const observe = Effect.gen(function* () {
        const cfnPages = yield* observeType("AWS_CLOUD_FORMATION");
        const tagPages = yield* observeType("AWS_TAGS");
        const stackNames = [
          ...new Set(
            cfnPages.flatMap((page) => page.ResourceCollection?.CloudFormation?.StackNames ?? []),
          ),
        ].sort();
        const tagMap = new Map<string, Set<string>>();
        for (const page of tagPages) {
          for (const tag of page.ResourceCollection?.Tags ?? []) {
            const values = tagMap.get(tag.AppBoundaryKey) ?? new Set<string>();
            for (const value of tag.TagValues) values.add(value);
            tagMap.set(tag.AppBoundaryKey, values);
          }
        }
        // AWS keeps an app-boundary key with an empty TagValues list after
        // its last value is removed — a key selecting no values analyzes
        // nothing, so it is treated as absent.
        const tags = [...tagMap.entries()]
          .filter(([, values]) => values.size > 0)
          .map(([appBoundaryKey, values]) => ({
            appBoundaryKey,
            tagValues: [...values].sort(),
          }))
          .sort((l, r) => l.appBoundaryKey.localeCompare(r.appBoundaryKey));
        return { stackNames, tags };
      });

      const update = Effect.fn(function* (
        action: devopsguru.UpdateResourceCollectionAction,
        filter: devopsguru.UpdateResourceCollectionFilter,
      ) {
        yield* retryUpdateConflict(
          devopsguru.updateResourceCollection({
            Action: action,
            ResourceCollection: filter,
          }),
        );
      });

      const toAttrs = (observed: { stackNames: string[]; tags: TagAppBoundary[] }) => ({
        cloudFormationStackNames: observed.stackNames,
        tags: observed.tags,
      });

      return {
        // Account/region singleton — the one collection, when configured.
        list: () =>
          observe.pipe(
            Effect.map((observed) =>
              observed.stackNames.length > 0 || observed.tags.length > 0 ? [toAttrs(observed)] : [],
            ),
          ),

        read: Effect.fn(function* ({ output }) {
          const observed = yield* observe;
          if (observed.stackNames.length === 0 && observed.tags.length === 0) {
            return undefined;
          }
          const attrs = toAttrs(observed);
          // The collection can't carry ownership tags — a configured
          // collection we have no record of belongs to someone else until
          // explicitly adopted.
          return output !== undefined ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ news, session }) {
          const desiredStacks = news.cloudFormation?.stackNames ?? [];
          const desiredTags = news.tags ?? [];

          // 1. OBSERVE — the live account collection is authoritative.
          const observed = yield* observe;

          // 2. SYNC (removals first) — the two filter types are mutually
          //    exclusive, so pruning before adding also handles switching
          //    between CloudFormation- and tag-based coverage.
          const stacksToRemove = observed.stackNames.filter(
            (name) => !desiredStacks.includes(name),
          );
          if (stacksToRemove.length > 0) {
            yield* update("REMOVE", {
              CloudFormation: { StackNames: stacksToRemove },
            });
          }
          for (const tag of observed.tags) {
            const desired = desiredTags.find((t) => sameKey(t.appBoundaryKey, tag.appBoundaryKey));
            const valuesToRemove = tag.tagValues.filter(
              (value) => !(desired?.tagValues ?? []).includes(value),
            );
            if (valuesToRemove.length > 0) {
              yield* update("REMOVE", {
                Tags: [
                  {
                    AppBoundaryKey: tag.appBoundaryKey,
                    TagValues: valuesToRemove,
                  },
                ],
              });
            }
          }

          // 3. SYNC (additions) — apply only the delta.
          const stacksToAdd = desiredStacks.filter((name) => !observed.stackNames.includes(name));
          if (stacksToAdd.length > 0) {
            yield* update("ADD", {
              CloudFormation: { StackNames: stacksToAdd },
            });
          }
          for (const desired of desiredTags) {
            const current = observed.tags.find((t) =>
              sameKey(t.appBoundaryKey, desired.appBoundaryKey),
            );
            const valuesToAdd = desired.tagValues.filter(
              (value) => !(current?.tagValues ?? []).includes(value),
            );
            if (valuesToAdd.length > 0) {
              yield* update("ADD", {
                Tags: [
                  {
                    AppBoundaryKey: desired.appBoundaryKey,
                    TagValues: valuesToAdd,
                  },
                ],
              });
            }
          }

          // 4. RETURN fresh attributes.
          const final = yield* observe;
          yield* session.note(
            final.stackNames.length > 0
              ? `stacks: ${final.stackNames.join(", ")}`
              : `tags: ${final.tags.map((t) => t.appBoundaryKey).join(", ")}`,
          );
          return toAttrs(final);
        }),

        // Deleting the collection removes every observed filter, returning
        // the account to "DevOps Guru analyzes nothing".
        delete: Effect.fn(function* () {
          const observed = yield* observe;
          if (observed.stackNames.length > 0) {
            yield* update("REMOVE", {
              CloudFormation: { StackNames: observed.stackNames },
            });
          }
          for (const tag of observed.tags) {
            yield* update("REMOVE", {
              Tags: [
                {
                  AppBoundaryKey: tag.appBoundaryKey,
                  TagValues: tag.tagValues,
                },
              ],
            });
          }
        }),
      };
    }),
  );