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

import * as Hetzner from "@distilled.cloud/hetzner";
import type {
  GetVolumeResponseVolume,
  ListVolumesResponseVolumesItem,
} from "@distilled.cloud/hetzner/volumes";
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, waitForActions } from "./actions.ts";
import {
  alchemyStackSelector,
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  labelSelector,
  stripInternalLabels,
  toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";

const DEFAULT_LOCATION = "nbg1";
const MIN_SIZE_GB = 10;
const MAX_NAME_LENGTH = 64;

export type VolumeFormat = "ext4" | "xfs";

export type VolumeStatus = "available" | "creating";

/**
 * 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 a Volume can attach to at create time. Accepts a
 * `Hetzner.Server` resource or a `{ serverId }` stub.
 */
export type VolumeServer = { readonly serverId: number };

export interface VolumeProps {
  /**
   * Size of the Volume in GB. Minimum 10, maximum 10240. Increasing size
   * updates in place (Hetzner cannot shrink a Volume — decreasing it
   * replaces).
   */
  size: number;
  /**
   * Filesystem to format on create. One of `ext4` or `xfs`. Cannot be
   * changed after creation — changing it replaces the Volume.
   */
  format?: VolumeFormat;
  /**
   * Location to create the Volume in (`nbg1`, `fsn1`, `hel1`, …). Required
   * unless `server` is set (the Volume is then created in the Server's
   * location). Cannot be changed after creation.
   *
   * @default "nbg1"
   */
  location?: string;
  /**
   * Volume name. Must be unique per project, 1–64 characters, alphanumeric
   * with dashes/underscores/dots, starting and ending alphanumeric. If
   * omitted, a unique name is generated from the stack, stage and logical
   * ID.
   */
  name?: string;
  /**
   * User-defined labels. Alchemy ownership labels (`alchemy.stack` /
   * `alchemy.stage` / `alchemy.id`) are always merged in.
   */
  labels?: Record<string, string>;
  /**
   * Server to attach the Volume to at create time. Accepts a
   * `Hetzner.Server` or `{ serverId }`. Location may be omitted when this
   * is set. Subsequent attach/detach is reconciled from the observed
   * server.
   */
  server?: Ref<VolumeServer>;
  /**
   * Auto-mount the Volume after attach. Only used when `server` is set.
   *
   * @default false
   */
  automount?: boolean;
}

export type Volume = Resource<
  "Hetzner.Volume",
  VolumeProps,
  {
    /** Numeric Hetzner Volume ID. */
    id: number;
    /** Volume name (unique per project). */
    name: string;
    /** Size in GB. */
    size: number;
    /** Filesystem if formatted on creation. */
    format: VolumeFormat | undefined;
    /** Location name (`nbg1`, `fsn1`, …). */
    location: string;
    /** Numeric location ID. */
    locationId: number;
    /** Device path on the file system (e.g. `/dev/disk/by-id/scsi-…`). */
    linuxDevice: string;
    /** Volume status. */
    status: VolumeStatus;
    /** Attached Server ID, or `null` if unattached. */
    serverId: number | null;
    /** RFC3339 creation timestamp. */
    created: string;
    /** User-defined labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
  },
  never,
  Providers
>;

/**
 * A Hetzner Cloud Volume — a network block device that can be attached to
 * a Server in the same Location. Unattached Volumes are valid; pass
 * `server` to attach at create time.
 *
 * Size can grow in place (min 10 GB). Format and location are immutable
 * (changing either replaces the Volume). Hetzner cannot shrink a Volume.
 *
 * @see https://docs.hetzner.cloud/reference/cloud#volumes
 *
 * ### Creating a Volume
 * **Example:** Unattached Volume
 * ```typescript
 * const volume = yield* Hetzner.Volume("data", {
 *   size: 10,
 *   format: "ext4",
 *   location: "nbg1",
 * });
 * ```
 *
 * **Example:** Named Volume with labels
 * ```typescript
 * const volume = yield* Hetzner.Volume("data", {
 *   name: "app-data",
 *   size: 20,
 *   format: "xfs",
 *   location: "nbg1",
 *   labels: { role: "db" },
 * });
 * ```
 *
 * ### Attaching to a Server
 * **Example:** Create-time attach
 * ```typescript
 * const server = yield* Hetzner.Server("web", {
 *   serverType: "cx22",
 *   image: "ubuntu-24.04",
 *   location: "nbg1",
 * });
 * const volume = yield* Hetzner.Volume("data", {
 *   size: 10,
 *   format: "ext4",
 *   server,
 *   automount: true,
 * });
 * ```
 *
 * @resource
 * @product Volume
 */
export const Volume = Resource<Volume>("Hetzner.Volume");

type CloudVolume = GetVolumeResponseVolume | ListVolumesResponseVolumesItem;

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

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

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

const asFormat = (format: string | null | undefined): VolumeFormat | undefined =>
  format === "ext4" || format === "xfs" ? format : undefined;

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

const toAttrs = (volume: CloudVolume): Volume["Attributes"] => ({
  id: volume.id,
  name: volume.name,
  size: volume.size,
  format: asFormat(volume.format),
  location: volume.location.name,
  locationId: volume.location.id,
  linuxDevice: volume.linux_device,
  status: volume.status,
  serverId: volume.server,
  created: volume.created,
  labels: userLabels(volume.labels),
});

const retryable = (e: { readonly _tag: string }): boolean =>
  e._tag === "VolumePending" ||
  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 createVolumeName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return name ?? existing ?? (yield* createPhysicalName({ id, maxLength: MAX_NAME_LENGTH }));
  });

