diff --git a/engdocs/design/bd-serve-v0.md b/engdocs/design/bd-serve-v0.md index 66584d184..de5551079 100644 --- a/engdocs/design/bd-serve-v0.md +++ b/engdocs/design/bd-serve-v0.md @@ -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 diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index a5981b360..7c5758539 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -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. // diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index e42fdbc5c..4c9d65298 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -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`