@alchemy.run/fly 0.0.0 → 2.0.0-beta.85

package/lib/VerifyHttp.js

@@ -0,0 +1,38 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.js";
+import { bytesToBase64, makeHttpSecretKeyBinding } from "./SecretKeyHttp.js";
+import { Verify } from "./Verify.js";
+/**
+ * HTTP implementation of {@link Verify}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const verify = yield* Fly.Verify(Signing);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.VerifyHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret Key
+ * @provides Fly.Verify
+ */
+export const VerifyHttp = Layer.effect(Verify, Effect.suspend(() => makeHttpSecretKeyBinding({
+    makeClient: (auth, appName, secretName) => Effect.fn("Fly.Verify")(function* (request) {
+        // Fly answers 200 only when the signature checks out.
+        yield* auth.authorize(machines.verifySecretKey({
+            app_name: yield* appName,
+            secret_name: yield* secretName,
+            plaintext: bytesToBase64(request.plaintext),
+            signature: bytesToBase64(request.signature),
+        }));
+        return { valid: true };
+    }),
+}))).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));
+//# sourceMappingURL=VerifyHttp.js.map

package/lib/VerifyHttp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VerifyHttp.js","sourceRoot":"","sources":["../src/VerifyHttp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,kCAAkC,CAAC;AAC7D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CACpC,MAAM,EACN,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAClB,wBAAwB,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,CACxC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAsB;QACvD,sDAAsD;QACtD,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CACnB,QAAQ,CAAC,eAAe,CAAC;YACvB,QAAQ,EAAE,KAAK,CAAC,CAAC,OAAO;YACxB,WAAW,EAAE,KAAK,CAAC,CAAC,UAAU;YAC9B,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;YAC3C,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,IAAa,EAAE,CAAC;IAClC,CAAC,CAAC;CACL,CAAC,CACH,CACF,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC"}

package/lib/Volume.d.ts

@@ -0,0 +1,53 @@
+import type { Volume as FlyVolume } from "@distilled.cloud/fly-io/machines";
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import type { DiskSpec } from "./MountVolume.ts";
+export declare const DEFAULT_VOLUME_REGION = "iad";
+export declare const MIN_SIZE_GB = 1;
+declare const VolumeNotCreated_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.VolumeNotCreated";
+} & Readonly<A>;
+export declare class VolumeNotCreated extends VolumeNotCreated_base<{
+    resourceName: string;
+    appName: string;
+}> {
+}
+export declare const destroying: (state: string | undefined) => state is "destroyed" | "pending_destroy" | "scheduled_for_destruction";
+export declare const getVolumeById: (appName: string, volumeId: string) => Effect.Effect<FlyVolume | undefined, import("@distilled.cloud/fly-io").Forbidden | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const listVolumesByApp: (appName: string) => Effect.Effect<never[] | FlyVolume[], machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const listVolumeGroup: (appName: string, name: string, region: string) => Effect.Effect<FlyVolume[], machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const waitUntilVolumeReady: (appName: string, volumeId: string) => Effect.Effect<FlyVolume | undefined, import("@distilled.cloud/fly-io").Forbidden | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const waitUntilVolumeGone: (appName: string, volumeId: string) => Effect.Effect<boolean, import("@distilled.cloud/fly-io").Forbidden | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const pathKey: (path: string) => string;
+export declare const volumeGroupName: (id: string, disk: Pick<DiskSpec, "path" | "name">) => Effect.Effect<string, never, import("alchemy/ResourceContext").ResourceContext | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage>;
+export declare const createVolume: (input: {
+    appName: string;
+    name: string;
+    region: string;
+    disk: DiskSpec;
+}) => Effect.Effect<FlyVolume, import("@distilled.cloud/fly-io").BadRequest | import("@distilled.cloud/fly-io").Forbidden | import("@distilled.cloud/fly-io").NotFound | VolumeNotCreated | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const syncVolume: (appName: string, volume: FlyVolume, disk: DiskSpec) => Effect.Effect<FlyVolume, import("@distilled.cloud/fly-io").BadGateway | import("@distilled.cloud/fly-io").BadRequest | import("@distilled.cloud/fly-io").ConfigError | import("@distilled.cloud/fly-io").CreateExtensionTosAgreementNotAuthorized | import("@distilled.cloud/fly-io").FlyIoParseError | import("@distilled.cloud/fly-io").Forbidden | import("@distilled.cloud/fly-io").GatewayTimeout | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/fly-io").InternalServerError | import("@distilled.cloud/core/protocol-http").InvalidInput | import("@distilled.cloud/fly-io").NotFound | import("@distilled.cloud/fly-io").ServiceUnavailable | import("@distilled.cloud/fly-io").TooManyRequests | import("@distilled.cloud/fly-io").Unauthorized | import("@distilled.cloud/fly-io").UnknownFlyIoError, machines.FlyIoOpContext>;
+/**
+ * Observe-ensure-sync a Fly volume group (`name` shared, `count`
+ * independent volumes). Extras are left in place for the caller to
+ * delete after the Machines that mount them are gone.
+ */
+export declare const ensureVolumeGroup: (input: {
+    appName: string;
+    name: string;
+    region: string;
+    count: number;
+    disk: DiskSpec;
+    preferIds?: readonly string[];
+}) => Effect.Effect<{
+    volumes: FlyVolume[];
+    extras: FlyVolume[];
+}, import("@distilled.cloud/fly-io").BadRequest | import("@distilled.cloud/fly-io").Forbidden | import("@distilled.cloud/fly-io").NotFound | VolumeNotCreated | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const deleteVolume: (appName: string, volumeId: string) => Effect.Effect<void, import("@distilled.cloud/fly-io").Conflict | import("@distilled.cloud/fly-io").Forbidden | machines.VolumeAttached | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export declare const listOwnedVolumes: () => Effect.Effect<{
+    appName: string;
+    volumeId: string;
+    volume: FlyVolume;
+}[], import("./Environment.ts").FlyOrgNotFound | import("@distilled.cloud/fly-io").Forbidden | machines.FlyIoOpError, machines.FlyIoOpContext>;
+export {};
+//# sourceMappingURL=Volume.d.ts.map

