Skip to content

Commit a821f03

Browse files
fix(client-runtime): connection diagnosis no longer blames the host while this device's sign-in loads (pingdotgg#29352)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 3ddd398 commit a821f03

3 files changed

Lines changed: 67 additions & 6 deletions

File tree

‎docs/user/t3-connect-troubleshooting.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,8 @@ Fix:
9999

100100
## Sign-in, account, or link problems
101101

102-
T3 Connect does not have an active link between your account and the host.
102+
This device's T3 Connect sign-in is not ready yet, or T3 Connect does not have
103+
an active link between your account and the host.
103104

104105
- **The host is linked to a different account.** Sign in to the same T3 Connect
105106
account on this device and on the host. On the host, run `t3 connect logout`,
@@ -111,6 +112,9 @@ T3 Connect does not have an active link between your account and the host.
111112
`t3 service restart` on the host, or restart `t3 serve`.
112113
- **This device's sign-in expired, or the host no longer accepts this
113114
device.** Sign out of T3 Connect and sign in again.
115+
- **This device is still loading its T3 Connect sign-in.** Wait a moment;
116+
T3 Code retries on its own. If it keeps waiting, reload or restart T3 Code on
117+
this device.
114118
- **Your account reached its tunnel limit.** Remove an environment you do not
115119
use from your T3 account's T3 Connect page, or
116120
[link a paid T3 Chat account](./remote-access.md#more-machines-with-t3-chat)

‎packages/client-runtime/src/connection/diagnosis.test.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import { presentConnectionDiagnosis } from "./diagnosis.ts";
88
import { mapManagedRelayError, mapRemoteEnvironmentError } from "./errors.ts";
99
import {
1010
AVAILABLE_CONNECTION_STATE,
11+
ConnectionBlockedError,
12+
ConnectionTransientError,
1113
type ConnectionAttemptError,
1214
type SupervisorConnectionState,
1315
} from "./model.ts";
@@ -128,6 +130,30 @@ describe("presentConnectionDiagnosis", () => {
128130
expect(origin?.hops.map((hop) => hop.hop)).toEqual(["device", "relay", "tunnel", "server"]);
129131
});
130132

133+
it("blames this device, not the host, while its own T3 Connect sign-in loads", () => {
134+
const failure = new ConnectionTransientError({
135+
reason: "session-pending",
136+
detail: "Waiting for the T3 Connect sign-in to load.",
137+
});
138+
const diagnosis = diagnose(backoff(failure));
139+
expect(diagnosis?.headline).not.toContain("did not answer");
140+
expect(diagnosis?.hops.find((hop) => hop.result === "failed")?.hop).toBe("device");
141+
expect(diagnosis?.steps.join(" ")).not.toContain("Mac mini");
142+
expect(diagnosis?.moreInfoUrl).toContain("sign-in-account-or-link-problems");
143+
// A host with a LAN route as well uses the direct route, still authorized through T3 Connect.
144+
expect(diagnose(backoff(failure), "direct")?.moreInfoUrl).toContain(
145+
"sign-in-account-or-link-problems",
146+
);
147+
});
148+
149+
it("does not report hops as working when the failure names none", () => {
150+
const failure = new ConnectionBlockedError({
151+
reason: "authentication",
152+
detail: "Your cloud sign-in changed. Sign in again to authorize the environment.",
153+
});
154+
expect(results(backoff(failure))).not.toContainEqual(expect.stringMatching(/:ok$/));
155+
});
156+
131157
it("keeps the relay health status out of a failure that has its own cause", () => {
132158
const failure = mapRemoteEnvironmentError(
133159
new RemoteEnvironmentAuthFetchError({ message: "Failed to fetch", cause: new TypeError() }),

‎packages/client-runtime/src/connection/diagnosis.ts‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ export interface ConnectionDiagnosis {
2626
readonly hops: ReadonlyArray<ConnectionDiagnosisHop>;
2727
readonly steps: ReadonlyArray<string>;
2828
readonly facts: ReadonlyArray<readonly [label: string, value: string]>;
29-
/** The troubleshooting guide section for this failure. Null for direct routes. */
29+
/** The troubleshooting guide section for this failure. Null for direct routes, except a pending T3 Connect sign-in. */
3030
readonly moreInfoUrl: string | null;
3131
}
3232

@@ -46,7 +46,15 @@ export interface ConnectionDiagnosisInput {
4646

4747
interface Located {
4848
readonly hop: ConnectionHop;
49-
readonly cause: ConnectionFailureCause | "offline" | "outdated" | "released" | null;
49+
readonly cause:
50+
| ConnectionFailureCause
51+
| "offline"
52+
| "outdated"
53+
| "released"
54+
| "session_pending"
55+
| null;
56+
/** The failure named no hop, so the hops before this one were never probed. */
57+
readonly guessed?: true;
5058
}
5159

5260
const NOT_ANSWERING: ReadonlySet<ConnectionFailureCause> = new Set([
@@ -62,6 +70,9 @@ function locate(input: ConnectionDiagnosisInput): Located | null {
6270
if (failure?._tag === "ConnectionBlockedError" && failure.serverUpdateRequired) {
6371
return { hop: "server", cause: "outdated" };
6472
}
73+
if (failure?.reason === "session-pending") {
74+
return { hop: "device", cause: "session_pending" };
75+
}
6576
if (failure?.hop !== undefined) {
6677
return { hop: failure.hop, cause: failure.failureCause ?? null };
6778
}
@@ -71,7 +82,11 @@ function locate(input: ConnectionDiagnosisInput): Located | null {
7182
failure.reason === "timeout" ||
7283
failure.reason === "transport";
7384
const via = failure.via ?? input.via;
74-
return { hop: unreachable && via === "relay" ? "tunnel" : "server", cause: null };
85+
return {
86+
hop: unreachable && via === "relay" ? "tunnel" : "server",
87+
cause: null,
88+
guessed: true,
89+
};
7590
}
7691
const status = input.relayStatus;
7792
if (status?.status !== "offline") return null;
@@ -84,6 +99,8 @@ function headline(host: string, located: Located, failure: ConnectionAttemptErro
8499
switch (located.cause) {
85100
case "offline":
86101
return "This device is offline";
102+
case "session_pending":
103+
return "This device is still loading its T3 Connect sign-in";
87104
case "outdated":
88105
return `${host} runs an older T3 Code`;
89106
case "clock_skew":
@@ -141,6 +158,11 @@ function steps(host: string, located: Located, failure: ConnectionAttemptError |
141158
switch (located.cause) {
142159
case "offline":
143160
return ["Connect this device to the internet. T3 Code reconnects on its own."];
161+
case "session_pending":
162+
return [
163+
"Wait a moment. T3 Code retries on its own.",
164+
"If it keeps waiting, reload or restart T3 Code on this device.",
165+
];
144166
case "outdated":
145167
return [`Update T3 Code on ${host}.`];
146168
case "clock_skew":
@@ -220,6 +242,7 @@ function helpSection(
220242
return "the-host-runs-an-older-t3-code";
221243
case "clock_skew":
222244
return "the-clock-is-off";
245+
case "session_pending":
223246
case "not_linked":
224247
case "tunnel_not_enabled":
225248
return "sign-in-account-or-link-problems";
@@ -300,7 +323,12 @@ export function presentConnectionDiagnosis(
300323
const hops = order.map((hop, index): ConnectionDiagnosisHop => ({
301324
hop,
302325
label: hopLabel(hop, host),
303-
result: index < failedIndex ? "ok" : index === failedIndex ? "failed" : "unchecked",
326+
result:
327+
index === failedIndex
328+
? "failed"
329+
: index < failedIndex && located.guessed !== true
330+
? "ok"
331+
: "unchecked",
304332
}));
305333

306334
// The relay health check only explains the state when no attempt has failed yet.
@@ -329,7 +357,10 @@ export function presentConnectionDiagnosis(
329357
hops,
330358
steps: steps(host, located, failure),
331359
facts,
332-
moreInfoUrl: relayPath ? t3ConnectTroubleshootingUrl(helpSection(located, failure)) : null,
360+
moreInfoUrl:
361+
relayPath || located.cause === "session_pending"
362+
? t3ConnectTroubleshootingUrl(helpSection(located, failure))
363+
: null,
333364
};
334365
}
335366

0 commit comments

Comments
 (0)