Commit 2dca7a1eddd27c823e4d9d0a316864c4ad9f95c5 | the-knife

author	Theo Browne <me@t3.gg> 2026-09-04 17:54:08-07:00
committer	GitHub <noreply@github.com> 2026-09-04 17:54:08-07:00
log	2dca7a1eddd27c823e4d9d0a316864c4ad9f95c5
tree	572d533ca6496ff6d5d25060b21f6b992576097a
parent	720e126b761ba0da112d8c68b589d20ab98a7eb0
signature	Signed by PGP key B5690EEEBB952194

fix(client): explain possible network blocking for T3 Connect (#9783)

12 files changed, 211 insertions(+), 44 deletions(-)

apps
- web
  - src
    components
    settings
    ConnectionsSettings.tsx
packages
- client-runtime
  - src
    authorization
    service.ts
    connection
    errors.test.ts
    errors.ts
    supervisor.test.ts
    supervisor.ts
    errors
    network.ts
    relay
    discovery.test.ts
    managedRelay.test.ts
    managedRelay.ts
    rpc
    session.test.ts
    session.ts

apps/web/src/components/settings/ConnectionsSettings.tsx+3-1

...	...	@@ -1524,7 +1524,9 @@ function SavedBackendListRow({
1524	1524	) : null}
1525	1525	{environment.connection.error && !resumingServerUpdate ? (
1526	1526	<p className="flex min-w-0 items-center gap-2 text-destructive text-xs">
1527		<span className="truncate">{connectionStatusText(environment.connection)}</span>
	1527	<span className="min-w-0 break-words">
	1528	{connectionStatusText(environment.connection)}
	1529	</span>
1528	1530	{errorTraceId ? (
1529	1531	<button
1530	1532	type="button"

packages/client-runtime/src/authorization/service.ts+4-3

...	...	@@ -80,9 +80,10 @@ function mapDpopSocketError(error: RemoteEnvironmentAuthError \| ConnectionAttemp
80	80
81	81	const fetchDescriptor = Effect.fn("clientRuntime.connection.remote.fetchDescriptor")(function* (
82	82	httpBaseUrl: string,
	83	connectionMethod: ClientConnectionMethod,
83	84	) {
84	85	return yield* fetchRemoteEnvironmentDescriptor({ httpBaseUrl }).pipe(
85		Effect.mapError(mapRemoteEnvironmentError),
	86	Effect.mapError((error) => mapRemoteEnvironmentError(error, connectionMethod)),
86	87	);
87	88	});
88	89
...	...	@@ -119,7 +120,7 @@ export const make = Effect.gen(function* () {
119	120	cachedDescriptor.validatedAtEpochMs + BEARER_DESCRIPTOR_CACHE_TTL_MS > now;
120	121	const descriptor = canReuseDescriptor
121	122	? cachedDescriptor.descriptor
122		: yield* fetchDescriptor(input.httpBaseUrl).pipe(
	123	: yield* fetchDescriptor(input.httpBaseUrl, input.connectionMethod).pipe(
123	124	Effect.provideService(HttpClient.HttpClient, httpClient),
124	125	);
125	126	if (descriptor.environmentId !== input.expectedEnvironmentId) {
...	...	@@ -252,7 +253,7 @@ export const make = Effect.gen(function* () {
252	253	"connection.remote_token_cache": "miss",
253	254	});
254	255	const bootstrap = yield* input.obtainBootstrap;
255		const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl).pipe(
	256	const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl, "relay").pipe(
256	257	Effect.provideService(HttpClient.HttpClient, httpClient),
257	258	Effect.withSpan("environment.authorization.descriptor"),
258	259	);

packages/client-runtime/src/connection/errors.test.ts+58-2

...	...	@@ -1,12 +1,40 @@
1	1	import { EnvironmentAuthInvalidError } from "@t3tools/contracts";
2		import { RelayAuthInvalidError } from "@t3tools/contracts/relay";
	2	import {
	3	RelayAuthInvalidError,
	4	RelayEnvironmentEndpointTimedOutError,
	5	} from "@t3tools/contracts/relay";
3	6	import { describe, expect, it } from "@effect/vitest";
4	7
5		import { mapManagedRelayError, mapRemoteDpopEnvironmentError } from "./errors.ts";
	8	import {
	9	mapManagedRelayError,
	10	mapRemoteDpopEnvironmentError,
	11	mapRemoteEnvironmentError,
	12	} from "./errors.ts";
6	13	import { DPOP_RETRY_HINT, DPOP_UNKNOWN_HINT } from "../relay/errorPresentation.ts";
7	14	import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
	15	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
	16	import { RemoteEnvironmentAuthFetchError, RemoteEnvironmentAuthTimeoutError } from "../rpc/http.ts";
8	17
9	18	describe("mapManagedRelayError", () => {
	19	it("keeps a timeout reported by the relay distinct from a local network failure", () => {
	20	const relayError = new RelayEnvironmentEndpointTimedOutError({
	21	code: "environment_endpoint_timed_out",
	22	traceId: "trace-server-timeout",
	23	});
	24	const mapped = mapManagedRelayError(
	25	new ManagedRelayRequestFailedError({
	26	action: "connect relay environment",
	27	cause: relayError,
	28	relayError,
	29	}),
	30	);
	31	expect(mapped).toMatchObject({
	32	reason: "timeout",
	33	detail: "Relay timed out while contacting the environment endpoint.",
	34	traceId: "trace-server-timeout",
	35	});
	36	});
	37
10	38	it("presents clock skew as one possible cause for a generic DPoP error", () => {
11	39	const mapped = mapManagedRelayError(
12	40	new ManagedRelayRequestFailedError({
...	...	@@ -48,6 +76,34 @@ describe("mapManagedRelayError", () => {
48	76	});
49	77
50	78	describe("mapRemoteDpopEnvironmentError", () => {
	79	it("keeps relay descriptor auth failures distinct from DPoP proof failures", () => {
	80	const error = new EnvironmentAuthInvalidError({
	81	code: "auth_invalid",
	82	reason: "invalid_credential",
	83	traceId: "trace-descriptor",
	84	});
	85	expect(mapRemoteEnvironmentError(error, "relay").message).toBe(
	86	"The environment credential is invalid.",
	87	);
	88	expect(mapRemoteDpopEnvironmentError(error).message).toBe(
	89	`The environment credential is invalid. ${DPOP_UNKNOWN_HINT}`,
	90	);
	91	});
	92
	93	it.each([
	94	new RemoteEnvironmentAuthFetchError({
	95	message: "Failed to fetch remote environment endpoint.",
	96	cause: new TypeError("Failed to fetch"),
	97	}),
	98	new RemoteEnvironmentAuthTimeoutError("https://environment.example.test", 10_000),
	99	])("suggests another network when the relay endpoint cannot be reached: $_tag", (error) => {
	100	const mapped = mapRemoteDpopEnvironmentError(error);
	101	expect(mapped).toMatchObject({
	102	_tag: "ConnectionTransientError",
	103	detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
	104	});
	105	});
	106
51	107	it("does not present a generic environment auth error as confirmed clock skew", () => {
52	108	const mapped = mapRemoteDpopEnvironmentError(
53	109	new EnvironmentAuthInvalidError({

packages/client-runtime/src/connection/errors.ts+7-4

...	...	@@ -1,8 +1,9 @@
1		import type { EnvironmentId } from "@t3tools/contracts";
	1	import type { ClientConnectionMethod, EnvironmentId } from "@t3tools/contracts";
2	2	import type { RelayProtectedError } from "@t3tools/contracts/relay";
3	3	import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
4	4	import { dpopFailureMessage, relayProtectedErrorMessage } from "../relay/errorPresentation.ts";
5	5	import type { RemoteEnvironmentAuthError } from "../authorization/remote.ts";
	6	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
6	7	import {
7	8	ConnectionBlockedError,
8	9	type ConnectionAttemptError,
...	...	@@ -113,7 +114,9 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
113	114
114	115	export function mapRemoteEnvironmentError(
115	116	error: RemoteEnvironmentAuthError,
	117	connectionMethod: ClientConnectionMethod = "direct",
116	118	): ConnectionAttemptError {
	119	const networkHint = connectionMethod === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
117	120	switch (error._tag) {
118	121	case "EnvironmentAuthInvalidError":
119	122	return new ConnectionBlockedError({
...	...	@@ -146,12 +149,12 @@ export function mapRemoteEnvironmentError(
146	149	case "RemoteEnvironmentAuthTimeoutError":
147	150	return new ConnectionTransientError({
148	151	reason: "timeout",
149		detail: error.message,
	152	detail: `${error.message}${networkHint}`,
150	153	});
151	154	case "RemoteEnvironmentAuthFetchError":
152	155	return new ConnectionTransientError({
153	156	reason: "network",
154		detail: error.message,
	157	detail: `${error.message}${networkHint}`,
155	158	});
156	159	case "EnvironmentInternalError":
157	160	return new ConnectionTransientError({
...	...	@@ -185,5 +188,5 @@ export function mapRemoteDpopEnvironmentError(
185	188	traceId: error.traceId,
186	189	});
187	190	}
188		return mapRemoteEnvironmentError(error);
	191	return mapRemoteEnvironmentError(error, "relay");
189	192	}

packages/client-runtime/src/connection/supervisor.test.ts+31-1

...	...	@@ -30,6 +30,7 @@ import {
30	30	import * as RpcSession from "../rpc/session.ts";
31	31	import * as EnvironmentSupervisor from "./supervisor.ts";
32	32	import * as ConnectionWakeups from "./wakeups.ts";
	33	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
33	34
34	35	const TARGET = new PrimaryConnectionTarget({
35	36	environmentId: EnvironmentId.make("environment-1"),
...	...	@@ -467,6 +468,35 @@ describe("EnvironmentSupervisor", () => {
467	468	}).pipe(Effect.provide(TestClock.layer())),
468	469	);
469	470
	471	it.effect(
	472	"shows a network hint for a stalled relay connection and clears it after recovery",
	473	() =>
	474	Effect.gen(function* () {
	475	const harness = yield* makeHarness({
	476	prepare: (attempt) =>
	477	attempt === 1 ? Effect.never : Effect.succeed(PREPARED_CONNECTION),
	478	});
	479	const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
	480	initiallyDesired: true,
	481	}).pipe(Effect.provide(harness.dependencies));
	482
	483	yield* awaitState(supervisor.state, (state) => state.phase === "connecting");
	484	yield* TestClock.adjust("15 seconds");
	485	const failed = yield* awaitState(supervisor.state, (state) => state.phase === "backoff");
	486	expect(failed.lastFailure?.message).toBe(
	487	`Test environment did not respond during connection setup. ${NETWORK_BLOCKING_HINT}`,
	488	);
	489
	490	yield* TestClock.adjust("3 seconds");
	491	const recovered = yield* awaitState(
	492	supervisor.state,
	493	(state) => state.phase === "connected",
	494	);
	495	expect(recovered.lastFailure).toBeNull();
	496	expect(yield* Ref.get(harness.prepareCount)).toBe(2);
	497	}).pipe(Effect.provide(TestClock.layer())),
	498	);
	499
470	500	it.effect("converts unexpected driver defects into retryable failures", () =>
471	501	Effect.gen(function* () {
472	502	const harness = yield* makeHarness({
...	...	@@ -475,7 +505,7 @@ describe("EnvironmentSupervisor", () => {
475	505	? Effect.die(new Error("Native transport defect."))
476	506	: Effect.succeed(PREPARED_CONNECTION),
477	507	});
478		const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
	508	const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
479	509	initiallyDesired: true,
480	510	}).pipe(Effect.provide(harness.dependencies));
481	511

packages/client-runtime/src/connection/supervisor.ts+6-2

...	...	@@ -28,6 +28,7 @@ import {
28	28	} from "./model.ts";
29	29	import * as RpcSession from "../rpc/session.ts";
30	30	import { safeErrorLogAttributes } from "../errors/safeLog.ts";
	31	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
31	32	import * as ConnectionWakeups from "./wakeups.ts";
32	33
33	34	const RETRY_DELAYS_MS = [3_000, 4_000, 8_000, 16_000] as const;
...	...	@@ -241,6 +242,9 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
241	242	\| ConnectionWakeups.ConnectionWakeups
242	243	> {
243	244	const target = entry.target;
	245	const setupTimeoutDetail = `${target.label} did not respond during connection setup.${
	246	target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : ""
	247	}`;
244	248	yield* annotateTarget(target);
245	249
246	250	const connectivity = yield* Connectivity.Connectivity;
...	...	@@ -626,7 +630,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
626	630	} else {
627	631	replacementError = new ConnectionTransientError({
628	632	reason: "timeout",
629		detail: `${target.label} did not respond during connection setup.`,
	633	detail: setupTimeoutDetail,
630	634	});
631	635	}
632	636
...	...	@@ -708,7 +712,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
708	712	failure: {
709	713	error: new ConnectionTransientError({
710	714	reason: "timeout",
711		detail: `${target.label} did not respond during connection setup.`,
	715	detail: setupTimeoutDetail,
712	716	}),
713	717	attemptSpan: Option.none(),
714	718	},

packages/client-runtime/src/errors/network.ts created+4

...	...	@@ -0,0 +1,4 @@
	1	// A failed request cannot distinguish filtering from an outage. Keep this a
	2	// possible cause, and suggest a way to check without changing server settings.
	3	export const NETWORK_BLOCKING_HINT =
	4	"Your DNS or firewall may be blocking T3 Connect. Try another network, such as a phone hotspot.";

packages/client-runtime/src/relay/discovery.test.ts+2-1

...	...	@@ -19,6 +19,7 @@ import * as Connectivity from "../connection/connectivity.ts";
19	19	import { ConnectionBlockedError, type NetworkStatus } from "../connection/model.ts";
20	20	import * as ConnectionWakeups from "../connection/wakeups.ts";
21	21	import * as RelayEnvironmentDiscovery from "./discovery.ts";
	22	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
22	23
23	24	const environments = [
24	25	{
...	...	@@ -305,7 +306,7 @@ describe("RelayEnvironmentDiscovery", () => {
305	306	expect(Option.getOrThrow(state.error)).toMatchObject({
306	307	_tag: "ConnectionTransientError",
307	308	reason: "timeout",
308		message: "Relay environment listing timed out.",
	309	message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
309	310	});
310	311	}).pipe(Effect.provide(layer));
311	312	}),

packages/client-runtime/src/relay/managedRelay.test.ts+39-1

...	...	@@ -9,10 +9,15 @@ import * as Effect from "effect/Effect";
9	9	import * as Fiber from "effect/Fiber";
10	10	import * as Layer from "effect/Layer";
11	11	import * as Tracer from "effect/Tracer";
	12	import * as Schema from "effect/Schema";
12	13	import * as TestClock from "effect/testing/TestClock";
13	14
14	15	import * as ManagedRelay from "./managedRelay.ts";
15	16	import { remoteHttpClientLayer } from "../rpc/http.ts";
	17	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
	18
	19	const encodeRelayError = Schema.encodeEffect(ManagedRelay.ManagedRelayClientError);
	20	const decodeRelayError = Schema.decodeUnknownEffect(ManagedRelay.ManagedRelayClientError);
16	21
17	22	function managedRelayTestLayer(
18	23	fetchFn: typeof globalThis.fetch,
...	...	@@ -529,11 +534,44 @@ describe("ManagedRelayClient", () => {
529	534	_tag: "ManagedRelayRequestTimeoutError",
530	535	activity: "Relay environment listing",
531	536	timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
532		message: "Relay environment listing timed out.",
	537	message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
533	538	});
534	539	}).pipe(Effect.provide(Layer.merge(TestClock.layer(), managedRelayTestLayer(fetchFn))));
535	540	});
536	541
	542	it.effect("suggests checking network filtering when fetch fails without a response", () => {
	543	const fetchFn = (() =>
	544	Promise.reject(new TypeError("Failed to fetch"))) satisfies typeof globalThis.fetch;
	545	return Effect.gen(function* () {
	546	const relayClient = yield* ManagedRelay.ManagedRelayClient;
	547	const error = yield* relayClient
	548	.listEnvironments({ clerkToken: "clerk-token" })
	549	.pipe(Effect.flip);
	550	expect(error).toMatchObject({
	551	_tag: "ManagedRelayRequestFailedError",
	552	transportFailed: true,
	553	message: `Could not list relay-managed environments. ${NETWORK_BLOCKING_HINT}`,
	554	});
	555	const encoded = yield* encodeRelayError(error);
	556	const decoded = yield* decodeRelayError(encoded);
	557	expect(decoded.message).toBe(error.message);
	558	}).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
	559	});
	560
	561	it.effect("does not suggest network filtering for an HTTP server error", () => {
	562	const fetchFn = (() =>
	563	Promise.resolve(
	564	new Response("Unavailable", { status: 503 }),
	565	)) satisfies typeof globalThis.fetch;
	566	return Effect.gen(function* () {
	567	const relayClient = yield* ManagedRelay.ManagedRelayClient;
	568	const error = yield* relayClient
	569	.listEnvironments({ clerkToken: "clerk-token" })
	570	.pipe(Effect.flip);
	571	expect(error.message).toBe("Could not list relay-managed environments.");
	572	}).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
	573	});
	574
537	575	it.effect("preserves typed relay trace IDs on client errors", () => {
538	576	const fetchFn = (() =>
539	577	Promise.resolve(

packages/client-runtime/src/relay/managedRelay.ts+7-2

...	...	@@ -44,6 +44,7 @@ import * as SynchronizedRef from "effect/SynchronizedRef";
44	44	import * as HttpClientError from "effect/unstable/http/HttpClientError";
45	45	import type * as HttpMethod from "effect/unstable/http/HttpMethod";
46	46	import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
	47	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
47	48
48	49	export interface ManagedRelayDpopProofInput {
49	50	readonly method: HttpMethod.HttpMethod;
...	...	@@ -126,7 +127,7 @@ export class ManagedRelayRequestTimeoutError extends Schema.TaggedErrorClass<Man
126	127	},
127	128	) {
128	129	override get message(): string {
129		return `${this.activity} timed out.`;
	130	return `${this.activity} timed out. ${NETWORK_BLOCKING_HINT}`;
130	131	}
131	132	}
132	133
...	...	@@ -145,13 +146,15 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
145	146	"ManagedRelayRequestFailedError",
146	147	{
147	148	action: ManagedRelayRequestAction,
	149	transportFailed: Schema.optionalKey(Schema.Boolean),
148	150	cause: Schema.Defect(),
149	151	relayError: Schema.optional(RelayProtectedError),
150	152	traceId: Schema.optional(Schema.String),
151	153	},
152	154	) {
153	155	override get message(): string {
154		return `Could not ${this.action}.`;
	156	const message = `Could not ${this.action}.`;
	157	return this.transportFailed ? `${message} ${NETWORK_BLOCKING_HINT}` : message;
155	158	}
156	159	}
157	160
...	...	@@ -307,6 +310,8 @@ function relayRequestError(action: ManagedRelayRequestAction) {
307	310	return (cause: RelayHttpRequestError): ManagedRelayClientError =>
308	311	new ManagedRelayRequestFailedError({
309	312	action,
	313	transportFailed:
	314	HttpClientError.isHttpClientError(cause) && cause.reason._tag === "TransportError",
310	315	cause,
311	316	...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
312	317	});

packages/client-runtime/src/rpc/session.test.ts+32-20

...	...	@@ -30,6 +30,7 @@ import {
30	30	ConnectionBlockedError,
31	31	ConnectionTransientError,
32	32	PrimaryConnectionTarget,
	33	RelayConnectionTarget,
33	34	type PreparedConnection,
34	35	} from "../connection/model.ts";
35	36	import * as EnvironmentSupervisor from "../connection/supervisor.ts";
...	...	@@ -37,6 +38,7 @@ import * as Persistence from "../platform/persistence.ts";
37	38	import * as RpcSession from "./session.ts";
38	39	import { makeEnvironmentServerConfigState } from "../state/server.ts";
39	40	import { applyServerConfigProjection } from "../state/serverConfigProjection.ts";
	41	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
40	42
41	43	type SocketEventType = "open" \| "message" \| "close" \| "error";
42	44	type SocketEvent = {
...	...	@@ -1157,27 +1159,37 @@ describe("RpcSessionFactory", () => {
1157	1159	),
1158	1160	);
1159	1161
1160		it.effect("fails readiness when the websocket never opens", () =>
1161		Effect.gen(function* () {
1162		const { factory, sockets } = yield* makeFactory();
	1162	for (const relay of [false, true]) {
	1163	it.effect(`fails readiness when the ${relay ? "relay" : "direct"} websocket never opens`, () =>
	1164	Effect.gen(function* () {
	1165	const { factory, sockets } = yield* makeFactory();
1163	1166
1164		const error = yield* Effect.scoped(
1165		Effect.gen(function* () {
1166		const session = yield* factory.connect(PREPARED);
1167		const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
1168		yield* awaitSocket(sockets);
	1167	const error = yield* Effect.scoped(
	1168	Effect.gen(function* () {
	1169	const session = yield* factory.connect({
	1170	...PREPARED,
	1171	target: relay
	1172	? new RelayConnectionTarget({
	1173	environmentId: TARGET.environmentId,
	1174	label: TARGET.label,
	1175	})
	1176	: TARGET,
	1177	});
	1178	const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
	1179	yield* awaitSocket(sockets);
1169	1180
1170		yield* TestClock.adjust("15 seconds");
1171		return yield* Fiber.join(readyFiber);
1172		}),
1173		);
	1181	yield* TestClock.adjust("15 seconds");
	1182	return yield* Fiber.join(readyFiber);
	1183	}),
	1184	);
1174	1185
1175		expect(error).toBeInstanceOf(ConnectionTransientError);
1176		expect(error).toMatchObject({
1177		reason: "transport",
1178		message: "Test environment could not establish a WebSocket connection.",
1179		});
1180		expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
1181		}).pipe(Effect.provide(TestClock.layer())),
1182		);
	1186	expect(error).toBeInstanceOf(ConnectionTransientError);
	1187	expect(error).toMatchObject({
	1188	reason: "transport",
	1189	message: `Test environment could not establish a WebSocket connection.${relay ? ` ${NETWORK_BLOCKING_HINT}` : ""}`,
	1190	});
	1191	expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
	1192	}).pipe(Effect.provide(TestClock.layer())),
	1193	);
	1194	}
1183	1195	});

packages/client-runtime/src/rpc/session.ts+18-7

...	...	@@ -15,6 +15,7 @@ import * as Option from "effect/Option";
15	15	import * as PubSub from "effect/PubSub";
16	16	import * as Ref from "effect/Ref";
17	17	import * as Schedule from "effect/Schedule";
	18	import * as Schema from "effect/Schema";
18	19	import type * as Scope from "effect/Scope";
19	20	import * as Stream from "effect/Stream";
20	21	import type * as Rpc from "effect/unstable/rpc/Rpc";
...	...	@@ -24,6 +25,7 @@ import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
24	25	import * as Socket from "effect/unstable/socket/Socket";
25	26
26	27	import { makeWsRpcProtocolClient, type WsRpcProtocolClient } from "./protocol.ts";
	28	import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
27	29	import type {
28	30	ConnectionAttemptError,
29	31	ConnectionTransientError,
...	...	@@ -117,8 +119,11 @@ function serverConfigReplayEvents(
117	119	];
118	120	}
119	121
	122	const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
	123
120	124	function mapSessionRpcError(
121	125	error: InitialConfigError \| ProbeError \| ServerConfigSubscriptionError,
	126	networkHint: string,
122	127	): ConnectionAttemptError {
123	128	switch (error._tag) {
124	129	case "EnvironmentAuthorizationError":
...	...	@@ -135,7 +140,7 @@ function mapSessionRpcError(
135	140	case "RpcClientError":
136	141	return new ConnectionTransientErrorClass({
137	142	reason: "transport",
138		detail: error.message,
	143	detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
139	144	});
140	145	}
141	146	}
...	...	@@ -150,6 +155,10 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
150	155	};
151	156
152	157	const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
	158	const networkHint =
	159	connection.target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : "";
	160	const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
	161	mapSessionRpcError(error, networkHint);
153	162	yield* Effect.annotateCurrentSpan({
154	163	"connection.environment.id": connection.environmentId,
155	164	});
...	...	@@ -164,9 +173,11 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
164	173	disconnected,
165	174	new ConnectionTransientErrorClass({
166	175	reason: "transport",
167		detail: wasConnected
168		? `${connection.label} disconnected.`
169		: `${connection.label} could not establish a WebSocket connection.`,
	176	detail: `${
	177	wasConnected
	178	? `${connection.label} disconnected.`
	179	: `${connection.label} could not establish a WebSocket connection.`
	180	}${networkHint}`,
170	181	}),
171	182	),
172	183	),
...	...	@@ -263,7 +274,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
263	274	}
264	275	return Effect.all([
265	276	Deferred.failCause(serverConfigExit, exit.cause),
266		Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapSessionRpcError)),
	277	Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapRpcError)),
267	278	]).pipe(Effect.asVoid);
268	279	}),
269	280	);
...	...	@@ -271,7 +282,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
271	282	const initialConfig = Effect.raceFirst(
272	283	Deferred.await(initialConfigDeferred),
273	284	Deferred.await(serverConfigExit).pipe(
274		Effect.mapError(mapSessionRpcError),
	285	Effect.mapError(mapRpcError),
275	286	Effect.flatMap(() => Effect.fail(configSubscriptionEndedError)),
276	287	),
277	288	).pipe(Effect.withSpan("environment.initialSync"));
...	...	@@ -330,7 +341,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
330	341	(config.environment.capabilities.connectionProbe === true
331	342	? protocolClient[WS_METHODS.serverProbe]({})
332	343	: protocolClient[WS_METHODS.serverGetConfig]({})
333		).pipe(Effect.mapError(mapSessionRpcError)),
	344	).pipe(Effect.mapError(mapRpcError)),
334	345	),
335	346	Effect.asVoid,
336	347	Effect.withSpan("clientRuntime.connection.rpcSession.probe"),