Skip to content

fix: direct routes come before forwarded tunnels - #83

Merged
nullStack65 merged 2 commits into
release/native-0.1.10from
fix/native-0.1.10-direct-routes-before-forwards
Nov 18, 2026
Merged

nullStack65 merged 2 commits into
release/native-0.1.10from
fix/native-0.1.10-direct-routes-before-forwards

Conversation

@nullStack65

@nullStack65 nullStack65 commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

The desktop app reaches some machines through a cloudflared access tcp forward on a laptop port such as http://127.0.0.1:23780. Route ranking called that route "loopback", which ranks first. So when the app learned the machine's Tailscale or LAN route, it put that route behind the tunnel and never moved off the tunnel.

Fix

connectionRouteKind now returns a new forward kind for a BearerConnectionTarget with a loopback address, unless that route belongs to a desktop-local backend.

  • Rank: forward ranks with public (3), behind LAN (1) and Tailscale/VPN (2) and ahead of SSH and T3 Connect. A newly learned direct route is now placed ahead of the forward, and the supervisor's existing better-route check moves the connection to it.
  • Routes for this device stay first. The primary target is a PrimaryConnectionTarget and keeps loopback. Desktop-local secondary backends such as WSL use local:-prefixed connection IDs. That prefix now comes from client-runtime so web and the route kind share one constant, and those backends also keep loopback. Desktop ssh -L routes are SshConnectionTarget and keep ssh. Platform environments shadow user-saved entries for the same environment and never learn routes. So a user-saved bearer loopback route on desktop is a forward to another machine.
  • Trust is unchanged. routeKeepsItsHost treats forward like loopback. tokenAllowsPlainHttp still excludes it, so a forward's token is not sent over plain-HTTP LAN.
  • Probes: health probes on a forward now use the remote timeouts. Before, they used the quick loopback/LAN ones, which a tunnel to another machine cannot reliably meet.
  • Presentation: the label is "Forwarded". Web shows "via Forwarded" or "via Tailscale" for the route in use. Mobile gets an arrow.left.arrow.right icon in its kind-to-icon map.
  • Manual order is respected. Only insertRoute (new paired or learned routes) uses rank. Saved or dragged orders are never re-sorted.
  • Docs: one sentence in docs/user/remote-access.md, "Reach one machine several ways".

Tests

  • A new supervisor.test.ts case runs the failover scenario on synthetic routes, using TestClock and wakeups with no wall-clock waits:
    1. The environment is saved with only the forward (127.0.0.1:23780). The server reports a Tailscale endpoint, and mergeLearnedRoutes saves the order Tailscale, then Forwarded. The connection moves to Tailscale (generation 2).
    2. Tailscale stops answering and the socket drops. After the 250 ms backoff the connection uses the forward (generation 3, "Forwarded").
    3. Tailscale answers again. A network-changed wakeup moves the connection back to Tailscale (generation 4).
  • With the old rank (forward at 0), step 1 never reaches generation 2, so the test fails.
  • New routes.test.ts cases cover: forward vs. desktop-local vs. primary classification, the label, routeKeepsItsHost, insertion order, and that a saved order is not rearranged.
  • vp test run on routes.test.ts, supervisor.test.ts and registry.test.ts: 144 passed.
  • Typecheck passes for packages/client-runtime, apps/web and apps/mobile. Lint and format checks pass on the touched files.

Known limits

  • A forward saved before this change, with a Tailscale route already learned behind it, keeps its saved order. Nothing can tell that order from a dragged one. The user drags the direct route above the forward once.
  • On clients with no platform registrations (app.t3.codes, mobile), a bearer route to localhost that really is this device is also labeled "Forwarded". It ranks behind learned HTTPS or Tailscale routes to the same server, which still connect.
  • The same applies on desktop to a second T3 server on this machine paired by localhost (another npx t3, a dev worktree server, a Docker port), and to the iOS Simulator reaching the Mac. It is labeled "Forwarded", gets the slower health checks, and may connect to itself over Tailscale. Trust rules are unchanged.
  • The connection.route telemetry value is now "forward" for these routes, not "loopback".
  • A forward's first descriptor check now waits as long as a remote address (review finding 1, fixed at 33b265a, covered in authorization/layer.test.ts).

Model: claude-opus-5-5
Task: fix

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Bot review round 1 (Claude Opus 5.5, independent) @ 5636f45

Verdict: non-blocking. The fix is correct. It is small and matches the reported bug. Trust handling is unchanged. The failover test does prove the full sequence. My findings are a missed instance of the same "loopback answers quickly" assumption, an overclaim in the PR description, and a few nits.