package/lib/Volume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Volume.d.ts","sourceRoot":"","sources":["../src/Volume.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,QAAQ,MAAM,kCAAkC,CAAC;AAG7D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAQxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAC3C,eAAO,MAAM,WAAW,IAAI,CAAC;;;;AAE7B,qBAAa,gBAAiB,SAAQ,sBAAyC;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;CAAG;AAYL,eAAO,MAAM,UAAU,UAAW,MAAM,GAAG,SAAS,2EAC2C,CAAC;AAKhG,eAAO,MAAM,aAAa,YAAa,MAAM,YAAY,MAAM,uIAI5D,CAAC;AAEJ,eAAO,MAAM,gBAAgB,YAAa,MAAM,yFAI7C,CAAC;AAQJ,eAAO,MAAM,eAAe,YAAa,MAAM,QAAQ,MAAM,UAAU,MAAM,+EAO1E,CAAC;AAEJ,eAAO,MAAM,oBAAoB,YAAa,MAAM,YAAY,MAAM,uIAoBnE,CAAC;AAEJ,eAAO,MAAM,mBAAmB,YAAa,MAAM,YAAY,MAAM,yHAQlE,CAAC;AAEJ,eAAO,MAAM,OAAO,SAAU,MAAM,KAAG,MAMtC,CAAC;AAEF,eAAO,MAAM,eAAe,OAAQ,MAAM,QAAQ,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,oJAI7E,CAAC;AAEL,eAAO,MAAM,YAAY;aACd,MAAM;UACT,MAAM;YACJ,MAAM;UACR,QAAQ;2OA8Bd,CAAC;AAEH,eAAO,MAAM,UAAU,s4BA4BrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;aACnB,MAAM;UACT,MAAM;YACJ,MAAM;WACP,MAAM;UACP,QAAQ;gBACF,SAAS,MAAM,EAAE;;;;+MAqC7B,CAAC;AAEH,eAAO,MAAM,YAAY,iOAgBvB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;8IAkB3B,CAAC"}

package/lib/Volume.js

