sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Compute/ InstanceTemplate.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 { tagRecord } from "alchemy/Tags";
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 {
  createInternalLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import { waitGlobalOperation } from "./operations.ts";

const DEFAULT_MACHINE_TYPE = "e2-micro";
const DEFAULT_SOURCE_IMAGE = "projects/debian-cloud/global/images/family/debian-12";
const DEFAULT_DISK_SIZE_GB = "10";
const DEFAULT_NETWORK = "global/networks/default";
const MAX_NAME_LENGTH = 63;

export type InstanceTemplateAccessConfig = {
  /** Access config type. @default "ONE_TO_ONE_NAT" */
  type?: string;
  /** Access config name. */
  name?: string;
  /** Network tier (`PREMIUM` or `STANDARD`). */
  networkTier?: string;
  /** External IPv4 address. */
  natIP?: string;
};

export type InstanceTemplateNetworkInterface = {
  /**
   * VPC network URL or name.
   * @default "global/networks/default"
   */
  network?: string;
  /** Subnetwork URL. */
  subnetwork?: string;
  /** Internal IPv4 address. */
  networkIP?: string;
  /** NIC type (`GVNIC` or `VIRTIO_NET`). */
  nicType?: string;
  /** Stack type (`IPV4_ONLY` or `IPV4_IPV6`). */
  stackType?: string;
  /** External access configs. Omit for no external IP. */
  accessConfigs?: InstanceTemplateAccessConfig[];
};

export type InstanceTemplateDisk = {
  /** Whether this is the boot disk. */
  boot?: boolean;
  /** Delete the disk when the instance is deleted. */
  autoDelete?: boolean;
  /** Device name visible to the guest OS. */
  deviceName?: string;
  /** Disk type (`PERSISTENT` or `SCRATCH`). @default "PERSISTENT" */
  type?: string;
  /** Attach mode (`READ_WRITE` or `READ_ONLY`). */
  mode?: string;
  /** Disk interface (`SCSI` or `NVME`). */
  diskInterface?: string;
  /** Disk size in GB. */
  diskSizeGb?: string | number;
  /** Persistent disk type (`pd-standard`, `pd-balanced`, `pd-ssd`). */
  diskType?: string;
  /** Source image URL or family. */
  sourceImage?: string;
  /** Source snapshot URL. */
  sourceSnapshot?: string;
  /** Existing disk to attach (name for zonal, URL for regional). */
  source?: string;
  /** Disk resource name. */
  diskName?: string;
  /** Disk labels. */
  labels?: Record<string, string>;
};

export type InstanceTemplateServiceAccount = {
  /** Service account email. */
  email?: string;
  /** OAuth scopes granted to the service account. */
  scopes?: string[];
};

export type InstanceTemplateScheduling = {
  /** Restart the VM if Compute Engine terminates it. */
  automaticRestart?: boolean;
  /** Host maintenance behavior (`MIGRATE` or `TERMINATE`). */
  onHostMaintenance?: string;
  /** Whether the VM is preemptible. */
  preemptible?: boolean;
  /** Provisioning model (`STANDARD` or `SPOT`). */
  provisioningModel?: string;
};

export type InstanceTemplateProps = {
  /**
   * Template name. If omitted, a unique RFC1035 name is generated from the
   * stack, stage, and logical id. Must be 1-63 characters matching
   * `[a-z]([-a-z0-9]*[a-z0-9])?`. Changing it replaces the template.
   */
  templateName?: string;
  /**
   * Optional description. Changing it replaces the template.
   */
  description?: string;
  /**
   * Machine type name (not a URL), e.g. `e2-micro`. Instance templates are
   * immutable — changing this replaces the template.
   * @default "e2-micro"
   */
  machineType?: string;
  /**
   * Allow sending/receiving packets with non-instance IPs.
   * @default false
   */
  canIpForward?: boolean;
  /**
   * Labels applied to instances created from this template. Alchemy
   * ownership labels are merged in automatically. Changing labels replaces
   * the template (no in-place update API).
   */
  labels?: Record<string, string>;
  /**
   * Network tags applied to instances created from this template.
   */
  networkTags?: string[];
  /**
   * Instance metadata key/value pairs.
   */
  metadata?: Record<string, string>;
  /**
   * Attached disks. If omitted, a 10 GB Debian 12 boot disk is used.
   */
  disks?: InstanceTemplateDisk[];
  /**
   * Network interfaces.
   * @default [{ network: "global/networks/default" }]
   */
  networkInterfaces?: InstanceTemplateNetworkInterface[];
  /**
   * Service accounts and scopes for created instances.
   */
  serviceAccounts?: InstanceTemplateServiceAccount[];
  /**
   * Scheduling options for created instances.
   */
  scheduling?: InstanceTemplateScheduling;
};

export type InstanceTemplate = Resource<
  "GCP.Compute.InstanceTemplate",
  InstanceTemplateProps,
  {
    /** Template name. */
    templateName: string;
    /** Project id. */
    project: string;
    /** Description. */
    description: string | undefined;
    /** Machine type name. */
    machineType: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Network tags. */
    networkTags: string[];
    /** Whether IP forwarding is enabled. */
    canIpForward: boolean;
    /** Boot-disk source image, if set. */
    sourceImage: string | undefined;
    /** Server-defined URL. */
    selfLink: string | undefined;
    /** Server-assigned numeric id. */
    templateId: string | undefined;
    /** RFC3339 creation timestamp. */
    creationTimestamp: string | undefined;
  },
  never,
  Providers
>;

/**
 * A global Compute Engine instance template.
 *
 * Instance templates are immutable. Changing machine type, disks, labels,
 * network interfaces, or other properties replaces the template. Use the
 * template to create VMs, managed instance groups, and reservations.
 *
 * ### Creating a Template
 * **Example:** Generated name with defaults
 * ```typescript
 * const template = yield* GCP.Compute.InstanceTemplate("web", {});
 * ```
 *
 * **Example:** Explicit machine type, disk, and labels
 * ```typescript
 * const template = yield* GCP.Compute.InstanceTemplate("web", {
 *   machineType: "e2-micro",
 *   labels: { env: "prod" },
 *   disks: [
 *     {
 *       boot: true,
 *       autoDelete: true,
 *       sourceImage:
 *         "projects/debian-cloud/global/images/family/debian-12",
 *       diskSizeGb: 10,
 *     },
 *   ],
 *   networkInterfaces: [{ network: "global/networks/default" }],
 * });
 * ```
 *
 * @resource
 * @category Compute
 */
export const InstanceTemplate = Resource<InstanceTemplate>("GCP.Compute.InstanceTemplate");

export class InstanceTemplateNotResolved extends Data.TaggedError(
  "GCP.Compute.InstanceTemplateNotResolved",
)<{
  templateName: string;
}> {}

export class InstanceTemplateStillExists extends Data.TaggedError(
  "GCP.Compute.InstanceTemplateStillExists",
)<{
  templateName: string;
}> {}

const DEFAULT_DISKS: InstanceTemplateDisk[] = [
  {
    boot: true,
    autoDelete: true,
    type: "PERSISTENT",
    sourceImage: DEFAULT_SOURCE_IMAGE,
    diskSizeGb: DEFAULT_DISK_SIZE_GB,
  },
];

const DEFAULT_NICS: InstanceTemplateNetworkInterface[] = [{ network: DEFAULT_NETWORK }];

const userLabels = (
  labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));

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

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

