Repository navigation
Commit 958560c
feat(desktop): attach one local server as primary in client-only mode
## What Changed
Client-only desktop attaches one verified local server as primary (option B
from `#1349`). Main holds the attachment: env id plus endpoint plus pid and
start-time identity on every read, one bearer per attachment minted through
the bundled `t3 pair` command, drop to hosted-static on restart, port change,
or revocation. The renderer promotes exactly one `lifecycle: "attached"`
bootstrap to primary, takes the auth path against it, and retries once on 401
before surfacing hosted-static. A second 401 or a transport error drops the
attachment; a rejected WebSocket ticket invalidates the cached bearer. The
platform poll attaches a server started after launch. Folder and favicon
pickers stay available; the legacy local auto-pair stays off when the attach
bridge is present. Attach, re-verify and re-mint share one lock and a
generation guard, so parallel windows pair once and a racing detach wins. A
reject names the bearer that failed and is a no-op against a newer
attachment, and reports the bearer the failed request carried, never the
cache. A failed pair or a transport-error reject backs off auto-attach for
that server instance: 2s, doubling, capped at 60s, timed from the failure,
cleared on success or a restart. Only a 401 that survives a re-mint skips the
instance until it restarts. A saved connection for the same environment outranks the
attached primary: the platform entry is not registered, so dropping the
attachment never removes the saved one. Fork logic lives in `*.fork.ts` modules behind marked hooks.
## Why
`#1350` ships the `#1349` spike decision to production. Four commits:
contracts, desktop, client-runtime, web. Renderer holding the
bearer is parity with upstream managed mode; only the one-time pairing token
stays main-only and never crosses IPC.
## UI Changes
No new UI. Managed controls already hide in client-only mode because the
attached bearer carries standard scopes (no access-write).
## Checklist
- [x] This PR is small and focused
- [x] I explained what changed and why
- [ ] I included before/after screenshots for any UI changes
- [ ] I included a video for animation/interaction changes
## Close conditions
Quoted verbatim from #1350. Each box cites evidence;
unchecked boxes name the exact blocker.
Surface
- [x] Controls: attached hides restart, stop, update. `canManageLocalBackend`
is false: the attached bearer lacks the access-write scope. No
`ConnectionsSettings` change.
- [x] Picker: available in client-only mode — `pickFolder` and
`pickProjectFavicon` un-gate on `DesktopAttachedPrimary.isAttached`
(a live `current`, not an always-some `Option`).
- [x] Label: attached backend reads local — attached registers as
`PrimaryConnectionTarget`, whose transport label is "This machine"
(`EnvironmentRow.tsx:21`); unchanged code path.
- [x] Locality: never from localhost text — `isLocal` in
`pullRequestRouting.ts` returns the target tag; new fork test proves a
`lifecycle: "attached"` LAN-advertised URL promotes while a
`lifecycle: "managed"` loopback URL does not
(`attachSpike.fork.test.ts`, 7 passed).
- [x] Counts: zero, one, several servers tested — `DesktopAttachedPrimary`
rule (none/several stay detached) covered by 10 unit tests; resolver
covers the one-server bearer path (12 passed). A saved connection for the
same environment keeps its entry (`registry.fork.test.ts`, 2 passed).
Auth
- [x] Live auth: real pairing at standard scope — unit-mocked (`tokenResponse`
asserts standard scopes, 10 passed). Live: seeded `--home-dir` server, real Electron
`--backend-mode client-only`; bridge reports `lifecycle:"attached"`
([c1](https://github.com/user-attachments/assets/cc5573e5-9f55-40dd-b827-90ac7a08d4b8)).
- [x] HTTP and WebSocket: both accept the bearer — HTTP via
`withPrimaryBearerToken`; WebSocket via the shared `authorizeBearer` ticket
path the primary broker already uses (resolver test proves the bearer
reaches `authorizeBearer`). Live: `/api/orchestration/shell` and
`websocket-ticket` return 200 on the bearer; WebSocket upgrades 101.
- [x] Pairing token: stays in main — `mintBearerToken` runs in main;
`preload.ts` exposes only the bootstrap reads and the bearer getter, never
the pairing token; `tsc -p apps/desktop` clean.
Invalidation
- [x] Drop paths: each verified live — restart-away, port-move, revocation,
and same-port-restart (pid/start-time) covered by unit tests (10 passed).
Live: revoke gives exactly one 401, one retry 370ms later on a new bearer,
204. Server stop drops the attachment; server B re-attaches in about 2.4s on
a new bearer; the old bearer never reaches B ([down](https://github.com/user-attachments/assets/c1ed35f3-2407-4c8e-9cd6-8df5a1ba49ca),
[recovered](https://github.com/user-attachments/assets/7ba9fb34-8ae8-40b7-9cf9-bdb0c032b9cc)).
- [x] Dead endpoint: a transport error drops. The attached HTTP client calls
`rejectAttachedPrimary` on a transport error (`staleBearer.fork.test.ts`);
the healthy server re-attaches after the backoff, no restart needed
(desktop unit test).
Live: server stop gives one WebSocket close and one connection-refused, then
no retries during downtime.
- [x] Repeated 401: visible hosted-static. Retry once; a second 401 rejects;
managed mode never retries (`staleBearer.fork.test.ts`). A
server rejected on a 401 stays detached until it restarts; a
reject carrying an older bearer spares a restarted successor (desktop unit
test). A late transport error reports the bearer it sent, not one a
concurrent 401 refilled (`staleBearer.fork.test.ts`, 6 passed).
- [x] Late start: later server attaches. The platform poll calls
`refreshOrAttach`, which attaches from empty (desktop unit test).
Live: Electron starts with no server and stays hosted-static
([before](https://github.com/user-attachments/assets/601451eb-b4aa-4c59-a901-be5e3419ad85)); the server starts and attaches about 4.5s later, no
restart ([after](https://github.com/user-attachments/assets/cc5573e5-9f55-40dd-b827-90ac7a08d4b8)).
- [x] Concurrency: parallel requests and windows. Attach, re-verify and
re-mint run under one lock with a generation check; parallel reads mint
once, parallel attaches pair once, a racing detach wins. The pair and mint
are gated on a Deferred, and both parallel tests fail with the lock removed
(desktop unit tests, 18 passed).
Live parallel and multi-window load not driven; unit-covered only.
Lifecycle
- [x] Quit: attached server keeps running — Live: the server keeps serving
after Electron quits.
- [x] Managed mode: unchanged — all changes branch on client-only or
attached lifecycle; managed resolvers untouched; neighbor suites pass.
- [x] Real Electron: client-only run grounded — Live at head `55a63ffe04`,
before the lock, precedence and backoff fixes at `8d3340580e`:
attach, late start, revoke, restart, quit, and picker all pass. `pickFolder`
opens the native dialog while attached (with `localEnvironmentEnabled` true,
so the `isAttached` gate was not the deciding check). Repeated 401 not
driven live.
## Fork trailers
Squashes:
- 7388ccb feat(desktop): attach one local server as primary in client-only mode
- aae3c86 fixup! feat(desktop): attach one local server as primary in client-only mode
Fork-Domain: backend-attach
Fork-Tier: core
Fork-Upstreamable: no1 parent d3c875f commit 958560c
33 files changed
Lines changed: 2295 additions & 8 deletions
File tree
- apps
- desktop/src
- app
- ipc
- methods
- web/src
- components/settings
- connection
- environments/primary
- routes
- packages
- client-runtime/src
- connection
- platform
- contracts/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| 32 | + | |
32 | 33 | | |
33 | 34 | | |
34 | 35 | | |
| |||
247 | 248 | | |
248 | 249 | | |
249 | 250 | | |
| 251 | + | |
250 | 252 | | |
251 | 253 | | |
252 | 254 | | |
| |||
0 commit comments