sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Compute/ InstanceGroupManager.ts

import * as compute from "@distilled.cloud/gcp/compute_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 * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import { waitZoneOperation } from "./operations.ts";

export type InstanceGroupManagerNamedPort = {
  /** RFC1035 name for this port mapping (e.g. `"http"`). */
  name: string;
  /** TCP port number (`1`–`65535`). */
  port: number;
};

export type InstanceGroupManagerAutoHealingPolicy = {
  /**
   * Health check URL or name. Names expand to
   * `projects/{project}/global/healthChecks/{name}`.
   */
  healthCheck: string;
  /**
   * Seconds to ignore failed health checks after a VM is created
   * (`0`–`3600`).
   * @default 0
   */
  initialDelaySec?: number;
};

export type InstanceGroupManagerUpdatePolicy = compute.InstanceGroupManagerUpdatePolicy;

export type InstanceGroupManagerProps = {
  /**
   * Name of the managed instance group. Must be 1–63 characters and comply
   * with RFC1035. If omitted, a unique name is generated from the stack,
   * stage, and logical id. Changing this replaces the group.
   */
  managerName?: string;
  /**
   * Zone of the group (e.g. `"us-central1-a"`). Immutable — changing it
   * replaces the group.
   * @default "us-central1-a"
   */
  zone?: string;
  /**
   * Instance template URL or name used to create VMs. Names expand to
   * `projects/{project}/global/instanceTemplates/{name}`.
   */
  instanceTemplate: string;
  /**
   * Target number of running VMs. `0` creates an empty group.
   * @default 0
   */
  targetSize?: number;
  /**
   * Prefix for VM names (RFC1035, max 58 characters). Defaults to the
   * manager name. Immutable — changing it replaces the group.
   */
  baseInstanceName?: string;
  /**
   * Optional description. Managed instance groups have no labels API, so
   * Alchemy stamps ownership (`alchemy-stack` / `alchemy-stage` /
   * `alchemy-id`) into this field for `list` / nuke.
   */
  description?: string;
  /**
   * Named ports applied to the complementary instance group (the manager
   * field is output-only; updates use `instanceGroups.setNamedPorts`).
   */
  namedPorts?: InstanceGroupManagerNamedPort[];
  /**
   * Autohealing policy (one health check). Omit to leave the observed
   * policy unchanged.
   */
  autoHealingPolicies?: InstanceGroupManagerAutoHealingPolicy[];
  /**
   * Rolling-update policy. Omit to leave the observed policy unchanged.
   */
  updatePolicy?: InstanceGroupManagerUpdatePolicy;
  /**
   * Target-pool URLs or names that receive the group's VMs. Omit to leave
   * observed pools unchanged.
   */
  targetPools?: string[];
  /**
   * Repair / failure policy for managed VMs (e.g.
   * `{ defaultActionOnFailure: "DO_NOTHING" }`, which resize requests
   * require). Omit to leave the observed policy unchanged.
   */
  instanceLifecyclePolicy?: compute.InstanceGroupManagerInstanceLifecyclePolicy;
};

export type InstanceGroupManager = Resource<
  "GCP.Compute.InstanceGroupManager",
  InstanceGroupManagerProps,
  {
    /** Managed instance group name. */
    managerName: string;
    /** Zone (short name, e.g. `"us-central1-a"`). */
    zone: string;
    /** Project id. */
    project: string;
    /** Instance template URL. */
    instanceTemplate: string | undefined;
    /** Target number of running VMs. */
    targetSize: number;
    /** Prefix used for VM names. */
    baseInstanceName: string | undefined;
    /** User-facing description (ownership marker stripped). */
    description: string | undefined;
    /** Named ports currently configured on the group. */
    namedPorts: InstanceGroupManagerNamedPort[];
    /** Complementary unmanaged instance group URL. */
    instanceGroup: string | undefined;
    /** Whether the group is currently stable. */
    isStable: boolean | undefined;
    /** Server-generated resource URL. */
    selfLink: string | undefined;
    /** Server-generated numeric id. */
    id: string | undefined;
    /** RFC3339 creation timestamp. */
    creationTimestamp: string | undefined;
  },
  never,
  Providers
>;

