sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Shield/ ProtectionGroup.ts

import * as shield from "@distilled.cloud/aws/shield";
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, diffTags, hasAlchemyTags, tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

/** How Shield Advanced aggregates traffic across a protection group. */
export type ProtectionGroupAggregation = "SUM" | "MEAN" | "MAX";

/** Which protected resources are members of the group. */
export type ProtectionGroupPattern = "ALL" | "ARBITRARY" | "BY_RESOURCE_TYPE";

/** Resource type selector for `BY_RESOURCE_TYPE` groups. */
export type ProtectedResourceType =
  | "CLOUDFRONT_DISTRIBUTION"
  | "ROUTE_53_HOSTED_ZONE"
  | "ELASTIC_IP_ALLOCATION"
  | "CLASSIC_LOAD_BALANCER"
  | "APPLICATION_LOAD_BALANCER"
  | "GLOBAL_ACCELERATOR";

export interface ProtectionGroupProps {
  /**
   * Identifier of the protection group (alphanumeric and `-`, max 36 chars).
   * Immutable — changing it replaces the group. If omitted, a unique id is
   * generated.
   */
  protectionGroupId?: string;
  /**
   * How Shield Advanced aggregates traffic across the group: `SUM` for
   * combined volume, `MEAN` for per-resource average, `MAX` for the highest
   * single-resource volume. Mutable.
   */
  aggregation: ProtectionGroupAggregation;
  /**
   * Which protected resources are members: `ALL` protected resources,
   * an `ARBITRARY` list (set `members`), or all of one `BY_RESOURCE_TYPE`
   * (set `resourceType`). Mutable.
   */
  pattern: ProtectionGroupPattern;
  /**
   * Resource type included in the group. Required when `pattern` is
   * `BY_RESOURCE_TYPE`; omit otherwise.
   */
  resourceType?: ProtectedResourceType;
  /**
   * ARNs of the protected resources in the group. Required when `pattern` is
   * `ARBITRARY`; omit otherwise.
   */
  members?: string[];
  /**
   * User-defined tags. Alchemy ownership tags are merged in automatically.
   */
  tags?: Record<string, string>;
}

