sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OpenSearchServerless/ Collection.ts

import * as aoss from "@distilled.cloud/aws/opensearchserverless";
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 Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  awaitCollectionActive,
  recordToTagList,
  retryWhileConflict,
  tagsToRecord,
} from "./internal.ts";

/**
 * The collection type, which determines the OpenSearch features available:
 * - `SEARCH` — full-text search and analytics.
 * - `TIMESERIES` — log analytics over time-ordered data.
 * - `VECTORSEARCH` — vector (k-NN) similarity search — the type required to
 *   back an Amazon Bedrock Knowledge Base.
 */
export type CollectionType = "SEARCH" | "TIMESERIES" | "VECTORSEARCH";

export interface CollectionProps {
  /**
   * Name of the collection (3-32 characters, lowercase; must start with a
   * lowercase letter). Must be matched by an encryption
   * {@link SecurityPolicy | security policy} before it can be created. Changing
   * the name replaces the collection.
   * @default a generated physical name
   */
  collectionName?: string;
  /**
   * The collection type. Changing the type replaces the collection.
   * @default "SEARCH"
   */
  type?: CollectionType;
  /**
   * A human-readable description of the collection.
   */
  description?: string;
  /**
   * Whether to deploy redundant standby replicas (`ENABLED` doubles the OCU
   * floor but provides higher availability). Set at creation time.
   * @default "ENABLED"
   */
  standbyReplicas?: "ENABLED" | "DISABLED";
  /**
   * Whether deletion protection is enabled. When `ENABLED`, the collection
   * cannot be deleted until protection is turned off.
   * @default "DISABLED"
   */
  deletionProtection?: "ENABLED" | "DISABLED";
  /**
   * Tags to apply to the collection. Merged with the internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Collection extends Resource<
  "AWS.OpenSearchServerless.Collection",
  CollectionProps,
  {
    /**
     * Unique identifier of the collection.
     */
    collectionId: string;
    /**
     * Name of the collection.
     */
    collectionName: string;
    /**
     * ARN of the collection.
     */
    collectionArn: string;
    /**
     * Collection type (`SEARCH`, `TIMESERIES`, or `VECTORSEARCH`).
     */
    type?: string;
    /**
     * Collection status (e.g. `ACTIVE`, `CREATING`, `DELETING`).
     */
    status?: string;
    /**
     * ARN of the KMS key encrypting the collection.
     */
    kmsKeyArn?: string;
    /**
     * OpenSearch endpoint for data-plane requests.
     */
    collectionEndpoint?: string;
    /**
     * OpenSearch Dashboards endpoint for the collection.
     */
    dashboardEndpoint?: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon OpenSearch Serverless collection — a group of OpenSearch indexes
 * that scales OpenSearch Compute Units (OCUs) automatically. A collection of
 * type `VECTORSEARCH` is the vector store required to back an Amazon Bedrock
 * Knowledge Base.
 *
 * A collection requires a matching encryption {@link SecurityPolicy} to exist
 * before creation, plus a network security policy and a data
 * {@link AccessPolicy} to be reachable and usable. Creation is asynchronous —
 * the provider polls (bounded, ~5 minutes) until the collection reaches
 * `ACTIVE`.
 *
 * ### Creating Collections
 * **Example:** Vector Search Collection for a Bedrock Knowledge Base
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const encryption = yield* AWS.OpenSearchServerless.SecurityPolicy("Enc", {
 *   policyName: "kb-enc",
 *   type: "encryption",
 *   policy: {
 *     Rules: [{ ResourceType: "collection", Resource: ["collection/kb"] }],
 *     AWSOwnedKey: true,
 *   },
 * });
 * const network = yield* AWS.OpenSearchServerless.SecurityPolicy("Net", {
 *   policyName: "kb-net",
 *   type: "network",
 *   policy: [
 *     {
 *       Rules: [
 *         { ResourceType: "collection", Resource: ["collection/kb"] },
 *         { ResourceType: "dashboard", Resource: ["collection/kb"] },
 *       ],
 *       AllowFromPublic: true,
 *     },
 *   ],
 * });
 * const collection = yield* AWS.OpenSearchServerless.Collection("KB", {
 *   collectionName: "kb",
 *   type: "VECTORSEARCH",
 * });
 * // collection.collectionEndpoint is the aoss data-plane endpoint
 * ```
 *
 * ### Search Collections
 * **Example:** Simple Search Collection
 * ```typescript
 * const collection = yield* AWS.OpenSearchServerless.Collection("Search", {
 *   collectionName: "logs",
 *   type: "SEARCH",
 *   description: "application logs",
 * });
 * ```
 *
 * @resource
 */
export const Collection = Resource<Collection>("AWS.OpenSearchServerless.Collection");

export const CollectionProvider = () =>
  Provider.effect(
    Collection,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { collectionName?: string | undefined },
      ) {
        return (
          props.collectionName ??
          (yield* createPhysicalName({ id, maxLength: 32, lowercase: true }))
        );
      });

      const toAttributes = (detail: aoss.CollectionDetail) => ({
        collectionId: detail.id!,
        collectionName: detail.name!,
        collectionArn: detail.arn!,
        type: detail.type,
        status: detail.status,
        kmsKeyArn: detail.kmsKeyArn,
        collectionEndpoint: detail.collectionEndpoint,
        dashboardEndpoint: detail.dashboardEndpoint,
      });

      const observeByName = Effect.fn(function* (name: string) {
        const response = yield* aoss.batchGetCollection({ names: [name] });
        return response.collectionDetails?.[0];
      });

      const syncTags = Effect.fn(function* (arn: string, desired: Record<string, string>) {
        const observed = yield* aoss
          .listTagsForResource({ resourceArn: arn })
          .pipe(Effect.map((r) => tagsToRecord(r.tags)));
        const { upsert, removed } = diffTags(observed, desired);
        if (upsert.length > 0) {
          yield* aoss.tagResource({
            resourceArn: arn,
            tags: recordToTagList(Object.fromEntries(upsert.map((t) => [t.Key, t.Value]))),
          });
        }
        if (removed.length > 0) {
          yield* aoss.untagResource({ resourceArn: arn, tagKeys: removed });
        }
      });

      return Collection.Provider.of({
        stables: ["collectionId", "collectionName", "collectionArn"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* aoss.listCollections.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.collectionSummaries ?? [])
              .filter((s) => s.id !== undefined && s.name !== undefined && s.arn !== undefined)
              .map((s) => ({
                collectionId: s.id!,
                collectionName: s.name!,
                collectionArn: s.arn!,
                status: s.status,
                kmsKeyArn: s.kmsKeyArn,
              }));
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.collectionName ?? (yield* createName(id, olds ?? {}));
          const detail = yield* observeByName(name);
          if (detail?.id === undefined || detail.arn === undefined) {
            return undefined;
          }
          const attrs = toAttributes(detail);
          const tags = yield* aoss.listTagsForResource({ resourceArn: detail.arn }).pipe(
            Effect.map((r) => r.tags),
            Effect.orElseSucceed(() => undefined),
          );
          return (yield* hasAlchemyTags(
            id,
            (tags ?? []).map((t) => ({ Key: t.key, Value: t.value })),
          ))
            ? 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;
          }
          if ((olds.type ?? "SEARCH") !== (news.type ?? "SEARCH")) {
            return { action: "replace" } as const;
          }
          // description/deletionProtection/tags fall through to update
        }),

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

          // 1. OBSERVE — cloud state is authoritative
          let detail = yield* observeByName(name);

          // 2. ENSURE — create if missing; wait for ACTIVE (async provisioning)
          if (detail === undefined) {
            const created = yield* aoss
              .createCollection({
                name,
                type,
                description: news.description,
                standbyReplicas: news.standbyReplicas,
                deletionProtection: news.deletionProtection,
                tags: recordToTagList(desiredTags),
              })
              .pipe(
                Effect.map((r) => r.createCollectionDetail),
                // a concurrent reconciler already created it — fall through
                Effect.catchTag("ConflictException", () => Effect.undefined),
              );
            const collectionId = created?.id ?? (yield* observeByName(name))?.id;
            if (collectionId === undefined) {
              return yield* aoss.ResourceNotFoundException.make({
                message: `collection ${name} not visible after create`,
              });
            }
            yield* session.note(`creating collection ${name} (async)...`);
            detail = yield* awaitCollectionActive(collectionId);
          } else if (detail.status !== "ACTIVE") {
            detail = yield* awaitCollectionActive(detail.id!);
          }

          // 3. SYNC — description (deletionProtection updates alongside)
          const descriptionDrift =
            news.description !== undefined && news.description !== detail.description;
          const protectionDrift =
            news.deletionProtection !== undefined &&
            news.deletionProtection !== detail.deletionProtection;
          if (descriptionDrift || protectionDrift) {
            yield* aoss.updateCollection({
              id: detail.id!,
              description: descriptionDrift ? news.description : undefined,
              deletionProtection: protectionDrift ? news.deletionProtection : undefined,
            });
          }

          // 3b. SYNC TAGS — diff against observed cloud tags
          yield* syncTags(detail.arn!, desiredTags);

          yield* session.note(detail.id!);
          return toAttributes(detail);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileConflict(aoss.deleteCollection({ id: output.collectionId })).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );