fix(ios): race every transport at once and stop replacing healthy connections

[arul28]

iOS connect behaviour was broken in four measured ways. On cellular, relay was only dialed after the direct race burned its full 10s budget, so cold connects stalled 10-20s. The app could not remember that relay had worked (relay URLs were excluded from last-good) and could not remember failures at all, so dead endpoints were re-raced forever. The relay handshake serialized a Clerk token fetch behind the socket open and redialed every cold Durable Object. And while connected over relay on cellular, roaming launched a full connection race every ~30-70s and replaced the healthy connection each time — a captured idle phone made ~20 relay dials in 3.5 minutes, each felt as a 1-2s stream freeze.

This is iOS-only: apps/ios/** plus internal docs. No sync protocol, hello payload, or host-side change.

What changed

One race. Direct and relay candidates now share a single happy-eyeballs plan instead of two sequential races. A relay candidate that does not lead the ranking joins ~300ms behind the leading direct candidate; one that leads (because it is the proven route for this network) is dialed at t=0. The catch-driven "direct routes exhausted; beginning authenticated relay fallback" phase is gone.

Memory of what works. HostConnectionProfile gains networkRouteMemory: an MRU map (cap 8) from a coarse network fingerprint — wired, wifi:<the phone's own IPv4 /24>, cell — to the endpoint that last authenticated there. It is hoisted to the front of the plan and outranks the global lastSuccessfulAddress, which may belong to a different network. An SSID would need an entitlement the app does not hold; the phone's own /24 discriminates home/office/hotspot just as well for this purpose.

Memory of what fails. HostConnectionEndpointState gains lastFailedAt, consecutiveFailures, negotiatedReadyV2. Two consecutive failures inside 120s schedule an endpoint last — never removed, so a route that recovers is still tried on every connect. Success clears the streak. Cancellation, the single-flight refusal, and account/device errors are explicitly not route failures.

Path awareness. With no Wi-Fi or wired interface on the path, RFC1918 / mDNS / IPv6 link-local and unique-local candidates move to the back of the plan — each one raced eagerly costs a 5s socket-open timeout. Tailnet CGNAT and loopback are unaffected, since Tailscale works over cellular.

Relay handshake. The Clerk token is fetched concurrently with the WebSocket open via async let rather than after it. accepted (350ms window) now extends the deadline for ready, instead of the socket being abandoned and redialed without ?ready=2 on principle. That legacy redial now happens only for an endpoint that has never negotiated ready-v2. A token-based single-flight registry prevents two concurrent /connect dials for one machine key, which would otherwise consume the Durable Object's 16-tunnel cap with orphans swept only every 5-10 minutes.

Roaming. Triggers only on a real interface-set change (failover) or a 5-minute upgrade probe toward a strictly better class (lan < tailnet < relay). Being "on cellular with a saved tailnet route" is no longer a standing trigger. Roams are make-before-break, and a race that wins on the endpoint already in use keeps the live socket rather than swapping it.

Self-audit: constants

Constant	Before	After
SyncConnectionRaceTiming.relayReadyNegotiationNanoseconds	350ms, single window covering accepted and ready	renamed → relayAcceptedNegotiationNanoseconds, 350ms, now covers accepted only
SyncConnectionRaceTiming.relayReadyAfterAcceptedNanoseconds	— (post-accepted wait was unbounded, capped only by the 10s race budget)	new, 7s. Deliberately under overallBudgetNanoseconds so a relay that accepts and never bridges fails inside the race and is recorded as a failing endpoint
SyncConnectionRaceTiming.relayJoinDelayNanoseconds	—	new, 300ms
SyncEndpointFailureMemory.consecutiveFailureThreshold	—	new, 2
SyncEndpointFailureMemory.recentFailureWindowSeconds	—	new, 120s
syncNetworkRouteMemoryCapacity	—	new, 8
SyncRoamTiming.pathChangeCooldownSeconds	— (no cooldown existed; 250ms debounce only)	new, 3s
SyncRoamTiming.minimumConnectionAgeSeconds	—	new, 10s
SyncRoamTiming.upgradeProbeIntervalSeconds	—	new, 300s
candidateStaggerNanoseconds (250ms), overallBudgetNanoseconds (10s), maximumCandidateCount (3)	unchanged	unchanged

Deleted: syncShouldRoamToTailnet(...) — the standing-fact predicate that made every path update a roam trigger. Replaced by syncRoamTrigger(SyncRoamInputs). SyncRankedEndpointAttempt.kind changed from Int to SyncConnectionRouteKind (now Comparable, lower is better).

New persisted fields are all optional, so profiles written before this change decode unchanged — covered by testAProfileSavedBeforeFailureMemoryStillDecodes.

Self-audit: connect-path narratives

Cold cellular connect (relay is the only viable route)

• Before: the direct plan races saved LAN + tailnet candidates. On cellular no direct candidate can succeed, so the race burns its full 10s budget (or 5s per socket-open timeout across 3 concurrent slots) before the catch starts a second race for relay. The relay socket then opens, waits for accepted, and — on a cold Durable Object — usually fails the 350ms ready window, is abandoned, and is redialed without ?ready=2. Only then is the Clerk token fetched, serialized ahead of the hello. Measured: 10-20s.
• After: ranking puts relay first once it is the remembered winner for cell (and on the very first connect it is at most 300ms behind the leading direct candidate). Saved LAN addresses are demoted to the back of the plan because the path has no Wi-Fi interface. The Clerk token is fetched concurrently with the socket open. accepted arrives in the 350ms window and extends the ready deadline to 7s, so the cold DO completes its wake + host-pipe dial + local-port dial on the first socket. One dial, no fallback phase.

Wi-Fi returns during a relay session

• Before: nothing moved the connection off relay, ever. There was no roam-toward-LAN direction at all — the only roam target was tailnet, and it fired on the standing cellular condition rather than on the network actually changing.
• After: the interface set changes (cellular → Wi-Fi), which is a genuine .pathChange trigger, so a full replacement race runs immediately and the LAN candidate wins. If instead the phone was already on Wi-Fi and the machine simply became visible on Bonjour, the discovery callback evaluates an .upgradeProbe: with a connection ≥10s old and ≥300s since the last roam, a quiet race restricted to strictly-better-class candidates runs. Either way the live relay socket keeps serving traffic until the LAN candidate has authenticated, and if the race fails the relay connection is untouched.

Tailscale switched off mid-session

• Before: ~5s to recover — the path change fired attemptAuthenticatedPathReplacement, which ran a full connectUsingProfile. This is the behaviour that had to be preserved.
• After: still an immediate full race. The interface set changed, so syncRoamTrigger returns .pathChange, which ignores the connection-age floor and uses the short 3s cooldown rather than the 300s upgrade interval. Failover speed is unchanged; what was removed is the other path, where an unchanged interface set also triggered a race.

Also fixed

A latent auth-gate leak: the slot-0 hoist synthesized an attempt from lastSuccessfulAddress without checking it against the vetted candidate set, so a relay URL could enter the race while signed out (the old code's transport filter happened to mask this in the direct plan but not the relay plan). Hoisting now only reorders candidates that address and relay-authorization policy already accepted.

Testing

SyncTransportSelectionTests (22) + SyncRecoveryPolicyTests (58) cover the ranking with failure memory, the single-race plan and relay offset, fingerprint memory hoisting, the token-based single-flight guard, the accepted-extends-deadline state machine, roam triggers/cooldowns, and profile decode back-compat.

Full iOS suite: 1049 tests. The only failures are the two pre-existing testDeepLinkRouter* cases, which reproduce identically on a clean main checkout and are unrelated to this branch.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
ade	Ignored		Jul 29, 2026 7:02pm

[coderabbitai]

Warning

Review limit reached

@arul28, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 12 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 22f8b8d4-0da4-4116-8f4d-517b0bc3ee11

📥 Commits

Reviewing files that changed from the base of the PR and between cd1bb24 and b8cac17.

⛔ Files ignored due to path filters (4)

• apps/ios/ADE.xcodeproj/project.pbxproj is excluded by !**/*.xcodeproj/project.pbxproj
• docs/ARCHITECTURE.md is excluded by !docs/**
• docs/features/sync-and-multi-device/README.md is excluded by !docs/**
• docs/features/sync-and-multi-device/ios-companion.md is excluded by !docs/**

📒 Files selected for processing (7)

• apps/ios/ADE/Models/RemoteModels.swift
• apps/ios/ADE/Services/SyncConnectionRace.swift
• apps/ios/ADE/Services/SyncRecoveryPolicy.swift
• apps/ios/ADE/Services/SyncService.swift
• apps/ios/ADETests/ADETests.swift
• apps/ios/ADETests/SyncRecoveryPolicyTests.swift
• apps/ios/ADETests/SyncTransportSelectionTests.swift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}