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
});