sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Compute/ InstanceGroup.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 NamedPort = {
  /** RFC1035 name for this port mapping (e.g. `"http"`). */
  name: string;
  /** TCP port number (`1`–`65535`). */
  port: number;
};

export type InstanceGroupProps = {
  /**
   * Name of the 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.
   */
  instanceGroupName?: string;
  /**
   * Zone of the instance group (e.g. `"us-central1-a"`). Immutable —
   * changing it replaces the group.
   * @default "us-central1-a"
   */
  zone?: string;
  /**
   * Optional description. Unmanaged instance groups have no labels API, so
   * Alchemy stamps ownership (`alchemy-stack` / `alchemy-stage` /
   * `alchemy-id`) into this field for `list` / nuke. Changing the
   * user-facing description replaces the group.
   */
  description?: string;
  /**
   * VPC network URL or name (`default`, `global/networks/default`, or
   * `projects/{project}/global/networks/{name}`). Immutable — changing it
   * replaces the group.
   */
  network?: string;
  /**
   * Named ports applied to every instance in the group.
   */
  namedPorts?: NamedPort[];
  /**
   * Member instance URLs or names. When omitted, membership is left as-is.
   * When set (including `[]`), observed members are added/removed to match.
   */
  instances?: string[];
};

export type InstanceGroup = Resource<
  "GCP.Compute.InstanceGroup",
  InstanceGroupProps,
  {
    /** Instance group name. */
    instanceGroupName: string;
    /** Zone (short name, e.g. `"us-central1-a"`). */
    zone: string;
    /** Project id. */
    project: string;
    /** User-facing description (ownership marker stripped). */
    description: string | undefined;
    /** Network URL, if set. */
    network: string | undefined;
    /** Subnetwork URL, if set. */
    subnetwork: string | undefined;
    /** Named ports currently configured on the group. */
    namedPorts: NamedPort[];
    /** Number of member instances. */
    size: number;
    /** Server-generated resource URL. */
    selfLink: string | undefined;
    /** Server-generated numeric id. */
    id: string | undefined;
    /** RFC3339 creation timestamp. */
    creationTimestamp: string | undefined;
  },
  never,
  Providers
>;

/**
 * A zonal unmanaged Compute Engine instance group.
 *
 * Unmanaged groups hold an explicit list of VMs and optional named ports
 * for load balancing. They have no labels API — Alchemy records ownership
 * in the description so `list` / `pnpm nuke:gcp` can find them.
 *
 * ### Creating an Instance Group
 * **Example:** Generated name
 * ```typescript
 * const group = yield* GCP.Compute.InstanceGroup("web", {
 *   namedPorts: [{ name: "http", port: 80 }],
 * });
 * ```
 *
 * **Example:** Explicit name, zone, and named ports
 * ```typescript
 * const group = yield* GCP.Compute.InstanceGroup("web", {
 *   instanceGroupName: "web-backends",
 *   zone: "us-central1-a",
 *   description: "HTTP backends",
 *   namedPorts: [
 *     { name: "http", port: 80 },
 *     { name: "https", port: 443 },
 *   ],
 * });
 * ```
 *
 * @resource
 * @category Compute
 */
export const InstanceGroup = Resource<InstanceGroup>("GCP.Compute.InstanceGroup");

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

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

const DEFAULT_ZONE = "us-central1-a";

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

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

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

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 toNetworkUrl = (project: string, network: string | undefined) => {
  if (network === undefined || network.length === 0) return undefined;
  if (network.includes("/")) return network;
  return `projects/${project}/global/networks/${network}`;
};

const toInstanceUrl = (project: string, zone: string, instance: string) =>
  instance.includes("/") ? instance : `projects/${project}/zones/${zone}/instances/${instance}`;

const canonPorts = (ports: readonly NamedPort[] | undefined): NamedPort[] =>
  [...(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 NamedPort[] | undefined,
  right: readonly NamedPort[] | undefined,
) => JSON.stringify(canonPorts(left)) === JSON.stringify(canonPorts(right));

const fromApiPorts = (ports: readonly compute.NamedPort[] | undefined): NamedPort[] =>
  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 toAttrs = (group: compute.InstanceGroup, project: string) => {
  const { user } = parseDescription(group.description);
  return {
    instanceGroupName: group.name ?? lastSegment(group.selfLink ?? ""),
    zone: lastSegment(group.zone ?? DEFAULT_ZONE),
    project,
    description: user,
    network: group.network,
    subnetwork: group.subnetwork,
    namedPorts: fromApiPorts(group.namedPorts),
    size: group.size ?? 0,
    selfLink: group.selfLink,
    id: group.id,
    creationTimestamp: group.creationTimestamp,
  };
};

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

const listMembers = (project: string, zone: string, instanceGroup: string) =>
  compute.listInstancesInstanceGroups
    .items({
      project,
      zone,
      instanceGroup,
      body: { instanceState: "ALL" },
    })
    .pipe(
      Stream.runCollect,
      Effect.map((chunk) =>
        Array.from(chunk)
          .map((item) => item.instance)
          .filter((url): url is string => typeof url === "string"),
      ),
      Effect.catchTag("NotFound", () => Effect.succeed([] as string[])),
    );

const waitGone = (project: string, zone: string, instanceGroupName: string) =>
  getByName(project, zone, instanceGroupName).pipe(
    Effect.flatMap((group) =>
      group === undefined
        ? Effect.void
        : Effect.fail(new InstanceGroupStillExists({ instanceGroupName, zone })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.InstanceGroupStillExists",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

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"],
      }),
    ),
  );