Pinned: base release/native-0.1.10 @ 2349389883d27ee8ce5fc49179af34ffcb1d36d9, merge-base 417f8e817e2bf1341b1328dca4a08a9d6945dd3b, head 5636f45f34d5742ef44b2022b1ac6c4269052227. I reviewed git diff 417f8e817e..5636f45f34 only.

What I checked and found sound

  • Classification (packages/client-runtime/src/connection/routes.ts:111-119). The primary target is PrimaryConnectionTarget on web and desktop (apps/web/src/connection/platform.ts:453). WSL and other desktop-local backends are local:-prefixed bearer targets (platform.ts:488). Desktop SSH routes are SshConnectionTarget. Learned routes never carry loopback addresses (routes.ts:286). Paired, migrated and desktop-legacy bearer ids are bearer:…, so they cannot collide with local:. Every platform-owned same-device route keeps loopback.
  • Trust and plain-HTTP tokens are unchanged. routeKeepsItsHost (routes.ts:130-134) returns true exactly where it did before, because a forward was loopback before. tokenAllowsPlainHttp (routes.ts:361-372) still allows only lan/public. A forward was excluded before and is still excluded, so a forward's token is never sent over plain-HTTP LAN. sendsTokenInClear and usableRoutes behave the same.
  • Ordering. forward ranks 3, tied with public. insertRoute and upsertRoute (aheadOfSameKind compares the kind, not the rank) put new LAN and Tailscale routes ahead of a forward and leave saved or dragged orders alone. The mergeLearnedRoutes signature (routes.ts:348-355) uses the new kind on both sides, so the reclassification causes no spurious rewrite.
  • Failover test (supervisor.test.ts:2330-2427). It uses TestClock.adjust and the network-changed wakeup, with no wall-clock waits. routeInUse reads supervisor.prepared, so each step checks the route that is actually connected, not just the route order. The steps are: drop, then the forward at generation 3, then a better-route switch back to Tailscale at generation 4. The periodic better-route tick cannot fire because the clock is not advanced, so step 3 really comes from the wakeup. Mutation check: with forward: 0 (the old loopback rank), the test fails and the other 74 tests in that file are unaffected.
  • Surfaces. Web label and "via …" text come from the shared connectionRouteLabel (apps/web/src/components/settings/EnvironmentRow.tsx:37-38). The mobile icon map is exhaustive through the Record type, and arrow.left.arrow.right has an Android mapping (apps/mobile/src/components/ui/AppSymbol.android.tsx:155). Moving the prefix constant into client-runtime removes a duplicate instead of adding one.
  • Complexity. It adds a new kind, one prefix check and a shared constant, with no new machinery. I found no excess-complexity findings.