const sortedRecord = (labels: Record<string, string> | undefined): Record<string, string> =>
  Object.fromEntries(
    Object.entries(labels ?? {}).sort(([left], [right]) => left.localeCompare(right)),
  );

const resolvedDisks = (props: InstanceTemplateProps) =>
  props.disks !== undefined && props.disks.length > 0 ? props.disks : DEFAULT_DISKS;

const resolvedNics = (props: InstanceTemplateProps) =>
  props.networkInterfaces !== undefined && props.networkInterfaces.length > 0
    ? props.networkInterfaces
    : DEFAULT_NICS;

const fingerprint = (props: InstanceTemplateProps): string =>
  JSON.stringify({
    templateName: props.templateName ?? "",
    description: props.description ?? "",
    machineType: props.machineType ?? DEFAULT_MACHINE_TYPE,
    canIpForward: props.canIpForward === true,
    labels: sortedRecord(props.labels),
    networkTags: [...(props.networkTags ?? [])].sort(),
    metadata: sortedRecord(props.metadata),
    disks: resolvedDisks(props).map((disk) => ({
      boot: disk.boot === true,
      autoDelete: disk.autoDelete,
      deviceName: disk.deviceName ?? "",
      type: disk.type ?? "",
      mode: disk.mode ?? "",
      diskInterface: disk.diskInterface ?? "",
      diskSizeGb: disk.diskSizeGb !== undefined ? String(disk.diskSizeGb) : "",
      diskType: disk.diskType ?? "",
      sourceImage: disk.sourceImage ?? "",
      sourceSnapshot: disk.sourceSnapshot ?? "",
      source: disk.source ?? "",
      diskName: disk.diskName ?? "",
      labels: sortedRecord(disk.labels),
    })),
    networkInterfaces: resolvedNics(props).map((nic) => ({
      network: nic.network ?? "",
      subnetwork: nic.subnetwork ?? "",
      networkIP: nic.networkIP ?? "",
      nicType: nic.nicType ?? "",
      stackType: nic.stackType ?? "",
      accessConfigs: nic.accessConfigs ?? [],
    })),
    serviceAccounts: props.serviceAccounts ?? [],
    scheduling: props.scheduling ?? {},
  });

