From 5636f45f34d5742ef44b2022b1ac6c4269052227 Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:07:48 +0000 Subject: [PATCH 1/2] fix: direct routes come before forwarded tunnels A saved bearer route to a loopback address, such as a `cloudflared access tcp` forward, now has its own "forward" kind and ranks with public routes, behind LAN and Tailscale. Routes for servers on this device keep the "loopback" kind: the primary target and desktop-local backends registered under the `local:` connection id prefix. Forwards keep loopback's trust rules and show as "Forwarded". Model: claude-opus-5-5 Task: fix Agent: claude-code Co-Authored-By: Claude Opus 5.5 --- .../settings/EnvironmentRoutesSection.tsx | 1 + apps/web/src/connection/desktopLocal.ts | 7 +- docs/user/remote-access.md | 4 +- .../src/connection/routes.test.ts | 34 +++++- .../client-runtime/src/connection/routes.ts | 28 ++++- .../src/connection/supervisor.test.ts | 108 +++++++++++++++++- 6 files changed, 170 insertions(+), 12 deletions(-) diff --git a/apps/mobile/src/features/settings/EnvironmentRoutesSection.tsx b/apps/mobile/src/features/settings/EnvironmentRoutesSection.tsx index 4b02247c6137..6321da9f7f52 100644 --- a/apps/mobile/src/features/settings/EnvironmentRoutesSection.tsx +++ b/apps/mobile/src/features/settings/EnvironmentRoutesSection.tsx @@ -41,6 +41,7 @@ const REMOVE_SIZE = 20; const ROUTE_ICONS: Record = { relay: "cloud", loopback: "desktopcomputer", + forward: "arrow.left.arrow.right", lan: "wifi", tailnet: "point.3.connected.trianglepath.dotted", vpn: { ios: "lock.shield", android: "lock" }, diff --git a/apps/web/src/connection/desktopLocal.ts b/apps/web/src/connection/desktopLocal.ts index eb46a09ab3ac..59ac4fa2f177 100644 --- a/apps/web/src/connection/desktopLocal.ts +++ b/apps/web/src/connection/desktopLocal.ts @@ -1,12 +1,13 @@ -import type { ConnectionTarget } from "@t3tools/client-runtime/connection"; +import { + DESKTOP_LOCAL_CONNECTION_ID_PREFIX, + type ConnectionTarget, +} from "@t3tools/client-runtime/connection"; import { PRIMARY_LOCAL_ENVIRONMENT_ID, type DesktopBridge, type DesktopEnvironmentBootstrap, } from "@t3tools/contracts"; -const DESKTOP_LOCAL_CONNECTION_ID_PREFIX = "local:"; - export function desktopLocalConnectionId(backendId: string): string { return `${DESKTOP_LOCAL_CONNECTION_ID_PREFIX}${backendId}`; } diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md index c963e22b8d6a..fc2ec4cfb916 100644 --- a/docs/user/remote-access.md +++ b/docs/user/remote-access.md @@ -141,7 +141,9 @@ route** in the machine's route list, or next to it in the T3 Connect list. A pairing link for a saved machine is refused when it comes from an address that machine does not have yet; add that address with **Add route** instead. Pairing again over an address the machine already has still works. A new route -is placed by speed, in that order, and you can reorder routes at any time. +is placed by speed, in that order, and you can reorder routes at any time. A +`localhost` port forwarded to the machine, such as a `cloudflared access tcp` +tunnel, shows as Forwarded and is placed after its LAN and Tailscale routes. While connected through T3 Connect or a paired address, T3 Code also learns the machine's current LAN and Tailscale addresses and adds them as routes, so diff --git a/packages/client-runtime/src/connection/routes.test.ts b/packages/client-runtime/src/connection/routes.test.ts index e8dd244e043a..0edf28288461 100644 --- a/packages/client-runtime/src/connection/routes.test.ts +++ b/packages/client-runtime/src/connection/routes.test.ts @@ -8,7 +8,7 @@ import { type ConnectionRoute, } from "./catalog.ts"; import { pullRequestRoutingConnectionKey } from "./pullRequestRoutingPermissions.ts"; -import { BearerConnectionTarget, RelayConnectionTarget } from "./model.ts"; +import { BearerConnectionTarget, PrimaryConnectionTarget, RelayConnectionTarget } from "./model.ts"; import { connectionRouteId, connectionRouteKind, @@ -73,7 +73,7 @@ describe("connection routes", () => { expect(connectionRouteLabel(direct("mesh", "http://100.96.0.1:3773/"))).toBe("VPN"); expect(connectionRouteKind(TAILNET)).toBe("tailnet"); expect(connectionRouteKind(PUBLIC)).toBe("public"); - expect(connectionRouteKind(direct("lo", "http://127.0.0.1:3773/"))).toBe("loopback"); + expect(connectionRouteKind(direct("lo", "http://127.0.0.1:3773/"))).toBe("forward"); expect(connectionRouteKind(direct("ts6", "http://[fd7a:115c:a1e0::1]:3773/"))).toBe("tailnet"); expect(connectionRouteLabel(TAILNET)).toBe("Tailscale"); expect(connectionRouteLabel(RELAY)).toBe("T3 Connect"); @@ -108,6 +108,36 @@ describe("connection routes", () => { expect(isNearbyAddress("not a url")).toBe(false); }); + it("tells a forwarded loopback port from a server on this device", () => { + const forward = direct("r720", "http://127.0.0.1:23780/"); + expect(connectionRouteKind(forward)).toBe("forward"); + expect(connectionRouteLabel(forward)).toBe("Forwarded"); + // Its far side is authenticated, and the port cannot move to another host. + expect(routeKeepsItsHost(forward)).toBe(true); + const wsl = direct("local:wsl:Ubuntu", "http://127.0.0.1:3774/"); + expect(connectionRouteKind(wsl)).toBe("loopback"); + expect(connectionRouteLabel(wsl)).toBe("This device"); + const primary: ConnectionRoute = { + target: new PrimaryConnectionTarget({ + environmentId: ENVIRONMENT_ID, + label: "Desk", + httpBaseUrl: "http://127.0.0.1:3773/", + wsBaseUrl: "ws://127.0.0.1:3773/", + }), + profile: Option.none(), + }; + expect(connectionRouteKind(primary)).toBe("loopback"); + }); + + it("places a direct route ahead of a forward, and a forward behind direct routes", () => { + const forward = direct("r720", "http://127.0.0.1:23780/"); + expect(insertRoute([forward, RELAY], TAILNET)).toEqual([TAILNET, forward, RELAY]); + expect(insertRoute([forward], LAN)).toEqual([LAN, forward]); + expect(insertRoute([LAN, TAILNET, RELAY], forward)).toEqual([LAN, TAILNET, forward, RELAY]); + // An order already saved, possibly dragged, is not rearranged. + expect(insertRoute([forward, TAILNET], LAN)).toEqual([LAN, forward, TAILNET]); + }); + it("places a new route after faster kinds and ahead of T3 Connect", () => { expect(insertRoute([RELAY], LAN)).toEqual([LAN, RELAY]); expect(insertRoute([LAN, RELAY], TAILNET)).toEqual([LAN, TAILNET, RELAY]); diff --git a/packages/client-runtime/src/connection/routes.ts b/packages/client-runtime/src/connection/routes.ts index 7a3b4a11e616..d9833badf02d 100644 --- a/packages/client-runtime/src/connection/routes.ts +++ b/packages/client-runtime/src/connection/routes.ts @@ -17,6 +17,8 @@ import { BearerConnectionTarget, type ConnectionTarget } from "./model.ts"; export type ConnectionRouteKind = | "relay" | "loopback" + /** A saved loopback address, such as a `cloudflared access tcp` port, that reaches another machine. */ + | "forward" | "lan" | "tailnet" | "vpn" @@ -25,6 +27,9 @@ export type ConnectionRouteKind = export const RELAY_ROUTE_ID = "relay"; +/** Desktop-local secondary backends, such as WSL, register bearer routes under this id prefix. */ +export const DESKTOP_LOCAL_CONNECTION_ID_PREFIX = "local:"; + export function connectionRouteId(target: ConnectionTarget): string { switch (target._tag) { case "PrimaryConnectionTarget": @@ -99,23 +104,33 @@ export function connectionRouteKind(route: ConnectionRoute): ConnectionRouteKind const hostname = routeHostname(route); if (hostname === null) return "public"; const profile = Option.getOrNull(route.profile); - return directAddressKind( + const kind = directAddressKind( hostname, profile?._tag === "BearerConnectionProfile" && profile.network === "tailscale", ); + // Servers on this device come from the platform: the primary and the + // desktop-local backends. A user-saved loopback address is a port + // forward to another machine, so it ranks behind that machine's direct + // routes. + return kind === "loopback" && + route.target._tag === "BearerConnectionTarget" && + !route.target.connectionId.startsWith(DESKTOP_LOCAL_CONNECTION_ID_PREFIX) + ? "forward" + : kind; } } } /** * Whether the route's address reaches the same machine on every network: TLS - * proves who answers, and loopback cannot move. Any other plain http address, - * a tailnet one too once Tailscale is down, can belong to another machine after - * a network change, so an answer from it is not kept. + * proves who answers, and loopback, a forward too, cannot move. Any other + * plain http address, a tailnet one too once Tailscale is down, can belong to + * another machine after a network change, so an answer from it is not kept. */ export function routeKeepsItsHost(route: ConnectionRoute): boolean { if (routeHttpBaseUrl(route)?.startsWith("https:") === true) return true; - return connectionRouteKind(route) === "loopback"; + const kind = connectionRouteKind(route); + return kind === "loopback" || kind === "forward"; } /** A loopback or LAN host answers within a few seconds or is not there. */ @@ -134,6 +149,7 @@ const ROUTE_KIND_RANK: Record = { tailnet: 2, vpn: 2, public: 3, + forward: 3, ssh: 4, relay: 5, }; @@ -192,6 +208,8 @@ export function connectionRouteLabel(route: ConnectionRoute): string { return "T3 Connect"; case "loopback": return "This device"; + case "forward": + return "Forwarded"; case "lan": return "LAN"; case "tailnet": diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts index 1fb7aaed524a..a517d1aa5691 100644 --- a/packages/client-runtime/src/connection/supervisor.test.ts +++ b/packages/client-runtime/src/connection/supervisor.test.ts @@ -48,7 +48,14 @@ import * as RpcSession from "../rpc/session.ts"; import { presentConnectionState } from "./presentation.ts"; import * as EnvironmentSupervisor from "./supervisor.ts"; import * as ConnectionWakeups from "./wakeups.ts"; -import { connectionRouteId, entryWithRoutes, isLearned, mergeLearnedRoutes } from "./routes.ts"; +import { + connectionRouteId, + connectionRouteLabel, + connectionRoutes, + entryWithRoutes, + isLearned, + mergeLearnedRoutes, +} from "./routes.ts"; const TARGET = new PrimaryConnectionTarget({ environmentId: EnvironmentId.make("environment-1"), @@ -2320,6 +2327,105 @@ describe("EnvironmentSupervisor routes", () => { }), ); + it.effect( + "prefers a learned Tailscale route over a forwarded tunnel and fails over between them", + () => + Effect.gen(function* () { + // A `cloudflared access tcp` forward to another machine, paired on this laptop. + const forwardTarget = new BearerConnectionTarget({ + environmentId: TARGET.environmentId, + label: TARGET.label, + connectionId: "bearer:r720-forward", + }); + const forwardEntry: ConnectionCatalogEntry = { + target: forwardTarget, + profile: Option.some( + new BearerConnectionProfile({ + connectionId: forwardTarget.connectionId, + environmentId: TARGET.environmentId, + label: TARGET.label, + httpBaseUrl: "http://127.0.0.1:23780/", + wsBaseUrl: "ws://127.0.0.1:23780/", + }), + ), + enabled: true, + }; + const tailnetId = `learned:${TARGET.environmentId}:http://100.101.102.103:3773@${forwardTarget.connectionId}`; + const tailnetReachable = yield* Ref.make(true); + const harness = yield* makeHarness({ + checkRoute: (route) => + connectionRouteId(route.target) === tailnetId + ? Ref.get(tailnetReachable).pipe( + Effect.map((reachable) => (reachable ? "answered" : "silent")), + ) + : Effect.succeed("answered"), + prepare: (_attempt, target) => Effect.succeed(preparedFor(target)), + initialConfig: () => + Effect.succeed({ + directEndpoints: [{ kind: "tailnet", httpBaseUrl: "http://100.101.102.103:3773/" }], + } as unknown as ServerConfig), + }); + const current = yield* Ref.make(forwardEntry); + const supervisor = yield* EnvironmentSupervisor.make(forwardEntry, { + initiallyDesired: true, + learnRoutes: ({ activeRoute, reported }) => + Effect.gen(function* () { + const entry = yield* Ref.get(current); + const routes = mergeLearnedRoutes({ + entry, + activeRoute, + reported, + allowInsecure: true, + }); + if (routes === null) return Option.none(); + const next = entryWithRoutes(entry, routes); + yield* Ref.set(current, next); + return Option.some(next); + }), + }).pipe(Effect.provide(harness.dependencies)); + const routeInUse = Effect.gen(function* () { + const prepared = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.prepared)); + const route = connectionRoutes(yield* Ref.get(current)).find( + (candidate) => + connectionRouteId(candidate.target) === connectionRouteId(prepared.target), + ); + return route === undefined ? undefined : connectionRouteLabel(route); + }); + + // 1. The first connect can only use the forward. The Tailscale address + // it reports is saved ahead of the forward, and the connection moves to it. + yield* awaitState( + supervisor.state, + (state) => state.phase === "connected" && state.generation === 2, + ); + expect(connectionRoutes(yield* Ref.get(current)).map(connectionRouteLabel)).toEqual([ + "Tailscale", + "Forwarded", + ]); + expect(yield* routeInUse).toBe("Tailscale"); + + // 2. Away from the tailnet the direct socket drops; the forward takes over. + yield* Ref.set(tailnetReachable, false); + yield* harness.closeLatestSession(); + yield* awaitState(supervisor.state, (state) => state.phase === "backoff"); + yield* TestClock.adjust("250 millis"); + yield* awaitState( + supervisor.state, + (state) => state.phase === "connected" && state.generation === 3, + ); + expect(yield* routeInUse).toBe("Forwarded"); + + // 3. Back on the tailnet, the next network change moves it back to direct. + yield* Ref.set(tailnetReachable, true); + yield* harness.wake("network-changed"); + yield* awaitState( + supervisor.state, + (state) => state.phase === "connected" && state.generation === 4, + ); + expect(yield* routeInUse).toBe("Tailscale"); + }), + ); + it.effect.each(["initial", "late", "withdrawn", "withdrawn-upgrade", "omitted"] as const)( "learns the %s direct endpoint over T3 Connect", (discovery) => From 33b265a5f144a524b1bf76125782487daa59a40c Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:30:06 +0000 Subject: [PATCH 2/2] fix: a tunnel forward gets a remote's time on its first check The descriptor check before connecting still used the 3-second loopback timeout for a forwarded route, judged by its 127.0.0.1 address. A cloudflared tunnel that takes longer to open then failed the connect. The bearer broker now passes the route kind, so a forward waits as long as a remote address. Review round 1 finding 1. Model: claude-opus-5-5 Task: fix Agent: claude-code Co-Authored-By: Claude Opus 5.5 --- .../client-runtime/src/authorization/layer.test.ts | 13 +++++++++++-- .../client-runtime/src/authorization/service.ts | 8 +++++++- packages/client-runtime/src/connection/resolver.ts | 3 ++- 3 files changed, 20 insertions(+), 4 deletions(-) diff --git a/packages/client-runtime/src/authorization/layer.test.ts b/packages/client-runtime/src/authorization/layer.test.ts index 8db36ec6c399..d1a70e2c6b26 100644 --- a/packages/client-runtime/src/authorization/layer.test.ts +++ b/packages/client-runtime/src/authorization/layer.test.ts @@ -474,11 +474,15 @@ describe("RemoteEnvironmentAuthorization", () => { it.effect("gives up on a silent loopback or LAN address sooner than on a remote one", () => Effect.gen(function* () { const silent = () => new Promise(() => {}); - const harness = yield* makeHarness({ responses: [silent, silent, silent] }); + const harness = yield* makeHarness({ responses: [silent, silent, silent, silent] }); yield* Effect.gen(function* () { const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization; - const authorizeAt = (httpBaseUrl: string, connectionMethod: "direct" | "ssh" = "direct") => + const authorizeAt = ( + httpBaseUrl: string, + connectionMethod: "direct" | "ssh" = "direct", + forwarded = false, + ) => remote .authorizeBearer({ expectedEnvironmentId: ENVIRONMENT_ID, @@ -486,17 +490,21 @@ describe("RemoteEnvironmentAuthorization", () => { wsBaseUrl: httpBaseUrl.replace(/^http/, "ws"), bearerToken: "bearer-token", connectionMethod, + forwarded, }) .pipe(Effect.flip, Effect.forkChild); const lan = yield* authorizeAt("http://192.168.1.2:3773"); const tailnet = yield* authorizeAt("http://100.101.102.103:3773"); // An SSH forward listens on loopback but reaches a remote host. const forwarded = yield* authorizeAt("http://127.0.0.1:4010", "ssh"); + // A saved tunnel port, such as `cloudflared access tcp`, also reaches a remote host. + const tunnel = yield* authorizeAt("http://127.0.0.1:23780", "direct", true); yield* TestClock.adjust("3 seconds"); expect(lan.pollUnsafe()).toBeDefined(); expect(tailnet.pollUnsafe()).toBeUndefined(); expect(forwarded.pollUnsafe()).toBeUndefined(); + expect(tunnel.pollUnsafe()).toBeUndefined(); expect(yield* Fiber.join(lan)).toMatchObject({ _tag: "ConnectionTransientError", reason: "timeout", @@ -505,6 +513,7 @@ describe("RemoteEnvironmentAuthorization", () => { yield* TestClock.adjust("7 seconds"); expect(tailnet.pollUnsafe()).toBeDefined(); expect(forwarded.pollUnsafe()).toBeDefined(); + expect(tunnel.pollUnsafe()).toBeDefined(); }).pipe(Effect.provide(harness.layer)); }), ); diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts index 919ae3cf0499..67c374c75f29 100644 --- a/packages/client-runtime/src/authorization/service.ts +++ b/packages/client-runtime/src/authorization/service.ts @@ -70,6 +70,8 @@ export class RemoteEnvironmentAuthorization extends Context.Service< readonly wsBaseUrl: string; readonly bearerToken: string; readonly connectionMethod: ClientConnectionMethod; + /** A loopback port forward to another machine, such as a tunnel: it may take a remote's time to answer. */ + readonly forwarded?: boolean; }) => Effect.Effect; readonly authorizeDpop: (input: { readonly expectedEnvironmentId: EnvironmentId; @@ -186,6 +188,7 @@ export const make = Effect.gen(function* () { readonly expectedEnvironmentId: EnvironmentId; readonly httpBaseUrl: string; readonly connectionMethod: ClientConnectionMethod; + readonly forwarded?: boolean; }) { const checked = checkedDescriptors.get(input.httpBaseUrl); checkedDescriptors.delete(input.httpBaseUrl); @@ -200,7 +203,9 @@ export const make = Effect.gen(function* () { input.httpBaseUrl, input.connectionMethod, // An SSH forward listens on loopback but reaches a remote host. - input.connectionMethod === "direct" && isNearbyAddress(input.httpBaseUrl) + input.connectionMethod === "direct" && + input.forwarded !== true && + isNearbyAddress(input.httpBaseUrl) ? NEARBY_DESCRIPTOR_TIMEOUT_MS : undefined, ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient)); @@ -223,6 +228,7 @@ export const make = Effect.gen(function* () { readonly wsBaseUrl: string; readonly bearerToken: string; readonly connectionMethod: ClientConnectionMethod; + readonly forwarded?: boolean; }) { const descriptor = yield* verifyDirectEndpoint(input); const socketUrl = yield* resolveRemoteWebSocketConnectionUrl({ diff --git a/packages/client-runtime/src/connection/resolver.ts b/packages/client-runtime/src/connection/resolver.ts index 05235ef53603..e5a61615702c 100644 --- a/packages/client-runtime/src/connection/resolver.ts +++ b/packages/client-runtime/src/connection/resolver.ts @@ -48,7 +48,7 @@ import { appendOrchestrationProtocol, orchestrationProtocolCompatibilityError, } from "./compatibility.ts"; -import { credentialConnectionId } from "./routes.ts"; +import { connectionRouteKind, credentialConnectionId } from "./routes.ts"; import { fetchRemoteEnvironmentDescriptor } from "../environment/descriptor.ts"; export class ConnectionResolver extends Context.Service< @@ -169,6 +169,7 @@ const makeBearerBroker = Effect.fn("clientRuntime.connection.broker.makeBearer") wsBaseUrl: profile.wsBaseUrl, bearerToken: credential.token, connectionMethod: "direct", + forwarded: connectionRouteKind({ target, profile: entry.profile }) === "forward", }); return { ...authorized,