1import type {
2 Checkpoint as FlyCheckpoint,
3 CreateCheckpointError,
4 GetCheckpointError,
5 ListCheckpointsError,
6 RestoreCheckpointError,
7 StreamEvent,
8} from "@distilled.cloud/fly-io/sprites";
9import type * as Effect from "effect/Effect";
10import * as Binding from "../Binding.ts";
11import type { RuntimeContext } from "../RuntimeContext.ts";
12import type { Sprite } from "./Sprite.ts";
13
14export interface CheckpointClient {
15 /**
16 * Create a checkpoint of the Sprite filesystem. Returns NDJSON
17 * progress events. The checkpoint id is in a `complete` event.
18 */
19 create: (options?: {
20 comment?: string;
21 }) => Effect.Effect<
22 ReadonlyArray<StreamEvent>,
23 CreateCheckpointError,
24 RuntimeContext
25 >;
26 /** List checkpoints on the Sprite. */
27 list: () => Effect.Effect<
28 ReadonlyArray<FlyCheckpoint>,
29 ListCheckpointsError,
30 RuntimeContext
31 >;
32 /** Get one checkpoint by id (`v1`, `v2`, …). */
33 get: (
34 checkpointId: string,
35 ) => Effect.Effect<FlyCheckpoint, GetCheckpointError, RuntimeContext>;
36 /**
37 * Restore the Sprite filesystem to a checkpoint. Destructive.
38 * Returns NDJSON progress events.
39 */
40 restore: (
41 checkpointId: string,
42 ) => Effect.Effect<
43 ReadonlyArray<StreamEvent>,
44 RestoreCheckpointError,
45 RuntimeContext
46 >;
47}
48
49/**
50 * Checkpoint and restore a {@link Sprite} filesystem.
51 *
52 *
53 * ### Create a checkpoint
54 * Bind the client in init. Provide {@link CheckpointHttp}.
55 *
56 * **Example:** Create
57 * ```typescript
58 * const checkpoint = yield* Fly.Checkpoint(Box);
59 * yield* checkpoint.create({ comment: "before deploy" });
60 * ```
61 *
62 * ### Restore
63 * Restore rewinds the filesystem. Running processes stop.
64 *
65 * **Example:** Restore v1
66 * ```typescript
67 * yield* checkpoint.restore("v1");
68 * ```
69 *
70 * :::caution[Restore is destructive]
71 * The Sprite disk goes back to that checkpoint. Later writes are gone.
72 * :::
73 *
74 * @binding
75 * @product Sprite
76 */
77export interface Checkpoint extends Binding.Service<
78 Checkpoint,
79 "Fly.Checkpoint",
80 (sprite: Sprite) => Effect.Effect<CheckpointClient>
81> {}
82
83export const Checkpoint = Binding.Service<Checkpoint>("Fly.Checkpoint");