sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ResourceExplorer/ ExplorerIndex.ts

import * as re2 from "@distilled.cloud/aws/resource-explorer-2";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

/**
 * The type of a Resource Explorer index.
 *
 * - `LOCAL` — indexes resources in its own region only.
 * - `AGGREGATOR` — additionally replicates resource information from every
 *   other region's local index, enabling account-wide search from this
 *   region. Only one aggregator index may exist per account.
 */
export type IndexType = "LOCAL" | "AGGREGATOR";

export interface IndexProps {
  /**
   * The index type. Promote to `AGGREGATOR` to enable cross-region search
   * from this region; demote back to `LOCAL` to stop replication. Note
   * that after demoting an aggregator index AWS enforces a 24-hour wait
   * before another index can be promoted.
   * @default "LOCAL"
   */
  type?: IndexType;

  /**
   * Tags to apply to the index. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface Index extends Resource<
  "AWS.ResourceExplorer.Index",
  IndexProps,
  {
    /** ARN of the index, e.g. `arn:aws:resource-explorer-2:us-west-2:123456789012:index/uuid`. */
    indexArn: string;
    /** The current index type (`LOCAL` or `AGGREGATOR`). */
    indexType: string;
    /** Lifecycle state of the index (`CREATING`, `ACTIVE`, `UPDATING`, ...). */
    indexState: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Resource Explorer index — the region singleton that turns on
 * resource indexing so resources in the region can be searched.
 *
 * Only one index can exist per region, so this is a capture-and-restore
 * singleton: adopting an index that Alchemy did not create requires
 * `--adopt` (ownership is tracked through the index's tags), and destroy
 * turns Resource Explorer off for the region (deleting every view in it).
 *
 * The first index created in an account also creates the
 * `AWSServiceRoleForResourceExplorer` service-linked role.
 *
 * ### Turning on Resource Explorer
 * **Example:** Local index
 * ```typescript
 * const index = yield* AWS.ResourceExplorer.Index("Index", {});
 * ```
 *
 * **Example:** Aggregator index for cross-region search
 * ```typescript
 * const index = yield* AWS.ResourceExplorer.Index("Index", {
 *   type: "AGGREGATOR",
 * });
 * ```
 *
 * ### Searching
 * Search always goes through a view — see `AWS.ResourceExplorer.View` and
 * the `AWS.ResourceExplorer.Search` binding.
 */
const IndexResource = Resource<Index>("AWS.ResourceExplorer.Index");

export { IndexResource as Index };

/**
 * `GetIndex` keeps returning the most recent index long after it is
 * deleted (`State: "DELETED"` has been observed months later), so both
 * the typed `ResourceNotFoundException` and a `DELETING`/`DELETED` state
 * mean "no index in this region".
 */
const observeIndex = re2.getIndex({}).pipe(
  Effect.map((r): re2.GetIndexOutput | undefined =>
    r.State === "DELETED" || r.State === "DELETING" ? undefined : r,
  ),
  Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);

/**
 * Repeat a poll until the predicate holds (bounded — a fresh index becomes
 * `ACTIVE` in ~15s; type changes usually settle in seconds when no other
 * regions replicate). Expressed as an explicitly-typed helper: inlining
 * `Effect.repeat`/`Effect.retry` in a provider lifecycle op leaves a
 * conditional type unresolved in the provider's inferred layer type, which
 * declaration emit widens to an `unknown` R — poisoning `AWS.providers()`.
 */
const repeatUntil = <A, E, R>(
  self: Effect.Effect<A, E, R>,
  until: (a: A) => boolean,
): Effect.Effect<A, E, R> =>
  Effect.repeat(self, {
    schedule: Schedule.spaced("2 seconds"),
    until,
    times: 30,
  });

/**
 * Retry `ConflictException` on a bounded schedule — creating an index
 * while the previous one is still `DELETING` (or racing a peer create)
 * conflicts transiently.
 */
const retryWhileConflict = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
  });

const toTagRecord = (
  tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> => {
  const out: Record<string, string> = {};
  for (const [key, value] of Object.entries(tags ?? {})) {
    if (value !== undefined) out[key] = value;
  }
  return out;
};

const toAttrs = (live: re2.GetIndexOutput): Index["Attributes"] => ({
  indexArn: live.Arn!,
  indexType: live.Type ?? "LOCAL",
  indexState: live.State ?? "ACTIVE",
});

export const IndexProvider = () =>
  Provider.effect(
    IndexResource,
    Effect.gen(function* () {
      return IndexResource.Provider.of({
        stables: ["indexArn"],

        read: Effect.fn(function* ({ id }) {
          const live = yield* observeIndex;
          if (!live) return undefined;
          const attrs = toAttrs(live);
          const tags = toTagRecord(live.Tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        // Region singleton — report the single index, if any.
        list: () =>
          Effect.gen(function* () {
            const live = yield* observeIndex;
            return live ? [toAttrs(live)] : [];
          }),

        reconcile: Effect.fn(function* ({ id, news, session }) {
          const desiredType: IndexType = news.type ?? "LOCAL";
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative. A DELETED index is
          //    treated as absent (see observeIndex).
          let live = yield* observeIndex;

          // 2. ENSURE — create when missing. ConflictException covers both
          //    a race with a peer create and a previous index still
          //    DELETING; retry bounded, then fall through to observation.
          if (live === undefined) {
            yield* retryWhileConflict(re2.createIndex({ Tags: desiredTags })).pipe(
              Effect.catchTag("ConflictException", () => Effect.void),
              Effect.asVoid,
            );
            live = yield* repeatUntil(re2.getIndex({}), (r) => r.State === "ACTIVE");
          }

          // 3. SYNC TYPE — LOCAL <-> AGGREGATOR is an in-place update.
          //    Wait (bounded) for the asynchronous replication tasks to
          //    settle back to ACTIVE; if they take longer, return the
          //    observed UPDATING state and converge on the next deploy.
          if ((live.Type ?? "LOCAL") !== desiredType) {
            yield* retryWhileConflict(re2.updateIndexType({ Arn: live.Arn!, Type: desiredType }));
            live = yield* repeatUntil(re2.getIndex({}), (r) => r.State === "ACTIVE");
          }

          // 4. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //    converges (createIndex Tags only apply on first create).
          const observedTags = toTagRecord(live.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* re2.tagResource({
              resourceArn: live.Arn!,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* re2.untagResource({
              resourceArn: live.Arn!,
              tagKeys: removed,
            });
          }

          yield* session.note(live.Arn!);
          return {
            indexArn: live.Arn!,
            indexType: live.Type ?? desiredType,
            indexState: live.State ?? "ACTIVE",
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // Idempotent: the index may already be gone (or replaced by a
          // foreign one with a different ARN — never delete that one).
          yield* re2.deleteIndex({ Arn: output.indexArn }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            Effect.asVoid,
          );
        }),
      });
    }),
  );