sailfork / t3code-github / .repos/ alchemy-effect/ packages/ fly/ src/ VolumeSnapshot.ts

import type { VolumeSnapshot as FlyVolumeSnapshot } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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 type { App } from "./App.ts";
import type { Providers } from "./Providers.ts";
import { listOwnedVolumes } from "./Volume.ts";

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

export interface VolumeSnapshotProps {
  /**
   * Parent Fly App. Changing it replaces the snapshot (a new snapshot is
   * created on the new App's Volume). There is no delete API for the old
   * snapshot — it follows Volume `snapshot_retention`.
   */
  app: Ref<App>;
  /**
   * Fly Volume id to snapshot (`vol_…`). Changing it replaces the
   * snapshot. Identity is the snapshot `id` returned by a subsequent
   * `listVolumeSnapshots`.
   */
  volumeId: string;
}

export type VolumeSnapshot = Resource<
  "Fly.VolumeSnapshot",
  VolumeSnapshotProps,
  {
    /** Parent Fly App name. */
    appName: string;
    /** Fly Volume id this snapshot belongs to. */
    volumeId: string;
    /** Fly snapshot id (`vs_…`). Identity of the resource. */
    snapshotId: string;
    /** Observed snapshot status, if the API returned one. */
    status: string | undefined;
    /** Content digest of the snapshot. */
    digest: string | undefined;
    /** Snapshot size in bytes, if the API returned one. */
    size: number | undefined;
    /** Source volume size in GB at snapshot time. */
    volumeSize: number | undefined;
    /** Retention in days. */
    retentionDays: number | undefined;
    /** RFC3339 creation timestamp. */
    createdAt: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Fly.VolumeSnapshot is an on-demand snapshot of a mounted disk.
 *
 * Create is fire-and-forget. Identity is the snapshot id from a
 * subsequent list. Destroy is a no-op. Snapshots follow Volume
 * retention. `nuke` skips this type.
 *
 * @see https://fly.io/docs/machines/api/volumes-resource/
 *
 * ### Create a snapshot
 * Point it at a Volume id from the parent {@link Machine} or
 * {@link Service} (`mounts[0].volumeId`).
 *
 * **Example:** Snapshot a mounted disk
 * ```typescript
 * const box = yield* Fly.Machine("Box", {
 *   app: Site,
 *   region: "iad",
 *   image: "nginx:alpine",
 *   mounts: [{ path: "/data", sizeGb: 1 }],
 * });
 *
 * export const Nightly = Fly.VolumeSnapshot("Nightly", {
 *   app: Site,
 *   volumeId: box.mounts[0].volumeId,
 * });
 * ```
 *
 * :::caution[Changing `app` or `volumeId` replaces the snapshot]
 * A new snapshot is created. There is no delete API for the old one.
 * It follows Volume `snapshot_retention`.
 * :::
 *
 * ### Restore
 * Restore into a new disk with `snapshotId` on the mount. Create-only.
 * The new Machine gets a copy. The original Volume is unchanged.
 *
 * **Example:** Restore onto a Machine
 * ```typescript
 * const restored = yield* Fly.Machine("Restored", {
 *   app: Site,
 *   region: "iad",
 *   image: "nginx:alpine",
 *   mounts: [{ path: "/data", sizeGb: 1, snapshotId: Nightly.snapshotId }],
 * });
 * ```
 *
 * ### Restore into a Service
 * Pass `snapshotId` on {@link MountVolume}. Same create-only rule.
 *
 * **Example:** Restore onto a Service
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { app: Site, main: import.meta.url, region: "iad", port: 3000 },
 *   Effect.gen(function* () {
 *     const disk = yield* Fly.MountVolume({
 *       path: "/data",
 *       sizeGb: 1,
 *       snapshotId: Nightly.snapshotId,
 *     });
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text(disk.path)),
 *     };
 *   }).pipe(Effect.provide(Fly.MountVolumeLive)),
 * ) {}
 * ```
 *
 * @resource
 * @product Volume
 */
export const VolumeSnapshot = Resource<VolumeSnapshot>("Fly.VolumeSnapshot");

export class VolumeSnapshotNotCreated extends Data.TaggedError("Fly.VolumeSnapshotNotCreated")<{
  appName: string;
  volumeId: string;
}> {}

export class VolumeSnapshotRefsMissing extends Data.TaggedError("Fly.VolumeSnapshotRefsMissing")<{
  message: string;
}> {}

class VolumeSnapshotPending extends Data.TaggedError("Fly.VolumeSnapshotPending")<{
  volumeId: string;
}> {}

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

const appNameOf = (value: unknown): string | undefined => {
  if (value == null || typeof value !== "object") return undefined;
  const name = (value as { appName?: unknown }).appName;
  return typeof name === "string" && name.length > 0 ? name : undefined;
};

const volumeIdOf = (value: unknown): string | undefined => {
  if (typeof value === "string" && value.length > 0) return value;
  if (value == null || typeof value !== "object") return undefined;
  const id = (value as { volumeId?: unknown }).volumeId;
  return typeof id === "string" && id.length > 0 ? id : undefined;
};

const toAttrs = (
  appName: string,
  volumeId: string,
  snapshot: FlyVolumeSnapshot,
): VolumeSnapshot["Attributes"] => ({
  appName,
  volumeId,
  snapshotId: snapshot.id ?? "",
  status: snapshot.status,
  digest: snapshot.digest,
  size: snapshot.size,
  volumeSize: snapshot.volume_size,
  retentionDays: snapshot.retention_days,
  createdAt: snapshot.created_at,
});

const listSnapshots = (appName: string, volumeId: string) =>
  machines
    .listVolumeSnapshots({
      app_name: appName,
      volume_id: volumeId,
    })
    .pipe(
      Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([] as FlyVolumeSnapshot[])),
    );

const findById = (appName: string, volumeId: string, snapshotId: string) =>
  listSnapshots(appName, volumeId).pipe(
    Effect.map((snapshots) => snapshots.find((snapshot) => snapshot.id === snapshotId)),
  );

const newestFirst = (left: FlyVolumeSnapshot, right: FlyVolumeSnapshot) =>
  Date.parse(right.created_at ?? "") - Date.parse(left.created_at ?? "");

const pickNewest = (snapshots: FlyVolumeSnapshot[]): FlyVolumeSnapshot | undefined =>
  snapshots.filter((snapshot) => (snapshot.id ?? "").length > 0).sort(newestFirst)[0];

const waitForNewSnapshot = (appName: string, volumeId: string, knownIds: ReadonlySet<string>) =>
  listSnapshots(appName, volumeId).pipe(
    Effect.flatMap((snapshots) => {
      const next = pickNewest(
        snapshots.filter((snapshot) => snapshot.id !== undefined && !knownIds.has(snapshot.id)),
      );
      if (next !== undefined) return Effect.succeed(next);
      return Effect.fail(new VolumeSnapshotPending({ volumeId }));
    }),
    Effect.retry({
      while: (e) => e._tag === "Fly.VolumeSnapshotPending",
      times: 8,
      schedule: backoff,
    }),
    Effect.catchTag("Fly.VolumeSnapshotPending", () => Effect.undefined),
  );

export const VolumeSnapshotProvider = () =>
  Provider.succeed(VolumeSnapshot, {
    stables: ["snapshotId", "volumeId", "appName"],
    nuke: { skip: true },

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const desiredApp = appNameOf(news.app);
      const appChanged = desiredApp !== undefined && desiredApp !== output.appName;
      const desiredVolume = volumeIdOf(news.volumeId);
      const volumeChanged = desiredVolume !== undefined && desiredVolume !== output.volumeId;
      if (appChanged || volumeChanged) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const appName = output?.appName ?? appNameOf(olds?.app);
      const volumeId = output?.volumeId ?? volumeIdOf(olds?.volumeId);
      if (appName === undefined || volumeId === undefined) return undefined;
      const snapshotId = output?.snapshotId;
      if (snapshotId === undefined || snapshotId.length === 0) {
        return undefined;
      }
      const found = yield* findById(appName, volumeId, snapshotId);
      if (found === undefined) return undefined;
      return toAttrs(appName, volumeId, found);
    }),

    list: Effect.fn(function* () {
      const volumes = yield* listOwnedVolumes();
      const groups = yield* Effect.forEach(
        volumes,
        ({ appName, volumeId }) =>
          listSnapshots(appName, volumeId).pipe(
            Effect.map((snapshots) =>
              snapshots
                .filter((snapshot) => snapshot.id !== undefined && snapshot.id.length > 0)
                .map((snapshot) => toAttrs(appName, volumeId, snapshot)),
            ),
          ),
        { concurrency: 8 },
      );
      return groups.flat();
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const props = news ?? ({} as VolumeSnapshotProps);
      const appName = appNameOf(props.app) ?? output?.appName;
      const volumeId = volumeIdOf(props.volumeId) ?? output?.volumeId;
      if (appName === undefined || volumeId === undefined) {
        return yield* new VolumeSnapshotRefsMissing({
          message: "Fly.VolumeSnapshot requires a resolved App with appName and a volumeId.",
        });
      }

      // Observe by cached snapshot id on the target volume.
      const observed = yield* listSnapshots(appName, volumeId);
      let current =
        output?.snapshotId !== undefined && output.snapshotId.length > 0
          ? observed.find((snapshot) => snapshot.id === output.snapshotId)
          : undefined;

      if (current === undefined) {
        const knownIds = new Set(
          observed.flatMap((snapshot) =>
            snapshot.id !== undefined && snapshot.id.length > 0 ? [snapshot.id] : [],
          ),
        );
        yield* machines
          .createVolumeSnapshot({
            app_name: appName,
            volume_id: volumeId,
          })
          .pipe(
            Effect.asVoid,
            Effect.catchTag("Conflict", () => Effect.void),
            Effect.retry({
              while: (e) =>
                e._tag === "NotFound" ||
                (e._tag === "BadRequest" && e.message.includes("uninitialized volume")),
              times: 8,
              schedule: backoff,
            }),
          );
        current = yield* waitForNewSnapshot(appName, volumeId, knownIds);
      }

      if (current === undefined || current.id === undefined) {
        return yield* new VolumeSnapshotNotCreated({ appName, volumeId });
      }

      return toAttrs(appName, volumeId, current);
    }),

    delete: Effect.fn(function* () {
      // Fly has no snapshot delete API. Snapshots expire with Volume
      // snapshot_retention or when the Volume is deleted.
    }),
  });