@@ -0,0 +1,188 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+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 { listOwnedApps } from "./App.js";
+import { createFlyVolumeName, matchesAlchemyPhysicalName, sanitizeFlyVolumeName, } from "./Metadata.js";
+export const DEFAULT_VOLUME_REGION = "iad";
+export const MIN_SIZE_GB = 1;
+export class VolumeNotCreated extends Data.TaggedError("Fly.VolumeNotCreated") {
+}
+class VolumePending extends Data.TaggedError("Fly.VolumePending") {
+}
+const backoff = Schedule.min([
+    Schedule.exponential(Duration.millis(500), 1.5),
+    Schedule.spaced(Duration.seconds(5)),
+]);
+export const destroying = (state) => state === "destroyed" || state === "pending_destroy" || state === "scheduled_for_destruction";
+const transientState = (state) => state === "creating" || state === "pending" || state === "extending";
+export const getVolumeById = (appName, volumeId) => machines.getVolumeById({ app_name: appName, volume_id: volumeId }).pipe(Effect.map((volume) => (destroying(volume.state) ? undefined : volume)), Effect.catchTag("NotFound", () => Effect.undefined));
+export const listVolumesByApp = (appName) => machines.listVolumes({ app_name: appName }).pipe(Effect.map((volumes) => volumes.filter((volume) => !destroying(volume.state))), Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([])));
+const newestFirst = (left, right) => {
+    const byCreated = Date.parse(left.created_at ?? "") - Date.parse(right.created_at ?? "");
+    if (byCreated !== 0)
+        return byCreated;
+    return (left.id ?? "").localeCompare(right.id ?? "");
+};
+export const listVolumeGroup = (appName, name, region) => listVolumesByApp(appName).pipe(Effect.map((volumes) => volumes
+    .filter((volume) => volume.name === name && volume.region === region)
+    .sort(newestFirst)));
+export const waitUntilVolumeReady = (appName, volumeId) => getVolumeById(appName, volumeId).pipe(Effect.flatMap((volume) => {
+    if (volume === undefined)
+        return Effect.undefined;
+    if (transientState(volume.state)) {
+        return Effect.fail(new VolumePending({
+            volumeId,
+            state: volume.state ?? "creating",
+        }));
+    }
+    return Effect.succeed(volume);
+}), Effect.retry({
+    while: (e) => e._tag === "Fly.VolumePending",
+    times: 8,
+    schedule: backoff,
+}), Effect.catchTag("Fly.VolumePending", () => getVolumeById(appName, volumeId)));
+export const waitUntilVolumeGone = (appName, volumeId) => getVolumeById(appName, volumeId).pipe(Effect.map((volume) => volume === undefined), Effect.repeat({
+    schedule: Schedule.spaced("2 seconds"),
+    until: (gone) => gone,
+    times: 10,
+}));
+export const pathKey = (path) => {
+    const key = path
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return key.length === 0 ? "data" : key;
+};
+export const volumeGroupName = (id, disk) => Effect.gen(function* () {
+    if (disk.name !== undefined)
+        return sanitizeFlyVolumeName(disk.name);
+    return yield* createFlyVolumeName(`${id}/${pathKey(disk.path)}`);
+});
+export const createVolume = Effect.fn(function* (input) {
+    const sizeGb = Math.max(input.disk.sizeGb, MIN_SIZE_GB);
+    const created = yield* machines
+        .createVolume({
+        app_name: input.appName,
+        name: input.name,
+        region: input.region,
+        size_gb: sizeGb,
+        encrypted: input.disk.encrypted,
+        fstype: input.disk.fstype,
+        auto_backup_enabled: input.disk.autoBackupEnabled,
+        snapshot_retention: input.disk.snapshotRetention,
+        snapshot_id: input.disk.snapshotId,
+        source_volume_id: input.disk.sourceVolumeId,
+        require_unique_zone: input.disk.requireUniqueZone,
+    })
+        .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
+    if (created?.id !== undefined && created.id.length > 0) {
+        return (yield* waitUntilVolumeReady(input.appName, created.id)) ?? created;
+    }
+    const group = yield* listVolumeGroup(input.appName, input.name, input.region);
+    const hit = group.at(-1);
+    if (hit === undefined || hit.id === undefined) {
+        return yield* new VolumeNotCreated({
+            resourceName: input.name,
+            appName: input.appName,
+        });
+    }
+    return (yield* waitUntilVolumeReady(input.appName, hit.id)) ?? hit;
+});
+export const syncVolume = Effect.fn(function* (appName, volume, disk) {
+    const volumeId = volume.id;
+    if (volumeId === undefined || volumeId.length === 0)
+        return volume;
+    let current = volume;
+    const sizeGb = Math.max(disk.sizeGb, MIN_SIZE_GB);
+    const observedSize = current.size_gb ?? 0;
+    if (sizeGb > observedSize) {
+        const extended = yield* machines.extendVolume({
+            app_name: appName,
+            volume_id: volumeId,
+            size_gb: sizeGb,
+        });
+        current = extended.volume ?? (yield* waitUntilVolumeReady(appName, volumeId)) ?? current;
+    }
+    const backupChanged = disk.autoBackupEnabled !== undefined && disk.autoBackupEnabled !== current.auto_backup_enabled;
+    const retentionChanged = disk.snapshotRetention !== undefined && disk.snapshotRetention !== current.snapshot_retention;
+    if (backupChanged || retentionChanged) {
+        current = yield* machines.updateVolume({
+            app_name: appName,
+            volume_id: volumeId,
+            auto_backup_enabled: disk.autoBackupEnabled,
+            snapshot_retention: disk.snapshotRetention,
+        });
+    }
+    return current;
+});
+/**
+ * Observe-ensure-sync a Fly volume group (`name` shared, `count`
+ * independent volumes). Extras are left in place for the caller to
+ * delete after the Machines that mount them are gone.
+ */
+export const ensureVolumeGroup = Effect.fn(function* (input) {
+    const prefer = new Set((input.preferIds ?? []).filter((id) => id.length > 0));
+    let group = yield* listVolumeGroup(input.appName, input.name, input.region);
+    const preferred = group.filter((volume) => volume.id !== undefined && prefer.has(volume.id));
+    const rest = group.filter((volume) => volume.id === undefined || !prefer.has(volume.id));
+    group = [...preferred, ...rest];
+    let attempts = 0;
+    while (group.length < input.count && attempts < input.count + 3) {
+        attempts += 1;
+        const created = yield* createVolume({
+            appName: input.appName,
+            name: input.name,
+            region: input.region,
+            disk: input.disk,
+        });
+        if (created.id !== undefined && !group.some((volume) => volume.id === created.id)) {
+            group.push(created);
+        }
+        else {
+            group = yield* listVolumeGroup(input.appName, input.name, input.region);
+        }
+    }
+    if (group.length < input.count) {
+        return yield* new VolumeNotCreated({
+            resourceName: input.name,
+            appName: input.appName,
+        });
+    }
+    const kept = group.slice(0, input.count);
+    const extras = group.slice(input.count);
+    const synced = [];
+    for (const volume of kept) {
+        synced.push(yield* syncVolume(input.appName, volume, input.disk));
+    }
+    return { volumes: synced, extras };
+});
+export const deleteVolume = Effect.fn(function* (appName, volumeId) {
+    if (appName.length === 0 || volumeId.length === 0)
+        return;
+    yield* machines
+        .deleteVolume({
+        app_name: appName,
+        volume_id: volumeId,
+    })
+        .pipe(Effect.catchTag("NotFound", () => Effect.void), Effect.retry({
+        while: (e) => e._tag === "Conflict",
+        times: 8,
+        schedule: backoff,
+    }));
+    yield* waitUntilVolumeGone(appName, volumeId);
+});
+export const listOwnedVolumes = Effect.fn(function* () {
+    const apps = yield* listOwnedApps();
+    const groups = yield* Effect.forEach(apps, (app) => listVolumesByApp(app.appName).pipe(Effect.map((volumes) => volumes.flatMap((volume) => {
+        if (!matchesAlchemyPhysicalName(volume.name))
+            return [];
+        const volumeId = volume.id;
+        if (volumeId === undefined || volumeId.length === 0)
+            return [];
+        return [{ appName: app.appName, volumeId, volume }];
+    }))), { concurrency: 8 });
+    return groups.flat();
+});
+//# sourceMappingURL=Volume.js.map

