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 21, 04:45 UTC
| 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 | |
| 8 | import type { |
| 9 | ConnectionAttemptError, |
| 10 | ConnectionFailureCause, |
| 11 | ConnectionHop, |
| 12 | SupervisorConnectionState, |
| 13 | } from "./model.ts"; |
| 14 | import { mFallback, msg } from "gt-i18n"; |
| 15 | import type { MFunctionType } from "gt-i18n/types"; |
| 16 | |
| 17 | export type ConnectionHopResult = "ok" | "failed" | "unchecked"; |
| 18 | |
| 19 | export interface ConnectionDiagnosisHop { |
| 20 | readonly hop: ConnectionHop; |
| 21 | readonly label: string; |
| 22 | readonly result: ConnectionHopResult; |
| 23 | } |
| 24 | |
| 25 | export interface ConnectionDiagnosis { |
| 26 | /** Names the part that failed, e.g. "Mac mini's tunnel is offline". */ |
| 27 | readonly headline: string; |
| 28 | readonly hops: ReadonlyArray<ConnectionDiagnosisHop>; |
| 29 | readonly steps: ReadonlyArray<string>; |
| 30 | readonly facts: ReadonlyArray<readonly [label: string, value: string]>; |
| 31 | /** The troubleshooting guide section for this failure. Null for direct routes, except a pending T3 Connect sign-in. */ |
| 32 | readonly moreInfoUrl: string | null; |
| 33 | } |
| 34 | |
| 35 | export interface ConnectionDiagnosisInput { |
| 36 | readonly hostLabel: string; |
| 37 | readonly state: SupervisorConnectionState; |
| 38 | /** The environment's usual route, used when the failure does not name one. */ |
| 39 | readonly via: "relay" | "direct"; |
| 40 | /** The relay's last health check, which can name a cause before any connect attempt. */ |
| 41 | readonly relayStatus?: Pick< |
| 42 | RelayEnvironmentStatusResponse, |
| 43 | "status" | "endpointFailure" | "endpointStatus" | "offlineReason" |
| 44 | > | null; |
| 45 | readonly clientVersion?: string | undefined; |
| 46 | readonly serverVersion?: string | null | undefined; |
| 47 | } |
| 48 | |
| 49 | interface Located { |
| 50 | readonly hop: ConnectionHop; |
| 51 | readonly cause: |
| 52 | | ConnectionFailureCause |
| 53 | | "offline" |
| 54 | | "outdated" |
| 55 | | "released" |
| 56 | | "session_pending" |
| 57 | | null; |
| 58 | /** The failure named no hop, so the hops before this one were never probed. */ |
| 59 | readonly guessed?: true; |
| 60 | } |
| 61 | |
| 62 | const NOT_ANSWERING: ReadonlySet<ConnectionFailureCause> = new Set([ |
| 63 | "origin_unreachable", |
| 64 | "invalid_response", |
| 65 | ]); |
| 66 | |
| 67 | function locate(input: ConnectionDiagnosisInput): Located | null { |
| 68 | const failure = input.state.lastFailure; |
| 69 | if (input.state.network === "offline" || input.state.phase === "offline") { |
| 70 | return { hop: "device", cause: "offline" }; |
| 71 | } |
| 72 | if (failure?._tag === "ConnectionBlockedError" && failure.serverUpdateRequired) { |
| 73 | return { hop: "server", cause: "outdated" }; |
| 74 | } |
| 75 | if (failure?.reason === "session-pending") { |
| 76 | return { hop: "device", cause: "session_pending" }; |
| 77 | } |
| 78 | if (failure?.hop !== undefined) { |
| 79 | return { hop: failure.hop, cause: failure.failureCause ?? null }; |
| 80 | } |
| 81 | if (failure !== null) { |
| 82 | const unreachable = |
| 83 | failure.reason === "network" || |
| 84 | failure.reason === "timeout" || |
| 85 | failure.reason === "transport"; |
| 86 | const via = failure.via ?? input.via; |
| 87 | return { |
| 88 | hop: unreachable && via === "relay" ? "tunnel" : "server", |
| 89 | cause: null, |
| 90 | guessed: true, |
| 91 | }; |
| 92 | } |
| 93 | const status = input.relayStatus; |
| 94 | if (status?.status !== "offline") return null; |
| 95 | if (status.offlineReason === "tunnel_released") return { hop: "tunnel", cause: "released" }; |
| 96 | const cause = status.endpointFailure ?? null; |
| 97 | return { hop: cause !== null && NOT_ANSWERING.has(cause) ? "server" : "tunnel", cause }; |
| 98 | } |
| 99 | |
| 100 | function headline( |
| 101 | host: string, |
| 102 | located: Located, |
| 103 | failure: ConnectionAttemptError | null, |
| 104 | resolve: MFunctionType, |
| 105 | ): string { |
| 106 | switch (located.cause) { |
| 107 | case "offline": |
| 108 | return resolve(msg("This device is offline")); |
| 109 | case "session_pending": |
| 110 | return resolve(msg("This device is still loading its T3 Connect sign-in")); |
| 111 | case "approval_pending": |
| 112 | return resolve(msg("{host} is waiting for someone to approve this device", { host })); |
| 113 | case "outdated": |
| 114 | return resolve(msg("{host} runs an older T3 Code", { host })); |
| 115 | case "clock_skew": |
| 116 | return resolve(msg("This device's clock is off")); |
| 117 | case "not_linked": |
| 118 | return resolve(msg("{host} is not linked to your T3 Connect account", { host })); |
| 119 | case "relay_error": |
| 120 | return resolve(msg("T3 Connect returned an error")); |
| 121 | case "tunnel_pending": |
| 122 | return resolve(msg("{host}'s tunnel is still being set up", { host })); |
| 123 | case "tunnel_not_enabled": |
| 124 | return resolve(msg("T3 Connect is not turned on for {host}", { host })); |
| 125 | case "released": |
| 126 | case "tunnel_down": |
| 127 | return resolve(msg("{host}'s tunnel is offline", { host })); |
| 128 | case "origin_unreachable": |
| 129 | return resolve(msg("Tunnel works, but T3 Code on {host} did not answer", { host })); |
| 130 | case "invalid_response": |
| 131 | return resolve(msg("T3 Code on {host} sent an unexpected answer", { host })); |
| 132 | case "dns": |
| 133 | return resolve(msg("{host}'s tunnel address did not resolve", { host })); |
| 134 | case "tls": |
| 135 | return resolve(msg("Secure connection to {host}'s tunnel failed", { host })); |
| 136 | case "refused": |
| 137 | return resolve(msg("{host}'s tunnel refused the connection", { host })); |
| 138 | case "timeout": |
| 139 | return resolve(msg("{host} did not answer in time", { host })); |
| 140 | case "unknown": |
| 141 | case null: |
| 142 | break; |
| 143 | } |
| 144 | switch (located.hop) { |
| 145 | case "device": |
| 146 | return resolve(msg("This device could not prepare the connection")); |
| 147 | case "relay": |
| 148 | return failure?.reason === "authentication" |
| 149 | ? resolve(msg("T3 Connect did not accept this device's sign-in")) |
| 150 | : resolve(msg("This device can't reach T3 Connect")); |
| 151 | case "tunnel": |
| 152 | // The relay already reached the host when this device fails on its own. |
| 153 | return failure?.reason === "network" || |
| 154 | failure?.reason === "transport" || |
| 155 | failure?.reason === "timeout" |
| 156 | ? resolve(msg("This device can't reach {host}'s tunnel", { host })) |
| 157 | : resolve(msg("T3 Connect could not reach {host}'s tunnel", { host })); |
| 158 | case "server": |
| 159 | return failure?.reason === "authentication" || failure?.reason === "permission" |
| 160 | ? resolve(msg("T3 Code on {host} did not accept this device", { host })) |
| 161 | : resolve(msg("T3 Code on {host} did not answer", { host })); |
| 162 | } |
| 163 | } |
| 164 | |
| 165 | function steps( |
| 166 | host: string, |
| 167 | located: Located, |
| 168 | failure: ConnectionAttemptError | null, |
| 169 | resolve: MFunctionType, |
| 170 | ): string[] { |
| 171 | const checkHost = resolve( |
| 172 | msg("On {host}, check Settings > Sharing & access or run `t3 connect status`.", { host }), |
| 173 | ); |
| 174 | switch (located.cause) { |
| 175 | case "offline": |
| 176 | return [resolve(msg("Connect this device to the internet. T3 Code reconnects on its own."))]; |
| 177 | case "session_pending": |
| 178 | return [ |
| 179 | resolve(msg("Wait a moment. T3 Code retries on its own.")), |
| 180 | resolve(msg("If it keeps waiting, reload or restart T3 Code on this device.")), |
| 181 | ]; |
| 182 | case "approval_pending": { |
| 183 | const code = |
| 184 | failure?._tag === "ConnectionTransientError" ? failure.verificationCode : undefined; |
| 185 | return [ |
| 186 | code |
| 187 | ? resolve( |
| 188 | msg( |
| 189 | "On a device already connected to {host}, open Settings > Sharing & access and approve the device showing {code}.", |
| 190 | { host, code }, |
| 191 | ), |
| 192 | ) |
| 193 | : resolve( |
| 194 | msg( |
| 195 | "On a device already connected to {host}, open Settings > Sharing & access and approve this device.", |
| 196 | { host }, |
| 197 | ), |
| 198 | ), |
| 199 | resolve( |
| 200 | msg("Or run `t3 auth connect-device approve {code}` on {host}.", { |
| 201 | code: code ?? "<code>", |
| 202 | host, |
| 203 | }), |
| 204 | ), |
| 205 | ]; |
| 206 | } |
| 207 | case "outdated": |
| 208 | return [resolve(msg("Update T3 Code on {host}.", { host }))]; |
| 209 | case "clock_skew": |
| 210 | return [ |
| 211 | resolve( |
| 212 | msg("Turn on automatic date and time on this device and on {host}, then retry.", { |
| 213 | host, |
| 214 | }), |
| 215 | ), |
| 216 | ]; |
| 217 | case "not_linked": |
| 218 | return [ |
| 219 | resolve( |
| 220 | msg("Check that this device is signed in to the same T3 Connect account as the host."), |
| 221 | ), |
| 222 | resolve( |
| 223 | msg("On {host}, open Settings > Sharing & access and turn T3 Connect on.", { host }), |
| 224 | ), |
| 225 | ]; |
| 226 | case "tunnel_pending": |
| 227 | return [resolve(msg("Wait a minute. T3 Code retries on its own.")), checkHost]; |
| 228 | case "relay_error": |
| 229 | return [ |
| 230 | resolve(msg("Wait a few minutes. T3 Code retries on its own.")), |
| 231 | resolve(msg("If it keeps failing, copy the diagnostics and report it.")), |
| 232 | ]; |
| 233 | case "tunnel_not_enabled": |
| 234 | return [ |
| 235 | resolve( |
| 236 | msg("On {host}, open Settings > Sharing & access and turn T3 Connect on.", { host }), |
| 237 | ), |
| 238 | ]; |
| 239 | case "released": |
| 240 | case "tunnel_down": |
| 241 | return [ |
| 242 | resolve(msg("Make sure {host} is awake and T3 Code is running on it.", { host })), |
| 243 | checkHost, |
| 244 | resolve( |
| 245 | msg( |
| 246 | "A VPN or Tailscale exit node on {host} can block the tunnel (port 7844). Turn it off or allow the tunnel.", |
| 247 | { host }, |
| 248 | ), |
| 249 | ), |
| 250 | ]; |
| 251 | case "origin_unreachable": |
| 252 | case "invalid_response": |
| 253 | return [resolve(msg("Open or restart T3 Code on {host}.", { host })), checkHost]; |
| 254 | // The relay saw these on its way to the host, so the fix is on the host. |
| 255 | case "dns": |
| 256 | case "tls": |
| 257 | case "refused": |
| 258 | case "timeout": |
| 259 | case "unknown": |
| 260 | return [resolve(msg("Make sure {host} is awake and online.", { host })), checkHost]; |
| 261 | case null: |
| 262 | break; |
| 263 | } |
| 264 | switch (located.hop) { |
| 265 | case "device": |
| 266 | return [ |
| 267 | resolve(msg("Restart T3 Code on this device.")), |
| 268 | resolve( |
| 269 | msg("If it keeps failing, remove {host} from this device and add it again.", { host }), |
| 270 | ), |
| 271 | ]; |
| 272 | case "relay": |
| 273 | return failure?.reason === "authentication" |
| 274 | ? [resolve(msg("Sign out of T3 Connect and sign in again."))] |
| 275 | : [ |
| 276 | resolve(msg("Check this device's internet connection.")), |
| 277 | resolve(msg("A VPN, firewall, or ad blocker on this device can block T3 Connect.")), |
| 278 | ]; |
| 279 | case "tunnel": |
| 280 | return failure?.reason === "network" || |
| 281 | failure?.reason === "transport" || |
| 282 | failure?.reason === "timeout" |
| 283 | ? [ |
| 284 | resolve(msg("A VPN, firewall, or DNS filter on this device can block the tunnel.")), |
| 285 | resolve(msg("Try another network, or add a direct route such as a Tailscale address.")), |
| 286 | ] |
| 287 | : [resolve(msg("Make sure {host} is awake and online.", { host })), checkHost]; |
| 288 | case "server": |
| 289 | return failure?.reason === "authentication" |
| 290 | ? [ |
| 291 | resolve( |
| 292 | msg( |
| 293 | "This device's sign-in to {host} expired or was revoked. Pair it again with a new pairing link from {host}.", |
| 294 | { host }, |
| 295 | ), |
| 296 | ), |
| 297 | ] |
| 298 | : [ |
| 299 | resolve(msg("Make sure T3 Code is running on {host}.", { host })), |
| 300 | resolve(msg("Retry. If it keeps failing, copy the diagnostics.")), |
| 301 | ]; |
| 302 | } |
| 303 | } |
| 304 | |
| 305 | function helpSection( |
| 306 | located: Located, |
| 307 | failure: ConnectionAttemptError | null, |
| 308 | ): T3ConnectTroubleshootingSection { |
| 309 | switch (located.cause) { |
| 310 | case "offline": |
| 311 | return "this-device-cant-reach-t3-connect"; |
| 312 | case "outdated": |
| 313 | return "the-host-runs-an-older-t3-code"; |
| 314 | case "clock_skew": |
| 315 | return "the-clock-is-off"; |
| 316 | case "session_pending": |
| 317 | case "approval_pending": |
| 318 | case "not_linked": |
| 319 | case "tunnel_not_enabled": |
| 320 | return "sign-in-account-or-link-problems"; |
| 321 | case "relay_error": |
| 322 | return "t3-connect-returned-an-error"; |
| 323 | case "released": |
| 324 | case "tunnel_down": |
| 325 | case "tunnel_pending": |
| 326 | return "the-hosts-tunnel-is-offline"; |
| 327 | case "origin_unreachable": |
| 328 | case "invalid_response": |
| 329 | return "the-tunnel-works-but-t3-code-does-not-answer"; |
| 330 | case "dns": |
| 331 | case "tls": |
| 332 | case "refused": |
| 333 | case "timeout": |
| 334 | case "unknown": |
| 335 | return "the-t3-connect-address-does-not-resolve-or-answer"; |
| 336 | case null: |
| 337 | break; |
| 338 | } |
| 339 | const onThisDevice = |
| 340 | failure?.reason === "network" || |
| 341 | failure?.reason === "transport" || |
| 342 | failure?.reason === "timeout"; |
| 343 | switch (located.hop) { |
| 344 | case "device": |
| 345 | return "this-device-cant-reach-t3-connect"; |
| 346 | case "relay": |
| 347 | return failure?.reason === "authentication" |
| 348 | ? "sign-in-account-or-link-problems" |
| 349 | : "this-device-cant-reach-t3-connect"; |
| 350 | case "tunnel": |
| 351 | return onThisDevice ? "this-device-cant-reach-t3-connect" : "the-hosts-tunnel-is-offline"; |
| 352 | case "server": |
| 353 | return failure?.reason === "authentication" || failure?.reason === "permission" |
| 354 | ? "sign-in-account-or-link-problems" |
| 355 | : "the-tunnel-works-but-t3-code-does-not-answer"; |
| 356 | } |
| 357 | } |
| 358 | |
| 359 | const T3_CONNECT_NAME = "T3 Connect"; |
| 360 | |
| 361 | const HOP_ORDER = { |
| 362 | relay: ["device", "relay", "tunnel", "server"], |
| 363 | direct: ["device", "server"], |
| 364 | } as const; |
| 365 | |
| 366 | function hopLabel(hop: ConnectionHop, host: string, resolve: MFunctionType): string { |
| 367 | switch (hop) { |
| 368 | case "device": |
| 369 | return resolve(msg("This device")); |
| 370 | case "relay": |
| 371 | return T3_CONNECT_NAME; |
| 372 | case "tunnel": |
| 373 | return resolve(msg("{host} tunnel", { host })); |
| 374 | case "server": |
| 375 | return resolve(msg("T3 Code on {host}", { host })); |
| 376 | } |
| 377 | } |
| 378 | |
| 379 | /** |
| 380 | * Turns a connection state into what failed, in order, and what to try. Returns |
| 381 | * null when nothing has failed. Web and mobile render this same model. |
| 382 | */ |
| 383 | export function presentConnectionDiagnosis( |
| 384 | input: ConnectionDiagnosisInput, |
| 385 | resolve: MFunctionType = mFallback, |
| 386 | ): ConnectionDiagnosis | null { |
| 387 | const located = locate(input); |
| 388 | if (located === null) return null; |
| 389 | const host = input.hostLabel; |
| 390 | const failure = input.state.lastFailure; |
| 391 | const relayPath = |
| 392 | located.hop === "relay" || |
| 393 | located.hop === "tunnel" || |
| 394 | (failure === null && input.relayStatus?.status === "offline") || |
| 395 | (failure?.via ?? input.via) === "relay"; |
| 396 | const order: ReadonlyArray<ConnectionHop> = HOP_ORDER[relayPath ? "relay" : "direct"]; |
| 397 | const failedIndex = order.indexOf(located.hop); |
| 398 | const hops = order.map((hop, index): ConnectionDiagnosisHop => ({ |
| 399 | hop, |
| 400 | label: hopLabel(hop, host, resolve), |
| 401 | result: |
| 402 | index === failedIndex |
| 403 | ? "failed" |
| 404 | : index < failedIndex && located.guessed !== true |
| 405 | ? "ok" |
| 406 | : "unchecked", |
| 407 | })); |
| 408 | |
| 409 | // The relay health check only explains the state when no attempt has failed yet. |
| 410 | const httpStatus = failure !== null ? failure.httpStatus : input.relayStatus?.endpointStatus; |
| 411 | const facts: Array<readonly [string, string]> = []; |
| 412 | const add = (label: string, value: string | number | null | undefined) => { |
| 413 | if (value !== null && value !== undefined && value !== "") facts.push([label, String(value)]); |
| 414 | }; |
| 415 | add( |
| 416 | resolve(msg("Cause", { $context: "diagnostics field label" })), |
| 417 | located.cause ?? failure?.reason, |
| 418 | ); |
| 419 | add(resolve(msg("HTTP status")), httpStatus); |
| 420 | add( |
| 421 | resolve(msg("Attempts", { $context: "diagnostics field label" })), |
| 422 | input.state.attempt > 0 ? input.state.attempt : null, |
| 423 | ); |
| 424 | add( |
| 425 | resolve(msg("Next retry")), |
| 426 | input.state.retryAt === null |
| 427 | ? null |
| 428 | : DateTime.formatIso(DateTime.makeUnsafe(input.state.retryAt)), |
| 429 | ); |
| 430 | add( |
| 431 | resolve(msg("Route", { $context: "diagnostics field label" })), |
| 432 | relayPath ? "T3 Connect" : resolve(msg("Direct", { $context: "connection route" })), |
| 433 | ); |
| 434 | add(resolve(msg("App version")), input.clientVersion); |
| 435 | add(resolve(msg("Host version")), input.serverVersion); |
| 436 | add(resolve(msg("Error", { $context: "diagnostics field label" })), failure?.detail); |
| 437 | add(resolve(msg("Trace ID")), failure?.traceId); |
| 438 | |
| 439 | return { |
| 440 | headline: headline(host, located, failure, resolve), |
| 441 | hops, |
| 442 | steps: steps(host, located, failure, resolve), |
| 443 | facts, |
| 444 | moreInfoUrl: |
| 445 | relayPath || located.cause === "session_pending" |
| 446 | ? t3ConnectTroubleshootingUrl(helpSection(located, failure)) |
| 447 | : null, |
| 448 | }; |
| 449 | } |
| 450 | |
| 451 | const HOP_MARK = { ok: "ok", failed: "FAILED", unchecked: "not checked" } as const; |
| 452 | |
| 453 | /** One plain-text block for bug reports. */ |
| 454 | export function connectionDiagnosisText(hostLabel: string, diagnosis: ConnectionDiagnosis): string { |
| 455 | return [ |
| 456 | `T3 Code connection to ${hostLabel}: ${diagnosis.headline}`, |
| 457 | "", |
| 458 | ...diagnosis.hops.map((hop) => `${hop.label}: ${HOP_MARK[hop.result]}`), |
| 459 | "", |
| 460 | ...diagnosis.facts.map(([label, value]) => `${label}: ${value}`), |
| 461 | ...(diagnosis.moreInfoUrl ? ["", `More info: ${diagnosis.moreInfoUrl}`] : []), |
| 462 | ].join("\n"); |
| 463 | } |