sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ AIPlatform/ FeatureOnlineStore.ts

import * as aiplatform from "@distilled.cloud/gcp/aiplatform_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } 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 { GcpEnvironment } from "../Environment.ts";
import { createInternalLabels, diffLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  hasAlchemyLabelMap,
  normalizeLocation,
  parseResourceName,
  specifiedEquals,
  toPhysicalSnake,
  userLabels,
} from "./helpers.ts";
import { listLocations } from "./names.ts";
import { waitForOperation } from "./operations.ts";

const MAX_NAME_LENGTH = 60;

export type FeatureOnlineStoreBigtableAutoScaling = {
  /** Minimum node count (>= 1). */
  minNodeCount?: number;
  /** Maximum node count (<= 10 * minNodeCount). */
  maxNodeCount?: number;
  /** Target CPU percent (10–80). Defaults to 50. */
  cpuUtilizationTarget?: number;
};

export type FeatureOnlineStoreBigtable = {
  /** Autoscaling applied to the backing Bigtable instance. */
  autoScaling?: FeatureOnlineStoreBigtableAutoScaling;
  /** Allow direct Bigtable access. */
  enableDirectBigtableAccess?: boolean;
  /** Zone for the primary Bigtable cluster (e.g. `us-central1-a`). Immutable. */
  zone?: string;
};

export type FeatureOnlineStoreDedicatedServingEndpoint = {
  /** Private Service Connect config (Optimized storage only). */
  privateServiceConnectConfig?: {
    enablePrivateServiceConnect?: boolean;
    projectAllowlist?: string[];
  };
};

export type FeatureOnlineStoreProps = {
  /**
   * Feature Online Store id. Valid characters `[a-z0-9_]`, must start
   * with a letter, max 60. Immutable — changing it replaces the store.
   */
  featureOnlineStoreId?: string;
  /**
   * Region. Immutable — changing it replaces the store.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
  /**
   * Bigtable storage. Mutually exclusive with `optimized`. Immutable
   * storage type — switching to Optimized replaces the store.
   * @default { autoScaling: { minNodeCount: 1, maxNodeCount: 1 } } when `optimized` is unset
   */
  bigtable?: FeatureOnlineStoreBigtable;
  /**
   * Optimized storage. When true or `{}`, Vertex provisions the
   * Optimized serving backend. Immutable storage type.
   */
  optimized?: boolean | Record<string, never>;
  /**
   * Dedicated serving endpoint (Optimized storage).
   */
  dedicatedServingEndpoint?: FeatureOnlineStoreDedicatedServingEndpoint;
  /**
   * Customer-managed encryption. Immutable.
   */
  encryptionSpec?: { kmsKeyName?: string };
};

