sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ BackupSearch/ SearchJob.ts

import * as backupsearch from "@distilled.cloud/aws/backupsearch";
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 Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { readBackupSearchTags, syncBackupSearchTags } from "./internal.ts";

export interface BackupCreationTimeFilter {
  /** Only include recovery points created after this ISO-8601 timestamp. */
  createdAfter?: string;
  /** Only include recovery points created before this ISO-8601 timestamp. */
  createdBefore?: string;
}

export interface SearchScope {
  /**
   * Resource types of the recovery points to include in the search:
   * `S3` and/or `EBS`.
   */
  backupResourceTypes: string[];
  /** Filter recovery points by their backup creation time. */
  backupResourceCreationTime?: BackupCreationTimeFilter;
  /** Only search backups of these source resources (ARNs). */
  sourceResourceArns?: string[];
  /** Only search these recovery points (recovery point ARNs). */
  backupResourceArns?: string[];
  /** Only search recovery points carrying these tags. */
  backupResourceTags?: Record<string, string>;
}

export interface StringCondition {
  /** The string value to compare against. */
  value: string;
  /**
   * Comparison operator: `EQUALS_TO`, `NOT_EQUALS_TO`, `CONTAINS`,
   * `DOES_NOT_CONTAIN`, `BEGINS_WITH`, `ENDS_WITH`, `DOES_NOT_BEGIN_WITH`,
   * or `DOES_NOT_END_WITH`.
   * @default EQUALS_TO
   */
  operator?: string;
}

export interface LongCondition {
  /** The numeric value to compare against. */
  value: number;
  /**
   * Comparison operator: `EQUALS_TO`, `NOT_EQUALS_TO`,
   * `LESS_THAN_EQUAL_TO`, or `GREATER_THAN_EQUAL_TO`.
   * @default EQUALS_TO
   */
  operator?: string;
}

export interface TimeCondition {
  /** The ISO-8601 timestamp to compare against. */
  value: string;
  /**
   * Comparison operator: `EQUALS_TO`, `NOT_EQUALS_TO`,
   * `LESS_THAN_EQUAL_TO`, or `GREATER_THAN_EQUAL_TO`.
   * @default EQUALS_TO
   */
  operator?: string;
}

export interface S3ItemFilter {
  /** Match S3 objects by key. */
  objectKeys?: StringCondition[];
  /** Match S3 objects by size in bytes. */
  sizes?: LongCondition[];
  /** Match S3 objects by creation time. */
  creationTimes?: TimeCondition[];
  /** Match S3 objects by version id. */
  versionIds?: StringCondition[];
  /** Match S3 objects by ETag. */
  etags?: StringCondition[];
}

export interface EBSItemFilter {
  /** Match EBS files by path. */
  filePaths?: StringCondition[];
  /** Match EBS files by size in bytes. */
  sizes?: LongCondition[];
  /** Match EBS files by creation time. */
  creationTimes?: TimeCondition[];
  /** Match EBS files by last-modification time. */
  lastModificationTimes?: TimeCondition[];
}

export interface ItemFilters {
  /** Filters applied to items inside S3 recovery points. */
  s3ItemFilters?: S3ItemFilter[];
  /** Filters applied to items inside EBS recovery points. */
  ebsItemFilters?: EBSItemFilter[];
}

export interface SearchJobProps {
  /**
   * Display name of the search job. If omitted, a unique name is generated
   * from the app, stage, and logical ID. Changing the name replaces the job.
   */
  name?: string;
  /**
   * ARN of the KMS key used to encrypt the search results. Immutable —
   * changing it replaces the job.
   */
  encryptionKeyArn?: string;
  /**
   * The recovery points to search. Immutable — changing it replaces the job.
   */
  searchScope: SearchScope;
  /**
   * Filters applied to the items inside the recovery points. Immutable —
   * changing them replaces the job.
   */
  itemFilters?: ItemFilters;
  /**
   * User-defined tags for the search job.
   */
  tags?: Record<string, string>;
}

