sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ DiscoveryEngine/ CollectionsEngine.ts

import * as discoveryengine from "@distilled.cloud/gcp/discoveryengine_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  collectionParent,
  dataStoreIdOf,
  DEFAULT_COLLECTION,
  normalizeCollection,
  normalizeLocation,
  parseResourceName,
  sameJson,
  sameStringList,
  toResourceId,
} from "./internal.ts";
import { waitForOperation } from "./operations.ts";

export type CollectionsEngineSearchEngineConfig = {
  /**
   * Search feature tier. Defaults to `SEARCH_TIER_STANDARD`.
   */
  searchTier?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigSearchTierEnum;
  /**
   * Search add-ons enabled on this engine.
   */
  searchAddOns?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigSearchAddOnsItemEnumList;
  /**
   * Required subscription tier. Immutable after create.
   */
  requiredSubscriptionTier?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigRequiredSubscriptionTierEnum;
};

export type CollectionsEngineCommonConfig = {
  /**
   * Company or entity associated with the engine. Setting this may help
   * LLM features.
   */
  companyName?: string;
};

export type CollectionsEngineProps = {
  /**
   * Engine id (the `{engine}` segment of the resource name). If omitted,
   * a unique RFC-1034 id is generated. Immutable — changing it replaces
   * the engine.
   */
  engineId?: string;
  /**
   * Location (`global`, `us`, `eu`, …). Immutable — changing it replaces
   * the engine.
   * @default "global"
   */
  location?: string;
  /**
   * Collection id. Immutable — changing it replaces the engine.
   * @default "default_collection"
   */
  collectionId?: string;
  /**
   * User-facing display name.
   * @default the engine id
   */
  displayName?: string;
  /**
   * Solution type. Immutable — changing it replaces the engine.
   * @default "SOLUTION_TYPE_SEARCH"
   */
  solutionType?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSolutionTypeEnum;
  /**
   * Industry vertical. Must match the linked data store. Immutable.
   * @default "GENERIC"
   */
  industryVertical?: discoveryengine.GoogleCloudDiscoveryengineV1EngineIndustryVerticalEnum;
  /**
   * Data store ids to attach. For search and recommendation engines at
   * most one id is allowed. Values may be ids or full resource names.
   */
  dataStoreIds?: string[];
  /**
   * Search-engine configuration. Applied when `solutionType` is
   * `SOLUTION_TYPE_SEARCH`.
   */
  searchEngineConfig?: CollectionsEngineSearchEngineConfig;
  /**
   * Common metadata (company name).
   */
  commonConfig?: CollectionsEngineCommonConfig;
  /**
   * Chat-engine configuration. One-time consumed at create.
   */
  chatEngineConfig?: discoveryengine.GoogleCloudDiscoveryengineV1EngineChatEngineConfig;
  /**
   * Media recommendation configuration.
   */
  mediaRecommendationEngineConfig?: discoveryengine.GoogleCloudDiscoveryengineV1EngineMediaRecommendationEngineConfig;
  /**
   * Disable analytics for searches on this engine.
   * @default false
   */
  disableAnalytics?: boolean;
  /**
   * Application type. Immutable.
   */
  appType?: discoveryengine.GoogleCloudDiscoveryengineV1EngineAppTypeEnum;
};

