sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EntityResolution/ IdMappingWorkflow.ts

import * as entityresolution from "@distilled.cloud/aws/entityresolution";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 { retryRolePropagation, syncEntityResolutionTags, toTagRecord } from "./internal.ts";

export interface IdMappingWorkflowProps {
  /**
   * Name of the ID mapping workflow. Must be unique per account/region and
   * match `[a-zA-Z_0-9-]*`. If omitted, a unique name is generated from the
   * app, stage, and logical ID. Changing the name replaces the workflow.
   */
  workflowName?: string;
  /**
   * A description of the workflow.
   */
  description?: string;
  /**
   * The input records to map: for rule-based mapping, entries reference ID
   * namespace ARNs (`inputSourceARN`) with their role (`type: "SOURCE"` or
   * `"TARGET"`); for provider-based mapping, entries may reference Glue
   * tables with a `schemaName`.
   */
  inputSourceConfig: entityresolution.IdMappingWorkflowInputSource[];
  /**
   * Where mapped output records are written: an S3 path (`outputS3Path`) and
   * an optional KMS key (`KMSArn`). Optional — rule-based workflows can also
   * receive per-job output configuration on `StartIdMappingJob`.
   */
  outputSourceConfig?: entityresolution.IdMappingWorkflowOutputSource[];
  /**
   * How records are mapped: `RULE_BASED` with `ruleBasedProperties`
   * (definition type, attribute/record matching models) or a `PROVIDER`
   * service (e.g. LiveRamp).
   */
  idMappingTechniques: entityresolution.IdMappingTechniques;
  /**
   * Incremental-run configuration. Note the service currently rejects
   * incremental processing for ID mapping workflows.
   */
  incrementalRunConfig?: entityresolution.IdMappingIncrementalRunConfig;
  /**
   * The ARN of the IAM role Entity Resolution assumes to read Glue-table
   * input sources and write the S3 output on your behalf. Optional when all
   * input sources are ID namespaces that carry their own roles.
   */
  roleArn?: string;
  /**
   * Tags to apply to the workflow. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface IdMappingWorkflow extends Resource<
  "AWS.EntityResolution.IdMappingWorkflow",
  IdMappingWorkflowProps,
  {
    /**
     * The name of the ID mapping workflow.
     */
    workflowName: string;
    /**
     * The ARN of the ID mapping workflow.
     */
    workflowArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Entity Resolution ID mapping workflow — a data-processing job
 * definition that translates record identifiers between a `SOURCE` and a
 * `TARGET` ID namespace, using rule-based matching or a provider service.
 *
 * The workflow definition itself is cheap and instant; a mapping RUN
 * (`StartIdMappingJob`) processes the full input and takes many minutes.
 *
 * ### Creating ID Mapping Workflows
 * **Example:** Rule-based ID mapping between two namespaces
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const workflow = yield* AWS.EntityResolution.IdMappingWorkflow("Map", {
 *   inputSourceConfig: [
 *     { inputSourceARN: source.idNamespaceArn, type: "SOURCE" },
 *     { inputSourceARN: target.idNamespaceArn, type: "TARGET" },
 *   ],
 *   idMappingTechniques: {
 *     idMappingType: "RULE_BASED",
 *     ruleBasedProperties: {
 *       ruleDefinitionType: "TARGET",
 *       attributeMatchingModel: "ONE_TO_ONE",
 *       recordMatchingModel: "ONE_SOURCE_TO_ONE_TARGET",
 *     },
 *   },
 *   outputSourceConfig: [
 *     { outputS3Path: `s3://${bucket.bucketName}/idmapping/` },
 *   ],
 *   roleArn: role.roleArn,
 * });
 * ```
 *
 * @resource
 */
export const IdMappingWorkflow = Resource<IdMappingWorkflow>(
  "AWS.EntityResolution.IdMappingWorkflow",
);

export const IdMappingWorkflowProvider = () =>
  Provider.effect(
    IdMappingWorkflow,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { workflowName?: string | undefined },
      ) {
        return props.workflowName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
      });

      /** Get an ID mapping workflow by name; typed not-found → undefined. */
      const getByName = Effect.fn(function* (workflowName: string) {
        return yield* entityresolution
          .getIdMappingWorkflow({ workflowName })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      return {
        stables: ["workflowName", "workflowArn"],

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.workflowName ?? (yield* createName(id, olds ?? {}));
          const workflow = yield* getByName(name);
          if (workflow === undefined) return undefined;
          const attrs = {
            workflowName: workflow.workflowName,
            workflowArn: workflow.workflowArn,
          };
          // getIdMappingWorkflow returns tags — use the observed tags for
          // the ownership check.
          const tags = toTagRecord(workflow.tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

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

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

          // 1. Observe — names are unique, so the name IS the identity.
          let workflow = yield* getByName(name);

          // 2. Ensure — create when missing. A freshly-created IAM role is
          //    transiently rejected while IAM propagates; tolerate the
          //    concurrent-create race, then re-observe: the create response
          //    is a structural subset of the Get shape (it omits
          //    createdAt/updatedAt/tags).
          if (workflow === undefined) {
            yield* entityresolution
              .createIdMappingWorkflow({
                workflowName: name,
                description: news.description,
                inputSourceConfig: news.inputSourceConfig,
                outputSourceConfig: news.outputSourceConfig,
                idMappingTechniques: news.idMappingTechniques,
                incrementalRunConfig: news.incrementalRunConfig,
                roleArn: news.roleArn,
                tags: desiredTags,
              })
              .pipe(
                retryRolePropagation,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
            workflow = yield* entityresolution.getIdMappingWorkflow({
              workflowName: name,
            });
          }

          // 3. Sync — everything except the name updates in place via a
          //    full-PUT update. Only call the API on an actual delta between
          //    OBSERVED and desired configuration.
          const desired = {
            description: news.description ?? undefined,
            inputSourceConfig: news.inputSourceConfig,
            outputSourceConfig: news.outputSourceConfig ?? undefined,
            idMappingTechniques: news.idMappingTechniques,
            incrementalRunConfig: news.incrementalRunConfig ?? undefined,
            roleArn: news.roleArn ?? undefined,
          };
          const observed = {
            description: workflow.description ?? undefined,
            inputSourceConfig: workflow.inputSourceConfig,
            outputSourceConfig: workflow.outputSourceConfig ?? undefined,
            idMappingTechniques: workflow.idMappingTechniques,
            incrementalRunConfig: workflow.incrementalRunConfig ?? undefined,
            roleArn: workflow.roleArn ?? undefined,
          };
          if (!deepEqual(observed, desired)) {
            // The update response omits createdAt/updatedAt/tags; the ARN is
            // stable, so keep the observed Get shape.
            yield* entityresolution
              .updateIdMappingWorkflow({
                workflowName: name,
                description: news.description,
                inputSourceConfig: news.inputSourceConfig,
                outputSourceConfig: news.outputSourceConfig,
                idMappingTechniques: news.idMappingTechniques,
                incrementalRunConfig: news.incrementalRunConfig,
                roleArn: news.roleArn,
              })
              .pipe(retryRolePropagation);
          }

          const workflowArn = workflow.workflowArn;

          // 3b. Sync tags against OBSERVED cloud tags (adoption-safe).
          yield* syncEntityResolutionTags(workflowArn, desiredTags);

          yield* session.note(workflowArn);
          return { workflowName: name, workflowArn };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteIdMappingWorkflow succeeds even when the workflow is
          // already gone; a running mapping job conflicts — retry briefly.
          yield* entityresolution
            .deleteIdMappingWorkflow({ workflowName: output.workflowName })
            .pipe(
              Effect.retry({
                while: (e) => e._tag === "ConflictException",
                schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
              }),
            );
        }),

        list: () =>
          entityresolution.listIdMappingWorkflows.items({}).pipe(
            Stream.map((summary) => ({
              workflowName: summary.workflowName,
              workflowArn: summary.workflowArn,
            })),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
          ),
      };
    }),
  );