sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ DataCatalog/ Taxonomy.ts

import * as datacatalog from "@distilled.cloud/gcp/datacatalog_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import { isTransientGcpError } from "../Errors.ts";
import { createInternalLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  DatacatalogNotResolved,
  collectPages,
  emptyOnMissing,
  encodeOwnership,
  findOwned,
  hasOwnershipMarker,
  ignoreGone,
  listAtLocation,
  locationParent,
  missingGet,
  normalizeLocation,
  ownedByAlchemy,
  parseName,
  parseOwnership,
  replaceOnIdentity,
  retryTransient,
  sameStringList,
  sameText,
  toDisplayName,
  updateMaskOf,
  type TaxonomyActivatedPolicyType,
} from "./internal.ts";

export type { TaxonomyActivatedPolicyType };

export type TaxonomyProps = {
  /**
   * Region (`us-central1`, `us`, …). Immutable — changing it replaces
   * the taxonomy. Policy Tag Manager assigns the taxonomy id; it is not
   * chosen by the caller.
   * @default the stack's GCP region (`GCP.Region`, profile region, `us-central1`)
   */
  location?: string;
  /**
   * User-defined display name. Unique within an organization. Letters,
   * numbers, underscores, dashes, and spaces; max 200 bytes. If omitted,
   * a unique name is generated from the stack, stage, and logical id.
   */
  displayName?: string;
  /**
   * Human-readable description (max 2000 bytes). Taxonomies have no
   * labels field, so Alchemy ownership is stored in a `[alchemy …]`
   * prefix and stripped from attributes.
   */
  description?: string;
  /**
   * Policy types activated on this taxonomy
   * (`FINE_GRAINED_ACCESS_CONTROL`).
   */
  activatedPolicyTypes?: TaxonomyActivatedPolicyType[];
};