package/lib/Volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Volume.js","sourceRoot":"","sources":["../src/Volume.ts"],"names":[],"mappings":"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"}

package/lib/VolumeSnapshot.d.ts

@@ -0,0 +1,135 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { App } from "./App.ts";
+import type { Providers } from "./Providers.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 declare const VolumeSnapshot: import("alchemy/Resource").ResourceClass<VolumeSnapshot>;
+declare const VolumeSnapshotNotCreated_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.VolumeSnapshotNotCreated";
+} & Readonly<A>;
+export declare class VolumeSnapshotNotCreated extends VolumeSnapshotNotCreated_base<{
+    appName: string;
+    volumeId: string;
+}> {
+}
+declare const VolumeSnapshotRefsMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.VolumeSnapshotRefsMissing";
+} & Readonly<A>;
+export declare class VolumeSnapshotRefsMissing extends VolumeSnapshotRefsMissing_base<{
+    message: string;
+}> {
+}
+export declare const VolumeSnapshotProvider: () => import("effect/Layer").Layer<Provider.Provider<VolumeSnapshot>, never, machines.FlyIoOpContext>;
+export {};
+//# sourceMappingURL=VolumeSnapshot.d.ts.map

package/lib/VolumeSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VolumeSnapshot.d.ts","sourceRoot":"","sources":["../src/VolumeSnapshot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,kCAAkC,CAAC;AAE7D,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;;GAGG;AACH,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACd;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,CACnC,oBAAoB,EACpB,mBAAmB,EACnB;IACE,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,sCAAsC;IACtC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,iDAAiD;IACjD,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yBAAyB;IACzB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,kCAAkC;IAClC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,EACD,KAAK,EACL,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,eAAO,MAAM,cAAc,0DAAiD,CAAC;;;;AAE7E,qBAAa,wBAAyB,SAAQ,8BAAiD;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;CAAG;;;;AAEL,qBAAa,yBAA0B,SAAQ,+BAAkD;IAC/F,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;CAAG;AA8EL,eAAO,MAAM,sBAAsB,uGAqG/B,CAAC"}