const getById = (id: number) =>
  Hetzner.volumes.getVolume({ id }).pipe(
    Effect.map(({ volume }) => volume),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const getByName = (name: string) =>
  Hetzner.volumes
    .listVolumes({ name, per_page: 50 })
    .pipe(Effect.map(({ volumes }) => volumes.find((item) => item.name === name)));

const getByLabels = (labels: Record<string, string>) =>
  Hetzner.volumes
    .listVolumes({ label_selector: labelSelector(labels), per_page: 50 })
    .pipe(Effect.map(({ volumes }) => volumes[0]));

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

const waitUntilAvailable = (volumeId: number) =>
  Hetzner.volumes.getVolume({ id: volumeId }).pipe(
    Effect.flatMap(({ volume }) =>
      volume.status === "available"
        ? Effect.succeed(volume)
        : Effect.fail(new VolumePending({ volumeId: volume.id, status: volume.status })),
    ),
    Effect.retry({ while: retryable, times: 10, schedule: backoff }),
    Effect.catchTag(
      "VolumePending",
      (e) => new VolumeTimeout({ volumeId: e.volumeId, status: e.status }),
    ),
  );

const settleAction = (action: Parameters<typeof waitForAction>[0]) =>
  waitForAction(action).pipe(Effect.catchTag("ActionTimeout", () => Effect.void));

const settleActions = (actions: Parameters<typeof waitForActions>[0]) =>
  waitForActions(actions).pipe(Effect.catchTag("ActionTimeout", () => Effect.void));

const waitUntilGone = (volumeId: number) =>
  Hetzner.volumes.getVolume({ id: volumeId }).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;
};

