sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Personalize/ DatasetGroup.ts

import * as personalize from "@distilled.cloud/aws/personalize";
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 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";
import { readPersonalizeTags, syncPersonalizeTags } from "./internal.ts";

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

export interface DatasetGroupProps {
  /**
   * Name of the dataset group. If omitted, a unique name is generated from the
   * app, stage, and logical ID. Changing the name replaces the group.
   */
  name?: string;
  /**
   * ARN of an IAM role Personalize assumes to access a customer-managed KMS
   * key. Immutable — changing it replaces the group.
   */
  roleArn?: string;
  /**
   * ARN of a customer-managed KMS key used to encrypt the datasets. Immutable
   * — changing it replaces the group.
   */
  kmsKeyArn?: string;
  /**
   * The domain of a domain dataset group (`ECOMMERCE` or `VIDEO_ON_DEMAND`).
   * Omit for a custom dataset group. Immutable — changing it replaces the
   * group.
   */
  domain?: string;
  /**
   * User-defined tags for the dataset group.
   */
  tags?: Record<string, string>;
}

export interface DatasetGroup extends Resource<
  "AWS.Personalize.DatasetGroup",
  DatasetGroupProps,
  {
    /**
     * ARN of the dataset group.
     */
    datasetGroupArn: string;
    /**
     * Name of the dataset group.
     */
    name: string;
    /**
     * Dataset group status (e.g. `ACTIVE`, `CREATE PENDING`).
     */
    status: string;
    /**
     * Domain of the dataset group (`ECOMMERCE` or `VIDEO_ON_DEMAND`) when
     * it is a domain dataset group.
     */
    domain: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An Amazon Personalize dataset group — the top-level container that holds the
 * datasets, solutions, and campaigns for a single use case. Creating a dataset
 * group is cheap and fast; the expensive training work lives in solutions and
 * campaigns provisioned separately.
 *
 * ### Creating a Dataset Group
 * **Example:** Custom Dataset Group
 * ```typescript
 * const group = yield* Personalize.DatasetGroup("Recommendations", {});
 * ```
 *
 * **Example:** Domain Dataset Group with Encryption
 * ```typescript
 * const group = yield* Personalize.DatasetGroup("Storefront", {
 *   domain: "ECOMMERCE",
 *   roleArn: role.roleArn,
 *   kmsKeyArn: key.keyArn,
 *   tags: { team: "growth" },
 * });
 * ```
 *
 * @resource
 */
export const DatasetGroup = Resource<DatasetGroup>("AWS.Personalize.DatasetGroup");

export const DatasetGroupProvider = () =>
  Provider.effect(
    DatasetGroup,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: DatasetGroupProps) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 63 }));
      });

      const describe = Effect.fn(function* (datasetGroupArn: string) {
        const response = yield* personalize
          .describeDatasetGroup({ datasetGroupArn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.datasetGroup;
      });

      /** Poll until the group reaches ACTIVE; fail fast on CREATE FAILED. */
      const waitActive = Effect.fn(function* (datasetGroupArn: string) {
        const group = yield* describe(datasetGroupArn).pipe(
          Effect.repeat({
            schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(40)]),
            until: (g) => g?.status === "ACTIVE" || (g?.status ?? "").includes("FAILED"),
          }),
        );
        if (group?.status !== "ACTIVE") {
          return yield* new PersonalizeDatasetGroupNotReady({
            message: `Personalize dataset group ${datasetGroupArn} did not become ACTIVE (status: ${group?.status}, reason: ${group?.failureReason})`,
          });
        }
        return group;
      });

      /** Find an existing dataset group's ARN by its (deterministic) name. */
      const findArnByName = Effect.fn(function* (name: string) {
        const pages = yield* personalize.listDatasetGroups.pages({}).pipe(Stream.runCollect);
        return Array.from(pages)
          .flatMap((page) => page.datasetGroups ?? [])
          .find((summary) => summary.name === name)?.datasetGroupArn;
      });

      const toAttrs = (group: personalize.DatasetGroup) => ({
        datasetGroupArn: group.datasetGroupArn!,
        name: group.name!,
        status: group.status!,
        domain: group.domain,
      });

      /** Bounded retry schedule for ResourceInUse while async deletes drain. */
      const inUseRetry = {
        while: (e: { _tag: string }) => e._tag === "ResourceInUseException",
        schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
      };

      const listChildren = Effect.fn(function* (datasetGroupArn: string) {
        const [trackers, filters, solutions, datasets] = yield* Effect.all(
          [
            personalize.listEventTrackers.pages({ datasetGroupArn }).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.eventTrackers ?? [])),
            ),
            personalize.listFilters.pages({ datasetGroupArn }).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Filters ?? [])),
            ),
            personalize.listSolutions.pages({ datasetGroupArn }).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.solutions ?? [])),
            ),
            personalize.listDatasets.pages({ datasetGroupArn }).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.datasets ?? [])),
            ),
          ],
          { concurrency: 4 },
        );
        return { trackers, filters, solutions, datasets };
      });

      /**
       * DeleteDatasetGroup requires all children (event trackers, filters,
       * campaigns, solutions, datasets) to be deleted first. Children created
       * out-of-band (e.g. via CreateSolution/CreateCampaign runtime bindings)
       * are not tracked in state, so the group drains any that remain. Each
       * child delete is idempotent (NotFound tolerated) and asynchronous, so
       * after issuing the deletes we poll (bounded) until the group is empty.
       */
      const drainChildren = Effect.fn(function* (datasetGroupArn: string) {
        const { trackers, filters, solutions, datasets } = yield* listChildren(datasetGroupArn);

        yield* Effect.forEach(
          trackers,
          (t) =>
            personalize.deleteEventTracker({ eventTrackerArn: t.eventTrackerArn! }).pipe(
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
              Effect.retry(inUseRetry),
            ),
          { concurrency: 4 },
        );

        yield* Effect.forEach(
          filters,
          (f) =>
            personalize.deleteFilter({ filterArn: f.filterArn! }).pipe(
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
              Effect.retry(inUseRetry),
            ),
          { concurrency: 4 },
        );

        // Campaigns block their solution's deletion, so drain them per
        // solution before deleting the solution.
        yield* Effect.forEach(
          solutions,
          Effect.fn(function* (s) {
            const campaigns = yield* personalize.listCampaigns
              .pages({ solutionArn: s.solutionArn })
              .pipe(
                Stream.runCollect,
                Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.campaigns ?? [])),
              );
            yield* Effect.forEach(
              campaigns,
              (c) =>
                personalize.deleteCampaign({ campaignArn: c.campaignArn! }).pipe(
                  Effect.catchTag("ResourceNotFoundException", () => Effect.void),
                  Effect.retry(inUseRetry),
                ),
              { concurrency: 4 },
            );
            yield* personalize.deleteSolution({ solutionArn: s.solutionArn! }).pipe(
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
              // Campaign deletion is async — retry while it drains.
              Effect.retry(inUseRetry),
            );
          }),
          { concurrency: 2 },
        );

        yield* Effect.forEach(
          datasets,
          (d) =>
            personalize.deleteDataset({ datasetArn: d.datasetArn! }).pipe(
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
              Effect.retry(inUseRetry),
            ),
          { concurrency: 4 },
        );

        // All child deletes are asynchronous — wait (bounded) until the group
        // reports no remaining children so DeleteDatasetGroup succeeds.
        const remaining = yield* listChildren(datasetGroupArn).pipe(
          Effect.repeat({
            schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(40)]),
            until: (children): boolean =>
              children.trackers.length === 0 &&
              children.filters.length === 0 &&
              children.solutions.length === 0 &&
              children.datasets.length === 0,
          }),
        );
        if (
          remaining.trackers.length +
            remaining.filters.length +
            remaining.solutions.length +
            remaining.datasets.length >
          0
        ) {
          return yield* new PersonalizeDatasetGroupNotReady({
            message: `Personalize dataset group ${datasetGroupArn} still has children after drain (trackers: ${remaining.trackers.length}, filters: ${remaining.filters.length}, solutions: ${remaining.solutions.length}, datasets: ${remaining.datasets.length})`,
          });
        }
      });

      return {
        stables: ["datasetGroupArn", "name"],

        diff: Effect.fn(function* ({ id, olds = {}, news }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (
            oldName !== newName ||
            (olds.roleArn ?? undefined) !== (news.roleArn ?? undefined) ||
            (olds.kmsKeyArn ?? undefined) !== (news.kmsKeyArn ?? undefined) ||
            (olds.domain ?? undefined) !== (news.domain ?? undefined)
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, output }) {
          if (!output?.datasetGroupArn) return undefined;
          const group = yield* describe(output.datasetGroupArn);
          if (group === undefined) return undefined;
          const attrs = toAttrs(group);
          const tags = yield* readPersonalizeTags(group.datasetGroupArn!);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

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

          // 1. Observe — cloud state is authoritative; output is an ARN cache.
          let group =
            output?.datasetGroupArn !== undefined
              ? yield* describe(output.datasetGroupArn)
              : undefined;

          // 2. Ensure — create if missing, then wait for ACTIVE. A crashed
          //    prior run may have left a same-named group behind with no
          //    persisted state — adopt it by name and converge.
          if (group === undefined) {
            const arn = yield* personalize
              .createDatasetGroup({
                name,
                roleArn: news.roleArn,
                kmsKeyArn: news.kmsKeyArn,
                domain: news.domain,
                tags: Object.entries(desiredTags).map(([tagKey, tagValue]) => ({
                  tagKey,
                  tagValue,
                })),
              })
              .pipe(
                Effect.map((created) => created.datasetGroupArn!),
                Effect.catchTag("ResourceAlreadyExistsException", (error) =>
                  findArnByName(name).pipe(
                    Effect.flatMap((existing) =>
                      existing === undefined ? Effect.fail(error) : Effect.succeed(existing),
                    ),
                  ),
                ),
              );
            group = yield* waitActive(arn);
          }

          // 3. Sync tags — diff against OBSERVED cloud tags (no-op after a
          //    fresh create; converges an adopted leftover).
          yield* syncPersonalizeTags(group.datasetGroupArn!, desiredTags);

          yield* session.note(group.datasetGroupArn!);
          return toAttrs(group);
        }),

        delete: Effect.fn(function* ({ output }) {
          // DeleteDatasetGroup requires every child — event trackers, filters,
          // campaigns, solutions, and datasets — to be deleted first, and each
          // child delete is itself asynchronous. Deletion ordering can't
          // guarantee children-before-parent (bindings/tests create children
          // out-of-band that are not tracked in state), so drain the group's
          // remaining children before deleting the group itself. Every step is
          // idempotent and NotFound-tolerant.
          const group = yield* describe(output.datasetGroupArn);
          if (group !== undefined) {
            yield* drainChildren(output.datasetGroupArn);
          }
          yield* personalize.deleteDatasetGroup({ datasetGroupArn: output.datasetGroupArn }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            // Tolerate the eventual-consistency window while the drained
            // children finish their own asynchronous deletions.
            Effect.retry({
              while: (e) => e._tag === "ResourceInUseException",
              schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
            }),
          );
          // Deletion is asynchronous (DELETE IN_PROGRESS) — wait until the
          // group is actually gone so the run leaves no lingering resources
          // (the group's auto-created event schema is removed with it).
          const remaining = yield* describe(output.datasetGroupArn).pipe(
            Effect.repeat({
              schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(40)]),
              until: (group): boolean => group === undefined,
            }),
          );
          if (remaining !== undefined) {
            return yield* new PersonalizeDatasetGroupNotReady({
              message: `Personalize dataset group ${output.datasetGroupArn} was not deleted (status: ${remaining.status})`,
            });
          }
        }),

        list: () =>
          personalize.listDatasetGroups.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.datasetGroups ?? [])),
            Effect.flatMap(
              Effect.forEach(
                (summary) =>
                  describe(summary.datasetGroupArn!).pipe(
                    Effect.map((g) => (g ? toAttrs(g) : undefined)),
                  ),
                { concurrency: 4 },
              ),
            ),
            Effect.map((items) => items.filter((item) => item !== undefined)),
          ),
      };
    }),
  );