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

121 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.