export const VolumeProvider = () =>
  Provider.succeed(Volume, {
    stables: ["id", "linuxDevice", "location", "locationId", "created"],
    list: Effect.fn(function* () {
      const items = yield* Hetzner.volumes.listVolumes
        .items({ 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) {
        if (news.location !== undefined && news.location !== output.location) {
          return { action: "replace" } as const;
        }
        if (news.format !== undefined && news.format !== output.format) {
          return { action: "replace" } as const;
        }
        if (news.size < output.size) {
          return { action: "replace" } as const;
        }
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, olds, output }) {
      const found = yield* observe({ id, name: olds?.name ?? output?.name, 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 name = yield* createVolumeName(id, news.name, output?.name);
      const internalLabels = yield* createInternalLabels(id);
      const desiredLabels = { ...toLabels(news.labels), ...internalLabels };
      const desiredServerId = serverIdOf(news.server);
      const location =
        news.location ?? (desiredServerId === undefined ? DEFAULT_LOCATION : undefined);

      // Observe by id then desired name only. Do not fall back to
      // ownership labels — a create-first replacement still has the old
      // generation live under the same logical id.
      let current = output?.id !== undefined ? yield* getById(output.id) : undefined;
      if (current === undefined) {
        current = yield* getByName(name);
      }

      // Ensure — create only when missing. A Conflict is a race with a
      // peer reconciler or a name that just became visible; re-observe.
      if (current === undefined) {
        const created = yield* Hetzner.volumes
          .createVolume({
            name,
            size: Math.max(news.size, MIN_SIZE_GB),
            format: news.format,
            location,
            labels: desiredLabels,
            server: desiredServerId,
            automount: desiredServerId !== undefined ? news.automount : undefined,
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          if (created.action) {
            yield* settleActions([created.action, ...created.next_actions]);
          }
          current = yield* waitUntilAvailable(created.volume.id);
        } else {
          const hit = yield* getByName(name);
          if (hit === undefined) {
            return yield* new VolumeNotCreated({ resourceName: name });
          }
          current = yield* waitUntilAvailable(hit.id);
        }
      }

      // Sync name + labels against observed cloud labels, not olds.
      // updateVolume overwrites the full label set.
      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const needsMeta = current.name !== name || upsert.length > 0 || removed.length > 0;
      if (needsMeta) {
        const updated = yield* Hetzner.volumes.updateVolume({
          id: current.id,
          name,
          labels: desiredLabels,
        });
        current = updated.volume;
      }

      // Sync size — grow only. Shrink is a replacement (handled in diff).
      if (news.size > current.size) {
        const { action } = yield* Hetzner.volumeActions.resizeVolume({
          id: current.id,
          size: news.size,
        });
        yield* settleAction(action);
        current = yield* waitUntilAvailable(current.id);
      }

      // Sync attach — create-time sugar also applies on later updates.
      const observedServerId = current.server ?? undefined;
      if (desiredServerId !== observedServerId) {
        if (observedServerId !== undefined) {
          const { action } = yield* Hetzner.volumeActions.detachVolume({ id: current.id });
          yield* settleAction(action);
          current = yield* waitUntilAvailable(current.id);
        }
        if (desiredServerId !== undefined) {
          const { action } = yield* Hetzner.volumeActions.attachVolume({
            id: current.id,
            server: desiredServerId,
            automount: news.automount,
          });
          yield* settleAction(action);
          current = yield* waitUntilAvailable(current.id);
        }
      }

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

      if (current.protection.delete) {
        const { action } = yield* Hetzner.volumeActions.changeVolumeProtection({
          id: current.id,
          delete: false,
        });
        yield* settleAction(action);
      }

      const attached = current.server;
      if (attached !== null) {
        yield* Hetzner.volumeActions.detachVolume({ id: current.id }).pipe(
          Effect.flatMap(({ action }) => settleAction(action)),
          // Server delete detaches the Volume first; treat that race as
          // already-detached.
          Effect.catchTag(["NotFound", "UnprocessableEntity"], () => Effect.void),
        );
      }

      yield* Hetzner.volumes.deleteVolume({ id: current.id }).pipe(
        Effect.catchTag("NotFound", () => Effect.void),
        Effect.retry({
          while: (e) => retryable(e) || e._tag === "UnprocessableEntity",
          times: 8,
          schedule: backoff,
        }),
      );
      yield* waitUntilGone(current.id);
    }),
  });