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

main
ts 166 lines 5.08 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { Resource } from "alchemy/Resource";
3 import * as Data from "effect/Data";
4 import * as Effect from "effect/Effect";
5 import * as Layer from "effect/Layer";
6 import type { Volume } from "./Volume.ts";
7
8 export interface MountVolumeOptions {
9 /**
10 * Absolute path inside the container the Volume is mounted at
11 * (e.g. `/data`).
12 */
13 path: string;
14 }
15
16 /**
17 * Runtime view of a Volume mounted into a {@link Service} or
18 * `Railway.Function`: the path inside the container.
19 */
20 export interface MountedVolume {
21 /** Mount path inside the container (same value as {@link MountVolumeOptions.path}). */
22 path: string;
23 }
24
25 /**
26 * A volume mount injected onto a {@link Service} via {@link MountVolume}.
27 * Service reconcile attaches it with `volumeInstanceUpdate`.
28 */
29 export interface MountSpec {
30 /** Railway volume id (not the instance id). */
31 volumeId: string;
32 /** Absolute path inside the container. */
33 path: string;
34 }
35
36 // Pass `volume.volumeId` through as-is. At bind time it is an Output,
37 // never a materialized string — `typeof === "string"` would store `""`
38 // and every downstream guard would skip the mount. `Input<Binding>`
39 // resolves the Output before reconcile.
40 const volumeIdOf = (volume: Volume) => volume.volumeId ?? "";
41
42 const RAILWAY_BIND_HOST_TYPES = new Set(["Railway.Service", "Railway.Function"]);
43
44 /**
45 * True for a Railway compute host that accepts {@link ServiceBinding}
46 * (`Railway.Service` or {@link Function}).
47 */
48 export const isRailwayHost = (
49 value: unknown,
50 ): value is Resource<string, any, any, ServiceBinding> =>
51 typeof value === "object" &&
52 value !== null &&
53 RAILWAY_BIND_HOST_TYPES.has((value as { Type?: string }).Type ?? "");
54
55 /**
56 * Binding contract accepted by {@link Service} and
57 * `Railway.Function` for mounted volumes and injected env.
58 */
59 export interface ServiceBinding {
60 env?: Record<string, any>;
61 mounts?: MountSpec[];
62 }
63
64 /**
65 * Railway allows one volume per service. Two `MountVolume`s, or a
66 * second {@link Volume} attached via `service`, is this error.
67 */
68 export class MultipleVolumes extends Data.TaggedError("Railway.MultipleVolumes")<{
69 resourceName: string;
70 paths: readonly string[];
71 volumeIds: readonly string[];
72 }> {}
73
74 const distinctMounts = (mounts: readonly MountSpec[]): MountSpec[] => {
75 const seen = new Set<string>();
76 const out: MountSpec[] = [];
77 for (const mount of mounts) {
78 if (mount.volumeId.length === 0) continue;
79 const key = `${mount.volumeId}:${mount.path}`;
80 if (seen.has(key)) continue;
81 seen.add(key);
82 out.push(mount);
83 }
84 return out;
85 };
86
87 /** At most one volume on a host. */
88 export const assertHostDisk = (input: {
89 name: string;
90 mounts: readonly MountSpec[];
91 }): Effect.Effect<void, MultipleVolumes> => {
92 const mounts = distinctMounts(input.mounts);
93 if (mounts.length <= 1) return Effect.void;
94 return new MultipleVolumes({
95 resourceName: input.name,
96 paths: mounts.map((mount) => mount.path),
97 volumeIds: mounts.map((mount) => mount.volumeId),
98 });
99 };
100
101 /**
102 * Mount a Railway.Volume into a {@link Service} or `Railway.Function`.
103 *
104 * `yield* Railway.MountVolume(volume, { path: "/data" })` inside a
105 * Service/Function impl registers `{ mounts: [{ volumeId, path }] }` on
106 * the host. Reconcile attaches the volume via `volumeInstanceUpdate`.
107 *
108 * Railway allows **one volume per service**. A second mount is
109 * `Railway.MultipleVolumes`. Railway does not give each replica its
110 * own disk.
111 *
112 *
113 * ### Mount into a Service
114 * Yield `MountVolume` inside init. Provide {@link MountVolumeLive}.
115 * At runtime you get `disk.path`.
116 *
117 * **Example:** Bind a path
118 * ```typescript
119 * export default class Api extends Railway.Service<Api>()(
120 * "Api",
121 * { project: Site, main: import.meta.url },
122 * Effect.gen(function* () {
123 * const disk = yield* Railway.MountVolume(Data, { path: "/data" });
124 * const fs = yield* FileSystem.FileSystem;
125 * return {
126 * fetch: Effect.gen(function* () {
127 * const text = yield* fs.readFileString(`${disk.path}/hello.txt`);
128 * return HttpServerResponse.text(text);
129 * }),
130 * };
131 * }).pipe(Effect.provide(Railway.MountVolumeLive)),
132 * ) {}
133 * ```
134 *
135 * :::caution[One volume per service]
136 * Railway does not attach a disk per replica. Two {@link MountVolume}s
137 * on one host fail with {@link MultipleVolumes}.
138 * :::
139 *
140 * @binding
141 * @product Volume
142 */
143 export interface MountVolume extends Binding.Service<
144 MountVolume,
145 "Railway.MountVolume",
146 (volume: Volume, options: MountVolumeOptions) => Effect.Effect<MountedVolume>
147 > {}
148
149 export const MountVolume = Binding.Service<MountVolume>("Railway.MountVolume");
150
151 export const MountVolumeLive = Layer.effect(
152 MountVolume,
153 Effect.succeed(
154 Effect.fn(function* (volume: Volume, options: MountVolumeOptions) {
155 if (!globalThis.__ALCHEMY_RUNTIME__) {
156 const host = yield* Binding.Host;
157 if (isRailwayHost(host)) {
158 yield* host.bind`Railway.MountVolume(${options.path})`({
159 mounts: [{ volumeId: volumeIdOf(volume), path: options.path }],
160 });
161 }
162 }
163 return { path: options.path };
164 }),
165 ),
166 );