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

main
ts 420 lines 16.1 KB
Raw
1 import * as Console from "effect/Console";
2 import * as Context from "effect/Context";
3 import * as Deferred from "effect/Deferred";
4 import * as Effect from "effect/Effect";
5 import * as Exit from "effect/Exit";
6 import * as Fiber from "effect/Fiber";
7 import * as FetchHttpClient from "effect/http/FetchHttpClient";
8 import type { HttpClient } from "effect/http/HttpClient";
9 import * as Layer from "effect/Layer";
10 import * as Scope from "effect/Scope";
11 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
12 import type { ProviderService } from "../Provider.ts";
13 import type { ResourceLike } from "../Resource.ts";
14 import { childJsonLogLayer, LOG_FORMAT_ENV, LogProcess } from "../Util/LogRecord.ts";
15 import { platformLayer, PlatformServices, runMain } from "../Util/PlatformServices.ts";
16 import { logShutdown } from "../Util/Shutdown.ts";
17 import { processTrace, withTraceParent } from "../Util/TraceParent.ts";
18 import * as RpcSerialization from "./RpcSerialization.ts";
19 import * as RpcServerEnvironment from "./RpcServerEnvironment.ts";
20 import type { SessionEnvironment } from "./RpcServerEnvironment.ts";
21 import {
22 makeServerRpcSession,
23 type ServerRpcSession,
24 type ServerWebSocketLike,
25 } from "./RpcServerSession.ts";
26
27 /**
28 * A service that exposes one or more resource providers over RPC.
29 * This returns `never` because it is meant to be used with `Layer.launch` (see {@link launch}).
30 */
31 export class RpcServer extends Context.Service<RpcServer, never>()("alchemy/Local/RpcServer") {}
32
33 /**
34 * The provider shape served over RPC. The `mode`/`modes` variant machinery
35 * (lazy Layer-built Effects, see `ProviderLayer.dual`) is process-local and
36 * cannot cross the RPC boundary — the sidecar serves the concrete provider
37 * implementation, never the mode-dispatching wrapper.
38 */
39 export type RpcProviderService<R extends ResourceLike> = Omit<ProviderService<R>, "mode" | "modes">;
40
41 /**
42 * The RPC API that is implemented by the server and consumed by {@link RpcProviderProxy}.
43 */
44 export interface RpcProxyApi {
45 /**
46 * Retrieves a provider from the RPC server context.
47 * The consumer must unwrap the provider using {@link RpcSerialization.unwrapRpcHandlers} before using it.
48 *
49 * `group` names the provider group the type belongs to: for a server
50 * launched with a group loader (the dev sidecar, see `Local/Sidecar.ts`)
51 * it is the URL of the module whose default export is that group's
52 * provider layer, imported and built on first use per session. A server
53 * launched with a static layer ignores it.
54 */
55 readonly getProvider: <R extends ResourceLike>(
56 type: R["Type"],
57 group: string,
58 testOwned?: boolean,
59 ) => Promise<RpcSerialization.RpcWrapped<RpcProviderService<R>>>;
60 /** Release only this connection's test-owned provider contexts. */
61 readonly releaseSession: () => Promise<void>;
62 /** Bounded, payload-free counts; does not build any provider contexts. */
63 readonly getDiagnostics: () => Promise<SessionProviderCounts>;
64 }
65
66 export interface SessionProviderCounts {
67 readonly sessions: number;
68 readonly testSessions: number;
69 readonly contexts: number;
70 readonly building: number;
71 readonly artifactBags: number;
72 readonly artifacts: number;
73 }
74
75 /** The layer shape a served provider group must have. */
76 export type ProviderLayer = Layer.Layer<
77 any,
78 any,
79 | Scope.Scope
80 | RpcServerEnvironment.RpcEnvironmentServices
81 | PlatformServices
82 | HttpClient
83 | ArtifactStore
84 >;
85
86 /**
87 * Resolves a provider group to its layer. Receives the `group` the client
88 * passed to {@link RpcProxyApi.getProvider}.
89 */
90 export type ProviderGroupLoader = (group: string) => Effect.Effect<ProviderLayer, unknown>;
91
92 const serverPlatformLayer = platformLayer({
93 bun: async () => {
94 const { RpcServerBun } = await import("./RpcServerBun.ts");
95 return RpcServerBun;
96 },
97 node: async () => {
98 const { RpcServerNode } = await import("./RpcServerNode.ts");
99 return RpcServerNode;
100 },
101 });
102
103 /** Test leases are connection-local; dev contexts remain keyed by environment. */
104 interface SessionLease {
105 closed: boolean;
106 closing?: Promise<void>;
107 readonly calls: Set<Fiber.Fiber<unknown, unknown>>;
108 }
109
110 interface SessionContext {
111 readonly scope: Scope.Closeable;
112 readonly resources: Scope.Closeable;
113 readonly artifacts: ArtifactStore["Service"];
114 readonly builds: Map<string, { pending: Promise<Context.Context<any>>; ready: boolean }>;
115 }
116
117 /** Each provider group is built with its own MemoMap and session scope. */
118 export class SessionProviders extends Context.Service<
119 SessionProviders,
120 {
121 readonly get: (
122 sessionEnv: string | undefined,
123 type: string,
124 group: string,
125 lease?: SessionLease,
126 ) => Promise<RpcSerialization.RpcWrapped<RpcProviderService<any>>>;
127 readonly release: (lease: SessionLease) => Promise<void>;
128 readonly diagnostics: () => SessionProviderCounts;
129 }
130 >()("alchemy/Local/SessionProviders") {}
131
132 const sessionProviders = (resolve: ProviderGroupLoader) =>
133 Layer.effect(
134 SessionProviders,
135 Effect.gen(function* () {
136 const scope = yield* Effect.scope;
137 const ambient = Context.omit(Scope.Scope)(yield* Effect.context<never>());
138 const base = yield* RpcServerEnvironment.fromProcessEnv.pipe(Effect.orDie);
139 const sessions = new Map<string | undefined | SessionLease, SessionContext>();
140
141 const contextFor = (
142 sessionEnv: string | undefined,
143 group: string,
144 lease?: SessionLease,
145 ): Promise<Context.Context<any>> => {
146 if (lease?.closed) {
147 return Promise.reject(new Error("Test RPC session is closed"));
148 }
149 const key = lease ?? sessionEnv;
150 let session = sessions.get(key);
151 if (session === undefined) {
152 session = {
153 scope: Scope.forkUnsafe(scope),
154 resources: Scope.makeUnsafe("sequential"),
155 artifacts: createArtifactStore(),
156 builds: new Map(),
157 };
158 sessions.set(key, session);
159 const current = session;
160 Effect.runSyncWith(ambient)(
161 Scope.addFinalizer(
162 current.scope,
163 // Calls drain before provider finalizers and artifact disposal.
164 Effect.suspend(() => {
165 if (lease === undefined) return Effect.void;
166 lease.closed = true;
167 return Fiber.interruptAll([...lease.calls]);
168 }).pipe(
169 Effect.ensuring(Scope.close(current.resources, Exit.void)),
170 Effect.ensuring(
171 Effect.sync(() => {
172 if (sessions.get(key) === current) sessions.delete(key);
173 current.builds.clear();
174 for (const bag of current.artifacts.values()) bag.clear();
175 current.artifacts.clear();
176 }),
177 ),
178 ),
179 ),
180 );
181 }
182 const current = session;
183 const existing = current.builds.get(group);
184 if (existing !== undefined) return existing.pending;
185 const resolved: SessionEnvironment | undefined =
186 sessionEnv !== undefined
187 ? RpcServerEnvironment.decodeSessionEnvironment(sessionEnv)
188 : base.stack !== undefined && base.alchemyContext !== undefined
189 ? { stack: base.stack, alchemyContext: base.alchemyContext }
190 : undefined;
191 if (resolved === undefined) {
192 return Promise.reject(
193 new Error(
194 "RPC session carried no session environment and the server was booted without a default one",
195 ),
196 );
197 }
198 const groupScope = Scope.forkUnsafe(current.resources);
199 const pending = Effect.runPromiseWith(ambient)(
200 resolve(group).pipe(
201 Effect.flatMap((providers) =>
202 Layer.buildWithMemoMap(
203 providers.pipe(
204 Layer.provide(
205 RpcServerEnvironment.layer({
206 profile: base.profile,
207 envFile: base.envFile,
208 ...resolved,
209 }),
210 ),
211 ),
212 Layer.makeMemoMapUnsafe(),
213 groupScope,
214 ),
215 ),
216 Effect.provideService(ArtifactStore, current.artifacts),
217 Scope.provide(groupScope),
218 Effect.provideContext(ambient as Context.Context<any>),
219 Effect.forkIn(groupScope),
220 Effect.flatMap(Fiber.join),
221 Effect.onError(() => Scope.close(groupScope, Exit.void)),
222 ) as Effect.Effect<Context.Context<any>>,
223 );
224 const build = { pending, ready: false };
225 current.builds.set(group, build);
226 pending.then(
227 () => {
228 build.ready = true;
229 },
230 () => {
231 if (current.builds.get(group) === build) current.builds.delete(group);
232 },
233 );
234 return pending;
235 };
236
237 return SessionProviders.of({
238 diagnostics: () => {
239 let testSessions = 0;
240 let contexts = 0;
241 let building = 0;
242 let artifactBags = 0;
243 let artifacts = 0;
244 for (const [key, session] of sessions) {
245 if (typeof key === "object") testSessions++;
246 for (const build of session.builds.values()) {
247 if (build.ready) contexts++;
248 else building++;
249 }
250 artifactBags += session.artifacts.size;
251 for (const bag of session.artifacts.values()) artifacts += bag.size;
252 }
253 return {
254 sessions: sessions.size,
255 testSessions,
256 contexts,
257 building,
258 artifactBags,
259 artifacts,
260 };
261 },
262 release: (lease) => {
263 if (lease.closing !== undefined) return lease.closing;
264 lease.closed = true;
265 const session = sessions.get(lease);
266 lease.closing =
267 session === undefined
268 ? Promise.resolve()
269 : Effect.runPromiseWith(ambient)(Scope.close(session.scope, Exit.void));
270 return lease.closing;
271 },
272 get: async (sessionEnv, type, group, lease) => {
273 const context = await contextFor(sessionEnv, group, lease);
274 if (lease?.closed) throw new Error("Test RPC session is closed");
275 const provider = context.mapUnsafe.get(type) as ProviderService<any> | undefined;
276 if (!provider) {
277 throw new Error(`Provider "${type}" not found in provider group ${group}`);
278 }
279 const { mode: _mode, modes: _modes, ...serializable } = provider;
280 const registerCall =
281 lease === undefined
282 ? undefined
283 : Effect.acquireRelease(
284 Effect.withFiber((fiber) =>
285 Effect.sync(() => {
286 if (lease.closed) throw new Error("Test RPC session is closed");
287 lease.calls.add(fiber);
288 return fiber;
289 }),
290 ),
291 (fiber) =>
292 Effect.sync(() => {
293 lease.calls.delete(fiber);
294 }),
295 ).pipe(Effect.asVoid);
296 return RpcSerialization.wrapRpcHandlers(
297 serializable as RpcProviderService<any>,
298 ["tail"],
299 registerCall,
300 );
301 },
302 });
303 }),
304 );
305
306 /**
307 * Launches an RPC server that serves providers.
308 * Alchemy globals such as `AlchemyContext`, `Profile`, and `Stack` are inherited from the parent via {@link RpcServerEnvironment.fromEnv} and should not be provided manually.
309 * `PlatformServices` and `HttpClient` are also included.
310 *
311 * Pass a layer to serve a fixed set of providers, or a
312 * {@link ProviderGroupLoader} to resolve the group each client names — the
313 * dev sidecar (`Local/Sidecar.ts`) imports the group module on demand, so
314 * one process serves every provider group without loading the ones a run
315 * never touches.
316 *
317 * @example
318 * ```ts
319 * RpcServer.launch(
320 * Layer.merge(
321 * FunctionProvider,
322 * QueueProvider,
323 * ),
324 * );
325 * ```
326 *
327 * @param providers - A layer containing the providers to serve, or a loader
328 * from group to layer.
329 */
330 export const launch = (providers: ProviderLayer | ProviderGroupLoader) =>
331 serverPlatformLayer.pipe(
332 Layer.provide(
333 sessionProviders(Layer.isLayer(providers) ? () => Effect.succeed(providers) : providers),
334 ),
335 Layer.provide(Layer.mergeAll(PlatformServices, FetchHttpClient.layer)),
336 Layer.launch,
337 logShutdown("sidecar"),
338 // Spans outside RPC calls join the `alchemy dev` trace, like its records.
339 withTraceParent(processTrace),
340 // The spawner asks for JSON records: the process that owns the
341 // terminal decodes and renders them, so structure (level, resource,
342 // text as written) survives the pipe.
343 Effect.provide(process.env[LOG_FORMAT_ENV] === "json" ? childJsonLogLayer : Layer.empty),
344 Effect.provideService(LogProcess, "sidecar"),
345 Effect.scoped,
346 runMain,
347 );
348
349 /**
350 * Constructs an `RpcServer` layer using the given server implementation.
351 * @param serve - A function that spawns a websocket server and returns its URL.
352 * @returns An `RpcServer` layer.
353 */
354 export const layerServer = (
355 serve: (handlers: {
356 /**
357 * Creates a new RPC session over the given websocket. `sessionEnv` is
358 * the raw {@link SessionEnvironment} JSON from the websocket URL's
359 * `SESSION_ENV_PARAM` query parameter, when the client sent one.
360 */
361 createRpcSession: (
362 ws: ServerWebSocketLike,
363 sessionEnv?: string,
364 ) => ServerRpcSession<RpcProxyApi>;
365 /** Called when the parent connection, indicated by the `/parent` path, is established. */
366 parentConnected: () => void;
367 /** Called when the parent disconnects. The server will shut down when this is called. */
368 /** The parent link closed; `detail` says how, when the server knows. */
369 parentDisconnected: (detail?: string) => void;
370 }) => Effect.Effect<{ readonly url: string }, never, Scope.Scope>,
371 ) =>
372 Layer.effect(
373 RpcServer,
374 Effect.gen(function* () {
375 const providers = yield* SessionProviders;
376 const context = yield* Effect.context();
377 const connected = yield* Deferred.make<void>();
378 const disconnected = yield* Deferred.make<string | undefined>();
379 const { url } = yield* serve({
380 createRpcSession: (ws, sessionEnv) => {
381 const lease: SessionLease = { closed: false, calls: new Set() };
382 let testOwned = false;
383 const session = makeServerRpcSession<RpcProxyApi>(ws, {
384 getProvider: (<R extends ResourceLike>(
385 type: R["Type"],
386 group: string,
387 owned = false,
388 ) => {
389 testOwned ||= owned;
390 return providers.get(sessionEnv, type, group, testOwned ? lease : undefined);
391 }) as RpcProxyApi["getProvider"],
392 releaseSession: () => providers.release(lease),
393 getDiagnostics: () => Promise.resolve(providers.diagnostics()),
394 });
395 const close = session.dispatch.close;
396 session.dispatch.close = (code, reason) => {
397 close(code, reason);
398 // A broken test transport has no remaining owner; dev sessions
399 // deliberately retain their contexts across hot reloads.
400 if (testOwned) {
401 void providers.release(lease).catch((error) => {
402 Effect.runForkWith(context)(Effect.logError(error));
403 });
404 }
405 };
406 return session;
407 },
408 parentConnected: () => Deferred.doneUnsafe(connected, Effect.void),
409 parentDisconnected: (detail) => Deferred.doneUnsafe(disconnected, Effect.succeed(detail)),
410 });
411 yield* Console.log(`<ALCHEMY_RPC_ADDRESS>${url}</ALCHEMY_RPC_ADDRESS>`);
412 yield* Deferred.await(connected).pipe(Effect.timeout("10 seconds")); // TODO(john): should the timeout be shorter?
413 // The sidecar exits with its parent; record why the link closed.
414 const detail = yield* Deferred.await(disconnected);
415 yield* Effect.logInfo(
416 `parent connection closed${detail === undefined ? "" : ` (${detail})`}; shutting down`,
417 );
418 return yield* Effect.interrupt;
419 }),
420 );