/**
 * A zonal Compute Engine managed instance group (MIG).
 *
 * The group creates VMs from an instance template and maintains
 * `targetSize`. Alchemy records ownership in the description so
 * `list` / `pnpm nuke:gcp` can find groups (MIGs have no labels API).
 * Changing `managerName`, `zone`, or `baseInstanceName` replaces the
 * group.
 *
 * ### Creating a Managed Instance Group
 * **Example:** Generated name, empty group
 * ```typescript
 * const template = yield* GCP.Compute.InstanceTemplate("web", {});
 * const group = yield* GCP.Compute.InstanceGroupManager("web", {
 *   instanceTemplate: template.templateName,
 * });
 * ```
 *
 * **Example:** Named ports and target size
 * ```typescript
 * const template = yield* GCP.Compute.InstanceTemplate("web", {});
 * const group = yield* GCP.Compute.InstanceGroupManager("web", {
 *   managerName: "web-mig",
 *   zone: "us-central1-a",
 *   instanceTemplate: template.templateName,
 *   targetSize: 2,
 *   namedPorts: [{ name: "http", port: 80 }],
 * });
 * ```
 *
 * @resource
 * @category Compute
 */
export const InstanceGroupManager = Resource<InstanceGroupManager>(
  "GCP.Compute.InstanceGroupManager",
);

export class InstanceGroupManagerNotResolved extends Data.TaggedError(
  "GCP.Compute.InstanceGroupManagerNotResolved",
)<{
  managerName: string;
  zone: string;
}> {}

export class InstanceGroupManagerStillExists extends Data.TaggedError(
  "GCP.Compute.InstanceGroupManagerStillExists",
)<{
  managerName: string;
  zone: string;
}> {}

const DEFAULT_ZONE = "us-central1-a";
const DEFAULT_TARGET_SIZE = 0;
const MAX_NAME_LENGTH = 63;
const MAX_BASE_NAME_LENGTH = 58;

const lastSegment = (value: string | undefined) => {
  if (value === undefined || value.length === 0) return "";
  const parts = value.split("/").filter((part) => part.length > 0);
  return parts[parts.length - 1] ?? value;
};

const rfc1035Name = (name: string, maxLength = MAX_NAME_LENGTH) => {
  let next = name
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (!/^[a-z]/.test(next)) {
    next = `m${next}`;
  }
  next = next.slice(0, maxLength).replace(/-+$/g, "");
  return next.length > 0 ? next : "mig";
};

const toName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return rfc1035Name(
      name ??
        existing ??
        (yield* createPhysicalName({
          id,
          maxLength: MAX_NAME_LENGTH,
          lowercase: true,
        })),
    );
  });

const toBaseInstanceName = (managerName: string, explicit?: string) =>
  rfc1035Name(explicit ?? managerName, MAX_BASE_NAME_LENGTH);

const encodeDescription = (user: string | undefined, labels: Record<string, string>) => {
  const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
  const trimmed = user?.trim();
  return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
};

const parseDescription = (description: string | undefined) => {
  if (!description?.startsWith("[alchemy ")) {
    return { user: description, labels: {} as Record<string, string> };
  }
  const end = description.indexOf("]");
  if (end < 0) {
    return { user: description, labels: {} as Record<string, string> };
  }
  const labels: Record<string, string> = {};
  for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
    const eq = part.indexOf("=");
    if (eq > 0) {
      labels[part.slice(0, eq)] = part.slice(eq + 1);
    }
  }
  const rest = description
    .slice(end + 1)
    .replace(/^\n/, "")
    .trim();
  return {
    user: rest.length > 0 ? rest : undefined,
    labels,
  };
};

const hasOwnershipMarker = (description: string | undefined) =>
  Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));

const toTemplateUrl = (project: string, template: string) =>
  template.includes("/") ? template : `projects/${project}/global/instanceTemplates/${template}`;

const toHealthCheckUrl = (project: string, healthCheck: string) =>
  healthCheck.includes("/")
    ? healthCheck
    : `projects/${project}/global/healthChecks/${healthCheck}`;

const toTargetPoolUrl = (project: string, zone: string, pool: string) => {
  if (pool.includes("/")) return pool;
  const region = zone.slice(0, zone.lastIndexOf("-"));
  return `projects/${project}/regions/${region}/targetPools/${pool}`;
};

const canonPorts = (
  ports: readonly InstanceGroupManagerNamedPort[] | undefined,
): InstanceGroupManagerNamedPort[] =>
  [...(ports ?? [])]
    .map((port) => ({ name: port.name, port: port.port }))
    .sort((a, b) => a.name.localeCompare(b.name) || a.port - b.port);