export interface ProtectionGroup extends Resource<
  "AWS.Shield.ProtectionGroup",
  ProtectionGroupProps,
  {
    /** Identifier of the protection group. */
    protectionGroupId: string;
    /** ARN of the protection group. */
    protectionGroupArn: string;
    /** Traffic aggregation mode. */
    aggregation: string;
    /** Membership pattern. */
    pattern: string;
    /** Resource type for `BY_RESOURCE_TYPE` groups. */
    resourceType: string | undefined;
    /** Member resource ARNs for `ARBITRARY` groups. */
    members: string[];
    /** Tags on the protection group (including Alchemy ownership tags). */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Shield Advanced Protection Group — a collective of protected
 * resources whose traffic Shield Advanced monitors as a unit, improving
 * detection accuracy and reducing false positives.
 *
 * Requires an active Shield Advanced subscription ($3,000/month with a 1-year
 * commitment); without one every call fails with the typed
 * `SubscriptionNotFound` error.
 *
 * ### Grouping Protections
 * **Example:** Group All Protected Resources
 * ```typescript
 * const group = yield* Shield.ProtectionGroup("AllResources", {
 *   aggregation: "SUM",
 *   pattern: "ALL",
 * });
 * ```
 *
 * **Example:** Group by Resource Type
 * ```typescript
 * const group = yield* Shield.ProtectionGroup("Distributions", {
 *   aggregation: "MAX",
 *   pattern: "BY_RESOURCE_TYPE",
 *   resourceType: "CLOUDFRONT_DISTRIBUTION",
 * });
 * ```
 *
 * **Example:** Arbitrary Member List
 * ```typescript
 * const group = yield* Shield.ProtectionGroup("Fleet", {
 *   aggregation: "MEAN",
 *   pattern: "ARBITRARY",
 *   members: [distribution.distributionArn],
 *   tags: { team: "platform" },
 * });
 * ```
 */
export const ProtectionGroup = Resource<ProtectionGroup>("AWS.Shield.ProtectionGroup");

const observeGroup = (protectionGroupId: string) =>
  shield.describeProtectionGroup({ ProtectionGroupId: protectionGroupId }).pipe(
    Effect.map((r) => r.ProtectionGroup),
    Effect.catchTag(["ResourceNotFoundException", "SubscriptionNotFound"], () => Effect.undefined),
  );

const toTagRecord = (tags: shield.Tag[] | undefined): Record<string, string> =>
  tagRecord(
    (tags ?? []).flatMap((t) =>
      t.Key !== undefined && t.Value !== undefined ? [{ Key: t.Key, Value: t.Value }] : [],
    ),
  );

const readGroupTags = (protectionGroupArn: string) =>
  shield.listTagsForResource({ ResourceARN: protectionGroupArn }).pipe(
    Effect.map((r) => toTagRecord(r.Tags)),
    Effect.orElseSucceed(() => ({})),
  );

const buildAttrs = (group: shield.ProtectionGroup, tags: Record<string, string>) => ({
  protectionGroupId: group.ProtectionGroupId,
  protectionGroupArn: group.ProtectionGroupArn!,
  aggregation: group.Aggregation,
  pattern: group.Pattern,
  resourceType: group.ResourceType,
  members: [...group.Members],
  tags,
});

const sameMembers = (a: readonly string[], b: readonly string[]) =>
  a.length === b.length && [...a].sort().join(",") === [...b].sort().join(",");

export const ProtectionGroupProvider = () =>
  Provider.effect(
    ProtectionGroup,
    Effect.gen(function* () {
      const toGroupId = (id: string, props: { protectionGroupId?: string }) =>
        props.protectionGroupId
          ? Effect.succeed(props.protectionGroupId)
          : createPhysicalName({ id, maxLength: 36 });

      const syncTags = Effect.fn(function* (
        protectionGroupArn: string,
        desiredTags: Record<string, string>,
      ) {
        const observedTags = yield* readGroupTags(protectionGroupArn);
        const { upsert, removed } = diffTags(observedTags, desiredTags);
        if (upsert.length > 0) {
          yield* shield.tagResource({
            ResourceARN: protectionGroupArn,
            Tags: upsert,
          });
        }
        if (removed.length > 0) {
          yield* shield.untagResource({
            ResourceARN: protectionGroupArn,
            TagKeys: removed,
          });
        }
      });

      return {
        stables: ["protectionGroupId", "protectionGroupArn"],

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

        read: Effect.fn(function* ({ id, olds, output }) {
          const groupId = output?.protectionGroupId ?? (yield* toGroupId(id, olds ?? {}));
          const group = yield* observeGroup(groupId);
          if (!group?.ProtectionGroupArn) return undefined;
          const tags = yield* readGroupTags(group.ProtectionGroupArn);
          const attrs = buildAttrs(group, tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, session }) {
          const groupId = yield* toGroupId(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative.
          let group = yield* observeGroup(groupId);

          // 2. ENSURE — create if missing; tolerate the AlreadyExists race.
          if (!group) {
            yield* shield
              .createProtectionGroup({
                ProtectionGroupId: groupId,
                Aggregation: news.aggregation,
                Pattern: news.pattern,
                ResourceType: news.resourceType,
                Members: news.members,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
            group = yield* observeGroup(groupId);
            if (!group?.ProtectionGroupArn) {
              return yield* new ProtectionGroupUnexpectedResponse({
                message: `Failed to create or read Shield protection group ${groupId}`,
              });
            }
          } else {
            // 3. SYNC settings — diff observed against desired; update only
            //    on an actual delta.
            const changed =
              group.Aggregation !== news.aggregation ||
              group.Pattern !== news.pattern ||
              (group.ResourceType ?? undefined) !== (news.resourceType ?? undefined) ||
              !sameMembers(group.Members ?? [], news.members ?? []);
            if (changed) {
              yield* shield.updateProtectionGroup({
                ProtectionGroupId: groupId,
                Aggregation: news.aggregation,
                Pattern: news.pattern,
                ResourceType: news.resourceType,
                Members: news.members,
              });
              group = yield* observeGroup(groupId);
            }
          }

          // 3b. SYNC tags — diff against OBSERVED cloud tags.
          yield* syncTags(group!.ProtectionGroupArn!, desiredTags);

          // 4. RETURN fresh attributes.
          yield* session.note(group!.ProtectionGroupArn!);
          return buildAttrs(group!, desiredTags);
        }),

        // Enumerate every protection group in the account. Without a Shield
        // Advanced subscription the account cannot have any groups.
        list: () =>
          Effect.gen(function* () {
            const groups = yield* shield.listProtectionGroups.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) => page.ProtectionGroups ?? []),
              ),
              Effect.catchTag("SubscriptionNotFound", () => Effect.succeed([])),
            );
            return yield* Effect.forEach(
              groups.filter((g) => g.ProtectionGroupArn != null),
              (group) =>
                Effect.gen(function* () {
                  const tags = yield* readGroupTags(group.ProtectionGroupArn!);
                  return buildAttrs(group, tags);
                }),
              { concurrency: 5 },
            );
          }),

        delete: Effect.fn(function* ({ output }) {
          yield* shield
            .deleteProtectionGroup({
              ProtectionGroupId: output.protectionGroupId,
            })
            .pipe(
              Effect.catchTag(
                ["ResourceNotFoundException", "SubscriptionNotFound"],
                () => Effect.void,
              ),
            );
        }),
      };
    }),
  );