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

export type ImageRawDisk = {
  /** GCS URI of a gzip-compressed tarball (`gs://` or `https://storage.googleapis.com/`). */
  source: string;
  /** SHA-1 checksum of the tarball, if known. */
  sha1Checksum?: string;
  /**
   * Container type of the disk image.
   * @default "TAR"
   */
  containerType?: "TAR" | (string & {});
};

export type ImageProps = {
  /**
   * Image name (RFC1035, 1-63 characters). If omitted, a unique name is
   * generated from the stack, stage, and logical id. Changing the name
   * replaces the image.
   */
  imageName?: string;
  /**
   * Optional description. Mutable in place via `images.patch`.
   */
  description?: string;
  /**
   * Image family. Disks can target the family to get the latest
   * non-deprecated image. Mutable in place via `images.patch`.
   */
  family?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically
   * and synced via `images.setLabels`.
   */
  labels?: Record<string, string>;
  /**
   * Source disk URL (`projects/{project}/zones/{zone}/disks/{disk}`).
   * Immutable — changing it replaces the image. Provide one of
   * `sourceDisk`, `sourceImage`, `sourceSnapshot`, or `rawDisk`.
   */
  sourceDisk?: string;
  /**
   * Source image URL (`projects/{project}/global/images/{image}` or
   * `.../images/family/{family}`). Immutable — changing it replaces
   * the image.
   */
  sourceImage?: string;
  /**
   * Source snapshot URL (`projects/{project}/global/snapshots/{snapshot}`).
   * Immutable — changing it replaces the image.
   */
  sourceSnapshot?: string;
  /**
   * Raw disk image stored in Cloud Storage. Immutable — changing it
   * replaces the image.
   */
  rawDisk?: ImageRawDisk;
  /**
   * Size of the image when restored onto a persistent disk, in GB.
   * Immutable — changing it replaces the image.
   */
  diskSizeGb?: number;
  /**
   * Cloud Storage locations for the image (`us-central1`, `us`, …).
   * Immutable — changing it replaces the image.
   */
  storageLocations?: string[];
  /**
   * CPU architecture (`ARM64` or `X86_64`). Immutable — changing it
   * replaces the image.
   */
  architecture?: compute.ImageArchitectureEnum | (string & {});
  /**
   * License URIs attached to the image. Immutable — changing it replaces
   * the image.
   */
  licenses?: string[];
};

export type Image = Resource<
  "GCP.Compute.Image",
  ImageProps,
  {
    /** Image name. */
    imageName: string;
    /** Server-assigned numeric id. */
    imageId: string | undefined;
    /** Project id. */
    project: string;
    /** Server-reported status (`PENDING`, `READY`, `FAILED`, …). */
    status: string | undefined;
    /** Image family, if set. */
    family: string | undefined;
    /** Description. */
    description: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Source disk URL, if any. */
    sourceDisk: string | undefined;
    /** Source image URL, if any. */
    sourceImage: string | undefined;
    /** Source snapshot URL, if any. */
    sourceSnapshot: string | undefined;
    /** Size in GB when restored onto a disk. */
    diskSizeGb: string | undefined;
    /** Architecture, if set. */
    architecture: string | undefined;
    /** Storage locations. */
    storageLocations: string[];
    /** Compute Engine self-link. */
    selfLink: string | undefined;
    /** RFC3339 creation timestamp. */
    creationTimestamp: string | undefined;
    /** Archive size in bytes, if reported. */
    archiveSizeBytes: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Compute Engine custom image used to create boot disks for VMs.
 *
 * Create from a disk, another image, a snapshot, or a GCS tarball.
 * `family` and `description` update in place; labels are synced via
 * `setLabels`. Source, size, architecture, licenses, and storage
 * locations replace the image.
 *
 * ### Creating an Image
 * **Example:** Image from a disk
 * ```typescript
 * const image = yield* GCP.Compute.Image("boot", {
 *   sourceDisk: "projects/my-project/zones/us-central1-a/disks/my-disk",
 *   family: "app-boot",
 *   labels: { env: "prod" },
 * });
 * ```
 *
 * **Example:** Clone a public image family
 * ```typescript
 * const image = yield* GCP.Compute.Image("debian", {
 *   sourceImage: "projects/debian-cloud/global/images/family/debian-12",
 *   storageLocations: ["us-central1"],
 * });
 * ```
 *
 * ### Updating an Image
 * **Example:** Family, description, and labels
 * ```typescript
 * const image = yield* GCP.Compute.Image("boot", {
 *   imageName: "app-boot-v2",
 *   sourceDisk: "projects/my-project/zones/us-central1-a/disks/my-disk",
 *   family: "app-boot",
 *   description: "golden image",
 *   labels: { env: "prod", role: "boot" },
 * });
 * ```
 *
 * @resource
 * @category Compute
 */
export const Image = Resource<Image>("GCP.Compute.Image");

export class ImageNotResolved extends Data.TaggedError("GCP.Compute.ImageNotResolved")<{
  imageName: string;
}> {}

export class ImagePending extends Data.TaggedError("GCP.Compute.ImagePending")<{
  imageName: string;
  status: string;
}> {}

export class ImageFailed extends Data.TaggedError("GCP.Compute.ImageFailed")<{
  imageName: string;
  status: string;
}> {}

export class ImageStillExists extends Data.TaggedError("GCP.Compute.ImageStillExists")<{
  imageName: string;
  status: string;
}> {}

export class ImageSourceRequired extends Data.TaggedError("GCP.Compute.ImageSourceRequired")<{
  imageName: string;
}> {}

const MAX_NAME_LENGTH = 63;

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

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

const sameStrings = (left?: readonly string[], right?: readonly string[]) =>
  JSON.stringify([...(left ?? [])].sort()) === JSON.stringify([...(right ?? [])].sort());

const toName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (name !== undefined) return name;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: MAX_NAME_LENGTH,
      lowercase: true,
    });
    return /^[a-z]/.test(generated) ? generated : `i${generated}`.slice(0, MAX_NAME_LENGTH);
  });

