Repository navigation
Document the desktop orchestrator's shell contract - #1686
phantomic12 wants to merge 3 commits into
Conversation
A desktop shell has to start the orchestrator, keep it alive and talk to it, and none of that boundary is written down anywhere public: the boot phase names, the readiness budgets, the stdin bootstrap line, the HMAC lifetime socket and the x-freebuff-launch-id gate on /api/* are all re-derived by reading a shipped install. This documents the boundary as observed from one, so a client, a test harness or a native shell can drive the same server. No user data, no server code.
|
The instinct here is good — a written contract for the shell↔orchestrator boundary (phases, timeouts, stdin bootstrap, HMAC lifetime socket, The problem is provenance. This is stated to be "recovered from a shipped install," but the PR gives no pointer to how each claim was derived — no reference to specific binary strings, no version/build it was checked against, no indication of what happens if the orchestrator changes behavior across releases. The level of precision (exactly nine phase names, 30s/60s budgets, 3s ping / 10s tolerance, the exact JSON shape of the bootstrap line, exit code 75) is the kind of detail that's either exactly right or subtly wrong in a way a maintainer can't check by reading this diff alone — there's no source reference, no test, and no versioning note ("as of build X"). Baking unverified specifics into a permanent doc is worse than no doc if any of it is stale or mis-observed. Separately: the companion issue (#1685) is explicitly framed as "should a native shell exist," and this PR ships 100 lines treating that shell's exact protocol as settled fact ahead of that discussion. That's a minor sequencing issue, not a blocker, but it means this doc is coupled to a product direction that hasn't been decided. Before this is portable: add a note on what build/version this was checked against, and ideally point to the specific observed artifacts (strings in the binary, captured traffic, etc.) so a maintainer can spot-check the nine phase names and the two timeouts against the real source quickly rather than having to re-derive the whole thing themselves. |
The review asked for provenance: which build this was checked against, and what to grep to spot-check a claim without re-deriving it. Adds the desktop version (0.0.203), the SHA-256 of each artifact read, and a table of the literal behind every constant in the document; the bundle keeps its source paths, so src/server/boot-phase.ts and src/server/services/orchestrator-lock.ts are named as the places to look. Also states the staleness risk plainly: no handshake carries a protocol version, so a build that renames a phase or moves a budget breaks a client silently. The shape is what to rely on; the constants are what to re-read per release. And scopes the page away from the direction question in the companion issue -- a harness or a diagnostics client needs these facts regardless.
|
Fair on both counts. Pushed a provenance section ( Build and artifacts. Written against installed Freebuff Desktop Per-claim pointers. A table maps every constant to a file and line and quotes the literal, so the spot-check is mechanical rather than a re-derivation:
The bundle still carries its source paths, which is the better pointer for your side: the phase list is Nothing needs a build to check. Two greps, both in the doc: npx @electron/asar extract "<install>/resources/app.asar" app
grep -n "READY_LINE_BUDGET_MS\|HEALTH_BUDGET_MS" app/electron/orchestrator-startup.cjs
grep -n "PROFILE_BUSY_EXIT\|invalid launch id\|LAUNCH_TOKEN_HEADER" \
"<install>/resources/orchestrator/orchestrator.js"On staleness. I agree these are exactly the details that are either right or subtly wrong, so the doc now says out loud that nothing is negotiated — no handshake carries a protocol version, so a build that renames a phase or moves a budget breaks a client silently. It separates the durable shape (phase line on stdout, ready line with a launch id, stdin bootstrap, HMAC lifetime socket, launch-id header) from the constants that should be re-read per release, and it states that where the page disagrees with a newer build, the build wins. If you would rather not carry versioned specifics in a permanent doc at all, the alternative is to cut the constants and keep only the shape — say so and I will trim it; I kept them because a harness that does not know the budgets cannot fail a slow boot. On sequencing, taken: the page no longer leans on the native-shell question. The new |
… from An update landed while this page was under review: orchestrator.js moved from 6a34e09a2722c87b to c0267ead585538d3 (the shell's app.asar hash did not change). Re-read every literal against the newer bundle -- the phases, both budgets, the launch-id header, PROFILE_BUSY_EXIT = 75 and its stderr line are all still there, unchanged -- so the page still describes the current build, and the hash pair records that it was checked rather than assumed.
|
One thing to flag on the provenance table, since it is the part you asked about: the orchestrator That is also the argument for the "across versions" paragraph at the bottom of the page: the |
What this changes
Adds
docs/desktop-shell-contract.md: the boundary between the desktop shell and theorchestrator it starts, written down once instead of re-derived per client.
It covers:
127.0.0.1, cwd, stdout as the progress channel);60 s ready →
/healthz);killed shell takes its server down instead of orphaning it;
x-freebuff-launch-id(orfreebuff_launch_<port>cookie) gate that answers401 unauthorizedon every/api/*path;with exit 75.
Why
Everything above is observable from a shipped install but undocumented, and the observations are
easy to get subtly wrong — the phase whitelist, the two different timeouts, and the fact that the
launch id travels on stdin rather than in the environment are all things a second implementer
would otherwise rediscover by trial and error. This is the documentation half of an experiment
that replaced the shell with a native UI; the shell code is not part of this PR, and the issue
linked below asks whether it should be.
No product behaviour changes: documentation only. It touches no path outside
docs/.Companion issue: #1685 (area: Desktop app). A native shell is a direction question, not a docs
question, so it is asked there rather than shipped here — if the answer is "not the direction",
this page is still true and still useful.
The experiment itself — a reference implementation of this contract in Rust on Rune, with the
same panes, tokens and geometry — is public at https://github.com/phantomic12/freebuff-rune,
so the claims above can be checked against running code rather than prose.