Files
pipelines/app/notes/connection-recovery.md
T

6.7 KiB
Raw Blame History

Connection recovery: zero servers, independent sign-in, address choice

Three real failures from the first multi-machine delivery, and what changed.

Removing servers stranded the app

Removing a profile that was not the primary never activated anything, and removing the primary left no pipelines/runs machine, so the native app sat on "Server endpoint not configured" with no way out. Now:

  • ServerConnections(replaceRemovedPrimary: true) (native only) hands the primary role to the next saved machine when the primary is removed.
  • PipelinesRoot listens to the catalog: a native host with no saved machine left returns to the connect screen (Add server, discovery, saved list) however the last profile went away. Nothing is deleted; each machine's kept sign-in survives for when it is added again.
  • Browsers keep following their page origin; they never switch machines.

A new machine asks for its own password

MachineAuthenticator (core/servers/machine_access.dart) is implemented by ChatServerPool and handed to Settings through ServerConnections.authenticator.

  • Add server → Save now probes the machine (probe): connected, needs its password, or unreachable with the reason. A machine that needs its password gets a sign-in step in the same page (SavedServerSignInStep); "Later" keeps it saved. Editing only the name does not re-ask.
  • Each Settings row shows its live state: Connected, Sign in required (tap or the menu's "Sign in to X" opens the shared showMachineSignIn dialog) or Unreachable with the reason. Address lines read "Address" / "Backup address"; the footer says entries are separate machines with their own passwords and that addresses inside one entry are routes to that same machine.
  • Native: a socket that fails to open is classified by probing /login with that machine's own kept cookie (ServerSession.probeProfile): the form means it wants its password, a redirect means the sign-in is fine and the socket failed. Browsers get the relay's needs_password verdict directly (MachineSignInRequired). No other machine's credential is ever reused.

Unreachable addresses say why

ServerSession.probe returns ServerProbeResult(state, reason); probeServerAddresses and the connect screen show the reason instead of a generic "Could not reach that server":

  • TLS failure against an IP: Tailscale certificates only cover the tailnet name, so use wss://<name>.ts.net:<port>/connect or ws:// with the IP and the plain web port.
  • A 200 that is not the Pipelines sign-in page (another service on that port, for example :443 when the web app is on :8443): check the port.
  • Other statuses, refused connections and timeouts name the host and port.

Discovery offers every route

The server advertises its tailnet IPv4 addresses (ts=) and the installer's public HTTPS origin (public=, from PIPELINES_WEB_PUBLIC_URL) in TXT; browse returns addresses with kinds lan, tailscale, public. DiscoveredServer carries them; a discovered machine with several routes expands to a checklist (DiscoveredServerRow) and the checked routes are saved together as one machine, the first checked tried first. Onboarding saves them through saveMachine. Typing a different address drops the discovered routes.

Diagnosing from a terminal

dart run tool/connection_probe.dart [--sign-in] <address>... (from app/) runs the native login probe, the sign-in and the websocket exactly as the app does, printing each address's verdict and reason. The password is read from the web auth file and never printed.

Verification

  • Flutter: settings 158, onboarding 24, core/servers 49, core/session 18, zero-server recovery 2, sign-in 5, root/selection/chat destination 7: all pass under the watchdog. Analyzer clean. The full suite has 44 failures in test/application (pending LaunchUpdateChecker timer) that fail identically on untouched main c2d8d6d7; they are unrelated to this change.
  • Go: internal/discovery, internal/protocol, internal/server pass with the new route tests. internal/claude and internal/opencode fail on untouched main too (environment-dependent tests).
  • Node: web/test passes unchanged (the proxy forwards the discovery body).
  • Live, with the app's own native code (tool/connection_probe.dart): wss://alans-macbook-pro.tail6bf4dc.ts.net:8443/connect is the sign-in page, sign-in returns a cookie, the kept session is accepted and the websocket upgrades (101). wss://100.85.25.33:8443 fails TLS with the IP explanation; wss://alans-macbook-pro.tail6bf4dc.ts.net/connect (port 443) answers 502 from another service and is reported as not the Pipelines page. ws://100.85.25.33:8083, ws://10.0.0.75:8083, ws://100.97.159.92:8082 and ws://tank.tail6bf4dc.ts.net:8082 all show the sign-in page. ws://10.0.0.100:8082 (tank's LAN address as advertised over mDNS) times out from this Mac while tank's tailnet addresses work: tank itself appears to block LAN access to its web port, which the Tailscale route choice now works around.
  • Browser captures: see the capture section appended below.

Browser captures (real Chrome, capture kit, full-app fixture machines=1)

The fixture served the controlled discovery JSON at /api/discovery (tank with LAN, Tailscale IP and Tailscale name routes; the Mac with one) and a fixture authenticator (Mac connected, Linux desktop needing its password, new machines accepting fixture-pass). Inspected PNGs under /tmp/review/connection-recovery/:

  • material/01 Settings: "Alan’s Mac · Connected · Pipelines and runs server", "Linux desktop · Sign in required", footer explaining machines vs addresses.
  • material/04 Add server: tank expanded to "Local network", "Tailscale IP", "Tailscale name (HTTPS)" checkboxes with their addresses and "Use tank".
  • material/05 name and both chosen addresses prefilled, editable.
  • material/06 "Sign in to tank" step after Save with Password, Sign in, Later.
  • material/07 list with tank "Connected", Address + Backup address lines.
  • cupertino/02, cupertino/04 (dark, 560px): the same route checklist and a "Wrong password." retry in the sign-in step.
  • menu/02: the row menu's "Sign in to Linux desktop" opens the shared dialog.

Live after deployment (2026-11-09 00:25, server 49f36a94)

The restarted Mac server advertises ts=100.85.25.33 and public=https://alans-macbook-pro.tail6bf4dc.ts.net:8443; the authenticated /api/discovery lists the Mac with lan, tailscale and public routes. tank still runs 828227f5 and lists its LAN route only until it is upgraded. A proxied POST /files into a scratch home folder returned 200, then 409 on repeat, and 401 without a session. Published: APK 29903053, Linux 29903060, macOS 29903061.