sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OpenSearchServerless/ CollectionGroup.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 { recordToTagList, retryWhileConflict, tagsToRecord } from "./internal.ts";

export interface CollectionGroupCapacityLimits {
  /**
   * Maximum indexing capacity, in OpenSearch Compute Units (OCUs), shared by
   * the group's collections.
   */
  maxIndexingCapacityInOCU?: number;
  /**
   * Maximum search capacity, in OCUs, shared by the group's collections.
   */
  maxSearchCapacityInOCU?: number;
  /**
   * Minimum indexing capacity, in OCUs, reserved for the group.
   */
  minIndexingCapacityInOCU?: number;
  /**
   * Minimum search capacity, in OCUs, reserved for the group.
   */
  minSearchCapacityInOCU?: number;
}

export interface CollectionGroupProps {
  /**
   * Name of the collection group (3-32 characters, lowercase; must start with
   * a lowercase letter). Changing the name replaces the group.
   * @default a generated physical name
   */
  groupName?: string;
  /**
   * Whether collections in the group deploy redundant standby replicas. Set
   * at creation time; changing it replaces the group.
   * @default "ENABLED"
   */
  standbyReplicas?: "ENABLED" | "DISABLED";
  /**
   * A human-readable description of the collection group.
   */
  description?: string;
  /**
   * OCU capacity limits shared by the collections in the group.
   */
  capacityLimits?: CollectionGroupCapacityLimits;
  /**
   * Tags to apply to the collection group. Merged with the internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface CollectionGroup extends Resource<
  "AWS.OpenSearchServerless.CollectionGroup",
  CollectionGroupProps,
  {
    /**
     * Unique identifier of the collection group.
     */
    collectionGroupId: string;
    /**
     * Name of the collection group.
     */
    collectionGroupName: string;
    /**
     * ARN of the collection group.
     */
    collectionGroupArn: string;
    /**
     * Whether standby replicas are enabled for the group's collections.
     */
    standbyReplicas?: string;
    /**
     * Number of collections currently in the group.
     */
    numberOfCollections?: number;
    /**
     * The capacity generation of the group.
     */
    generation?: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon OpenSearch Serverless collection group. Collection groups manage
 * OpenSearch Compute Units (OCUs) at a group level — multiple collections
 * share the group's capacity limits instead of each collection scaling
 * independently.
 *
 * ### Creating Collection Groups
 * **Example:** Capacity-Bounded Collection Group
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const group = yield* AWS.OpenSearchServerless.CollectionGroup("Group", {
 *   groupName: "analytics",
 *   standbyReplicas: "DISABLED",
 *   capacityLimits: {
 *     maxIndexingCapacityInOCU: 4,
 *     maxSearchCapacityInOCU: 4,
 *   },
 * });
 * ```
 *
 * @resource
 */
export const CollectionGroup = Resource<CollectionGroup>(
  "AWS.OpenSearchServerless.CollectionGroup",
);

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

      const toAttributes = (detail: aoss.CollectionGroupDetail) => ({
        collectionGroupId: detail.id!,
        collectionGroupName: detail.name!,
        collectionGroupArn: detail.arn!,
        standbyReplicas: detail.standbyReplicas,
        numberOfCollections: detail.numberOfCollections,
        generation: detail.generation,
      });

      // batchGetCollectionGroup reports a missing group in
      // collectionGroupErrorDetails instead of failing.
      const observeByName = Effect.fn(function* (name: string) {
        const response = yield* aoss.batchGetCollectionGroup({
          names: [name],
        });
        return response.collectionGroupDetails?.[0];
      });

      const capacityDrift = (
        desired: CollectionGroupCapacityLimits | undefined,
        observed: aoss.CollectionGroupCapacityLimits | undefined,
      ): boolean =>
        desired !== undefined &&
        (desired.maxIndexingCapacityInOCU !== observed?.maxIndexingCapacityInOCU ||
          desired.maxSearchCapacityInOCU !== observed?.maxSearchCapacityInOCU ||
          desired.minIndexingCapacityInOCU !== observed?.minIndexingCapacityInOCU ||
          desired.minSearchCapacityInOCU !== observed?.minSearchCapacityInOCU);

      // batchGetCollectionGroup does not return the group's tags — read them
      // via listTagsForResource (the authoritative tag store).
      const observeTags = Effect.fn(function* (arn: string) {
        return yield* aoss
          .listTagsForResource({ resourceArn: arn })
          .pipe(Effect.map((r) => tagsToRecord(r.tags)));
      });

      const syncTags = Effect.fn(function* (
        arn: string,
        observed: Record<string, string>,
        desired: Record<string, string>,
      ) {
        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 CollectionGroup.Provider.of({
        stables: ["collectionGroupId", "collectionGroupName", "collectionGroupArn"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* aoss.listCollectionGroups.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.collectionGroupSummaries ?? [])
              .filter((s) => s.id !== undefined && s.name !== undefined && s.arn !== undefined)
              .map((s) => ({
                collectionGroupId: s.id!,
                collectionGroupName: s.name!,
                collectionGroupArn: s.arn!,
                generation: s.generation,
              }));
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.collectionGroupName ?? (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* observeTags(detail.arn).pipe(Effect.orElseSucceed(() => ({})));
          return (yield* hasAlchemyTags(
            id,
            Object.entries(tags).map(([Key, Value]) => ({ Key, 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.standbyReplicas !== undefined &&
            news.standbyReplicas !== undefined &&
            olds.standbyReplicas !== news.standbyReplicas
          ) {
            return { action: "replace" } as const;
          }
          // description/capacityLimits/tags fall through to update
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.collectionGroupName ?? (yield* createName(id, news));
          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; tolerate a concurrent create race
          if (detail === undefined) {
            const created = yield* aoss
              .createCollectionGroup({
                name,
                standbyReplicas: news.standbyReplicas ?? "ENABLED",
                description: news.description,
                capacityLimits: news.capacityLimits,
                tags: recordToTagList(desiredTags),
              })
              .pipe(
                Effect.map((r) => r.createCollectionGroupDetail),
                Effect.catchTag("ConflictException", () => Effect.undefined),
              );
            detail = created !== undefined ? { ...created } : yield* observeByName(name);
          } else {
            // 3. SYNC — description/capacityLimits when observed drifts
            const descriptionDrift =
              news.description !== undefined && news.description !== detail.description;
            const limitsDrift = capacityDrift(news.capacityLimits, detail.capacityLimits);
            if (descriptionDrift || limitsDrift) {
              yield* aoss.updateCollectionGroup({
                id: detail.id!,
                description: descriptionDrift ? news.description : undefined,
                capacityLimits: limitsDrift ? news.capacityLimits : undefined,
              });
            }
          }

          if (detail?.id === undefined || detail.arn === undefined) {
            return yield* aoss.ResourceNotFoundException.make({
              message: `collection group ${name} not visible after reconcile`,
            });
          }

          // 3b. SYNC TAGS — diff against observed cloud tags (read via
          // listTagsForResource on every path: adoption may bring foreign
          // tags, and a create race may have dropped ours).
          yield* syncTags(detail.arn, yield* observeTags(detail.arn), desiredTags);

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

        delete: Effect.fn(function* ({ output }) {
          // A group with collections still in it (or tearing down) surfaces
          // ConflictException — retry through the teardown window.
          yield* retryWhileConflict(
            aoss.deleteCollectionGroup({ id: output.collectionGroupId }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );