sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Firestore/ Database.ts

import * as firestore from "@distilled.cloud/gcp/firestore_v1";
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 * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import { waitForOperation as waitForGcpOperation } from "../Operation.ts";
import type { Providers } from "../Providers.ts";

const DEFAULT_TYPE = "FIRESTORE_NATIVE";
const DEFAULT_EDITION = "STANDARD";
const DEFAULT_DELETE_PROTECTION = "DELETE_PROTECTION_DISABLED";
const DEFAULT_APP_ENGINE = "DISABLED";
const MAX_DATABASE_ID_LENGTH = 63;

export type DatabaseType = firestore.GoogleFirestoreAdminV1DatabaseTypeEnum | (string & {});
export type DatabaseEdition =
  | firestore.GoogleFirestoreAdminV1DatabaseDatabaseEditionEnum
  | (string & {});
export type DatabaseConcurrencyMode =
  | firestore.GoogleFirestoreAdminV1DatabaseConcurrencyModeEnum
  | (string & {});
export type DatabasePointInTimeRecoveryEnablement =
  | firestore.GoogleFirestoreAdminV1DatabasePointInTimeRecoveryEnablementEnum
  | (string & {});
export type DatabaseAppEngineIntegrationMode =
  | firestore.GoogleFirestoreAdminV1DatabaseAppEngineIntegrationModeEnum
  | (string & {});
export type DatabaseDeleteProtectionState =
  | firestore.GoogleFirestoreAdminV1DatabaseDeleteProtectionStateEnum
  | (string & {});
export type DatabaseRealtimeUpdatesMode =
  | firestore.GoogleFirestoreAdminV1DatabaseRealtimeUpdatesModeEnum
  | (string & {});
export type DatabaseDataAccessMode =
  | firestore.GoogleFirestoreAdminV1DatabaseFirestoreDataAccessModeEnum
  | (string & {});

export type DatabaseCmekConfig = {
  /**
   * Cloud KMS CryptoKey used to encrypt the database
   * (`projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}`).
   * Must be in the same location as the database. Immutable — changing
   * it replaces the database.
   */
  kmsKeyName?: string;
};

export type DatabaseProps = {
  /**
   * Database id (the `{database}` segment of
   * `projects/{project}/databases/{database}`). If omitted, a unique name
   * is generated from the stack, stage, and logical id. Must be 4-63
   * characters, match `[a-z][a-z0-9-]*[a-z0-9]`, and must not look like a
   * UUID. `"(default)"` is valid for the Standard edition default
   * database. Immutable — changing it replaces the database.
   */
  databaseId?: string;
  /**
   * Location of the database (`us-central1`, `nam5`, `eur3`, …).
   * Immutable — changing it replaces the database. `US-CENTRAL1` is
   * accepted and normalized to `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * Database type. Mode changes are only allowed when the database is
   * empty.
   * @default "FIRESTORE_NATIVE"
   */
  type?: DatabaseType;
  /**
   * Database edition. Immutable — changing it replaces the database.
   * @default "STANDARD"
   */
  databaseEdition?: DatabaseEdition;
  /**
   * Default transaction concurrency mode. Defaults to `PESSIMISTIC` for
   * Standard edition and `OPTIMISTIC` for Enterprise.
   */
  concurrencyMode?: DatabaseConcurrencyMode;
  /**
   * Point-in-time recovery. When enabled, version retention is 7 days
   * instead of 1 hour.
   * @default "POINT_IN_TIME_RECOVERY_DISABLED"
   */
  pointInTimeRecoveryEnablement?: DatabasePointInTimeRecoveryEnablement;
  /**
   * App Engine integration mode. `DISABLED` is the API default for
   * databases created with the Firestore API.
   * @default "DISABLED"
   */
  appEngineIntegrationMode?: DatabaseAppEngineIntegrationMode;
  /**
   * Delete protection. Alchemy defaults to disabled so `destroy` can
   * delete the database.
   * @default "DELETE_PROTECTION_DISABLED"
   */
  deleteProtectionState?: DatabaseDeleteProtectionState;
  /**
   * Default Realtime Updates mode. Immutable — changing it replaces the
   * database.
   */
  realtimeUpdatesMode?: DatabaseRealtimeUpdatesMode;
  /**
   * Firestore API data access mode. Defaults to enabled on Standard
   * edition and disabled on Enterprise.
   */
  firestoreDataAccessMode?: DatabaseDataAccessMode;
  /**
   * MongoDB-compatible API data access mode. Always disabled on Standard
   * edition.
   */
  mongodbCompatibleDataAccessMode?: DatabaseDataAccessMode;
  /**
   * Customer-managed encryption. Immutable — changing it replaces the
   * database.
   */
  cmekConfig?: DatabaseCmekConfig;
};

