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

main
ts 315 lines 8.28 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { Resource } from "alchemy/Resource";
3 import * as Effect from "effect/Effect";
4 import * as Layer from "effect/Layer";
5
6 /**
7 * Spec for a per-replica Fly disk. Fly Volumes cannot be shared —
8 * `count` Machines get `count` Volumes in one name-group.
9 */
10 export interface DiskSpec {
11 /**
12 * Absolute path inside the Machine the disk is mounted at
13 * (e.g. `/data`).
14 */
15 path: string;
16 /**
17 * Size in GB. Fly minimum is 1. Increasing size updates in place
18 * via `extendVolume`. Fly cannot shrink a Volume.
19 */
20 sizeGb: number;
21 /**
22 * Encrypt the Volume at rest. Create-only.
23 */
24 encrypted?: boolean;
25 /**
26 * Filesystem type (`ext4`, …). Create-only.
27 */
28 fstype?: string;
29 /**
30 * Enable scheduled automatic snapshots.
31 *
32 * @default true
33 */
34 autoBackupEnabled?: boolean;
35 /**
36 * Snapshot retention in days. Updated in place via `updateVolume`.
37 */
38 snapshotRetention?: number;
39 /**
40 * Restore from an existing snapshot. Create-only.
41 */
42 snapshotId?: string;
43 /**
44 * Fork from an existing volume. Create-only.
45 */
46 sourceVolumeId?: string;
47 /**
48 * Require the Volume to land in a unique zone. Create-only.
49 */
50 requireUniqueZone?: boolean;
51 /**
52 * Fly volume-group name. If omitted, a unique name is generated
53 * from the host's logical ID and {@link path}.
54 */
55 name?: string;
56 }
57
58 export interface MountVolumeOptions extends DiskSpec {}
59
60 /**
61 * Runtime view of a disk mounted into a {@link Service}: the path
62 * inside the Machine.
63 */
64 export interface MountedVolume {
65 /** Mount path inside the Machine (same value as {@link DiskSpec.path}). */
66 path: string;
67 }
68
69 /**
70 * Observed disk attached to a Machine / Service replica.
71 */
72 export interface MountedDisk {
73 /** Mount path inside the Machine. */
74 path: string;
75 /** Fly Volume id. */
76 volumeId: string;
77 /** Size in GB. */
78 sizeGb: number;
79 /** Fly volume-group name. */
80 name: string;
81 }
82
83 const isBindHost = (value: unknown): value is Resource<string, any, any, ServiceBinding> =>
84 typeof value === "object" &&
85 value !== null &&
86 ((value as { Type?: string }).Type === "Fly.Service" ||
87 (value as { Type?: string }).Type === "Fly.Machine");
88
89 /**
90 * Binding contract accepted by {@link Service} (and Machine) for mounted
91 * disks and injected env.
92 */
93 export interface ServiceBinding {
94 env?: Record<string, any>;
95 mounts?: DiskSpec[];
96 /**
97 * Upstash Redis add-on to attach. Redis HTTP bindings write
98 * `REDIS_URL` as an App secret during Service reconcile.
99 */
100 redis?: { name: string; id?: string };
101 /**
102 * Tigris bucket to attach. Object HTTP bindings write `AWS_*` /
103 * `BUCKET_NAME` as App secrets during Service reconcile.
104 */
105 bucket?: { name: string; id?: string };
106 /**
107 * Managed Postgres cluster to attach. `Fly.ConnectPostgres` records
108 * the MPG attachment during Service reconcile. Connection URIs travel
109 * as Outputs (`yield* postgres.connectionUri`), not bind env.
110 */
111 postgres?: { clusterId: string; variableName?: string };
112 /**
113 * Another Service this one calls, recorded by `Fly.bindService` and
114 * `Fly.bindEndpoint`. Service reconcile checks the target is reachable
115 * from this Service's network and, for an endpoint, that the port is
116 * published.
117 */
118 target?: BoundTarget;
119 }
120
121 /** A Service bound by `Fly.bindService` or `Fly.bindEndpoint`. */
122 export interface BoundTarget {
123 /** Logical id of the bound Service. */
124 service: string;
125 /** Fly App the bound Service runs in. */
126 appName: string;
127 /** Private network of that App. `undefined` for the default network. */
128 network: string | undefined;
129 /** The bound Service's private address; `undefined` when it publishes nothing. */
130 privateUrl: string | undefined;
131 /** The bound Service's caller token. */
132 rpcToken?: import("effect/Redacted").Redacted<string>;
133 /** Port `Fly.bindEndpoint` targets; the binding port for `bindService`. */
134 port?: number;
135 /** Ports the bound Service publishes, for `Fly.bindEndpoint`. */
136 endpoints?: Array<{ port: number; handlers: string[] }>;
137 }
138
139 /**
140 * Create a per-replica Fly Volume and mount it into a {@link Service}.
141 *
142 * There is no standalone Volume resource. From a {@link Machine}, pass
143 * `mounts: [{ path, sizeGb }]` instead.
144 *
145 *
146 * ### Mount into a Service
147 * Yield `MountVolume` inside init. App and region come from the
148 * parent Service. Provide {@link MountVolumeLive}. At runtime you get
149 * `disk.path`.
150 *
151 * A Volume attaches to one Machine. `count: 3` creates three Volumes
152 * in one name-group, one per replica.
153 *
154 * **Example:** Bind a path
155 * ```typescript
156 * export default class Api extends Fly.Service<Api>()(
157 * "Api",
158 * { app: Site, main: import.meta.url, region: "iad", count: 3, port: 3000 },
159 * Effect.gen(function* () {
160 * const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
161 * const fs = yield* FileSystem.FileSystem;
162 * return {
163 * fetch: Effect.gen(function* () {
164 * const text = yield* fs.readFileString(`${disk.path}/hello.txt`);
165 * return HttpServerResponse.text(text);
166 * }),
167 * };
168 * }).pipe(Effect.provide(Fly.MountVolumeLive)),
169 * ) {}
170 * ```
171 *
172 * ### Grow a disk
173 * `sizeGb` can grow in place via `extendVolume`. Fly cannot shrink a
174 * Volume. Minimum size is 1 GB.
175 *
176 * **Example:** 10 GB
177 * ```typescript
178 * const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 10 });
179 * ```
180 *
181 * ### Encryption
182 * `encrypted` encrypts the Volume at rest.
183 *
184 * **Example:** Encrypted
185 * ```typescript
186 * const disk = yield* Fly.MountVolume({
187 * path: "/data",
188 * sizeGb: 1,
189 * encrypted: true,
190 * });
191 * ```
192 *
193 * :::note[Create-only]
194 * Flipping `encrypted` later is ignored.
195 * :::
196 *
197 * ### Filesystem
198 * `fstype` is the filesystem (`ext4`, …).
199 *
200 * **Example:** ext4
201 * ```typescript
202 * const disk = yield* Fly.MountVolume({
203 * path: "/data",
204 * sizeGb: 1,
205 * fstype: "ext4",
206 * });
207 * ```
208 *
209 * :::note[Create-only]
210 * Flipping `fstype` later is ignored.
211 * :::
212 *
213 * ### Scheduled snapshots
214 * Scheduled snapshots default on (`autoBackupEnabled`).
215 * `snapshotRetention` is days and updates in place. An on-demand
216 * snapshot is {@link VolumeSnapshot}.
217 *
218 * **Example:** Retention
219 * ```typescript
220 * const disk = yield* Fly.MountVolume({
221 * path: "/data",
222 * sizeGb: 1,
223 * autoBackupEnabled: true,
224 * snapshotRetention: 5,
225 * });
226 * ```
227 *
228 * ### Restore from a snapshot
229 * `snapshotId` restores into a new disk.
230 *
231 * **Example:** snapshotId
232 * ```typescript
233 * const disk = yield* Fly.MountVolume({
234 * path: "/data",
235 * sizeGb: 1,
236 * snapshotId: Nightly.snapshotId,
237 * });
238 * ```
239 *
240 * :::note[Create-only]
241 * Changing `snapshotId` later is ignored.
242 * :::
243 *
244 * ### Fork a volume
245 * `sourceVolumeId` forks from an existing Volume.
246 *
247 * **Example:** sourceVolumeId
248 * ```typescript
249 * const disk = yield* Fly.MountVolume({
250 * path: "/data",
251 * sizeGb: 1,
252 * sourceVolumeId: box.mounts[0].volumeId,
253 * });
254 * ```
255 *
256 * :::note[Create-only]
257 * Changing `sourceVolumeId` later is ignored.
258 * :::
259 *
260 * ### Unique zone
261 * `requireUniqueZone` asks Fly to land the Volume in a unique zone.
262 *
263 * **Example:** Unique zone
264 * ```typescript
265 * const disk = yield* Fly.MountVolume({
266 * path: "/data",
267 * sizeGb: 1,
268 * requireUniqueZone: true,
269 * });
270 * ```
271 *
272 * :::note[Create-only]
273 * Flipping `requireUniqueZone` later is ignored.
274 * :::
275 *
276 * ### Volume name
277 * `name` is the Fly volume-group name. If omitted, a unique name is
278 * generated from the host's logical ID and `path`.
279 *
280 * **Example:** Named group
281 * ```typescript
282 * const disk = yield* Fly.MountVolume({
283 * path: "/data",
284 * sizeGb: 1,
285 * name: "api_data",
286 * });
287 * ```
288 *
289 * @binding
290 * @product Volume
291 */
292 export interface MountVolume extends Binding.Service<
293 MountVolume,
294 "Fly.MountVolume",
295 (options: MountVolumeOptions) => Effect.Effect<MountedVolume>
296 > {}
297
298 export const MountVolume = Binding.Service<MountVolume>("Fly.MountVolume");
299
300 export const MountVolumeLive = Layer.effect(
301 MountVolume,
302 Effect.succeed(
303 Effect.fn(function* (options: MountVolumeOptions) {
304 if (!globalThis.__ALCHEMY_RUNTIME__) {
305 const host = yield* Binding.Host;
306 if (isBindHost(host)) {
307 yield* host.bind`Fly.MountVolume(${options.path})`({
308 mounts: [options],
309 });
310 }
311 }
312 return { path: options.path };
313 }),
314 ),
315 );