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

import * as re2 from "@distilled.cloud/aws/resource-explorer-2";
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 } 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";

export interface ViewProps {
  /**
   * Name of the view. Can include letters, digits, and the dash character
   * (up to 64 characters), and must be unique within the region.
   * @default ${app}-${stage}-${id}
   */
  viewName?: string;

  /**
   * A Resource Explorer search filter that scopes every query made through
   * this view, e.g. `"service:s3"` or `"tag:stage=prod"`. Results of a
   * search are the intersection of the query and this filter.
   * Omit to leave the view unfiltered.
   */
  filterString?: string;

  /**
   * Additional resource properties to include in search results returned
   * by this view. `"tags"` is the only supported property today.
   */
  includedProperties?: string[];

  /**
   * The root ARN the view is scoped to. Defaults to the account
   * (`arn:aws:iam::<account>:root`). Changing the scope requires
   * replacement — the API offers no scope update.
   */
  scope?: string;

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

/** @resource */
export interface View extends Resource<
  "AWS.ResourceExplorer.View",
  ViewProps,
  {
    /** ARN of the view, e.g. `arn:aws:resource-explorer-2:us-west-2:123456789012:view/my-view/uuid`. */
    viewArn: string;
    /** Name of the view. */
    viewName: string;
    /** The root ARN the view is scoped to. */
    scope: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AWS Resource Explorer view — a saved search lens with an optional
 * filter and a set of included properties that `Search` queries run
 * through.
 *
 * Views require an active `AWS.ResourceExplorer.Index` in the region.
 * When an index and a view deploy together, the view provider retries
 * through the window where the index is still provisioning.
 *
 * ### Creating Views
 * **Example:** Unfiltered view over the whole account
 * ```typescript
 * const index = yield* AWS.ResourceExplorer.Index("Index", {});
 * const view = yield* AWS.ResourceExplorer.View("AllResources", {});
 * ```
 *
 * **Example:** Filtered view with tags included in results
 * ```typescript
 * const view = yield* AWS.ResourceExplorer.View("S3Only", {
 *   filterString: "service:s3",
 *   includedProperties: ["tags"],
 * });
 * ```
 *
 * ### Searching
 * **Example:** Search from a Lambda function
 * ```typescript
 * // init
 * const search = yield* AWS.ResourceExplorer.Search(view);
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     // runtime
 *     const results = yield* search({ QueryString: "service:s3" });
 *     return HttpServerResponse.json({ count: results.Count });
 *   }),
 * };
 * ```
 */
const ViewResource = Resource<View>("AWS.ResourceExplorer.View");

export { ViewResource as View };

/**
 * Raised when a view can neither be created (a peer holds the name) nor
 * observed afterwards — i.e. reconciliation raced a concurrent delete.
 */
export class ViewUnobservable extends Data.TaggedError("ResourceExplorerViewUnobservable")<{
  message: string;
}> {}

/**
 * Resource Explorer answers `GetView`/`DeleteView` for a nonexistent or
 * deleted view with the typed `UnauthorizedException` (HTTP 401, empty
 * message) rather than `ResourceNotFoundException` — both mean "the view
 * is not there for you".
 */
const getViewSafe = Effect.fn(function* (viewArn: string) {
  return yield* re2.getView({ ViewArn: viewArn }).pipe(
    Effect.map((r): re2.GetViewOutput | undefined => r),
    Effect.catchTag(["UnauthorizedException", "ResourceNotFoundException"], () => Effect.undefined),
  );
});

/**
 * Find a view's ARN by its name. View ARNs embed the name as the second
 * `/`-segment: `arn:...:view/{name}/{uuid}`.
 */
const findViewArnByName = Effect.fn(function* (name: string) {
  const arns = yield* re2.listViews.pages({}).pipe(
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Views ?? [])),
  );
  return arns.find((arn) => arn.split("/")[1] === name);
});

/**
 * Creating a view while the region's index is still provisioning (or
 * missing) is rejected with the typed `UnauthorizedException`. When an
 * `Index` and a `View` deploy concurrently this is a transient ordering
 * race — retry through it on a bounded schedule (an index becomes ACTIVE
 * in ~15s). Explicitly-typed helper: an inline `Effect.retry` widens the
 * provider layer's declaration-emitted R to `unknown`.
 */
const retryWhileIndexProvisioning = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "UnauthorizedException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
  });

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 includedPropertyNames = (properties: re2.IncludedProperty[] | undefined): string[] =>
  (properties ?? []).map((p) => p.Name);

const sameStringSet = (a: string[], b: string[]) =>
  a.length === b.length && [...a].sort().join(",") === [...b].sort().join(",");

