@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 321 lines 10.8 KB
Raw
1 import type { VolumeSnapshot as FlyVolumeSnapshot } from "@distilled.cloud/fly-io/machines";
2 import * as machines from "@distilled.cloud/fly-io/machines";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Duration from "effect/Duration";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import type { App } from "./App.ts";
11 import type { Providers } from "./Providers.ts";
12 import { listOwnedVolumes } from "./Volume.ts";
13
14 /**
15 * A resource-valued prop: the resource itself, or an Effect that produces
16 * it (so `yield* App(...)` and `App(...)` both type-check).
17 */
18 type Ref<T> = T | Effect.Effect<T, never, Providers>;
19
20 export interface VolumeSnapshotProps {
21 /**
22 * Parent Fly App. Changing it replaces the snapshot (a new snapshot is
23 * created on the new App's Volume). There is no delete API for the old
24 * snapshot — it follows Volume `snapshot_retention`.
25 */
26 app: Ref<App>;
27 /**
28 * Fly Volume id to snapshot (`vol_…`). Changing it replaces the
29 * snapshot. Identity is the snapshot `id` returned by a subsequent
30 * `listVolumeSnapshots`.
31 */
32 volumeId: string;
33 }
34
35 export type VolumeSnapshot = Resource<
36 "Fly.VolumeSnapshot",
37 VolumeSnapshotProps,
38 {
39 /** Parent Fly App name. */
40 appName: string;
41 /** Fly Volume id this snapshot belongs to. */
42 volumeId: string;
43 /** Fly snapshot id (`vs_…`). Identity of the resource. */
44 snapshotId: string;
45 /** Observed snapshot status, if the API returned one. */
46 status: string | undefined;
47 /** Content digest of the snapshot. */
48 digest: string | undefined;
49 /** Snapshot size in bytes, if the API returned one. */
50 size: number | undefined;
51 /** Source volume size in GB at snapshot time. */
52 volumeSize: number | undefined;
53 /** Retention in days. */
54 retentionDays: number | undefined;
55 /** RFC3339 creation timestamp. */
56 createdAt: string | undefined;
57 },
58 never,
59 Providers
60 >;
61
62 /**
63 * A Fly.VolumeSnapshot is an on-demand snapshot of a mounted disk.
64 *
65 * Create is fire-and-forget. Identity is the snapshot id from a
66 * subsequent list. Destroy is a no-op. Snapshots follow Volume
67 * retention. `nuke` skips this type.
68 *
69 * @see https://fly.io/docs/machines/api/volumes-resource/
70 *
71 * ### Create a snapshot
72 * Point it at a Volume id from the parent {@link Machine} or
73 * {@link Service} (`mounts[0].volumeId`).
74 *
75 * **Example:** Snapshot a mounted disk
76 * ```typescript
77 * const box = yield* Fly.Machine("Box", {
78 * app: Site,
79 * region: "iad",
80 * image: "nginx:alpine",
81 * mounts: [{ path: "/data", sizeGb: 1 }],
82 * });
83 *
84 * export const Nightly = Fly.VolumeSnapshot("Nightly", {
85 * app: Site,
86 * volumeId: box.mounts[0].volumeId,
87 * });
88 * ```
89 *
90 * :::caution[Changing `app` or `volumeId` replaces the snapshot]
91 * A new snapshot is created. There is no delete API for the old one.
92 * It follows Volume `snapshot_retention`.
93 * :::
94 *
95 * ### Restore
96 * Restore into a new disk with `snapshotId` on the mount. Create-only.
97 * The new Machine gets a copy. The original Volume is unchanged.
98 *
99 * **Example:** Restore onto a Machine
100 * ```typescript
101 * const restored = yield* Fly.Machine("Restored", {
102 * app: Site,
103 * region: "iad",
104 * image: "nginx:alpine",
105 * mounts: [{ path: "/data", sizeGb: 1, snapshotId: Nightly.snapshotId }],
106 * });
107 * ```
108 *
109 * ### Restore into a Service
110 * Pass `snapshotId` on {@link MountVolume}. Same create-only rule.
111 *
112 * **Example:** Restore onto a Service
113 * ```typescript
114 * export default class Api extends Fly.Service<Api>()(
115 * "Api",
116 * { app: Site, main: import.meta.url, region: "iad", port: 3000 },
117 * Effect.gen(function* () {
118 * const disk = yield* Fly.MountVolume({
119 * path: "/data",
120 * sizeGb: 1,
121 * snapshotId: Nightly.snapshotId,
122 * });
123 * return {
124 * fetch: Effect.succeed(HttpServerResponse.text(disk.path)),
125 * };
126 * }).pipe(Effect.provide(Fly.MountVolumeLive)),
127 * ) {}
128 * ```
129 *
130 * @resource
131 * @product Volume
132 */
133 export const VolumeSnapshot = Resource<VolumeSnapshot>("Fly.VolumeSnapshot");
134
135 export class VolumeSnapshotNotCreated extends Data.TaggedError("Fly.VolumeSnapshotNotCreated")<{
136 appName: string;
137 volumeId: string;
138 }> {}
139
140 export class VolumeSnapshotRefsMissing extends Data.TaggedError("Fly.VolumeSnapshotRefsMissing")<{
141 message: string;
142 }> {}
143
144 class VolumeSnapshotPending extends Data.TaggedError("Fly.VolumeSnapshotPending")<{
145 volumeId: string;
146 }> {}
147
148 const backoff = Schedule.min([
149 Schedule.exponential(Duration.millis(500), 1.5),
150 Schedule.spaced(Duration.seconds(5)),
151 ]);
152
153 const appNameOf = (value: unknown): string | undefined => {
154 if (value == null || typeof value !== "object") return undefined;
155 const name = (value as { appName?: unknown }).appName;
156 return typeof name === "string" && name.length > 0 ? name : undefined;
157 };
158
159 const volumeIdOf = (value: unknown): string | undefined => {
160 if (typeof value === "string" && value.length > 0) return value;
161 if (value == null || typeof value !== "object") return undefined;
162 const id = (value as { volumeId?: unknown }).volumeId;
163 return typeof id === "string" && id.length > 0 ? id : undefined;
164 };
165
166 const toAttrs = (
167 appName: string,
168 volumeId: string,
169 snapshot: FlyVolumeSnapshot,
170 ): VolumeSnapshot["Attributes"] => ({
171 appName,
172 volumeId,
173 snapshotId: snapshot.id ?? "",
174 status: snapshot.status,
175 digest: snapshot.digest,
176 size: snapshot.size,
177 volumeSize: snapshot.volume_size,
178 retentionDays: snapshot.retention_days,
179 createdAt: snapshot.created_at,
180 });
181
182 const listSnapshots = (appName: string, volumeId: string) =>
183 machines
184 .listVolumeSnapshots({
185 app_name: appName,
186 volume_id: volumeId,
187 })
188 .pipe(
189 Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([] as FlyVolumeSnapshot[])),
190 );
191
192 const findById = (appName: string, volumeId: string, snapshotId: string) =>
193 listSnapshots(appName, volumeId).pipe(
194 Effect.map((snapshots) => snapshots.find((snapshot) => snapshot.id === snapshotId)),
195 );
196
197 const newestFirst = (left: FlyVolumeSnapshot, right: FlyVolumeSnapshot) =>
198 Date.parse(right.created_at ?? "") - Date.parse(left.created_at ?? "");
199
200 const pickNewest = (snapshots: FlyVolumeSnapshot[]): FlyVolumeSnapshot | undefined =>
201 snapshots.filter((snapshot) => (snapshot.id ?? "").length > 0).sort(newestFirst)[0];
202
203 const waitForNewSnapshot = (appName: string, volumeId: string, knownIds: ReadonlySet<string>) =>
204 listSnapshots(appName, volumeId).pipe(
205 Effect.flatMap((snapshots) => {
206 const next = pickNewest(
207 snapshots.filter((snapshot) => snapshot.id !== undefined && !knownIds.has(snapshot.id)),
208 );
209 if (next !== undefined) return Effect.succeed(next);
210 return Effect.fail(new VolumeSnapshotPending({ volumeId }));
211 }),
212 Effect.retry({
213 while: (e) => e._tag === "Fly.VolumeSnapshotPending",
214 times: 8,
215 schedule: backoff,
216 }),
217 Effect.catchTag("Fly.VolumeSnapshotPending", () => Effect.undefined),
218 );
219
220 export const VolumeSnapshotProvider = () =>
221 Provider.succeed(VolumeSnapshot, {
222 stables: ["snapshotId", "volumeId", "appName"],
223 nuke: { skip: true },
224
225 diff: Effect.fn(function* ({ news, output }) {
226 if (news === undefined || !isResolved(news)) return undefined;
227 if (output === undefined) return undefined;
228 const desiredApp = appNameOf(news.app);
229 const appChanged = desiredApp !== undefined && desiredApp !== output.appName;
230 const desiredVolume = volumeIdOf(news.volumeId);
231 const volumeChanged = desiredVolume !== undefined && desiredVolume !== output.volumeId;
232 if (appChanged || volumeChanged) {
233 return { action: "replace" as const };
234 }
235 return undefined;
236 }),
237
238 read: Effect.fn(function* ({ olds, output }) {
239 const appName = output?.appName ?? appNameOf(olds?.app);
240 const volumeId = output?.volumeId ?? volumeIdOf(olds?.volumeId);
241 if (appName === undefined || volumeId === undefined) return undefined;
242 const snapshotId = output?.snapshotId;
243 if (snapshotId === undefined || snapshotId.length === 0) {
244 return undefined;
245 }
246 const found = yield* findById(appName, volumeId, snapshotId);
247 if (found === undefined) return undefined;
248 return toAttrs(appName, volumeId, found);
249 }),
250
251 list: Effect.fn(function* () {
252 const volumes = yield* listOwnedVolumes();
253 const groups = yield* Effect.forEach(
254 volumes,
255 ({ appName, volumeId }) =>
256 listSnapshots(appName, volumeId).pipe(
257 Effect.map((snapshots) =>
258 snapshots
259 .filter((snapshot) => snapshot.id !== undefined && snapshot.id.length > 0)
260 .map((snapshot) => toAttrs(appName, volumeId, snapshot)),
261 ),
262 ),
263 { concurrency: 8 },
264 );
265 return groups.flat();
266 }),
267
268 reconcile: Effect.fn(function* ({ news, output }) {
269 const props = news ?? ({} as VolumeSnapshotProps);
270 const appName = appNameOf(props.app) ?? output?.appName;
271 const volumeId = volumeIdOf(props.volumeId) ?? output?.volumeId;
272 if (appName === undefined || volumeId === undefined) {
273 return yield* new VolumeSnapshotRefsMissing({
274 message: "Fly.VolumeSnapshot requires a resolved App with appName and a volumeId.",
275 });
276 }
277
278 // Observe by cached snapshot id on the target volume.
279 const observed = yield* listSnapshots(appName, volumeId);
280 let current =
281 output?.snapshotId !== undefined && output.snapshotId.length > 0
282 ? observed.find((snapshot) => snapshot.id === output.snapshotId)
283 : undefined;
284
285 if (current === undefined) {
286 const knownIds = new Set(
287 observed.flatMap((snapshot) =>
288 snapshot.id !== undefined && snapshot.id.length > 0 ? [snapshot.id] : [],
289 ),
290 );
291 yield* machines
292 .createVolumeSnapshot({
293 app_name: appName,
294 volume_id: volumeId,
295 })
296 .pipe(
297 Effect.asVoid,
298 Effect.catchTag("Conflict", () => Effect.void),
299 Effect.retry({
300 while: (e) =>
301 e._tag === "NotFound" ||
302 (e._tag === "BadRequest" && e.message.includes("uninitialized volume")),
303 times: 8,
304 schedule: backoff,
305 }),
306 );
307 current = yield* waitForNewSnapshot(appName, volumeId, knownIds);
308 }
309
310 if (current === undefined || current.id === undefined) {
311 return yield* new VolumeSnapshotNotCreated({ appName, volumeId });
312 }
313
314 return toAttrs(appName, volumeId, current);
315 }),
316
317 delete: Effect.fn(function* () {
318 // Fly has no snapshot delete API. Snapshots expire with Volume
319 // snapshot_retention or when the Volume is deleted.
320 }),
321 });