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

import * as resourcemanager from "@distilled.cloud/gcp/cloudresourcemanager_v3";
import { Unowned } from "alchemy/AdoptPolicy";
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 type { Providers } from "../Providers.ts";
import {
  FOLDER_DISPLAY_MAX,
  collectPages,
  isDeleteRequested,
  resolveParent,
  resourceNameFromOperation,
  sameHierarchyParent,
  waitForOperation,
  waitForCreate,
} from "./internal.ts";

export type FolderProps = {
  /**
   * User-visible display name. Unique among sibling folders. 1-30
   * characters, starting and ending with a letter or digit. If omitted,
   * a unique name is generated from the stack, stage, and logical id.
   */
  displayName?: string;
  /**
   * Parent `organizations/{org}` or `folders/{folder}`. Defaults to the
   * current project's parent. Changing parent moves the folder.
   */
  parent?: string;
};

export type Folder = Resource<
  "GCP.ResourceManager.Folder",
  FolderProps,
  {
    /** Resource name `folders/{folder_id}`. */
    name: string;
    /** User-visible display name as stored in Cloud Resource Manager. */
    displayName: string;
    /** Parent `organizations/{org}` or `folders/{folder}`. */
    parent: string;
    /** Lifecycle state (`ACTIVE` or `DELETE_REQUESTED`). */
    state: string | undefined;
    /** Server etag for optimistic concurrency. */
    etag: string | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
    /** RFC3339 time a delete was requested, if any. */
    deleteTime: string | undefined;
    /** Configured folder capabilities, if any. */
    configuredCapabilities: string[];
    /** Management project when app-management is enabled. */
    managementProject: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Resource Manager folder — a node in an organization's resource
 * hierarchy used to group projects and other folders.
 *
 * Folders have no labels, so a folder found without prior state is
 * reported as unowned and only taken over with `--adopt`. `displayName`
 * updates in place; changing `parent` moves the folder. Delete is a 30-day
 * soft-delete (`DELETE_REQUESTED`).
 *
 * ### Creating a Folder
 * **Example:** Generated display name under the current project's parent
 * ```typescript
 * const folder = yield* GCP.ResourceManager.Folder("Team", {});
 * ```
 *
 * **Example:** Explicit display name and parent
 * ```typescript
 * const folder = yield* GCP.ResourceManager.Folder("Team", {
 *   displayName: "platform",
 *   parent: "organizations/123456789",
 * });
 * ```
 *
 * ### Updating a Folder
 * **Example:** Rename
 * ```typescript
 * const folder = yield* GCP.ResourceManager.Folder("Team", {
 *   displayName: "platform-prod",
 * });
 * ```
 *
 * @resource
 * @category ResourceManager
 */
export const Folder = Resource<Folder>("GCP.ResourceManager.Folder");

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

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

const sanitizeDisplayName = (value: string) => {
  let next = value
    .replace(/[^a-zA-Z0-9_ -]/g, "-")
    .replace(/\s+/g, " ")
    .trim();
  if (next.length > FOLDER_DISPLAY_MAX) {
    next = next.slice(0, FOLDER_DISPLAY_MAX);
  }
  if (!/^[a-zA-Z0-9]/.test(next)) next = `a${next}`.slice(0, FOLDER_DISPLAY_MAX);
  next = next.replace(/[^a-zA-Z0-9]+$/g, "");
  if (next.length === 0) next = "az0";
  return next;
};

const toDisplayName = (id: string, displayName: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (displayName !== undefined) return sanitizeDisplayName(displayName);
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: FOLDER_DISPLAY_MAX,
      lowercase: true,
      suffixLength: 8,
    });
    return sanitizeDisplayName(generated);
  });

const toAttrs = (folder: resourcemanager.Folder) => ({
  name: folder.name ?? "",
  displayName: folder.displayName ?? "",
  parent: folder.parent ?? "",
  state: folder.state,
  etag: folder.etag,
  createTime: folder.createTime,
  updateTime: folder.updateTime,
  deleteTime: folder.deleteTime,
  configuredCapabilities: folder.configuredCapabilities ?? [],
  managementProject: folder.managementProject,
});

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

