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

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

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

Synced Nov 22, 22:00 UTC

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),