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

main
ts 1,188 lines 43.1 KB
Raw
1 import { msg } from "gt-i18n";
2 import { translatableMessage } from "../errors/translatable.ts";
3 import type { QueryPersistence } from "./queryPersistence.ts";
4 import { createCommandPermissions } from "./commandPermissions.ts";
5 import { followStreamInEnvironment } from "./environmentStreams.ts";
6 import { reuseUnchanged } from "./serverConfigProjection.ts";
7 export { runStreamInEnvironment, followStreamInEnvironment } from "./environmentStreams.ts";
8 import {
9 type ClientGuardedRpcTag,
10 EnvironmentId,
11 type EnvironmentId as EnvironmentIdType,
12 } from "@t3tools/contracts";
13 import * as Cause from "effect/Cause";
14 import * as Deferred from "effect/Deferred";
15 import * as Effect from "effect/Effect";
16 import type * as Exit from "effect/Exit";
17 import * as Fiber from "effect/Fiber";
18 import * as Option from "effect/Option";
19 import * as Schema from "effect/Schema";
20 import * as Semaphore from "effect/Semaphore";
21 import * as Stream from "effect/Stream";
22 import * as SubscriptionRef from "effect/SubscriptionRef";
23 import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
24
25 import type { ConnectionAttemptError, SupervisorConnectionState } from "../connection/model.ts";
26 import * as EnvironmentRegistry from "../connection/registry.ts";
27 import {
28 type EnvironmentRpcInput,
29 type EnvironmentRpcSuccess,
30 type EnvironmentRpcFailure,
31 type EnvironmentRpcStreamFailure,
32 type EnvironmentRpcStreamValue,
33 type EnvironmentSubscriptionRpcTag,
34 type EnvironmentUnaryRpcTag,
35 EnvironmentRpcUnavailableError,
36 request,
37 requestGuarded,
38 RpcPermissionGuard,
39 subscribe,
40 } from "../rpc/client.ts";
41 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
42 import type * as RpcSession from "../rpc/session.ts";
43
44 const isEnvironmentRpcUnavailable = Schema.is(EnvironmentRpcUnavailableError);
45
46 /**
47 * Holds back the unavailable failure of a query whose session went away. The
48 * query atom reruns when it sees that session change, so settling first would
49 * show a failure for a query that is about to retry. While `session` is still
50 * current no rerun is coming, and the failure stands.
51 */
52 const pendingOnceSessionReplaced =
53 (session: RpcSession.RpcSession) =>
54 <A, E, R>(effect: Effect.Effect<A, E, R>) =>
55 effect.pipe(
56 // The query's error type is generic, so its tags are unknown to `catchTags`.
57 Effect.catchIf(isEnvironmentRpcUnavailable, (error) =>
58 EnvironmentSupervisor.EnvironmentSupervisor.pipe(
59 Effect.flatMap((supervisor) => SubscriptionRef.get(supervisor.session)),
60 Effect.flatMap((current) =>
61 Option.isSome(current) && current.value === session ? Effect.fail(error) : Effect.never,
62 ),
63 ),
64 ),
65 );
66
67 interface EnvironmentAtomOptions<Input, A, E, R> {
68 readonly label: string;
69 readonly execute: (input: Input) => Effect.Effect<A, E, R>;
70 readonly scheduler?: AtomCommandScheduler;
71 readonly concurrency?: AtomCommandConcurrency<{
72 readonly environmentId: EnvironmentIdType;
73 readonly input: Input;
74 }>;
75 }
76
77 interface EnvironmentCommandAtomOptions<Input, A, E, R> extends Omit<
78 EnvironmentAtomOptions<Input, A, E, R>,
79 "execute"
80 > {
81 readonly execute: (
82 input: Input,
83 registry: AtomRegistry.AtomRegistry,
84 environmentId: EnvironmentIdType,
85 ) => Effect.Effect<A, E, R>;
86 }
87
88 interface EnvironmentQueryAtomOptions<Input, A, E, R> extends Omit<
89 EnvironmentAtomOptions<Input, A, E, R>,
90 "execute"
91 > {
92 /**
93 * `emit` shows a provisional value while the query keeps waiting. The settled
94 * result replaces it, so catch failures that should keep it on screen.
95 */
96 readonly execute: (
97 input: Input,
98 emit: (value: A) => Effect.Effect<void>,
99 previous: Option.Option<A>,
100 ) => Effect.Effect<A, E, R>;
101 readonly persistence?: QueryPersistence<A>;
102 readonly staleTimeMs?: number;
103 readonly idleTtlMs?: number;
104 readonly refreshIntervalMs?: number;
105 readonly refreshTrigger?: (target: {
106 readonly environmentId: EnvironmentIdType;
107 readonly input: Input;
108 }) => Atom.Atom<unknown> | undefined;
109 readonly isFinal?: (value: A) => boolean;
110 /**
111 * Runs where each server answer lands, before readers see it, so derived records (summaries,
112 * snapshots, watches) come from the producer instead of from components watching the data.
113 * Cached and emitted provisional values are not answers.
114 */
115 readonly onAnswer?: QueryAnswerHandler<Input, A>;
116 }
117
118 export type QueryAnswerHandler<Input, A> = (
119 target: { readonly environmentId: EnvironmentIdType; readonly input: Input },
120 value: A,
121 registry: AtomRegistry.AtomRegistry,
122 ) => Effect.Effect<void>;
123
124 interface EnvironmentSubscriptionAtomOptions<Input, A, E, R> {
125 readonly sensitiveInput?: boolean;
126 readonly label: string;
127 readonly subscribe: (input: Input) => Stream.Stream<A, E, R>;
128 readonly completeWhen?: (value: A) => boolean;
129 readonly idleTtlMs?: number;
130 /** Keeps a completed value this long after its last reader leaves, so reopening skips a resubscribe. */
131 readonly completedTtlMs?: number;
132 }
133
134 export type SettledAsyncResult<A, E> = AsyncResult.Success<A, E> | AsyncResult.Failure<A, E>;
135
136 export type AtomCommandResult<A, E> = SettledAsyncResult<A, E>;
137
138 export type AtomCommandSuccess<R> = R extends AtomCommandResult<infer A, infer _E> ? A : never;
139
140 export type AtomCommandFailure<R> = R extends AtomCommandResult<infer _A, infer E> ? E : never;
141
142 export interface AtomCommandOptions {
143 readonly label?: string;
144 readonly reportFailure?: boolean;
145 readonly reportDefect?: boolean;
146 /** Aborting interrupts the run. */
147 readonly signal?: AbortSignal | undefined;
148 }
149
150 export interface AtomCommandReporter {
151 readonly warn: (message: string, cause: Cause.Cause<unknown>) => void;
152 readonly error: (message: string, cause: Cause.Cause<unknown>) => void;
153 }
154
155 export interface AtomCommand<W, A, E> {
156 readonly label: string;
157 /**
158 * Runs on the calling fiber, so interrupting the caller stops the command. Code outside
159 * Effect starts it with `runAtomCommand`.
160 */
161 readonly run: (registry: AtomRegistry.AtomRegistry, input: W) => Effect.Effect<A, E>;
162 }
163
164 export type AtomCommandConcurrency<W> =
165 | { readonly mode: "parallel" }
166 | {
167 readonly mode: "serial" | "singleFlight" | "latest";
168 readonly key: (input: W) => string;
169 };
170
171 /** One run that several callers wait on. It is interrupted once the last of them stops waiting. */
172 interface SharedRun {
173 readonly result: Deferred.Deferred<unknown, unknown>;
174 waiters: number;
175 fiber: Fiber.Fiber<unknown, unknown> | undefined;
176 }
177
178 interface AtomCommandLatestLane {
179 pending: (SharedRun & { start: Effect.Effect<void> }) | undefined;
180 }
181
182 interface AtomCommandSchedulerState {
183 readonly serial: Map<string, { readonly semaphore: Semaphore.Semaphore; users: number }>;
184 readonly singleFlight: Map<string, SharedRun>;
185 readonly latest: Map<string, AtomCommandLatestLane>;
186 }
187
188 export interface AtomCommandScheduler {
189 readonly schedule: <W, A, E, R>(
190 registry: AtomRegistry.AtomRegistry,
191 concurrency: AtomCommandConcurrency<W>,
192 input: W,
193 effect: Effect.Effect<A, E, R>,
194 ) => Effect.Effect<A, E, R>;
195 }
196
197 const startSharedRun = <A, E>(run: SharedRun, effect: Effect.Effect<A, E>) =>
198 effect.pipe(
199 Effect.interruptible,
200 Effect.onExit((exit) => Deferred.done(run.result, exit)),
201 Effect.ignoreCause,
202 Effect.forkDetach({ startImmediately: true }),
203 Effect.map((fiber) => {
204 run.fiber = fiber;
205 }),
206 );
207
208 const awaitSharedRun = <A, E>(
209 run: SharedRun,
210 restore: <X, XE, XR>(effect: Effect.Effect<X, XE, XR>) => Effect.Effect<X, XE, XR>,
211 abandon: Effect.Effect<void>,
212 ): Effect.Effect<A, E> => {
213 run.waiters++;
214 return restore(Deferred.await(run.result as Deferred.Deferred<A, E>)).pipe(
215 Effect.onInterrupt(() => (--run.waiters === 0 ? abandon : Effect.void)),
216 );
217 };
218
219 const interruptSharedRun = (run: SharedRun) =>
220 run.fiber === undefined ? Effect.void : Fiber.interrupt(run.fiber);
221
222 export function createAtomCommandScheduler(): AtomCommandScheduler {
223 const registryStates = new WeakMap<AtomRegistry.AtomRegistry, AtomCommandSchedulerState>();
224 const stateFor = (registry: AtomRegistry.AtomRegistry) => {
225 let state = registryStates.get(registry);
226 if (state === undefined) {
227 state = { serial: new Map(), singleFlight: new Map(), latest: new Map() };
228 registryStates.set(registry, state);
229 }
230 return state;
231 };
232
233 const serial = <A, E, R>(
234 lanes: AtomCommandSchedulerState["serial"],
235 key: string,
236 effect: Effect.Effect<A, E, R>,
237 ) =>
238 Effect.acquireUseRelease(
239 Effect.sync(() => {
240 const lane = lanes.get(key) ?? { semaphore: Semaphore.makeUnsafe(1), users: 0 };
241 lanes.set(key, lane);
242 lane.users++;
243 return lane;
244 }),
245 (lane) => lane.semaphore.withPermit(effect),
246 (lane) =>
247 Effect.sync(() => {
248 if (--lane.users === 0) lanes.delete(key);
249 }),
250 );
251
252 const singleFlight = <A, E, R>(
253 flights: AtomCommandSchedulerState["singleFlight"],
254 key: string,
255 effect: Effect.Effect<A, E, R>,
256 ) =>
257 Effect.uninterruptibleMask((restore) =>
258 Effect.gen(function* () {
259 let flight = flights.get(key);
260 if (flight === undefined) {
261 const started: SharedRun = {
262 result: Deferred.makeUnsafe(),
263 waiters: 0,
264 fiber: undefined,
265 };
266 flight = started;
267 flights.set(key, started);
268 const context = yield* Effect.context<R>();
269 yield* startSharedRun(
270 started,
271 effect.pipe(
272 Effect.provide(context),
273 Effect.ensuring(
274 Effect.sync(() => {
275 if (flights.get(key) === started) flights.delete(key);
276 }),
277 ),
278 ),
279 );
280 }
281 const joined = flight;
282 return yield* awaitSharedRun<A, E>(
283 joined,
284 restore,
285 Effect.suspend(() => {
286 // Left the map first, so a caller arriving during the interrupt starts a fresh run.
287 if (flights.get(key) === joined) flights.delete(key);
288 return interruptSharedRun(joined);
289 }),
290 );
291 }),
292 );
293
294 const latest = <A, E, R>(
295 lanes: AtomCommandSchedulerState["latest"],
296 key: string,
297 effect: Effect.Effect<A, E, R>,
298 ) =>
299 Effect.uninterruptibleMask((restore) =>
300 Effect.gen(function* () {
301 const context = yield* Effect.context<R>();
302 const existing = lanes.get(key);
303 const lane = existing ?? { pending: undefined };
304 lanes.set(key, lane);
305 // Callers that queue behind a run share the next one, which runs the newest of them.
306 const batch = lane.pending ?? {
307 result: Deferred.makeUnsafe(),
308 waiters: 0,
309 fiber: undefined,
310 start: Effect.void,
311 };
312 batch.start = startSharedRun(batch, Effect.provide(effect, context));
313 lane.pending = batch;
314
315 if (existing === undefined) {
316 const drain: Effect.Effect<void> = Effect.suspend(() => {
317 const next = lane.pending;
318 if (next === undefined) {
319 lanes.delete(key);
320 return Effect.void;
321 }
322 lane.pending = undefined;
323 return next.start.pipe(
324 Effect.andThen(Deferred.await(next.result)),
325 Effect.exit,
326 Effect.andThen(drain),
327 );
328 });
329 yield* drain.pipe(Effect.forkDetach({ startImmediately: true }));
330 }
331 return yield* awaitSharedRun<A, E>(
332 batch,
333 restore,
334 Effect.suspend(() => {
335 if (lane.pending === batch) lane.pending = undefined;
336 return interruptSharedRun(batch);
337 }),
338 );
339 }),
340 );
341
342 return {
343 schedule: (registry, concurrency, input, effect) =>
344 concurrency.mode === "parallel"
345 ? effect
346 : Effect.suspend(() => {
347 const key = concurrency.key(input);
348 const state = stateFor(registry);
349 switch (concurrency.mode) {
350 case "serial":
351 return serial(state.serial, key, effect);
352 case "singleFlight":
353 return singleFlight(state.singleFlight, key, effect);
354 case "latest":
355 return latest(state.latest, key, effect);
356 }
357 }),
358 };
359 }
360
361 const settleAtEdge = <A, E>(
362 effect: Effect.Effect<A, E>,
363 options: AtomCommandOptions,
364 reporter: AtomCommandReporter,
365 ): Promise<AtomCommandResult<A, E>> =>
366 Effect.runPromiseExit(effect, { signal: options.signal }).then((exit) => {
367 const result = AsyncResult.fromExit(exit);
368 reportAtomCommandResult(result, options, reporter);
369 return result;
370 });
371
372 /** Starts a command from outside Effect. Effect callers yield `command.run` instead. */
373 export function runAtomCommand<W, A, E>(
374 registry: AtomRegistry.AtomRegistry,
375 command: AtomCommand<W, A, E>,
376 input: W,
377 options: AtomCommandOptions = {},
378 reporter: AtomCommandReporter = console,
379 ): Promise<AtomCommandResult<A, E>> {
380 return settleAtEdge(
381 Effect.suspend(() => command.run(registry, input)),
382 { ...options, label: options.label ?? command.label },
383 reporter,
384 );
385 }
386
387 export function mapAtomCommandResult<A, E, B>(
388 result: AtomCommandResult<A, E>,
389 map: (value: A) => B,
390 ): AtomCommandResult<B, E> {
391 return result._tag === "Success"
392 ? AsyncResult.success(map(result.value))
393 : AsyncResult.failure(result.cause);
394 }
395
396 export function isAtomCommandInterrupted(result: AtomCommandResult<unknown, unknown>): boolean {
397 return result._tag === "Failure" && Cause.hasInterruptsOnly(result.cause);
398 }
399
400 export function squashAtomCommandFailure(result: {
401 readonly cause: Cause.Cause<unknown>;
402 }): unknown {
403 return Cause.squash(result.cause);
404 }
405
406 export async function settleAsyncResult<A, E>(
407 execute: () => Promise<Exit.Exit<A, E>>,
408 ): Promise<SettledAsyncResult<A, E>> {
409 try {
410 return AsyncResult.fromExit(await execute());
411 } catch (defect) {
412 return AsyncResult.failure(Cause.die(defect));
413 }
414 }
415
416 export interface AtomQueryOptions extends AtomCommandOptions {
417 /**
418 * Force a fresh execution instead of accepting a value the atom already
419 * holds (e.g. an SWR-cached result within its stale window). Used by
420 * verification flows where a cached failure must not satisfy a retry.
421 */
422 readonly refresh?: boolean;
423 }
424
425 /**
426 * A query atom's settled value. The atom stays mounted while the caller waits, and
427 * interrupting the caller releases it.
428 */
429 export const awaitAtomResult = <A, E>(
430 registry: AtomRegistry.AtomRegistry,
431 atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
432 options: Pick<AtomQueryOptions, "refresh"> = {},
433 ): Effect.Effect<A, E> =>
434 Effect.scoped(
435 Effect.gen(function* () {
436 yield* AtomRegistry.mount(registry, atom);
437 if (options.refresh) {
438 yield* Effect.sync(() => {
439 const current = registry.get(atom);
440 if (current._tag !== "Initial" && !current.waiting) {
441 registry.refresh(atom);
442 }
443 });
444 }
445 return yield* AtomRegistry.getResult(registry, atom, {
446 suspendOnWaiting: true,
447 });
448 }),
449 );
450
451 /** Reads a query atom from outside Effect. Effect callers yield `awaitAtomResult` instead. */
452 export function executeAtomQuery<A, E>(
453 registry: AtomRegistry.AtomRegistry,
454 atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
455 options: AtomQueryOptions = {},
456 reporter: AtomCommandReporter = console,
457 ): Promise<AtomCommandResult<A, E>> {
458 return settleAtEdge(awaitAtomResult(registry, atom, options), options, reporter);
459 }
460
461 /** Runs an effect on the calling fiber with the services of an atom runtime. */
462 export const provideAtomRuntime =
463 <R, ER>(registry: AtomRegistry.AtomRegistry, runtime: Atom.AtomRuntime<R, ER>) =>
464 <A, E>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | ER> =>
465 Effect.scoped(
466 AtomRegistry.mount(registry, runtime).pipe(
467 Effect.andThen(AtomRegistry.getResult(registry, runtime)),
468 Effect.flatMap((context) => Effect.provide(effect, context)),
469 ),
470 );
471
472 export function createRuntimeCommand<R, ER, W, A, E>(
473 runtime: Atom.AtomRuntime<R, ER>,
474 options: {
475 readonly label: string;
476 readonly execute: (input: W, registry: AtomRegistry.AtomRegistry) => Effect.Effect<A, E, R>;
477 readonly scheduler?: AtomCommandScheduler;
478 readonly concurrency?: AtomCommandConcurrency<W>;
479 },
480 ): AtomCommand<W, A, E | ER> {
481 const scheduler = options.scheduler ?? createAtomCommandScheduler();
482 const concurrency = options.concurrency ?? { mode: "parallel" as const };
483 return {
484 label: options.label,
485 run: (registry, input) =>
486 scheduler.schedule(
487 registry,
488 concurrency,
489 input,
490 Effect.suspend(() => options.execute(input, registry)).pipe(
491 provideAtomRuntime(registry, runtime),
492 ),
493 ),
494 };
495 }
496
497 export function reportAtomCommandResult(
498 result: AtomCommandResult<unknown, unknown>,
499 options: AtomCommandOptions = {},
500 reporter: AtomCommandReporter = console,
501 ): void {
502 if (AsyncResult.isSuccess(result) || Cause.hasInterruptsOnly(result.cause)) {
503 return;
504 }
505
506 const label = options.label ?? "atom command";
507 if (Cause.hasDies(result.cause)) {
508 if (options.reportDefect ?? true) {
509 reporter.error(`[atom-command] ${label} defected`, result.cause);
510 }
511 } else if (options.reportFailure ?? true) {
512 reporter.warn(`[atom-command] ${label} failed`, result.cause);
513 }
514 }
515
516 export async function settlePromise<A>(
517 execute: () => Promise<A>,
518 ): Promise<AtomCommandResult<A, never>> {
519 try {
520 return AsyncResult.success(await execute());
521 } catch (defect) {
522 return AsyncResult.failure(Cause.die(defect));
523 }
524 }
525
526 /** Where a query's answer is persisted, so an action's reply can be saved where a read would be. */
527 export const queryPersistenceKey = (label: string, input: unknown): string =>
528 JSON.stringify([label, input]);
529
530 function environmentRpcKey<Input>(target: {
531 readonly environmentId: EnvironmentIdType;
532 readonly input: Input;
533 }): string {
534 return JSON.stringify([target.environmentId, target.input]);
535 }
536
537 function parseEnvironmentRpcKey<Input>(key: string): {
538 readonly environmentId: EnvironmentIdType;
539 readonly input: Input;
540 } {
541 const decoded = JSON.parse(key) as [EnvironmentIdType, Input];
542 return {
543 environmentId: EnvironmentId.make(decoded[0]),
544 input: decoded[1],
545 };
546 }
547
548 function runInEnvironment<A, E, R>(
549 environmentId: EnvironmentIdType,
550 effect: Effect.Effect<A, E, R>,
551 ): Effect.Effect<
552 A,
553 E | EnvironmentRegistry.EnvironmentNotRegisteredError,
554 EnvironmentRegistry.EnvironmentRegistry | Exclude<R, EnvironmentSupervisor.EnvironmentSupervisor>
555 > {
556 return EnvironmentRegistry.EnvironmentRegistry.pipe(
557 Effect.flatMap((registry) => registry.run(environmentId, effect)),
558 );
559 }
560
561 /**
562 * `Atom.makeRefreshOnSignal` subscribes to the signal, so a query that outlives its view on an
563 * idle TTL still re-runs on every change. Reading the signal as a dependency instead lets the
564 * registry re-run a mounted query right away and only mark an idle one stale, which then
565 * refreshes on its next read.
566 */
567 const refreshOnSignalWhileRead =
568 <V>(signal: Atom.Atom<unknown>, isFinal: (value: V) => boolean) =>
569 <A extends V>(self: Atom.Atom<A>): Atom.Atom<A> => {
570 // The signal value each registry's data was read under. Held outside the node because the
571 // registry can sweep this node while `self` keeps the data, and the rebuilt node must still
572 // see a change it missed.
573 const readUnder = new WeakMap<AtomRegistry.AtomRegistry, unknown>();
574 return Atom.transform(
575 self,
576 (get) => {
577 const current = get(signal);
578 get.subscribe(self, (value) => get.setSelf(value));
579 const changed =
580 readUnder.has(get.registry) && !Object.is(readUnder.get(get.registry), current);
581 readUnder.set(get.registry, current);
582 if (changed && !isFinal(get.once(self))) get.refresh(self);
583 return get.once(self);
584 },
585 { initialValueTarget: self },
586 );
587 };
588
589 const refreshEveryUntilFinal =
590 <V>(intervalMs: number, isFinal: (value: V) => boolean) =>
591 <A extends V>(self: Atom.Atom<A>): Atom.Atom<A> =>
592 Atom.transform(
593 self,
594 (get) => {
595 const value = get(self);
596 if (!isFinal(value)) {
597 // @effect-diagnostics-next-line globalTimers:off - Mirrors `Atom.withRefresh`, outside an Effect runtime.
598 const handle = setTimeout(() => get.refresh(self), intervalMs);
599 get.addFinalizer(() => clearTimeout(handle));
600 }
601 return value;
602 },
603 { initialValueTarget: self },
604 );
605
606 const isStale = (result: AsyncResult.AsyncResult<unknown, unknown>, staleTimeMs: number) => {
607 if (result.waiting) return false;
608 const success =
609 result._tag === "Failure" ? Option.getOrUndefined(result.previousSuccess) : result;
610 if (success?._tag !== "Success") return result._tag === "Failure";
611 // @effect-diagnostics-next-line globalDate:off - `AsyncResult` timestamps come from `Date.now`.
612 return Date.now() - success.timestamp >= staleTimeMs;
613 };
614
615 /**
616 * Stale-while-revalidate on every mount. `Atom.swr` checks only when its node builds, which an idle
617 * TTL skips on a remount; this layer has no TTL (a transform drops it) while `self` keeps the cache.
618 * It reads `self` as a dependency, not a subscription, so `self` goes idle with its last reader.
619 */
620 export const revalidateOnMount =
621 (staleTimeMs: number) =>
622 <A, E>(
623 self: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
624 ): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
625 Atom.transform(
626 self,
627 (get) => {
628 const current = get(self);
629 if (Option.isNone(get.self()) && isStale(current, staleTimeMs)) {
630 let active = true;
631 get.addFinalizer(() => {
632 active = false;
633 });
634 // Deferred out of the build, which runs while React renders. A plain read drops this
635 // node before the task runs, so only a mount refetches.
636 get.registry.schedulerAsync.makeDispatcher().scheduleTask(() => {
637 if (active && isStale(get.once(self), staleTimeMs)) get.refresh(self);
638 }, 0);
639 }
640 return current;
641 },
642 { initialValueTarget: self },
643 );
644
645 /**
646 * A query result's data alone. A refetch always publishes a new result (a new
647 * timestamp, `waiting` on and off), while equal data keeps its identity, so a
648 * reader of only this skips the refetches that changed nothing.
649 */
650 export const selectEnvironmentQueryData = <A, E>(result: AsyncResult.AsyncResult<A, E>): A | null =>
651 AsyncResult.getOrElse(result, () => null);
652
653 type EnvironmentConnection = readonly [
654 SupervisorConnectionState,
655 Option.Option<RpcSession.RpcSession>,
656 ];
657
658 const connectionAtomsByRuntime = new WeakMap<
659 object,
660 (
661 environmentId: EnvironmentIdType,
662 ) => Atom.Atom<AsyncResult.AsyncResult<EnvironmentConnection | null>>
663 >();
664
665 /**
666 * One connection atom per environment for every query on a runtime, so a reader of the session
667 * generation and a query it re-runs see the same connection change at once.
668 */
669 function environmentConnectionAtoms<R, ER>(
670 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
671 ) {
672 const existing = connectionAtomsByRuntime.get(runtime);
673 if (existing !== undefined) return existing;
674 const family = Atom.family((environmentId: EnvironmentIdType) =>
675 runtime.atom(
676 followStreamInEnvironment(
677 environmentId,
678 Stream.unwrap(
679 EnvironmentSupervisor.EnvironmentSupervisor.pipe(
680 Effect.map((supervisor) =>
681 SubscriptionRef.changes(supervisor.state).pipe(
682 Stream.zipLatest(SubscriptionRef.changes(supervisor.session)),
683 ),
684 ),
685 ),
686 ),
687 ),
688 { initialValue: null },
689 ),
690 ) as (
691 environmentId: EnvironmentIdType,
692 ) => Atom.Atom<AsyncResult.AsyncResult<EnvironmentConnection | null>>;
693 connectionAtomsByRuntime.set(runtime, family);
694 return family;
695 }
696
697 export function environmentConnectionAtom<R, ER>(
698 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
699 environmentId: EnvironmentIdType,
700 ) {
701 return environmentConnectionAtoms(runtime)(environmentId);
702 }
703
704 const sessionGenerationAtomsByRuntime = new WeakMap<
705 object,
706 (environmentId: EnvironmentIdType) => Atom.Atom<number>
707 >();
708
709 /**
710 * Counts established sessions; it changes only when a new one comes up, so failed one-shot reads
711 * can watch it to run again. Keyed on the session object because the supervisor's `generation`
712 * restarts when the registry installs a new supervisor (re-pairing, route edits).
713 */
714 export function environmentSessionGenerationAtom<R, ER>(
715 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
716 environmentId: EnvironmentIdType,
717 ): Atom.Atom<number> {
718 let family = sessionGenerationAtomsByRuntime.get(runtime);
719 if (family === undefined) {
720 const connectionAtom = environmentConnectionAtoms(runtime);
721 const sessionsSeen = Atom.family((id: EnvironmentIdType) =>
722 Atom.make(
723 (get): { readonly session: RpcSession.RpcSession | null; readonly count: number } => {
724 const previous = Option.getOrElse(
725 get.self<{ readonly session: RpcSession.RpcSession | null; readonly count: number }>(),
726 () => ({ session: null, count: 0 }),
727 );
728 const connection = AsyncResult.getOrElse(get(connectionAtom(id)), () => null);
729 if (connection === null || connection[0].phase !== "connected") return previous;
730 const session = Option.getOrNull(connection[1]);
731 return session === null || session === previous.session
732 ? previous
733 : { session, count: previous.count + 1 };
734 },
735 ),
736 );
737 family = Atom.family((id: EnvironmentIdType) =>
738 Atom.make((get) => get(sessionsSeen(id)).count).pipe(
739 Atom.withLabel(`environment-session-generation:${id}`),
740 ),
741 );
742 sessionGenerationAtomsByRuntime.set(runtime, family);
743 }
744 return family(environmentId);
745 }
746
747 export function createEnvironmentQueryAtomFamily<R, ER, Input, A, E>(
748 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
749 options: EnvironmentQueryAtomOptions<
750 Input,
751 A,
752 E,
753 | EnvironmentSupervisor.EnvironmentSupervisor
754 | EnvironmentRegistry.EnvironmentRegistry
755 | AtomRegistry.AtomRegistry
756 | R
757 >,
758 ): (
759 target: { readonly environmentId: EnvironmentIdType; readonly input: Input },
760 mountScope?: string,
761 ) => Atom.Atom<AsyncResult.AsyncResult<A, E | ER | Error>> {
762 const connectionAtom = environmentConnectionAtoms(runtime);
763 // `Atom.family` holds members weakly and the mounted layer has no TTL, so each member lives
764 // as long as its cache: keyed weakly, this lets both go once the cache's TTL ends.
765 const cacheFamily = Atom.family((key: string) => {
766 const target = parseEnvironmentRpcKey<Input>(key);
767 const idleTtlMs = options.idleTtlMs ?? 5 * 60_000;
768 const queryAtom = runtime
769 .atom<
770 A,
771 | E
772 | ConnectionAttemptError
773 | EnvironmentRegistry.EnvironmentNotRegisteredError
774 | EnvironmentRpcUnavailableError
775 >((get) => {
776 const connection = AsyncResult.getOrElse(
777 get(connectionAtom(target.environmentId)),
778 () => null,
779 );
780 // A refetch that returns equal content keeps the previous value's
781 // references, so readers of the data skip re-rendering on idle polls.
782 const share = (value: A): A =>
783 reuseUnchanged(
784 Option.getOrUndefined(
785 Option.flatMap(get.self<AsyncResult.AsyncResult<A, unknown>>(), AsyncResult.value),
786 ),
787 value,
788 );
789 const emit = (value: A) =>
790 Effect.sync(() => get.setSelf(AsyncResult.success(share(value), { waiting: true }))).pipe(
791 // A value set while the atom builds wins over the build's own
792 // result, so a query that then settled synchronously would stay
793 // waiting forever. Suspend on a promise (`yieldNow` is drained
794 // inside the build) so the settled result arrives asynchronously.
795 Effect.andThen(Effect.promise(() => Promise.resolve())),
796 );
797 const execute = (): Effect.Effect<
798 A,
799 | E
800 | ConnectionAttemptError
801 | EnvironmentRegistry.EnvironmentNotRegisteredError
802 | EnvironmentRpcUnavailableError,
803 | EnvironmentRegistry.EnvironmentRegistry
804 | AtomRegistry.AtomRegistry
805 | Exclude<R, EnvironmentSupervisor.EnvironmentSupervisor>
806 > => {
807 if (connection === null) return Effect.never;
808 const [connectionState, session] = connection;
809 switch (connectionState.phase) {
810 case "connected":
811 return Option.isSome(session)
812 ? runInEnvironment(
813 target.environmentId,
814 options
815 .execute(
816 target.input,
817 emit,
818 Option.flatMap(
819 get.self<AsyncResult.AsyncResult<A, unknown>>(),
820 AsyncResult.value,
821 ),
822 )
823 .pipe(pendingOnceSessionReplaced(session.value)),
824 )
825 : Effect.never;
826 case "connecting":
827 case "backoff":
828 // A retry can take minutes. A query with an answer keeps showing it while it
829 // waits; one with nothing to show reports the failure the retry is recovering
830 // from, so its reader stops loading, and re-runs when the connection settles.
831 return connectionState.lastFailure !== null &&
832 Option.isNone(
833 Option.flatMap(
834 get.self<AsyncResult.AsyncResult<A, unknown>>(),
835 AsyncResult.value,
836 ),
837 )
838 ? Effect.fail(connectionState.lastFailure)
839 : Effect.never;
840 case "available":
841 case "offline":
842 case "blocked":
843 if (connectionState.lastFailure !== null) {
844 return Effect.fail(connectionState.lastFailure);
845 }
846 return Effect.fail(
847 new EnvironmentRpcUnavailableError({
848 environmentId: target.environmentId,
849 ...translatableMessage(
850 connectionState.phase === "offline"
851 ? msg("Environment {environmentId} is offline.", {
852 environmentId: target.environmentId,
853 })
854 : connectionState.phase === "blocked"
855 ? msg("Environment {environmentId} is blocked.", {
856 environmentId: target.environmentId,
857 })
858 : msg("Environment {environmentId} is not connected.", {
859 environmentId: target.environmentId,
860 }),
861 ),
862 }),
863 );
864 }
865 };
866 const onAnswer = options.onAnswer;
867 const answer = () =>
868 onAnswer === undefined
869 ? execute().pipe(Effect.map(share))
870 : execute().pipe(
871 Effect.map(share),
872 Effect.tap((value) => onAnswer(target, value, get.registry)),
873 );
874 if (!options.persistence) return answer();
875 const persistence = options.persistence;
876 const cacheKey = queryPersistenceKey(options.label, target.input);
877 const previous = Option.flatMap(
878 get.self<AsyncResult.AsyncResult<A, unknown>>(),
879 AsyncResult.value,
880 );
881 return Effect.gen(function* () {
882 const cached = Option.isSome(previous)
883 ? previous
884 : yield* persistence.load(target.environmentId, cacheKey);
885 if (
886 Option.isSome(cached) &&
887 (connection === null || connection[0].phase !== "connected")
888 ) {
889 return cached.value;
890 }
891 if (Option.isNone(previous) && Option.isSome(cached)) yield* emit(cached.value);
892 // Readers must not wait on the disk: web saves one IndexedDB row per listed PR's stats.
893 // The save ends with the query, so a removed environment's cache stays cleared.
894 return yield* answer().pipe(
895 Effect.tap((value) =>
896 persistence.save(target.environmentId, cacheKey, value).pipe(Effect.forkScoped),
897 ),
898 );
899 });
900 })
901 .pipe(Atom.setIdleTTL(idleTtlMs));
902 const isFinal = (result: AsyncResult.AsyncResult<A, unknown>) =>
903 options.isFinal !== undefined && Option.exists(AsyncResult.value(result), options.isFinal);
904 const intervalQuery =
905 options.refreshIntervalMs === undefined
906 ? queryAtom
907 : queryAtom.pipe(refreshEveryUntilFinal(options.refreshIntervalMs, isFinal));
908 const refreshTrigger = options.refreshTrigger?.(target);
909 return (
910 refreshTrigger === undefined
911 ? intervalQuery
912 : intervalQuery.pipe(refreshOnSignalWhileRead(refreshTrigger, isFinal))
913 ).pipe(Atom.setIdleTTL(idleTtlMs));
914 });
915 type QueryAtom = ReturnType<typeof cacheFamily>;
916 const membersByCache = new WeakMap<QueryAtom, Map<string | undefined, QueryAtom>>();
917 return (target, mountScope) => {
918 const key = environmentRpcKey(target);
919 const cache = cacheFamily(key);
920 let members = membersByCache.get(cache);
921 if (members === undefined) {
922 members = new Map();
923 membersByCache.set(cache, members);
924 }
925 const existing = members.get(mountScope);
926 if (existing !== undefined) return existing;
927 const member = cache.pipe(
928 revalidateOnMount(options.staleTimeMs ?? 30_000),
929 Atom.withLabel(`${options.label}:${key}${mountScope === undefined ? "" : `:${mountScope}`}`),
930 );
931 members.set(mountScope, member);
932 return member;
933 };
934 }
935
936 export function createEnvironmentSubscriptionAtomFamily<R, ER, Input, A, E>(
937 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
938 options: EnvironmentSubscriptionAtomOptions<
939 Input,
940 A,
941 E,
942 EnvironmentSupervisor.EnvironmentSupervisor | R
943 >,
944 ) {
945 const idleTtlMs = options.idleTtlMs ?? 5 * 60_000;
946 const label = (key: string) =>
947 options.sensitiveInput
948 ? `${options.label}:${parseEnvironmentRpcKey<Input>(key).environmentId}`
949 : `${options.label}:${key}`;
950 const live = Atom.family((key: string) => {
951 const target = parseEnvironmentRpcKey<Input>(key);
952 return runtime
953 .atom(
954 Stream.suspend(() =>
955 followStreamInEnvironment(target.environmentId, options.subscribe(target.input)),
956 ).pipe(options.completeWhen ? Stream.takeUntil(options.completeWhen) : (stream) => stream),
957 )
958 .pipe(Atom.setIdleTTL(idleTtlMs), Atom.withLabel(label(key)));
959 });
960 const { completeWhen, completedTtlMs } = options;
961 if (completeWhen === undefined || completedTtlMs === undefined) {
962 return (target: { readonly environmentId: EnvironmentIdType; readonly input: Input }) =>
963 live(environmentRpcKey(target));
964 }
965 const completed = Atom.family((key: string) =>
966 Atom.make(Option.none<A>()).pipe(
967 Atom.setIdleTTL(completedTtlMs),
968 Atom.withLabel(`${label(key)}:completed`),
969 ),
970 );
971 // Reading `completed` first drops the live subscription once its value is final.
972 const family = Atom.family((key: string) =>
973 Atom.make((get) => {
974 const done = get(completed(key));
975 if (Option.isSome(done)) return AsyncResult.success(done.value);
976 const result = get(live(key));
977 if (AsyncResult.isSuccess(result) && !result.waiting && completeWhen(result.value)) {
978 get.set(completed(key), Option.some(result.value));
979 }
980 return result;
981 }).pipe(Atom.setIdleTTL(idleTtlMs), Atom.withLabel(label(key))),
982 );
983 return (target: { readonly environmentId: EnvironmentIdType; readonly input: Input }) =>
984 family(environmentRpcKey(target));
985 }
986
987 export function createEnvironmentCommand<R, ER, Input, A, E>(
988 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
989 options: EnvironmentCommandAtomOptions<
990 Input,
991 A,
992 E,
993 EnvironmentSupervisor.EnvironmentSupervisor | EnvironmentRegistry.EnvironmentRegistry | R
994 >,
995 ) {
996 return createRuntimeCommand(runtime, {
997 label: options.label,
998 ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
999 ...(options.concurrency === undefined ? {} : { concurrency: options.concurrency }),
1000 execute: (target, registry) =>
1001 runInEnvironment(
1002 target.environmentId,
1003 options.execute(target.input, registry, target.environmentId),
1004 ),
1005 });
1006 }
1007
1008 export function createEnvironmentRpcQueryAtomFamily<
1009 R,
1010 ER,
1011 TTag extends Exclude<EnvironmentUnaryRpcTag, ClientGuardedRpcTag>,
1012 >(
1013 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
1014 options: {
1015 readonly label: string;
1016 readonly tag: TTag;
1017 readonly execute?: (
1018 input: EnvironmentRpcInput<TTag>,
1019 emit: (value: EnvironmentRpcSuccess<TTag>) => Effect.Effect<void>,
1020 previous: Option.Option<EnvironmentRpcSuccess<TTag>>,
1021 ) => Effect.Effect<
1022 EnvironmentRpcSuccess<TTag>,
1023 EnvironmentRpcFailure<TTag> | EnvironmentRpcUnavailableError,
1024 EnvironmentSupervisor.EnvironmentSupervisor | EnvironmentRegistry.EnvironmentRegistry
1025 >;
1026 readonly persistence?: QueryPersistence<EnvironmentRpcSuccess<TTag>>;
1027 readonly staleTimeMs?: number;
1028 readonly idleTtlMs?: number;
1029 readonly refreshIntervalMs?: number;
1030 readonly refreshTrigger?: (target: {
1031 readonly environmentId: EnvironmentIdType;
1032 readonly input: EnvironmentRpcInput<TTag>;
1033 }) => Atom.Atom<unknown> | undefined;
1034 readonly isFinal?: (value: EnvironmentRpcSuccess<TTag>) => boolean;
1035 readonly onAnswer?: QueryAnswerHandler<EnvironmentRpcInput<TTag>, EnvironmentRpcSuccess<TTag>>;
1036 },
1037 ) {
1038 return createEnvironmentQueryAtomFamily(runtime, {
1039 label: options.label,
1040 ...(options.persistence === undefined ? {} : { persistence: options.persistence }),
1041 ...(options.staleTimeMs === undefined ? {} : { staleTimeMs: options.staleTimeMs }),
1042 ...(options.idleTtlMs === undefined ? {} : { idleTtlMs: options.idleTtlMs }),
1043 ...(options.refreshIntervalMs === undefined
1044 ? {}
1045 : { refreshIntervalMs: options.refreshIntervalMs }),
1046 ...(options.refreshTrigger === undefined ? {} : { refreshTrigger: options.refreshTrigger }),
1047 ...(options.isFinal === undefined ? {} : { isFinal: options.isFinal }),
1048 ...(options.onAnswer === undefined ? {} : { onAnswer: options.onAnswer }),
1049 execute: (
1050 input: EnvironmentRpcInput<TTag>,
1051 emit: (value: EnvironmentRpcSuccess<TTag>) => Effect.Effect<void>,
1052 previous: Option.Option<EnvironmentRpcSuccess<TTag>>,
1053 ) => options.execute?.(input, emit, previous) ?? request(options.tag, input),
1054 });
1055 }
1056
1057 export function createEnvironmentRpcSubscriptionAtomFamily<
1058 R,
1059 ER,
1060 TTag extends EnvironmentSubscriptionRpcTag,
1061 B = EnvironmentRpcStreamValue<TTag>,
1062 >(
1063 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
1064 options: {
1065 readonly label: string;
1066 readonly tag: TTag;
1067 readonly idleTtlMs?: number;
1068 readonly completeWhen?: (value: B) => boolean;
1069 readonly completedTtlMs?: number;
1070 readonly transform?: (
1071 stream: Stream.Stream<
1072 EnvironmentRpcStreamValue<TTag>,
1073 EnvironmentRpcStreamFailure<TTag>,
1074 EnvironmentSupervisor.EnvironmentSupervisor | R
1075 >,
1076 ) => Stream.Stream<
1077 B,
1078 EnvironmentRpcStreamFailure<TTag>,
1079 EnvironmentSupervisor.EnvironmentSupervisor | R
1080 >;
1081 },
1082 ) {
1083 return createEnvironmentSubscriptionAtomFamily(runtime, {
1084 label: options.label,
1085 ...(options.completeWhen === undefined ? {} : { completeWhen: options.completeWhen }),
1086 ...(options.completedTtlMs === undefined ? {} : { completedTtlMs: options.completedTtlMs }),
1087 ...(options.idleTtlMs === undefined ? {} : { idleTtlMs: options.idleTtlMs }),
1088 subscribe: (input: EnvironmentRpcInput<TTag>) => {
1089 const stream = subscribe(options.tag, input);
1090 return options.transform === undefined
1091 ? (stream as Stream.Stream<
1092 B,
1093 EnvironmentRpcStreamFailure<TTag>,
1094 EnvironmentSupervisor.EnvironmentSupervisor | R
1095 >)
1096 : options.transform(stream);
1097 },
1098 });
1099 }
1100
1101 export function createEnvironmentRpcCommand<
1102 R,
1103 ER,
1104 TTag extends EnvironmentUnaryRpcTag,
1105 Input extends EnvironmentRpcInput<TTag> = EnvironmentRpcInput<TTag>,
1106 Started = undefined,
1107 >(
1108 runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
1109 options: {
1110 readonly label: string;
1111 readonly tag: TTag;
1112 /** Runs once authorized, as the request starts; what it returns reaches `onSuccess`. */
1113 readonly onStart?: (
1114 target: {
1115 readonly environmentId: EnvironmentIdType;
1116 readonly input: NoInfer<Input>;
1117 },
1118 registry: AtomRegistry.AtomRegistry,
1119 ) => Started;
1120 readonly execute?: (
1121 input: Input,
1122 registry: AtomRegistry.AtomRegistry,
1123 environmentId: EnvironmentIdType,
1124 ) => Effect.Effect<
1125 EnvironmentRpcSuccess<TTag>,
1126 EnvironmentRpcFailure<TTag> | EnvironmentRpcUnavailableError,
1127 EnvironmentSupervisor.EnvironmentSupervisor | EnvironmentRegistry.EnvironmentRegistry
1128 >;
1129 readonly scheduler?: AtomCommandScheduler;
1130 readonly concurrency?: AtomCommandConcurrency<{
1131 readonly environmentId: EnvironmentIdType;
1132 readonly input: NoInfer<Input>;
1133 }>;
1134 readonly onSuccess?: (
1135 target: {
1136 readonly environmentId: EnvironmentIdType;
1137 readonly input: NoInfer<Input>;
1138 },
1139 registry: AtomRegistry.AtomRegistry,
1140 result: EnvironmentRpcSuccess<TTag>,
1141 started: Started | undefined,
1142 ) => Effect.Effect<void, never, R>;
1143 readonly onSettled?: (
1144 target: {
1145 readonly environmentId: EnvironmentIdType;
1146 readonly input: NoInfer<Input>;
1147 },
1148 registry: AtomRegistry.AtomRegistry,
1149 ) => Effect.Effect<void, never, R>;
1150 },
1151 ) {
1152 const permissions = createCommandPermissions(runtime, options.tag);
1153 const command = createEnvironmentCommand(runtime, {
1154 label: options.label,
1155 ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
1156 ...(options.concurrency === undefined ? {} : { concurrency: options.concurrency }),
1157 execute: (input: Input, registry, environmentId) => {
1158 const target = {
1159 environmentId,
1160 input,
1161 };
1162 let started: Started | undefined;
1163 // Routing requires consent on the origin as well as the actual destination.
1164 // The transport check below deliberately checks the destination again.
1165 return permissions.authorize(registry, environmentId, input).pipe(
1166 Effect.andThen(() => {
1167 started = options.onStart?.(target, registry);
1168 return (
1169 options.execute?.(input, registry, environmentId) ?? requestGuarded(options.tag, input)
1170 );
1171 }),
1172 Effect.provideService(RpcPermissionGuard, {
1173 authorize: (id, method, payload) =>
1174 createCommandPermissions(runtime, method).authorize(registry, id, payload),
1175 }),
1176 Effect.tap(
1177 (result) => options.onSuccess?.(target, registry, result, started) ?? Effect.void,
1178 ),
1179 Effect.ensuring(options.onSettled?.(target, registry) ?? Effect.void),
1180 );
1181 },
1182 });
1183 return {
1184 ...command,
1185 requiredScopes: permissions.requiredScopes,
1186 permissionAtom: permissions.permissionAtom,
1187 };
1188 }