sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Macie2/ ClassificationJob.ts

import * as macie2 from "@distilled.cloud/aws/macie2";
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 Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";
import { retryThroughEnablement } from "./common.ts";

/**
 * Whether the classification job runs once (`ONE_TIME`) or on a recurring
 * schedule (`SCHEDULED`).
 */
export type JobType = "ONE_TIME" | "SCHEDULED";

/**
 * How Macie selects managed data identifiers for the job.
 */
export type ManagedDataIdentifierSelector = "ALL" | "EXCLUDE" | "INCLUDE" | "NONE" | "RECOMMENDED";

/**
 * A set of S3 buckets (within one account) that the job analyzes.
 */
export interface BucketDefinition {
  /** The account that owns the buckets. */
  accountId: string;
  /** The names of the buckets to analyze. */
  buckets: string[];
}

export interface ClassificationJobProps {
  /**
   * Custom name for the job. Must be unique per account. If omitted, a unique
   * name is generated from the app/stage/logical ID.
   */
  name?: string;

  /**
   * Whether the job runs once (`ONE_TIME`) or on a recurring schedule
   * (`SCHEDULED`).
   * @default "ONE_TIME"
   */
  jobType?: JobType;

  /**
   * The S3 buckets to analyze, grouped by owning account. Changing this
   * replaces the job — classification jobs are immutable once created.
   */
  bucketDefinitions: BucketDefinition[];

  /**
   * Optional description of the job.
   */
  description?: string;

  /**
   * The sampling depth, as a percentage, applied to objects in the buckets.
   * @default 100
   */
  samplingPercentage?: number;

  /**
   * For a scheduled job, whether Macie analyzes all existing eligible objects
   * immediately on the first run.
   */
  initialRun?: boolean;

  /**
   * How Macie selects managed data identifiers for the job.
   */
  managedDataIdentifierSelector?: ManagedDataIdentifierSelector;

  /**
   * Tags applied to the job. Alchemy ownership tags are merged in automatically.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface ClassificationJob extends Resource<
  "AWS.Macie2.ClassificationJob",
  ClassificationJobProps,
  {
    /** Generated job ID. */
    jobId: string;
    /** ARN of the classification job. */
    jobArn: string;
    /** The resolved job name. */
    name: string;
    /** Current job status (`RUNNING` / `COMPLETE` / `CANCELLED` / ...). */
    jobStatus: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An Amazon Macie classification job — scans one or more S3 buckets for
 * sensitive data. Requires Macie to be enabled for the account (see
 * `Macie2.Session`). Jobs are immutable once created; changing the job type,
 * name, or bucket set replaces the job. Destroy cancels the job.
 *
 * ### Creating a classification job
 * **Example:** One-time job over a bucket
 * ```typescript
 * const job = yield* Macie2.ClassificationJob("Scan", {
 *   jobType: "ONE_TIME",
 *   bucketDefinitions: [{ accountId, buckets: ["my-bucket"] }],
 * });
 * ```
 *
 * **Example:** Sampled scan with a description
 * ```typescript
 * const job = yield* Macie2.ClassificationJob("Scan", {
 *   jobType: "ONE_TIME",
 *   bucketDefinitions: [{ accountId, buckets: ["my-bucket"] }],
 *   samplingPercentage: 20,
 *   description: "PII sweep",
 * });
 * ```
 */
const ClassificationJobResource = Resource<ClassificationJob>("AWS.Macie2.ClassificationJob");

export { ClassificationJobResource as ClassificationJob };

const createName = (id: string, props: Partial<ClassificationJobProps>) =>
  props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 200 });

// A stable fingerprint of the immutable definition — any change replaces.
const fingerprint = (props: Partial<ClassificationJobProps>) =>
  JSON.stringify({
    jobType: props.jobType ?? "ONE_TIME",
    bucketDefinitions: (props.bucketDefinitions ?? [])
      .map((b) => ({ accountId: b.accountId, buckets: [...b.buckets].sort() }))
      .sort((a, b) => a.accountId.localeCompare(b.accountId)),
  });

const buildAttrs = (jobId: string, d: macie2.DescribeClassificationJobResponse) => ({
  jobId,
  jobArn: d.jobArn!,
  name: d.name!,
  jobStatus: d.jobStatus,
});

export const ClassificationJobProvider = () =>
  Provider.effect(
    ClassificationJobResource,
    Effect.gen(function* () {
      const describe = (jobId: string) =>
        macie2
          .describeClassificationJob({ jobId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      return {
        stables: ["jobId", "jobArn", "name"],

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

        // Classification jobs are enumerable, but they are per-job resources
        // (not a singleton); the engine keys them by logical ID, so return the
        // empty set here and rely on `read` for state refresh.
        list: () => Effect.succeed([]),

        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;
          if (fingerprint(olds) !== fingerprint(news)) {
            return { action: "replace" } as const;
          }
          // Jobs are immutable apart from status; nothing else to update.
          return undefined;
        }),

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

          // 1. OBSERVE — cloud state is authoritative; output is an id cache.
          let jobId = output?.jobId;
          let live = jobId ? yield* describe(jobId) : undefined;

          // 2. ENSURE — create the job if it does not exist.
          if (jobId === undefined || live === undefined) {
            const created = yield* retryThroughEnablement(
              macie2.createClassificationJob({
                name,
                jobType: news.jobType ?? "ONE_TIME",
                s3JobDefinition: {
                  bucketDefinitions: news.bucketDefinitions.map((b) => ({
                    accountId: b.accountId,
                    buckets: b.buckets,
                  })),
                },
                description: news.description,
                samplingPercentage: news.samplingPercentage,
                initialRun: news.initialRun,
                managedDataIdentifierSelector: news.managedDataIdentifierSelector,
                tags: desiredTags,
              }),
            );
            jobId = created.jobId!;
            live = yield* macie2.describeClassificationJob({ jobId });
          } else {
            // 3. SYNC tags — the definition is immutable; only tags mutate.
            const { upsert, removed } = diffTags(tagRecord(live.tags), desiredTags);
            if (upsert.length > 0) {
              yield* macie2.tagResource({
                resourceArn: live.jobArn!,
                tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
              });
            }
            if (removed.length > 0) {
              yield* macie2.untagResource({
                resourceArn: live.jobArn!,
                tagKeys: removed,
              });
            }
          }

          // 4. RETURN fresh attributes.
          const final = yield* macie2.describeClassificationJob({ jobId });
          yield* session.note(jobId);
          return buildAttrs(jobId, final);
        }),

        delete: Effect.fn(function* ({ output }) {
          // Classification jobs cannot be deleted — only cancelled. Cancelling
          // an already-terminal job raises ConflictException; treat as done.
          yield* macie2
            .updateClassificationJob({
              jobId: output.jobId,
              jobStatus: "CANCELLED",
            })
            .pipe(
              Effect.catchTags({
                ConflictException: () => Effect.void,
                ResourceNotFoundException: () => Effect.void,
              }),
            );
        }),
      };
    }),
  );