const initializeParamsOf = (
  disk: InstanceTemplateDisk,
): compute.AttachedDiskInitializeParams | undefined => {
  if (
    disk.sourceImage === undefined &&
    disk.sourceSnapshot === undefined &&
    disk.diskType === undefined &&
    disk.diskName === undefined &&
    disk.labels === undefined &&
    disk.diskSizeGb === undefined
  ) {
    return undefined;
  }
  return {
    sourceImage: disk.sourceImage,
    sourceSnapshot: disk.sourceSnapshot,
    diskType: disk.diskType,
    diskName: disk.diskName,
    labels: disk.labels,
    diskSizeGb: disk.diskSizeGb !== undefined ? String(disk.diskSizeGb) : undefined,
  };
};

const toDisks = (disks: InstanceTemplateDisk[]): compute.AttachedDisk[] =>
  disks.map((disk) => ({
    boot: disk.boot,
    autoDelete: disk.autoDelete,
    deviceName: disk.deviceName,
    type: disk.type,
    mode: disk.mode,
    interface: disk.diskInterface,
    source: disk.source,
    initializeParams: disk.source ? undefined : initializeParamsOf(disk),
  }));

const toNics = (nics: InstanceTemplateNetworkInterface[]): compute.NetworkInterface[] =>
  nics.map((nic) => ({
    network: nic.network,
    subnetwork: nic.subnetwork,
    networkIP: nic.networkIP,
    nicType: nic.nicType,
    stackType: nic.stackType,
    accessConfigs: nic.accessConfigs,
  }));

const toProperties = (
  news: InstanceTemplateProps,
  labels: Record<string, string>,
): compute.InstanceProperties => ({
  machineType: news.machineType ?? DEFAULT_MACHINE_TYPE,
  canIpForward: news.canIpForward,
  labels,
  tags: news.networkTags !== undefined ? { items: news.networkTags } : undefined,
  metadata:
    news.metadata !== undefined
      ? {
          items: Object.entries(news.metadata).map(([key, value]) => ({
            key,
            value,
          })),
        }
      : undefined,
  disks: toDisks(resolvedDisks(news)),
  networkInterfaces: toNics(resolvedNics(news)),
  serviceAccounts: news.serviceAccounts,
  scheduling: news.scheduling,
});

const bootSourceImage = (template: compute.InstanceTemplate) => {
  const boot = (template.properties?.disks ?? []).find((disk) => disk.boot === true);
  return boot?.initializeParams?.sourceImage;
};

const toAttrs = (template: compute.InstanceTemplate, project: string) => ({
  templateName: template.name ?? "",
  project,
  description: template.description,
  machineType: template.properties?.machineType,
  labels: userLabels(template.properties?.labels),
  networkTags: template.properties?.tags?.items ?? [],
  canIpForward: template.properties?.canIpForward === true,
  sourceImage: bootSourceImage(template),
  selfLink: template.selfLink,
  templateId: template.id,
  creationTimestamp: template.creationTimestamp,
});

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

