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

main
ts 491 lines 18.8 KB
Raw
1 import { msg } from "gt-i18n";
2 import { translatableDetail } from "../errors/translatable.ts";
3 import {
4 type ServerConfig,
5 type ServerConfigStreamEvent,
6 WsSubscribeServerConfigRpc,
7 WS_METHODS,
8 } from "@t3tools/contracts";
9 import {
10 joinSocketFrameParts,
11 SOCKET_FRAME_PARTS_QUERY_PARAM,
12 } from "@t3tools/shared/socketFrameParts";
13 import * as Cause from "effect/Cause";
14 import * as Clock from "effect/Clock";
15 import * as Context from "effect/Context";
16 import * as Deferred from "effect/Deferred";
17 import * as Duration from "effect/Duration";
18 import * as Effect from "effect/Effect";
19 import * as Equal from "effect/Equal";
20 import * as Exit from "effect/Exit";
21 import * as Layer from "effect/Layer";
22 import * as Option from "effect/Option";
23 import * as PubSub from "effect/PubSub";
24 import * as Ref from "effect/Ref";
25 import * as Schedule from "effect/Schedule";
26 import * as Schema from "effect/Schema";
27 import type * as Scope from "effect/Scope";
28 import * as Stream from "effect/Stream";
29 import type * as Rpc from "effect/rpc/Rpc";
30 import * as RpcClient from "effect/rpc/RpcClient";
31 import * as RpcClientError from "effect/rpc/RpcClientError";
32 import * as RpcSerialization from "effect/rpc/RpcSerialization";
33 import * as Socket from "effect/socket/Socket";
34
35 import { makeWsRpcProtocolClient, PING_TIMEOUT, type WsRpcProtocolClient } from "./protocol.ts";
36 import { NETWORK_BLOCKING_HINT, UNRESPONSIVE_HOST_HINT } from "../errors/network.ts";
37 import type {
38 ConnectionAttemptError,
39 ConnectionTransientError,
40 PreparedConnection,
41 } from "../connection/model.ts";
42 import {
43 ConnectionBlockedError,
44 ConnectionTransientError as ConnectionTransientErrorClass,
45 } from "../connection/model.ts";
46 import {
47 applyServerConfigProjection,
48 type ServerConfigProjection,
49 withoutEnvironmentThemes,
50 } from "../state/serverConfigProjection.ts";
51 import { environmentMismatchError } from "../connection/errors.ts";
52 import { recordServerClock } from "../clock.ts";
53
54 const SOCKET_OPEN_TIMEOUT = "15 seconds";
55
56 export interface RpcSession {
57 readonly client: WsRpcProtocolClient;
58 readonly initialConfig: Effect.Effect<ServerConfig, ConnectionAttemptError>;
59 readonly subscribeServerConfig: (
60 input?: ServerConfigSubscriptionInput,
61 ) => ServerConfigSubscription;
62 readonly ready: Effect.Effect<void, ConnectionAttemptError>;
63 readonly probe: Effect.Effect<void, ConnectionAttemptError>;
64 /** Frames received so far: proof the socket is alive that needs no reply. */
65 readonly inboundFrames: Effect.Effect<number>;
66 readonly closed: Effect.Effect<never, ConnectionAttemptError>;
67 }
68
69 export interface RpcSessionOptions {
70 readonly environmentThemes?: boolean;
71 readonly usageLimitSources?: boolean;
72 readonly usageLimitsCommand?: boolean;
73 readonly providerCatalogsOnDemand?: boolean;
74 readonly providerCatalogDigests?: boolean;
75 readonly providerStatusDeltas?: boolean;
76 }
77
78 export class RpcSessionFactory extends Context.Service<
79 RpcSessionFactory,
80 {
81 readonly connect: (
82 connection: PreparedConnection,
83 ) => Effect.Effect<RpcSession, ConnectionAttemptError, Scope.Scope>;
84 }
85 >()("@t3tools/client-runtime/rpc/session/RpcSessionFactory") {}
86
87 type InitialConfigError = Effect.Error<
88 ReturnType<WsRpcProtocolClient[typeof WS_METHODS.serverGetConfig]>
89 >;
90 type ProbeError = Effect.Error<ReturnType<WsRpcProtocolClient[typeof WS_METHODS.serverProbe]>>;
91 type ServerConfigSubscriptionError =
92 | Rpc.ErrorExit<typeof WsSubscribeServerConfigRpc>
93 | RpcClientError.RpcClientError;
94 type ServerConfigSubscription = Stream.Stream<
95 ServerConfigStreamEvent,
96 ServerConfigSubscriptionError
97 >;
98 type ServerConfigSubscriptionInput = Parameters<
99 WsRpcProtocolClient[typeof WS_METHODS.subscribeServerConfig]
100 >[0];
101 type EnvironmentThemesUpdatedEvent = Extract<
102 ServerConfigStreamEvent,
103 { readonly type: "environmentThemesUpdated" }
104 >;
105 type UsageLimitSourcesUpdatedEvent = Extract<
106 ServerConfigStreamEvent,
107 { readonly type: "usageLimitSourcesUpdated" }
108 >;
109
110 interface ServerConfigReplayState {
111 readonly projection: ServerConfigProjection;
112 readonly revision: number;
113 readonly themesEvent: EnvironmentThemesUpdatedEvent | undefined;
114 readonly sourcesEvent: UsageLimitSourcesUpdatedEvent | undefined;
115 }
116
117 interface BufferedServerConfigEvent {
118 readonly event: ServerConfigStreamEvent;
119 readonly replay: ServerConfigReplayState;
120 readonly revision: number;
121 }
122
123 function serverConfigReplayEvents(
124 state: ServerConfigReplayState,
125 ): ReadonlyArray<ServerConfigStreamEvent> {
126 const snapshot = {
127 version: 1 as const,
128 type: "snapshot" as const,
129 config: withoutEnvironmentThemes(state.projection.config),
130 };
131 return [
132 snapshot,
133 ...(state.themesEvent === undefined ? [] : [state.themesEvent]),
134 ...(state.sourcesEvent === undefined ? [] : [state.sourcesEvent]),
135 ];
136 }
137
138 const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
139 const PING_TIMEOUT_SECONDS = Duration.toSeconds(PING_TIMEOUT);
140
141 function mapSessionRpcError(
142 error: InitialConfigError | ProbeError | ServerConfigSubscriptionError,
143 networkHint: string,
144 via: "relay" | "direct",
145 ): ConnectionAttemptError {
146 switch (error._tag) {
147 case "EnvironmentAuthorizationError":
148 return new ConnectionBlockedError({
149 reason: "permission",
150 detail: error.message,
151 hop: "server",
152 via,
153 });
154 case "KeybindingsConfigParseError":
155 case "ServerSettingsError":
156 return new ConnectionTransientErrorClass({
157 reason: "remote-unavailable",
158 detail: error.message,
159 hop: "server",
160 via,
161 });
162 case "RpcClientError":
163 return new ConnectionTransientErrorClass({
164 reason: "transport",
165 detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
166 ...socketFailureLocation(via),
167 });
168 }
169 }
170
171 /** Over T3 Connect the relay already reached the host, so a socket that drops failed between this device and the tunnel. */
172 function socketFailureLocation(via: "relay" | "direct") {
173 return { hop: via === "relay" ? "tunnel" : "server", via } as const;
174 }
175
176 /** @public */
177 export const make = Effect.fn("RpcSessionFactory.make")(function* (
178 options: RpcSessionOptions = {},
179 ) {
180 const webSocketConstructor = yield* Socket.WebSocketConstructor;
181 const serverConfigInput: ServerConfigSubscriptionInput = {
182 ...(options.environmentThemes === true ? { environmentThemes: true } : {}),
183 ...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
184 ...(options.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
185 ...(options.providerCatalogsOnDemand === true ? { providerCatalogsOnDemand: true } : {}),
186 ...(options.providerCatalogDigests === true ? { providerCatalogDigests: true } : {}),
187 ...(options.providerStatusDeltas === true ? { providerStatusDeltas: true } : {}),
188 };
189 // Config state merges the snapshots it fetches back in, so no subscriber needs them broadcast.
190 const onDemandSnapshots = (input: ServerConfigSubscriptionInput) => ({
191 ...input,
192 workspaceSnapshotsOnDemand: true,
193 });
194
195 const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
196 const via = connection.target._tag === "RelayConnectionTarget" ? "relay" : "direct";
197 const networkHint = via === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
198 const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
199 mapSessionRpcError(error, networkHint, via);
200 yield* Effect.annotateCurrentSpan({
201 "connection.environment.id": connection.environmentId,
202 });
203
204 const connected = yield* Deferred.make<void>();
205 const disconnected = yield* Deferred.make<never, ConnectionTransientError>();
206 const pingTimedOut = yield* Ref.make(false);
207 const hooks = RpcClient.ConnectionHooks.of({
208 onConnect: Deferred.succeed(connected, undefined).pipe(Effect.asVoid),
209 onDisconnect: Effect.all([Deferred.isDone(connected), Ref.get(pingTimedOut)]).pipe(
210 Effect.flatMap(([wasConnected, timedOut]) =>
211 Deferred.fail(
212 disconnected,
213 new ConnectionTransientErrorClass({
214 reason: "transport",
215 // The network hint only fits a socket that never opened. Once it
216 // opened, the path worked, and a host that goes quiet is more
217 // often overloaded or asleep than blocked.
218 ...(!wasConnected
219 ? translatableDetail(
220 msg("{host} could not establish a WebSocket connection.", {
221 host: connection.label,
222 }),
223 ...(via === "relay" ? [NETWORK_BLOCKING_HINT] : []),
224 )
225 : timedOut
226 ? translatableDetail(
227 msg("{host} stopped responding for {seconds}s.", {
228 host: connection.label,
229 seconds: String(PING_TIMEOUT_SECONDS),
230 }),
231 UNRESPONSIVE_HOST_HINT,
232 )
233 : translatableDetail(msg("{host} disconnected.", { host: connection.label }))),
234 ...socketFailureLocation(via),
235 }),
236 ),
237 ),
238 Effect.asVoid,
239 ),
240 });
241 // The protocol never reopens its socket, so every frame counted here came
242 // from this session's one socket.
243 let inboundFrames = 0;
244 const countingWebSocketConstructor: typeof webSocketConstructor = (url, options) => {
245 const socket = webSocketConstructor(url, options);
246 socket.addEventListener("message", () => {
247 inboundFrames += 1;
248 });
249 return socket;
250 };
251 const socketUrl = new URL(connection.socketUrl);
252 socketUrl.searchParams.set(SOCKET_FRAME_PARTS_QUERY_PARAM, "1");
253 const layerSocket = Layer.effect(
254 Socket.Socket,
255 Effect.map(Effect.service(Socket.Socket), joinSocketFrameParts),
256 ).pipe(
257 Layer.provide(
258 Socket.layerWebSocket(socketUrl.toString(), {
259 openTimeout: SOCKET_OPEN_TIMEOUT,
260 }),
261 ),
262 Layer.provide(Layer.succeed(Socket.WebSocketConstructor, countingWebSocketConstructor)),
263 );
264 const layerProtocol = Layer.effect(
265 RpcClient.Protocol,
266 RpcClient.makeProtocolSocket({
267 pingTimeout: PING_TIMEOUT,
268 retryTransientErrors: false,
269 retryPolicy: Schedule.recurs(0),
270 onPingTimeout: Ref.set(pingTimedOut, true),
271 }).pipe(
272 // Teardown sends an interrupt per open stream, and a write to a closed
273 // socket waits out the client's 1s interrupt timeout before reconnecting.
274 // Requests still go through, so they fail with the protocol error.
275 Effect.map((protocol) => ({
276 ...protocol,
277 send: (clientId, request, transferables) =>
278 request._tag !== "Request" && Deferred.isDoneUnsafe(disconnected)
279 ? Effect.void
280 : protocol.send(clientId, request, transferables),
281 })),
282 ),
283 ).pipe(
284 Layer.provide(
285 Layer.mergeAll(
286 layerSocket,
287 RpcSerialization.layerJson,
288 Layer.succeed(RpcClient.ConnectionHooks, hooks),
289 ),
290 ),
291 );
292 const protocolContext = yield* Layer.build(layerProtocol).pipe(
293 Effect.withSpan("environment.websocket.connect"),
294 );
295 // Building the protocol only starts the socket; this span times the
296 // handshake up to the first open, without making `connect` wait for it.
297 yield* Deferred.await(connected).pipe(
298 Effect.raceFirst(Deferred.await(disconnected)),
299 Effect.withSpan("environment.websocket.open"),
300 Effect.ignore,
301 Effect.forkScoped,
302 );
303 const protocolClient = yield* makeWsRpcProtocolClient.pipe(Effect.provide(protocolContext));
304 const initialConfigDeferred = yield* Deferred.make<ServerConfig>();
305 const serverConfigExit = yield* Deferred.make<void, ServerConfigSubscriptionError>();
306 const configSubscriptionClosed = yield* Deferred.make<never, ConnectionAttemptError>();
307 const serverConfigState = yield* Ref.make(Option.none<ServerConfigReplayState>());
308 const serverConfigUpdates = yield* PubSub.sliding<BufferedServerConfigEvent>(64);
309 const configSubscriptionEndedError = new ConnectionTransientErrorClass({
310 reason: "remote-unavailable",
311 detail: `${connection.label} config subscription ended.`,
312 });
313 const configRequestedAtMs = yield* Clock.currentTimeMillis;
314 const serverConfigSource = protocolClient[WS_METHODS.subscribeServerConfig](
315 onDemandSnapshots(serverConfigInput),
316 ).pipe(
317 Stream.runForEach((event) =>
318 Effect.gen(function* () {
319 const buffered = yield* Ref.modify(serverConfigState, (current) => {
320 const projection = applyServerConfigProjection(
321 Option.map(current, (state) => state.projection),
322 event,
323 );
324 if (Option.isNone(projection)) {
325 return [Option.none<BufferedServerConfigEvent>(), current] as const;
326 }
327 const next = {
328 projection: projection.value,
329 revision: Option.match(current, {
330 onNone: () => 1,
331 onSome: (state) => state.revision + 1,
332 }),
333 themesEvent:
334 event.type === "environmentThemesUpdated"
335 ? event
336 : Option.getOrUndefined(current)?.themesEvent,
337 sourcesEvent:
338 event.type === "usageLimitSourcesUpdated"
339 ? event
340 : Option.getOrUndefined(current)?.sourcesEvent,
341 } satisfies ServerConfigReplayState;
342 return [
343 Option.some({ event, replay: next, revision: next.revision }),
344 Option.some(next),
345 ] as const;
346 });
347 if (Option.isSome(buffered)) {
348 yield* PubSub.publish(serverConfigUpdates, buffered.value);
349 }
350 if (event.type === "snapshot") {
351 // Later snapshots may repeat the first one's serverTime. Record
352 // before readiness so the first timers already use its clock.
353 if (!(yield* Deferred.isDone(initialConfigDeferred))) {
354 const { serverTime } = event.config;
355 recordServerClock(connection.environmentId, {
356 serverTimeMs: serverTime === undefined ? undefined : Date.parse(serverTime),
357 requestedAtMs: configRequestedAtMs,
358 receivedAtMs: yield* Clock.currentTimeMillis,
359 });
360 }
361 yield* Deferred.succeed(initialConfigDeferred, event.config);
362 }
363 }),
364 ),
365 Effect.onExit((exit) => {
366 if (Exit.isSuccess(exit)) {
367 return Effect.all([
368 Deferred.succeed(serverConfigExit, undefined),
369 Deferred.fail(configSubscriptionClosed, configSubscriptionEndedError),
370 ]).pipe(Effect.asVoid);
371 }
372 if (Cause.hasInterruptsOnly(exit.cause)) {
373 return Effect.void;
374 }
375 return Effect.all([
376 Deferred.failCause(serverConfigExit, exit.cause),
377 Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapRpcError)),
378 ]).pipe(Effect.asVoid);
379 }),
380 );
381 yield* serverConfigSource.pipe(Effect.forkScoped);
382 const initialConfig = Effect.raceFirst(
383 Deferred.await(initialConfigDeferred),
384 Deferred.await(serverConfigExit).pipe(
385 Effect.mapError(mapRpcError),
386 Effect.flatMap(() => Effect.fail(configSubscriptionEndedError)),
387 ),
388 ).pipe(
389 Effect.filterOrElse(
390 (config) => config.environment.environmentId === connection.environmentId,
391 (config) =>
392 environmentMismatchError({
393 expected: connection.environmentId,
394 actual: config.environment.environmentId,
395 }),
396 ),
397 Effect.withSpan("environment.initialSync"),
398 );
399 const serverConfigEvents = Stream.unwrap(
400 Effect.gen(function* () {
401 const subscription = yield* PubSub.subscribe(serverConfigUpdates);
402 const snapshot = yield* Ref.get(serverConfigState);
403 if (Option.isNone(snapshot)) {
404 return Stream.empty;
405 }
406 const updates = Stream.fromSubscription(subscription).pipe(
407 Stream.filter((buffered) => buffered.revision > snapshot.value.revision),
408 Stream.mapAccum(
409 () => snapshot.value.revision,
410 (revision, buffered) => [
411 buffered.revision,
412 buffered.revision === revision + 1
413 ? [buffered.event]
414 : serverConfigReplayEvents(buffered.replay),
415 ],
416 ),
417 );
418 const terminal = Stream.fromEffect(Deferred.await(serverConfigExit)).pipe(Stream.drain);
419 return Stream.concat(
420 Stream.fromIterable(serverConfigReplayEvents(snapshot.value)),
421 Stream.merge(updates, terminal, { haltStrategy: "either" }),
422 );
423 }),
424 ).pipe(
425 Stream.catchCause((cause) => {
426 if (Cause.hasInterruptsOnly(cause)) {
427 return Stream.failCause(cause);
428 }
429 // The supervisor keeps the original cause. Shared durable consumers
430 // need a transport-shaped failure so they wait for its replacement.
431 return Stream.fail(
432 new RpcClientError.RpcClientError({
433 reason: new RpcClientError.RpcClientDefect({
434 message: `${connection.label} config subscription failed.`,
435 cause,
436 }),
437 }),
438 );
439 }),
440 );
441 const validatedInitialConfig = initialConfig.pipe(
442 Effect.mapError(
443 (cause) =>
444 new RpcClientError.RpcClientError({
445 reason: new RpcClientError.RpcClientDefect({
446 message: `${connection.label} config subscription failed.`,
447 cause,
448 }),
449 }),
450 ),
451 );
452 const subscribeServerConfig = (input: ServerConfigSubscriptionInput = serverConfigInput) =>
453 Stream.unwrap(
454 validatedInitialConfig.pipe(
455 Effect.as(
456 Equal.equals(input, serverConfigInput)
457 ? serverConfigEvents
458 : protocolClient[WS_METHODS.subscribeServerConfig](onDemandSnapshots(input)),
459 ),
460 ),
461 );
462 const probe = initialConfig.pipe(
463 Effect.flatMap(() =>
464 protocolClient[WS_METHODS.serverProbe]({}).pipe(Effect.mapError(mapRpcError)),
465 ),
466 Effect.asVoid,
467 Effect.withSpan("clientRuntime.connection.rpcSession.probe"),
468 );
469
470 return {
471 client: protocolClient,
472 initialConfig,
473 subscribeServerConfig,
474 ready: Deferred.await(connected).pipe(
475 Effect.andThen(initialConfig),
476 Effect.asVoid,
477 Effect.raceFirst(Deferred.await(disconnected)),
478 ),
479 probe,
480 inboundFrames: Effect.sync(() => inboundFrames),
481 closed: Effect.raceFirst(
482 Deferred.await(disconnected),
483 Deferred.await(configSubscriptionClosed),
484 ),
485 } satisfies RpcSession;
486 });
487
488 return RpcSessionFactory.of({ connect });
489 });
490
491 export const layer = (options: RpcSessionOptions) => Layer.effect(RpcSessionFactory, make(options));