export type Database = Resource<
  "GCP.Firestore.Database",
  DatabaseProps,
  {
    /** Full resource name `projects/{project}/databases/{database}`. */
    name: string;
    /** Database id (last path segment). */
    databaseId: string;
    /** Project id. */
    project: string;
    /** Location id (`us-central1`, `nam5`, …). */
    location: string;
    /** Database type (`FIRESTORE_NATIVE`, `DATASTORE_MODE`). */
    type: string;
    /** Database edition (`STANDARD`, `ENTERPRISE`). */
    databaseEdition: string | undefined;
    /** Default concurrency mode. */
    concurrencyMode: string | undefined;
    /** Point-in-time recovery enablement. */
    pointInTimeRecoveryEnablement: string | undefined;
    /** App Engine integration mode. */
    appEngineIntegrationMode: string | undefined;
    /** Delete protection state. */
    deleteProtectionState: string | undefined;
    /** Realtime Updates mode. */
    realtimeUpdatesMode: string | undefined;
    /** Firestore API data access mode. */
    firestoreDataAccessMode: string | undefined;
    /** MongoDB-compatible API data access mode. */
    mongodbCompatibleDataAccessMode: string | undefined;
    /** CMEK key, if any. */
    kmsKeyName: string | undefined;
    /** System-generated UUID4. */
    uid: string | undefined;
    /** Datastore key prefix, if any. */
    keyPrefix: string | undefined;
    /** Whether this database is eligible for the free tier. */
    freeTier: boolean | undefined;
    /** Version retention period (e.g. `"3600s"`). */
    versionRetentionPeriod: string | undefined;
    /** Earliest PITR timestamp, if available. */
    earliestVersionTime: string | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
    /** Server etag. */
    etag: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Firestore database.
 *
 * Firestore databases have no labels field and Alchemy writes no data
 * into them: `read` reports a database it finds without prior state as
 * unowned (adopt it with `--adopt`). Changing `databaseId`, `location`, `databaseEdition`, CMEK, or
 * Realtime Updates mode replaces the database.
 *
 * Create, update, and delete are long-running operations — provisioning
 * a named database typically takes tens of seconds.
 *
 * ### Creating a Database
 * **Example:** Generated name
 * ```typescript
 * const database = yield* GCP.Firestore.Database("App", {});
 * ```
 *
 * **Example:** Explicit id, location, and concurrency
 * ```typescript
 * const database = yield* GCP.Firestore.Database("App", {
 *   databaseId: "app-data",
 *   location: "us-central1",
 *   type: "FIRESTORE_NATIVE",
 *   concurrencyMode: "OPTIMISTIC",
 * });
 * ```
 *
 * ### Reading and Writing Documents
 * **Example:** Upsert and read a document
 * ```typescript
 * const patchDocument = yield* GCP.Firestore.PatchDocument(database);
 * yield* patchDocument({
 *   documentPath: "users/alice",
 *   body: { fields: { name: { stringValue: "Alice" } } },
 * });
 * const getDocument = yield* GCP.Firestore.GetDocument(database);
 * const doc = yield* getDocument({ documentPath: "users/alice" });
 * ```
 *
 * @resource
 * @category Firestore
 */
export const Database = Resource<Database>("GCP.Firestore.Database");

export class DatabaseNotResolved extends Data.TaggedError("GCP.Firestore.DatabaseNotResolved")<{
  resourceName: string;
}> {}

export class DatabaseStillExists extends Data.TaggedError("GCP.Firestore.DatabaseStillExists")<{
  resourceName: string;
}> {}

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const normalizeLocation = (location: string | undefined, fallback: string) =>
  lastSegment(location ?? fallback).toLowerCase();

const normalizeEnum = (value: string | undefined, fallback: string) => {
  const next = (value ?? fallback).toUpperCase();
  return next.endsWith("_UNSPECIFIED") ? fallback : next;
};

const normalizeType = (value: string | undefined) => normalizeEnum(value, DEFAULT_TYPE);

const normalizeEdition = (value: string | undefined) => normalizeEnum(value, DEFAULT_EDITION);

const resourceName = (project: string, databaseId: string) =>
  `projects/${project}/databases/${databaseId}`;

const parseName = (name: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const databasesAt = parts.lastIndexOf("databases");
  const projectsAt = parts.lastIndexOf("projects");
  return {
    project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
    databaseId:
      databasesAt >= 0 && parts[databasesAt + 1] ? parts[databasesAt + 1]! : lastSegment(name),
  };
};

const toDatabaseId = (id: string, databaseId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (databaseId !== undefined) return databaseId;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: MAX_DATABASE_ID_LENGTH,
      lowercase: true,
    });
    let named = /^[a-z]/.test(generated) ? generated : `f${generated}`;
    named = named.replace(/-+$/g, "").slice(0, MAX_DATABASE_ID_LENGTH);
    named = named.replace(/-+$/g, "");
    if (named.length < 4) {
      named = `${named}dbxx`.slice(0, MAX_DATABASE_ID_LENGTH);
    }
    return named;
  });

const toAttrs = (
  database: firestore.GoogleFirestoreAdminV1Database,
  project: string,
): Database["Attributes"] => {
  const name = database.name ?? "";
  const parsed = parseName(name);
  return {
    name,
    databaseId: parsed.databaseId,
    project: parsed.project || project,
    location: normalizeLocation(database.locationId, ""),
    type: normalizeType(database.type),
    databaseEdition: database.databaseEdition,
    concurrencyMode: database.concurrencyMode,
    pointInTimeRecoveryEnablement: database.pointInTimeRecoveryEnablement,
    appEngineIntegrationMode: database.appEngineIntegrationMode,
    deleteProtectionState: database.deleteProtectionState,
    realtimeUpdatesMode: database.realtimeUpdatesMode,
    firestoreDataAccessMode: database.firestoreDataAccessMode,
    mongodbCompatibleDataAccessMode: database.mongodbCompatibleDataAccessMode,
    kmsKeyName: database.cmekConfig?.kmsKeyName,
    uid: database.uid,
    keyPrefix: database.keyPrefix,
    freeTier: database.freeTier,
    versionRetentionPeriod: database.versionRetentionPeriod,
    earliestVersionTime: database.earliestVersionTime,
    createTime: database.createTime,
    updateTime: database.updateTime,
    etag: database.etag,
  };
};