Findings (most severe first)

  1. Low. The connect-time descriptor read still gives a forward the 3 s "nearby" timeout. packages/client-runtime/src/authorization/service.ts:203 uses isNearbyAddress(httpBaseUrl) (routes.ts:137-144). That function classifies by hostname only, so 127.0.0.1:23780 counts as nearby and gets NEARBY_DESCRIPTOR_TIMEOUT_MS = 3_000. The supervisor.ts:667 answersQuickly probe path was fixed, but this is the same faulty assumption in a sibling path. The code comment there already makes this exception for SSH forwards.

    • Scenario: an environment saved with only the forward (the state in step 1 of this PR's own scenario). connectOverRoutes skips route checks when there is one route (driver.ts:79-82), so no cached descriptor exists. The first cloudflared access tcp connection opens the tunnel lazily, and that can take longer than 3 s. The descriptor fetch then times out, and the connect fails as transient and backs off, even though the tunnel would have answered.
    • Fix: decide "nearby" from the route kind instead of the URL. For example, have the resolver pass connectionRouteKind(route) === "loopback" || === "lan" (or a boolean) into fetchDescriptor, and keep isNearbyAddress only where there is no route. Alternatively, record it as a named follow-up. The repo rule asks for all in-scope instances of a pattern to be fixed together, so I would rather it land here.
  2. Low. The PR description overclaims; same-device servers paired by URL are labeled Forwarded. The description says "a user-saved bearer loopback route on desktop is a forward to another machine". That is not always true. On desktop, pairing a second T3 server on the same machine by http://localhost:<port> is still classified forward by routes.ts:115-119. Examples are another npx t3 instance, a second dev worktree server, or a Docker-published port. The iOS Simulator pairing to a dev server on the Mac host is classified the same way.

    • Impact: mostly cosmetic. The label reads "Forwarded", probes use the 15 s remote timeout instead of 3 s, and if that server reports a Tailscale endpoint, the connection moves to the machine's own Tailscale IP. That still works, and Tailscale loops it back locally. LAN plain-HTTP is not learned, because the loopback-paired token is excluded. There is no trust regression.
    • Fix: no code change needed. Correct the description and add this desktop case to "Known limits", so the next reader doesn't rely on the stronger claim.
  3. Nit. The test fails by timing out, not on an assertion. Under the mutation, the failure is Error: Test timed out in 5000ms, because awaitState(…generation === 2) waits forever. The test does not need a timeout to pass, so it meets the repo rule. Still, a reader of the failure gets no signal about which step broke. Optional fix: after step 1, assert the saved order (already done) before waiting on generation 2, or race the wait against TestClock-bounded progress. Fine as is.

  4. Nit. There is no unit coverage for the probe-timeout claim. The "Probes" bullet changes probeTimeoutFor (supervisor.ts:667-668, 3 s to 15 s for a forward on network-changed/application-active-probe) only by implication, and no test pins it. Add a test if this behavior matters; otherwise it is fine.

  5. Nit. The telemetry attribute gains a value. supervisor.ts:499 (connection.route) now emits forward where it emitted loopback. Any dashboard or query that buckets loopback will split. I note it only so nobody is surprised.

What I ran

  • vp i, using the repo-local vp under Node 26.13.1, because the system Node is 22.
  • vp test run packages/client-runtime/src/connection/routes.test.ts packages/client-runtime/src/connection/supervisor.test.ts packages/client-runtime/src/connection/registry.test.ts: 3 files, 144 passed.
  • Mutation: temporarily set forward: 0 in ROUTE_KIND_RANK, then ran vp test run supervisor.test.ts -t 'forwarded tunnel': 1 failed (timed out at step 1), 74 skipped. I reverted the change, and the tree is clean at 5636f45.
  • I did not run typecheck, lint, repo-wide checks, dev servers, or any real-client verification. I pushed no code and made no reviewer requests.

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 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Repair round 1 @ 33b265a

Fixes for the round 1 review (#83 (comment)):

  1. Fixed. A forward's first descriptor check used the 3-second loopback timeout. authorizeBearer now takes forwarded, the bearer broker sets it from connectionRouteKind(...) === "forward", and the check uses the remote timeout for it. Test: the existing "gives up on a silent loopback or LAN address sooner" case in authorization/layer.test.ts gains a tunnel at 127.0.0.1:23780 that is still pending at 3 s and times out with the remote ones.
  2. Fixed in the description. Known limits now names same-machine localhost servers and the iOS Simulator.
  3. Not changed (nit): the failover test fails by timeout rather than naming the step.
  4. Covered by the new case in 1 for the descriptor check. The supervisor's health-check timeout for forwards is still untested (nit).
  5. Noted in the description: telemetry now reports "forward".

Ran: vp test run on authorization/layer.test.ts, connection/resolver.test.ts, routes.test.ts and supervisor.test.ts in packages/client-runtime: 135 passed. vpr typecheck in client-runtime exited 0. Lint and format are clean on the 3 touched files.

@nullStack65
nullStack65 merged commit 328c68b into release/native-0.1.10 Nov 18, 2026
2 checks passed
@nullStack65

Copy link
Copy Markdown
Owner Author

Fleet build artifacts from release/native-0.1.10 at 328c68b5ca, the merge of this PR. That's 8ddb5d91a8 plus #83. Built on ASUS with the same recipe as the earlier builds. Not installed anywhere; installs are the fleet cutover owner's.

Artifact Path on ASUS sha256 Checks
Linux x64 headless server (t3 serve, ASUS and R720) ~/.local/share/closura/t3-release-staging/closura-fleet-server-0.1.10-328c68b5/t3-0.1.10-linux-x64.tar.gz 8f1a96269261f728804a5ee50d4746cadc338533bb913e70d8d2f608fb8cb810 smoke-cli-archive.ts --expect-version 0.1.10 passes. Max GLIBC 2.34. Linked environments is on by default. manifest.json beside it.
Linux x64 desktop AppImage (laptop) ~/.local/share/closura/t3-release-staging/closura-fleet-desktop-0.1.10-328c68b5/T3-Code-0.1.10-x86_64.AppImage 0b6cde48c49271cf108ab19f07ded7eaa6d4ad30836ac94f648a51a2cc68cef8 No app-update.yml. The bundled server reports 0.1.10. The committed qualify script gives failed_gates: [].
Linux x64 desktop .deb same folder, T3-Code-0.1.10-amd64.deb 01f0ddda796b8f66bc7f760909ea1741c39a0521c2dfad0203f2af9bfe55ae77 Same build.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant