sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ BigQueryDataPolicy/ DataPolicy.ts

import * as bqdp from "@distilled.cloud/gcp/bigquerydatapolicy_v2";
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 * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  LIST_LOCATIONS,
  compact,
  hasOwnershipMarker,
  lastSegment,
  normalizeLocation,
  normalizePolicyType,
  ownedByAlchemy,
  parentOf,
  parseName,
  resourceNameOf,
  sameJson,
  sameStringList,
  sameText,
  sortedStrings,
  toDataPolicyId,
  updateMaskOf,
} from "./internal.ts";

export type DataPolicyType = bqdp.DataPolicyDataPolicyTypeEnum | (string & {});

export type DataMaskingPolicyPredefinedExpression =
  | bqdp.DataMaskingPolicyPredefinedExpressionEnum
  | (string & {});

export type DataMaskingPolicy = {
  /**
   * Predefined masking expression (`SHA256`, `ALWAYS_NULL`,
   * `DEFAULT_MASKING_VALUE`, `LAST_FOUR_CHARACTERS`,
   * `FIRST_FOUR_CHARACTERS`, `EMAIL_MASK`, `DATE_YEAR_MASK`,
   * `RANDOM_HASH`). Mutually exclusive with `routine`.
   */
  predefinedExpression?: DataMaskingPolicyPredefinedExpression;
  /**
   * BigQuery routine that implements a custom masking function, as
   * `projects/{project}/datasets/{dataset}/routines/{routine}`. Mutually
   * exclusive with `predefinedExpression`.
   */
  routine?: string;
};

export type DataGovernanceTag = {
  /**
   * Namespaced tag key (`parent-id/pii`). Tag keys are globally unique
   * Resource Manager keys.
   */
  key?: string;
  /**
   * Short tag value (`sensitive`).
   */
  value?: string;
};

export type DataPolicyProps = {
  /**
   * Data policy id (the `{dataPolicy}` segment of
   * `projects/{project}/locations/{location}/dataPolicies/{dataPolicy}`).
   * If omitted, a unique name is generated from the stack, stage, and
   * logical id. Letters, digits, and underscores; max 200 characters.
   * Data policies have no labels field, so Alchemy stamps ownership into
   * this id (`alch___…`) for `list` / nuke. Immutable — changing it
   * replaces the policy.
   */
  dataPolicyId?: string;
  /**
   * BigQuery location (`us-central1`, `US`, `EU`, …). Immutable —
   * changing it replaces the policy. Multi-regions `US` and `EU` stay
   * uppercase; regional ids are lowercased (`US-CENTRAL1` becomes
   * `us-central1`).
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * Type of data policy. `COLUMN_LEVEL_SECURITY_POLICY` is deprecated in
   * the v2 API (GET/LIST of v1 policies only).
   * @default "RAW_DATA_ACCESS_POLICY"
   */
  dataPolicyType?: DataPolicyType;
  /**
   * Masking rule. Required when `dataPolicyType` is
   * `DATA_MASKING_POLICY`.
   */
  dataMaskingPolicy?: DataMaskingPolicy;
  /**
   * IAM V2 principals with fine-grained access to the governed data
   * (`principal://goog/subject/user@example.com`). V2 policies only.
   */
  grantees?: string[];
  /**
   * Resource Manager data-governance tag bound to this policy.
   */
  dataGovernanceTag?: DataGovernanceTag;
};

export type DataPolicy = Resource<
  "GCP.BigQueryDataPolicy.DataPolicy",
  DataPolicyProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/dataPolicies/{dataPolicy}`. */
    name: string;
    /** Data policy id (last path segment), including the Alchemy prefix. */
    dataPolicyId: string;
    /** Project id used when the policy was reconciled. */
    project: string;
    /** Location id (`us-central1`, `US`, …). */
    location: string;
    /** Policy type. */
    dataPolicyType: string | undefined;
    /** Masking rule, if this is a data-masking policy. */
    dataMaskingPolicy: DataMaskingPolicy | undefined;
    /** Fine-grained access principals. */
    grantees: string[];
    /** Bound data-governance tag, if any. */
    dataGovernanceTag: DataGovernanceTag | undefined;
    /** Policy-tag resource name (v1 policies only). */
    policyTag: string | undefined;
    /** Server-reported policy version (`V1`, `V2`). */
    version: string | undefined;
    /** Server etag used for concurrent updates. */
    etag: string | undefined;
  },
  never,
  Providers
>;

/**
 * A BigQuery Data Policy (v2) — raw-data access or column data masking.
 *
 * Data policies have no labels, so Alchemy stamps ownership into the
 * policy id (`alch___…`) so `list` / `pnpm nuke:gcp` can find them.
 * `dataPolicyId` and `location` are identity — changing either replaces
 * the policy. Type, masking rule, grantees, and the data-governance tag
 * update in place. Patches send the observed etag.
 *
 * ### Creating a Data Policy
 * **Example:** Raw-data access
 * ```typescript
 * const policy = yield* GCP.BigQueryDataPolicy.DataPolicy("Raw", {
 *   dataPolicyType: "RAW_DATA_ACCESS_POLICY",
 * });
 * ```
 *
 * **Example:** SHA256 masking
 * ```typescript
 * const policy = yield* GCP.BigQueryDataPolicy.DataPolicy("Mask", {
 *   location: "us-central1",
 *   dataPolicyType: "DATA_MASKING_POLICY",
 *   dataMaskingPolicy: { predefinedExpression: "SHA256" },
 * });
 * ```
 *
 * ### Updating a Data Policy
 * Change props on the same logical id; the engine keeps the physical id.
 *
 * **Example:** Change the masking expression
 * ```typescript
 * const policy = yield* GCP.BigQueryDataPolicy.DataPolicy("Mask", {
 *   location: "us-central1",
 *   dataPolicyType: "DATA_MASKING_POLICY",
 *   dataMaskingPolicy: { predefinedExpression: "ALWAYS_NULL" },
 * });
 * ```
 *
 * @resource
 * @category BigQueryDataPolicy
 */
export const DataPolicy = Resource<DataPolicy>("GCP.BigQueryDataPolicy.DataPolicy");

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

const toMasking = (policy: bqdp.DataMaskingPolicy | undefined): DataMaskingPolicy | undefined => {
  if (policy === undefined) return undefined;
  const next = compact({
    predefinedExpression: policy.predefinedExpression,
    routine: policy.routine,
  });
  return Object.keys(next).length > 0 ? next : undefined;
};

const toGovernanceTag = (
  tag: bqdp.DataGovernanceTag | undefined,
): DataGovernanceTag | undefined => {
  if (tag === undefined) return undefined;
  const next = compact({ key: tag.key, value: tag.value });
  return Object.keys(next).length > 0 ? next : undefined;
};

const toAttrs = (policy: bqdp.DataPolicy, project: string, region: string) => {
  const name = policy.name ?? "";
  const parsed = parseName(name, project, region);
  return {
    name,
    dataPolicyId: policy.dataPolicyId ?? parsed.dataPolicyId,
    project,
    location: parsed.location,
    dataPolicyType: policy.dataPolicyType,
    dataMaskingPolicy: toMasking(policy.dataMaskingPolicy),
    grantees: sortedStrings(policy.grantees),
    dataGovernanceTag: toGovernanceTag(policy.dataGovernanceTag),
    policyTag: policy.policyTag,
    version: policy.version,
    etag: policy.etag,
  };
};

const getByName = (name: string) =>
  name.length === 0
    ? Effect.undefined
    : bqdp
        .getProjectsLocationsDataPolicies({ name })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listAt = (project: string, location: string) =>
  bqdp.listProjectsLocationsDataPolicies
    .pages({
      parent: parentOf(project, location),
      pageSize: 1000,
    })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.dataPolicies ?? [])),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("NotFound", () => Effect.succeed([] as bqdp.DataPolicy[])),
    );

const findOwned = (items: readonly bqdp.DataPolicy[], id: string, name?: string) =>
  Effect.gen(function* () {
    if (name !== undefined && name.length > 0) {
      const match = items.find((item) => item.name === name);
      if (match !== undefined) return match;
    }
    for (const item of items) {
      const resourceId = item.dataPolicyId ?? lastSegment(item.name ?? "");
      if (yield* ownedByAlchemy(id, resourceId)) return item;
    }
    return undefined;
  });

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 items = yield* listAt(project, location);
    return yield* findOwned(items, id, name);
  });

const toCreateBody = (news: DataPolicyProps, dataPolicyType: string) =>
  compact({
    dataPolicyType,
    dataMaskingPolicy: news.dataMaskingPolicy,
    grantees: news.grantees,
    dataGovernanceTag: news.dataGovernanceTag,
  });

const patchPolicy = (name: string, updateMask: string, body: bqdp.DataPolicy) =>
  Effect.gen(function* () {
    const latest = yield* getByName(name);
    if (latest === undefined) {
      return yield* new DataPolicyNotResolved({ resourceName: name });
    }
    return yield* bqdp.patchProjectsLocationsDataPolicies({
      name,
      updateMask,
      body: compact({
        ...body,
        etag: latest.etag,
      }),
    });
  }).pipe(
    Effect.retry({
      while: (error) => error._tag === "Conflict",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

export const DataPolicyProvider = () =>
  Provider.succeed(DataPolicy, {
    stables: ["name", "dataPolicyId", "project", "location"],

    diff: Effect.fn(function* ({ id, news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      const previousId = olds?.dataPolicyId ?? output?.dataPolicyId;
      const nextId = yield* toDataPolicyId(id, news.dataPolicyId, previousId);
      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
      if (
        (previousId === undefined || nextId === previousId) &&
        previousLocation === nextLocation
      ) {
        return undefined;
      }
      return {
        action: "replace" as const,
        deleteFirst: false,
      };
    }),

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

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const pages = yield* Effect.forEach(
          Array.from(new Set<string>([...LIST_LOCATIONS, env.region])),
          (location) => listAt(env.project, location),
          { concurrency: 4 },
        );
        const byName = new Map<string, ReturnType<typeof toAttrs>>();
        for (const item of pages.flat()) {
          const resourceId = item.dataPolicyId ?? lastSegment(item.name ?? "");
          if (!hasOwnershipMarker(resourceId)) continue;
          const attrs = toAttrs(item, env.project, env.region);
          if (attrs.name.length > 0) byName.set(attrs.name, attrs);
        }
        return Array.from(byName.values());
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const dataPolicyId = yield* toDataPolicyId(id, news.dataPolicyId, output?.dataPolicyId);
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const parent = parentOf(env.project, location);
      const name = output?.name ?? resourceNameOf(env.project, location, dataPolicyId);
      const dataPolicyType = normalizePolicyType(news.dataPolicyType ?? output?.dataPolicyType);

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

      if (current === undefined) {
        const created = yield* bqdp
          .createProjectsLocationsDataPolicies({
            parent,
            body: {
              dataPolicyId,
              dataPolicy: toCreateBody(news, dataPolicyType),
            },
          })
          .pipe(Effect.catchTag("Conflict", () => observe(id, name, env.project, location)));
        current = created ?? undefined;
      }

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

      const currentName = current.name ?? name;
      const desiredType = normalizePolicyType(news.dataPolicyType ?? current.dataPolicyType);
      const observedType = normalizePolicyType(current.dataPolicyType);
      const typeChanged = !sameText(observedType, desiredType);
      const maskingChanged =
        news.dataMaskingPolicy !== undefined &&
        !sameJson(toMasking(current.dataMaskingPolicy), news.dataMaskingPolicy);
      const granteesChanged =
        news.grantees !== undefined && !sameStringList(current.grantees, news.grantees);
      const tagChanged =
        news.dataGovernanceTag !== undefined &&
        !sameJson(toGovernanceTag(current.dataGovernanceTag), news.dataGovernanceTag);

      const updateMask = updateMaskOf(
        typeChanged ? "dataPolicyType" : undefined,
        maskingChanged ? "dataMaskingPolicy" : undefined,
        granteesChanged ? "grantees" : undefined,
        tagChanged ? "dataGovernanceTag" : undefined,
      );

      if (updateMask.length > 0) {
        current = yield* patchPolicy(
          currentName,
          updateMask,
          compact({
            dataPolicyType: typeChanged ? desiredType : undefined,
            dataMaskingPolicy: maskingChanged ? news.dataMaskingPolicy : undefined,
            grantees: granteesChanged ? news.grantees : undefined,
            dataGovernanceTag: tagChanged ? news.dataGovernanceTag : undefined,
          }),
        );
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* bqdp
        .deleteProjectsLocationsDataPolicies({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });