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