export interface SearchJob extends Resource<
  "AWS.BackupSearch.SearchJob",
  SearchJobProps,
  {
    /**
     * Service-assigned unique ID of the search job.
     */
    searchJobIdentifier: string;
    /**
     * ARN of the search job.
     */
    searchJobArn: string;
    /**
     * Name of the search job.
     */
    name: string | undefined;
    /**
     * Current status of the search job (e.g. `RUNNING`, `COMPLETED`).
     */
    status: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Backup Search job — a data-plane search over AWS Backup recovery
 * points (S3 and EBS) whose backup indexes are active. A search job is
 * immutable once started: it runs to completion, retains its results for
 * seven days, and can only be stopped while `RUNNING` (destroying the
 * resource stops a running job; completed jobs age out server-side).
 *
 * ### Creating a Search Job
 * **Example:** Search All S3 Backups
 * ```typescript
 * const search = yield* BackupSearch.SearchJob("FindReports", {
 *   searchScope: { backupResourceTypes: ["S3"] },
 *   itemFilters: {
 *     s3ItemFilters: [
 *       { objectKeys: [{ value: "reports/", operator: "BEGINS_WITH" }] },
 *     ],
 *   },
 * });
 * ```
 *
 * **Example:** Search Specific Recovery Points
 * ```typescript
 * const search = yield* BackupSearch.SearchJob("AuditSearch", {
 *   searchScope: {
 *     backupResourceTypes: ["EBS"],
 *     backupResourceArns: [recoveryPointArn],
 *     backupResourceCreationTime: { createdAfter: "2026-01-01T00:00:00Z" },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const SearchJob = Resource<SearchJob>("AWS.BackupSearch.SearchJob");

const encodeTimeCondition = (condition: TimeCondition): backupsearch.TimeCondition => ({
  Value: new Date(condition.value),
  Operator: condition.operator,
});

const encodeStringCondition = (condition: StringCondition): backupsearch.StringCondition => ({
  Value: condition.value,
  Operator: condition.operator,
});

const encodeLongCondition = (condition: LongCondition): backupsearch.LongCondition => ({
  Value: condition.value,
  Operator: condition.operator,
});

const encodeSearchScope = (scope: SearchScope): backupsearch.SearchScope => ({
  BackupResourceTypes: scope.backupResourceTypes,
  BackupResourceCreationTime: scope.backupResourceCreationTime
    ? {
        CreatedAfter: scope.backupResourceCreationTime.createdAfter
          ? new Date(scope.backupResourceCreationTime.createdAfter)
          : undefined,
        CreatedBefore: scope.backupResourceCreationTime.createdBefore
          ? new Date(scope.backupResourceCreationTime.createdBefore)
          : undefined,
      }
    : undefined,
  SourceResourceArns: scope.sourceResourceArns,
  BackupResourceArns: scope.backupResourceArns,
  BackupResourceTags: scope.backupResourceTags,
});

const encodeItemFilters = (filters: ItemFilters): backupsearch.ItemFilters => ({
  S3ItemFilters: filters.s3ItemFilters?.map((filter) => ({
    ObjectKeys: filter.objectKeys?.map(encodeStringCondition),
    Sizes: filter.sizes?.map(encodeLongCondition),
    CreationTimes: filter.creationTimes?.map(encodeTimeCondition),
    VersionIds: filter.versionIds?.map(encodeStringCondition),
    ETags: filter.etags?.map(encodeStringCondition),
  })),
  EBSItemFilters: filters.ebsItemFilters?.map((filter) => ({
    FilePaths: filter.filePaths?.map(encodeStringCondition),
    Sizes: filter.sizes?.map(encodeLongCondition),
    CreationTimes: filter.creationTimes?.map(encodeTimeCondition),
    LastModificationTimes: filter.lastModificationTimes?.map(encodeTimeCondition),
  })),
});

export const SearchJobProvider = () =>
  Provider.effect(
    SearchJob,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: SearchJobProps) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 60 }));
      });

      const get = Effect.fn(function* (searchJobIdentifier: string) {
        return yield* backupsearch
          .getSearchJob({ SearchJobIdentifier: searchJobIdentifier })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      const toAttrs = (job: backupsearch.GetSearchJobOutput) => ({
        searchJobIdentifier: job.SearchJobIdentifier,
        searchJobArn: job.SearchJobArn,
        name: job.Name,
        status: job.Status as string,
      });

      return {
        stables: ["searchJobIdentifier", "searchJobArn", "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.encryptionKeyArn ?? undefined) !== (news.encryptionKeyArn ?? undefined) ||
            JSON.stringify(olds.searchScope ?? null) !== JSON.stringify(news.searchScope ?? null) ||
            JSON.stringify(olds.itemFilters ?? null) !== JSON.stringify(news.itemFilters ?? null)
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, output }) {
          if (!output?.searchJobIdentifier) return undefined;
          const job = yield* get(output.searchJobIdentifier);
          if (job === undefined) return undefined;
          const attrs = toAttrs(job);
          const tags = yield* readBackupSearchTags(job.SearchJobArn);
          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 };

          // OBSERVE — output is only an identifier cache; the job may be gone.
          let job =
            output?.searchJobIdentifier !== undefined
              ? yield* get(output.searchJobIdentifier)
              : undefined;

          // ENSURE — a search job is immutable once started; start it if
          // missing. Any change to the scope/filters is a replacement (diff).
          if (job === undefined) {
            const started = yield* backupsearch.startSearchJob({
              Name: name,
              EncryptionKeyArn: news.encryptionKeyArn,
              SearchScope: encodeSearchScope(news.searchScope),
              ItemFilters: news.itemFilters ? encodeItemFilters(news.itemFilters) : undefined,
              Tags: desiredTags,
            });
            job = yield* backupsearch.getSearchJob({
              SearchJobIdentifier: started.SearchJobIdentifier!,
            });
          } else {
            // SYNC — tags are the only mutable aspect; diff against OBSERVED.
            yield* syncBackupSearchTags(job.SearchJobArn, desiredTags);
          }

          yield* session.note(job.SearchJobIdentifier);
          return toAttrs(job);
        }),

        delete: Effect.fn(function* ({ output }) {
          // A search job cannot be deleted — results age out after 7 days.
          // Stop it if it is still RUNNING; stopping a job in any other
          // state is a ConflictException and means there is nothing to do.
          yield* backupsearch
            .stopSearchJob({
              SearchJobIdentifier: output.searchJobIdentifier,
            })
            .pipe(
              Effect.catchTags({
                ResourceNotFoundException: () => Effect.void,
                ConflictException: () => Effect.void,
              }),
            );
        }),

        list: () =>
          backupsearch.listSearchJobs.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.SearchJobs ?? [])
                .map((summary) => ({
                  searchJobIdentifier: summary.SearchJobIdentifier!,
                  searchJobArn: summary.SearchJobArn!,
                  name: summary.Name,
                  status: (summary.Status ?? "UNKNOWN") as string,
                })),
            ),
          ),
      };
    }),
  );