const samePorts = (
  left: readonly InstanceGroupManagerNamedPort[] | undefined,
  right: readonly InstanceGroupManagerNamedPort[] | undefined,
) => JSON.stringify(canonPorts(left)) === JSON.stringify(canonPorts(right));

const fromApiPorts = (
  ports: readonly compute.NamedPort[] | undefined,
): InstanceGroupManagerNamedPort[] =>
  canonPorts(
    (ports ?? [])
      .filter(
        (port): port is { name: string; port: number } =>
          typeof port.name === "string" && typeof port.port === "number",
      )
      .map((port) => ({ name: port.name, port: port.port })),
  );

const sameSegments = (
  left: readonly string[] | undefined,
  right: readonly string[] | undefined,
) => {
  const a = [...(left ?? [])].map(lastSegment).sort();
  const b = [...(right ?? [])].map(lastSegment).sort();
  return a.length === b.length && a.every((value, index) => value === b[index]);
};

const toHealing = (
  project: string,
  policies: readonly InstanceGroupManagerAutoHealingPolicy[],
): compute.InstanceGroupManagerAutoHealingPolicy[] =>
  policies.map((policy) => ({
    healthCheck: toHealthCheckUrl(project, policy.healthCheck),
    initialDelaySec: policy.initialDelaySec,
  }));

const fromApiHealing = (
  policies: readonly compute.InstanceGroupManagerAutoHealingPolicy[] | undefined,
): InstanceGroupManagerAutoHealingPolicy[] =>
  (policies ?? [])
    .filter(
      (policy): policy is { healthCheck: string } & typeof policy =>
        typeof policy.healthCheck === "string",
    )
    .map((policy) => ({
      healthCheck: policy.healthCheck,
      initialDelaySec: policy.initialDelaySec,
    }));

const sameHealing = (
  left: readonly { healthCheck?: string; initialDelaySec?: number }[] | undefined,
  right: readonly { healthCheck?: string; initialDelaySec?: number }[] | undefined,
) => {
  const canon = (policies: readonly { healthCheck?: string; initialDelaySec?: number }[]) =>
    [...policies]
      .map((policy) => ({
        healthCheck: lastSegment(policy.healthCheck ?? ""),
        initialDelaySec: policy.initialDelaySec ?? 0,
      }))
      .sort((a, b) => a.healthCheck.localeCompare(b.healthCheck));
  return JSON.stringify(canon(left ?? [])) === JSON.stringify(canon(right ?? []));
};

const sameUpdatePolicy = (
  left: compute.InstanceGroupManagerUpdatePolicy | undefined,
  right: compute.InstanceGroupManagerUpdatePolicy | undefined,
) => JSON.stringify(left ?? {}) === JSON.stringify(right ?? {});

const toAttrs = (manager: compute.InstanceGroupManager, project: string) => {
  const { user } = parseDescription(manager.description);
  return {
    managerName: manager.name ?? lastSegment(manager.selfLink),
    zone: lastSegment(manager.zone) || DEFAULT_ZONE,
    project,
    instanceTemplate: manager.instanceTemplate,
    targetSize: manager.targetSize ?? DEFAULT_TARGET_SIZE,
    baseInstanceName: manager.baseInstanceName,
    description: user,
    namedPorts: fromApiPorts(manager.namedPorts),
    instanceGroup: manager.instanceGroup,
    isStable: manager.status?.isStable,
    selfLink: manager.selfLink,
    id: manager.id,
    creationTimestamp: manager.creationTimestamp,
  };
};