export type FeatureOnlineStore = Resource<
  "GCP.AIPlatform.FeatureOnlineStore",
  FeatureOnlineStoreProps,
  {
    /** Full resource name. */
    name: string;
    /** Store id. */
    featureOnlineStoreId: string;
    /** Project id. */
    project: string;
    /** Location id. */
    location: string;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Bigtable config, if used. */
    bigtable: FeatureOnlineStoreBigtable | undefined;
    /** Whether Optimized storage is enabled. */
    optimized: boolean;
    /** Store state (`STABLE`, `UPDATING`). */
    state: string | undefined;
    /** Dedicated serving endpoint. */
    dedicatedServingEndpoint:
      | {
          publicEndpointDomainName: string | undefined;
          serviceAttachment: string | undefined;
          privateServiceConnectConfig:
            | {
                enablePrivateServiceConnect?: boolean;
                projectAllowlist?: string[];
              }
            | undefined;
        }
      | undefined;
    /** Customer-managed encryption key. */
    encryptionSpec: { kmsKeyName?: string } | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
    /** Server etag. */
    etag: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Vertex AI Feature Online Store for low-latency feature and embedding
 * serving.
 *
 * Id, location, storage type (Bigtable vs Optimized), Bigtable zone, and
 * encryption are identity. Labels and Bigtable autoscaling update in
 * place. Defaults to a one-node Bigtable backend when neither backend is
 * set (Vertex AI no longer creates new Optimized stores for most projects).
 *
 * ### Creating a Feature Online Store
 * **Example:** Default one-node Bigtable store
 * ```typescript
 * const store = yield* GCP.AIPlatform.FeatureOnlineStore("Serving", {
 *   labels: { env: "prod" },
 * });
 * ```
 *
 * **Example:** Bigtable-backed store
 * ```typescript
 * const store = yield* GCP.AIPlatform.FeatureOnlineStore("Serving", {
 *   bigtable: {
 *     autoScaling: { minNodeCount: 1, maxNodeCount: 2 },
 *   },
 * });
 * ```
 *
 * @resource
 * @category AIPlatform
 */
export const FeatureOnlineStore = Resource<FeatureOnlineStore>("GCP.AIPlatform.FeatureOnlineStore");

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

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

const resourceName = (project: string, location: string, storeId: string) =>
  `projects/${project}/locations/${location}/featureOnlineStores/${storeId}`;

// Vertex no longer creates Optimized stores unless asked explicitly, so
// the default backend is the smallest Bigtable one.
const wantsOptimized = (news: FeatureOnlineStoreProps) =>
  news.bigtable === undefined && news.optimized !== undefined && news.optimized !== false;

const DEFAULT_BIGTABLE: FeatureOnlineStoreBigtable = {
  autoScaling: { minNodeCount: 1, maxNodeCount: 1 },
};

const bigtableOf = (news: FeatureOnlineStoreProps) => news.bigtable ?? DEFAULT_BIGTABLE;

const toBigtable = (
  config:
    | aiplatform.GoogleCloudAiplatformV1FeatureOnlineStoreBigtable
    | FeatureOnlineStoreBigtable
    | undefined,
): FeatureOnlineStoreBigtable | undefined => {
  if (config === undefined) return undefined;
  return {
    autoScaling: config.autoScaling
      ? {
          minNodeCount: config.autoScaling.minNodeCount,
          maxNodeCount: config.autoScaling.maxNodeCount,
          cpuUtilizationTarget: config.autoScaling.cpuUtilizationTarget,
        }
      : undefined,
    enableDirectBigtableAccess: config.enableDirectBigtableAccess,
    zone: config.zone,
  };
};

const toAttrs = (store: aiplatform.GoogleCloudAiplatformV1FeatureOnlineStore, project: string) => {
  const name = store.name ?? "";
  const parsed = parseResourceName(name, "featureOnlineStores");
  const endpoint = store.dedicatedServingEndpoint;
  return {
    name,
    featureOnlineStoreId: parsed.id,
    project: parsed.project || project,
    location: parsed.location,
    labels: userLabels(store.labels),
    bigtable: toBigtable(store.bigtable),
    optimized: store.optimized !== undefined,
    state: store.state,
    dedicatedServingEndpoint:
      endpoint === undefined
        ? undefined
        : {
            publicEndpointDomainName: endpoint.publicEndpointDomainName,
            serviceAttachment: endpoint.serviceAttachment,
            privateServiceConnectConfig: endpoint.privateServiceConnectConfig
              ? {
                  enablePrivateServiceConnect:
                    endpoint.privateServiceConnectConfig.enablePrivateServiceConnect === true,
                  projectAllowlist: endpoint.privateServiceConnectConfig.projectAllowlist,
                }
              : undefined,
          },
    encryptionSpec: store.encryptionSpec?.kmsKeyName
      ? { kmsKeyName: store.encryptionSpec.kmsKeyName }
      : undefined,
    createTime: store.createTime,
    updateTime: store.updateTime,
    etag: store.etag,
  };
};

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

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

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

const isReady = (state: string | undefined) => {
  const value = (state ?? "").toUpperCase();
  return value === "STABLE" || value === "";
};

const waitUntilReady = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (store): store is aiplatform.GoogleCloudAiplatformV1FeatureOnlineStore => store !== undefined,
      () => new FeatureOnlineStoreNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (store) => isReady(store.state),
      () => new FeatureOnlineStoreNotResolved({ resourceName: name }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.AIPlatform.FeatureOnlineStoreNotResolved",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
  );

export const FeatureOnlineStoreProvider = () =>
  Provider.succeed(FeatureOnlineStore, {
    stables: ["name", "featureOnlineStoreId", "project", "location", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      const env = yield* GcpEnvironment.current;
      if (!isResolved(news)) return undefined;
      const previousId = olds?.featureOnlineStoreId ?? output?.featureOnlineStoreId;
      const nextId = news.featureOnlineStoreId ?? previousId;
      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
      const previousOptimized =
        olds?.optimized !== undefined ? olds.optimized !== false : (output?.optimized ?? false);
      const nextOptimized =
        news.bigtable !== undefined
          ? false
          : news.optimized !== undefined
            ? news.optimized !== false
            : previousOptimized;
      const previousZone = olds?.bigtable?.zone ?? output?.bigtable?.zone ?? "";
      const nextZone = news.bigtable?.zone ?? previousZone;
      const previousKey =
        olds?.encryptionSpec?.kmsKeyName ?? output?.encryptionSpec?.kmsKeyName ?? "";
      const nextKey = news.encryptionSpec?.kmsKeyName ?? previousKey;
      const replace =
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        previousLocation !== nextLocation ||
        previousOptimized !== nextOptimized ||
        previousZone !== nextZone ||
        previousKey !== nextKey;
      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          previousLocation === nextLocation && previousId !== undefined && nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const storeId = yield* toPhysicalSnake(
        id,
        olds?.featureOnlineStoreId,
        output?.featureOnlineStoreId,
        MAX_NAME_LENGTH,
      );
      const location = normalizeLocation(olds?.location ?? output?.location, env.region);
      const name = output?.name ?? resourceName(env.project, location, storeId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* Stream.fromIterable(listLocations(env.region)).pipe(
          Stream.flatMap((location) =>
            aiplatform.listProjectsLocationsFeatureOnlineStores.pages({
              parent: `projects/${env.project}/locations/${location}`,
              pageSize: 100,
            }),
          ),
          Stream.flatMap((page) => Stream.fromIterable(page.featureOnlineStores ?? [])),
          Stream.filter((store) => hasAlchemyLabelMap(store.labels)),
          Stream.map((store) => toAttrs(store, env.project)),
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
          Effect.catchTag("NotFound", () => Effect.succeed([])),
        );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const storeId = yield* toPhysicalSnake(
        id,
        news.featureOnlineStoreId,
        output?.featureOnlineStoreId,
        MAX_NAME_LENGTH,
      );
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const name = resourceName(env.project, location, storeId);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };
      const optimized = wantsOptimized(news);

      let current = yield* getByName(output?.name ?? name);

      if (current === undefined) {
        const created = yield* aiplatform
          .createProjectsLocationsFeatureOnlineStores({
            parent: `projects/${env.project}/locations/${location}`,
            featureOnlineStoreId: storeId,
            body: {
              labels: desiredLabels,
              bigtable: optimized ? undefined : bigtableOf(news),
              optimized: optimized ? {} : undefined,
              dedicatedServingEndpoint: news.dedicatedServingEndpoint,
              encryptionSpec: news.encryptionSpec,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* waitUntilExists(name);
      }

      if (current === undefined) {
        return yield* new FeatureOnlineStoreNotResolved({ resourceName: name });
      }

      if (!isReady(current.state)) {
        current = yield* waitUntilReady(name);
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const scalingChanged =
        news.bigtable?.autoScaling !== undefined &&
        !specifiedEquals(news.bigtable.autoScaling, current.bigtable?.autoScaling);
      const directChanged =
        news.bigtable?.enableDirectBigtableAccess !== undefined &&
        (current.bigtable?.enableDirectBigtableAccess === true) !==
          (news.bigtable.enableDirectBigtableAccess === true);

      if (labelsChanged || scalingChanged || directChanged) {
        const updateMask = [
          labelsChanged ? "labels" : undefined,
          scalingChanged ? "bigtable.auto_scaling" : undefined,
          directChanged ? "bigtable" : undefined,
        ].filter((field): field is string => field !== undefined);

        const patched = yield* aiplatform
          .patchProjectsLocationsFeatureOnlineStores({
            name,
            updateMask: updateMask.join(","),
            body: {
              name,
              labels: desiredLabels,
              bigtable: news.bigtable,
            },
          })
          .pipe(
            Effect.retry({
              while: (error) => error._tag === "Conflict",
              times: 8,
              schedule: Schedule.spaced("5 seconds"),
            }),
          );
        yield* waitForOperation(patched);
        current = yield* waitUntilReady(name);
      }

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

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