const getByName = (name: string) =>
  firestore.getProjectsDatabases({ name }).pipe(
    Effect.map((database) => (database.deleteTime !== undefined ? undefined : database)),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

/**
 * Wait for a Firestore admin operation; named databases provision in tens
 * of seconds to a few minutes. With `alreadyExistsOk`, ALREADY_EXISTS
 * (code 6) counts as success (create race).
 */
const waitForOperation = (
  operation: firestore.GoogleLongrunningOperation,
  options?: { alreadyExistsOk?: boolean },
) =>
  waitForGcpOperation(operation, (name) => firestore.getProjectsDatabasesOperations({ name }), {
    budget: "10 minutes",
  }).pipe(
    Effect.catchIf(
      (error) =>
        options?.alreadyExistsOk === true &&
        error._tag === "GCP.OperationFailed" &&
        error.code === 6,
      () => Effect.succeed(operation),
    ),
  );

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (database): database is firestore.GoogleFirestoreAdminV1Database => database !== undefined,
      () => new DatabaseNotResolved({ resourceName: name }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Firestore.DatabaseNotResolved",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (database) => database === undefined,
      () => new DatabaseStillExists({ resourceName: name }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Firestore.DatabaseStillExists",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
    Effect.asVoid,
  );

const retryConcurrentChanges = <A, E extends { readonly _tag: string }, R>(
  effect: Effect.Effect<A, E, R>,
) =>
  effect.pipe(
    Effect.retry({
      while: (error) => error._tag === "Conflict",
      times: 8,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

const enumChanged = (desired: string | undefined, observed: string | undefined) => {
  if (desired === undefined) return false;
  return normalizeEnum(observed, desired) !== normalizeEnum(desired, desired);
};

export const DatabaseProvider = () =>
  Provider.succeed(Database, {
    stables: [
      "name",
      "databaseId",
      "project",
      "location",
      "uid",
      "createTime",
      "keyPrefix",
      "databaseEdition",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      const env = yield* GcpEnvironment.current;
      if (!isResolved(news)) return undefined;

      const previousId = olds?.databaseId ?? output?.databaseId;
      const nextId = news.databaseId ?? previousId;
      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
      const previousEdition = normalizeEdition(olds?.databaseEdition ?? output?.databaseEdition);
      const nextEdition = normalizeEdition(news.databaseEdition ?? output?.databaseEdition);
      const previousKms = olds?.cmekConfig?.kmsKeyName ?? output?.kmsKeyName ?? "";
      const nextKms = news.cmekConfig?.kmsKeyName ?? previousKms;
      const previousRealtime = (
        olds?.realtimeUpdatesMode ??
        output?.realtimeUpdatesMode ??
        ""
      ).toUpperCase();
      const nextRealtime = (
        news.realtimeUpdatesMode ??
        output?.realtimeUpdatesMode ??
        previousRealtime
      ).toUpperCase();

      const replace =
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        previousLocation !== nextLocation ||
        previousEdition !== nextEdition ||
        previousKms !== nextKms ||
        (news.realtimeUpdatesMode !== undefined && previousRealtime !== nextRealtime);

      if (!replace) return undefined;
      return {
        action: "replace" as const,
        deleteFirst: previousId !== undefined && nextId !== undefined && nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const databaseId = yield* toDatabaseId(id, olds?.databaseId, output?.databaseId);
      const name = output?.name ?? resourceName(env.project, databaseId);
      const existing = yield* getByName(name);
      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 databaseId = yield* toDatabaseId(id, news.databaseId, output?.databaseId);
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const type = normalizeType(news.type);
      const name = resourceName(env.project, databaseId);
      const desiredProtection = news.deleteProtectionState ?? DEFAULT_DELETE_PROTECTION;

      let current = yield* getByName(name);

      if (current === undefined) {
        const created = yield* firestore
          .createProjectsDatabases({
            parent: `projects/${env.project}`,
            databaseId,
            body: {
              locationId: location,
              type,
              databaseEdition: news.databaseEdition
                ? normalizeEdition(news.databaseEdition)
                : undefined,
              concurrencyMode: news.concurrencyMode,
              pointInTimeRecoveryEnablement: news.pointInTimeRecoveryEnablement,
              appEngineIntegrationMode: news.appEngineIntegrationMode ?? DEFAULT_APP_ENGINE,
              deleteProtectionState: desiredProtection,
              realtimeUpdatesMode: news.realtimeUpdatesMode,
              firestoreDataAccessMode: news.firestoreDataAccessMode,
              mongodbCompatibleDataAccessMode: news.mongodbCompatibleDataAccessMode,
              cmekConfig: news.cmekConfig?.kmsKeyName
                ? { kmsKeyName: news.cmekConfig.kmsKeyName }
                : undefined,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created, { alreadyExistsOk: true });
        }
        current = yield* waitUntilExists(name);
      }

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

      const mask: string[] = [];
      const patchBody: firestore.GoogleFirestoreAdminV1Database = {};

      if (enumChanged(type, current.type)) {
        patchBody.type = type;
        mask.push("type");
      }
      if (enumChanged(news.concurrencyMode, current.concurrencyMode)) {
        patchBody.concurrencyMode = news.concurrencyMode;
        mask.push("concurrencyMode");
      }
      if (enumChanged(news.pointInTimeRecoveryEnablement, current.pointInTimeRecoveryEnablement)) {
        patchBody.pointInTimeRecoveryEnablement = news.pointInTimeRecoveryEnablement;
        mask.push("pointInTimeRecoveryEnablement");
      }
      if (enumChanged(news.appEngineIntegrationMode, current.appEngineIntegrationMode)) {
        patchBody.appEngineIntegrationMode = news.appEngineIntegrationMode;
        mask.push("appEngineIntegrationMode");
      }
      if (enumChanged(desiredProtection, current.deleteProtectionState)) {
        patchBody.deleteProtectionState = desiredProtection;
        mask.push("deleteProtectionState");
      }
      if (enumChanged(news.firestoreDataAccessMode, current.firestoreDataAccessMode)) {
        patchBody.firestoreDataAccessMode = news.firestoreDataAccessMode;
        mask.push("firestoreDataAccessMode");
      }
      if (
        enumChanged(news.mongodbCompatibleDataAccessMode, current.mongodbCompatibleDataAccessMode)
      ) {
        patchBody.mongodbCompatibleDataAccessMode = news.mongodbCompatibleDataAccessMode;
        mask.push("mongodbCompatibleDataAccessMode");
      }

      if (mask.length > 0) {
        const patched = yield* retryConcurrentChanges(
          firestore.patchProjectsDatabases({
            name,
            updateMask: mask.join(","),
            body: patchBody,
          }),
        );
        yield* waitForOperation(patched);
        current = yield* waitUntilExists(name);
      }

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

    delete: Effect.fn(function* ({ output }) {
      const current = yield* getByName(output.name);
      if (current === undefined) return;

      if (
        normalizeEnum(current.deleteProtectionState, DEFAULT_DELETE_PROTECTION) ===
        "DELETE_PROTECTION_ENABLED"
      ) {
        const patched = yield* retryConcurrentChanges(
          firestore.patchProjectsDatabases({
            name: output.name,
            updateMask: "deleteProtectionState",
            body: {
              deleteProtectionState: DEFAULT_DELETE_PROTECTION,
            },
          }),
        );
        yield* waitForOperation(patched);
      }

      yield* retryConcurrentChanges(firestore.deleteProjectsDatabases({ name: output.name })).pipe(
        Effect.catchTag("NotFound", () => Effect.void),
      );
      // Soft-delete: GET reports `deleteTime` long before the LRO is done.
      yield* waitUntilGone(output.name);
    }),
  });