sailfork / t3code-github / .repos/ alchemy-effect/ packages/ hetzner/ src/ Image.ts

import * as Hetzner from "@distilled.cloud/hetzner";
import type {
  GetImageResponseImage,
  ListImagesResponseImagesItem,
  UpdateImageResponseImage,
} from "@distilled.cloud/hetzner/images";
import type { CreateServerImageResponseImage } from "@distilled.cloud/hetzner/server_actions";
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 Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { waitForAction } from "./actions.ts";
import {
  alchemyStackSelector,
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  labelSelector,
  stripInternalLabels,
  toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";

const MAX_DESCRIPTION_LENGTH = 64;

export type ImageType = "snapshot" | "backup";

export type ImageStatus = "available" | "creating" | "unavailable";

export type ImageArchitecture = "x86" | "arm";

export type ImageOsFlavor =
  | "ubuntu"
  | "centos"
  | "debian"
  | "fedora"
  | "rocky"
  | "alma"
  | "opensuse"
  | "unknown";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* Server(...)` and `Server(...)` both type-check).
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

/**
 * Server identity an Image is snapshotted from. Accepts a `Hetzner.Server`
 * resource or a `{ serverId }` stub. Stock (system/app) Images are not
 * managed here — look those up with `Hetzner.findImage`.
 */
export type ImageServer = {
  readonly serverId: number;
};

export interface ImageProps {
  /**
   * Server to snapshot. Required on create. Changing the source Server
   * replaces the Image (Hetzner cannot re-snapshot onto an existing Image).
   * Accepts a `Hetzner.Server` or `{ serverId }`.
   */
  server: Ref<ImageServer>;
  /**
   * Human-readable description. Snapshots have no unique `name` (that
   * field is only set on system Images). If omitted, a unique description
   * is generated from the stack, stage and logical ID.
   */
  description?: string;
  /**
   * Image type. Snapshots are independent of the source Server and billed
   * per GB. Backups are bound to the Server (and deleted with it) and
   * require backups to be enabled. Convert a backup to a snapshot in
   * place; snapshot → backup replaces.
   *
   * @default "snapshot"
   */
  type?: ImageType;
  /**
   * User-defined labels. Alchemy ownership labels (`alchemy.stack` /
   * `alchemy.stage` / `alchemy.id`) are always merged in.
   */
  labels?: Record<string, string>;
  /**
   * Prevent the Image from being deleted via the API. Only valid on
   * snapshots.
   *
   * @default false
   */
  deleteProtection?: boolean;
}

export type Image = Resource<
  "Hetzner.Image",
  ImageProps,
  {
    /** Numeric Hetzner Image ID. */
    id: number;
    /** Image type (`snapshot` or `backup`). */
    type: ImageType;
    /** Image status. */
    status: ImageStatus;
    /**
     * Unique identifier. Only set for system Images — snapshots and
     * backups are `null`.
     */
    name: string | null;
    /** Human-readable description. */
    description: string;
    /**
     * Size of the Image file in Hetzner storage in GB. Relevant for
     * snapshot billing. `null` while the Image is still creating.
     */
    imageSize: number | null;
    /** Size of the disk contained in the Image in GB. */
    diskSize: number;
    /** RFC3339 creation timestamp. */
    created: string;
    /** ID of the Server this Image was created from, or `null`. */
    createdFromId: number | null;
    /** Server name at snapshot time, or `null`. */
    createdFromName: string | null;
    /**
     * Server ID this Image is bound to. Only set for `backup` Images.
     */
    boundTo: number | null;
    /** Flavor of operating system contained in the Image. */
    osFlavor: ImageOsFlavor;
    /** Operating system version, or `null`. */
    osVersion: string | null;
    /** Whether rapid deploy of the Image is available. */
    rapidDeploy: boolean | undefined;
    /** Whether delete protection is enabled. */
    deleteProtection: boolean;
    /** RFC3339 deprecation timestamp, or `null`. */
    deprecated: string | null;
    /** CPU architecture compatible with the Image. */
    architecture: ImageArchitecture;
    /** User-defined labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
  },
  never,
  Providers
>;

/**
 * A Hetzner Cloud custom Image — a snapshot (or backup) of a Server's
 * disk. Stock system/app Images (`ubuntu-24.04`, …) are Catalog lookups
 * via `Hetzner.findImage`, not this resource.
 *
 * Snapshots are created with `POST /servers/{id}/actions/create_image`
 * and billed per GB. Description, labels, delete protection, and
 * backup→snapshot conversion update in place. Changing the source Server
 * replaces the Image.
 *
 * @see https://docs.hetzner.cloud/reference/cloud#images
 *
 * ### Creating a Snapshot
 * **Example:** Snapshot from a Server
 * ```typescript
 * const server = yield* Hetzner.Server("web", {
 *   serverType: "cx22",
 *   image: "ubuntu-24.04",
 *   location: "nbg1",
 * });
 * const image = yield* Hetzner.Image("golden", {
 *   server,
 *   description: "golden-web",
 *   labels: { role: "golden" },
 * });
 * ```
 *
 * **Example:** Snapshot with generated description
 * ```typescript
 * const image = yield* Hetzner.Image("backup", {
 *   server: { serverId: 42 },
 * });
 * ```
 *
 * ### Updating a Snapshot
 * **Example:** Description, labels, and protection
 * ```typescript
 * const image = yield* Hetzner.Image("golden", {
 *   server,
 *   description: "golden-web-v2",
 *   labels: { role: "golden", env: "prod" },
 *   deleteProtection: true,
 * });
 * ```
 *
 * @resource
 * @product Server
 */
export const Image = Resource<Image>("Hetzner.Image");

type CloudImage =
  | GetImageResponseImage
  | ListImagesResponseImagesItem
  | CreateServerImageResponseImage
  | UpdateImageResponseImage;

class ImagePending extends Data.TaggedError("ImagePending")<{
  imageId: number;
  status: string;
}> {}

class ImageTimeout extends Data.TaggedError("ImageTimeout")<{
  imageId: number;
  status: string;
}> {}

class ImageNotResolved extends Data.TaggedError("Hetzner.ImageNotResolved")<{
  serverId: number;
  description: string;
}> {}

class ImageServerRequired extends Data.TaggedError("Hetzner.ImageServerRequired")<{
  description: string;
}> {}

const DEFAULT_TYPE: ImageType = "snapshot";

const asType = (type: string): ImageType => (type === "backup" ? "backup" : "snapshot");

const asStatus = (status: string): ImageStatus =>
  status === "creating" || status === "unavailable" ? status : "available";

const asArchitecture = (architecture: string): ImageArchitecture =>
  architecture === "arm" ? "arm" : "x86";

const asOsFlavor = (flavor: string): ImageOsFlavor => {
  switch (flavor) {
    case "ubuntu":
    case "centos":
    case "debian":
    case "fedora":
    case "rocky":
    case "alma":
    case "opensuse":
    case "unknown":
      return flavor;
    default:
      return "unknown";
  }
};

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

const toAttrs = (image: CloudImage): Image["Attributes"] => ({
  id: image.id,
  type: asType(image.type),
  status: asStatus(image.status),
  name: image.name,
  description: image.description,
  imageSize: image.image_size,
  diskSize: image.disk_size,
  created: image.created,
  createdFromId: image.created_from?.id ?? null,
  createdFromName: image.created_from?.name ?? null,
  boundTo: image.bound_to,
  osFlavor: asOsFlavor(image.os_flavor),
  osVersion: image.os_version,
  rapidDeploy: image.rapid_deploy,
  deleteProtection: image.protection.delete,
  deprecated: image.deprecated,
  architecture: asArchitecture(image.architecture),
  labels: userLabels(image.labels),
});

const retryable = (e: { readonly _tag: string }): boolean =>
  e._tag === "ImagePending" ||
  e._tag === "TooManyRequests" ||
  e._tag === "ServiceUnavailable" ||
  e._tag === "InternalServerError" ||
  e._tag === "BadGateway" ||
  e._tag === "GatewayTimeout" ||
  e._tag === "Locked";

const backoff = Schedule.min([
  Schedule.exponential(Duration.millis(500), 1.5),
  Schedule.spaced(Duration.seconds(5)),
]);

const toDescription = (id: string, description: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return (
      description ??
      existing ??
      (yield* createPhysicalName({ id, maxLength: MAX_DESCRIPTION_LENGTH }))
    );
  });

const getById = (id: number) =>
  Hetzner.images.getImage({ id }).pipe(
    Effect.map(({ image }) => image),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const getByLabels = (labels: Record<string, string>) =>
  Hetzner.images
    .listImages({
      type: ["snapshot", "backup"],
      label_selector: labelSelector(labels),
      per_page: 50,
    })
    .pipe(Effect.map(({ images }) => images[0]));

const observe = Effect.fn(function* ({ id, outputId }: { id: string; outputId?: number }) {
  if (outputId !== undefined) {
    const byId = yield* getById(outputId);
    if (byId !== undefined) return byId;
  }
  const internal = yield* createInternalLabels(id);
  return yield* getByLabels(internal);
});

const waitUntilAvailable = (imageId: number) =>
  getById(imageId).pipe(
    Effect.flatMap((image) =>
      image !== undefined && image.status === "available"
        ? Effect.succeed(image)
        : Effect.fail(
            new ImagePending({
              imageId,
              status: image?.status ?? "missing",
            }),
          ),
    ),
    Effect.retry({
      while: retryable,
      times: 10,
      schedule: Schedule.spaced(Duration.seconds(5)),
    }),
    Effect.catchTag(
      "ImagePending",
      (e) =>
        new ImageTimeout({
          imageId: e.imageId,
          status: e.status,
        }),
    ),
  );

const waitUntilGone = (imageId: number) =>
  Hetzner.images.getImage({ id: imageId }).pipe(
    Effect.map(() => false),
    Effect.catchTag("NotFound", () => Effect.succeed(true)),
    Effect.repeat({
      schedule: Schedule.spaced(Duration.seconds(1)),
      until: (gone) => gone,
      times: 10,
    }),
  );

const serverIdOf = (value: unknown): number | undefined => {
  if (value == null || typeof value !== "object") return undefined;
  const id = (value as { serverId?: unknown }).serverId;
  return typeof id === "number" ? id : undefined;
};

const disableProtection = (id: number) =>
  Hetzner.imageActions
    .changeImageProtection({ id, delete: false })
    .pipe(Effect.flatMap(({ action }) => waitForAction(action)));

export const ImageProvider = () =>
  Provider.succeed(Image, {
    stables: ["id", "created", "createdFromId", "architecture", "diskSize", "osFlavor"],
    list: Effect.fn(function* () {
      const items = yield* Hetzner.images.listImages
        .items({
          type: ["snapshot", "backup"],
          label_selector: alchemyStackSelector,
          per_page: 50,
        })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
      return items.map(toAttrs);
    }),
    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (output !== undefined) {
        const nextServerId = serverIdOf(news.server);
        if (
          nextServerId !== undefined &&
          output.createdFromId !== null &&
          nextServerId !== output.createdFromId
        ) {
          return { action: "replace" } as const;
        }
        const nextType = news.type ?? DEFAULT_TYPE;
        if (nextType === "backup" && output.type === "snapshot") {
          return { action: "replace" } as const;
        }
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output }) {
      const found = yield* observe({
        id,
        outputId: output?.id,
      });
      if (found === undefined) return undefined;
      const attrs = toAttrs(found);
      const owned = yield* hasAlchemyLabels(id, tagRecord(found.labels));
      return owned ? attrs : Unowned(attrs);
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const description = yield* toDescription(id, news.description, output?.description);
      const internalLabels = yield* createInternalLabels(id);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...internalLabels,
      };
      const desiredType = news.type ?? DEFAULT_TYPE;
      const desiredProtection = news.deleteProtection ?? false;
      const desiredServerId = serverIdOf(news.server);

      // Observe by id only. Do not fall back to ownership labels — a
      // create-first replacement still has the old generation live under
      // the same logical id, and snapshots are not uniquely named.
      let current = output?.id !== undefined ? yield* getById(output.id) : undefined;

      if (current === undefined) {
        if (desiredServerId === undefined) {
          return yield* new ImageServerRequired({ description });
        }
        const created = yield* Hetzner.serverActions.createServerImage({
          id: desiredServerId,
          description,
          type: desiredType,
          labels: desiredLabels,
        });
        const imageId =
          created.image?.id ??
          created.action?.resources.find((resource) => resource.type === "image")?.id;
        if (imageId === undefined) {
          return yield* new ImageNotResolved({
            serverId: desiredServerId,
            description,
          });
        }
        if (created.action) {
          yield* waitForAction(created.action).pipe(
            Effect.catchTag("ActionTimeout", () => Effect.void),
          );
        }
        current = yield* waitUntilAvailable(imageId);
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const convertToSnapshot = current.type === "backup" && desiredType === "snapshot";
      const descriptionChanged = current.description !== description;
      if (descriptionChanged || labelsChanged || convertToSnapshot) {
        const updated = yield* Hetzner.images.updateImage({
          id: current.id,
          description: descriptionChanged ? description : undefined,
          type: convertToSnapshot ? "snapshot" : undefined,
          labels: labelsChanged ? desiredLabels : undefined,
        });
        current = updated.image ?? (yield* waitUntilAvailable(current.id));
      }

      if (current.protection.delete !== desiredProtection) {
        const { action } = yield* Hetzner.imageActions.changeImageProtection({
          id: current.id,
          delete: desiredProtection,
        });
        yield* waitForAction(action);
        current = (yield* getById(current.id)) ?? current;
      }

      return toAttrs(current);
    }),
    delete: Effect.fn(function* ({ output }) {
      const current = yield* getById(output.id);
      if (current === undefined) return;

      if (current.protection.delete) {
        yield* disableProtection(current.id);
      }

      yield* Hetzner.images.deleteImage({ id: current.id }).pipe(
        Effect.catchTag("NotFound", () => Effect.void),
        Effect.retry({
          while: retryable,
          times: 8,
          schedule: backoff,
        }),
      );
      yield* waitUntilGone(current.id);
    }),
  });