package/lib/VolumeSnapshot.js

@@ -0,0 +1,213 @@
+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 { listOwnedVolumes } from "./Volume.js";
+/**
+ * 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("Fly.VolumeSnapshot");
+export class VolumeSnapshotNotCreated extends Data.TaggedError("Fly.VolumeSnapshotNotCreated") {
+}
+export class VolumeSnapshotRefsMissing extends Data.TaggedError("Fly.VolumeSnapshotRefsMissing") {
+}
+class VolumeSnapshotPending extends Data.TaggedError("Fly.VolumeSnapshotPending") {
+}
+const backoff = Schedule.min([
+    Schedule.exponential(Duration.millis(500), 1.5),
+    Schedule.spaced(Duration.seconds(5)),
+]);
+const appNameOf = (value) => {
+    if (value == null || typeof value !== "object")
+        return undefined;
+    const name = value.appName;
+    return typeof name === "string" && name.length > 0 ? name : undefined;
+};
+const volumeIdOf = (value) => {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value == null || typeof value !== "object")
+        return undefined;
+    const id = value.volumeId;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+};
+const toAttrs = (appName, volumeId, snapshot) => ({
+    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, volumeId) => machines
+    .listVolumeSnapshots({
+    app_name: appName,
+    volume_id: volumeId,
+})
+    .pipe(Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([])));
+const findById = (appName, volumeId, snapshotId) => listSnapshots(appName, volumeId).pipe(Effect.map((snapshots) => snapshots.find((snapshot) => snapshot.id === snapshotId)));
+const newestFirst = (left, right) => Date.parse(right.created_at ?? "") - Date.parse(left.created_at ?? "");
+const pickNewest = (snapshots) => snapshots.filter((snapshot) => (snapshot.id ?? "").length > 0).sort(newestFirst)[0];
+const waitForNewSnapshot = (appName, volumeId, knownIds) => 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" };
+        }
+        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 ?? {};
+        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.
+    }),
+});
+//# sourceMappingURL=VolumeSnapshot.js.map