The best way to control Claude Code, Codex and more from any computer or phone
feat(connect): t3 connect checks that other devices can reach this machine (#22172)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 20, 2026 at 01:18 UTC
91d7bf3eefec7390ef7e38124db1062bc429c0c1
22 files changed
+1148
-35
apps/mobile/src/features/connection/ConnectionDiagnosisDetails.tsx
+10
-1
@@ -12,7 +12,7 @@ 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";
15
+import { Linking, View } from "react-native";
16
17
import { AppText as Text } from "../../components/ui/AppText";
18
import { Button } from "../../components/ui/Button";
@@ -52,6 +52,7 @@ export function ConnectionDiagnosisDetails(props: {
52
readonly diagnosis: ConnectionDiagnosis;
53
}) {
54
const { diagnosis } = props;
55
+ const { moreInfoUrl } = diagnosis;
56
return (
57
<View className="gap-3">
58
<View className="gap-0.5">
@@ -87,6 +88,14 @@ export function ConnectionDiagnosisDetails(props: {
88
});
89
}}
90
/>
91
+ {moreInfoUrl ? (
92
+ <Button
93
+ label="More info"
94
+ icon="safari"
95
+ tone="secondary"
96
+ onPress={() => void Linking.openURL(moreInfoUrl).catch(() => undefined)}
97
+ />
98
+ ) : null}
99
</View>
100
);
101
}
apps/server/src/cli/connect.ts
+109
-8
@@ -1,6 +1,10 @@
1
import {
2
+ AuthRelayReadScope,
3
AuthRelayWriteScope,
4
+ type AuthEnvironmentScope,
5
+ type EnvironmentConnectReachability,
6
EnvironmentHttpApi,
7
+ formatConnectReachable,
8
type RelayClientInstallProgressEvent,
9
type RelayClientInstallProgressStage,
10
} from "@t3tools/contracts";
@@ -9,6 +13,7 @@ import * as HostProcess from "@t3tools/shared/HostProcess";
13
import * as RelayClient from "@t3tools/shared/relayClient";
14
import { withRelayClientTracing } from "@t3tools/shared/relayTracing";
15
import * as Cause from "effect/Cause";
16
+import * as Clock from "effect/Clock";
17
import * as Config from "effect/Config";
18
import * as Console from "effect/Console";
19
import * as Crypto from "effect/Crypto";
@@ -29,6 +34,7 @@ import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
34
import * as BootService from "../cloud/bootService.ts";
35
import * as CliState from "../cloud/CliState.ts";
36
import * as CliTokenManager from "../cloud/CliTokenManager.ts";
37
+import { formatReachabilityFailure } from "../cloud/ConnectReachability.ts";
38
import { filterRelayResponse } from "../cloud/relayResponse.ts";
39
import {
40
CLOUD_LINK_REVOKED,
@@ -142,6 +148,9 @@ interface CloudCliStatus {
148
readonly relayUrl: string | null;
149
readonly publishAgentActivity: boolean;
150
readonly relayClient: RelayClient.RelayClientStatus;
151
+ readonly linkMode: CliState.CliDesiredLinkMode;
152
+ /** `null` when no server answered the live check, or none ran because no tunnel is wanted. */
153
+ readonly reachability: EnvironmentConnectReachability | null;
154
}
155
156
function formatRelayClientStatus(executable: RelayClient.RelayClientStatus): ReadonlyArray<string> {
@@ -199,8 +208,19 @@ function formatCloudStatus(status: CloudCliStatus, options?: { readonly json?: b
208
` Relay: ${status.relayUrl ?? "not provisioned"}`,
209
` Publish agent activity: ${status.publishAgentActivity ? "enabled" : "disabled"}`,
210
...formatRelayClientStatus(status.relayClient),
202
- "",
203
- "This is saved setup, not a live connection check. Check the background service with `t3 service status`.",
211
+ ...(!status.desired || status.linkMode !== "managed"
212
+ ? []
213
+ : status.reachability === null
214
+ ? [
215
+ "",
216
+ "No running server answered, so reachability was not checked. Check the background service with `t3 service status`.",
217
+ ]
218
+ : status.reachability.status === "reachable"
219
+ ? [
220
+ "",
221
+ `✓ Other devices can reach this machine · ${formatConnectReachable(status.reachability)}`,
222
+ ]
223
+ : ["", formatReachabilityFailure(status.reachability)]),
224
...(nextStep ? ["", `Next: ${nextStep}`] : []),
225
].join("\n");
226
}
@@ -261,11 +281,12 @@ export const acquireRelayClientForLink = Effect.fn("cloud.cli.acquire_relay_clie
281
282
const withCloudCliSessionToken = <A, E, R>(
283
environmentAuth: EnvironmentAuth.EnvironmentAuth["Service"],
284
+ scope: AuthEnvironmentScope,
285
run: (token: string) => Effect.Effect<A, E, R>,
286
) =>
287
Effect.acquireUseRelease(
288
environmentAuth.issueSession({
268
- scopes: [AuthRelayWriteScope],
289
+ scopes: [scope],
290
subject: "cloud-cli",
291
label: "t3 connect cli",
292
}),
@@ -287,7 +308,7 @@ const runLiveCloudUnlink = Effect.fn("cloud.cli.run_live_unlink")(function* () {
308
309
const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
310
const result = yield* Effect.exit(
290
- withCloudCliSessionToken(environmentAuth, (token) =>
311
+ withCloudCliSessionToken(environmentAuth, AuthRelayWriteScope, (token) =>
312
HttpApiClient.make(EnvironmentHttpApi, {
313
baseUrl: runtimeState.value.origin,
314
}).pipe(
@@ -303,6 +324,73 @@ const runLiveCloudUnlink = Effect.fn("cloud.cli.run_live_unlink")(function* () {
324
: ({ status: "failed", cause: result.cause } satisfies LiveCloudActionResult);
325
});
326
327
+// One check probes the endpoint, the tunnel edge, and Tailscale, each with its own timeout.
328
+const CLOUD_CLI_REACHABILITY_TIMEOUT = Duration.seconds(30);
329
+const CLOUD_CLI_REACHABILITY_WAIT = Duration.seconds(60);
330
+const CLOUD_CLI_REACHABILITY_RETRY = Duration.seconds(5);
331
+
332
+/** Asks the running server to check T3 Connect now. `null` when no server answers. */
333
+const checkLiveReachability = Effect.fn("cloud.cli.check_live_reachability")(function* () {
334
+ const config = yield* ServerConfig.ServerConfig;
335
+ const runtimeState = yield* readPersistedServerRuntimeState(config.serverRuntimeStatePath);
336
+ if (Option.isNone(runtimeState)) return null;
337
+ const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
338
+ return yield* withCloudCliSessionToken(environmentAuth, AuthRelayReadScope, (token) =>
339
+ HttpApiClient.make(EnvironmentHttpApi, { baseUrl: runtimeState.value.origin }).pipe(
340
+ Effect.flatMap((client) =>
341
+ client.connect.checkReachability({ headers: { authorization: `Bearer ${token}` } }),
342
+ ),
343
+ Effect.timeout(CLOUD_CLI_REACHABILITY_TIMEOUT),
344
+ ),
345
+ ).pipe(Effect.orElseSucceed(() => null));
346
+});
347
+
348
+function formatAlertBox(text: string): string {
349
+ const lines = text.split("\n");
350
+ const width = Math.max(...lines.map((line) => line.length));
351
+ const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
352
+ const red = (line: string) => (color ? `\x1b[1;31m${line}\x1b[0m` : line);
353
+ return [
354
+ `┌${"─".repeat(width + 2)}┐`,
355
+ ...lines.map((line) => `│ ${line.padEnd(width)} │`),
356
+ `└${"─".repeat(width + 2)}┘`,
357
+ ]
358
+ .map(red)
359
+ .join("\n");
360
+}
361
+
362
+/**
363
+ * Waits for the server that `t3 connect` just started to prove other devices
364
+ * can reach it, so a broken tunnel fails setup instead of looking green.
365
+ */
366
+const waitForReachability = Effect.fn("cloud.cli.wait_for_reachability")(function* () {
367
+ yield* Console.log("\nChecking that other devices can reach this machine...");
368
+ const deadline =
369
+ (yield* Clock.currentTimeMillis) + Duration.toMillis(CLOUD_CLI_REACHABILITY_WAIT);
370
+ let last: EnvironmentConnectReachability | null = null;
371
+ while (true) {
372
+ last = (yield* checkLiveReachability()) ?? last;
373
+ if (last?.status === "reachable") {
374
+ yield* Console.log(
375
+ `✓ Other devices can reach this machine · ${formatConnectReachable(last)}`,
376
+ );
377
+ return;
378
+ }
379
+ if ((yield* Clock.currentTimeMillis) >= deadline) break;
380
+ yield* Effect.sleep(CLOUD_CLI_REACHABILITY_RETRY);
381
+ }
382
+ yield* Console.error(
383
+ formatAlertBox(
384
+ last === null
385
+ ? "✕ Could not check T3 Connect\n The T3 server on this machine did not answer.\n Fix: run `t3 service status`, then `t3 connect status`."
386
+ : formatReachabilityFailure(last),
387
+ ),
388
+ );
389
+ yield* Effect.sync(() => {
390
+ process.exitCode = 1;
391
+ });
392
+});
393
+
394
type RelayUnlinkResult =
395
| { readonly status: "not-authenticated" }
396
| { readonly status: "revoked" }
@@ -551,7 +639,9 @@ const connectStatusCommand = Command.make("status", {
639
...projectLocationFlags,
640
json: jsonFlag,
641
}).pipe(
554
- Command.withDescription("Show persisted T3 Connect and relay client state."),
642
+ Command.withDescription(
643
+ "Show T3 Connect setup and check that other devices can reach this machine.",
644
+ ),
645
Command.withHandler((flags) =>
646
runCloudCommand(
647
flags,
@@ -567,6 +657,7 @@ const connectStatusCommand = Command.make("status", {
657
publishAgentActivity,
658
revoked,
659
executable,
660
+ linkMode,
661
] = yield* Effect.all(
662
[
663
CliState.readCliDesiredCloudLink,
@@ -576,9 +667,13 @@ const connectStatusCommand = Command.make("status", {
667
secrets.get(PUBLISH_AGENT_ACTIVITY_SECRET),
668
secrets.get(CLOUD_LINK_REVOKED),
669
relayClient.resolve,
670
+ CliState.readCliDesiredLinkMode,
671
],
672
{ concurrency: "unbounded" },
673
);
674
+ // A publish-only link has no tunnel for other devices to reach.
675
+ const reachability =
676
+ desired && linkMode === "managed" ? yield* checkLiveReachability() : null;
677
const status: CloudCliStatus = {
678
desired,
679
authenticated,
@@ -590,6 +685,8 @@ const connectStatusCommand = Command.make("status", {
685
Option.isSome(publishAgentActivity) ? bytesToString(publishAgentActivity.value) : null,
686
),
687
relayClient: executable,
688
+ linkMode,
689
+ reachability,
690
};
691
yield* Console.log(formatCloudStatus(status, { json: flags.json }));
692
}),
@@ -703,7 +800,7 @@ export const reportServiceOnboarding = Effect.fn("cli.connect.report_service_onb
800
}
801
const serveCommand = yield* resolveCliCommand("serve");
802
yield* Console.log(
706
- `\nNext\n Start the server with \`${serveCommand}\` to make this machine reachable.`,
803
+ `\nNext\n Start the server with \`${serveCommand}\` to make this machine reachable.\n It checks that other devices can reach this machine when it starts.`,
804
);
805
},
806
);
@@ -724,9 +821,13 @@ export const connectCommand = Command.make("connect", {
821
}
822
yield* Console.log(`✓ Authorized${connectedAs(linked.identity)}`);
823
727
- yield* reportServiceOnboarding(
728
- yield* CliService.recoverServiceOnboardingOffer(CliService.offerServiceDuringOnboarding),
824
+ const outcome = yield* CliService.recoverServiceOnboardingOffer(
825
+ CliService.offerServiceDuringOnboarding,
826
);
827
+ yield* reportServiceOnboarding(outcome);
828
+ if (outcome !== "skipped") {
829
+ yield* waitForReachability();
830
+ }
831
}),
832
),
833
),
apps/server/src/cloud/CloudLink.lifecycle.test.ts
+19
@@ -43,6 +43,7 @@ import {
43
RELAY_URL_SECRET,
44
} from "./config.ts";
45
import * as CloudLink from "./CloudLink.ts";
46
+import * as ConnectReachability from "./ConnectReachability.ts";
47
import { consumeCloudReplayGuards } from "./CloudLink.ts";
48
import { pendingServiceUpdateExists } from "./updateHandoff.ts";
49
import {
@@ -154,6 +155,13 @@ describe("reconcileDesiredCloudLink", () => {
155
expect(error._tag).toBe("CloudLinkAuthorizationMissingError");
156
}).pipe(
157
Effect.provide(CloudLink.layer),
158
+ Effect.provideService(
159
+ ConnectReachability.ConnectReachability,
160
+ ConnectReachability.ConnectReachability.of({
161
+ check: Effect.die("unused"),
162
+ latest: Effect.succeed(Option.none()),
163
+ }),
164
+ ),
165
Effect.provideService(HttpServer.HttpServer, idleHttpServer),
166
Effect.provideService(
167
ServerConfigModule.ServerConfig,
@@ -177,6 +185,8 @@ describe("reconcileDesiredCloudLink", () => {
185
recoveryRequests: Stream.empty,
186
requestRecovery: () => Effect.void,
187
tunnelConnected: Stream.empty,
188
+ inspectConnector: Effect.succeed(null),
189
+ readinessChanged: Stream.empty,
190
withLinkStateLock: (effect) => effect,
191
} satisfies ManagedEndpointRuntime.CloudManagedEndpointRuntime["Service"]),
192
),
@@ -276,6 +286,13 @@ describe("releaseManagedTunnelOnShutdown", () => {
286
<A, E, R>(effect: Effect.Effect<A, E, R>) =>
287
effect.pipe(
288
Effect.provide(CloudLink.layer),
289
+ Effect.provideService(
290
+ ConnectReachability.ConnectReachability,
291
+ ConnectReachability.ConnectReachability.of({
292
+ check: Effect.die("unused"),
293
+ latest: Effect.succeed(Option.none()),
294
+ }),
295
+ ),
296
Effect.provideService(HttpServer.HttpServer, {
297
...idleHttpServer,
298
address: harness.address ?? idleHttpServer.address,
@@ -308,6 +325,8 @@ describe("releaseManagedTunnelOnShutdown", () => {
325
recoveryRequests: Stream.empty,
326
requestRecovery: () => Effect.void,
327
tunnelConnected: Stream.empty,
328
+ inspectConnector: Effect.succeed(null),
329
+ readinessChanged: Stream.empty,
330
withLinkStateLock: (effect) => effect,
331
}),
332
),
apps/server/src/cloud/CloudLink.test.ts
+4
@@ -16,6 +16,7 @@ import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
16
import * as AgentAwarenessRelay from "../relay/AgentAwarenessRelay.ts";
17
import * as CliTokenManager from "./CliTokenManager.ts";
18
import * as CloudLink from "./CloudLink.ts";
19
+import * as ConnectReachability from "./ConnectReachability.ts";
20
import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
21
import {
22
HOLD_WEBHOOKS_WHILE_OFFLINE_SECRET,
@@ -94,6 +95,9 @@ const withService = <A, E>(
95
}),
96
Layer.mock(AgentAwarenessRelay.AgentAwarenessRelay)({ requestCatchUp: () => Effect.void }),
97
Layer.mock(ManagedEndpointRuntime.CloudManagedEndpointRuntime)({}),
98
+ Layer.mock(ConnectReachability.ConnectReachability)({
99
+ latest: Effect.succeed(Option.none()),
100
+ }),
101
Layer.mock(EnvironmentAuth.EnvironmentAuth)({}),
102
Layer.mock(CliTokenManager.CloudCliTokenManager)({}),
103
Layer.mock(HttpServer.HttpServer)({
apps/server/src/cloud/CloudLink.ts
+6
-1
@@ -96,6 +96,7 @@ import {
96
RELAY_URL_SECRET,
97
} from "./config.ts";
98
import { getOrCreateEnvironmentKeyPairFromSecretStore } from "./environmentKeys.ts";
99
+import * as ConnectReachability from "./ConnectReachability.ts";
100
import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
101
import { relayUrlConfig } from "./publicConfig.ts";
102
import {
@@ -529,6 +530,7 @@ const make = Effect.gen(function* () {
530
const secrets = yield* ServerSecretStore.ServerSecretStore;
531
const environment = yield* ServerEnvironment.ServerEnvironment;
532
const endpointRuntime = yield* ManagedEndpointRuntime.CloudManagedEndpointRuntime;
533
+ const reachability = yield* ConnectReachability.ConnectReachability;
534
const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
535
const cliTokenManager = yield* CliTokenManager.CloudCliTokenManager;
536
const httpClient = yield* HttpClient.HttpClient;
@@ -1314,6 +1316,7 @@ const make = Effect.gen(function* () {
1316
publishAgentActivity,
1317
holdWebhooks,
1318
revoked,
1319
+ latestReachability,
1320
] = yield* Effect.all(
1321
[
1322
secrets.get(CLOUD_LINKED_USER_ID),
@@ -1323,8 +1326,9 @@ const make = Effect.gen(function* () {
1326
secrets.get(PUBLISH_AGENT_ACTIVITY_SECRET),
1327
secrets.get(HOLD_WEBHOOKS_WHILE_OFFLINE_SECRET),
1328
secrets.get(CLOUD_LINK_REVOKED),
1329
+ reachability.latest,
1330
],
1327
- { concurrency: 7 },
1331
+ { concurrency: 8 },
1332
);
1333
return {
1334
linked: Option.isSome(cloudUserId),
@@ -1338,6 +1342,7 @@ const make = Effect.gen(function* () {
1342
: false,
1343
holdWebhooksWhileOffline:
1344
Option.isSome(holdWebhooks) && bytesToString(holdWebhooks.value) === "true",
1345
+ ...(Option.isSome(latestReachability) ? { reachability: latestReachability.value } : {}),
1346
} satisfies EnvironmentCloudLinkStateResult;
1347
});
1348
apps/server/src/cloud/ConnectReachability.test.ts
new
+153
@@ -0,0 +1,153 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - reads the user guide to check its anchors.
2
+import * as NodeFS from "node:fs";
3
+
4
+import { formatConnectReachable, T3_CONNECT_TROUBLESHOOTING_SECTIONS } from "@t3tools/contracts";
5
+import { describe, expect, it } from "@effect/vitest";
6
+
7
+import {
8
+ classifyReachability,
9
+ formatReachabilityFailure,
10
+ type ReachabilityFacts,
11
+} from "./ConnectReachability.ts";
12
+
13
+const checkedAt = "2026-10-19T00:00:00.000Z";
14
+const connected = { readyConnections: 4, hostname: "env.example.test", protocol: "quic" };
15
+const notConnected = { readyConnections: 0, hostname: null, protocol: null };
16
+const facts = (overrides: Partial<ReachabilityFacts>): ReachabilityFacts => ({
17
+ managedTunnelConfigured: true,
18
+ connector: connected,
19
+ endpoint: null,
20
+ edgeReachable: null,
21
+ exitNode: null,
22
+ ...overrides,
23
+});
24
+
25
+describe("classifyReachability", () => {
26
+ it("blames the exit node when the tunnel edge times out through it", () => {
27
+ const result = classifyReachability(
28
+ facts({
29
+ connector: notConnected,
30
+ edgeReachable: false,
31
+ exitNode: { name: "home-pi", online: true },
32
+ }),
33
+ checkedAt,
34
+ );
35
+
36
+ expect(result.status === "unreachable" && formatReachabilityFailure(result)).toBe(
37
+ [
38
+ "✕ T3 Connect is NOT reachable from other devices",
39
+ " Cloudflare's tunnel port (7844) times out from this machine.",
40
+ ' Tailscale exit node "home-pi" is on. Traffic to Cloudflare goes through it.',
41
+ " Fix: tailscale set --exit-node= (or allow outbound 7844 on that network)",
42
+ " More info: https://github.com/pingdotgg/t3code/blob/main/docs/user/t3-connect-troubleshooting.md#port-7844-is-blocked-on-the-host",
43
+ ].join("\n"),
44
+ );
45
+ });
46
+
47
+ it("names a generic blocker when no exit node is on", () => {
48
+ const result = classifyReachability(
49
+ facts({ connector: notConnected, edgeReachable: false }),
50
+ checkedAt,
51
+ );
52
+
53
+ expect(result).toMatchObject({
54
+ cause: "edge_unreachable",
55
+ hint: "A VPN, proxy, or firewall may block it.",
56
+ });
57
+ });
58
+
59
+ it.each([
60
+ [{ kind: "status", status: 502 }, "origin_unreachable"],
61
+ [{ kind: "status", status: 530 }, "no_connector"],
62
+ [{ kind: "status", status: 404 }, "unexpected_response"],
63
+ [{ kind: "dns_failed" }, "dns_failed"],
64
+ [{ kind: "network_error" }, "timeout"],
65
+ ] as const)("maps endpoint result %o to %s", (endpoint, cause) => {
66
+ expect(classifyReachability(facts({ endpoint, edgeReachable: true }), checkedAt)).toMatchObject(
67
+ { status: "unreachable", cause },
68
+ );
69
+ });
70
+
71
+ it("keeps the endpoint cause when the TCP edge test cannot explain it", () => {
72
+ // QUIC (UDP) can connect while TCP 7844 is blocked.
73
+ expect(
74
+ classifyReachability(
75
+ facts({ endpoint: { kind: "status", status: 502 }, edgeReachable: false }),
76
+ checkedAt,
77
+ ),
78
+ ).toMatchObject({ cause: "origin_unreachable" });
79
+ expect(
80
+ classifyReachability(
81
+ facts({
82
+ connector: { readyConnections: null, hostname: "env.example.test", protocol: null },
83
+ endpoint: { kind: "status", status: 502 },
84
+ edgeReachable: false,
85
+ }),
86
+ checkedAt,
87
+ ),
88
+ ).toMatchObject({ cause: "origin_unreachable" });
89
+ // Failed DNS also fails the edge lookups.
90
+ expect(
91
+ classifyReachability(
92
+ facts({
93
+ connector: { readyConnections: null, hostname: "env.example.test", protocol: null },
94
+ endpoint: { kind: "dns_failed" },
95
+ edgeReachable: false,
96
+ }),
97
+ checkedAt,
98
+ ),
99
+ ).toMatchObject({ cause: "dns_failed" });
100
+ });
101
+
102
+ it("waits on a connector that has not connected while the edge answers", () => {
103
+ expect(
104
+ classifyReachability(facts({ connector: notConnected, edgeReachable: true }), checkedAt),
105
+ ).toMatchObject({ cause: "connector_not_ready" });
106
+ });
107
+
108
+ it("reports connections and protocol when the endpoint answers", () => {
109
+ expect(
110
+ classifyReachability(facts({ endpoint: { kind: "status", status: 200 } }), checkedAt),
111
+ ).toEqual({ status: "reachable", checkedAt, readyConnections: 4, protocol: "quic" });
112
+ });
113
+
114
+ it("leaves out the connection count when cloudflared did not report one", () => {
115
+ const result = classifyReachability(
116
+ facts({
117
+ connector: { readyConnections: null, hostname: "env.example.test", protocol: null },
118
+ endpoint: { kind: "status", status: 200 },
119
+ }),
120
+ checkedAt,
121
+ );
122
+ expect(result.status === "reachable" && formatConnectReachable(result)).toBe(
123
+ "Tunnel connected",
124
+ );
125
+ });
126
+
127
+ it("does not probe a tunnel that was never set up", () => {
128
+ expect(
129
+ classifyReachability(facts({ managedTunnelConfigured: false, connector: null }), checkedAt),
130
+ ).toMatchObject({ cause: "not_linked" });
131
+ });
132
+});
133
+
134
+describe("T3 Connect troubleshooting links", () => {
135
+ it("each section names a heading in the user guide", () => {
136
+ const guide = NodeFS.readFileSync(
137
+ new URL("../../../../docs/user/t3-connect-troubleshooting.md", import.meta.url),
138
+ "utf8",
139
+ );
140
+ // GitHub's heading anchors: lowercase, drop punctuation, spaces become hyphens.
141
+ const anchors = new Set(
142
+ [...guide.matchAll(/^#{2,3} (.+)$/gm)].map(([, heading]) =>
143
+ heading!
144
+ .toLowerCase()
145
+ .replace(/[^\p{L}\p{N} _-]/gu, "")
146
+ .replace(/ /g, "-"),
147
+ ),
148
+ );
149
+ for (const section of T3_CONNECT_TROUBLESHOOTING_SECTIONS) {
150
+ expect(anchors, section).toContain(section);
151
+ }
152
+ });
153
+});
apps/server/src/cloud/ConnectReachability.ts
new
+312
@@ -0,0 +1,312 @@
1
+import * as NodeNet from "node:net";
2
+
3
+import {
4
+ connectReachabilityHelpUrl,
5
+ type EnvironmentConnectReachability,
6
+ formatConnectReachable,
7
+} from "@t3tools/contracts";
8
+import { readTailscaleExitNode, type TailscaleExitNode } from "@t3tools/tailscale";
9
+import * as Context from "effect/Context";
10
+import * as DateTime from "effect/DateTime";
11
+import * as Duration from "effect/Duration";
12
+import * as Effect from "effect/Effect";
13
+import * as Layer from "effect/Layer";
14
+import * as Option from "effect/Option";
15
+import * as Ref from "effect/Ref";
16
+import * as Stream from "effect/Stream";
17
+import { HttpClient } from "effect/http";
18
+import { ChildProcessSpawner } from "effect/process";
19
+
20
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
21
+import { CLOUD_ENDPOINT_RUNTIME_CONFIG } from "./config.ts";
22
+import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
23
+
24
+// cloudflared finds the edge through the SRV record `_v2-origintunneld._tcp.argotunnel.com`,
25
+// which names these two hosts on port 7844. QUIC and HTTP/2 both use that port.
26
+const TUNNEL_EDGE_HOSTS = ["region1.v2.argotunnel.com", "region2.v2.argotunnel.com"];
27
+const TUNNEL_EDGE_PORT = 7844;
28
+const EDGE_CONNECT_TIMEOUT = Duration.seconds(5);
29
+const ENDPOINT_REQUEST_TIMEOUT = Duration.seconds(10);
30
+// cloudflared registers several connections within a few seconds; they are one change.
31
+const READINESS_CHANGE_DEBOUNCE = Duration.seconds(3);
32
+// Readiness changes miss failures and recoveries past cloudflared (DNS, origin, edge errors).
33
+const RECHECK_INTERVAL = Duration.minutes(5);
34
+
35
+export type EndpointProbe =
36
+ | { readonly kind: "status"; readonly status: number }
37
+ | { readonly kind: "dns_failed" | "timeout" | "network_error" };
38
+
39
+/** Everything one check learned. `null` means that step did not run. */
40
+export interface ReachabilityFacts {
41
+ readonly managedTunnelConfigured: boolean;
42
+ readonly connector: ManagedEndpointRuntime.ConnectorFacts | null;
43
+ readonly endpoint: EndpointProbe | null;
44
+ readonly edgeReachable: boolean | null;
45
+ readonly exitNode: TailscaleExitNode | null;
46
+}
47
+
48
+type Unreachable = Extract<EnvironmentConnectReachability, { status: "unreachable" }>;
49
+
50
+function exitNodeHint(exitNode: TailscaleExitNode | null): string | null {
51
+ if (!exitNode) return null;
52
+ const name = exitNode.name ? ` "${exitNode.name}"` : "";
53
+ return `Tailscale exit node${name} is on. Traffic to Cloudflare goes through it.`;
54
+}
55
+
56
+/** Turns what one check learned into the answer every surface shows. */
57
+export function classifyReachability(
58
+ facts: ReachabilityFacts,
59
+ checkedAt: string,
60
+): EnvironmentConnectReachability {
61
+ const { connector, endpoint, exitNode } = facts;
62
+ const fail = (
63
+ cause: Unreachable["cause"],
64
+ reason: string,
65
+ fix: string,
66
+ hint: string | null = null,
67
+ ): Unreachable => ({ status: "unreachable", checkedAt, cause, reason, hint, fix });
68
+ const restart = "Restart T3 Code. If it stays, run `t3 connect` again.";
69
+
70
+ if (!facts.managedTunnelConfigured) {
71
+ return fail(
72
+ "not_linked",
73
+ "The server has not set up a T3 Connect tunnel.",
74
+ "Run `t3 connect`, then restart the server (`t3 service restart`) so it applies the link.",
75
+ );
76
+ }
77
+ if (connector === null) {
78
+ return fail(
79
+ "connector_not_running",
80
+ "The tunnel client (cloudflared) is not running.",
81
+ "Restart T3 Code. If it stays down, check the server log for relay client errors.",
82
+ );
83
+ }
84
+ const status = endpoint?.kind === "status" ? endpoint.status : null;
85
+ if (status === 200) {
86
+ return {
87
+ status: "reachable",
88
+ checkedAt,
89
+ readyConnections: connector.readyConnections,
90
+ protocol: connector.protocol,
91
+ };
92
+ }
93
+ // The edge test is TCP only. With QUIC connections up, a 502 from a working tunnel, or
94
+ // DNS already failing, a failed TCP test would hide the real cause.
95
+ if (
96
+ facts.edgeReachable === false &&
97
+ status !== 502 &&
98
+ !(connector.readyConnections && connector.readyConnections > 0) &&
99
+ endpoint?.kind !== "dns_failed"
100
+ ) {
101
+ return fail(
102
+ "edge_unreachable",
103
+ `Cloudflare's tunnel port (${TUNNEL_EDGE_PORT}) times out from this machine.`,
104
+ exitNode
105
+ ? `tailscale set --exit-node= (or allow outbound ${TUNNEL_EDGE_PORT} on that network)`
106
+ : `Allow outbound TCP and UDP port ${TUNNEL_EDGE_PORT}, or turn off the VPN or firewall that blocks it.`,
107
+ exitNodeHint(exitNode) ?? "A VPN, proxy, or firewall may block it.",
108
+ );
109
+ }
110
+ if (status === 502) {
111
+ return fail(
112
+ "origin_unreachable",
113
+ "The tunnel is up, but it cannot reach the T3 server on this machine.",
114
+ "Restart T3 Code so the tunnel uses the port the server listens on.",
115
+ );
116
+ }
117
+ if (endpoint === null || connector.readyConnections === 0) {
118
+ return fail(
119
+ "connector_not_ready",
120
+ "cloudflared has not connected to Cloudflare yet.",
121
+ "Wait a minute. If it stays, check the network and the server log.",
122
+ );
123
+ }
124
+ // Cloudflare answers 530 (error 1033) when the tunnel has no live connector.
125
+ if (status === 530) {
126
+ return fail(
127
+ "no_connector",
128
+ "Cloudflare has no live connection from this machine for the tunnel.",
129
+ restart,
130
+ );
131
+ }
132
+ if (status !== null) {
133
+ return fail(
134
+ "unexpected_response",
135
+ `The T3 Connect address answered with HTTP ${status}.`,
136
+ restart,
137
+ );
138
+ }
139
+ return endpoint.kind === "dns_failed"
140
+ ? fail(
141
+ "dns_failed",
142
+ "The T3 Connect address does not resolve from this machine.",
143
+ "Check the DNS settings on this machine or its VPN.",
144
+ exitNodeHint(exitNode),
145
+ )
146
+ : fail(
147
+ "timeout",
148
+ "The T3 Connect address did not answer from this machine.",
149
+ "Check the network, VPN, or proxy on this machine.",
150
+ exitNodeHint(exitNode),
151
+ );
152
+}
153
+
154
+/** The loud diagnosis the CLI prints and the server logs. */
155
+export function formatReachabilityFailure(result: Unreachable): string {
156
+ return [
157
+ "✕ T3 Connect is NOT reachable from other devices",
158
+ ` ${result.reason}`,
159
+ ...(result.hint ? [` ${result.hint}`] : []),
160
+ ` Fix: ${result.fix}`,
161
+ ` More info: ${connectReachabilityHelpUrl(result.cause)}`,
162
+ ].join("\n");
163
+}
164
+
165
+function hasErrorCode(error: unknown, codes: ReadonlySet<string>): boolean {
166
+ let current = error;
167
+ for (let depth = 0; depth < 6 && typeof current === "object" && current !== null; depth++) {
168
+ if ("code" in current && typeof current.code === "string" && codes.has(current.code)) {
169
+ return true;
170
+ }
171
+ current = "cause" in current ? current.cause : undefined;
172
+ }
173
+ return false;
174
+}
175
+
176
+const DNS_ERROR_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_NONAME"]);
177
+
178
+const canOpenTcp = (host: string, port: number) =>
179
+ Effect.callback<boolean>((resume) => {
180
+ const socket = NodeNet.connect({ host, port });
181
+ const finish = (connected: boolean) => {
182
+ socket.destroy();
183
+ resume(Effect.succeed(connected));
184
+ };
185
+ socket.setTimeout(Duration.toMillis(EDGE_CONNECT_TIMEOUT), () => finish(false));
186
+ socket.once("connect", () => finish(true));
187
+ socket.once("error", () => finish(false));
188
+ return Effect.sync(() => socket.destroy());
189
+ });
190
+
191
+export class ConnectReachability extends Context.Service<
192
+ ConnectReachability,
193
+ {
194
+ /** Runs a check now. The server also runs one when the tunnel's readiness changes. */
195
+ readonly check: Effect.Effect<EnvironmentConnectReachability>;
196
+ readonly latest: Effect.Effect<Option.Option<EnvironmentConnectReachability>>;
197
+ }
198
+>()("t3/cloud/ConnectReachability") {}
199
+
200
+const make = Effect.gen(function* () {
201
+ const runtime = yield* ManagedEndpointRuntime.CloudManagedEndpointRuntime;
202
+ const secrets = yield* ServerSecretStore.ServerSecretStore;
203
+ const httpClient = yield* HttpClient.HttpClient;
204
+ // `order` ranks checks by start, so a slow older one cannot replace a newer result.
205
+ const latestRef = yield* Ref.make(
206
+ Option.none<{ readonly order: number; readonly result: EnvironmentConnectReachability }>(),
207
+ );
208
+ const checkCounter = yield* Ref.make(0);
209
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
210
+ const readExitNode = readTailscaleExitNode.pipe(
211
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
212
+ Effect.orElseSucceed(() => null),
213
+ );
214
+
215
+ const probeEndpoint = (hostname: string) =>
216
+ httpClient.get(`https://${hostname}/.well-known/t3/environment`).pipe(
217
+ Effect.map((response): EndpointProbe => ({ kind: "status", status: response.status })),
218
+ Effect.scoped,
219
+ Effect.timeoutOption(ENDPOINT_REQUEST_TIMEOUT),
220
+ Effect.map(Option.getOrElse((): EndpointProbe => ({ kind: "timeout" }))),
221
+ Effect.catch((error) =>
222
+ Effect.succeed<EndpointProbe>({
223
+ kind: hasErrorCode(error, DNS_ERROR_CODES) ? "dns_failed" : "network_error",
224
+ }),
225
+ ),
226
+ );
227
+
228
+ const gatherFacts = Effect.gen(function* () {
229
+ const managedTunnelConfigured = Option.isSome(
230
+ yield* secrets.get(CLOUD_ENDPOINT_RUNTIME_CONFIG).pipe(Effect.orElseSucceed(Option.none)),
231
+ );
232
+ const connector = managedTunnelConfigured ? yield* runtime.inspectConnector : null;
233
+ const endpoint =
234
+ connector?.hostname && connector.readyConnections !== 0
235
+ ? yield* probeEndpoint(connector.hostname)
236
+ : null;
237
+ const facts: ReachabilityFacts = {
238
+ managedTunnelConfigured,
239
+ connector,
240
+ endpoint,
241
+ edgeReachable: null,
242
+ exitNode: null,
243
+ };
244
+ if (connector === null || (endpoint?.kind === "status" && endpoint.status === 200)) {
245
+ return facts;
246
+ }
247
+ const [edgeResults, exitNode] = yield* Effect.all(
248
+ [
249
+ Effect.forEach(TUNNEL_EDGE_HOSTS, (host) => canOpenTcp(host, TUNNEL_EDGE_PORT), {
250
+ concurrency: "unbounded",
251
+ }),
252
+ readExitNode,
253
+ ],
254
+ { concurrency: 2 },
255
+ );
256
+ return { ...facts, edgeReachable: edgeResults.some(Boolean), exitNode };
257
+ });
258
+
259
+ const check = Effect.gen(function* () {
260
+ const order = yield* Ref.updateAndGet(checkCounter, (count) => count + 1);
261
+ const facts = yield* gatherFacts;
262
+ const result = classifyReachability(facts, DateTime.formatIso(yield* DateTime.now));
263
+ const previous = yield* Ref.modify(latestRef, (current) =>
264
+ Option.isSome(current) && current.value.order > order
265
+ ? [null, current]
266
+ : [current, Option.some({ order, result })],
267
+ );
268
+ if (previous === null) return result;
269
+ const changed = Option.match(previous, {
270
+ onNone: () => true,
271
+ onSome: ({ result: last }) =>
272
+ last.status !== result.status ||
273
+ (last.status === "unreachable" &&
274
+ result.status === "unreachable" &&
275
+ last.cause !== result.cause),
276
+ });
277
+ if (!changed || (result.status === "unreachable" && result.cause === "not_linked")) {
278
+ return result;
279
+ }
280
+ if (result.status === "unreachable") {
281
+ // A connector that has not connected yet is usually still starting; the
282
+ // runtime restarts it, and an unreachable edge is reported as its own cause.
283
+ const log = result.cause === "connector_not_ready" ? Effect.logWarning : Effect.logError;
284
+ yield* log(`\n${formatReachabilityFailure(result)}`).pipe(
285
+ Effect.annotateLogs({ cause: result.cause }),
286
+ );
287
+ } else {
288
+ yield* Effect.logInfo(
289
+ `T3 Connect is reachable from other devices. ${formatConnectReachable(result)}`,
290
+ );
291
+ }
292
+ return result;
293
+ }).pipe(Effect.withSpan("ConnectReachability.check"));
294
+
295
+ yield* runtime.readinessChanged.pipe(
296
+ Stream.debounce(READINESS_CHANGE_DEBOUNCE),
297
+ Stream.runForEach(() => check),
298
+ Effect.forkScoped,
299
+ );
300
+ yield* Effect.sleep(RECHECK_INTERVAL).pipe(
301
+ Effect.andThen(check),
302
+ Effect.forever,
303
+ Effect.forkScoped,
304
+ );
305
+
306
+ return ConnectReachability.of({
307
+ check,
308
+ latest: Ref.get(latestRef).pipe(Effect.map(Option.map(({ result }) => result))),
309
+ });
310
+});
311
+
312
+export const layer = Layer.effect(ConnectReachability, make);
apps/server/src/cloud/ManagedEndpointRuntime.ts
+74
-1
@@ -11,10 +11,11 @@ import * as Option from "effect/Option";
11
import * as Queue from "effect/Queue";
12
import * as Ref from "effect/Ref";
13
import * as Result from "effect/Result";
14
+import * as Schema from "effect/Schema";
15
import * as Semaphore from "effect/Semaphore";
16
import * as Scope from "effect/Scope";
17
import * as Stream from "effect/Stream";
17
-import { HttpClient } from "effect/http";
18
+import { HttpClient, HttpClientResponse } from "effect/http";
19
import * as ChildProcess from "effect/process/ChildProcess";
20
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
21
@@ -42,12 +43,24 @@ export type CloudManagedEndpointRuntimeStatus =
43
readonly providerKind: RelayManagedEndpointRuntimeConfig["providerKind"];
44
};
45
46
+/** What the running cloudflared reports about itself. `null` fields are not known yet. */
47
+export interface ConnectorFacts {
48
+ readonly readyConnections: number | null;
49
+ /** The public tunnel hostname from the remote config cloudflared receives once it connects. */
50
+ readonly hostname: string | null;
51
+ readonly protocol: string | null;
52
+}
53
+
54
export class CloudManagedEndpointRuntime extends Context.Service<
55
CloudManagedEndpointRuntime,
56
{
57
readonly applyConfig: (
58
config: RelayManagedEndpointRuntimeConfig | null,
59
) => Effect.Effect<CloudManagedEndpointRuntimeStatus>;
60
+ /** `null` when no connector is running. */
61
+ readonly inspectConnector: Effect.Effect<ConnectorFacts | null>;
62
+ /** Emits when a connector registers a connection or its readiness changes. */
63
+ readonly readinessChanged: Stream.Stream<void>;
64
readonly recoveryRequests: Stream.Stream<RelayManagedEndpointRuntimeConfig>;
65
readonly requestRecovery: (config: RelayManagedEndpointRuntimeConfig) => Effect.Effect<void>;
66
readonly tunnelConnected: Stream.Stream<void>;
@@ -64,6 +77,7 @@ interface ActiveConnector {
77
readonly startedAtMillis: number;
78
readonly registered: Deferred.Deferred<void>;
79
readonly metricsAddress: Deferred.Deferred<string>;
80
+ readonly protocol: Ref.Ref<string | null>;
81
}
82
83
// Without the backoff below, a relay client that fails instantly (a stale
@@ -86,6 +100,17 @@ const CONNECTOR_READINESS_REQUEST_TIMEOUT = Duration.seconds(5);
100
const CONNECTOR_NOT_READY_CHECKS_BEFORE_RESTART = 6;
101
const CONNECTOR_NOT_READY_CHECKS_MAX = 60;
102
const RELAY_CLIENT_METRICS_LINE = /\bStarting metrics server on (127\.0\.0\.1:\d+)\/metrics\b/u;
103
+const RELAY_CLIENT_PROTOCOL = /\bprotocol=(\w+)/u;
104
+// cloudflared's metrics server: `/ready` answers 200 or 503 with this body, and
105
+// `/config` holds the ingress rules the edge pushed after the first connection.
106
+const ConnectorReadyBody = Schema.Struct({ readyConnections: Schema.Number });
107
+const ConnectorConfigBody = Schema.Struct({
108
+ config: Schema.Struct({
109
+ ingress: Schema.optional(
110
+ Schema.NullOr(Schema.Array(Schema.Struct({ hostname: Schema.optional(Schema.String) }))),
111
+ ),
112
+ }),
113
+});
114
// Registration resets cloudflared's own fallback, even when QUIC stalls again
115
// immediately. Keep that evidence across registrations and connector restarts.
116
const QUIC_STALLS_BEFORE_HTTP2 = 30;
@@ -173,6 +198,7 @@ export const make = Effect.gen(function* () {
198
const desiredConfigRef = yield* Ref.make<RelayManagedEndpointRuntimeConfig | null>(null);
199
const recoveryRequests = yield* Queue.sliding<RelayManagedEndpointRuntimeConfig>(1);
200
const tunnelConnections = yield* Queue.sliding<void>(1);
201
+ const readinessChanges = yield* Queue.sliding<void>(1);
202
const reconcileSemaphore = yield* Semaphore.make(1);
203
const restartDelayRef = yield* Ref.make(0);
204
const linkStateSemaphore = yield* Semaphore.make(1);
@@ -403,6 +429,7 @@ export const make = Effect.gen(function* () {
429
const watchConnectorReadiness = Effect.fnUntraced(function* (connector: ActiveConnector) {
430
const readyUrl = `http://${yield* Deferred.await(connector.metricsAddress)}/ready`;
431
let notReadyChecks = 0;
432
+ let lastReady: boolean | null = null;
433
while (true) {
434
yield* Effect.sleep(CONNECTOR_READINESS_INTERVAL);
435
const status = yield* httpClient.get(readyUrl).pipe(
@@ -413,6 +440,11 @@ export const make = Effect.gen(function* () {
440
Effect.orElseSucceed(() => Option.none<number>()),
441
);
442
if (Option.isNone(status)) continue;
443
+ if (status.value === 200 || status.value === 503) {
444
+ const ready = status.value === 200;
445
+ if (ready !== lastReady) yield* Queue.offer(readinessChanges, undefined);
446
+ lastReady = ready;
447
+ }
448
if (status.value === 200) {
449
notReadyChecks = 0;
450
yield* Ref.set(notReadyChecksBeforeRestartRef, CONNECTOR_NOT_READY_CHECKS_BEFORE_RESTART);
@@ -489,10 +521,14 @@ export const make = Effect.gen(function* () {
521
case "connected":
522
rejectedRegistrations = 0;
523
return Deferred.succeed(connector.registered, undefined).pipe(
524
+ Effect.andThen(
525
+ Ref.set(connector.protocol, RELAY_CLIENT_PROTOCOL.exec(line)?.[1] ?? null),
526
+ ),
527
Effect.andThen(
528
Effect.logInfo("Relay client tunnel connection registered", attributes),
529
),
530
Effect.andThen(Queue.offer(tunnelConnections, undefined)),
531
+ Effect.andThen(Queue.offer(readinessChanges, undefined)),
532
Effect.andThen(
533
RelayClient.isPinnedManagedRelayClient(connector.executable)
534
? Ref.getAndSet(prunedRef, true).pipe(
@@ -666,6 +702,7 @@ export const make = Effect.gen(function* () {
702
startedAtMillis: yield* Clock.currentTimeMillis,
703
registered: yield* Deferred.make<void>(),
704
metricsAddress: yield* Deferred.make<string>(),
705
+ protocol: yield* Ref.make<string | null>(null),
706
} satisfies ActiveConnector;
707
yield* Ref.set(activeRef, connector);
708
yield* Effect.forkIn(observeConnectorOutput(connector), connectorScope);
@@ -712,8 +749,44 @@ export const make = Effect.gen(function* () {
749
),
750
);
751
752
+ const readMetrics = <S extends Schema.Decoder<unknown>>(url: string, schema: S) =>
753
+ httpClient.get(url).pipe(
754
+ Effect.flatMap(HttpClientResponse.schemaBodyJson(schema)),
755
+ Effect.scoped,
756
+ Effect.withTracerEnabled(false),
757
+ Effect.timeoutOption(CONNECTOR_READINESS_REQUEST_TIMEOUT),
758
+ Effect.map(Option.getOrNull),
759
+ Effect.orElseSucceed(() => null),
760
+ );
761
+
762
+ const inspectConnector = Effect.gen(function* () {
763
+ const active = yield* Ref.get(activeRef);
764
+ if (!active || !(yield* active.child.isRunning.pipe(Effect.orElseSucceed(() => false)))) {
765
+ return null;
766
+ }
767
+ const protocol = yield* Ref.get(active.protocol);
768
+ if (!(yield* Deferred.isDone(active.metricsAddress))) {
769
+ return { readyConnections: null, hostname: null, protocol } satisfies ConnectorFacts;
770
+ }
771
+ const metricsUrl = `http://${yield* Deferred.await(active.metricsAddress)}`;
772
+ const [ready, config] = yield* Effect.all(
773
+ [
774
+ readMetrics(`${metricsUrl}/ready`, ConnectorReadyBody),
775
+ readMetrics(`${metricsUrl}/config`, ConnectorConfigBody),
776
+ ],
777
+ { concurrency: 2 },
778
+ );
779
+ return {
780
+ readyConnections: ready?.readyConnections ?? null,
781
+ hostname: config?.config.ingress?.find((rule) => rule.hostname)?.hostname ?? null,
782
+ protocol,
783
+ } satisfies ConnectorFacts;
784
+ });
785
+
786
const runtime = CloudManagedEndpointRuntime.of({
787
applyConfig,
788
+ inspectConnector,
789
+ readinessChanged: Stream.fromQueue(readinessChanges),
790
recoveryRequests: Stream.fromQueue(recoveryRequests),
791
requestRecovery: (config) => Queue.offer(recoveryRequests, config).pipe(Effect.asVoid),
792
tunnelConnected: Stream.fromQueue(tunnelConnections),
apps/server/src/cloud/http.test.ts
+6
@@ -13,6 +13,7 @@ import {
13
} from "@t3tools/contracts/relay";
14
import * as Effect from "effect/Effect";
15
import * as Layer from "effect/Layer";
16
+import * as Option from "effect/Option";
17
import * as Schema from "effect/Schema";
18
import { HttpClient, HttpServer } from "effect/http";
19
import * as Etag from "effect/http/Etag";
@@ -34,6 +35,7 @@ import * as AgentAwarenessRelay from "../relay/AgentAwarenessRelay.ts";
35
import * as CliTokenManager from "./CliTokenManager.ts";
36
import * as CloudLink from "./CloudLink.ts";
37
import * as ConnectHttp from "./http.ts";
38
+import * as ConnectReachability from "./ConnectReachability.ts";
39
import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
40
41
const DESKTOP_BOOTSTRAP_TOKEN = "test-desktop-bootstrap-token";
@@ -75,6 +77,9 @@ const layerLinkProofRoutes = HttpApiBuilder.layer(LinkProofTestApi).pipe(
77
Layer.provide([AuthHttp.layer, ConnectHttp.layer]),
78
Layer.provide(AuthHttp.layerAuthenticatedAuth),
79
Layer.provide(CloudLink.layer),
80
+ Layer.provide(
81
+ Layer.mock(ConnectReachability.ConnectReachability)({ latest: Effect.succeed(Option.none()) }),
82
+ ),
83
Layer.provide(EnvironmentAuth.layer),
84
Layer.provide([
85
SqlitePersistence.layerMemory,
@@ -285,6 +290,7 @@ const answerHealthWith = async (failure: HealthFailure) => {
290
answerHealthRequest: () => Effect.fail(failure),
291
}),
292
),
293
+ Layer.provide(Layer.mock(ConnectReachability.ConnectReachability)({})),
294
Layer.provide(AuthHttp.layerAuthenticatedAuth),
295
Layer.provide(Layer.mock(EnvironmentAuth.EnvironmentAuth)({})),
296
Layer.provideMerge(
apps/server/src/cloud/http.ts
+5
@@ -17,6 +17,7 @@ import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
17
import { requireEnvironmentScope } from "../auth/http.ts";
18
import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
19
import * as CloudLink from "./CloudLink.ts";
20
+import * as ConnectReachability from "./ConnectReachability.ts";
21
import type { RelayRequestError } from "./relayResponse.ts";
22
import { traceRelayRequest } from "./traceRelayRequest.ts";
23
@@ -107,6 +108,7 @@ export const layer = HttpApiBuilder.group(
108
"connect",
109
Effect.fnUntraced(function* (handlers) {
110
const cloudLink = yield* CloudLink.CloudLink;
111
+ const reachability = yield* ConnectReachability.ConnectReachability;
112
return handlers
113
.handle("linkProof", ({ payload }) =>
114
Effect.gen(function* () {
@@ -127,6 +129,9 @@ export const layer = HttpApiBuilder.group(
129
Effect.andThen(toHttpError(cloudLink.linkState())),
130
),
131
)
132
+ .handle("checkReachability", () =>
133
+ requireEnvironmentScope(AuthRelayReadScope).pipe(Effect.andThen(reachability.check)),
134
+ )
135
.handle("unlink", () =>
136
requireEnvironmentScope(AuthRelayWriteScope).pipe(
137
Effect.andThen(toHttpError(cloudLink.unlink())),
apps/server/src/server.ts
+2
-1
@@ -140,6 +140,7 @@ import {
140
import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
141
import * as CloudHttp from "./cloud/http.ts";
142
import * as CloudLink from "./cloud/CloudLink.ts";
143
+import * as ConnectReachability from "./cloud/ConnectReachability.ts";
144
import { pendingServiceUpdateExists } from "./cloud/updateHandoff.ts";
145
import * as RelayTracing from "./cloud/relayTracing.ts";
146
import * as CloudManagedEndpointRuntime from "./cloud/ManagedEndpointRuntime.ts";
@@ -1047,7 +1048,7 @@ const layerMakeServer = Layer.unwrap(
1048
);
1049
1050
return layerServerApplication.pipe(
1050
- Layer.provide(CloudLink.layer),
1051
+ Layer.provide(CloudLink.layer.pipe(Layer.provideMerge(ConnectReachability.layer))),
1052
Layer.provideMerge(layerRuntimeServices),
1053
Layer.provideMerge(
1054
McpSessionRegistry.layer.pipe(
apps/web/src/components/settings/ConnectionDiagnosisDetails.tsx
+10
@@ -166,6 +166,16 @@ export function ConnectionDiagnosisPanel({
166
<li key={step}>{step}</li>
167
))}
168
</ol>
169
+ {diagnosis.moreInfoUrl ? (
170
+ <a
171
+ href={diagnosis.moreInfoUrl}
172
+ target="_blank"
173
+ rel="noreferrer"
174
+ className="text-muted-foreground underline underline-offset-2 hover:text-foreground"
175
+ >
176
+ More info
177
+ </a>
178
+ ) : null}
179
</div>
180
<dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-3 font-mono text-muted-foreground">
181
{diagnosis.facts.map(([label, value]) => (
apps/web/src/components/settings/ConnectionsSettings.tsx
+35
-2
@@ -15,6 +15,7 @@ import {
15
type ReactNode,
16
memo,
17
useEffect,
18
+ useEffectEvent,
19
useId,
20
useRef,
21
useState,
@@ -41,6 +42,8 @@ import {
42
type DesktopServerExposureState,
43
type DesktopWslState,
44
type EnvironmentId,
45
+ connectReachabilityHelpUrl,
46
+ formatConnectReachable,
47
resolveEnvironmentMachineKind,
48
} from "@t3tools/contracts";
49
import {
@@ -1844,6 +1847,32 @@ function ConfiguredCloudLinkRow({ canManageRelay }: { readonly canManageRelay: b
1847
? "Your session does not have permission to manage T3 Connect access."
1848
: null;
1849
const isBusy = isUpdating || isUpdatingPreference;
1850
+ const refreshLinkState = useEffectEvent(primaryCloudLinkState.refresh);
1851
+ // The server rechecks reachability when the tunnel's 30 s readiness poll changes.
1852
+ // Poll while mounted, so a failed read does not stop later ones.
1853
+ useEffect(() => {
1854
+ const interval = window.setInterval(() => refreshLinkState(), 30_000);
1855
+ return () => window.clearInterval(interval);
1856
+ }, []);
1857
+ const reachability = managedTunnelActive ? primaryCloudLinkState.data?.reachability : undefined;
1858
+ const reachabilityStatus =
1859
+ reachability?.status === "reachable" ? (
1860
+ formatConnectReachable(reachability)
1861
+ ) : reachability?.status === "unreachable" ? (
1862
+ <span className="block text-destructive">
1863
+ {[reachability.reason, reachability.hint, `Fix: ${reachability.fix}`]
1864
+ .filter(Boolean)
1865
+ .join(" ")}{" "}
1866
+ <a
1867
+ href={connectReachabilityHelpUrl(reachability.cause)}
1868
+ target="_blank"
1869
+ rel="noreferrer"
1870
+ className="underline underline-offset-2"
1871
+ >
1872
+ More info
1873
+ </a>
1874
+ </span>
1875
+ ) : null;
1876
1877
const updateManagedTunnel = async (enabled: boolean) => {
1878
if (
@@ -1919,12 +1948,16 @@ function ConfiguredCloudLinkRow({ canManageRelay }: { readonly canManageRelay: b
1948
linkRevoked
1949
? "This environment was removed from T3 Connect. Turn it on to link it again."
1950
: managedTunnelActive
1922
- ? "This environment is available to your other devices through T3 Connect."
1951
+ ? reachability?.status === "unreachable"
1952
+ ? "T3 Connect is on, but other devices cannot reach this environment."
1953
+ : reachability?.status === "reachable"
1954
+ ? "This environment is available to your other devices through T3 Connect."
1955
+ : "T3 Connect is on. Reachability has not been checked yet."
1956
: managedTunnelOutOfSync
1957
? "T3 Connect is out of sync. This environment is linked only to publish agent activity, so other devices cannot connect. Turn T3 Connect on to repair it."
1958
: "Make this environment available to your other devices through T3 Connect."
1959
}
1927
- status={operationError ?? primaryCloudLinkState.error}
1960
+ status={operationError ?? primaryCloudLinkState.error ?? reachabilityStatus}
1961
control={
1962
<CloudLinkSwitch
1963
checked={managedTunnelActive}
docs/README.md
+1
@@ -19,6 +19,7 @@
19
- [Usage and limits](./user/usage.md)
20
- [Product usage data](./user/telemetry.md)
21
- [Remote access](./user/remote-access.md)
22
+- [T3 Connect troubleshooting](./user/t3-connect-troubleshooting.md)
23
- [Outside agents (MCP)](./user/outside-agents.md)
24
- [Running in the background](./user/background-service.md)
25
- [Updating T3 Code](./user/updating.md)
docs/user/background-service.md
+1
-1
@@ -118,7 +118,7 @@ Downloads, it may need Full Disk Access for the `t3` executable listed in
118
`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.
119
120
For failures after signing in to T3 Connect, see
121
-[connection troubleshooting](./remote-access.md#t3-connect-troubleshooting).
121
+[connection troubleshooting](./t3-connect-troubleshooting.md).
122
123
## Reclaim database space
124
docs/user/remote-access.md
+3
-20
@@ -331,26 +331,9 @@ screenshots, logs, or bug reports.
331
332
## T3 Connect troubleshooting
333
334
-Run `t3 connect status` on the host to inspect saved authorization and link
335
-configuration. It is not a live reachability check. If the environment appears
336
-offline, run `t3 service status` and read the displayed log. If it disappears
337
-when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting).
338
-
339
-| Error | Recovery |
340
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
341
-| `environment_link_limit_exceeded` or managed tunnel limit | Deregister an unused environment, then restart T3 Code on the host. |
342
-| `auth_invalid` or `invalid_bearer` | Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. |
343
-| Expired or invalid link proof | Check the host's date and time, update T3 Code, then restart it. |
344
-| HTTP 403 without a recognized error | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. |
345
-| HTTP 408, 429, or 5xx | Check network and relay availability. Startup retries temporary failures for up to ten minutes. |
346
-
347
-After fixing a permanent rejection, restart the host's server. On Linux, use
348
-`systemctl --user restart t3code.service` for the background service. For a
349
-foreground server, stop it and run `t3 serve` again with your usual options.
350
-Include the diagnostic message and trace ID when reporting a persistent failure.
351
-
352
-For a connection that still fails after linking, check the date and time on both
353
-devices. For server version warnings, follow [Updating T3 Code](./updating.md).
334
+When a T3 Connect connection fails, see
335
+[T3 Connect troubleshooting](./t3-connect-troubleshooting.md). It explains each
336
+error, where the problem is, and how to fix it.
337
338
## Using the Desktop App as a Remote Only
339
docs/user/t3-connect-troubleshooting.md
new
+151
@@ -0,0 +1,151 @@
1
+# T3 Connect troubleshooting
2
+
3
+A T3 Connect connection goes through four parts, in this order:
4
+
5
+1. **This device** reaches T3 Connect over the internet.
6
+2. **T3 Connect** checks your sign-in and the host's link.
7
+3. **The host's tunnel** (cloudflared on the host) carries the request to the host.
8
+4. **T3 Code on the host** answers.
9
+
10
+When a connection fails, open **Settings > Connections**, find the environment,
11
+and select **Details**. The first part marked as failed is the cause. Find its
12
+section below.
13
+
14
+To see the host's side, run `t3 connect status` on the host, or open
15
+**Settings > Connections** on the host. Both check the host's T3 Connect
16
+address from the host, and say why it fails. `t3 connect` runs the same check
17
+when it finishes setup. This check cannot test another device's network. For a
18
+problem on one device, use **Details** on that device.
19
+
20
+## The host's tunnel is offline
21
+
22
+T3 Connect could not reach the host's tunnel. This means one of these:
23
+
24
+- The host is asleep, turned off, or offline.
25
+- T3 Code is not running on the host.
26
+- The host's network blocks the tunnel. See
27
+ [Port 7844 is blocked on the host](#port-7844-is-blocked-on-the-host).
28
+
29
+Fix:
30
+
31
+1. Make sure the host is awake and T3 Code runs on it.
32
+2. On the host, run `t3 connect status`. It names the problem on the host's side.
33
+3. If the host was offline for a long time, T3 Connect removes its tunnel. Start
34
+ T3 Code on the host and update it to the latest version. It gets a new tunnel.
35
+
36
+## Port 7844 is blocked on the host
37
+
38
+The tunnel on the host connects out to Cloudflare on port 7844, with TCP and
39
+UDP. Both tunnel protocols (QUIC and HTTP/2) use this port. When the host's
40
+network blocks it, the tunnel cannot start, but normal web traffic still works.
41
+The host looks online, so this problem is easy to miss.
42
+
43
+Common causes:
44
+
45
+- **A Tailscale exit node on the host.** All of the host's internet traffic goes
46
+ through the exit node, and that network blocks port 7844. Turn off the exit
47
+ node on the host with `tailscale set --exit-node=`, or allow outbound port
48
+ 7844 on the exit node's network.
49
+- **A VPN on the host.** Work VPNs often block unknown ports. Ask for port 7844
50
+ to be allowed, or use a direct route instead (see below).
51
+- **A firewall or strict network.** Allow outbound TCP and UDP port 7844.
52
+
53
+If you cannot unblock the port, you can connect without T3 Connect. When the
54
+host and this device are on the same Tailscale network, add the host's
55
+Tailscale address as a direct route. See
56
+[Reach one machine several ways](./remote-access.md#reach-one-machine-several-ways).
57
+
58
+## The tunnel works, but T3 Code does not answer
59
+
60
+The host's tunnel is up, but it cannot reach T3 Code on the host. Common causes:
61
+
62
+- T3 Code on the host stopped, crashed, or is still starting.
63
+- T3 Code restarted on a different port, for example after an update, and the
64
+ tunnel still points at the old port.
65
+- The server binds only one network address with `T3CODE_HOST`. The tunnel
66
+ sends requests to `127.0.0.1`, so the server must also listen there.
67
+
68
+Fix: restart T3 Code on the host. For the background service, run
69
+`t3 service restart`. Then run `t3 connect status` on the host.
70
+
71
+## The T3 Connect address does not resolve or answer
72
+
73
+The host's T3 Connect address did not resolve, refused the connection, failed a
74
+secure (TLS) connection, or did not answer in time.
75
+
76
+Fix:
77
+
78
+1. Make sure the host is awake and online.
79
+2. On the host, run `t3 connect status`.
80
+3. If the check fails only on the host, check the host's DNS, VPN, or proxy.
81
+
82
+## This device can't reach T3 Connect
83
+
84
+The problem is on this device's network, not on the host. This device could
85
+not reach T3 Connect, or it reached T3 Connect but not the host's tunnel
86
+address.
87
+
88
+Fix:
89
+
90
+1. Check this device's internet connection. On a captive or dead Wi-Fi network,
91
+ the device can look online but cannot reach anything.
92
+2. A VPN, firewall, ad blocker, or DNS filter on this device can block T3
93
+ Connect. Turn it off for a moment to test.
94
+3. On iPhone, Connectivity Assist in the Wi-Fi settings can break T3 Connect.
95
+ Turn it off to test.
96
+4. Try another network, or add a direct route to the host, such as its
97
+ Tailscale address. See
98
+ [Reach one machine several ways](./remote-access.md#reach-one-machine-several-ways).
99
+
100
+## Sign-in, account, or link problems
101
+
102
+T3 Connect does not have an active link between your account and the host.
103
+
104
+- **The host is linked to a different account.** Sign in to the same T3 Connect
105
+ account on this device and on the host. On the host, run `t3 connect logout`,
106
+ then `t3 connect`.
107
+- **T3 Connect is off on the host, or the host only publishes agent activity.**
108
+ On the host, open **Settings > Connections** and turn **T3 Connect** on, or
109
+ run `t3 connect`.
110
+- **The host was linked, but the server did not apply the link yet.** Run
111
+ `t3 service restart` on the host, or restart `t3 serve`.
112
+- **This device's sign-in expired, or the host no longer accepts this
113
+ device.** Sign out of T3 Connect and sign in again.
114
+- **Your account reached its tunnel limit.** Remove an environment you do not
115
+ use from your T3 account's T3 Connect page, then restart T3 Code on the host.
116
+
117
+## The clock is off
118
+
119
+T3 Connect signs requests with short-lived proofs. When the clock on this
120
+device or the host is a few minutes wrong, T3 Connect rejects them. Turn on
121
+automatic date and time on both devices, then retry.
122
+
123
+## The host runs an older T3 Code
124
+
125
+This app needs a newer T3 Code on the host. Update T3 Code on the host. See
126
+[Updating T3 Code](./updating.md).
127
+
128
+## T3 Connect returned an error
129
+
130
+| Error | Fix |
131
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
132
+| `environment_link_limit_exceeded` or managed tunnel limit | Remove an unused environment, then restart T3 Code on the host. |
133
+| `auth_invalid` or `invalid_bearer` | Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. |
134
+| Expired or invalid link proof | Check the host's date and time, update T3 Code, then restart it. |
135
+| HTTP 403 without a recognized error | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. |
136
+| HTTP 408, 429, or 5xx | Wait a few minutes. T3 Code retries temporary failures on its own. |
137
+
138
+After you fix a permanent rejection, restart the host's server with
139
+`t3 service restart`. For a foreground server, stop it and run `t3 serve` again.
140
+
141
+If T3 Code on the host disappears when SSH closes, see
142
+[background-service troubleshooting](./background-service.md#troubleshooting).
143
+
144
+## Report a problem
145
+
146
+If none of this helps, open an issue on
147
+[GitHub](https://github.com/pingdotgg/t3code/issues). Include:
148
+
149
+- The text from **Copy diagnostics** in the environment's **Details**.
150
+- The output of `t3 connect status` on the host.
151
+- The trace ID, if one is shown.
packages/client-runtime/src/connection/diagnosis.test.ts
+19
@@ -15,6 +15,7 @@ import {
15
import {
16
AVAILABLE_CONNECTION_STATE,
17
type ConnectionAttemptError,
18
+ ConnectionBlockedError,
19
type SupervisorConnectionState,
20
} from "./model.ts";
21
import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
@@ -69,6 +70,24 @@ describe("presentConnectionDiagnosis", () => {
70
expect(diagnosis?.steps.join(" ")).toContain("Tailscale exit node on Mac mini");
71
expect(diagnosis?.facts).toContainEqual(["HTTP status", "530"]);
72
expect(diagnosis?.facts).toContainEqual(["Trace ID", "trace-1"]);
73
+ expect(diagnosis?.moreInfoUrl).toMatch(
74
+ /t3-connect-troubleshooting\.md#the-hosts-tunnel-is-offline$/,
75
+ );
76
+ });
77
+
78
+ it("links a host that rejects this device to the sign-in section", () => {
79
+ const failure = new ConnectionBlockedError({
80
+ reason: "authentication",
81
+ detail: "rejected",
82
+ hop: "server",
83
+ via: "relay",
84
+ });
85
+ expect(diagnose(backoff(failure))?.moreInfoUrl).toMatch(/#sign-in-account-or-link-problems$/);
86
+ });
87
+
88
+ it("links the guide only for T3 Connect routes", () => {
89
+ const failure = credentialMissingError("direct-1");
90
+ expect(diagnose(backoff(failure), "direct")?.moreInfoUrl).toBeNull();
91
});
92
93
it("tells a working tunnel apart from T3 Code not answering", () => {
packages/client-runtime/src/connection/diagnosis.ts
+60
@@ -1,3 +1,7 @@
1
+import {
2
+ t3ConnectTroubleshootingUrl,
3
+ type T3ConnectTroubleshootingSection,
4
+} from "@t3tools/contracts";
5
import type { RelayEnvironmentStatusResponse } from "@t3tools/contracts/relay";
6
import * as DateTime from "effect/DateTime";
7
@@ -22,6 +26,8 @@ export interface ConnectionDiagnosis {
26
readonly hops: ReadonlyArray<ConnectionDiagnosisHop>;
27
readonly steps: ReadonlyArray<string>;
28
readonly facts: ReadonlyArray<readonly [label: string, value: string]>;
29
+ /** The troubleshooting guide section for this failure. Null for direct routes. */
30
+ readonly moreInfoUrl: string | null;
31
}
32
33
export interface ConnectionDiagnosisInput {
@@ -203,6 +209,58 @@ function steps(host: string, located: Located, failure: ConnectionAttemptError |
209
}
210
}
211
212
+function helpSection(
213
+ located: Located,
214
+ failure: ConnectionAttemptError | null,
215
+): T3ConnectTroubleshootingSection {
216
+ switch (located.cause) {
217
+ case "offline":
218
+ return "this-device-cant-reach-t3-connect";
219
+ case "outdated":
220
+ return "the-host-runs-an-older-t3-code";
221
+ case "clock_skew":
222
+ return "the-clock-is-off";
223
+ case "not_linked":
224
+ case "tunnel_not_enabled":
225
+ return "sign-in-account-or-link-problems";
226
+ case "relay_error":
227
+ return "t3-connect-returned-an-error";
228
+ case "released":
229
+ case "tunnel_down":
230
+ case "tunnel_pending":
231
+ return "the-hosts-tunnel-is-offline";
232
+ case "origin_unreachable":
233
+ case "invalid_response":
234
+ return "the-tunnel-works-but-t3-code-does-not-answer";
235
+ case "dns":
236
+ case "tls":
237
+ case "refused":
238
+ case "timeout":
239
+ case "unknown":
240
+ return "the-t3-connect-address-does-not-resolve-or-answer";
241
+ case null:
242
+ break;
243
+ }
244
+ const onThisDevice =
245
+ failure?.reason === "network" ||
246
+ failure?.reason === "transport" ||
247
+ failure?.reason === "timeout";
248
+ switch (located.hop) {
249
+ case "device":
250
+ return "this-device-cant-reach-t3-connect";
251
+ case "relay":
252
+ return failure?.reason === "authentication"
253
+ ? "sign-in-account-or-link-problems"
254
+ : "this-device-cant-reach-t3-connect";
255
+ case "tunnel":
256
+ return onThisDevice ? "this-device-cant-reach-t3-connect" : "the-hosts-tunnel-is-offline";
257
+ case "server":
258
+ return failure?.reason === "authentication" || failure?.reason === "permission"
259
+ ? "sign-in-account-or-link-problems"
260
+ : "the-tunnel-works-but-t3-code-does-not-answer";
261
+ }
262
+}
263
+
264
const HOP_ORDER = {
265
relay: ["device", "relay", "tunnel", "server"],
266
direct: ["device", "server"],
@@ -271,6 +329,7 @@ export function presentConnectionDiagnosis(
329
hops,
330
steps: steps(host, located, failure),
331
facts,
332
+ moreInfoUrl: relayPath ? t3ConnectTroubleshootingUrl(helpSection(located, failure)) : null,
333
};
334
}
335
@@ -284,5 +343,6 @@ export function connectionDiagnosisText(hostLabel: string, diagnosis: Connection
343
...diagnosis.hops.map((hop) => `${hop.label}: ${HOP_MARK[hop.result]}`),
344
"",
345
...diagnosis.facts.map(([label, value]) => `${label}: ${value}`),
346
+ ...(diagnosis.moreInfoUrl ? ["", `More info: ${diagnosis.moreInfoUrl}`] : []),
347
].join("\n");
348
}
packages/contracts/src/environmentHttp.ts
+92
@@ -408,6 +408,89 @@ export const EnvironmentCloudRelayConfigResult = Schema.Struct({
408
});
409
export type EnvironmentCloudRelayConfigResult = typeof EnvironmentCloudRelayConfigResult.Type;
410
411
+export const EnvironmentConnectReachabilityCause = Schema.Literals([
412
+ "not_linked",
413
+ "connector_not_running",
414
+ "connector_not_ready",
415
+ "edge_unreachable",
416
+ "no_connector",
417
+ "origin_unreachable",
418
+ "dns_failed",
419
+ "timeout",
420
+ "unexpected_response",
421
+]);
422
+export type EnvironmentConnectReachabilityCause = typeof EnvironmentConnectReachabilityCause.Type;
423
+
424
+/** Whether other devices can reach this environment through its T3 Connect tunnel. */
425
+export const EnvironmentConnectReachability = Schema.Union([
426
+ Schema.Struct({
427
+ status: Schema.Literal("reachable"),
428
+ checkedAt: Schema.String,
429
+ /** Null when cloudflared did not report a count. */
430
+ readyConnections: Schema.NullOr(Schema.Int),
431
+ protocol: Schema.NullOr(Schema.String),
432
+ }),
433
+ Schema.Struct({
434
+ status: Schema.Literal("unreachable"),
435
+ checkedAt: Schema.String,
436
+ cause: EnvironmentConnectReachabilityCause,
437
+ reason: Schema.String,
438
+ hint: Schema.NullOr(Schema.String),
439
+ fix: Schema.String,
440
+ }),
441
+]);
442
+export type EnvironmentConnectReachability = typeof EnvironmentConnectReachability.Type;
443
+
444
+/** "Tunnel connected · 4 connections · QUIC" for a healthy check. */
445
+export function formatConnectReachable(
446
+ result: Extract<EnvironmentConnectReachability, { status: "reachable" }>,
447
+): string {
448
+ const count = result.readyConnections;
449
+ return [
450
+ "Tunnel connected",
451
+ ...(count === null ? [] : [`${count} connection${count === 1 ? "" : "s"}`]),
452
+ ...(result.protocol ? [result.protocol.toUpperCase()] : []),
453
+ ].join(" · ");
454
+}
455
+
456
+/**
457
+ * Sections of docs/user/t3-connect-troubleshooting.md. Each is the GitHub anchor of a
458
+ * heading there; the test fails when a heading is renamed without updating this list.
459
+ */
460
+export const T3_CONNECT_TROUBLESHOOTING_SECTIONS = [
461
+ "the-hosts-tunnel-is-offline",
462
+ "port-7844-is-blocked-on-the-host",
463
+ "the-tunnel-works-but-t3-code-does-not-answer",
464
+ "the-t3-connect-address-does-not-resolve-or-answer",
465
+ "this-device-cant-reach-t3-connect",
466
+ "sign-in-account-or-link-problems",
467
+ "the-clock-is-off",
468
+ "the-host-runs-an-older-t3-code",
469
+ "t3-connect-returned-an-error",
470
+] as const;
471
+export type T3ConnectTroubleshootingSection = (typeof T3_CONNECT_TROUBLESHOOTING_SECTIONS)[number];
472
+
473
+/** Clients, the CLI, and server logs link here as "More info". */
474
+export function t3ConnectTroubleshootingUrl(section: T3ConnectTroubleshootingSection): string {
475
+ return `https://github.com/pingdotgg/t3code/blob/main/docs/user/t3-connect-troubleshooting.md#${section}`;
476
+}
477
+
478
+const REACHABILITY_SECTION = {
479
+ not_linked: "sign-in-account-or-link-problems",
480
+ connector_not_running: "the-hosts-tunnel-is-offline",
481
+ connector_not_ready: "the-hosts-tunnel-is-offline",
482
+ no_connector: "the-hosts-tunnel-is-offline",
483
+ edge_unreachable: "port-7844-is-blocked-on-the-host",
484
+ origin_unreachable: "the-tunnel-works-but-t3-code-does-not-answer",
485
+ unexpected_response: "the-tunnel-works-but-t3-code-does-not-answer",
486
+ dns_failed: "the-t3-connect-address-does-not-resolve-or-answer",
487
+ timeout: "the-t3-connect-address-does-not-resolve-or-answer",
488
+} satisfies Record<EnvironmentConnectReachabilityCause, T3ConnectTroubleshootingSection>;
489
+
490
+export function connectReachabilityHelpUrl(cause: EnvironmentConnectReachabilityCause): string {
491
+ return t3ConnectTroubleshootingUrl(REACHABILITY_SECTION[cause]);
492
+}
493
+
494
export const EnvironmentCloudLinkStateResult = Schema.Struct({
495
linked: Schema.Boolean,
496
cloudUserId: Schema.NullOr(Schema.String),
@@ -417,6 +500,8 @@ export const EnvironmentCloudLinkStateResult = Schema.Struct({
500
publishAgentActivity: Schema.Boolean,
501
holdWebhooksWhileOffline: Schema.optional(Schema.Boolean),
502
linkRevoked: Schema.optional(Schema.Boolean),
503
+ /** The latest check the server ran on its own, absent until one finishes. */
504
+ reachability: Schema.optional(EnvironmentConnectReachability),
505
});
506
export type EnvironmentCloudLinkStateResult = typeof EnvironmentCloudLinkStateResult.Type;
507
@@ -689,6 +774,13 @@ class EnvironmentConnectHttpApi extends HttpApiGroup.make("connect")
774
error: EnvironmentHttpCloudErrors,
775
}).middleware(EnvironmentAuthenticatedAuth),
776
)
777
+ .add(
778
+ HttpApiEndpoint.post("checkReachability", "/api/connect/reachability", {
779
+ headers: OptionalBearerHeaders,
780
+ success: EnvironmentConnectReachability,
781
+ error: EnvironmentHttpCloudErrors,
782
+ }).middleware(EnvironmentAuthenticatedAuth),
783
+ )
784
.add(
785
HttpApiEndpoint.post("unlink", "/api/connect/unlink", {
786
headers: OptionalBearerHeaders,
packages/tailscale/src/tailscale.test.ts
+25
@@ -15,6 +15,7 @@ import {
15
disableTailscaleServe,
16
ensureTailscaleServe,
17
isTailscaleIpv4Address,
18
+ parseTailscaleExitNode,
19
parseTailscaleMagicDnsName,
20
parseTailscaleSshEnabled,
21
parseTailscaleStatus,
@@ -147,6 +148,30 @@ describe("tailscale", () => {
148
}),
149
);
150
151
+ it.effect("names the exit node in use", () =>
152
+ Effect.gen(function* () {
153
+ const inUse = yield* parseTailscaleExitNode(
154
+ JSON.stringify({
155
+ ExitNodeStatus: { ID: "nX", Online: true, TailscaleIPs: ["100.101.102.103/32"] },
156
+ Peer: {
157
+ "nodekey:a": { HostName: "laptop", DNSName: "laptop.tail.ts.net.", ExitNode: false },
158
+ "nodekey:b": {
159
+ HostName: "raspberrypi",
160
+ DNSName: "home-pi.tail.ts.net.",
161
+ ExitNode: true,
162
+ },
163
+ },
164
+ }),
165
+ );
166
+ assert.deepEqual(inUse, { name: "home-pi", online: true });
167
+
168
+ const unnamed = yield* parseTailscaleExitNode(`{"ExitNodeStatus":{"Online":false}}`);
169
+ assert.deepEqual(unnamed, { name: null, online: false });
170
+
171
+ assert.equal(yield* parseTailscaleExitNode(tailscaleStatusJson), null);
172
+ }),
173
+ );
174
+
175
it.effect("reads the HTTPS serve capability from the status capability map", () =>
176
Effect.gen(function* () {
177
const enabled = yield* parseTailscaleStatus(
packages/tailscale/src/tailscale.ts
+51
@@ -286,6 +286,57 @@ export const readTailscaleStatus = readTailscaleOutput("status", ["status", "--j
286
Effect.flatMap(parseTailscaleStatus),
287
);
288
289
+const TailscaleExitNodeJson = Schema.Struct({
290
+ ExitNodeStatus: Schema.optional(Schema.Struct({ Online: Schema.optional(Schema.Unknown) })),
291
+ Peer: Schema.optional(
292
+ Schema.Record(
293
+ Schema.String,
294
+ Schema.Struct({
295
+ ExitNode: Schema.optional(Schema.Unknown),
296
+ HostName: Schema.optional(Schema.Unknown),
297
+ DNSName: Schema.optional(Schema.Unknown),
298
+ }),
299
+ ),
300
+ ),
301
+});
302
+
303
+const decodeTailscaleExitNodeJson = Schema.decodeEffect(
304
+ Schema.fromJsonString(TailscaleExitNodeJson),
305
+);
306
+
307
+export interface TailscaleExitNode {
308
+ readonly name: string | null;
309
+ readonly online: boolean;
310
+}
311
+
312
+/**
313
+ * `ExitNodeStatus` is present only while an exit node is in use, but it has no
314
+ * name. The name comes from the peer marked `ExitNode: true`.
315
+ */
316
+export const parseTailscaleExitNode = (
317
+ rawStatusJson: string,
318
+): Effect.Effect<TailscaleExitNode | null, TailscaleStatusParseError> =>
319
+ decodeTailscaleExitNodeJson(rawStatusJson).pipe(
320
+ Effect.mapError((cause) => new TailscaleStatusParseError({ cause })),
321
+ Effect.map((parsed) => {
322
+ if (parsed.ExitNodeStatus === undefined) return null;
323
+ const peer = Object.values(parsed.Peer ?? {}).find(
324
+ (candidate) => candidate.ExitNode === true,
325
+ );
326
+ // The DNS label is the tailnet machine name; HostName is the OS name and ignores renames.
327
+ const dnsLabel = typeof peer?.DNSName === "string" ? (peer.DNSName.split(".")[0] ?? "") : "";
328
+ const hostName = typeof peer?.HostName === "string" ? peer.HostName.trim() : "";
329
+ return {
330
+ name: dnsLabel || hostName || null,
331
+ online: parsed.ExitNodeStatus.Online === true,
332
+ };
333
+ }),
334
+ );
335
+
336
+export const readTailscaleExitNode = readTailscaleOutput("status", ["status", "--json"]).pipe(
337
+ Effect.flatMap(parseTailscaleExitNode),
338
+);
339
+
340
const TailscalePrefsJson = Schema.Struct({
341
RunSSH: Schema.optional(Schema.Unknown),
342
WantRunning: Schema.optional(Schema.Unknown),