const getByName = (project: string, zone: string, instanceGroupManager: string) =>
  compute
    .getInstanceGroupManagers({ project, zone, instanceGroupManager })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const waitGone = (project: string, zone: string, managerName: string) =>
  getByName(project, zone, managerName).pipe(
    Effect.flatMap((manager) =>
      manager === undefined
        ? Effect.void
        : Effect.fail(new InstanceGroupManagerStillExists({ managerName, zone })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.InstanceGroupManagerStillExists",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const waitPresent = (project: string, zone: string, managerName: string) =>
  getByName(project, zone, managerName).pipe(
    Effect.flatMap((manager) =>
      manager === undefined
        ? Effect.fail(new InstanceGroupManagerNotResolved({ managerName, zone }))
        : Effect.succeed(manager),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.InstanceGroupManagerNotResolved",
      times: 8,
      schedule: Schedule.exponential("250 millis"),
    }),
    Effect.catchTag("GCP.Compute.InstanceGroupManagerNotResolved", () => Effect.undefined),
  );

const runOp = <E, R>(
  project: string,
  zone: string,
  start: Effect.Effect<compute.Operation, E, R>,
) =>
  start.pipe(
    Effect.flatMap((operation) =>
      waitZoneOperation(project, zone, operation, {
        ignore: ["RESOURCE_ALREADY_EXISTS"],
      }),
    ),
  );

const syncNamedPorts = (
  project: string,
  zone: string,
  instanceGroupUrl: string | undefined,
  namedPorts: InstanceGroupManagerNamedPort[],
) =>
  Effect.gen(function* () {
    const instanceGroup = lastSegment(instanceGroupUrl);
    if (instanceGroup.length === 0) return;
    const group = yield* compute
      .getInstanceGroups({ project, zone, instanceGroup })
      .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
    if (group === undefined) return;
    if (samePorts(fromApiPorts(group.namedPorts), namedPorts)) return;
    yield* runOp(
      project,
      zone,
      compute.setNamedPortsInstanceGroups({
        project,
        zone,
        instanceGroup,
        body: {
          namedPorts,
          fingerprint: group.fingerprint,
        },
      }),
    ).pipe(
      Effect.retry({
        while: (error) => error._tag === "Conflict",
        times: 5,
        schedule: Schedule.exponential("250 millis"),
      }),
    );
  });

export const InstanceGroupManagerProvider = () =>
  Provider.succeed(InstanceGroupManager, {
    stables: [
      "managerName",
      "zone",
      "project",
      "baseInstanceName",
      "id",
      "selfLink",
      "instanceGroup",
      "creationTimestamp",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousName = olds?.managerName ?? output?.managerName;
      const nextName = news.managerName ?? previousName;
      const previousZone = lastSegment(olds?.zone ?? output?.zone);
      const nextZone = lastSegment(news.zone ?? DEFAULT_ZONE);
      const previousBase = olds?.baseInstanceName ?? output?.baseInstanceName;
      const nextBase =
        news.baseInstanceName !== undefined
          ? toBaseInstanceName(nextName ?? news.baseInstanceName, news.baseInstanceName)
          : previousBase;
      const nameChanged =
        previousName !== undefined && nextName !== undefined && previousName !== nextName;
      const zoneChanged = previousZone.length > 0 && previousZone !== nextZone;
      const baseChanged =
        previousBase !== undefined &&
        nextBase !== undefined &&
        lastSegment(previousBase) !== lastSegment(nextBase);
      if (!nameChanged && !zoneChanged && !baseChanged) {
        return undefined;
      }
      return {
        action: "replace" as const,
        deleteFirst:
          previousName !== undefined &&
          nextName !== undefined &&
          previousName === nextName &&
          previousZone === nextZone,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const managerName = yield* toName(id, olds?.managerName, output?.managerName);
      const zone = lastSegment(olds?.zone ?? output?.zone ?? DEFAULT_ZONE);
      const existing = yield* getByName(env.project, zone, managerName);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      const { labels } = parseDescription(existing.description);
      return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const pages = yield* compute.aggregatedListInstanceGroupManagers
          .pages({
            project: env.project,
            maxResults: 500,
            returnPartialSuccess: true,
          })
          .pipe(Stream.runCollect);
        return Array.from(pages).flatMap((page) =>
          Object.entries(page.items ?? {}).flatMap(([scope, scoped]) => {
            if (!scope.startsWith("zones/")) return [];
            return (scoped?.instanceGroupManagers ?? [])
              .filter((manager) => hasOwnershipMarker(manager.description))
              .map((manager) => toAttrs(manager, env.project));
          }),
        );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const managerName = yield* toName(id, news.managerName, output?.managerName);
      const zone = lastSegment(news.zone ?? output?.zone ?? DEFAULT_ZONE);
      const instanceTemplate = toTemplateUrl(env.project, news.instanceTemplate);
      const targetSize = news.targetSize ?? DEFAULT_TARGET_SIZE;
      const baseInstanceName = toBaseInstanceName(
        managerName,
        news.baseInstanceName ?? output?.baseInstanceName,
      );
      const namedPorts = canonPorts(news.namedPorts);
      const desiredLabels = yield* createInternalLabels(id);
      const description = encodeDescription(news.description, desiredLabels);

      let current = yield* getByName(env.project, zone, managerName);

      if (current === undefined) {
        yield* compute
          .insertInstanceGroupManagers({
            project: env.project,
            zone,
            body: {
              name: managerName,
              description,
              instanceTemplate,
              baseInstanceName,
              targetSize,
              namedPorts: namedPorts.length > 0 ? namedPorts : undefined,
              autoHealingPolicies:
                news.autoHealingPolicies !== undefined
                  ? toHealing(env.project, news.autoHealingPolicies)
                  : undefined,
              updatePolicy: news.updatePolicy,
              targetPools:
                news.targetPools !== undefined
                  ? news.targetPools.map((pool) => toTargetPoolUrl(env.project, zone, pool))
                  : undefined,
              instanceLifecyclePolicy: news.instanceLifecyclePolicy,
            },
          })
          .pipe(
            Effect.catchTag("Conflict", () => Effect.undefined),
            Effect.flatMap((operation) =>
              operation === undefined
                ? Effect.void
                : waitZoneOperation(env.project, zone, operation, {
                    ignore: ["RESOURCE_ALREADY_EXISTS"],
                  }).pipe(Effect.asVoid),
            ),
          );
        current = yield* waitPresent(env.project, zone, managerName);
      }

      if (current === undefined) {
        return yield* new InstanceGroupManagerNotResolved({
          managerName,
          zone,
        });
      }

      const patch: compute.InstanceGroupManager = {
        fingerprint: current.fingerprint,
      };
      let dirty = false;

      if ((current.description ?? "") !== description) {
        patch.description = description;
        dirty = true;
      }
      if ((current.targetSize ?? DEFAULT_TARGET_SIZE) !== targetSize) {
        patch.targetSize = targetSize;
        dirty = true;
      }
      if (lastSegment(current.instanceTemplate) !== lastSegment(instanceTemplate)) {
        patch.instanceTemplate = instanceTemplate;
        dirty = true;
      }
      if (news.autoHealingPolicies !== undefined) {
        const desiredHealing = toHealing(env.project, news.autoHealingPolicies);
        if (!sameHealing(fromApiHealing(current.autoHealingPolicies), desiredHealing)) {
          patch.autoHealingPolicies = desiredHealing;
          dirty = true;
        }
      }
      if (
        news.updatePolicy !== undefined &&
        !sameUpdatePolicy(current.updatePolicy, news.updatePolicy)
      ) {
        patch.updatePolicy = news.updatePolicy;
        dirty = true;
      }
      if (news.targetPools !== undefined) {
        const desiredPools = news.targetPools.map((pool) =>
          toTargetPoolUrl(env.project, zone, pool),
        );
        if (!sameSegments(current.targetPools, desiredPools)) {
          patch.targetPools = desiredPools;
          dirty = true;
        }
      }
      const observedLifecycle: Record<string, unknown> = {
        ...current.instanceLifecyclePolicy,
      };
      if (
        news.instanceLifecyclePolicy !== undefined &&
        Object.entries(news.instanceLifecyclePolicy).some(
          ([key, value]) =>
            JSON.stringify(observedLifecycle[key] ?? null) !== JSON.stringify(value ?? null),
        )
      ) {
        patch.instanceLifecyclePolicy = news.instanceLifecyclePolicy;
        dirty = true;
      }

      if (dirty) {
        yield* runOp(
          env.project,
          zone,
          compute.patchInstanceGroupManagers({
            project: env.project,
            zone,
            instanceGroupManager: managerName,
            body: patch,
          }),
        ).pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 5,
            schedule: Schedule.exponential("250 millis"),
          }),
        );
        current = (yield* getByName(env.project, zone, managerName)) ?? current;
      }

      if (!samePorts(fromApiPorts(current.namedPorts), namedPorts)) {
        yield* syncNamedPorts(env.project, zone, current.instanceGroup, namedPorts);
        current = (yield* getByName(env.project, zone, managerName)) ?? current;
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* compute
        .deleteInstanceGroupManagers({
          project: output.project,
          zone: output.zone,
          instanceGroupManager: output.managerName,
        })
        .pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("2 seconds"),
          }),
          Effect.catchTag("NotFound", () => Effect.undefined),
          Effect.flatMap((operation) =>
            operation === undefined
              ? Effect.void
              : waitZoneOperation(output.project, output.zone, operation, {
                  ignore: ["RESOURCE_NOT_FOUND"],
                }).pipe(Effect.asVoid),
          ),
          Effect.catchTag("NotFound", () => Effect.void),
        );
      yield* waitGone(output.project, output.zone, output.managerName);
    }),
  });