const waitUntilPresent = (project: string, templateName: string) =>
  getByName(project, templateName).pipe(
    Effect.flatMap((template) =>
      template !== undefined
        ? Effect.succeed(template)
        : Effect.fail(new InstanceTemplateNotResolved({ templateName })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.InstanceTemplateNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
    Effect.catchTag("GCP.Compute.InstanceTemplateNotResolved", () => Effect.undefined),
  );

const waitUntilGone = (project: string, templateName: string) =>
  getByName(project, templateName).pipe(
    Effect.flatMap((template) =>
      template === undefined
        ? Effect.void
        : Effect.fail(new InstanceTemplateStillExists({ templateName })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.InstanceTemplateStillExists",
      times: 10,
      schedule: Schedule.spaced("1 second"),
    }),
    Effect.catchTag("GCP.Compute.InstanceTemplateStillExists", () => Effect.void),
  );

export const InstanceTemplateProvider = () =>
  Provider.succeed(InstanceTemplate, {
    stables: ["templateName", "project", "templateId", "selfLink", "creationTimestamp"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousName = olds?.templateName ?? output?.templateName;
      const nextName = news.templateName ?? previousName;
      if (previousName === undefined && output === undefined) {
        return undefined;
      }
      const nameChanged =
        news.templateName !== undefined &&
        previousName !== undefined &&
        news.templateName !== previousName;
      const propsChanged = olds !== undefined && fingerprint(news) !== fingerprint(olds);
      const adoptedChanged =
        olds === undefined &&
        output !== undefined &&
        ((news.machineType ?? DEFAULT_MACHINE_TYPE) !==
          (output.machineType ?? DEFAULT_MACHINE_TYPE) ||
          (news.description ?? "") !== (output.description ?? "") ||
          (news.canIpForward === true) !== output.canIpForward ||
          JSON.stringify(sortedRecord(news.labels)) !==
            JSON.stringify(sortedRecord(output.labels)));
      if (!nameChanged && !propsChanged && !adoptedChanged) {
        return undefined;
      }
      return {
        action: "replace" as const,
        deleteFirst:
          previousName !== undefined && nextName !== undefined && nextName === previousName,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const templateName = yield* toName(id, olds?.templateName, output?.templateName);
      const existing = yield* getByName(env.project, templateName);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.properties?.labels)))
        ? attrs
        : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* compute.listInstanceTemplates
          .items({ project: env.project, maxResults: 500 })
          .pipe(
            Stream.filter((template) =>
              Object.keys(template.properties?.labels ?? {}).some((key) =>
                key.startsWith("alchemy-"),
              ),
            ),
            Stream.map((template) => toAttrs(template, env.project)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const templateName = yield* toName(id, news.templateName, output?.templateName);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };

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

      if (current === undefined) {
        yield* compute
          .insertInstanceTemplates({
            project: env.project,
            body: {
              name: templateName,
              description: news.description,
              properties: toProperties(news, desiredLabels),
            },
          })
          .pipe(
            Effect.flatMap((operation) =>
              waitGlobalOperation(env.project, operation, {
                ignore: ["RESOURCE_ALREADY_EXISTS"],
              }),
            ),
            Effect.catchTag("Conflict", () => Effect.void),
          );
        current = yield* waitUntilPresent(env.project, templateName);
      }

      if (current === undefined) {
        return yield* new InstanceTemplateNotResolved({ templateName });
      }

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

    delete: Effect.fn(function* ({ output }) {
      const env = yield* GcpEnvironment.current;
      const operation = yield* compute
        .deleteInstanceTemplates({
          project: env.project,
          instanceTemplate: output.templateName,
        })
        .pipe(
          Effect.catchTag("NotFound", () => Effect.undefined),
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("2 seconds"),
          }),
        );
      if (operation !== undefined) {
        yield* waitGlobalOperation(env.project, operation, {
          ignore: ["RESOURCE_NOT_FOUND"],
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      }
      yield* waitUntilGone(env.project, output.templateName);
    }),
  });