mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
05a1d76f2e
* test: gate daemon RPC wire compatibility against the last released tag (#1432) ADR 0006 fixes exactly when DAEMON_RPC_PROTOCOL_VERSION must be bumped, and nothing checked that it was. The runtime guard (readRemoteDaemonHealth) refuses a mismatched peer, but only fires when someone remembered the bump — a wire change that skipped it left both sides advertising protocol 2 while parsing different payloads, which is the failure ADR 0006 exists to prevent. Local daemons cannot skew (isReusableDaemonInfo takes over on any package version mismatch). Cross-machine is skewed by design — proxy, cloud/limrun, a remote macOS host — and ADR 0006 explicitly rules package version out as the compatibility gate there, so the one boundary where skew is intended was the one boundary with no gate. test/wire-compat/surface.ts declares the wire surface grouped by the ADR bullet each group serves, quoting it, with an `uncovered` note where a bullet is only partly digestible (the /health and /rpc literals inside http-server.ts stay reviewer-owned: a moved route 404s at connect time rather than misparsing). ledger.json records what each declaration hashes to, at which protocol version. Two gates, split for the same reason the replay-compat corpus splits: - unit-core holds the ledger to its source and prints the digest to paste; - Released-Surface Compatibility reads the ledger at the last RELEASED tag and requires the drift since then to carry a bump or a compatibleChanges ack. From one commit a bumped ledger and an unbumped one are both just an edited file, so only a released baseline can tell them apart. Acks are keyed by the digest they cover, so one "added an optional field" cannot launder later changes. Digests ignore comments and formatting; the manifest's closure is derived from the AST, so a field typed by an unlisted sibling fails rather than sitting outside the gate. CI cost: one added job (checkout + toolchain + two node scripts, ~1 min), mirroring the existing full-history replay-compat job. * test: close wire-surface overclaim and make the closure fail closed (#1432) Addresses both review P1s on #1717. P1 — the manifest materially overclaimed ADR 0006 coverage. It quoted all four bullets while digesting only the payload TYPES, so the producer and consumer seams could break a skewed peer without moving a listed digest. Now listed on both sides of every boundary: JSON-RPC method sets and the projections that turn each method's params into a DaemonRequest, createRpcError/sendJson/ writeRpcResponseEnvelope, resolveToken and the auth-hook types, upload preflight/finalize/308 handlers and the resumable ticket shape, artifact route and download/inventory framing, REST error mapping, and the client's own payload builder, lease-method mapping, response parser and error projection. 57 -> 117 declarations. What stays out is now named rather than implied: createDaemonHttpServer's dispatch wiring and the /health and /rpc literals inside it. Everything it dispatches WITH is digested individually, and a moved route 404s at connect time rather than misparsing — the loud failure, not the silent one. P1 — imported and re-exported payload shapes escaped the closure. declarationHomes() scanned only the manifest's own files and the walk continued silently when a name could not be placed, so a listed type could gain foo?: ImportedShape from a new module and stay green. Resolution is now explicit and fails closed: relative imports, workspace specifiers (through the owning package's own exports map, so a re-pointed export cannot drop a type), and facade re-export chains. Every referenced name must land on a listed declaration, a waiver with a written reason, a declared external module, or the TS/Node global set. Fixed two extractor blind spots the walk exposed: a declaration's own generic parameters and `as const` were being reported as references. Planted-red proofs (wire-mutations.test.ts): 13 cases independently mutate method naming, response serialization, response parsing, auth projection, upload ticket shape, 308 framing, artifact framing, REST error mapping, and progress framing, each asserting the digest moves; 3 probes prove the closure really reaches across a package boundary, a facade re-export, and a plain relative import. Mutations apply inside the declaration's own span — a whole-file replace silently hit a sibling sharing the substring, which is how the first draft of one case passed vacuously. The largest waiver pair (InternalRequestOptions, CommandFlags) rests on ADR 0006's own additive rule: they reach the peer inside DaemonRequest's untyped flags/input bags, and the decision says a new flag needs no bump. Digesting them would fire the gate on every new CLI flag and train reviewers to rubber-stamp acks. * test: list the consumer half of the auxiliary HTTP boundaries (#1432) Addresses the remaining review P1 on #1717. The manifest claimed both sides of response/upload/artifact framing while listing nothing from upload-client.ts, daemon-artifacts.ts, or the health consumer in daemon-client-transport.ts, so those parsers could narrow without moving a listed digest or protocol 2. Now listed (117 -> 141 declarations): - /health consumer: RemoteDaemonHealth, readHealthPayload, readDaemonHttpHealth, readRemoteDaemonHealth. This is the sharpest of the three — narrowing the reader or the comparison disables the very refusal ADR 0006 exists to guarantee, and nothing else in the repo would notice. - /upload consumer: UploadResponse, UploadPreflightResponse, UploadPreflightResult, parseUploadPreflightResult, requestUploadPreflight, uploadDirectArtifact, tryDirectUploadWithResume, shouldRetryDirectUpload, finalizeDirectUpload, uploadLegacyArtifact, ARTIFACT_HASH_ALGORITHM, isStringRecord, and PreparedUploadArtifact — whose sha256/sizeBytes/fileName/artifactType/ contentType fields ARE the preflight body the daemon parses. - /artifacts/* consumer: DaemonArtifactEndpoint, buildDaemonArtifactUrl, isRemoteDaemon, DownloadRemoteArtifactParams, downloadRemoteArtifact, materializeRemoteArtifacts, resolveMaterializedArtifactPath. Running the closure fail-closed over the new files surfaced three more stops, each decided rather than skipped: PreparedUploadArtifact listed (it is payload), UploadProgressSink waived (client-local rendering, never leaves the process), and src/daemon/types.ts#DaemonArtifact waived as a re-export alias of the listed kernel type, matching its DaemonRequest/DaemonResponse siblings. 10 more planted-red mutations cover the new seams: health version-read and mismatch-refusal defeated, RemoteDaemonHealth field dropped, preflight parser narrowed, preflight/legacy response shapes narrowed, finalize body key renamed, ticket field renamed, artifact tenant header dropped, artifact URL moved. A fourth closure probe proves the upload-consumer files are genuinely reached by the walk rather than merely listed. 22 -> 33 tests. The README now states the coverage as a producer/consumer table per boundary, so the claim is checkable at a glance instead of asserted in prose. * test: list the client half of the resumable 308 contract (#1432) Addresses the third review P1 on #1717. Listing the daemon's handleResumableUpload proved it still PRODUCES 308; nothing proved the client still CONSUMES the released one. src/remote/upload-stream.ts owns that half and was entirely outside the manifest, so a newer client could stop accepting `upload-offset`, change how it reads `Range: bytes=0-N`, or emit a different resumed `Content-Range` without moving one of the 141 listed digests. Now listed (141 -> 151): UploadStreamResponse, streamFileToHttpRequest, streamFileToHttpRequestAttempt, buildUploadRequestHeaders, isUploadResumeStatus, isUploadRedirectStatus, parseUploadResumeOffset, parseNonNegativeIntegerHeader, firstHeaderValue, MAX_UPLOAD_REDIRECTS. streamFileToHttpRequestAttempt is listed despite its size, unlike createDaemonHttpServer which stays in `uncovered`. The distinction is stated at the declaration: the HTTP server only dispatches to handlers that are each digested, while the attempt loop IS the resume state machine — it decides whether a 308 continues the upload and what the next request carries, so its sequencing alone can break a released daemon while every helper keeps its digest. 6 new planted-red mutations prove the client half moves the ledger: a dropped `upload-offset` fallback, narrowed Range parsing, a changed resumed Content-Range, 308 no longer treated as continue, a narrowed UploadStreamResponse, and dropped header-value coercion. 33 -> 39 tests. Closure fail-closed surfaced two more stops: UploadStreamProgressOptions waived (local byte-progress rendering) and URL/URLSearchParams added to the global set. README now carries a `/upload` resume row in the producer/consumer table, and names the pattern behind three rounds of review: the coverage sentence kept getting written ahead of the coverage, so the table and the `uncovered` notes are the claims to trust — they are checkable against surface.ts, prose is not. --------- Co-authored-by: Claude <noreply@anthropic.com>
76 lines
3.9 KiB
Markdown
76 lines
3.9 KiB
Markdown
# ADR 0006: Daemon RPC Protocol Version
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
`agent-device` can run a client on one machine and reach a daemon on another machine through the
|
|
HTTP JSON-RPC transport, including `agent-device proxy` in front of a local macOS daemon. Client and
|
|
remote host package versions can differ. Many version skews are safe because the client sends a
|
|
stable command request envelope and the daemon executes only the requested command.
|
|
|
|
Package semver is too strict for this boundary: a 0.15 client and 0.17 remote daemon can often
|
|
interoperate. At the same time, the client needs a cheap way to fail before sending command RPC when
|
|
the transport protocol itself is no longer compatible.
|
|
|
|
## Decision
|
|
|
|
The daemon HTTP `/health` payload advertises a `rpcProtocolVersion` integer alongside service and
|
|
package version metadata. Remote clients compare this value before sending JSON-RPC requests.
|
|
|
|
Package `version` is diagnostic only and must not be used as a compatibility gate. Missing
|
|
`rpcProtocolVersion` is treated as a legacy remote daemon and is allowed unless a later security or
|
|
protocol decision explicitly retires legacy compatibility.
|
|
|
|
`rpcProtocolVersion` changes only when an older client and newer daemon, or newer client and older
|
|
daemon, cannot safely communicate over the HTTP RPC boundary for existing commands. Bump it for
|
|
breaking changes to:
|
|
|
|
- HTTP route requirements for `/health`, `/rpc`, `/upload`, or `/artifacts/*`.
|
|
- Authentication semantics required to authorize RPC, upload, or artifact requests.
|
|
- JSON-RPC envelope shape, method naming, request id handling, or command request projection.
|
|
- Response, error, artifact, upload, or progress-stream framing that existing clients parse.
|
|
- Existing command request or response contracts when the old side would misinterpret the payload
|
|
rather than fail clearly.
|
|
|
|
Do not bump it for additive changes:
|
|
|
|
- New commands.
|
|
- New optional request fields or flags that older daemons can ignore or reject with a normal
|
|
command error.
|
|
- New optional response fields that older clients can ignore.
|
|
- Package version changes, refactors, or implementation-only daemon/proxy changes.
|
|
|
|
When a single command needs finer-grained compatibility in the future, prefer command-level feature
|
|
or capability metadata over bumping the whole RPC protocol, unless the shared transport contract is
|
|
also affected.
|
|
|
|
## Alternatives Considered
|
|
|
|
- Gate by package version: simple, but rejects compatible version skew and makes proxy usage brittle
|
|
across frequent releases.
|
|
- Do not check compatibility: maximizes compatibility but fails later, after the client has sent an
|
|
RPC payload that a remote daemon may parse incorrectly.
|
|
- Full schema negotiation: more precise, but too much machinery for the current JSON-RPC boundary.
|
|
|
|
## Consequences
|
|
|
|
Protocol-breaking changes must update `DAEMON_RPC_PROTOCOL_VERSION`, tests that assert `/health`
|
|
metadata, and at least one remote-client regression test that proves mismatched protocols fail before
|
|
command RPC.
|
|
|
|
The bump rules above are enforced rather than remembered (#1432). `test/wire-compat/surface.ts`
|
|
declares the wire surface grouped by the bullets in this decision, and `test/wire-compat/ledger.json`
|
|
records what each declaration hashes to and at which protocol version. The unit lane fails when a
|
|
declaration's shape moves without the ledger following, and `pnpm check:daemon-wire-compat` compares
|
|
the ledger against the last released tag: drift since that release must carry either a bump or a
|
|
`compatibleChanges` acknowledgment invoking the additive list above. Where a bullet is only partly
|
|
digestible — the `/health` and `/rpc` path literals inside `http-server.ts` — the manifest records
|
|
the gap and its reason instead of implying coverage. See `test/wire-compat/README.md`.
|
|
|
|
Legacy remote daemons without `rpcProtocolVersion` remain reachable. This keeps the first release of
|
|
the proxy compatible with older HTTP daemons, but it means absence of the marker is not proof of
|
|
compatibility.
|