export const ViewProvider = () =>
  Provider.effect(
    ViewResource,
    Effect.gen(function* () {
      const createViewName = Effect.fn(function* (
        id: string,
        props: { viewName?: string | undefined },
      ) {
        return props.viewName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const toAttrs = (view: re2.View, name: string): View["Attributes"] => ({
        viewArn: view.ViewArn!,
        viewName: name,
        scope: view.Scope,
      });

      return ViewResource.Provider.of({
        stables: ["viewArn", "viewName"],

        list: () =>
          Effect.gen(function* () {
            const arns = yield* re2.listViews.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Views ?? [])),
            );
            // A view can vanish between enumeration and hydration — drop it.
            const items = yield* Effect.forEach(
              arns,
              (arn) =>
                getViewSafe(arn).pipe(
                  Effect.map((found) =>
                    found?.View?.ViewArn
                      ? toAttrs(found.View, found.View.ViewName ?? arn.split("/")[1]!)
                      : undefined,
                  ),
                ),
              { concurrency: 10 },
            );
            return items.filter((item): item is View["Attributes"] => item !== undefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          // Prefer the cached ARN; fall back to a by-name scan (state may
          // have been lost after a persistence failure).
          let arn = output?.viewArn;
          if (arn === undefined) {
            const name = yield* createViewName(id, olds ?? {});
            arn = yield* findViewArnByName(name);
          }
          if (arn === undefined) return undefined;
          const found = yield* getViewSafe(arn);
          if (!found?.View?.ViewArn) return undefined;
          const attrs = toAttrs(found.View, found.View.ViewName ?? arn.split("/")[1]!);
          const tags = toTagRecord(found.Tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createViewName(id, olds ?? {});
          const newName = yield* createViewName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // Scope has no update API — a change requires replacement.
          if ((olds ?? {}).scope !== news.scope) {
            return { action: "replace" } as const;
          }
          // Fall through: default update path handles filters/properties/tags.
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.viewName ?? (yield* createViewName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredProperties = news.includedProperties ?? [];
          const desiredFilter = news.filterString;

          // 1. OBSERVE — by cached ARN first, then by name (covers
          //    adoption and lost state).
          let found =
            output?.viewArn !== undefined ? yield* getViewSafe(output.viewArn) : undefined;
          if (!found?.View) {
            const arn = yield* findViewArnByName(name);
            found = arn !== undefined ? yield* getViewSafe(arn) : undefined;
          }

          // 2. ENSURE — create when missing. Retries through the window
          //    where the region's index is still provisioning, and
          //    tolerates a duplicate-name Conflict as a race (observe the
          //    winner and converge below).
          if (!found?.View) {
            found = yield* retryWhileIndexProvisioning(
              re2.createView({
                ViewName: name,
                Filters: desiredFilter !== undefined ? { FilterString: desiredFilter } : undefined,
                IncludedProperties: desiredProperties.map((Name) => ({
                  Name,
                })),
                Scope: news.scope,
                Tags: desiredTags,
              }),
            ).pipe(
              Effect.map(
                (r): re2.GetViewOutput | undefined => r.View && { View: r.View, Tags: desiredTags },
              ),
              Effect.catchTag("ConflictException", () =>
                Effect.gen(function* () {
                  const arn = yield* findViewArnByName(name);
                  return arn !== undefined ? yield* getViewSafe(arn) : undefined;
                }),
              ),
            );
          }
          const view = found?.View;
          if (found === undefined || view?.ViewArn === undefined) {
            // Unreachable in practice: create either succeeded or the
            // conflicting peer exists; observation just raced a delete.
            return yield* new ViewUnobservable({
              message: `ResourceExplorer view ${name} could not be created or observed`,
            });
          }

          // 3. SYNC — UpdateView REPLACES both Filters and
          //    IncludedProperties (omitted fields are cleared), so always
          //    send the full desired shape when either differs.
          const observedFilter = view.Filters?.FilterString;
          const observedProperties = includedPropertyNames(view.IncludedProperties);
          if (
            (observedFilter ?? undefined) !== desiredFilter ||
            !sameStringSet(observedProperties, desiredProperties)
          ) {
            yield* re2.updateView({
              ViewArn: view.ViewArn,
              Filters: desiredFilter !== undefined ? { FilterString: desiredFilter } : undefined,
              IncludedProperties: desiredProperties.map((Name) => ({ Name })),
            });
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags.
          const observedTags = toTagRecord(found.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* re2.tagResource({
              resourceArn: view.ViewArn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* re2.untagResource({
              resourceArn: view.ViewArn,
              tagKeys: removed,
            });
          }

          yield* session.note(view.ViewArn);
          return toAttrs(view, view.ViewName ?? name);
        }),

        delete: Effect.fn(function* ({ output }) {
          // Idempotent: a missing/deleted view answers with the typed
          // UnauthorizedException (Resource Explorer's "not found" for
          // views) or ResourceNotFoundException.
          yield* re2.deleteView({ ViewArn: output.viewArn }).pipe(
            Effect.catchTag(
              ["UnauthorizedException", "ResourceNotFoundException"],
              () => Effect.undefined,
            ),
            Effect.asVoid,
          );
        }),
      });
    }),
  );