const toAttrs = (image: compute.Image, project: string) => ({
  imageName: image.name ?? image.id ?? "",
  imageId: image.id,
  project,
  status: image.status,
  family: image.family,
  description: image.description,
  labels: userLabels(image.labels),
  sourceDisk: image.sourceDisk,
  sourceImage: image.sourceImage,
  sourceSnapshot: image.sourceSnapshot,
  diskSizeGb: image.diskSizeGb,
  architecture: image.architecture,
  storageLocations: image.storageLocations ?? [],
  selfLink: image.selfLink,
  creationTimestamp: image.creationTimestamp,
  archiveSizeBytes: image.archiveSizeBytes,
});

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

const waitUntilReady = (project: string, imageName: string) =>
  getByName(project, imageName).pipe(
    Effect.flatMap((image) =>
      image?.status === "FAILED"
        ? Effect.fail(new ImageFailed({ imageName, status: "FAILED" }))
        : Effect.succeed(image),
    ),
    Effect.filterOrFail(
      (image): image is compute.Image => image !== undefined && image.status === "READY",
      (image) =>
        new ImagePending({
          imageName,
          status: image?.status ?? "MISSING",
        }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.ImagePending",
      times: 10,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

const waitUntilGone = (project: string, imageName: string) =>
  getByName(project, imageName).pipe(
    Effect.flatMap((image) =>
      image === undefined
        ? Effect.void
        : Effect.fail(
            new ImageStillExists({
              imageName,
              status: image.status ?? "UNKNOWN",
            }),
          ),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Compute.ImageStillExists",
      times: 18,
      schedule: Schedule.spaced("3 seconds"),
    }),
  );

const insertBody = (
  imageName: string,
  news: ImageProps,
  labels: Record<string, string>,
): compute.Image => ({
  name: imageName,
  description: news.description,
  family: news.family,
  labels,
  sourceDisk: news.sourceDisk,
  sourceImage: news.sourceImage,
  sourceSnapshot: news.sourceSnapshot,
  rawDisk: news.rawDisk
    ? {
        source: news.rawDisk.source,
        sha1Checksum: news.rawDisk.sha1Checksum,
        containerType: news.rawDisk.containerType ?? "TAR",
      }
    : undefined,
  diskSizeGb: news.diskSizeGb !== undefined ? String(news.diskSizeGb) : undefined,
  storageLocations: news.storageLocations,
  architecture: news.architecture,
  licenses: news.licenses,
});

const hasSource = (props: ImageProps) =>
  props.sourceDisk !== undefined ||
  props.sourceImage !== undefined ||
  props.sourceSnapshot !== undefined ||
  props.rawDisk?.source !== undefined;

const sourceIdentity = (props: ImageProps): string => {
  if (props.sourceDisk !== undefined) {
    return `disk:${lastSegment(props.sourceDisk)}`;
  }
  if (props.sourceImage !== undefined) {
    return `image:${lastSegment(props.sourceImage)}`;
  }
  if (props.sourceSnapshot !== undefined) {
    return `snapshot:${lastSegment(props.sourceSnapshot)}`;
  }
  if (props.rawDisk?.source !== undefined) {
    return `raw:${props.rawDisk.source}:${props.rawDisk.sha1Checksum ?? ""}:${props.rawDisk.containerType ?? "TAR"}`;
  }
  return "";
};

const sourceChanged = (olds: ImageProps, news: ImageProps) => {
  const previous = sourceIdentity(olds);
  const next = sourceIdentity(news);
  return previous.length > 0 && next.length > 0 && previous !== next;
};

export const ImageProvider = () =>
  Provider.succeed(Image, {
    stables: [
      "imageName",
      "imageId",
      "project",
      "selfLink",
      "creationTimestamp",
      "sourceDisk",
      "sourceImage",
      "sourceSnapshot",
      "architecture",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousName = olds.imageName ?? output?.imageName;
      const nextName = news.imageName ?? previousName;
      const nameChanged =
        previousName !== undefined && nextName !== undefined && previousName !== nextName;

      const previousSize = olds.diskSizeGb ?? Number(output?.diskSizeGb);
      const sizeChanged =
        news.diskSizeGb !== undefined &&
        previousSize !== undefined &&
        !Number.isNaN(previousSize) &&
        news.diskSizeGb !== previousSize;

      const architectureChanged =
        news.architecture !== undefined &&
        (olds.architecture ?? output?.architecture) !== undefined &&
        news.architecture !== (olds.architecture ?? output?.architecture);

      const storageChanged =
        news.storageLocations !== undefined &&
        !sameStrings(news.storageLocations, olds.storageLocations ?? output?.storageLocations);

      const licensesChanged =
        news.licenses !== undefined &&
        olds.licenses !== undefined &&
        !sameStrings(news.licenses, olds.licenses);

      const replace =
        nameChanged ||
        sourceChanged(olds, news) ||
        sizeChanged ||
        architectureChanged ||
        storageChanged ||
        licensesChanged;

      if (!replace) 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 imageName = yield* toName(id, olds?.imageName, output?.imageName);
      const existing = yield* getByName(env.project, imageName);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
    }),

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

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

      let current = yield* getByName(env.project, imageName);
      if (current?.status === "DELETING") {
        yield* waitUntilGone(env.project, imageName);
        current = undefined;
      }

      if (current === undefined) {
        if (!hasSource(news)) {
          return yield* new ImageSourceRequired({ imageName });
        }
        const inserted = yield* compute
          .insertImages({
            project: env.project,
            body: insertBody(imageName, news, desiredLabels),
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (inserted !== undefined) {
          yield* waitGlobalOperation(env.project, inserted, {
            ignore: ["RESOURCE_ALREADY_EXISTS"],
          });
        }
        current = yield* waitUntilReady(env.project, imageName);
      }

      if (current === undefined) {
        return yield* new ImageNotResolved({ imageName });
      }

      if (current.status !== "READY") {
        current = yield* waitUntilReady(env.project, imageName);
      }

      if (current === undefined) {
        return yield* new ImageNotResolved({ imageName });
      }

      const familyChanged = (current.family ?? "") !== (news.family ?? "");
      const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
      if (familyChanged || descriptionChanged) {
        yield* compute
          .patchImages({
            project: env.project,
            image: imageName,
            body: {
              family: news.family,
              description: news.description,
            },
          })
          .pipe(Effect.flatMap((operation) => waitGlobalOperation(env.project, operation)));
        current = (yield* getByName(env.project, imageName)) ?? current;
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      if (upsert.length > 0 || removed.length > 0) {
        yield* compute
          .setLabelsImages({
            project: env.project,
            resource: imageName,
            body: {
              labels: desiredLabels,
              labelFingerprint: current.labelFingerprint,
            },
          })
          .pipe(Effect.flatMap((operation) => waitGlobalOperation(env.project, operation)));
        // A read right after setLabels can still return the old labels.
        current =
          (yield* getByName(env.project, imageName).pipe(
            Effect.repeat({
              schedule: Schedule.spaced("2 seconds"),
              until: (image) => {
                const labels = diffLabels(tagRecord(image?.labels), desiredLabels);
                return labels.upsert.length === 0 && labels.removed.length === 0;
              },
              times: 10,
            }),
          )) ?? current;
      }

      if (current === undefined) {
        return yield* new ImageNotResolved({ imageName });
      }

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

    delete: Effect.fn(function* ({ output }) {
      const env = yield* GcpEnvironment.current;
      const operation = yield* compute
        .deleteImages({
          project: env.project,
          image: output.imageName,
        })
        .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.imageName);
    }),
  });