export type CollectionsEngine = Resource<
  "GCP.DiscoveryEngine.CollectionsEngine",
  CollectionsEngineProps,
  {
    /** Full resource name. */
    name: string;
    /** Engine id (last path segment). */
    engineId: string;
    /** Project id. */
    project: string;
    /** Location id. */
    location: string;
    /** Collection id. */
    collectionId: string;
    /** Display name. */
    displayName: string | undefined;
    /** Solution type. */
    solutionType: string | undefined;
    /** Industry vertical. */
    industryVertical: string | undefined;
    /** Attached data store ids. */
    dataStoreIds: string[];
    /** Whether analytics are disabled. */
    disableAnalytics: boolean;
    /** Company name from common config. */
    companyName: string | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Discovery Engine Engine under a collection — serves Search,
 * Recommendation, or Chat from one or more DataStores.
 *
 * Without labels, ownership rests on the deterministic id: `read` reports a
 * resource it finds without prior state as unowned (adopt it with `--adopt`).
 * Parent is
 * `projects/{project}/locations/{location}/collections/{collection}`. Id,
 * location, collection, solution type, and vertical are immutable; display
 * name, analytics flag, and common config update in place.
 *
 * ### Creating an Engine
 * **Example:** Search engine over a data store
 * ```typescript
 * const store = yield* GCP.DiscoveryEngine.DataStore("Docs", {});
 * const engine = yield* GCP.DiscoveryEngine.CollectionsEngine("Search", {
 *   dataStoreIds: [store.dataStoreId],
 *   displayName: "docs search",
 * });
 * ```
 *
 * ### Updating an Engine
 * **Example:** Rename
 * ```typescript
 * // Same logical id as before; only the changed props differ.
 * const engine = yield* GCP.DiscoveryEngine.CollectionsEngine("Search", {
 *   dataStoreIds: [store.dataStoreId],
 *   displayName: "docs search prod",
 * });
 * ```
 *
 * @resource
 * @category DiscoveryEngine
 */
export const CollectionsEngine = Resource<CollectionsEngine>(
  "GCP.DiscoveryEngine.CollectionsEngine",
);

export class CollectionsEngineNotResolved extends Data.TaggedError(
  "GCP.DiscoveryEngine.CollectionsEngineNotResolved",
)<{
  resourceName: string;
}> {}

export class CollectionsEngineStillExists extends Data.TaggedError(
  "GCP.DiscoveryEngine.CollectionsEngineStillExists",
)<{
  resourceName: string;
}> {}

const resourceName = (project: string, location: string, collectionId: string, engineId: string) =>
  `${collectionParent(project, location, collectionId)}/engines/${engineId}`;

const solutionOf = (
  value: discoveryengine.GoogleCloudDiscoveryengineV1EngineSolutionTypeEnum | undefined,
) => value ?? "SOLUTION_TYPE_SEARCH";

const verticalOf = (
  value: discoveryengine.GoogleCloudDiscoveryengineV1EngineIndustryVerticalEnum | undefined,
) => value ?? "GENERIC";

const idsOf = (values: readonly string[] | undefined) => (values ?? []).map(dataStoreIdOf);

const getByName = (name: string) =>
  discoveryengine
    .getProjectsLocationsCollectionsEngines({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const toAttrs = (engine: discoveryengine.GoogleCloudDiscoveryengineV1Engine, project: string) => {
  const name = engine.name ?? "";
  const parsed = parseResourceName(name, "engines");
  return {
    name,
    engineId: parsed.id,
    project: parsed.project || project,
    location: parsed.location,
    collectionId: parsed.collectionId || DEFAULT_COLLECTION,
    displayName: engine.displayName,
    solutionType: engine.solutionType,
    industryVertical: engine.industryVertical,
    dataStoreIds: [...(engine.dataStoreIds ?? [])],
    disableAnalytics: engine.disableAnalytics === true,
    companyName: engine.commonConfig?.companyName,
    createTime: engine.createTime,
    updateTime: engine.updateTime,
  };
};

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((engine) =>
      engine
        ? Effect.succeed(engine)
        : Effect.fail(new CollectionsEngineNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.DiscoveryEngine.CollectionsEngineNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((engine) =>
      engine === undefined
        ? Effect.void
        : Effect.fail(new CollectionsEngineStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.DiscoveryEngine.CollectionsEngineStillExists",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

export const CollectionsEngineProvider = () =>
  Provider.succeed(CollectionsEngine, {
    stables: [
      "name",
      "engineId",
      "project",
      "location",
      "collectionId",
      "solutionType",
      "industryVertical",
      "createTime",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.engineId ?? output?.engineId;
      const nextId = news.engineId ?? previousId;
      const previousLocation = normalizeLocation(olds?.location ?? output?.location);
      const nextLocation = normalizeLocation(news.location ?? olds?.location ?? output?.location);
      const previousCollection = normalizeCollection(olds?.collectionId ?? output?.collectionId);
      const nextCollection = normalizeCollection(
        news.collectionId ?? olds?.collectionId ?? output?.collectionId,
      );
      const previousSolution = solutionOf(
        olds?.solutionType ?? (output?.solutionType as CollectionsEngineProps["solutionType"]),
      );
      const nextSolution = solutionOf(
        news.solutionType ?? (output?.solutionType as CollectionsEngineProps["solutionType"]),
      );
      const previousVertical = verticalOf(
        olds?.industryVertical ??
          (output?.industryVertical as CollectionsEngineProps["industryVertical"]),
      );
      const nextVertical = verticalOf(
        news.industryVertical ??
          (output?.industryVertical as CollectionsEngineProps["industryVertical"]),
      );
      const replace =
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        previousLocation !== nextLocation ||
        previousCollection !== nextCollection ||
        previousSolution !== nextSolution ||
        previousVertical !== nextVertical;
      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          previousLocation === nextLocation &&
          previousCollection === nextCollection &&
          previousId !== undefined &&
          nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const engineId = yield* toResourceId(id, olds?.engineId, output?.engineId);
      const location = normalizeLocation(olds?.location ?? output?.location);
      const collectionId = normalizeCollection(olds?.collectionId ?? output?.collectionId);
      const existing = yield* getByName(
        output?.name ?? resourceName(env.project, location, collectionId, engineId),
      );
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      // No labels field: without prior state it may not be ours.
      return output !== undefined ? attrs : Unowned(attrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(news.location ?? output?.location);
      const collectionId = normalizeCollection(news.collectionId ?? output?.collectionId);
      const engineId = yield* toResourceId(id, news.engineId, output?.engineId);
      const displayName = news.displayName ?? engineId;
      const solutionType = solutionOf(news.solutionType);
      const industryVertical = verticalOf(news.industryVertical);
      const dataStoreIds = idsOf(news.dataStoreIds ?? output?.dataStoreIds);
      const parent = collectionParent(env.project, location, collectionId);
      const fallbackName =
        output?.name ?? resourceName(env.project, location, collectionId, engineId);
      const searchEngineConfig =
        solutionType === "SOLUTION_TYPE_SEARCH"
          ? (news.searchEngineConfig ?? {})
          : news.searchEngineConfig;
      const disableAnalytics = news.disableAnalytics === true;

      let current = yield* getByName(fallbackName);

      if (current === undefined) {
        const created = yield* discoveryengine
          .createProjectsLocationsCollectionsEngines({
            parent,
            engineId,
            body: {
              displayName,
              solutionType,
              industryVertical,
              dataStoreIds,
              searchEngineConfig,
              commonConfig: news.commonConfig,
              chatEngineConfig: news.chatEngineConfig,
              mediaRecommendationEngineConfig: news.mediaRecommendationEngineConfig,
              disableAnalytics: disableAnalytics ? true : undefined,
              appType: news.appType,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* waitUntilExists(fallbackName);
      }

      if (current === undefined) {
        return yield* new CollectionsEngineNotResolved({ resourceName: fallbackName });
      }

      const name = current.name ?? fallbackName;
      const displayNameChanged = (current.displayName ?? "") !== displayName;
      const analyticsChanged = (current.disableAnalytics === true) !== disableAnalytics;
      const companyChanged =
        (current.commonConfig?.companyName ?? "") !== (news.commonConfig?.companyName ?? "");
      const searchChanged =
        searchEngineConfig !== undefined &&
        !sameJson(current.searchEngineConfig, searchEngineConfig);
      const dataStoresChanged = !sameStringList(current.dataStoreIds, dataStoreIds);

      if (
        displayNameChanged ||
        analyticsChanged ||
        companyChanged ||
        searchChanged ||
        dataStoresChanged
      ) {
        current = yield* discoveryengine.patchProjectsLocationsCollectionsEngines({
          name,
          updateMask: [
            displayNameChanged ? "display_name" : undefined,
            analyticsChanged ? "disable_analytics" : undefined,
            companyChanged ? "common_config" : undefined,
            searchChanged ? "search_engine_config" : undefined,
            dataStoresChanged ? "data_store_ids" : undefined,
          ]
            .filter((field): field is string => field !== undefined)
            .join(","),
          body: {
            name,
            displayName,
            disableAnalytics,
            commonConfig: news.commonConfig,
            searchEngineConfig,
            dataStoreIds,
          },
        });
      }

      return toAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* getByName(output.name);
      if (existing === undefined) return;
      const operation = yield* discoveryengine
        .deleteProjectsLocationsCollectionsEngines({ name: output.name })
        .pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("2 seconds"),
          }),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      if (operation !== undefined) {
        yield* waitForOperation(operation, { notFoundOk: true });
      }
      yield* waitUntilGone(output.name);
    }),
  });