@devries-cameron20 / t3code Mirror · read-only / commits / e009276576
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 22:00 UTC

fix(connect): show which part of a T3 Connect connection failed and how to fix it (#22171)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Theo Browne committed Oct 20, 2026 at 00:13 UTC e0092765769fe66ebdd0ce257689e07df60becea
18 files changed +1210 -38
apps/mobile/src/features/connection/CloudEnvironmentRows.tsx
+7 -1
@@ -28,6 +28,7 @@ import { environmentPresentations } from "../../state/presentation";
28 import { availableCloudEnvironmentPresentation } from "../cloud/cloudEnvironmentPresentation";
29 import { hasCloudPublicConfig } from "../cloud/publicConfig";
30 import { ConnectionStatusDot } from "./ConnectionStatusDot";
31 +import { useConnectionDiagnosis } from "./ConnectionDiagnosisDetails";
32 import { environmentStatusText } from "./environmentStatusText";
33 import { type RelayEnvironmentView, useConnectionController } from "./useConnectionController";
34
@@ -193,6 +194,7 @@ function ConnectedCloudEnvironmentRow(props: {
194 );
195 const canRetry = presentation !== null && hasSavedBearerRoute(presentation.entry);
196 const enabled = props.environment.isEnabled && !unsupported;
197 + const { diagnosis } = useConnectionDiagnosis(props.environment.environmentId, presentation);
198 const [lastDescriptor, setLastDescriptor] = useState(props.descriptor);
199 if (props.descriptor !== undefined && props.descriptor !== lastDescriptor) {
200 setLastDescriptor(props.descriptor);
@@ -213,7 +215,11 @@ function ConnectedCloudEnvironmentRow(props: {
215 onValueChange={props.onSetEnabled}
216 onToggleError={props.onToggleError}
217 disabled={unsupported && !canRetry}
216 - {...(enabled || unsupported ? {} : { statusText: "Off" })}
218 + {...(enabled || unsupported
219 + ? diagnosis
220 + ? { statusText: diagnosis.headline }
221 + : {}
222 + : { statusText: "Off" })}
223 value={enabled}
224 />
225 );
apps/mobile/src/features/connection/ConnectionDiagnosisDetails.tsx new
+92
@@ -0,0 +1,92 @@
1 +import { useAtomValue } from "@effect/atom-react";
2 +import {
3 + AVAILABLE_CONNECTION_STATE,
4 + type ConnectionDiagnosis,
5 + connectionDiagnosisText,
6 + connectionRoutes,
7 + hasRelayRoute,
8 + presentConnectionDiagnosis,
9 + type EnvironmentPresentation,
10 +} from "@t3tools/client-runtime/connection";
11 +import type { EnvironmentId } from "@t3tools/contracts";
12 +import Constants from "expo-constants";
13 +import * as Option from "effect/Option";
14 +import { AsyncResult } from "effect/reactivity";
15 +import { View } from "react-native";
16 +
17 +import { AppText as Text } from "../../components/ui/AppText";
18 +import { Button } from "../../components/ui/Button";
19 +import { environmentCatalog } from "../../connection/catalog";
20 +import { cn } from "../../lib/cn";
21 +import { copyTextWithHaptic } from "../../lib/copyTextWithHaptic";
22 +
23 +const HOP_MARK = { ok: "✓", failed: "✕", unchecked: "–" } as const;
24 +const HOP_NOTE = { ok: "", failed: " · Failed", unchecked: " · Not checked" } as const;
25 +
26 +/** Same model as the web Settings row; null while connected, off, or not failed. */
27 +export function useConnectionDiagnosis(
28 + environmentId: EnvironmentId,
29 + presentation: EnvironmentPresentation | null,
30 +) {
31 + const state = Option.getOrElse(
32 + AsyncResult.value(useAtomValue(environmentCatalog.stateAtom(environmentId))),
33 + () => AVAILABLE_CONNECTION_STATE,
34 + );
35 + if (presentation === null || !presentation.entry.enabled) return { diagnosis: null, state };
36 + const phase = presentation.connection.phase;
37 + if (phase === "connected" || phase === "unsupported") return { diagnosis: null, state };
38 + const relayOnly =
39 + connectionRoutes(presentation.entry).length === 1 && hasRelayRoute(presentation.entry);
40 + const diagnosis = presentConnectionDiagnosis({
41 + hostLabel: presentation.entry.target.label,
42 + state,
43 + via: relayOnly ? "relay" : "direct",
44 + clientVersion: Constants.expoConfig?.version,
45 + serverVersion: presentation.serverConfig?.environment.serverVersion,
46 + });
47 + return { diagnosis, state };
48 +}
49 +
50 +export function ConnectionDiagnosisDetails(props: {
51 + readonly hostLabel: string;
52 + readonly diagnosis: ConnectionDiagnosis;
53 +}) {
54 + const { diagnosis } = props;
55 + return (
56 + <View className="gap-3">
57 + <View className="gap-0.5">
58 + {diagnosis.hops.map((hop) => (
59 + <Text
60 + key={hop.hop}
61 + className={cn(
62 + "text-sm",
63 + hop.result === "failed" ? "text-danger-foreground" : "text-foreground-muted",
64 + )}
65 + >
66 + {`${HOP_MARK[hop.result]} ${hop.label}${HOP_NOTE[hop.result]}`}
67 + </Text>
68 + ))}
69 + </View>
70 + <View className="gap-0.5">
71 + <Text className="text-sm font-t3-bold text-foreground">What to try</Text>
72 + {diagnosis.steps.map((step, index) => (
73 + <Text key={step} className="text-sm text-foreground-muted">
74 + {`${index + 1}. ${step}`}
75 + </Text>
76 + ))}
77 + </View>
78 + <Text selectable className="font-mono text-xs text-foreground-muted">
79 + {diagnosis.facts.map(([label, value]) => `${label}: ${value}`).join("\n")}
80 + </Text>
81 + <Button
82 + label="Copy diagnostics"
83 + icon="doc.on.doc"
84 + onPress={() => {
85 + copyTextWithHaptic(connectionDiagnosisText(props.hostLabel, diagnosis), {
86 + target: "connection-diagnostics",
87 + });
88 + }}
89 + />
90 + </View>
91 + );
92 +}
apps/mobile/src/features/connection/ConnectionEnvironmentRow.tsx
+21 -1
@@ -20,6 +20,7 @@ import { cn } from "../../lib/cn";
20 import type { ConnectedEnvironmentSummary } from "../../state/remote-runtime-types";
21 import { serverEnvironment } from "../../state/server";
22 import { environmentPresentations } from "../../state/presentation";
23 +import { ConnectionDiagnosisDetails, useConnectionDiagnosis } from "./ConnectionDiagnosisDetails";
24 import { ConnectionFormField } from "./ConnectionFormField";
25 import { ConnectionStatusDot } from "./ConnectionStatusDot";
26 import { environmentStatusText } from "./environmentStatusText";
@@ -58,6 +59,10 @@ export function ConnectionEnvironmentRow(props: {
59 environmentPresentations.presentationAtom(props.environment.environmentId),
60 );
61 const canRetry = presentation !== null && hasSavedBearerRoute(presentation.entry);
62 + const { diagnosis, state: connectionState } = useConnectionDiagnosis(
63 + props.environment.environmentId,
64 + presentation,
65 + );
66 const enabled = props.environment.isEnabled && !unsupported;
67 const statusLabel = connectionStatusLabel(props.environment);
68 const statusTraceId = enabled ? props.environment.connectionErrorTraceId : null;
@@ -118,7 +123,16 @@ export function ConnectionEnvironmentRow(props: {
123 {props.environment.displayUrl}
124 </Text>
125 ) : null}
121 - {statusLabel ? (
126 + {diagnosis ? (
127 + <>
128 + <Text className="text-xs text-danger-foreground">{diagnosis.headline}</Text>
129 + {connectionState.attempt > 0 ? (
130 + <Text className="text-xs text-foreground-muted">
131 + {`Retrying · attempt ${connectionState.attempt}`}
132 + </Text>
133 + ) : null}
134 + </>
135 + ) : statusLabel ? (
136 <Text
137 className={cn(
138 "text-xs",
@@ -177,6 +191,12 @@ export function ConnectionEnvironmentRow(props: {
191 exiting={FadeOut.duration(150)}
192 className="gap-3 px-4 pb-4"
193 >
194 + {diagnosis ? (
195 + <ConnectionDiagnosisDetails
196 + hostLabel={props.environment.environmentLabel}
197 + diagnosis={diagnosis}
198 + />
199 + ) : null}
200 {props.environment.isRelayManaged ? (
201 <Text className="text-sm text-foreground-muted">
202 Managed by T3 Connect. Tunnel details update automatically.
apps/web/src/components/ChatView.tsx
+4
@@ -359,6 +359,7 @@ import {
359 } from "../lib/composerContextRecords";
360 import { type ReviewCommentContext } from "../reviewCommentContext";
361 import { environmentCatalog } from "../connection/catalog";
362 +import { ConnectionDiagnosisHeadline } from "./settings/ConnectionDiagnosisDetails";
363 import { isDesktopLocalConnectionTarget } from "../connection/desktopLocal";
364 import { useEnvironmentDisconnectDelay } from "../hooks/useEnvironmentDisconnectDelay";
365 import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
@@ -2350,6 +2351,9 @@ export default function ChatView(props: ChatViewProps) {
2351 variant: unavailableConnection.phase === "error" ? "error" : "warning",
2352 icon: <WifiOffIcon />,
2353 title: `${activeEnvironmentUnavailableState.label} is ${environmentReconnecting ? "reconnecting" : "offline"}`,
2354 + description: activeEnvironment ? (
2355 + <ConnectionDiagnosisHeadline environment={activeEnvironment} />
2356 + ) : undefined,
2357 actions: (
2358 <>
2359 {!environmentReconnecting ? (
apps/web/src/components/settings/ConnectionDiagnosisDetails.tsx new
+201
@@ -0,0 +1,201 @@
1 +import { useAtomValue } from "@effect/atom-react";
2 +import {
3 + AVAILABLE_CONNECTION_STATE,
4 + type ConnectionDiagnosis,
5 + connectionDiagnosisText,
6 + connectionRoutes,
7 + hasRelayRoute,
8 + presentConnectionDiagnosis,
9 +} from "@t3tools/client-runtime/connection";
10 +import * as Option from "effect/Option";
11 +import { AsyncResult } from "effect/reactivity";
12 +import { ChevronRightIcon } from "lucide-react";
13 +import { useEffect, useState } from "react";
14 +
15 +import { APP_VERSION } from "~/branding";
16 +import { environmentCatalog } from "~/connection/catalog";
17 +import { type EnvironmentPresentation, useRelayEnvironmentDiscovery } from "~/state/environments";
18 +import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
19 +import { cn } from "../../lib/utils";
20 +import { Button } from "../ui/button";
21 +import { stackedThreadToast, toastManager } from "../ui/toast";
22 +
23 +/**
24 + * What failed on the way to an environment, or null while it is connected, off,
25 + * or has not failed. Reads the supervisor state itself so callers that only need
26 + * the headline do not re-render on every attempt.
27 + */
28 +export function useConnectionDiagnosis(environment: EnvironmentPresentation) {
29 + const environmentId = environment.environmentId;
30 + const state = Option.getOrElse(
31 + AsyncResult.value(useAtomValue(environmentCatalog.stateAtom(environmentId))),
32 + () => AVAILABLE_CONNECTION_STATE,
33 + );
34 + const relayStatus = useRelayEnvironmentDiscovery().environments.get(environmentId)?.status;
35 + const routes = connectionRoutes(environment.entry);
36 + const relayOnly = routes.length === 1 && hasRelayRoute(environment.entry);
37 + const phase = environment.connection.phase;
38 + const diagnosis =
39 + environment.entry.enabled && phase !== "connected" && phase !== "unsupported"
40 + ? presentConnectionDiagnosis({
41 + hostLabel: environment.label,
42 + state,
43 + via: relayOnly ? "relay" : "direct",
44 + // With a direct route as well, the relay's health says nothing about the route in use.
45 + relayStatus: relayOnly ? Option.getOrNull(relayStatus ?? Option.none()) : null,
46 + clientVersion: APP_VERSION,
47 + serverVersion: environment.serverConfig?.environment.serverVersion,
48 + })
49 + : null;
50 + return { diagnosis, state, relayOnly };
51 +}
52 +
53 +/** The failure headline alone, for banners outside Settings. */
54 +export function ConnectionDiagnosisHeadline({
55 + environment,
56 +}: {
57 + readonly environment: EnvironmentPresentation;
58 +}) {
59 + return useConnectionDiagnosis(environment).diagnosis?.headline ?? null;
60 +}
61 +
62 +const HOP_MARK = { ok: "✓", failed: "✕", unchecked: "–" } as const;
63 +const HOP_NOTE = { ok: "", failed: "Failed", unchecked: "Not checked" } as const;
64 +
65 +/** Ticks once per second, and only while a retry is scheduled, so the list around it does not re-render. */
66 +function RetryCountdown({ retryAt }: { readonly retryAt: number }) {
67 + const [now, setNow] = useState(Date.now);
68 + useEffect(() => {
69 + if (retryAt <= Date.now()) return;
70 + const timer = setInterval(() => setNow(Date.now()), 1_000);
71 + return () => clearInterval(timer);
72 + }, [retryAt]);
73 + const seconds = Math.ceil((retryAt - now) / 1_000);
74 + return <>{seconds > 0 ? `retrying in ${seconds}s` : "retrying"}</>;
75 +}
76 +
77 +/** The collapsed failure: the full headline, then the retry state and a Details toggle. */
78 +export function ConnectionDiagnosisSummary({
79 + diagnosis,
80 + retryAt,
81 + attempt,
82 + expanded,
83 + onToggle,
84 +}: {
85 + readonly diagnosis: ConnectionDiagnosis;
86 + readonly retryAt: number | null;
87 + readonly attempt: number;
88 + readonly expanded: boolean;
89 + readonly onToggle: () => void;
90 +}) {
91 + return (
92 + <div className="text-xs">
93 + <p className="text-destructive">{diagnosis.headline}</p>
94 + <p className="flex flex-wrap items-center gap-1 text-muted-foreground">
95 + {retryAt !== null ? <RetryCountdown retryAt={retryAt} /> : null}
96 + {retryAt !== null && attempt > 0 ? <span aria-hidden>·</span> : null}
97 + {attempt > 0 ? <span>attempt {attempt}</span> : null}
98 + {retryAt !== null || attempt > 0 ? <span aria-hidden>·</span> : null}
99 + <button
100 + type="button"
101 + aria-expanded={expanded}
102 + onClick={onToggle}
103 + className="inline-flex items-center gap-0.5 rounded-sm outline-none hover:text-foreground focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring"
104 + >
105 + Details
106 + <ChevronRightIcon
107 + aria-hidden
108 + className={cn(
109 + "size-3 transition-transform duration-150 motion-reduce:transition-none",
110 + expanded && "rotate-90",
111 + )}
112 + />
113 + </button>
114 + </p>
115 + </div>
116 + );
117 +}
118 +
119 +/** Hops in order, what to try, the facts, and the actions. */
120 +export function ConnectionDiagnosisPanel({
121 + hostLabel,
122 + diagnosis,
123 + onRetry,
124 + onAddRoute,
125 +}: {
126 + readonly hostLabel: string;
127 + readonly diagnosis: ConnectionDiagnosis;
128 + readonly onRetry: () => void;
129 + readonly onAddRoute: (() => void) | null;
130 +}) {
131 + const { copyToClipboard } = useCopyToClipboard({
132 + target: "connection diagnostics",
133 + onCopy: () => toastManager.add({ type: "success", title: "Diagnostics copied" }),
134 + onError: (error) =>
135 + toastManager.add(
136 + stackedThreadToast({
137 + type: "error",
138 + title: "Could not copy diagnostics",
139 + description: error.message,
140 + }),
141 + ),
142 + });
143 + return (
144 + <div className="mt-2 grid gap-3 border-t border-border/50 pt-2 text-xs">
145 + <ol className="grid gap-0.5">
146 + {diagnosis.hops.map((hop) => (
147 + <li
148 + key={hop.hop}
149 + className={cn(
150 + "flex gap-2",
151 + hop.result === "failed" ? "text-destructive" : "text-muted-foreground",
152 + )}
153 + >
154 + <span aria-hidden className="w-3 text-center">
155 + {HOP_MARK[hop.result]}
156 + </span>
157 + <span className={cn(hop.result === "ok" && "text-foreground")}>{hop.label}</span>
158 + <span>{HOP_NOTE[hop.result]}</span>
159 + </li>
160 + ))}
161 + </ol>
162 + <div>
163 + <p className="font-medium text-foreground">What to try</p>
164 + <ol className="list-decimal pl-4 text-muted-foreground">
165 + {diagnosis.steps.map((step) => (
166 + <li key={step}>{step}</li>
167 + ))}
168 + </ol>
169 + </div>
170 + <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-3 font-mono text-muted-foreground">
171 + {diagnosis.facts.map(([label, value]) => (
172 + <div key={label} className="contents">
173 + <dt>{label}</dt>
174 + <dd className="break-all text-foreground">{value}</dd>
175 + </div>
176 + ))}
177 + </dl>
178 + <div className="flex flex-wrap gap-2">
179 + <Button type="button" size="xs" variant="outline" onClick={onRetry}>
180 + Retry now
181 + </Button>
182 + <Button
183 + type="button"
184 + size="xs"
185 + variant="outline"
186 + onClick={() => {
187 + const text = connectionDiagnosisText(hostLabel, diagnosis);
188 + copyToClipboard(text, undefined);
189 + }}
190 + >
191 + Copy diagnostics
192 + </Button>
193 + {onAddRoute ? (
194 + <Button type="button" size="xs" variant="outline" onClick={onAddRoute}>
195 + Add direct route
196 + </Button>
197 + ) : null}
198 + </div>
199 + </div>
200 + );
201 +}
apps/web/src/components/settings/ConnectionsSettings.tsx
+40 -6
@@ -85,6 +85,11 @@ import { LocalEnvironmentSetting } from "./LocalEnvironmentSetting";
85 import { searchableSetting } from "./settingsSearch";
86 import { EnvironmentIconMenu } from "./EnvironmentIconPicker";
87 import { EnvironmentRoutesList } from "./EnvironmentRoutesList";
88 +import {
89 + ConnectionDiagnosisPanel,
90 + ConnectionDiagnosisSummary,
91 + useConnectionDiagnosis,
92 +} from "./ConnectionDiagnosisDetails";
93 import { usePreparedConnection } from "~/state/session";
94 import {
95 EnvironmentRow,
@@ -1468,6 +1473,7 @@ function SavedBackendListRow({
1473 }: SavedBackendListRowProps) {
1474 const [routesOpen, setRoutesOpen] = useState(false);
1475 const [permissionsOpen, setPermissionsOpen] = useState(false);
1476 + const [diagnosisOpen, setDiagnosisOpen] = useState(false);
1477 const environmentId = environment.environmentId;
1478 const unsupported = environment.connection.phase === "unsupported";
1479 const blocked = unsupported && !hasSavedBearerRoute(environment.entry);
@@ -1541,6 +1547,13 @@ function SavedBackendListRow({
1547 ) {
1548 setLastRelayHttpBaseUrl(discoveredRelayHttpBaseUrl);
1549 }
1550 + const retryNow = useAtomCommand(environmentCatalog.retryNow);
1551 + const {
1552 + diagnosis: currentDiagnosis,
1553 + state: connectionState,
1554 + relayOnly,
1555 + } = useConnectionDiagnosis(environment);
1556 + const diagnosis = resumingServerUpdate ? null : currentDiagnosis;
1557 const prepared = usePreparedConnection(environmentId);
1558 const connectedTarget = isConnected && prepared._tag === "Some" ? prepared.value.target : null;
1559 const mcpUrl = environmentMcpUrl({
@@ -1555,7 +1568,8 @@ function SavedBackendListRow({
1568 const routeCount = connectionRoutes(environment.entry).length;
1569 const subtitleText = [
1570 environmentTransportLabel(environment, connectedTarget),
1558 - resumingServerUpdate ? "Restarting" : status.text,
1571 + // The headline below names the failure in full.
1572 + diagnosis ? null : resumingServerUpdate ? "Restarting" : status.text,
1573 enabled && versionMismatch ? serverVersion : null,
1574 ]
1575 .filter((value): value is string => value !== null)
@@ -1598,6 +1612,7 @@ function SavedBackendListRow({
1612 enabled &&
1613 status.tone === "error" &&
1614 !resumingServerUpdate &&
1615 + !diagnosis &&
1616 "text-destructive",
1617 )}
1618 />
@@ -1649,14 +1664,33 @@ function SavedBackendListRow({
1664 </span>
1665 }
1666 below={
1652 - serverUpdateState.status !== "idle" ? (
1653 - <div className="mt-1 max-w-md">
1654 - <ServerUpdateProgress state={serverUpdateState} />
1655 - </div>
1656 - ) : null
1667 + <>
1668 + {diagnosis ? (
1669 + <ConnectionDiagnosisSummary
1670 + diagnosis={diagnosis}
1671 + retryAt={connectionState.phase === "backoff" ? connectionState.retryAt : null}
1672 + attempt={connectionState.attempt}
1673 + expanded={diagnosisOpen}
1674 + onToggle={() => setDiagnosisOpen((open) => !open)}
1675 + />
1676 + ) : null}
1677 + {serverUpdateState.status !== "idle" ? (
1678 + <div className="mt-1 max-w-md">
1679 + <ServerUpdateProgress state={serverUpdateState} />
1680 + </div>
1681 + ) : null}
1682 + </>
1683 }
1684 detail={
1685 <>
1686 + {diagnosis && diagnosisOpen ? (
1687 + <ConnectionDiagnosisPanel
1688 + hostLabel={environment.label}
1689 + diagnosis={diagnosis}
1690 + onRetry={() => void retryNow(environmentId)}
1691 + onAddRoute={relayOnly ? () => onAddRoute(environment) : null}
1692 + />
1693 + ) : null}
1694 {routesOpen && (
1695 <EnvironmentRoutesList
1696 environment={environment}
infra/relay/src/environments/EnvironmentConnector.test.ts
+33
@@ -827,6 +827,39 @@ describe("EnvironmentConnector", () => {
827 }).pipe(Effect.provide(layerConnectorTest(execute)));
828 });
829
830 + it.effect("names a dead tunnel when Cloudflare has no connector for it", () => {
831 + const execute = (request: HttpClientRequest.HttpClientRequest) =>
832 + Effect.succeed(
833 + HttpClientResponse.fromWeb(request, new Response("error code: 1033", { status: 530 })),
834 + );
835 +
836 + return Effect.gen(function* () {
837 + const connector = yield* EnvironmentConnector.EnvironmentConnector;
838 + const connect = yield* connector
839 + .connect({
840 + userId: "user_123",
841 + environmentId: "env-connector-test",
842 + clientProofKeyThumbprint: "client-proof-key-thumbprint",
843 + })
844 + .pipe(Effect.flip);
845 + const status = yield* connector.status({
846 + userId: "user_123",
847 + environmentId: "env-connector-test",
848 + });
849 +
850 + expect(connect).toMatchObject({
851 + _tag: "EnvironmentMintRequestFailed",
852 + endpointFailure: "tunnel_down",
853 + endpointStatus: 530,
854 + });
855 + expect(status).toMatchObject({
856 + status: "offline",
857 + endpointFailure: "tunnel_down",
858 + endpointStatus: 530,
859 + });
860 + }).pipe(Effect.provide(layerConnectorTest(execute)));
861 + });
862 +
863 it.effect("times out hung managed endpoint mint requests", () => {
864 let resolveRequestStarted: (() => void) | undefined;
865 const requestStarted = new Promise<void>((resolve) => {
infra/relay/src/environments/EnvironmentConnector.ts
+22 -7
@@ -14,6 +14,7 @@ import {
14 RelayEnvironmentMintResponseProofPayload,
15 RelayCloudMintCredentialProofPayload,
16 RelayEnvironmentConnectNotAuthorizedReason,
17 + RelayEnvironmentEndpointFailure,
18 type RelayEnvironmentConnectResponse,
19 type RelayEnvironmentStatusResponse,
20 type RelayManagedEndpoint,
@@ -42,6 +43,7 @@ import * as FetchHttpClient from "effect/http/FetchHttpClient";
43 import * as HttpClient from "effect/http/HttpClient";
44 import * as HttpClientError from "effect/http/HttpClientError";
45
46 +import { diagnoseEndpointFailure } from "./endpointFailure.ts";
47 import * as EnvironmentLinks from "./EnvironmentLinks.ts";
48 import * as ManagedEndpointAllocations from "./ManagedEndpointAllocations.ts";
49 import * as RelayConfiguration from "../Config.ts";
@@ -89,6 +91,8 @@ export class EnvironmentMintRequestFailed extends Schema.TaggedError<Environment
91 environmentId: Schema.String,
92 operation: Schema.Literals(["connect", "status"]),
93 cause: Schema.Defect(),
94 + endpointFailure: Schema.optionalKey(RelayEnvironmentEndpointFailure),
95 + endpointStatus: Schema.optionalKey(Schema.Number),
96 },
97 ) {
98 override get message(): string {
@@ -511,21 +515,25 @@ const make = Effect.gen(function* () {
515 status: "offline" as const,
516 checkedAt,
517 error: "Managed endpoint health request timed out.",
518 + endpointFailure: "timeout" as const,
519 ...offlineReasonFor(allocation),
520 traceId,
521 };
522 }
523 if (responseOption.value._tag === "Failure") {
524 const failureReason = environmentHealthRequestFailureReason(responseOption.value.cause);
525 + const diagnosis = yield* diagnoseEndpointFailure(responseOption.value.cause);
526 yield* Effect.annotateCurrentSpan({
527 "relay.environment_health.outcome": "failure",
528 "relay.environment_health.failure_reason": failureReason,
529 + "relay.environment_health.endpoint_failure": diagnosis.endpointFailure,
530 "relay.environment_health.trace_id": traceId,
531 });
532 yield* Effect.logWarning("Managed endpoint health request failed", {
533 environmentId: link.environmentId,
534 endpoint: endpoint.httpBaseUrl,
535 failureReason,
536 + endpointFailure: diagnosis.endpointFailure,
537 traceId,
538 });
539 return {
@@ -534,6 +542,7 @@ const make = Effect.gen(function* () {
542 status: "offline" as const,
543 checkedAt,
544 error: environmentHealthRequestFailureMessage(responseOption.value.cause),
545 + ...diagnosis,
546 ...offlineReasonFor(allocation),
547 traceId,
548 };
@@ -649,13 +658,19 @@ const make = Effect.gen(function* () {
658 .t3MintCredential({ payload: { proof } })
659 .pipe(
660 withoutRedirects,
652 - Effect.mapError(
653 - (cause) =>
654 - new EnvironmentMintRequestFailed({
655 - environmentId: input.environmentId,
656 - operation: "connect",
657 - cause,
658 - }),
661 + Effect.catch((cause) =>
662 + diagnoseEndpointFailure(cause).pipe(
663 + Effect.flatMap((diagnosis) =>
664 + Effect.fail(
665 + new EnvironmentMintRequestFailed({
666 + environmentId: input.environmentId,
667 + operation: "connect",
668 + cause,
669 + ...diagnosis,
670 + }),
671 + ),
672 + ),
673 + ),
674 ),
675 Effect.timeoutOption(Duration.millis(ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS)),
676 Effect.flatMap(
infra/relay/src/environments/endpointFailure.test.ts new
+35
@@ -0,0 +1,35 @@
1 +import { describe, expect, it } from "@effect/vitest";
2 +
3 +import { classifyEndpointResponse, classifyTransportFailure } from "./endpointFailure.ts";
4 +
5 +describe("classifyEndpointResponse", () => {
6 + it.each([
7 + [530, "error code: 1033", "tunnel_down"],
8 + [530, "", "tunnel_down"],
9 + [530, "error code: 1016", "dns"],
10 + [502, "Bad Gateway", "origin_unreachable"],
11 + [503, "", "origin_unreachable"],
12 + [521, "error code: 521", "refused"],
13 + [524, "", "timeout"],
14 + [526, "", "tls"],
15 + [404, "Not Found", "invalid_response"],
16 + [200, "<html>", "invalid_response"],
17 + ] as const)("maps HTTP %i with body %j to %s", (status, body, expected) => {
18 + expect(classifyEndpointResponse(status, body)).toBe(expected);
19 + });
20 +});
21 +
22 +describe("classifyTransportFailure", () => {
23 + const nested = (code: string) =>
24 + new TypeError("fetch failed", { cause: Object.assign(new Error(code), { code }) });
25 +
26 + it.each([
27 + ["ENOTFOUND", "dns"],
28 + ["ECONNREFUSED", "refused"],
29 + ["UNABLE_TO_VERIFY_LEAF_SIGNATURE: certificate", "tls"],
30 + ["UND_ERR_CONNECT_TIMEOUT", "timeout"],
31 + ["ECONNRESET", "unknown"],
32 + ] as const)("reads %s from the cause chain", (code, expected) => {
33 + expect(classifyTransportFailure(nested(code))).toBe(expected);
34 + });
35 +});
infra/relay/src/environments/endpointFailure.ts new
+93
@@ -0,0 +1,93 @@
1 +import type { RelayEnvironmentEndpointFailure } from "@t3tools/contracts/relay";
2 +import * as Duration from "effect/Duration";
3 +import * as Effect from "effect/Effect";
4 +import * as Option from "effect/Option";
5 +import * as HttpClientError from "effect/http/HttpClientError";
6 +
7 +export interface EndpointFailureDiagnosis {
8 + readonly endpointFailure: RelayEnvironmentEndpointFailure;
9 + readonly endpointStatus?: number;
10 +}
11 +
12 +/**
13 + * Cloudflare answers a Worker subrequest it cannot route with a plain-text body
14 + * such as `error code: 1033`. 1033 means no cloudflared connector is running for
15 + * the tunnel; 1016 means the origin hostname did not resolve.
16 + */
17 +export function classifyEndpointResponse(
18 + status: number,
19 + body: string,
20 +): RelayEnvironmentEndpointFailure {
21 + const cloudflareCode = /error code:\s*(\d{4})/i.exec(body)?.[1];
22 + if (cloudflareCode === "1016") return "dns";
23 + if (cloudflareCode === "1033") return "tunnel_down";
24 + switch (status) {
25 + case 530:
26 + return cloudflareCode === undefined ? "tunnel_down" : "unknown";
27 + // cloudflared answers 502 when nothing listens on the local origin port.
28 + case 502:
29 + case 503:
30 + return "origin_unreachable";
31 + case 521:
32 + return "refused";
33 + case 504:
34 + case 522:
35 + case 524:
36 + return "timeout";
37 + case 525:
38 + case 526:
39 + return "tls";
40 + default:
41 + // Any other status came from T3 Code itself, in a shape we did not expect.
42 + return "invalid_response";
43 + }
44 +}
45 +
46 +/** Reads the error code from the transport failure's cause chain, such as undici's `ECONNREFUSED`. */
47 +export function classifyTransportFailure(cause: unknown): RelayEnvironmentEndpointFailure {
48 + const parts: Array<string> = [];
49 + for (let current = cause, depth = 0; current instanceof Error && depth < 4; depth++) {
50 + const code = "code" in current ? current.code : undefined;
51 + parts.push(current.message, typeof code === "string" ? code : "");
52 + current = current.cause;
53 + }
54 + const text = parts.join(" ");
55 + if (/ENOTFOUND|EAI_AGAIN|getaddrinfo|\bDNS\b/i.test(text)) return "dns";
56 + if (/ECONNREFUSED|refused/i.test(text)) return "refused";
57 + if (/CERT|\bTLS\b|\bSSL\b|certificate/i.test(text)) return "tls";
58 + if (/ETIMEDOUT|TIMEOUT|timed out/i.test(text)) return "timeout";
59 + return "unknown";
60 +}
61 +
62 +const ERROR_BODY_READ_TIMEOUT = Duration.seconds(2);
63 +
64 +/** Turns a failed environment request into the cause the client shows the user. */
65 +export const diagnoseEndpointFailure = Effect.fnUntraced(function* (cause: unknown) {
66 + if (!HttpClientError.isHttpClientError(cause)) {
67 + return { endpointFailure: "invalid_response" } satisfies EndpointFailureDiagnosis;
68 + }
69 + const response = cause.response;
70 + if (response === undefined) {
71 + return {
72 + endpointFailure:
73 + cause.reason._tag === "TransportError"
74 + ? classifyTransportFailure(cause.reason.cause)
75 + : "unknown",
76 + } satisfies EndpointFailureDiagnosis;
77 + }
78 + // Only Cloudflare's 530 needs the body to tell a dead tunnel from a DNS error.
79 + const body =
80 + response.status === 530
81 + ? Option.getOrElse(
82 + yield* response.text.pipe(
83 + Effect.timeoutOption(ERROR_BODY_READ_TIMEOUT),
84 + Effect.orElseSucceed(() => Option.none<string>()),
85 + ),
86 + () => "",
87 + )
88 + : "";
89 + return {
90 + endpointFailure: classifyEndpointResponse(response.status, body),
91 + endpointStatus: response.status,
92 + } satisfies EndpointFailureDiagnosis;
93 +});
infra/relay/src/http/Api.ts
+6 -2
@@ -1105,10 +1105,12 @@ export const layerDpopClientApi = HttpApiBuilder.group(
1105 reason: error.reason,
1106 traceId,
1107 }),
1108 - EnvironmentMintRequestFailed: (_error, traceId) =>
1108 + EnvironmentMintRequestFailed: (error, traceId) =>
1109 new RelayEnvironmentEndpointUnavailableError({
1110 code: "environment_endpoint_unavailable",
1111 reason: "endpoint_request_failed",
1112 + ...(error.endpointFailure ? { endpointFailure: error.endpointFailure } : {}),
1113 + ...(error.endpointStatus ? { endpointStatus: error.endpointStatus } : {}),
1114 traceId,
1115 }),
1116 EnvironmentMintRequestTimedOut: (_error, traceId) =>
@@ -1148,10 +1150,12 @@ export const layerDpopClientApi = HttpApiBuilder.group(
1150 reason: error.reason,
1151 traceId,
1152 }),
1151 - EnvironmentMintRequestFailed: (_error, traceId) =>
1153 + EnvironmentMintRequestFailed: (error, traceId) =>
1154 new RelayEnvironmentEndpointUnavailableError({
1155 code: "environment_endpoint_unavailable",
1156 reason: "endpoint_request_failed",
1157 + ...(error.endpointFailure ? { endpointFailure: error.endpointFailure } : {}),
1158 + ...(error.endpointStatus ? { endpointStatus: error.endpointStatus } : {}),
1159 traceId,
1160 }),
1161 EnvironmentMintRequestTimedOut: (_error, traceId) =>
packages/client-runtime/src/connection/diagnosis.test.ts new
+207
@@ -0,0 +1,207 @@
1 +import {
2 + RelayAuthInvalidError,
3 + RelayEnvironmentEndpointTimedOutError,
4 + RelayEnvironmentEndpointUnavailableError,
5 + type RelayProtectedError,
6 +} from "@t3tools/contracts/relay";
7 +import { describe, expect, it } from "@effect/vitest";
8 +
9 +import { connectionDiagnosisText, presentConnectionDiagnosis } from "./diagnosis.ts";
10 +import {
11 + credentialMissingError,
12 + mapManagedRelayError,
13 + mapRemoteEnvironmentError,
14 +} from "./errors.ts";
15 +import {
16 + AVAILABLE_CONNECTION_STATE,
17 + type ConnectionAttemptError,
18 + type SupervisorConnectionState,
19 +} from "./model.ts";
20 +import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
21 +import { RemoteEnvironmentAuthFetchError } from "../rpc/http.ts";
22 +
23 +const backoff = (lastFailure: ConnectionAttemptError): SupervisorConnectionState => ({
24 + ...AVAILABLE_CONNECTION_STATE,
25 + desired: true,
26 + network: "online",
27 + phase: "backoff",
28 + attempt: 3,
29 + lastFailure,
30 + retryAt: Date.UTC(2026, 9, 19, 12, 0, 30),
31 +});
32 +
33 +const fromRelay = (relayError: RelayProtectedError) =>
34 + mapManagedRelayError(
35 + new ManagedRelayRequestFailedError({
36 + action: "connect relay environment",
37 + cause: relayError,
38 + relayError,
39 + }),
40 + );
41 +
42 +const unavailable = (endpointFailure: "tunnel_down" | "origin_unreachable") =>
43 + fromRelay(
44 + new RelayEnvironmentEndpointUnavailableError({
45 + code: "environment_endpoint_unavailable",
46 + reason: "endpoint_request_failed",
47 + endpointFailure,
48 + endpointStatus: endpointFailure === "tunnel_down" ? 530 : 502,
49 + traceId: "trace-1",
50 + }),
51 + );
52 +
53 +const diagnose = (state: SupervisorConnectionState, via: "relay" | "direct" = "relay") =>
54 + presentConnectionDiagnosis({ hostLabel: "Mac mini", state, via });
55 +
56 +const results = (state: SupervisorConnectionState, via?: "relay" | "direct") =>
57 + diagnose(state, via)?.hops.map((hop) => `${hop.hop}:${hop.result}`);
58 +
59 +describe("presentConnectionDiagnosis", () => {
60 + it("names a dead tunnel and points the fix at the host", () => {
61 + const diagnosis = diagnose(backoff(unavailable("tunnel_down")));
62 + expect(diagnosis?.headline).toBe("Mac mini's tunnel is offline");
63 + expect(results(backoff(unavailable("tunnel_down")))).toEqual([
64 + "device:ok",
65 + "relay:ok",
66 + "tunnel:failed",
67 + "server:unchecked",
68 + ]);
69 + expect(diagnosis?.steps.join(" ")).toContain("Tailscale exit node on Mac mini");
70 + expect(diagnosis?.facts).toContainEqual(["HTTP status", "530"]);
71 + expect(diagnosis?.facts).toContainEqual(["Trace ID", "trace-1"]);
72 + });
73 +
74 + it("tells a working tunnel apart from T3 Code not answering", () => {
75 + expect(diagnose(backoff(unavailable("origin_unreachable")))?.headline).toBe(
76 + "Tunnel works, but T3 Code on Mac mini did not answer",
77 + );
78 + expect(results(backoff(unavailable("origin_unreachable")), "direct")).toEqual([
79 + "device:ok",
80 + "relay:ok",
81 + "tunnel:ok",
82 + "server:failed",
83 + ]);
84 + });
85 +
86 + it("blames this device when it cannot reach a tunnel the relay already reached", () => {
87 + const failure = mapRemoteEnvironmentError(
88 + new RemoteEnvironmentAuthFetchError({ message: "Failed to fetch", cause: new TypeError() }),
89 + "relay",
90 + );
91 + // A learned LAN route makes the environment's usual route direct; the failure still names the relay.
92 + const diagnosis = diagnose(backoff(failure), "direct");
93 + expect(diagnosis?.headline).toBe("This device can't reach Mac mini's tunnel");
94 + expect(diagnosis?.hops).toHaveLength(4);
95 + expect(diagnosis?.steps.join(" ")).not.toContain("On Mac mini");
96 + });
97 +
98 + it("points a relay timeout at the host, not this device", () => {
99 + const failure = fromRelay(
100 + new RelayEnvironmentEndpointTimedOutError({
101 + code: "environment_endpoint_timed_out",
102 + traceId: "trace-3",
103 + }),
104 + );
105 + const diagnosis = diagnose(backoff(failure));
106 + expect(diagnosis?.headline).toBe("Mac mini did not answer in time");
107 + expect(diagnosis?.steps.join(" ")).toContain("On Mac mini");
108 + expect(diagnosis?.steps.join(" ")).not.toContain("on this device");
109 + });
110 +
111 + it("stops at T3 Connect when this device cannot reach the relay", () => {
112 + const failure = mapManagedRelayError(
113 + new ManagedRelayRequestFailedError({
114 + action: "connect relay environment",
115 + transportFailed: true,
116 + cause: new TypeError("Failed to fetch"),
117 + }),
118 + );
119 + expect(diagnose(backoff(failure))?.headline).toBe("This device can't reach T3 Connect");
120 + expect(results(backoff(failure))).toEqual([
121 + "device:ok",
122 + "relay:failed",
123 + "tunnel:unchecked",
124 + "server:unchecked",
125 + ]);
126 + });
127 +
128 + it("does not blame this device's network when T3 Connect answered with an error", () => {
129 + const failure = mapManagedRelayError(
130 + new ManagedRelayRequestFailedError({
131 + action: "connect relay environment",
132 + cause: new Error("Bad Gateway"),
133 + status: 502,
134 + }),
135 + );
136 + const diagnosis = diagnose(backoff(failure));
137 + expect(diagnosis?.headline).toBe("T3 Connect returned an error");
138 + expect(diagnosis?.steps.join(" ")).not.toContain("this device");
139 + });
140 +
141 + it("blames this device when its saved credential is missing", () => {
142 + const diagnosis = diagnose(backoff(credentialMissingError("connection-1")), "direct");
143 + expect(diagnosis?.hops[0]).toMatchObject({ hop: "device", result: "failed" });
144 + });
145 +
146 + it("names clock skew from a DPoP time window rejection", () => {
147 + const failure = fromRelay(
148 + new RelayAuthInvalidError({
149 + code: "auth_invalid",
150 + reason: "invalid_dpop",
151 + dpopFailureReason: "time_window",
152 + traceId: "trace-2",
153 + }),
154 + );
155 + expect(diagnose(backoff(failure))?.headline).toBe("This device's clock is off");
156 + });
157 +
158 + it("reports this device as offline before any other hop", () => {
159 + const state = { ...backoff(unavailable("tunnel_down")), network: "offline" as const };
160 + expect(diagnose(state)?.headline).toBe("This device is offline");
161 + expect(results(state)?.[0]).toBe("device:failed");
162 + });
163 +
164 + it("uses the relay health check before any connect attempt fails", () => {
165 + const diagnosis = presentConnectionDiagnosis({
166 + hostLabel: "Mac mini",
167 + state: AVAILABLE_CONNECTION_STATE,
168 + via: "relay",
169 + relayStatus: { status: "offline", endpointFailure: "tunnel_down", endpointStatus: 530 },
170 + });
171 + expect(diagnosis?.headline).toBe("Mac mini's tunnel is offline");
172 + const origin = presentConnectionDiagnosis({
173 + hostLabel: "Mac mini",
174 + state: AVAILABLE_CONNECTION_STATE,
175 + via: "direct",
176 + relayStatus: { status: "offline", endpointFailure: "origin_unreachable" },
177 + });
178 + expect(origin?.hops.map((hop) => hop.hop)).toEqual(["device", "relay", "tunnel", "server"]);
179 + });
180 +
181 + it("keeps the relay health status out of a failure that has its own cause", () => {
182 + const failure = mapRemoteEnvironmentError(
183 + new RemoteEnvironmentAuthFetchError({ message: "Failed to fetch", cause: new TypeError() }),
184 + );
185 + const diagnosis = presentConnectionDiagnosis({
186 + hostLabel: "Mac mini",
187 + state: backoff(failure),
188 + via: "direct",
189 + relayStatus: { status: "offline", endpointFailure: "tunnel_down", endpointStatus: 530 },
190 + });
191 + expect(diagnosis?.facts.map(([label]) => label)).not.toContain("HTTP status");
192 + });
193 +
194 + it("has nothing to say when nothing failed", () => {
195 + expect(diagnose(AVAILABLE_CONNECTION_STATE)).toBeNull();
196 + });
197 +
198 + it("writes every hop and fact into the copied diagnostics", () => {
199 + const diagnosis = diagnose(backoff(unavailable("tunnel_down")));
200 + if (diagnosis === null) throw new Error("expected a diagnosis");
201 + const text = connectionDiagnosisText("Mac mini", diagnosis);
202 + expect(text).toContain("Mac mini tunnel: FAILED");
203 + expect(text).toContain("T3 Code on Mac mini: not checked");
204 + expect(text).toContain("Cause: tunnel_down");
205 + expect(text).toContain("Attempts: 3");
206 + });
207 +});
packages/client-runtime/src/connection/diagnosis.ts new
+288
@@ -0,0 +1,288 @@
1 +import type { RelayEnvironmentStatusResponse } from "@t3tools/contracts/relay";
2 +import * as DateTime from "effect/DateTime";
3 +
4 +import type {
5 + ConnectionAttemptError,
6 + ConnectionFailureCause,
7 + ConnectionHop,
8 + SupervisorConnectionState,
9 +} from "./model.ts";
10 +
11 +export type ConnectionHopResult = "ok" | "failed" | "unchecked";
12 +
13 +export interface ConnectionDiagnosisHop {
14 + readonly hop: ConnectionHop;
15 + readonly label: string;
16 + readonly result: ConnectionHopResult;
17 +}
18 +
19 +export interface ConnectionDiagnosis {
20 + /** Names the part that failed, e.g. "Mac mini's tunnel is offline". */
21 + readonly headline: string;
22 + readonly hops: ReadonlyArray<ConnectionDiagnosisHop>;
23 + readonly steps: ReadonlyArray<string>;
24 + readonly facts: ReadonlyArray<readonly [label: string, value: string]>;
25 +}
26 +
27 +export interface ConnectionDiagnosisInput {
28 + readonly hostLabel: string;
29 + readonly state: SupervisorConnectionState;
30 + /** The environment's usual route, used when the failure does not name one. */
31 + readonly via: "relay" | "direct";
32 + /** The relay's last health check, which can name a cause before any connect attempt. */
33 + readonly relayStatus?: Pick<
34 + RelayEnvironmentStatusResponse,
35 + "status" | "endpointFailure" | "endpointStatus" | "offlineReason"
36 + > | null;
37 + readonly clientVersion?: string | undefined;
38 + readonly serverVersion?: string | null | undefined;
39 +}
40 +
41 +interface Located {
42 + readonly hop: ConnectionHop;
43 + readonly cause: ConnectionFailureCause | "offline" | "outdated" | "released" | null;
44 +}
45 +
46 +const NOT_ANSWERING: ReadonlySet<ConnectionFailureCause> = new Set([
47 + "origin_unreachable",
48 + "invalid_response",
49 +]);
50 +
51 +function locate(input: ConnectionDiagnosisInput): Located | null {
52 + const failure = input.state.lastFailure;
53 + if (input.state.network === "offline" || input.state.phase === "offline") {
54 + return { hop: "device", cause: "offline" };
55 + }
56 + if (failure?._tag === "ConnectionBlockedError" && failure.serverUpdateRequired) {
57 + return { hop: "server", cause: "outdated" };
58 + }
59 + if (failure?.hop !== undefined) {
60 + return { hop: failure.hop, cause: failure.failureCause ?? null };
61 + }
62 + if (failure !== null) {
63 + const unreachable =
64 + failure.reason === "network" ||
65 + failure.reason === "timeout" ||
66 + failure.reason === "transport";
67 + const via = failure.via ?? input.via;
68 + return { hop: unreachable && via === "relay" ? "tunnel" : "server", cause: null };
69 + }
70 + const status = input.relayStatus;
71 + if (status?.status !== "offline") return null;
72 + if (status.offlineReason === "tunnel_released") return { hop: "tunnel", cause: "released" };
73 + const cause = status.endpointFailure ?? null;
74 + return { hop: cause !== null && NOT_ANSWERING.has(cause) ? "server" : "tunnel", cause };
75 +}
76 +
77 +function headline(host: string, located: Located, failure: ConnectionAttemptError | null): string {
78 + switch (located.cause) {
79 + case "offline":
80 + return "This device is offline";
81 + case "outdated":
82 + return `${host} runs an older T3 Code`;
83 + case "clock_skew":
84 + return "This device's clock is off";
85 + case "not_linked":
86 + return `${host} is not linked to your T3 Connect account`;
87 + case "relay_error":
88 + return "T3 Connect returned an error";
89 + case "tunnel_pending":
90 + return `${host}'s tunnel is still being set up`;
91 + case "tunnel_not_enabled":
92 + return `T3 Connect is not turned on for ${host}`;
93 + case "released":
94 + case "tunnel_down":
95 + return `${host}'s tunnel is offline`;
96 + case "origin_unreachable":
97 + return `Tunnel works, but T3 Code on ${host} did not answer`;
98 + case "invalid_response":
99 + return `T3 Code on ${host} sent an unexpected answer`;
100 + case "dns":
101 + return `${host}'s tunnel address did not resolve`;
102 + case "tls":
103 + return `Secure connection to ${host}'s tunnel failed`;
104 + case "refused":
105 + return `${host}'s tunnel refused the connection`;
106 + case "timeout":
107 + return `${host} did not answer in time`;
108 + case "unknown":
109 + case null:
110 + break;
111 + }
112 + switch (located.hop) {
113 + case "device":
114 + return "This device could not prepare the connection";
115 + case "relay":
116 + return failure?.reason === "authentication"
117 + ? "T3 Connect did not accept this device's sign-in"
118 + : "This device can't reach T3 Connect";
119 + case "tunnel":
120 + // The relay already reached the host when this device fails on its own (#17629).
121 + return failure?.reason === "network" ||
122 + failure?.reason === "transport" ||
123 + failure?.reason === "timeout"
124 + ? `This device can't reach ${host}'s tunnel`
125 + : `T3 Connect could not reach ${host}'s tunnel`;
126 + case "server":
127 + return failure?.reason === "authentication" || failure?.reason === "permission"
128 + ? `T3 Code on ${host} did not accept this device`
129 + : `T3 Code on ${host} did not answer`;
130 + }
131 +}
132 +
133 +function steps(host: string, located: Located, failure: ConnectionAttemptError | null): string[] {
134 + const checkHost = `On ${host}, check Settings > Connections or run \`t3 connect status\`.`;
135 + switch (located.cause) {
136 + case "offline":
137 + return ["Connect this device to the internet. T3 Code reconnects on its own."];
138 + case "outdated":
139 + return [`Update T3 Code on ${host}.`];
140 + case "clock_skew":
141 + return [`Turn on automatic date and time on this device and on ${host}, then retry.`];
142 + case "not_linked":
143 + return [
144 + "Check that this device is signed in to the same T3 Connect account as the host.",
145 + `On ${host}, open Settings > Connections and turn T3 Connect on.`,
146 + ];
147 + case "tunnel_pending":
148 + return ["Wait a minute. T3 Code retries on its own.", checkHost];
149 + case "relay_error":
150 + return [
151 + "Wait a few minutes. T3 Code retries on its own.",
152 + "If it keeps failing, copy the diagnostics and report it.",
153 + ];
154 + case "tunnel_not_enabled":
155 + return [`On ${host}, open Settings > Connections and turn T3 Connect on.`];
156 + case "released":
157 + case "tunnel_down":
158 + return [
159 + `Make sure ${host} is awake and T3 Code is running on it.`,
160 + checkHost,
161 + `A VPN or Tailscale exit node on ${host} can block the tunnel (port 7844). Turn it off or allow the tunnel.`,
162 + ];
163 + case "origin_unreachable":
164 + case "invalid_response":
165 + return [`Open or restart T3 Code on ${host}.`, checkHost];
166 + // The relay saw these on its way to the host, so the fix is on the host.
167 + case "dns":
168 + case "tls":
169 + case "refused":
170 + case "timeout":
171 + case "unknown":
172 + return [`Make sure ${host} is awake and online.`, checkHost];
173 + case null:
174 + break;
175 + }
176 + switch (located.hop) {
177 + case "device":
178 + return [
179 + "Restart T3 Code on this device.",
180 + `If it keeps failing, remove ${host} from this device and add it again.`,
181 + ];
182 + case "relay":
183 + return failure?.reason === "authentication"
184 + ? ["Sign out of T3 Connect and sign in again."]
185 + : [
186 + "Check this device's internet connection.",
187 + "A VPN, firewall, or ad blocker on this device can block T3 Connect.",
188 + ];
189 + case "tunnel":
190 + return failure?.reason === "network" ||
191 + failure?.reason === "transport" ||
192 + failure?.reason === "timeout"
193 + ? [
194 + "A VPN, firewall, or DNS filter on this device can block the tunnel.",
195 + "Try another network, or add a direct route such as a Tailscale address.",
196 + ]
197 + : [`Make sure ${host} is awake and online.`, checkHost];
198 + case "server":
199 + return [
200 + `Make sure T3 Code is running on ${host}.`,
201 + "Retry. If it keeps failing, copy the diagnostics.",
202 + ];
203 + }
204 +}
205 +
206 +const HOP_ORDER = {
207 + relay: ["device", "relay", "tunnel", "server"],
208 + direct: ["device", "server"],
209 +} as const;
210 +
211 +function hopLabel(hop: ConnectionHop, host: string): string {
212 + switch (hop) {
213 + case "device":
214 + return "This device";
215 + case "relay":
216 + return "T3 Connect";
217 + case "tunnel":
218 + return `${host} tunnel`;
219 + case "server":
220 + return `T3 Code on ${host}`;
221 + }
222 +}
223 +
224 +/**
225 + * Turns a connection state into what failed, in order, and what to try. Returns
226 + * null when nothing has failed. Web and mobile render this same model.
227 + */
228 +export function presentConnectionDiagnosis(
229 + input: ConnectionDiagnosisInput,
230 +): ConnectionDiagnosis | null {
231 + const located = locate(input);
232 + if (located === null) return null;
233 + const host = input.hostLabel;
234 + const failure = input.state.lastFailure;
235 + const relayPath =
236 + located.hop === "relay" ||
237 + located.hop === "tunnel" ||
238 + (failure === null && input.relayStatus?.status === "offline") ||
239 + (failure?.via ?? input.via) === "relay";
240 + const order: ReadonlyArray<ConnectionHop> = HOP_ORDER[relayPath ? "relay" : "direct"];
241 + const failedIndex = order.indexOf(located.hop);
242 + const hops = order.map((hop, index): ConnectionDiagnosisHop => ({
243 + hop,
244 + label: hopLabel(hop, host),
245 + result: index < failedIndex ? "ok" : index === failedIndex ? "failed" : "unchecked",
246 + }));
247 +
248 + // The relay health check only explains the state when no attempt has failed yet.
249 + const httpStatus = failure !== null ? failure.httpStatus : input.relayStatus?.endpointStatus;
250 + const facts: Array<readonly [string, string]> = [];
251 + const add = (label: string, value: string | number | null | undefined) => {
252 + if (value !== null && value !== undefined && value !== "") facts.push([label, String(value)]);
253 + };
254 + add("Cause", located.cause ?? failure?.reason);
255 + add("HTTP status", httpStatus);
256 + add("Attempts", input.state.attempt > 0 ? input.state.attempt : null);
257 + add(
258 + "Next retry",
259 + input.state.retryAt === null
260 + ? null
261 + : DateTime.formatIso(DateTime.makeUnsafe(input.state.retryAt)),
262 + );
263 + add("Route", relayPath ? "T3 Connect" : "Direct");
264 + add("App version", input.clientVersion);
265 + add("Host version", input.serverVersion);
266 + add("Error", failure?.detail);
267 + add("Trace ID", failure?.traceId);
268 +
269 + return {
270 + headline: headline(host, located, failure),
271 + hops,
272 + steps: steps(host, located, failure),
273 + facts,
274 + };
275 +}
276 +
277 +const HOP_MARK = { ok: "ok", failed: "FAILED", unchecked: "not checked" } as const;
278 +
279 +/** One plain-text block for bug reports. */
280 +export function connectionDiagnosisText(hostLabel: string, diagnosis: ConnectionDiagnosis): string {
281 + return [
282 + `T3 Code connection to ${hostLabel}: ${diagnosis.headline}`,
283 + "",
284 + ...diagnosis.hops.map((hop) => `${hop.label}: ${HOP_MARK[hop.result]}`),
285 + "",
286 + ...diagnosis.facts.map(([label, value]) => `${label}: ${value}`),
287 + ].join("\n");
288 +}
packages/client-runtime/src/connection/errors.ts
+93 -18
@@ -14,6 +14,7 @@ export function profileMissingError(connectionId: string): ConnectionBlockedErro
14 return new ConnectionBlockedError({
15 reason: "configuration",
16 detail: `Connection profile ${connectionId} is unavailable.`,
17 + hop: "device",
18 });
19 }
20
@@ -21,6 +22,7 @@ export function credentialMissingError(connectionId: string): ConnectionBlockedE
22 return new ConnectionBlockedError({
23 reason: "authentication",
24 detail: `Connection credential ${connectionId} is unavailable.`,
25 + hop: "device",
26 });
27 }
28
@@ -35,15 +37,25 @@ export function environmentMismatchError(input: {
37 }
38
39 function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError {
40 + const detail = relayProtectedErrorMessage(error);
41 + const traceId = error.traceId;
42 switch (error._tag) {
43 case "RelayAuthInvalidError":
44 + return new ConnectionBlockedError({
45 + reason: "authentication",
46 + detail,
47 + traceId,
48 + hop: "relay",
49 + ...(error.dpopFailureReason === "time_window" ? { failureCause: "clock_skew" } : {}),
50 + });
51 case "RelayEnvironmentLinkProofExpiredError":
52 case "RelayAgentActivityPublishProofExpiredError":
53 case "RelayAgentActivityPublishProofInvalidError":
54 return new ConnectionBlockedError({
55 reason: "authentication",
45 - detail: relayProtectedErrorMessage(error),
46 - traceId: error.traceId,
56 + detail,
57 + traceId,
58 + hop: "relay",
59 });
60 case "RelayEnvironmentConnectNotAuthorizedError":
61 // A host swapping in a new tunnel leaves its allocation unready until
@@ -51,41 +63,72 @@ function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError
63 if (error.reason === "managed_endpoint_allocation_not_ready") {
64 return new ConnectionTransientError({
65 reason: "endpoint-unavailable",
54 - detail: relayProtectedErrorMessage(error),
55 - traceId: error.traceId,
66 + detail,
67 + traceId,
68 + hop: "tunnel",
69 + failureCause: "tunnel_pending",
70 + });
71 + }
72 + if (error.reason === "endpoint_provider_not_managed") {
73 + return new ConnectionBlockedError({
74 + reason: "permission",
75 + detail,
76 + traceId,
77 + hop: "tunnel",
78 + failureCause: "tunnel_not_enabled",
79 });
80 }
81 return new ConnectionBlockedError({
82 reason: "permission",
60 - detail: relayProtectedErrorMessage(error),
61 - traceId: error.traceId,
83 + detail,
84 + traceId,
85 + hop: "relay",
86 + ...(error.reason === "environment_link_not_found" ? { failureCause: "not_linked" } : {}),
87 });
88 case "RelayEnvironmentLinkProofInvalidError":
89 case "RelayEnvironmentLinkLimitExceededError":
65 - return new ConnectionBlockedError({
66 - reason: "permission",
67 - detail: relayProtectedErrorMessage(error),
68 - traceId: error.traceId,
69 - });
90 + return new ConnectionBlockedError({ reason: "permission", detail, traceId, hop: "relay" });
91 case "RelayEnvironmentEndpointTimedOutError":
92 return new ConnectionTransientError({
93 reason: "timeout",
73 - detail: relayProtectedErrorMessage(error),
74 - traceId: error.traceId,
94 + detail,
95 + traceId,
96 + hop: "tunnel",
97 + failureCause: "timeout",
98 + });
99 + case "RelayEnvironmentEndpointUnavailableError": {
100 + const endpointFailure =
101 + error.endpointFailure ??
102 + (error.reason === "endpoint_response_invalid" ? "invalid_response" : undefined);
103 + return new ConnectionTransientError({
104 + reason: "endpoint-unavailable",
105 + detail,
106 + traceId,
107 + // The tunnel carried the request when T3 Code is what failed to answer.
108 + hop:
109 + endpointFailure === "origin_unreachable" || endpointFailure === "invalid_response"
110 + ? "server"
111 + : "tunnel",
112 + via: "relay",
113 + ...(endpointFailure ? { failureCause: endpointFailure } : {}),
114 + ...(error.endpointStatus ? { httpStatus: error.endpointStatus } : {}),
115 });
76 - case "RelayEnvironmentEndpointUnavailableError":
116 + }
117 case "RelayEnvironmentLinkUnavailableError":
118 return new ConnectionTransientError({
119 reason: "endpoint-unavailable",
80 - detail: relayProtectedErrorMessage(error),
81 - traceId: error.traceId,
120 + detail,
121 + traceId,
122 + hop: "tunnel",
123 });
124 case "RelayEnvironmentLinkFailedError":
125 case "RelayInternalError":
126 return new ConnectionTransientError({
127 reason: "relay-unavailable",
87 - detail: relayProtectedErrorMessage(error),
88 - traceId: error.traceId,
128 + detail,
129 + traceId,
130 + hop: "relay",
131 + failureCause: "relay_error",
132 });
133 }
134 }
@@ -99,22 +142,30 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
142 return new ConnectionTransientError({
143 reason: "relay-unavailable",
144 detail: error.message,
145 + hop: "relay",
146 + // A status means the relay answered, so this device did reach it.
147 + ...(error.status !== undefined
148 + ? { httpStatus: error.status, failureCause: "relay_error" }
149 + : {}),
150 ...(error.traceId ? { traceId: error.traceId } : {}),
151 });
152 case "ManagedRelayRequestTimeoutError":
153 return new ConnectionTransientError({
154 reason: "timeout",
155 detail: error.message,
156 + hop: "relay",
157 });
158 case "ManagedRelayUrlInvalidError":
159 return new ConnectionBlockedError({
160 reason: "configuration",
161 detail: error.message,
162 + hop: "relay",
163 });
164 case "ManagedRelayAccessTokenScopesUnexpectedError":
165 return new ConnectionBlockedError({
166 reason: "permission",
167 detail: error.message,
168 + hop: "relay",
169 });
170 case "ManagedRelayDpopKeyLoadError":
171 case "ManagedRelayTokenProofCreationError":
@@ -122,6 +173,7 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
173 return new ConnectionBlockedError({
174 reason: "authentication",
175 detail: error.message,
176 + hop: "device",
177 });
178 }
179 }
@@ -131,12 +183,18 @@ export function mapRemoteEnvironmentError(
183 connectionMethod: ClientConnectionMethod = "direct",
184 ): ConnectionAttemptError {
185 const networkHint = connectionMethod === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
186 + // Over T3 Connect the relay already reached the host, so a request that never
187 + // arrives was blocked between this device and the tunnel.
188 + const unreachableHop = connectionMethod === "relay" ? "tunnel" : "server";
189 + const via = connectionMethod === "relay" ? "relay" : "direct";
190 switch (error._tag) {
191 case "EnvironmentAuthInvalidError":
192 return new ConnectionBlockedError({
193 reason: "authentication",
194 detail: "The environment credential is invalid.",
195 traceId: error.traceId,
196 + hop: "server",
197 + via,
198 });
199 case "EnvironmentScopeRequiredError":
200 case "EnvironmentOperationForbiddenError":
@@ -144,40 +202,54 @@ export function mapRemoteEnvironmentError(
202 reason: "permission",
203 detail: "The environment credential does not grant the required access.",
204 traceId: error.traceId,
205 + hop: "server",
206 + via,
207 });
208 case "EnvironmentRequestInvalidError":
209 return new ConnectionBlockedError({
210 reason: "configuration",
211 detail: "The environment rejected the authentication request.",
212 traceId: error.traceId,
213 + hop: "server",
214 + via,
215 });
216 case "EnvironmentResourceNotFoundError":
217 return new ConnectionBlockedError({
218 reason: "configuration",
219 detail: "The environment endpoint could not be found.",
220 traceId: error.traceId,
221 + hop: "server",
222 + via,
223 });
224 case "RemoteEnvironmentAuthTimeoutError":
225 return new ConnectionTransientError({
226 reason: "timeout",
227 detail: `${error.message}${networkHint}`,
228 + hop: unreachableHop,
229 + via,
230 });
231 case "RemoteEnvironmentAuthFetchError":
232 return new ConnectionTransientError({
233 reason: "network",
234 detail: `${error.message}${networkHint}`,
235 + hop: unreachableHop,
236 + via,
237 });
238 case "EnvironmentInternalError":
239 return new ConnectionTransientError({
240 reason: "remote-unavailable",
241 detail: "The environment could not authorize the connection.",
242 traceId: error.traceId,
243 + hop: "server",
244 + via,
245 });
246 case "RemoteEnvironmentAuthInvalidJsonError":
247 case "RemoteEnvironmentAuthUndeclaredStatusError":
248 return new ConnectionTransientError({
249 reason: "remote-unavailable",
250 detail: error.message,
251 + hop: "server",
252 + via,
253 });
254 }
255 }
@@ -195,6 +267,9 @@ export function mapRemoteDpopEnvironmentError(
267 reason: "authentication",
268 detail: dpopFailureMessage("The environment credential is invalid.", error.dpopFailureReason),
269 traceId: error.traceId,
270 + hop: "server",
271 + via: "relay",
272 + ...(error.dpopFailureReason === "time_window" ? { failureCause: "clock_skew" } : {}),
273 });
274 }
275 return mapRemoteEnvironmentError(error, "relay");
packages/client-runtime/src/connection/index.ts
+1
@@ -1,4 +1,5 @@
1 export * from "./catalog.ts";
2 +export * from "./diagnosis.ts";
3 export * as Connectivity from "./connectivity.ts";
4 export * as CredentialStore from "./credentialStore.ts";
5 export { type ConnectionDriverProgress, type EnvironmentConnectionLease } from "./driver.ts";
packages/client-runtime/src/connection/model.ts
+30
@@ -1,4 +1,5 @@
1 import { EnvironmentId } from "@t3tools/contracts";
2 +import { RelayEnvironmentEndpointFailure } from "@t3tools/contracts/relay";
3 import * as Schema from "effect/Schema";
4
5 const ConnectionTargetBase = {
@@ -76,12 +77,40 @@ export const ConnectionBlockedReason = Schema.Literals([
77 ]);
78 export type ConnectionBlockedReason = typeof ConnectionBlockedReason.Type;
79
80 +/** A part of the path to an environment: this device, T3 Connect, the host's tunnel, or T3 Code on the host. */
81 +export const ConnectionHop = Schema.Literals(["device", "relay", "tunnel", "server"]);
82 +export type ConnectionHop = typeof ConnectionHop.Type;
83 +
84 +/** The relay's endpoint failures plus the causes the client can name from other errors. */
85 +export const ConnectionFailureCause = Schema.Literals([
86 + ...RelayEnvironmentEndpointFailure.literals,
87 + "clock_skew",
88 + "not_linked",
89 + "relay_error",
90 + "tunnel_pending",
91 + "tunnel_not_enabled",
92 +]);
93 +export type ConnectionFailureCause = typeof ConnectionFailureCause.Type;
94 +
95 +/**
96 + * Where and why a failure happened, when the code that saw it knows. See
97 + * `presentConnectionDiagnosis`. `via` names the route when the hop alone does
98 + * not: T3 Code on the host can fail behind the tunnel or on a direct route.
99 + */
100 +const ConnectionFailureFields = {
101 + hop: Schema.optionalKey(ConnectionHop),
102 + via: Schema.optionalKey(Schema.Literals(["relay", "direct"])),
103 + failureCause: Schema.optionalKey(ConnectionFailureCause),
104 + httpStatus: Schema.optionalKey(Schema.Number),
105 +};
106 +
107 export class ConnectionTransientError extends Schema.TaggedError<ConnectionTransientError>()(
108 "ConnectionTransientError",
109 {
110 reason: ConnectionTransientReason,
111 detail: Schema.String,
112 traceId: Schema.optionalKey(Schema.String),
113 + ...ConnectionFailureFields,
114 },
115 ) {
116 override get message(): string {
@@ -95,6 +124,7 @@ export class ConnectionBlockedError extends Schema.TaggedError<ConnectionBlocked
124 reason: ConnectionBlockedReason,
125 detail: Schema.String,
126 traceId: Schema.optionalKey(Schema.String),
127 + ...ConnectionFailureFields,
128
129 serverUpdateRequired: Schema.optionalKey(Schema.Boolean),
130 },
packages/client-runtime/src/rpc/session.ts
+15 -3
@@ -126,27 +126,38 @@ const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
126 function mapSessionRpcError(
127 error: InitialConfigError | ProbeError | ServerConfigSubscriptionError,
128 networkHint: string,
129 + via: "relay" | "direct",
130 ): ConnectionAttemptError {
131 switch (error._tag) {
132 case "EnvironmentAuthorizationError":
133 return new ConnectionBlockedError({
134 reason: "permission",
135 detail: error.message,
136 + hop: "server",
137 + via,
138 });
139 case "KeybindingsConfigParseError":
140 case "ServerSettingsError":
141 return new ConnectionTransientErrorClass({
142 reason: "remote-unavailable",
143 detail: error.message,
144 + hop: "server",
145 + via,
146 });
147 case "RpcClientError":
148 return new ConnectionTransientErrorClass({
149 reason: "transport",
150 detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
151 + ...socketFailureLocation(via),
152 });
153 }
154 }
155
156 +/** Over T3 Connect the relay already reached the host, so a socket that drops failed between this device and the tunnel. */
157 +function socketFailureLocation(via: "relay" | "direct") {
158 + return { hop: via === "relay" ? "tunnel" : "server", via } as const;
159 +}
160 +
161 /** @public Service construction is part of the canonical Effect module API. */
162 export const make = Effect.fn("RpcSessionFactory.make")(function* (
163 options: RpcSessionOptions = {},
@@ -159,10 +170,10 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
170 };
171
172 const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
162 - const networkHint =
163 - connection.target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : "";
173 + const via = connection.target._tag === "RelayConnectionTarget" ? "relay" : "direct";
174 + const networkHint = via === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
175 const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
165 - mapSessionRpcError(error, networkHint);
176 + mapSessionRpcError(error, networkHint, via);
177 yield* Effect.annotateCurrentSpan({
178 "connection.environment.id": connection.environmentId,
179 });
@@ -185,6 +196,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
196 ? `${connection.label} stopped responding.`
197 : `${connection.label} disconnected.`
198 }${networkHint}`,
199 + ...socketFailureLocation(via),
200 }),
201 ),
202 ),
packages/contracts/src/relay.ts
+22
@@ -380,6 +380,24 @@ export const RelayEnvironmentEndpointUnavailableReason = Schema.Literals([
380 export type RelayEnvironmentEndpointUnavailableReason =
381 typeof RelayEnvironmentEndpointUnavailableReason.Type;
382
383 +/**
384 + * Which part of the path from the relay to the environment failed. `tunnel_down`
385 + * means Cloudflare has no live connector for the tunnel; `origin_unreachable`
386 + * means the tunnel answered but T3 Code behind it did not. Optional on the wire
387 + * so old relays and old clients keep working.
388 + */
389 +export const RelayEnvironmentEndpointFailure = Schema.Literals([
390 + "tunnel_down",
391 + "origin_unreachable",
392 + "dns",
393 + "tls",
394 + "refused",
395 + "timeout",
396 + "invalid_response",
397 + "unknown",
398 +]);
399 +export type RelayEnvironmentEndpointFailure = typeof RelayEnvironmentEndpointFailure.Type;
400 +
401 export const RelayAgentActivityPublishProofInvalidReason = Schema.Literals([
402 "invalid_signature_or_payload",
403 "replayed_nonce",
@@ -482,6 +500,8 @@ export class RelayEnvironmentEndpointUnavailableError extends Schema.TaggedError
500 {
501 code: Schema.Literal("environment_endpoint_unavailable"),
502 reason: RelayEnvironmentEndpointUnavailableReason,
503 + endpointFailure: Schema.optionalKey(RelayEnvironmentEndpointFailure),
504 + endpointStatus: Schema.optionalKey(Schema.Number),
505 traceId: TrimmedNonEmptyString,
506 },
507 { httpApiStatus: 502 },
@@ -829,6 +849,8 @@ export const RelayEnvironmentStatusResponse = Schema.Struct({
849 checkedAt: TrimmedNonEmptyString,
850 descriptor: Schema.optional(ExecutionEnvironmentDescriptor),
851 error: Schema.optional(TrimmedNonEmptyString),
852 + endpointFailure: Schema.optional(RelayEnvironmentEndpointFailure),
853 + endpointStatus: Schema.optional(Schema.Number),
854 offlineReason: Schema.optional(RelayEnvironmentOfflineReason),
855 traceId: Schema.optional(TrimmedNonEmptyString),
856 });