export type Taxonomy = Resource<
  "GCP.DataCatalog.Taxonomy",
  TaxonomyProps,
  {
    /** Full resource name. */
    name: string;
    /** Server-assigned taxonomy id (last path segment). */
    taxonomyId: string;
    /** Project id. */
    project: string;
    /** Location id. */
    location: string;
    /** Display name. */
    displayName: string | undefined;
    /** User description (Alchemy ownership marker stripped). */
    description: string | undefined;
    /** Activated policy types. */
    activatedPolicyTypes: string[];
    /** Number of policy tags in this taxonomy. */
    policyTagCount: number | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Data Catalog taxonomy — a hierarchy of policy tags used to classify
 * data (for example PII vs financials).
 *
 * Taxonomy ids are assigned by Policy Tag Manager. Location is
 * immutable. Display name, description, and activated policy types
 * update in place. Taxonomies have no labels; Alchemy stamps
 * `alchemy-stack` / `alchemy-stage` / `alchemy-id` into the description
 * so `list` and `pnpm nuke:gcp` can identify owned taxonomies.
 *
 * ### Creating a Taxonomy
 * **Example:** Generated display name
 * ```typescript
 * const taxonomy = yield* GCP.DataCatalog.Taxonomy("Pii", {
 *   description: "sensitivity classes",
 * });
 * ```
 *
 * **Example:** Fine-grained access control
 * ```typescript
 * const taxonomy = yield* GCP.DataCatalog.Taxonomy("Pii", {
 *   displayName: "PII",
 *   activatedPolicyTypes: ["FINE_GRAINED_ACCESS_CONTROL"],
 * });
 * ```
 *
 * ### Updating a Taxonomy
 * **Example:** Description
 * ```typescript
 * // Same logical id, changed props: the engine updates it in place.
 * const taxonomy = yield* GCP.DataCatalog.Taxonomy("Pii", {
 *   displayName: "PII",
 *   description: "sensitivity classes v2",
 *   activatedPolicyTypes: ["FINE_GRAINED_ACCESS_CONTROL"],
 * });
 * ```
 *
 * @resource
 * @category DataCatalog
 */
export const Taxonomy = Resource<Taxonomy>("GCP.DataCatalog.Taxonomy");

const toAttrs = (
  taxonomy: datacatalog.GoogleCloudDatacatalogV1Taxonomy,
  project: string,
  region: string,
) => {
  const name = taxonomy.name ?? "";
  const parsed = parseName(name, "taxonomies", region);
  const ownership = parseOwnership(taxonomy.description);
  return {
    name,
    taxonomyId: parsed.id,
    project: parsed.project || project,
    location: parsed.location,
    displayName: taxonomy.displayName,
    description: ownership.text,
    activatedPolicyTypes: [...(taxonomy.activatedPolicyTypes ?? [])],
    policyTagCount: taxonomy.policyTagCount,
    createTime: taxonomy.taxonomyTimestamps?.createTime,
    updateTime: taxonomy.taxonomyTimestamps?.updateTime,
  };
};

const getByName = missingGet(datacatalog.getProjectsLocationsTaxonomies);

const listTaxonomiesAt = (
  parent: string,
): Effect.Effect<
  datacatalog.GoogleCloudDatacatalogV1Taxonomy[],
  datacatalog.ListProjectsLocationsTaxonomiesError,
  datacatalog.GcpOpContext
> =>
  emptyOnMissing(
    collectPages(
      datacatalog.listProjectsLocationsTaxonomies.pages({
        parent,
        pageSize: 1000,
      }),
      (page) => page.taxonomies,
    ),
  );

const listOwned = (project: string, region: string) =>
  listAtLocation(project, region, listTaxonomiesAt).pipe(
    Effect.map((items) => items.filter((item) => hasOwnershipMarker(item.description))),
  );

const observe = (id: string, name: string | undefined, project: string, location: string) =>
  Effect.gen(function* () {
    if (name !== undefined && name.length > 0) {
      const existing = yield* getByName(name);
      if (existing !== undefined) return existing;
    }
    const candidates = yield* listTaxonomiesAt(locationParent(project, location));
    return yield* findOwned(candidates, id, (item) => item.description);
  });

export const TaxonomyProvider = () =>
  Provider.succeed(Taxonomy, {
    stables: ["name", "taxonomyId", "project", "location", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      return replaceOnIdentity({
        previousLocation: normalizeLocation(olds?.location ?? output?.location, env.region),
        nextLocation: normalizeLocation(
          news.location ?? olds?.location ?? output?.location,
          env.region,
        ),
      });
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(olds?.location ?? output?.location, env.region);
      const existing = yield* observe(id, output?.name, env.project, location);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project, env.region);
      return (yield* ownedByAlchemy(id, existing.description)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const items = yield* listOwned(env.project, env.region);
        return items.map((item) => toAttrs(item, env.project, env.region));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const parent = locationParent(env.project, location);
      const ownership = yield* createInternalLabels(id);
      const description = encodeOwnership(ownership, news.description);
      const displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
      const activatedPolicyTypes = news.activatedPolicyTypes;

      let current = yield* observe(id, output?.name, env.project, location);

      if (current === undefined) {
        const created = yield* retryTransient(
          datacatalog.createProjectsLocationsTaxonomies({
            parent,
            body: {
              displayName,
              description,
              activatedPolicyTypes,
            },
          }),
        ).pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        current = created ?? (yield* observe(id, undefined, env.project, location));
      }

      if (current === undefined) {
        return yield* new DatacatalogNotResolved({
          resourceName: output?.name ?? `${parent}/taxonomies`,
        });
      }

      const currentName = current.name ?? output?.name ?? "";
      const displayChanged = !sameText(current.displayName, displayName);
      const descriptionChanged = (current.description ?? "") !== description;
      const policyChanged =
        activatedPolicyTypes !== undefined &&
        !sameStringList(current.activatedPolicyTypes, activatedPolicyTypes);

      if (displayChanged || descriptionChanged || policyChanged) {
        current = yield* retryTransient(
          datacatalog.patchProjectsLocationsTaxonomies({
            name: currentName,
            updateMask: updateMaskOf(
              displayChanged ? "display_name" : undefined,
              descriptionChanged ? "description" : undefined,
              policyChanged ? "activated_policy_types" : undefined,
            ),
            body: {
              name: currentName,
              displayName,
              description,
              activatedPolicyTypes,
            },
          }),
        );
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* ignoreGone(
        datacatalog.deleteProjectsLocationsTaxonomies({ name: output.name }).pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict" || isTransientGcpError(error),
            times: 8,
            schedule: Schedule.exponential("500 millis"),
          }),
        ),
      );
    }),
  });