export const InstanceGroupProvider = () =>
  Provider.succeed(InstanceGroup, {
    stables: ["instanceGroupName", "zone", "project", "id", "selfLink", "creationTimestamp"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousName = olds?.instanceGroupName ?? output?.instanceGroupName;
      const nextName = news.instanceGroupName ?? previousName;
      const previousZone = olds?.zone ?? output?.zone;
      const nextZone = news.zone ?? DEFAULT_ZONE;
      const previousNetwork = olds?.network ?? output?.network;
      const nextNetwork = news.network;
      const nameChanged =
        previousName !== undefined && nextName !== undefined && previousName !== nextName;
      const zoneChanged =
        previousZone !== undefined && lastSegment(previousZone) !== lastSegment(nextZone);
      const networkChanged =
        nextNetwork !== undefined &&
        previousNetwork !== undefined &&
        lastSegment(previousNetwork) !== lastSegment(nextNetwork);
      const descriptionChanged =
        olds !== undefined && (olds.description ?? "") !== (news.description ?? "");
      if (!nameChanged && !zoneChanged && !networkChanged && !descriptionChanged) {
        return undefined;
      }
      const sameIdentity =
        previousName === nextName && lastSegment(previousZone ?? "") === lastSegment(nextZone);
      return {
        action: "replace" as const,
        deleteFirst: sameIdentity,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceGroupName = yield* toName(
        id,
        olds?.instanceGroupName,
        output?.instanceGroupName,
      );
      const zone = lastSegment(olds?.zone ?? output?.zone ?? DEFAULT_ZONE);
      const existing = yield* getByName(env.project, zone, instanceGroupName);
      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.aggregatedListInstanceGroups
          .pages({
            project: env.project,
            maxResults: 500,
            returnPartialSuccess: true,
          })
          .pipe(Stream.runCollect);
        return Array.from(pages).flatMap((page) =>
          Object.values(page.items ?? {}).flatMap((scoped) =>
            (scoped?.instanceGroups ?? [])
              .filter((group) => hasOwnershipMarker(group.description))
              .map((group) => toAttrs(group, env.project)),
          ),
        );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const instanceGroupName = yield* toName(
        id,
        news.instanceGroupName,
        output?.instanceGroupName,
      );
      const zone = lastSegment(news.zone ?? output?.zone ?? DEFAULT_ZONE);
      const namedPorts = canonPorts(news.namedPorts);
      const network = toNetworkUrl(env.project, news.network);
      const desiredLabels = yield* createInternalLabels(id);
      const description = encodeDescription(news.description, desiredLabels);

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

      if (current === undefined) {
        yield* compute
          .insertInstanceGroups({
            project: env.project,
            zone,
            body: {
              name: instanceGroupName,
              description,
              namedPorts: namedPorts.length > 0 ? namedPorts : undefined,
              network,
            },
          })
          .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* getByName(env.project, zone, instanceGroupName).pipe(
          Effect.flatMap((group) =>
            group === undefined
              ? Effect.fail(new InstanceGroupNotResolved({ instanceGroupName, zone }))
              : Effect.succeed(group),
          ),
          Effect.retry({
            while: (error) => error._tag === "GCP.Compute.InstanceGroupNotResolved",
            times: 8,
            schedule: Schedule.exponential("250 millis"),
          }),
          Effect.catchTag("GCP.Compute.InstanceGroupNotResolved", () => Effect.undefined),
        );
      }

      if (current === undefined) {
        return yield* new InstanceGroupNotResolved({
          instanceGroupName,
          zone,
        });
      }

      if (!samePorts(fromApiPorts(current.namedPorts), namedPorts)) {
        yield* runOp(
          env.project,
          zone,
          compute.setNamedPortsInstanceGroups({
            project: env.project,
            zone,
            instanceGroup: instanceGroupName,
            body: {
              namedPorts,
              fingerprint: current.fingerprint,
            },
          }),
        ).pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 5,
            schedule: Schedule.exponential("250 millis"),
          }),
        );
        current = (yield* getByName(env.project, zone, instanceGroupName)) ?? current;
      }

      if (news.instances !== undefined) {
        const observed = yield* listMembers(env.project, zone, instanceGroupName);
        const desired = news.instances.map((instance) =>
          toInstanceUrl(env.project, zone, instance),
        );
        const observedKeys = new Set(observed.map(lastSegment));
        const desiredKeys = new Set(desired.map(lastSegment));
        const toAdd = desired.filter((instance) => !observedKeys.has(lastSegment(instance)));
        const toRemove = observed.filter((instance) => !desiredKeys.has(lastSegment(instance)));
        if (toAdd.length > 0) {
          yield* runOp(
            env.project,
            zone,
            compute.addInstancesInstanceGroups({
              project: env.project,
              zone,
              instanceGroup: instanceGroupName,
              body: {
                instances: toAdd.map((instance) => ({ instance })),
              },
            }),
          );
        }
        if (toRemove.length > 0) {
          yield* runOp(
            env.project,
            zone,
            compute.removeInstancesInstanceGroups({
              project: env.project,
              zone,
              instanceGroup: instanceGroupName,
              body: {
                instances: toRemove.map((instance) => ({ instance })),
              },
            }),
          );
        }
        current = (yield* getByName(env.project, zone, instanceGroupName)) ?? current;
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* compute
        .deleteInstanceGroups({
          project: output.project,
          zone: output.zone,
          instanceGroup: output.instanceGroupName,
        })
        .pipe(
          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.instanceGroupName);
    }),
  });