fix(httpapi): make bd_version wire_revision inference advisory
Opus review of 12c5144ca (HIGH-3). The spec told a client inferring
wire_revision from bd_version to use the release cutoff >= 1.3.0, and said
nothing about what happens when that inference is wrong -- which it
demonstrably is for real builds already in the field:
- main builds up to commit b3ef65c85 report bd_version 1.2.2 (below any
1.3.0 cutoff) while already sending the string-typed revision/
expected_version shape (#6053).
- 1.3.0-rc.N pre-release builds sort BELOW the release cutoff 1.3.0 under
plain string comparison despite already carrying the string shape.
- The bd-enterprise compatibility line at d3ab32773462 reports bd_version
1.1.0 while also sending strings.
Moved the cutoff to >= 1.3.0-rc.1 (compared as semver-with-prerelease,
which at least captures the rc builds), documented both named exceptions
inline, and made the whole inference explicitly ADVISORY: a client must
accept revision/expected_version as either a string or a number whenever
wire_revision is absent (or probe directly) rather than let the inferred
value choose a decoder, and must never refuse solely because the inferred
revision is 0. Mirrored into engdocs/design/bd-serve-v0.md.
This is spec/doc prose only -- there is no server-side inference code to
change, since this server always sends wire_revision directly; the
inference is guidance for clients reading a pre-signal server's response
(this server, past builds, or an unrelated implementation).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
f9e1ceda52
commit
e8a4edbbdc
3 changed files with 66 additions and 11 deletions
|
|
@ -547,9 +547,19 @@ property's description in `openapi.v0.yaml` — `0` for every build before this
|
|||
field existed (an integer `revision`, pre-#6053), `1` for the brief
|
||||
string-typed `revision` (#6053), `2` for the first build carrying
|
||||
`wire_revision` itself. A client talking to a build too old to answer this
|
||||
field at all infers the value from `bd_version`, which is always present; the
|
||||
mapping is documented beside the property rather than assumed, because
|
||||
`bd_version` alone does not sort the same way a counter does.
|
||||
field at all may use `bd_version` as an ADVISORY hint, never proof: compare it
|
||||
as semver with pre-release identifiers and treat `>= 1.3.0-rc.1` (not the
|
||||
release cutoff `1.3.0` — a `1.3.0-rc.N` build already carries the string shape
|
||||
and sorts below `1.3.0`) as a hint toward `1`, else a hint toward `0`. Two
|
||||
known builds defeat even that corrected hint: `main` up to commit
|
||||
`b3ef65c85` reports `bd_version: "1.2.2"` while already sending strings, and
|
||||
the bd-enterprise compatibility line at `d3ab32773462` reports `"1.1.0"` while
|
||||
also sending strings. A client therefore MUST accept `revision` and
|
||||
`expected_version` as either a string or a number whenever `wire_revision` is
|
||||
absent (or probe the shape directly) rather than let the inferred value
|
||||
choose a decoder, and MUST NEVER refuse solely because the inferred revision
|
||||
is `0` — see the `wire_revision` property's description for the exact
|
||||
language.
|
||||
|
||||
`min_client_wire_revision` is the other half: the oldest revision a build
|
||||
still answers correctly. A client that knows the revision it was compiled
|
||||
|
|
|
|||
|
|
@ -1053,7 +1053,19 @@ type ContextResponse struct {
|
|||
// `wire_revision` and `min_client_wire_revision` at all (this one).
|
||||
//
|
||||
//
|
||||
// A client talking to a server that omits this member entirely is talking to a pre-signal server and INFERS the revision rather than reading one: `1` when `bd_version` is `>= 1.3.0`, else `0`. A client that does not know how to speak the revision it reads or infers must refuse to proceed rather than guess at the shape.
|
||||
// A client talking to a server that omits this member entirely is talking to a pre-signal server. `bd_version` is a HINT for that case, never proof: compare it as semver WITH PRE-RELEASE identifiers, and treat `>= 1.3.0-rc.1` — not the release cutoff `1.3.0` itself — as a hint toward `1`, anything below as a hint toward `0`. The release cutoff is wrong on its own because a `1.3.0-rc.N` pre-release build already carries the `1` shape and sorts BELOW `1.3.0`.
|
||||
//
|
||||
// Known exceptions make even that corrected hint unreliable, which is why it is advisory rather than authoritative:
|
||||
//
|
||||
// * Builds from `main` up to commit `b3ef65c85` report
|
||||
// `bd_version: "1.2.2"` — below the `1.3.0-rc.1` hint cutoff —
|
||||
// while already sending the string-typed shape (`1`, not `0`).
|
||||
// * The bd-enterprise compatibility line at commit `d3ab32773462`
|
||||
// reports `bd_version: "1.1.0"` while also sending the
|
||||
// string-typed shape.
|
||||
//
|
||||
//
|
||||
// Because builds like these exist, a client MUST NOT trust the inferred revision to pick a decoder. Instead it MUST do ONE of: accept `revision` and `expected_version` as EITHER a JSON string OR a JSON number whenever `wire_revision` is absent, or probe the actual shape directly (for instance by inspecting the JSON type of a `revision` value already in hand). A client MUST NEVER refuse a request solely because the inferred revision is `0` — `0` here means only "this is an unreliable hint," never a confirmed fact to gate decoding on by itself. A client that still cannot cope with either shape after probing must refuse to proceed rather than guess, exactly as it would for a `wire_revision` it read directly and does not understand.
|
||||
//
|
||||
// This document's own drift gate is `TestWireShapeDigest` (`internal/httpapi/wireshape`): a golden digest of every EXISTING response member's (schema, member, type, format, enum, required) fails CI the moment any one of them changes without this field's Go constant (`CurrentWireRevision`, `internal/httpapi/wire_revision.go`) increasing to match. Regenerate the golden with `go run ./internal/httpapi/wireshape/cmd/gendigest` after a deliberate, revision-bumped change, and commit the result — see that package's doc.go for the exact command. A purely additive member or operation also changes the golden (it is appended to, never frozen in place) but needs no revision bump to pass.
|
||||
//
|
||||
|
|
|
|||
|
|
@ -220,9 +220,13 @@ info:
|
|||
behavior: a non-additive change to an EXISTING member's type, meaning,
|
||||
presence or name bumps `wire_revision`; a brand-new member or operation
|
||||
does not. A client that reads no `wire_revision` at all is talking to a
|
||||
server that predates it and infers one from `bd_version` (`>= 1.3.0`
|
||||
means `1`, else `0`); see `ContextResponse.wire_revision` for the full
|
||||
table and the `Bd-Wire-Revision` request header.
|
||||
server that predates it and may use `bd_version` as an ADVISORY hint
|
||||
(`>= 1.3.0-rc.1` hints `1`, else hints `0`) — never as proof: see
|
||||
`ContextResponse.wire_revision` for the known builds where the hint is
|
||||
wrong, why a client must accept `revision`/`expected_version` as either
|
||||
a string or a number whenever `wire_revision` is absent, and why an
|
||||
inferred `0` must never by itself be grounds to refuse a request. See
|
||||
also the `Bd-Wire-Revision` request header.
|
||||
* Clients MUST default-branch on unknown `code` and `reason` values within
|
||||
a status class: both vocabularies grow additively, so an exhaustive
|
||||
switch breaks on the first addition.
|
||||
|
|
@ -7557,10 +7561,39 @@ components:
|
|||
|
||||
|
||||
A client talking to a server that omits this member entirely is
|
||||
talking to a pre-signal server and INFERS the revision rather than
|
||||
reading one: `1` when `bd_version` is `>= 1.3.0`, else `0`. A
|
||||
client that does not know how to speak the revision it reads or
|
||||
infers must refuse to proceed rather than guess at the shape.
|
||||
talking to a pre-signal server. `bd_version` is a HINT for that
|
||||
case, never proof: compare it as semver WITH PRE-RELEASE
|
||||
identifiers, and treat `>= 1.3.0-rc.1` — not the release cutoff
|
||||
`1.3.0` itself — as a hint toward `1`, anything below as a hint
|
||||
toward `0`. The release cutoff is wrong on its own because a
|
||||
`1.3.0-rc.N` pre-release build already carries the `1` shape and
|
||||
sorts BELOW `1.3.0`.
|
||||
|
||||
|
||||
Known exceptions make even that corrected hint unreliable, which
|
||||
is why it is advisory rather than authoritative:
|
||||
|
||||
|
||||
* Builds from `main` up to commit `b3ef65c85` report
|
||||
`bd_version: "1.2.2"` — below the `1.3.0-rc.1` hint cutoff —
|
||||
while already sending the string-typed shape (`1`, not `0`).
|
||||
* The bd-enterprise compatibility line at commit `d3ab32773462`
|
||||
reports `bd_version: "1.1.0"` while also sending the
|
||||
string-typed shape.
|
||||
|
||||
|
||||
Because builds like these exist, a client MUST NOT trust the
|
||||
inferred revision to pick a decoder. Instead it MUST do ONE of:
|
||||
accept `revision` and `expected_version` as EITHER a JSON string
|
||||
OR a JSON number whenever `wire_revision` is absent, or probe the
|
||||
actual shape directly (for instance by inspecting the JSON type of
|
||||
a `revision` value already in hand). A client MUST NEVER refuse a
|
||||
request solely because the inferred revision is `0` — `0` here
|
||||
means only "this is an unreliable hint," never a confirmed fact to
|
||||
gate decoding on by itself. A client that still cannot cope with
|
||||
either shape after probing must refuse to proceed rather than
|
||||
guess, exactly as it would for a `wire_revision` it read directly
|
||||
and does not understand.
|
||||
|
||||
|
||||
This document's own drift gate is `TestWireShapeDigest`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue