sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ ResourceManager/ Lien.ts

import * as resourcemanager from "@distilled.cloud/gcp/cloudresourcemanager_v3";
import { unownedUnlessPrevious } 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 {
  DEFAULT_LIEN_ORIGIN,
  DEFAULT_LIEN_RESTRICTIONS,
  LIEN_ORIGIN_MAX,
  LIEN_REASON_MAX,
  collectPages,
  projectNumberOf,
  projectParent,
  sameStringList,
} from "./internal.ts";

export type LienProps = {
  /**
   * Resource this lien attaches to, e.g. `projects/{project}`. Defaults
   * to the current project (numeric form). Immutable — changing it
   * replaces the lien.
   */
  parent?: string;
  /**
   * Origin of the lien (max 200 characters). Programmatic identifier
   * for the system that created it.
   * @default "alchemy.effect"
   */
  origin?: string;
  /**
   * User-visible reason the restriction exists (max 200 characters).
   * @default "Protected by a lien."
   */
  reason?: string;
  /**
   * IAM permissions this lien blocks. An empty list is rejected.
   * @default ["resourcemanager.projects.delete"]
   */
  restrictions?: string[];
};

export type Lien = Resource<
  "GCP.ResourceManager.Lien",
  LienProps,
  {
    /** Resource name `liens/{lien_id}`. */
    name: string;
    /** Parent resource this lien is attached to. */
    parent: string;
    /** Origin identifier. */
    origin: string;
    /** Reason shown when a restricted operation is refused. */
    reason: string | undefined;
    /** Blocked IAM permissions. */
    restrictions: string[];
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** Project id used to default `parent`. */
    project: string;
  },
  never,
  Providers
>;

/**
 * A Cloud Resource Manager lien — an encumbrance that blocks selected
 * operations on a project (most commonly project deletion).
 *
 * Liens have no update API, id, or labels: the lien on `parent` with the
 * same origin, reason, and restrictions is the managed one, and `list` /
 * `pnpm nuke:gcp` return liens whose `origin` is `alchemy.effect`. Changing `parent`,
 * `origin`, `reason`, or `restrictions` replaces the lien (delete-first).
 *
 * ### Creating a Lien
 * **Example:** Block deletion of the current project
 * ```typescript
 * const lien = yield* GCP.ResourceManager.Lien("Hold", {
 *   reason: "production API key",
 * });
 * ```
 *
 * **Example:** Explicit parent and restrictions
 * ```typescript
 * const lien = yield* GCP.ResourceManager.Lien("Hold", {
 *   parent: "projects/123456789",
 *   origin: "alchemy.effect",
 *   reason: "holds billing export",
 *   restrictions: ["resourcemanager.projects.delete"],
 * });
 * ```
 *
 * @resource
 * @category ResourceManager
 */
export const Lien = Resource<Lien>("GCP.ResourceManager.Lien");

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

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

const unique = (values: string[]) => [...new Set(values.filter((value) => value.length > 0))];

const parentAliases = (parent: string, project: string, projectNumber: string) => {
  const normalized = projectParent(parent);
  if (!normalized.startsWith("projects/")) return [normalized];
  return unique([normalized, `projects/${project}`, `projects/${projectNumber}`]);
};

const sameParent = (left: string, right: string, project: string, projectNumber: string) => {
  const aliases = new Set(parentAliases(left, project, projectNumber));
  return parentAliases(right, project, projectNumber).some((alias) => aliases.has(alias));
};

const restrictionsOf = (values: readonly string[] | undefined) => {
  const next = [...(values ?? DEFAULT_LIEN_RESTRICTIONS)].filter((value) => value.length > 0);
  return next.length > 0 ? next : [...DEFAULT_LIEN_RESTRICTIONS];
};

const originOf = (origin: string | undefined) => {
  const next = (origin ?? DEFAULT_LIEN_ORIGIN).trim();
  return next.length > 0 ? next.slice(0, LIEN_ORIGIN_MAX) : DEFAULT_LIEN_ORIGIN;
};

const toAttrs = (lien: resourcemanager.Lien, project: string) => ({
  name: lien.name ?? "",
  parent: lien.parent ?? "",
  origin: lien.origin ?? DEFAULT_LIEN_ORIGIN,
  reason: lien.reason,
  restrictions: lien.restrictions ?? [],
  createTime: lien.createTime,
  project,
});

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

const listOnParent = (parent: string) =>
  collectPages(
    resourcemanager.listLiens.pages({
      parent,
      pageSize: 300,
    }),
    (page) => page.liens,
  ).pipe(Effect.catchTag("NotFound", () => Effect.succeed([] as resourcemanager.Lien[])));

const listOnParents = (parents: string[]) =>
  Effect.gen(function* () {
    const pages = yield* Effect.forEach(parents, listOnParent, {
      concurrency: 2,
    });
    const byName = new Map<string, resourcemanager.Lien>();
    for (const lien of pages.flat()) {
      if (lien.name) byName.set(lien.name, lien);
    }
    return [...byName.values()];
  });

const matchesDesired = (
  lien: resourcemanager.Lien,
  parent: string,
  origin: string,
  reason: string,
  restrictions: readonly string[],
  project: string,
  projectNumber: string,
) =>
  sameParent(lien.parent ?? "", parent, project, projectNumber) &&
  (lien.origin ?? "") === origin &&
  (lien.reason ?? "") === reason &&
  sameStringList(lien.restrictions, restrictions);

const DEFAULT_REASON = "Protected by a lien.";

const reasonOf = (reason: string | undefined) =>
  (reason ?? DEFAULT_REASON).slice(0, LIEN_REASON_MAX);

/**
 * Liens have no user-chosen id or labels: a lien on the parent with the
 * same origin, reason, and restrictions is the one this resource manages.
 */
const findMatching = (
  parent: string,
  origin: string,
  reason: string,
  restrictions: readonly string[],
  project: string,
  projectNumber: string,
  resourceName?: string,
) =>
  Effect.gen(function* () {
    if (resourceName !== undefined && resourceName.length > 0) {
      const byName = yield* getByName(resourceName);
      if (byName !== undefined) return byName;
    }
    const liens = yield* listOnParents(parentAliases(parent, project, projectNumber));
    return liens.find((lien) =>
      matchesDesired(lien, parent, origin, reason, restrictions, project, projectNumber),
    );
  });

const waitUntilExists = (
  parent: string,
  origin: string,
  reason: string,
  restrictions: readonly string[],
  project: string,
  projectNumber: string,
) =>
  findMatching(parent, origin, reason, restrictions, project, projectNumber).pipe(
    Effect.filterOrFail(
      (lien): lien is resourcemanager.Lien => lien !== undefined,
      () => new LienNotResolved({ resourceName: parent }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.ResourceManager.LienNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((lien) =>
      lien === undefined ? Effect.void : Effect.fail(new LienStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.ResourceManager.LienStillExists",
      times: 10,
      schedule: Schedule.spaced("1 second"),
    }),
  );

export const LienProvider = () =>
  Provider.succeed(Lien, {
    stables: ["name", "parent", "origin", "createTime", "project"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      const projectNumber = yield* projectNumberOf(env.project);
      const previousParent = olds?.parent ?? output?.parent;
      const nextParent = projectParent(news.parent ?? previousParent ?? env.project);
      const parentChanged =
        previousParent !== undefined &&
        !sameParent(previousParent, nextParent, env.project, projectNumber);

      const previousOrigin = originOf(olds?.origin ?? output?.origin);
      const originChanged = news.origin !== undefined && originOf(news.origin) !== previousOrigin;

      const previousRestrictions = restrictionsOf(olds?.restrictions ?? output?.restrictions);
      const restrictionsChanged =
        news.restrictions !== undefined && !sameStringList(news.restrictions, previousRestrictions);

      const previousReason = olds?.reason ?? output?.reason;
      const reasonChanged = news.reason !== undefined && news.reason !== previousReason;

      if (!parentChanged && !originChanged && !restrictionsChanged && !reasonChanged) {
        return undefined;
      }
      return { action: "replace" as const, deleteFirst: true };
    }),

    read: Effect.fn(function* ({ olds, output, previous }) {
      const env = yield* GcpEnvironment.current;
      const projectNumber = yield* projectNumberOf(env.project);
      const parent = projectParent(output?.parent ?? olds?.parent ?? `projects/${projectNumber}`);
      const existing = yield* findMatching(
        parent,
        originOf(olds?.origin ?? output?.origin),
        reasonOf(olds?.reason ?? output?.reason),
        restrictionsOf(olds?.restrictions ?? output?.restrictions),
        env.project,
        projectNumber,
        output?.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 : unownedUnlessPrevious(attrs, previous, "name");
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const projectNumber = yield* projectNumberOf(env.project);
        const liens = yield* listOnParents(
          parentAliases(`projects/${projectNumber}`, env.project, projectNumber),
        );
        // `origin` identifies the system that placed a lien.
        return liens
          .filter((lien) => lien.origin === DEFAULT_LIEN_ORIGIN)
          .map((lien) => toAttrs(lien, env.project));
      }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const env = yield* GcpEnvironment.current;
      const projectNumber = yield* projectNumberOf(env.project);
      const parent = projectParent(news.parent ?? output?.parent ?? `projects/${projectNumber}`);
      const origin = originOf(news.origin);
      const restrictions = restrictionsOf(news.restrictions);
      const reason = reasonOf(news.reason);

      let current = yield* findMatching(
        parent,
        origin,
        reason,
        restrictions,
        env.project,
        projectNumber,
        output?.name,
      );

      if (
        current !== undefined &&
        !matchesDesired(current, parent, origin, reason, restrictions, env.project, projectNumber)
      ) {
        if (current.name !== undefined) {
          yield* resourcemanager
            .deleteLiens({ name: current.name })
            .pipe(Effect.catchTag("NotFound", () => Effect.void));
          yield* waitUntilGone(current.name);
        }
        current = undefined;
      }

      if (current === undefined) {
        const created = yield* resourcemanager
          .createLiens({
            body: {
              parent,
              origin,
              reason,
              restrictions,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined && created.name !== undefined) {
          current = created;
        } else {
          current = yield* waitUntilExists(
            parent,
            origin,
            reason,
            restrictions,
            env.project,
            projectNumber,
          );
        }
      }

      if (current === undefined || current.name === undefined) {
        return yield* new LienNotResolved({ resourceName: parent });
      }

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

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