const listChildren = (parent: string, showDeleted = true) =>
  collectPages(
    resourcemanager.listFolders.pages({
      parent,
      pageSize: 300,
      showDeleted,
    }),
    (page) => page.folders,
  ).pipe(Effect.catchTag("NotFound", () => Effect.succeed([] as resourcemanager.Folder[])));

const findByDisplayName = (parent: string, displayName: string, resourceName?: string) =>
  Effect.gen(function* () {
    if (resourceName !== undefined && resourceName.length > 0) {
      const byName = yield* getByName(resourceName);
      if (byName !== undefined) return byName;
    }
    const children = yield* listChildren(parent, true);
    return children.find((folder) => folder.displayName === displayName);
  });

const observe = (resourceName: string | undefined, parent: string, displayName: string) =>
  Effect.gen(function* () {
    if (resourceName !== undefined && resourceName.length > 0) {
      const byName = yield* getByName(resourceName);
      if (byName !== undefined) return byName;
    }
    return yield* findByDisplayName(parent, displayName, resourceName);
  });

const waitUntilExists = (resourceName: string | undefined, parent: string, displayName: string) =>
  observe(resourceName, parent, displayName).pipe(
    Effect.filterOrFail(
      (folder): folder is resourcemanager.Folder => folder !== undefined,
      () =>
        new FolderNotResolved({
          resourceName: resourceName ?? `${parent}/${displayName}`,
        }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.ResourceManager.FolderNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

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

const ensureActive = (folder: resourcemanager.Folder) =>
  Effect.gen(function* () {
    if (!isDeleteRequested(folder.state) || folder.name === undefined) {
      return folder;
    }
    const operation = yield* resourcemanager.undeleteFolders({
      name: folder.name,
      body: {},
    });
    yield* waitForOperation(operation);
    return (
      (yield* waitUntilExists(folder.name, folder.parent ?? "", folder.displayName ?? "")) ?? folder
    );
  });

export const FolderProvider = () =>
  Provider.succeed(Folder, {
    stables: ["name", "createTime"],

    read: Effect.fn(function* ({ id, olds, output }) {
      const displayName = yield* toDisplayName(id, olds?.displayName, output?.displayName);
      const parent = yield* resolveParent(olds?.parent, output?.parent).pipe(
        Effect.catchTag("GCP.ResourceManager.ParentRequired", () =>
          Effect.succeed(output?.parent ?? ""),
        ),
      );
      if (parent.length === 0 && output?.name === undefined) return undefined;
      const existing = yield* observe(output?.name, parent || (output?.parent ?? ""), displayName);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing);
      // 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 displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
      const parent = yield* resolveParent(news.parent, output?.parent);

      let current = yield* observe(output?.name, parent, displayName);

      if (current === undefined) {
        const created = yield* resourcemanager
          .createFolders({
            body: {
              parent,
              displayName,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          const settled = yield* waitForCreate(created);
          current = yield* waitUntilExists(
            resourceNameFromOperation(settled, "folders/") ??
              resourceNameFromOperation(created, "folders/"),
            parent,
            displayName,
          );
        } else {
          current = yield* waitUntilExists(undefined, parent, displayName);
        }
      }

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

      const name = current.name;
      current = yield* ensureActive(current);

      if ((current.displayName ?? "") !== displayName) {
        const operation = yield* resourcemanager.patchFolders({
          name: current.name ?? name,
          updateMask: "displayName",
          body: {
            name: current.name ?? name,
            displayName,
            etag: current.etag,
          },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilExists(current.name ?? name, parent, displayName);
      }

      if (current.parent !== undefined && !sameHierarchyParent(current.parent, parent)) {
        const operation = yield* resourcemanager.moveFolders({
          name: current.name ?? name,
          body: { destinationParent: parent },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilExists(current.name ?? name, parent, displayName);
      }

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

      return toAttrs(current);
    }),

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