feat(httpapi): wire-shape signal — wire_revision, client floor, golden shape digest, param tokens (#7182)
* feat(httpapi): wire-shape signal — wire_revision, floor header, golden digest, param tokens
S0 of the HTTP role-parity program: give a client a single place to learn
whether this build's wire shape has moved under it, and give CI a gate that
catches an undocumented move.
- GET /v0/beads/context reports wire_revision (bumps only on a non-additive
response-shape change) and min_client_wire_revision. An optional
Bd-Wire-Revision request header lets a client declare the revision it was
built for; checkWireRevision refuses a declared revision below the floor
with 400 invalid_argument/reason=wire_revision_unsupported and a
min_wire_revision field, on every route but /healthz (wireRevisionExempt) —
including the identity handshake, where catching the mismatch is cheapest.
Absent header is today's behavior; malformed value is invalid_value, never
wire_revision_unsupported. The floor lives in Server.minClientWireRevision
(defaulting to the MinClientWireRevision constant) so a test can raise it.
- internal/httpapi/wireshape: a golden digest over every response's every
content-type schema (including application/problem+json) across the whole
spec, keyed by schema+member. TestWireShapeDigest fails closed when a
member's JSON name or type changes without wire_revision bumping to match;
regenerate with `go run ./internal/httpapi/wireshape/cmd/gendigest`.
- GET /v0/beads/issues' `sort` parameter now carries the issues.listSort
capability token, the same convention `capabilities` entries use.
TestNewParameterOnExistingOperationHasABehaviorToken requires every new
parameter on an existing operation to carry one, checked against a
write-once grandfather baseline (testdata/pretoken_parameters.json) of
parameters that predate the rule; TestUntokenedParameterRuleFires proves
the checker itself against a synthetic fixture.
- Docs: engdocs/design/bd-serve-v0.md gets a "The wire-shape signal" section;
CHANGELOG.md gets an Added entry.
Live-mutated and reverted three RED demonstrations during development:
retyping api_version in the spec failed TestWireShapeDigest; short-circuiting
checkWireRevision's floor comparison failed
TestWireRevisionBelowFloorRefusesEveryEnforcedRoute; adding an untokened
query parameter to listIssues failed
TestNewParameterOnExistingOperationHasABehaviorToken. All three now pass
against the unmutated tree.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): rename issues.listSort to issues.list.sort, harden token rule
Opus review of 12c5144ca (HIGH-1, MEDIUM-5):
- Rename the capability token issues.listSort -> issues.list.sort to match
bd-enterprise's client (httpstore/wire/handshake.go:121, DESIGN.txt S4e),
and widen capabilityToken to accept an optional third segment.
- untokenedParameters() now requires the extracted token to be one
Capabilities() actually serves, not just backtick-shaped text. This
catches real false positives that existed in the spec already
(workapi.DefaultReadyLimit, status.custom) which only shape-matched the
old regex; they're added to the pretoken baseline as genuinely
pre-existing untokened parameters.
- Extend the rule to request body members (new
testdata/pretoken_request_body_members.json baseline) and exempt
brand-new operations via a frozen testdata/pretoken_operations.json
snapshot.
- Add TestPretokenBaselinesNeverGrow pinning all three baseline sizes so
a future change can't hand-add an exemption instead of a token.
- Update spec prose for the widened rule scope.
go test ./internal/httpapi/... and the reviewer's pmut.py all pass as
expected: plain/bogus modes go RED, reuse (real-but-unrelated token) stays
green, matching the review's literal ask ("a token must be one advertised
by Capabilities()").
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): close four digest-coverage gaps, add gendigest write guard
Opus review of 12c5144ca (HIGH-2, MEDIUM-4). The digest only tracked
Type/Format/Enum/Required on direct properties, missing:
- nullable: true (never read at all)
- array item shape (Issue.labels items string->integer was invisible;
only object-shaped items got recursed into)
- additionalProperties value shape (IssueCount.groups)
- request bodies entirely (Compute() only walked responses, so
DeleteIssuesRequest.expected_version string->integer, the other half
of #6053, was invisible)
Also added defensive oneOf flattening alongside the existing allOf merge
(dormant today -- grep confirms this spec uses oneOf nowhere -- but no
longer silently invisible if that changes).
Extracted the golden-vs-computed comparison into wireshape.Compare(),
shared by TestWireShapeDigest and the new wireshape.SafeToWrite(), which
gendigest now calls before writing: it refuses to overwrite golden.json
with changed/removed entries unless the candidate's wire_revision is
strictly greater than the existing golden's. Pure additions always write.
TestSafeToWrite exercises both guard directions.
golden.json is regenerated. This single regen is a one-time exception to
the new guard, done by writing the digest directly rather than through
gendigest: confirmed via a throwaway diff (not checked in) that every one
of the 57 "changed" entries differs only in the NEW fields the wider walk
now populates (ItemType/ItemFormat/Nullable/AdditionalProps*) -- every
pre-existing Type/Format/Required/Enum value is byte-identical. Nothing on
the wire changed; the measurement got more precise. Bumping
CurrentWireRevision for this would have written a false "the protocol
changed here" entry into the revision history table. Going forward, any
REAL change the guard now reports uses the normal bump-then-regenerate
path, same as before.
Verified against the reviewer's mut.py: nested_type, nullable,
nullable_issue, array_items, addlprops, request_body and format all go RED
on TestWireShapeDigest, each reverted after confirming.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* 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>
* fix(httpapi): LOW-7/8/9/10 review follow-ups for wire-revision signal
LOW-7: WireRevisionUnsupported now also sets Problem.wire_revision (this
server's CurrentWireRevision) and Problem.bd_version on the
wire_revision_unsupported refusal, alongside the existing
min_wire_revision, so a client logging the refusal has this server's
full self-description without a second /v0/beads/context call.
LOW-8: gazelle + make bazel-sync add the BUILD.bazel entries the prior
commits were missing: wire_revision.go/wire_revision_test.go in
internal/httpapi's srcs, new BUILD.bazel files for wireshape and
wireshape/cmd/gendigest, and a testdata glob on httpapi's go_test so
the pretoken_*.json baselines are visible under `bazel test`. Verified
with `bazel build //internal/httpapi/...` and
`bazel test //internal/httpapi/... --test_env=BEADS_TEST_SKIP=dolt`
(both green) and `python3 tools/bazel/go_srcs.py --check` (clean).
LOW-9: narrowed CHANGELOG.md and engdocs/design/bd-serve-v0.md to
describe the digest's actual final coverage (format/enum/required/
nullable, array items, additionalProperties, request bodies, $ref/
allOf/oneOf recursion, the SafeToWrite revision-bump guard) and the
token rule's actual final shape (three pinned baselines, request-body
members, Capabilities()-membership validation, new-operation
exemption) instead of the original, narrower claims.
LOW-10: Bd-Wire-Revision now parses via a strict decimal-only
parseStrictNonNegativeInt (no leading '+', no leading zero except a
bare "0") instead of strconv.Atoi alone, so two different header
bytes can no longer name the same revision. New malformed-header test
cases: "+1", "01", "007".
Regenerated apigen/types.gen.go (make api-gen) for the new Problem
fields and wireshape/testdata/golden.json (go run
.../wireshape/cmd/gendigest) for the two new additive Problem members;
the latter wrote cleanly through SafeToWrite itself, since both are
pure additions.
go test ./... and bazel test //internal/httpapi/... both green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): re-review LOW follow-ups — retirement test, gendigest -init, docs
1. TestRetiredRevisionsStayBelowTheFloor pins the PRESENCE guarantee the
wire_revision property doc relies on: CurrentWireRevision >= 2 (so 0
and 1 stay permanently retired) and MinClientWireRevision <=
CurrentWireRevision (so this build's own floor never refuses every
request against itself).
2. gendigest now refuses to create a golden.json that does not exist yet
unless run with -init. Previously a missing file (moved testdata,
wrong path, accidental delete) was indistinguishable from a real first
run and silently wrote a fresh golden with no revision history checked
against anything. writeGolden() is extracted out of main() so this is
covered directly: TestWriteGoldenRequiresInitWhenMissing,
TestWriteGoldenInitCreatesWhenMissing,
TestWriteGoldenIgnoresInitWhenGoldenExists (the existing-golden path is
still governed only by SafeToWrite, -init or not).
3. Narrowed the two remaining stale claims that still described the
digest's original, narrower coverage: the wire_revision property's
prose in openapi.v0.yaml (regenerated into apigen/types.gen.go via
make api-gen) and wireshape/doc.go now both list nullable, array item
shape, additionalProperties value shape, request bodies, and
$ref/allOf/oneOf recursion, plus the new -init guard.
go test ./internal/httpapi/... and make api-check both green;
bazel test //internal/httpapi/... (httpapi, wireshape, and the new
gendigest test target) green; python3 tools/bazel/go_srcs.py --check
clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(wireshape): cover operation parameters in the wire-shape digest
The digest previously walked only response and request-body schemas, so a
type, enum, required, or removal change on one of the spec's 138 operation
parameters (123 query, 14 path, 1 header) passed the gate silently — the
open item from PR review on #7182.
Each parameter is now recorded as its own Entry, keyed by
"param:"+operationId / location+":"+name (operation-scoped, not
schema-scoped, since two operations' same-named parameter are independent
wire contracts), capturing type, array item shape, enum, required, style,
explode and default. Adding a parameter stays additive; removing,
retyping, narrowing its enum, or changing required/style/explode/default
now trips SafeToWrite exactly like a response or request-body change.
Verified against the live spec: retyping listIssues' `limit` query
parameter from integer to string now fails TestWireShapeDigest (confirmed
red, then reverted — not part of this commit). golden.json regenerated via
gendigest; the new parameter entries are a pure addition, no wire_revision
bump needed. Added TestParameterMutationsAreCaught (remove/retype/narrow-
enum against real golden entries) and updated wireshape's doc.go, the
`wire_revision` spec prose, and the CHANGELOG to describe the new
coverage.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): review fixes — stale-golden and lowered-revision arms, effective param serialization, digest boundary
Maintainer fixup from the adopt-pr review loop (iterations 1 and 2), on
top of e17ba924f.
- goldenDrift (A, I): TestWireShapeDigest's comparison moves into a
goldenDrift helper. An addition alongside a moved wire_revision no
longer passes with a stale golden: it asks for a regenerate, as a
changed or removed entry after a bump already did. Every message now
names response/request-body members AND parameters, and TestGoldenDrift
pins each arm. This takes only the test half of the stranded fixup
(adopt-pr/bd-47kdge/stranded-fixup-528cd6095); its doc half, which says
parameters are outside the digest, is false since e17ba924f and is not
replayed (J).
- Lowered wire_revision (D): a CurrentWireRevision LOWER than the
golden's is a wrong constant, not a stale golden, so goldenDrift says to
restore it instead of regenerating, and SafeToWrite (so gendigest)
refuses any write at a lower revision, whatever the entries.
- Effective style/explode (B): walkParam records style and explode with
OpenAPI 3.0's defaults filled in (form for query/cookie, simple for
path/header; explode defaults to style == form). Adding `explode: false`
to a query array that relied on form's implicit explode is now a
changed entry, while spelling out a default changes nothing.
testdata/golden.json is regenerated with -init: 111 parameter entries
change only in style/explode (96 to form/true, 15 to simple), 828
entries before and after, wire_revision stays 2. The golden is new in
this PR and unreleased, so this needs no bump.
- TestWalkParam (H): a package-internal table test
(wireshape_internal_test.go) pins every field walkParam extracts,
through a computeFrom(document, revision) seam that Compute now wraps:
per-location defaults, $ref'd parameters and items, format, nullable and
default, content parameters, and the nil returns.
TestEffectiveSerializationIsCompared pins B end to end through Compare
and SafeToWrite. BUILD.bazel embeds the library in the go_test, which is
gazelle's own output.
- Required inputs and the digest boundary (C, E, F; docs only): all five
prose surfaces (openapi.v0.yaml's wire_revision description and the
regenerated apigen/types.gen.go, wireshape/doc.go, CHANGELOG.md,
engdocs/design/bd-serve-v0.md) now say that a new REQUIRED request
input is recorded as an ordinary addition and needs its own review,
that value constraints and member-level composition are outside the
digest, and that object and content parameters are recorded only as
their container. bd-serve-v0.md also gains the parameter coverage it
was missing.
- G: a brand-new operation is permanently exempt from the
capability-token rule; its own review decides its capability story.
- Iteration 2 (nit): walkParam's comment now says that the location
default it records as a `content` parameter's style and explode is a
placeholder, since OpenAPI 3.0 applies style and explode only to a
parameter described by `schema`. All 138 operation parameters in the
spec use `schema`, so the golden does not change.
Validated: go test ./internal/httpapi/... (gms_pure_go), make api-check,
go vet for linux/windows/darwin, gofmt, git diff --check, gazelle on the
package (no drift), make bazel-sync-check, and bazel test
//internal/httpapi/wireshape/... in the local processwrapper sandbox
(2 of 2 pass). Overlay mutation probes: dropping the added-after-bump
arm, the lowered-revision arm, SafeToWrite's lowered check, or the
effective-default fill each turns the new tests red.
Iteration 2 changes only that comment; go test
./internal/httpapi/wireshape/... (gms_pure_go), go vet, gofmt and git
diff --check pass again.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
516e0b4bf0
commit
5439be97ba
25 changed files with 8689 additions and 36 deletions
48
CHANGELOG.md
48
CHANGELOG.md
|
|
@ -24,6 +24,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
recognizes a registered remote backend (`backends.IsRemote`) before any
|
||||
Dolt-mode check, so a remote-backend workspace is never misclassified as
|
||||
having a local Dolt root to gate.
|
||||
- `bd serve`'s `GET /v0/beads/context` now reports `wire_revision` (the
|
||||
non-additive wire-shape counter for this build) and
|
||||
`min_client_wire_revision` (the oldest revision this build still answers
|
||||
correctly). A client may declare the revision it was built for on any
|
||||
request via the optional `Bd-Wire-Revision` header (a plain non-negative
|
||||
decimal — no leading `+` or leading zero); a declared revision below
|
||||
`min_client_wire_revision` is refused with `400 invalid_argument`/`reason:
|
||||
"wire_revision_unsupported"` and `min_wire_revision`, `wire_revision`, and
|
||||
`bd_version` fields naming this server's floor, current revision, and
|
||||
release string. The header is absent by default and an absent header is
|
||||
served exactly as before — this is additive, not a new precondition on
|
||||
existing clients. A client with no `wire_revision` signal to read yet may
|
||||
infer one from `bd_version` only as an ADVISORY hint (string-or-number,
|
||||
never a refusal on an inferred `0`) — see the `wire_revision` property's
|
||||
inference notes in `internal/httpapi/spec/openapi.v0.yaml` for the cutoff
|
||||
and known-exception builds. See `internal/httpapi/wire_revision.go` and
|
||||
that same property for the full revision history.
|
||||
- `GET /v0/beads/issues`'s `sort` parameter now advertises the
|
||||
`issues.list.sort` capability token, the same way an operation itself
|
||||
does, and a CI rule
|
||||
(`TestNewParameterOnExistingOperationHasABehaviorToken`) requires every
|
||||
new parameter on an existing operation, or new request body member on an
|
||||
existing operation, to carry a token that `Capabilities()` actually
|
||||
advertises (not just backticked `a.b` text shaped like one). Three frozen
|
||||
baselines (`internal/httpapi/testdata/pretoken_*.json`) grandfather what
|
||||
predates the rule and are pinned never to grow
|
||||
(`TestPretokenBaselinesNeverGrow`); a brand-new operation is permanently
|
||||
exempt — its own review decides its capability story.
|
||||
- A CI golden digest (`internal/httpapi/wireshape`) pins the JSON name,
|
||||
type, format, enum, required-ness, and nullability of every EXISTING
|
||||
response AND request-body member across the whole HTTP spec — including
|
||||
array item shape and `additionalProperties` value shape — recursing
|
||||
through `$ref` and through a schema's own `allOf` or `oneOf`, and fails if
|
||||
any changes without `wire_revision` bumping to match;
|
||||
`go run ./internal/httpapi/wireshape/cmd/gendigest` refuses to write a
|
||||
changed or removed entry unless `wire_revision` has moved past what the
|
||||
existing golden recorded, and refuses any write at a lower
|
||||
`wire_revision` (purely additive entries otherwise always write). The
|
||||
same digest also pins every operation PARAMETER (query, path and header),
|
||||
keyed by operationId + location + name, and records its type, item shape,
|
||||
enum, required-ness, effective style and explode (OpenAPI's defaults
|
||||
filled in where unset), and default — a parameter retyped, re-enumerated,
|
||||
narrowed, re-serialized, switched required, or removed is non-additive
|
||||
exactly like a response or request-body member. A new member or
|
||||
parameter always counts as additive, even a REQUIRED one an old client
|
||||
will not send, and value constraints (`maxLength`, `pattern` and the
|
||||
like) are outside the digest: such changes need their own review against
|
||||
`wire_revision`.
|
||||
|
||||
### Changed
|
||||
|
||||
|
|
|
|||
|
|
@ -529,3 +529,127 @@ it cannot discover before connecting. Refusing keeps the published surface a
|
|||
property of the build, and matches how `bd` already answers this question one
|
||||
layer down, where a backend that cannot guarantee mutation-free access is turned
|
||||
away rather than opened anyway.
|
||||
|
||||
## The wire-shape signal
|
||||
|
||||
`capabilities` answers which OPERATIONS a build serves. Nothing answered
|
||||
whether an operation's response SHAPE had changed underneath a client already
|
||||
built against it — a client decoding a strict schema against a future server
|
||||
that renamed or retyped a field it depends on would fail wherever it happened
|
||||
to read that field, with no single place to check first. `wire_revision` and
|
||||
`min_client_wire_revision`, both on `GET /v0/beads/context`, are that single
|
||||
place.
|
||||
|
||||
`wire_revision` is a counter, not a semver: it bumps only for a NON-ADDITIVE
|
||||
change to an existing response member's JSON name or type (a new, purely
|
||||
additive member needs no bump). The full history is the `wire_revision`
|
||||
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 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
|
||||
against may assert it on ANY request via the optional `Bd-Wire-Revision`
|
||||
header — not only the handshake — and `checkWireRevision` refuses a request
|
||||
naming a revision below the floor with `400 invalid_argument`/
|
||||
`reason: "wire_revision_unsupported"` and a `min_wire_revision` field pinning
|
||||
the floor that was violated, before the server does any work building a body
|
||||
shaped for a revision the client has already said it cannot decode. The header
|
||||
is optional and absent by default, which is what keeps this additive: an older
|
||||
client that never sends it is served exactly as before. A malformed value
|
||||
(not a non-negative integer) is a different mistake — `reason: "invalid_value"`
|
||||
— and must never disclose `min_wire_revision`, which is reserved for a
|
||||
revision the server actually read and understood to be too old.
|
||||
|
||||
The check runs on every route but `GET /healthz` (`wireRevisionExempt`,
|
||||
`routes.go`) — including the identity handshake itself, unlike the
|
||||
`Bd-Project-Id` stamp, which exempts the handshake because that is how a
|
||||
client LEARNS the id it must stamp with. A client that already knows the wire
|
||||
revision it was built for has no equivalent reason to omit it on the very
|
||||
first request, and the handshake is where a floor violation is cheapest to
|
||||
catch: before the client has acted on anything shaped for a revision it
|
||||
cannot decode. Liveness is exempt for the same reason `Bd-Project-Id` is: a
|
||||
probe carries no notion of either header, and refusing it for one it never
|
||||
had a reason to send would make `/healthz` lie about the process being alive.
|
||||
|
||||
**The golden digest.** A revision bump is a promise a human makes; nothing
|
||||
enforced that the promise was kept, or that it was even necessary. CI pins
|
||||
one against the other with a golden digest, `internal/httpapi/wireshape`:
|
||||
`wireshape.Compute` walks every response's AND every request body's every
|
||||
content-type schema across the whole spec — not only `application/json`, so
|
||||
`application/problem+json` and therefore `Problem` itself is covered too —
|
||||
recursing through `$ref` and through a schema's own `allOf` or `oneOf`, and
|
||||
recording, keyed by schema and member name, each member's JSON name, type,
|
||||
format, enum values, required-ness, and nullability, plus the scalar shape of
|
||||
array items and of `additionalProperties` map values. It records every
|
||||
operation parameter (query, path, and header) as well, keyed by
|
||||
`operationId`, location, and name rather than by schema — two operations'
|
||||
same-named parameters are independent contracts — with its type, item shape,
|
||||
enum values, required-ness, style, explode, and default; style and explode
|
||||
are the effective values, OpenAPI's defaults filled in where the document
|
||||
leaves them unset, so spelling a default out changes nothing while flipping
|
||||
one does. The digest is a boundary, not the whole wire: value constraints
|
||||
such as `maxLength` or `pattern` (on members and parameters alike) and a
|
||||
composition keyword on a single member's own value are outside it, an
|
||||
object-typed or `content`-described parameter is recorded only as its
|
||||
container, and a new member or parameter always counts as additive — even a
|
||||
required one an old client will not send — so each of those needs its own
|
||||
review against `wire_revision`. `TestWireShapeDigest` fails on any
|
||||
disagreement between golden and spec, and the failure names the fix: a
|
||||
changed or removed entry without a `wire_revision` bump is drift nobody
|
||||
signed off on; a `wire_revision` LOWER than the golden's means the constant
|
||||
itself is wrong, since the revision table only ever grows; any other
|
||||
difference — a bumped `wire_revision`, or entries only added — means the
|
||||
golden is simply stale. Drift and staleness share one explicit fix,
|
||||
`go run ./internal/httpapi/wireshape/cmd/gendigest` — never run to make a
|
||||
failing test pass on an accidental shape change, only after the revision
|
||||
bump and the `openapi.v0.yaml` history entry it belongs beside; the command
|
||||
itself refuses to write a changed or removed entry unless `wire_revision`
|
||||
has moved past what the existing golden recorded, and refuses any write at a
|
||||
lowered `wire_revision`, so running it cannot silently launder drift into
|
||||
the baseline. A purely additive diff — new members or parameters, with no
|
||||
existing entry changed or removed — writes at the golden's own
|
||||
`wire_revision` or any later one.
|
||||
|
||||
**The new-parameter and new-request-body-member token rule.** `capabilities`
|
||||
already required a `resource.verb` token for a new OPERATION; nothing
|
||||
required one for a new PARAMETER, or new JSON request body member, on an
|
||||
EXISTING operation, so a client had no single place to learn that, say, `GET
|
||||
/v0/beads/issues`'s `sort` parameter had started accepting a value.
|
||||
`issues.list.sort` is the first deliberate use of the same convention one
|
||||
level down: the token lives in the parameter's (or body member's) own
|
||||
description, exactly as `capabilities` members carry theirs, enforced by
|
||||
`TestNewParameterOnExistingOperationHasABehaviorToken` against three frozen
|
||||
baselines (`internal/httpapi/testdata/pretoken_parameters.json`,
|
||||
`pretoken_request_body_members.json`, `pretoken_operations.json`) describing
|
||||
every parameter, body member, and operation the document already had the day
|
||||
the rule was written — written once and pinned never to grow
|
||||
(`TestPretokenBaselinesNeverGrow`), since only something pre-existing and
|
||||
untokened ever belongs on them, and a brand-new operation is permanently
|
||||
exempt from the rule: its own review decides its capability story, not a
|
||||
baseline written before it existed. A backticked `a.b`(`.c`)-shaped span in a
|
||||
description is not enough on its own: the rule also checks the token against
|
||||
`Capabilities()`'s own served list, so Go identifiers or example values that
|
||||
merely look like a token (`workapi.DefaultReadyLimit`, `status.custom`) do not
|
||||
satisfy it. `TestUntokenedParameterRuleFires` and
|
||||
`TestUntokenedRequestBodyMemberRuleFires` prove the checker itself still
|
||||
distinguishes tokened, grandfathered, and untokened parameters and body
|
||||
members — including a real-but-unrelated token, which correctly passes, since
|
||||
`Capabilities()` has no per-parameter binding to check a token's relevance
|
||||
against, only its existence — against synthetic fixtures rather than the real
|
||||
spec, so the rule's own logic is covered independently of whether the current
|
||||
document happens to exercise every branch.
|
||||
|
|
|
|||
|
|
@ -39,6 +39,7 @@ go_library(
|
|||
"sweep.go",
|
||||
"tree.go",
|
||||
"update.go",
|
||||
"wire_revision.go",
|
||||
],
|
||||
importpath = "github.com/steveyegge/beads/internal/httpapi",
|
||||
visibility = ["//:__subpackages__"],
|
||||
|
|
@ -103,12 +104,13 @@ go_test(
|
|||
"tree_test.go",
|
||||
"update_test.go",
|
||||
"wire_bijection_test.go",
|
||||
"wire_revision_test.go",
|
||||
],
|
||||
data = [
|
||||
"claim.go",
|
||||
"//cmd/bd:list.go",
|
||||
"//cmd/bd:ready.go",
|
||||
],
|
||||
] + glob(["testdata/**"]),
|
||||
embed = [":httpapi"],
|
||||
deps = [
|
||||
"//internal/config",
|
||||
|
|
|
|||
|
|
@ -1010,7 +1010,7 @@ type ContextResponse struct {
|
|||
// OPTIONAL, and absent means only that this server does not disclose its filesystem layout — never that it has no workspace. A client MUST NOT require it, MUST NOT treat absence as an error, and has no use for the value beyond display: it is a path on the SERVER's filesystem, which the client cannot open. Identify the workspace by `project_id` and `database`, which are required.
|
||||
BeadsDir *string `json:"beads_dir,omitempty"`
|
||||
|
||||
// Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, and `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string.
|
||||
// Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway, and `issues.list.sort`, which announces that `GET /v0/beads/issues` accepts the `sort` query parameter (two closed, pageable total orders — see that parameter) rather than silently answering `unknown_parameter`. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string.
|
||||
//
|
||||
// THIS LIST IS BUILD-LEVEL, NOT WORKSPACE-LEVEL. It says which operations this binary serves, and for every entry but two that is the whole answer. `events.list` and `events.watch` are the exceptions: the durable events journal is a per-workspace setting that is OFF by default, so a server that advertises them may still refuse every request to both with 409 `events_journal_disabled` — correctly, because the operations exist and the workspace has no journal. A consumer of either MUST treat the capability as "this server speaks it" and the 409 as "not on this workspace", and must not read the capability as a promise that records will arrive.
|
||||
Capabilities []string `json:"capabilities"`
|
||||
|
|
@ -1021,6 +1021,11 @@ type ContextResponse struct {
|
|||
// DoltMode Which storage mode this workspace is served from.
|
||||
DoltMode string `json:"dolt_mode"`
|
||||
|
||||
// MinClientWireRevision The OLDEST client `wire_revision` this server still answers correctly. A client whose own compiled `wire_revision` is below this number should refuse to dial at all, the same way it refuses an unknown `api_version`: nothing it does with a response shaped for this revision is safe to assume.
|
||||
//
|
||||
// A client MAY declare the revision it was built for on every request with the optional `Bd-Wire-Revision` header (see the document-level rule above). When it does, and the declared value is below this member, the server refuses with `400` / `code: invalid_argument` / `param: "Bd-Wire-Revision"` / `reason: "wire_revision_unsupported"` rather than risk serving a body the caller has already said it cannot decode. The header is OPTIONAL and an absent one is served exactly as today — this is additive wire surface, not a new precondition on requests already in the field, exactly as `Bd-Project-Id` is.
|
||||
MinClientWireRevision int `json:"min_client_wire_revision"`
|
||||
|
||||
// ProjectId Logical project identifier.
|
||||
ProjectId string `json:"project_id"`
|
||||
|
||||
|
|
@ -1029,6 +1034,45 @@ type ContextResponse struct {
|
|||
|
||||
// SchemaVersion The shared JSON schema version — the same constant the CLI's stdout JSON envelope reports. Diagnostic only: it can move for CLI-only reasons with no HTTP wire change, so clients MUST NOT branch on it.
|
||||
SchemaVersion int `json:"schema_version"`
|
||||
|
||||
// WireRevision A counter bumped on every release whose wire format changed in a way an unaware client could MISDECODE: an existing member's JSON type or meaning changed, or a member was removed or renamed. Adding a brand-new member to an existing schema, or a brand-new operation, is ADDITIVE and never bumps it — an old client simply never asks for the new member and is unaffected. That promise does not extend to a new REQUIRED request input (a request-body member or a parameter): it misdecodes nothing, so it bumps nothing, but an old client that never sends it is refused. The drift gate below records a new required parameter or body member as an ordinary addition and asks for no bump, so keeping old clients working through one is that change's own review's job.
|
||||
//
|
||||
// Revision history, and it only ever grows by appending a row:
|
||||
//
|
||||
// * `0` — every server before 1.3.0. `revision` and
|
||||
// `expected_version` were JSON integers, and this field did not
|
||||
// exist: an absent `wire_revision` together with a `bd_version`
|
||||
// below `1.3.0` IS a `0`.
|
||||
// * `1` — 1.3.0 up to, but not including, the release that adds this
|
||||
// field. `revision` and `expected_version` moved to DECIMAL-STRING
|
||||
// tokens (#6053) under the same `api_version: "v0"`, with nothing
|
||||
// in the handshake to tell an integer-expecting client the shape
|
||||
// had moved underneath it. That silent gap is the whole reason
|
||||
// this field exists.
|
||||
// * `2` — the first release whose `ContextResponse` carries
|
||||
// `wire_revision` and `min_client_wire_revision` at all (this one).
|
||||
//
|
||||
//
|
||||
// PRESENCE, not just value: a generated client whose JSON decoder zero-values a missing integer field cannot tell, by looking at a decoded `0` alone, whether the server SENT `0` or sent nothing. This is never actually ambiguous in practice, because `0` and `1` are PERMANENTLY RETIRED values — they describe servers that predate this field or carried the brief interim string shape, and no server that implements this field (`CurrentWireRevision` starts at `2` and only increases) will ever legitimately send a literal `0` or `1`. A decoded `0` can therefore only mean "this server omitted the field," and a client inferring from `bd_version` per the paragraph below is doing exactly the right thing in that case, never guessing at a value the field could have meant on its own. A client that wants presence as a first-class fact rather than an inference anyway should decode `wire_revision` into a nullable type, or check for the JSON key's presence directly, instead of relying on this retirement guarantee.
|
||||
//
|
||||
// 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 AND request body member's (schema, member, type, format, enum, required, nullable), plus the item shape of an array member and the value shape of an `additionalProperties` map, recursing through `$ref` and through a schema's own `allOf` or `oneOf`. The same digest also covers every operation PARAMETER (query, path and header) across every operation, keyed by operationId + location + name rather than by schema, recording its type, item shape (for an array parameter), enum, required, style, explode and default — style and explode as their effective values, OpenAPI's defaults filled in where the document leaves them unset. It fails CI the moment any one of these — member or parameter — 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, parameter or operation also changes the golden (it is appended to, never frozen in place) but needs no revision bump to pass; the command itself refuses to write a changed or removed entry at an unbumped revision, refuses any write at a LOWER revision than the golden records, and refuses to create a golden that does not exist yet unless run with `-init`. The digest is a boundary, not the whole wire: value constraints such as `maxLength`, `maximum`, `pattern` or `maxItems` are outside it, on members and parameters alike, and so is a composition keyword on a single member's own value (this document uses none); an object-typed parameter, or one described by `content` rather than `schema`, is recorded only as its container. Narrowing a constraint trips no gate, so such a change must be weighed against this counter in its own review.
|
||||
//
|
||||
// Every request PARAMETER (query, path or header) and every request BODY MEMBER, added to an EXISTING operation after this document, must carry a capability token in its own description, exactly as `capabilities` members do above — `TestNewParameterOnExistingOperationHasABehaviorToken` enforces it against two frozen baselines (`internal/httpapi/testdata/pretoken_parameters.json` for parameters, `pretoken_request_body_members.json` for body members) of every parameter and body member this document already had the day each rule was written. A member on its baseline is grandfathered and never needs a token; any member not on it — present now or added later, on an operation that already existed when the relevant baseline was frozen — must carry one today. A BRAND-NEW operation (one absent from the third frozen file, `pretoken_operations.json`) is exempt entirely: its own review decides its capability story, not a baseline written before it existed. The token itself must also be one `Capabilities()` actually serves — a backticked string merely shaped like a token proves nothing on its own. All three baselines are written once and never regenerated: only a pre-existing, untokened member or operation ever belongs on them, a newly tokened member satisfies the rule without needing an entry at all, and `TestPretokenBaselinesNeverGrow` pins their sizes so nothing can hand-add a new exemption instead of a token. `issues.list.sort` is the first deliberate use of the parameter rule; it also closes the one gap the rule was written to catch, since `sort` itself shipped (#5666) with no token at all.
|
||||
WireRevision int `json:"wire_revision"`
|
||||
}
|
||||
|
||||
// CreateIssueDependency One edge created with the issue. It carries `reverse` where `BatchCreateDependency` does not, because that operation's items have no id a target could point back at and this one's issue does.
|
||||
|
|
@ -1492,6 +1536,9 @@ type Problem struct {
|
|||
// IT IS OPTIONAL ON EVERY OPERATION BUT THE CLAIM. `POST /v0/beads/issues/{id}:claim` always carries it, because its conflict path reads the row it lost to. `PATCH /v0/beads/issues/{id}` and `POST /v0/beads/issues:batchApply` carry it only when the refusing transaction reported a holder, and `POST /v0/beads/issues/{id}:release` never does — the ownership fence refuses without naming anyone. An absent member means "this refusal could not name the holder", never "nobody holds it"; re-read the row.
|
||||
Assignee *string `json:"assignee,omitempty"`
|
||||
|
||||
// BdVersion With `invalid_argument` / `reason: "wire_revision_unsupported"` ONLY: this server's own `ContextResponse.bd_version`, for a client that logs or reports the refusal and wants the release string alongside the two wire-revision numbers rather than a second request to fetch it. It is set on that refusal and on no other.
|
||||
BdVersion *string `json:"bd_version,omitempty"`
|
||||
|
||||
// BlockerId With `dependency_cycle`, hierarchy refusal only: the ancestor or descendant the edge named as blocker. See `issue_id`.
|
||||
BlockerId *string `json:"blocker_id,omitempty"`
|
||||
|
||||
|
|
@ -1562,6 +1609,9 @@ type Problem struct {
|
|||
// ItemKind The `kind` of the item at `item_index`, so a client can dispatch on what the item was doing without walking its own request back.
|
||||
ItemKind *string `json:"item_kind,omitempty"`
|
||||
|
||||
// MinWireRevision With `invalid_argument` / `reason: "wire_revision_unsupported"` ONLY: this server's own `ContextResponse.min_client_wire_revision`, so a client that declared a `Bd-Wire-Revision` can log exactly how far behind it is without re-deriving the number from `bd_version`. It is set on that refusal and on no other.
|
||||
MinWireRevision *int `json:"min_wire_revision,omitempty"`
|
||||
|
||||
// OpenChildren With `not_closable`: how many open children the transaction that refused the close observed, read inside that transaction rather than parsed out of `detail`.
|
||||
//
|
||||
// PRESENT ONLY for the open-children refusal. The other `not_closable` refusal is a live blocker and carries `blockers` instead, so member presence — not prose — is how a client tells the two apart. Both are bypassed by `force`.
|
||||
|
|
@ -1572,7 +1622,7 @@ type Problem struct {
|
|||
// With `precondition_failed`: the body member carrying the guard that missed. It is the same spelling a 400 on the same operation would use, so a client reads one member to find the offending input whichever way the request was refused.
|
||||
Param *string `json:"param,omitempty"`
|
||||
|
||||
// Reason With `invalid_argument`: `unknown_parameter` (this server does not know that parameter — version skew; degrade or fall back), `invalid_value` (the value is not one this server will act on: malformed, out of vocabulary, or — for `limit=0` under `--allow-non-loopback` — legal but refused in this server's configuration; `detail` says which), or `project_mismatch` (the `Bd-Project-Id` header named a project this server does not serve — a document-level refusal like the Host-header 400, raised on every enforced route, and the one that carries `server_project_id`; see the document-level rule). Either way the recovery is to send something different, never to retry the same request. The set may grow; default-branch on unknown values.
|
||||
// Reason With `invalid_argument`: `unknown_parameter` (this server does not know that parameter — version skew; degrade or fall back), `invalid_value` (the value is not one this server will act on: malformed, out of vocabulary, or — for `limit=0` under `--allow-non-loopback` — legal but refused in this server's configuration; `detail` says which), `project_mismatch` (the `Bd-Project-Id` header named a project this server does not serve — a document-level refusal like the Host-header 400, raised on every enforced route, and the one that carries `server_project_id`; see the document-level rule), or `wire_revision_unsupported` (the `Bd-Wire-Revision` header named a revision below `ContextResponse.min_client_wire_revision` — also a document-level refusal, raised on every route including the identity handshake, and the one that carries `min_wire_revision`; see the document-level rule and `ContextResponse.wire_revision`). Either way the recovery is to send something different, never to retry the same request. The set may grow; default-branch on unknown values.
|
||||
Reason *string `json:"reason,omitempty"`
|
||||
|
||||
// RequestId Opaque correlation id for this request, echoed in the server's request log line. Never a dispatch key and never a retry key. (This server mints per-process ids that do not survive a restart; a deployment may substitute any identifier with the same log-correlation property, such as an edge trace id.)
|
||||
|
|
@ -1597,6 +1647,9 @@ type Problem struct {
|
|||
|
||||
// Type RFC 9457 problem type. This server never emits it, so `about:blank` is implied. A deployment that hosts problem documentation MAY supply it: one stable URI per status+code pair, dereferencing to documentation for that pair. It restates identity that `code` already carries, so a client MUST NOT dispatch on it and a server MUST NOT use it to subdivide a code.
|
||||
Type *string `json:"type,omitempty"`
|
||||
|
||||
// WireRevision With `invalid_argument` / `reason: "wire_revision_unsupported"` ONLY: this server's own current `ContextResponse.wire_revision`, alongside `min_wire_revision`, so a client logging the refusal has both ends of the supported range without a second request to `GET /v0/beads/context`. It is set on that refusal and on no other.
|
||||
WireRevision *int `json:"wire_revision,omitempty"`
|
||||
}
|
||||
|
||||
// QueryPage A page of query results. It is `ReadyPage`'s shape rather than `IssuesPage`'s, and the missing member is the point: a page of this operation carries no `next_cursor`, because a cursor is a keyset position in a database order and a predicate query's matching set is assembled outside the database.
|
||||
|
|
@ -2197,7 +2250,7 @@ type ListIssuesParams struct {
|
|||
//
|
||||
// THE VOCABULARY IS CLOSED, and deliberately smaller than the nine values `bd list --sort` and `GET /v0/beads/issues:query` take. Each value here is a cursor contract, not a display preference: it needs a keyset predicate and a key proven total. See the operation description for why the other seven have neither.
|
||||
//
|
||||
// A value outside the enum is a 400 `invalid_argument` with `param: "sort"` and `reason: "invalid_value"`. A server that predates this parameter answers `param: "sort"` with `reason: "unknown_parameter"` instead, which is the per-parameter capability probe a client can dispatch on to fall back to paging in `created` order and sorting client-side.
|
||||
// A value outside the enum is a 400 `invalid_argument` with `param: "sort"` and `reason: "invalid_value"`. A server that predates this parameter answers `param: "sort"` with `reason: "unknown_parameter"` instead, which is the per-parameter capability probe a client can dispatch on to fall back to paging in `created` order and sorting client-side. This server also advertises the `issues.list.sort` token in `ContextResponse.capabilities` for exactly that check, so a client with capabilities cached from the handshake never has to pay for the round trip an old server's `unknown_parameter` answer costs.
|
||||
Sort *ListIssuesParamsSort `form:"sort,omitempty" json:"sort,omitempty"`
|
||||
|
||||
// Cursor Opaque keyset position, taken verbatim from a previous response's `next_cursor`. Clients MUST NOT construct, parse or mutate it: its encoding is server-private and versioned, and an undecodable or unknown-version value is refused with 400 `invalid_cursor`. The recovery for that refusal is normative: restart paging with no `cursor` at all — the position cannot be salvaged, and re-sending the same value cannot succeed.
|
||||
|
|
|
|||
|
|
@ -95,9 +95,11 @@ func contextResponse(info domain.ContextInfo, schemaVersion int, capabilities []
|
|||
}
|
||||
published := domain.PublishedContext(info)
|
||||
return apigen.ContextResponse{
|
||||
ApiVersion: APIVersion,
|
||||
SchemaVersion: schemaVersion,
|
||||
Capabilities: capabilities,
|
||||
ApiVersion: APIVersion,
|
||||
SchemaVersion: schemaVersion,
|
||||
Capabilities: capabilities,
|
||||
WireRevision: CurrentWireRevision,
|
||||
MinClientWireRevision: MinClientWireRevision,
|
||||
|
||||
BdVersion: published.BdVersion,
|
||||
Backend: published.Backend,
|
||||
|
|
|
|||
|
|
@ -306,6 +306,15 @@ const (
|
|||
// `server_project_id`. The recovery is to stop stamping this server with
|
||||
// another workspace's id, never to retry the same request.
|
||||
ReasonProjectMismatch Reason = "project_mismatch"
|
||||
// ReasonWireRevisionUnsupported means the request's Bd-Wire-Revision header
|
||||
// named a revision below this server's ContextResponse.min_client_wire_revision.
|
||||
// Like ReasonProjectMismatch it is a document-level 400 reachable on every
|
||||
// enforced route — including the identity handshake itself — rather than
|
||||
// per-operation behavior, and it is the one refusal that carries
|
||||
// `min_wire_revision`. The recovery is to stop talking to this server with a
|
||||
// client built for a revision it no longer supports, never to retry the same
|
||||
// request.
|
||||
ReasonWireRevisionUnsupported Reason = "wire_revision_unsupported"
|
||||
)
|
||||
|
||||
// staticDetail is the set of codes whose `detail` is FIXED, whatever the
|
||||
|
|
@ -1345,6 +1354,37 @@ func ProjectMismatch(got, own string) Result {
|
|||
return res
|
||||
}
|
||||
|
||||
// WireRevisionUnsupported builds the 400 for a request whose Bd-Wire-Revision
|
||||
// header names a revision below this server's own
|
||||
// ContextResponse.min_client_wire_revision. got is the revision the client
|
||||
// declared; min is this server's floor, disclosed in the `min_wire_revision`
|
||||
// extension member for the same reason ProjectMismatch discloses
|
||||
// `server_project_id`: so a client that already knows it declared a revision
|
||||
// can tell exactly how far behind it is without re-deriving the number from
|
||||
// `bd_version`. current and bdVersion are this server's own
|
||||
// ContextResponse.wire_revision and ContextResponse.bd_version, disclosed in
|
||||
// the `wire_revision` and `bd_version` extension members so a client logging
|
||||
// or reporting the refusal has the server's full version story without a
|
||||
// second request to GET /v0/beads/context (review: "include the server's
|
||||
// current wire_revision and bd_version in the refusal problem body").
|
||||
//
|
||||
// This is the ONLY refusal on the surface that sets `min_wire_revision`,
|
||||
// `wire_revision` and `bd_version`, and — unlike ProjectMismatch, which is
|
||||
// exempt on the identity handshake because that is where a client LEARNS the
|
||||
// id it must stamp with — it is raised on GET /v0/beads/context too: a client
|
||||
// that already knows the revision it was built for gains nothing from being
|
||||
// served a body it has already said it cannot decode, and loses the chance to
|
||||
// fail before acting on it.
|
||||
func WireRevisionUnsupported(got, min, current int, bdVersion string) Result {
|
||||
res := InvalidArgument(WireRevisionHeader, ReasonWireRevisionUnsupported,
|
||||
"the "+WireRevisionHeader+" header names revision "+strconv.Itoa(got)+
|
||||
", which is below the "+strconv.Itoa(min)+" this server still answers correctly")
|
||||
res.Problem.MinWireRevision = &min
|
||||
res.Problem.WireRevision = ¤t
|
||||
res.Problem.BdVersion = &bdVersion
|
||||
return res
|
||||
}
|
||||
|
||||
// InvalidCursor builds the 400 for a cursor this server did not issue, cannot
|
||||
// decode, or issued under a different internal version.
|
||||
func InvalidCursor() Result {
|
||||
|
|
|
|||
|
|
@ -59,6 +59,23 @@ const CapProjectEnforce = "project.enforce"
|
|||
// round trip an old server would refuse anyway.
|
||||
const CapBatchApplyLarge = "issues.batchApplyLarge"
|
||||
|
||||
// CapIssuesListSort is the behavior capability that advertises GET
|
||||
// /v0/beads/issues' `sort` parameter (reads.go, spec `sort` on OpListIssues).
|
||||
// Like CapBatchApplyLarge it names a PARAMETER added to an existing operation
|
||||
// rather than a route of its own — `issues.list` is already the per-operation
|
||||
// token for the route itself — so it rides the same behaviorCapabilities list.
|
||||
//
|
||||
// The parameter shipped (#5666) with no token at all: a client already had the
|
||||
// per-parameter fallback (an old server answers `sort` with 400
|
||||
// `unknown_parameter`, which doubles as a capability probe), but that means
|
||||
// paying a round trip an old server would refuse anyway. A client that checks
|
||||
// this token at handshake time learns the same thing for free. This is also
|
||||
// the spec/lint rule in TestNewParameterOnExistingOperationHasABehaviorToken:
|
||||
// `sort` predates that rule and would have failed it, so it is the parity fix
|
||||
// — ent already advertises the equivalent token — that the rule's own
|
||||
// baseline is built from.
|
||||
const CapIssuesListSort = "issues.list.sort"
|
||||
|
||||
// customMethodTarget splits the custom method off the segment the router
|
||||
// matched, and reports the row that claims it.
|
||||
//
|
||||
|
|
@ -173,6 +190,17 @@ type route struct {
|
|||
// reads that touch no workspace data are exempt and every other route —
|
||||
// streaming or not — is enforced.
|
||||
projectExempt bool
|
||||
// wireRevisionExempt exempts an operation from the Bd-Wire-Revision floor
|
||||
// check (checkWireRevision). Legitimate only for liveness: a kubelet probe
|
||||
// carries no notion of a wire revision at all, and the check's refusal body
|
||||
// is itself a `ContextResponse`-shaped disclosure the health row must never
|
||||
// grow. It is deliberately NOT set on the identity handshake — unlike
|
||||
// projectExempt, where the handshake is how a client LEARNS the id it must
|
||||
// stamp with, a client that already knows the revision it was built for can
|
||||
// and should declare it on the very first request, and the handshake is
|
||||
// exactly where a floor violation is cheapest to catch: before the client
|
||||
// has acted on anything shaped for a revision it cannot decode.
|
||||
wireRevisionExempt bool
|
||||
// implemented gates the capability list, so a release between slices never
|
||||
// advertises an operation that does not work. Every v0 operation is
|
||||
// implemented as of the read-endpoints slice; the flag stays because the
|
||||
|
|
@ -203,8 +231,12 @@ var routeTable = []route{
|
|||
// liveness probe gated on a matching project stamp would go dark on a
|
||||
// misconfigured client exactly when an operator needs it most.
|
||||
projectExempt: true,
|
||||
implemented: true,
|
||||
handler: (*Server).handleHealth,
|
||||
// Same reasoning extends to the wire-revision floor: a probe carries no
|
||||
// `Bd-Wire-Revision` of its own, and must not be refused for a header it
|
||||
// never had a reason to send.
|
||||
wireRevisionExempt: true,
|
||||
implemented: true,
|
||||
handler: (*Server).handleHealth,
|
||||
},
|
||||
{
|
||||
op: OpGetContext,
|
||||
|
|
@ -778,7 +810,7 @@ func (r route) specPathOf() string {
|
|||
// route. project.enforce announces per-request Bd-Project-Id enforcement
|
||||
// (checkProjectStamp): a stamped client reads it to know the refusal is available
|
||||
// rather than silently dropped by an older server.
|
||||
var behaviorCapabilities = []string{CapProjectEnforce, CapBatchApplyLarge}
|
||||
var behaviorCapabilities = []string{CapProjectEnforce, CapBatchApplyLarge, CapIssuesListSort}
|
||||
|
||||
// Capabilities lists what this build advertises in ContextResponse.capabilities:
|
||||
// the operations it actually implements, gated on `implemented` so a stub can
|
||||
|
|
|
|||
|
|
@ -491,6 +491,15 @@ type Server struct {
|
|||
writeStall time.Duration
|
||||
watchPoll time.Duration
|
||||
watchBeat time.Duration
|
||||
// minClientWireRevision is the field checkWireRevision enforces against.
|
||||
// It starts at the package constant MinClientWireRevision and exists as
|
||||
// a field, rather than a direct read of that constant, only so a test can
|
||||
// raise the floor in milliseconds the way it shrinks semTimeout above —
|
||||
// production never overrides it. Unlike semTimeout et al it is an int
|
||||
// with no zero-value ambiguity to paper over with orDefault: the
|
||||
// constant's own real-world default is 0, so a freshly zeroed Server
|
||||
// behaves identically whether or not Listen ran yet.
|
||||
minClientWireRevision int
|
||||
// drainTimeout overrides the package-level drainTimeout constant used as
|
||||
// drainBudget's floor. A test shrinks this to prove Serve's drain
|
||||
// actually EXTENDS past it for an in-flight large apply, instead of
|
||||
|
|
@ -632,11 +641,12 @@ func Listen(cfg Config) (*Server, error) {
|
|||
workspaceMemories: cfg.Memories,
|
||||
eventsJournal: cfg.EventsJournal,
|
||||
|
||||
sem: make(chan struct{}, maxInflight),
|
||||
semTimeout: semAcquireTimeout,
|
||||
semWarn: saturationWarn,
|
||||
largeApplySem: make(chan struct{}, 1),
|
||||
largeApplyCeiling: orDefault(cfg.LargeApplyCeiling, DefaultLargeApplyCeiling),
|
||||
sem: make(chan struct{}, maxInflight),
|
||||
semTimeout: semAcquireTimeout,
|
||||
semWarn: saturationWarn,
|
||||
minClientWireRevision: MinClientWireRevision,
|
||||
largeApplySem: make(chan struct{}, 1),
|
||||
largeApplyCeiling: orDefault(cfg.LargeApplyCeiling, DefaultLargeApplyCeiling),
|
||||
|
||||
closing: make(chan struct{}),
|
||||
maxWatchStreams: maxWatchStreams,
|
||||
|
|
@ -1872,6 +1882,18 @@ func (s *Server) route(rt route) http.Handler {
|
|||
}
|
||||
}
|
||||
|
||||
// Wire-floor before resources, same as the project stamp: a client that
|
||||
// has declared a revision this build no longer supports is turned away
|
||||
// before it can buy a database slot or open a unit of work. Checked on
|
||||
// every route but health (see wireRevisionExempt) — including the
|
||||
// identity handshake, where catching the mismatch is cheapest.
|
||||
if !rt.wireRevisionExempt {
|
||||
if res := s.checkWireRevision(r); res != nil {
|
||||
s.fail(w, r, *res)
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
if !rt.bypassSemaphore {
|
||||
release, err := s.acquire(r.Context(), rec)
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -635,7 +635,7 @@ func TestCapabilitiesAdvertiseEveryImplementedOperation(t *testing.T) {
|
|||
// them; project.enforce and issues.batchApplyLarge are advertised in the
|
||||
// same list. Both are spelled literally here to keep this an independent
|
||||
// oracle rather than a second call to the code under test.
|
||||
want = append(want, "project.enforce", "issues.batchApplyLarge")
|
||||
want = append(want, "project.enforce", "issues.batchApplyLarge", "issues.list.sort")
|
||||
slices.Sort(want)
|
||||
if !slices.Equal(got, want) {
|
||||
t.Errorf("capabilities = %v, want %v", got, want)
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ info:
|
|||
it decides every refusal before opening its stream.
|
||||
|
||||
|
||||
## Four 400s cut across operations, and are documented here once
|
||||
## Five 400s cut across operations, and are documented here once
|
||||
|
||||
|
||||
* **Host header.** A request whose `Host` header is not in the server's
|
||||
|
|
@ -121,10 +121,34 @@ info:
|
|||
id to stamp with. A client detects that a server performs this check by
|
||||
the `project.enforce` capability (see `ContextResponse`).
|
||||
|
||||
* **Wire-revision floor.** A request MAY carry a `Bd-Wire-Revision` header
|
||||
naming the integer `wire_revision` (see `ContextResponse.wire_revision`)
|
||||
the CLIENT was built to decode. When the header is present, is a
|
||||
non-negative integer, and names a revision BELOW
|
||||
`ContextResponse.min_client_wire_revision`, the request is refused with
|
||||
`400` / `code: invalid_argument` / `param: "Bd-Wire-Revision"` /
|
||||
`reason: "wire_revision_unsupported"`, and that refusal carries this
|
||||
server's own floor in the `min_wire_revision` member so the client can
|
||||
log exactly how far behind it is without re-deriving the number from
|
||||
`bd_version`. A header value that is not a non-negative integer is
|
||||
refused the ordinary way a malformed value is: `400` /
|
||||
`reason: "invalid_value"`. An ABSENT header is the backward-compatible
|
||||
path, exactly as for `Bd-Project-Id`: a client that never declares a
|
||||
revision is served exactly as today, so this is additive wire surface,
|
||||
never a new precondition on requests already in the field. UNLIKE the
|
||||
project-id stamp, this check is NOT skipped on `GET /v0/beads/context`:
|
||||
the handshake is precisely where a client's floor matters most, because
|
||||
serving a `ContextResponse` to a client that has already said it cannot
|
||||
decode this revision would defeat the whole signal. It IS skipped on
|
||||
`GET /healthz` alone, for the reason liveness is always exempt: it must
|
||||
answer whatever client reaches it. See `ContextResponse.wire_revision`
|
||||
for the full version-signal design.
|
||||
|
||||
|
||||
The first two are uniform rules reachable on EVERY route including
|
||||
`GET /healthz`; the third holds on every body-carrying operation; the fourth
|
||||
holds on every route EXCEPT the two exempt reads named above. All four are
|
||||
`GET /healthz`; the third holds on every body-carrying operation; the
|
||||
fourth holds on every route EXCEPT the two exempt reads named above; the
|
||||
fifth holds on every route except `GET /healthz` alone. All five are
|
||||
stated here instead of being repeated on every operation. The per-operation
|
||||
`responses` below therefore list what an operation produces BEYOND them: a
|
||||
generated client must treat `400 invalid_argument` as possible everywhere,
|
||||
|
|
@ -192,6 +216,17 @@ info:
|
|||
* `schema_version` is NOT an HTTP gate. It is shared with the CLI's stdout
|
||||
JSON envelope, so it can move for CLI-only reasons with no HTTP wire
|
||||
change. Report it, log it, never branch on it.
|
||||
* `wire_revision` and `min_client_wire_revision` gate WIRE SHAPE, not
|
||||
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 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.
|
||||
|
|
@ -1281,7 +1316,11 @@ paths:
|
|||
predates this parameter answers `param: "sort"` with
|
||||
`reason: "unknown_parameter"` instead, which is the per-parameter
|
||||
capability probe a client can dispatch on to fall back to paging in
|
||||
`created` order and sorting client-side.
|
||||
`created` order and sorting client-side. This server also
|
||||
advertises the `issues.list.sort` token in
|
||||
`ContextResponse.capabilities` for exactly that check, so a client
|
||||
with capabilities cached from the handshake never has to pay for
|
||||
the round trip an old server's `unknown_parameter` answer costs.
|
||||
schema:
|
||||
type: string
|
||||
enum: [created, priority]
|
||||
|
|
@ -7385,7 +7424,7 @@ components:
|
|||
conforms to this document.
|
||||
required:
|
||||
[api_version, bd_version, schema_version, backend, dolt_mode, database,
|
||||
project_id, capabilities]
|
||||
project_id, capabilities, wire_revision, min_client_wire_revision]
|
||||
properties:
|
||||
api_version:
|
||||
type: string
|
||||
|
|
@ -7458,7 +7497,7 @@ components:
|
|||
`memories.forget`, `events.list`, `events.watch`,
|
||||
`issues.casMetadata`; the behavior tokens are `project.enforce`,
|
||||
which announces that a `Bd-Project-Id` stamp for the wrong workspace
|
||||
is refused here rather than silently ignored, and
|
||||
is refused here rather than silently ignored,
|
||||
`issues.batchApplyLarge`, which announces that
|
||||
`POST /v0/beads/issues:batchApply` accepts the RAISED envelope —
|
||||
up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB
|
||||
|
|
@ -7472,10 +7511,13 @@ components:
|
|||
server's ordinary deadline exactly as before. A client that
|
||||
checks for this token before sending a plan over 100 items learns
|
||||
whether THIS server accepts it without paying for a round trip an
|
||||
older server would refuse anyway. The list grows additively, and
|
||||
an operation never appears here unless it is fully implemented.
|
||||
This is how a client checks for an operation or a behavior —
|
||||
never the version string.
|
||||
older server would refuse anyway, and `issues.list.sort`, which
|
||||
announces that `GET /v0/beads/issues` accepts the `sort` query
|
||||
parameter (two closed, pageable total orders — see that
|
||||
parameter) rather than silently answering `unknown_parameter`. The
|
||||
list grows additively, and an operation never appears here unless
|
||||
it is fully implemented. This is how a client checks for an
|
||||
operation or a behavior — never the version string.
|
||||
|
||||
|
||||
THIS LIST IS BUILD-LEVEL, NOT WORKSPACE-LEVEL. It says which
|
||||
|
|
@ -7490,6 +7532,176 @@ components:
|
|||
not read the capability as a promise that records will arrive.
|
||||
items:
|
||||
type: string
|
||||
wire_revision:
|
||||
type: integer
|
||||
description: >-
|
||||
A counter bumped on every release whose wire format changed in a
|
||||
way an unaware client could MISDECODE: an existing member's JSON
|
||||
type or meaning changed, or a member was removed or renamed.
|
||||
Adding a brand-new member to an existing schema, or a brand-new
|
||||
operation, is ADDITIVE and never bumps it — an old client simply
|
||||
never asks for the new member and is unaffected. That promise does
|
||||
not extend to a new REQUIRED request input (a request-body member
|
||||
or a parameter): it misdecodes nothing, so it bumps nothing, but an
|
||||
old client that never sends it is refused. The drift gate below
|
||||
records a new required parameter or body member as an ordinary
|
||||
addition and asks for no bump, so keeping old clients working
|
||||
through one is that change's own review's job.
|
||||
|
||||
|
||||
Revision history, and it only ever grows by appending a row:
|
||||
|
||||
|
||||
* `0` — every server before 1.3.0. `revision` and
|
||||
`expected_version` were JSON integers, and this field did not
|
||||
exist: an absent `wire_revision` together with a `bd_version`
|
||||
below `1.3.0` IS a `0`.
|
||||
* `1` — 1.3.0 up to, but not including, the release that adds this
|
||||
field. `revision` and `expected_version` moved to DECIMAL-STRING
|
||||
tokens (#6053) under the same `api_version: "v0"`, with nothing
|
||||
in the handshake to tell an integer-expecting client the shape
|
||||
had moved underneath it. That silent gap is the whole reason
|
||||
this field exists.
|
||||
* `2` — the first release whose `ContextResponse` carries
|
||||
`wire_revision` and `min_client_wire_revision` at all (this one).
|
||||
|
||||
|
||||
PRESENCE, not just value: a generated client whose JSON decoder
|
||||
zero-values a missing integer field cannot tell, by looking at a
|
||||
decoded `0` alone, whether the server SENT `0` or sent nothing.
|
||||
This is never actually ambiguous in practice, because `0` and `1`
|
||||
are PERMANENTLY RETIRED values — they describe servers that predate
|
||||
this field or carried the brief interim string shape, and no
|
||||
server that implements this field (`CurrentWireRevision` starts at
|
||||
`2` and only increases) will ever legitimately send a literal `0`
|
||||
or `1`. A decoded `0` can therefore only mean "this server omitted
|
||||
the field," and a client inferring from `bd_version` per the
|
||||
paragraph below is doing exactly the right thing in that case,
|
||||
never guessing at a value the field could have meant on its own. A
|
||||
client that wants presence as a first-class fact rather than an
|
||||
inference anyway should decode `wire_revision` into a nullable
|
||||
type, or check for the JSON key's presence directly, instead of
|
||||
relying on this retirement guarantee.
|
||||
|
||||
|
||||
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 AND request body member's (schema, member, type,
|
||||
format, enum, required, nullable), plus the item shape of an array
|
||||
member and the value shape of an `additionalProperties` map,
|
||||
recursing through `$ref` and through a schema's own `allOf` or
|
||||
`oneOf`. The same digest also covers every operation PARAMETER
|
||||
(query, path and header) across every operation, keyed by
|
||||
operationId + location + name rather than by schema, recording its
|
||||
type, item shape (for an array parameter), enum, required, style,
|
||||
explode and default — style and explode as their effective values,
|
||||
OpenAPI's defaults filled in where the document leaves them unset.
|
||||
It fails CI the moment any one of these — member or parameter —
|
||||
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, parameter or operation also changes the golden (it is
|
||||
appended to, never frozen in place) but needs no revision bump to
|
||||
pass; the command itself refuses to write a changed or removed
|
||||
entry at an unbumped revision, refuses any write at a LOWER
|
||||
revision than the golden records, and refuses to create a golden
|
||||
that does not exist yet unless run with `-init`. The digest is a
|
||||
boundary, not the whole wire: value constraints such as
|
||||
`maxLength`, `maximum`, `pattern` or `maxItems` are outside it, on
|
||||
members and parameters alike, and so is a composition keyword on a
|
||||
single member's own value (this document uses none); an
|
||||
object-typed parameter, or one described by `content` rather than
|
||||
`schema`, is recorded only as its container. Narrowing a
|
||||
constraint trips no gate, so such a change must be weighed against
|
||||
this counter in its own review.
|
||||
|
||||
|
||||
Every request PARAMETER (query, path or header) and every request
|
||||
BODY MEMBER, added to an EXISTING operation after this document,
|
||||
must carry a capability token in its own description, exactly as
|
||||
`capabilities` members do above —
|
||||
`TestNewParameterOnExistingOperationHasABehaviorToken` enforces it
|
||||
against two frozen baselines
|
||||
(`internal/httpapi/testdata/pretoken_parameters.json` for
|
||||
parameters, `pretoken_request_body_members.json` for body
|
||||
members) of every parameter and body member this document already
|
||||
had the day each rule was written. A member on its baseline is
|
||||
grandfathered and never needs a token; any member not on it —
|
||||
present now or added later, on an operation that already existed
|
||||
when the relevant baseline was frozen — must carry one today. A
|
||||
BRAND-NEW operation (one absent from the third frozen file,
|
||||
`pretoken_operations.json`) is exempt entirely: its own review
|
||||
decides its capability story, not a baseline written before it
|
||||
existed. The token itself must also be one `Capabilities()`
|
||||
actually serves — a backticked string merely shaped like a token
|
||||
proves nothing on its own. All three baselines are written once
|
||||
and never regenerated: only a pre-existing, untokened member or
|
||||
operation ever belongs on them, a newly tokened member satisfies
|
||||
the rule without needing an entry at all, and
|
||||
`TestPretokenBaselinesNeverGrow` pins their sizes so nothing can
|
||||
hand-add a new exemption instead of a token. `issues.list.sort` is
|
||||
the first deliberate use of the parameter rule; it also closes the
|
||||
one gap the rule was written to catch, since `sort` itself shipped
|
||||
(#5666) with no token at all.
|
||||
min_client_wire_revision:
|
||||
type: integer
|
||||
description: >-
|
||||
The OLDEST client `wire_revision` this server still answers
|
||||
correctly. A client whose own compiled `wire_revision` is below
|
||||
this number should refuse to dial at all, the same way it refuses
|
||||
an unknown `api_version`: nothing it does with a response shaped
|
||||
for this revision is safe to assume.
|
||||
|
||||
|
||||
A client MAY declare the revision it was built for on every
|
||||
request with the optional `Bd-Wire-Revision` header (see the
|
||||
document-level rule above). When it does, and the declared value
|
||||
is below this member, the server refuses with `400` /
|
||||
`code: invalid_argument` / `param: "Bd-Wire-Revision"` /
|
||||
`reason: "wire_revision_unsupported"` rather than risk serving a
|
||||
body the caller has already said it cannot decode. The header is
|
||||
OPTIONAL and an absent one is served exactly as today — this is
|
||||
additive wire surface, not a new precondition on requests already
|
||||
in the field, exactly as `Bd-Project-Id` is.
|
||||
|
||||
IssueCount:
|
||||
type: object
|
||||
|
|
@ -11179,13 +11391,19 @@ components:
|
|||
`invalid_value` (the value is not one this server will act on:
|
||||
malformed, out of vocabulary, or — for `limit=0` under
|
||||
`--allow-non-loopback` — legal but refused in this server's
|
||||
configuration; `detail` says which), or `project_mismatch` (the
|
||||
configuration; `detail` says which), `project_mismatch` (the
|
||||
`Bd-Project-Id` header named a project this server does not serve —
|
||||
a document-level refusal like the Host-header 400, raised on every
|
||||
enforced route, and the one that carries `server_project_id`; see
|
||||
the document-level rule). Either way the recovery is to send
|
||||
something different, never to retry the same request. The set may
|
||||
grow; default-branch on unknown values.
|
||||
the document-level rule), or `wire_revision_unsupported` (the
|
||||
`Bd-Wire-Revision` header named a revision below
|
||||
`ContextResponse.min_client_wire_revision` — also a document-level
|
||||
refusal, raised on every route including the identity handshake,
|
||||
and the one that carries `min_wire_revision`; see the
|
||||
document-level rule and `ContextResponse.wire_revision`). Either
|
||||
way the recovery is to send something different, never to retry
|
||||
the same request. The set may grow; default-branch on unknown
|
||||
values.
|
||||
assignee:
|
||||
type: string
|
||||
description: >-
|
||||
|
|
@ -11446,3 +11664,28 @@ components:
|
|||
and never on a refusal raised before the stamp is checked — the Host
|
||||
gate, or a deployment's authentication layer — so its PRESENCE is the
|
||||
signal that this specific check fired.
|
||||
min_wire_revision:
|
||||
type: integer
|
||||
description: >-
|
||||
With `invalid_argument` / `reason: "wire_revision_unsupported"`
|
||||
ONLY: this server's own `ContextResponse.min_client_wire_revision`,
|
||||
so a client that declared a `Bd-Wire-Revision` can log exactly how
|
||||
far behind it is without re-deriving the number from `bd_version`.
|
||||
It is set on that refusal and on no other.
|
||||
wire_revision:
|
||||
type: integer
|
||||
description: >-
|
||||
With `invalid_argument` / `reason: "wire_revision_unsupported"`
|
||||
ONLY: this server's own current `ContextResponse.wire_revision`,
|
||||
alongside `min_wire_revision`, so a client logging the refusal has
|
||||
both ends of the supported range without a second request to
|
||||
`GET /v0/beads/context`. It is set on that refusal and on no
|
||||
other.
|
||||
bd_version:
|
||||
type: string
|
||||
description: >-
|
||||
With `invalid_argument` / `reason: "wire_revision_unsupported"`
|
||||
ONLY: this server's own `ContextResponse.bd_version`, for a client
|
||||
that logs or reports the refusal and wants the release string
|
||||
alongside the two wire-revision numbers rather than a second
|
||||
request to fetch it. It is set on that refusal and on no other.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
package httpapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"regexp"
|
||||
"slices"
|
||||
|
|
@ -419,11 +421,13 @@ func TestSpecDefaultsMatchSharedConstants(t *testing.T) {
|
|||
}
|
||||
|
||||
// capabilityToken matches one backticked capability token in the
|
||||
// `capabilities` description. The shape — a lowercase resource, a dot, a
|
||||
// lowerCamel verb — is what every token on this surface is, and it is narrow
|
||||
// enough that no other backticked word in that paragraph can be mistaken for
|
||||
// one.
|
||||
var capabilityToken = regexp.MustCompile("`([a-z]+\\.[a-zA-Z]+)`")
|
||||
// `capabilities` description. The shape is a lowercase resource, a dot, a
|
||||
// lowerCamel verb, and OPTIONALLY a second dot and a third lowerCamel segment
|
||||
// (`issues.list.sort`, matching the bd-enterprise client's
|
||||
// httpstore/wire/handshake.go:121 and DESIGN.txt §4e) — narrow enough that no
|
||||
// other backticked word in that paragraph can be mistaken for one, but wide
|
||||
// enough for a sub-capability one level below an operation's own token.
|
||||
var capabilityToken = regexp.MustCompile("`([a-z]+\\.[a-zA-Z]+(?:\\.[a-zA-Z]+)?)`")
|
||||
|
||||
// TestSpecCapabilityVocabularyMatchesTheRouteTable is the gate for the ONE
|
||||
// piece of per-operation plumbing that had no gate.
|
||||
|
|
@ -470,6 +474,408 @@ func TestSpecCapabilityVocabularyMatchesTheRouteTable(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
// hasValidCapabilityToken reports whether desc carries at least one
|
||||
// backticked token that is BOTH shaped like a capability (capabilityToken)
|
||||
// AND a member of validTokens. A backticked string that merely looks like a
|
||||
// token — `metadata.json`, say — proves nothing: anyone can put backticks
|
||||
// around two words. Checking membership against the real advertised set is
|
||||
// what makes the token verifiable rather than decorative (review HIGH,
|
||||
// "a token must be one advertised by Capabilities(), not any backticked a.b
|
||||
// text").
|
||||
func hasValidCapabilityToken(desc string, validTokens map[string]bool) bool {
|
||||
for _, m := range capabilityToken.FindAllStringSubmatch(desc, -1) {
|
||||
if validTokens[m[1]] {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// untokenedParameters reports "operationId.paramName" (query/path/header
|
||||
// parameters) and "operationId body.memberName" (request body members, one
|
||||
// level deep) for every undocumented dispatch surface in ops: one whose own
|
||||
// description carries no token that is a member of validTokens, and whose
|
||||
// (operationId, name) pair is not in baseline.
|
||||
//
|
||||
// Two further gates narrow this to a true ratchet rather than a sweep that
|
||||
// would also fire on surface this rule did not exist to judge:
|
||||
//
|
||||
// - existingOps restricts the rule to operations that existed when the rule
|
||||
// was frozen (testdata/pretoken_operations.json). A parameter or body
|
||||
// member on a BRAND-NEW operation is never "missing" a token under this
|
||||
// rule — a new operation's own review is where its capability story gets
|
||||
// decided, not a baseline file written before it existed.
|
||||
// - validTokens restricts what counts as a token at all: shape is not
|
||||
// enough (hasValidCapabilityToken).
|
||||
//
|
||||
// doc resolves the $refs a parameter or request body may point at. baseline
|
||||
// is keyed by operationId to the list of its parameter names exempt from the
|
||||
// rule; bodyBaseline is the same shape for "body.member" names.
|
||||
//
|
||||
// Factored out of TestNewParameterOnExistingOperationHasABehaviorToken so
|
||||
// TestUntokenedParameterRuleFires can falsify it against a fixture with no
|
||||
// dependency on the real document: the rule fires on its own fabricated
|
||||
// miss, not just on whatever this spec currently happens to contain.
|
||||
func untokenedParameters(
|
||||
t *testing.T,
|
||||
doc map[string]any,
|
||||
ops map[string]specOp,
|
||||
baseline map[string][]string,
|
||||
bodyBaseline map[string][]string,
|
||||
existingOps map[string]bool,
|
||||
validTokens map[string]bool,
|
||||
) []string {
|
||||
t.Helper()
|
||||
grandfathered := map[string]bool{}
|
||||
for opID, params := range baseline {
|
||||
for _, p := range params {
|
||||
grandfathered[opID+"\x00"+p] = true
|
||||
}
|
||||
}
|
||||
bodyGrandfathered := map[string]bool{}
|
||||
for opID, members := range bodyBaseline {
|
||||
for _, m := range members {
|
||||
bodyGrandfathered[opID+"\x00"+m] = true
|
||||
}
|
||||
}
|
||||
|
||||
var missing []string
|
||||
for opID, so := range ops {
|
||||
if existingOps != nil && !existingOps[opID] {
|
||||
continue // brand-new operation: its own review decides its tokens.
|
||||
}
|
||||
|
||||
if raw, ok := so.op["parameters"].([]any); ok {
|
||||
for _, r := range raw {
|
||||
pm, ok := r.(map[string]any)
|
||||
if !ok {
|
||||
t.Fatalf("%s: parameter is %T, want a mapping", opID, r)
|
||||
}
|
||||
pm = resolveRef(t, doc, pm)
|
||||
name, _ := pm["name"].(string)
|
||||
if name == "" {
|
||||
t.Fatalf("%s: parameter with no name", opID)
|
||||
}
|
||||
if grandfathered[opID+"\x00"+name] {
|
||||
continue
|
||||
}
|
||||
desc, _ := pm["description"].(string)
|
||||
if !hasValidCapabilityToken(desc, validTokens) {
|
||||
missing = append(missing, opID+"."+name)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for member, desc := range requestBodyMemberDescriptions(t, doc, so) {
|
||||
if bodyGrandfathered[opID+"\x00"+member] {
|
||||
continue
|
||||
}
|
||||
if !hasValidCapabilityToken(desc, validTokens) {
|
||||
missing = append(missing, opID+" body."+member)
|
||||
}
|
||||
}
|
||||
}
|
||||
sort.Strings(missing)
|
||||
return missing
|
||||
}
|
||||
|
||||
// requestBodyMemberDescriptions returns, for so's request body (if any), each
|
||||
// top-level member name mapped to its own description. Every request body in
|
||||
// this document is `required: true` with a single application/json media
|
||||
// type whose schema is a direct $ref to a named object schema with no allOf —
|
||||
// simple enough that one level of property-walking covers all of them; a
|
||||
// future body shaped any other way will simply report no members here rather
|
||||
// than silently miscounting, which TestRequestBodyMembersCoversEveryBody (if
|
||||
// that ever becomes necessary) would be the place to pin.
|
||||
func requestBodyMemberDescriptions(t *testing.T, doc map[string]any, so specOp) map[string]string {
|
||||
t.Helper()
|
||||
rb, ok := so.op["requestBody"].(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
content, ok := rb["content"].(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
media, ok := content["application/json"].(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
schemaRef, ok := media["schema"].(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
schema := resolveRef(t, doc, schemaRef)
|
||||
props, ok := schema["properties"].(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
out := map[string]string{}
|
||||
for member, raw := range props {
|
||||
pm, ok := raw.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
pm = resolveRef(t, doc, pm)
|
||||
desc, _ := pm["description"].(string)
|
||||
out[member] = desc
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func loadPretokenBaseline(t *testing.T) map[string][]string {
|
||||
t.Helper()
|
||||
return loadJSONStringMap(t, "pretoken_parameters.json")
|
||||
}
|
||||
|
||||
// loadPretokenBodyBaseline is loadPretokenBaseline's sibling for request body
|
||||
// members (review MEDIUM, "extend the rule to request-body members on
|
||||
// existing operations"): same write-once-grandfather shape, keyed by
|
||||
// operationId to the "body.member" names that already existed, untokened,
|
||||
// the day body-member coverage was added.
|
||||
func loadPretokenBodyBaseline(t *testing.T) map[string][]string {
|
||||
t.Helper()
|
||||
return loadJSONStringMap(t, "pretoken_request_body_members.json")
|
||||
}
|
||||
|
||||
func loadJSONStringMap(t *testing.T, filename string) map[string][]string {
|
||||
t.Helper()
|
||||
blob, err := os.ReadFile(filepath.Join("testdata", filename))
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", filename, err)
|
||||
}
|
||||
var out map[string][]string
|
||||
if err := json.Unmarshal(blob, &out); err != nil {
|
||||
t.Fatalf("decode testdata/%s: %v", filename, err)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// loadPretokenOperations is the review's "don't fire on brand-new
|
||||
// operations" gate: the set of operationIds that existed the day the
|
||||
// untokened-parameter rule (and its body-member extension) was frozen. An
|
||||
// operation not in this file is new, and gets no say from either baseline —
|
||||
// its own code review decides its capability story.
|
||||
func loadPretokenOperations(t *testing.T) map[string]bool {
|
||||
t.Helper()
|
||||
blob, err := os.ReadFile(filepath.Join("testdata", "pretoken_operations.json"))
|
||||
if err != nil {
|
||||
t.Fatalf("read pretoken operations: %v", err)
|
||||
}
|
||||
var list []string
|
||||
if err := json.Unmarshal(blob, &list); err != nil {
|
||||
t.Fatalf("decode testdata/pretoken_operations.json: %v", err)
|
||||
}
|
||||
out := make(map[string]bool, len(list))
|
||||
for _, id := range list {
|
||||
out[id] = true
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// servedCapabilities is validTokens for the real document: exactly what
|
||||
// Capabilities() advertises right now, which is also what
|
||||
// TestSpecCapabilityVocabularyMatchesTheRouteTable pins the spec prose to.
|
||||
func servedCapabilities() map[string]bool {
|
||||
out := map[string]bool{}
|
||||
for _, token := range Capabilities() {
|
||||
out[token] = true
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// TestNewParameterOnExistingOperationHasABehaviorToken is the lint rule S0
|
||||
// item 4 asks for: a parameter on an existing operation with no capability
|
||||
// token in its own description is undocumented dispatch surface — a client
|
||||
// has no way to learn THIS server accepts it without sending it and risking
|
||||
// `unknown_parameter`, which is exactly what happened to `sort` (#5666)
|
||||
// before `issues.list.sort` closed the gap.
|
||||
//
|
||||
// The baseline (testdata/pretoken_parameters.json) is a WRITE-ONCE grandfather
|
||||
// list: every parameter this document already had the day the rule was
|
||||
// written, captured by walking the spec with this same token regex. A
|
||||
// parameter on it is exempt permanently, and nothing here ever regenerates
|
||||
// the file. Any parameter not on it — present today or added by any later
|
||||
// change — must carry a token, which is what makes this a ratchet rather than
|
||||
// a one-time sweep: `issues.list.sort` is already the parity fix the rule's
|
||||
// own baseline is built from, not an exemption to it.
|
||||
func TestNewParameterOnExistingOperationHasABehaviorToken(t *testing.T) {
|
||||
doc := loadSpec(t)
|
||||
ops := specOps(t, doc)
|
||||
baseline := loadPretokenBaseline(t)
|
||||
bodyBaseline := loadPretokenBodyBaseline(t)
|
||||
existingOps := loadPretokenOperations(t)
|
||||
valid := servedCapabilities()
|
||||
|
||||
if missing := untokenedParameters(t, doc, ops, baseline, bodyBaseline, existingOps, valid); len(missing) > 0 {
|
||||
t.Errorf("parameter(s) or request body member(s) on an existing operation carry no capability token "+
|
||||
"that Capabilities() actually serves, and are not on the frozen baseline "+
|
||||
"(internal/httpapi/testdata/pretoken_parameters.json / pretoken_request_body_members.json): %v\n"+
|
||||
"add a `resource.verb` token to the member's own description, the way `sort` on "+
|
||||
"GET /v0/beads/issues advertises `issues.list.sort`", missing)
|
||||
}
|
||||
}
|
||||
|
||||
// TestPretokenBaselinesNeverGrow pins the three frozen testdata files at
|
||||
// their current size (review MEDIUM, "the baseline must never grow"):
|
||||
// nothing here ever regenerates them, so the only way their counts change is
|
||||
// someone hand-editing a new exemption in, which is exactly what this guards
|
||||
// against. A legitimate new parameter or body member must carry its own
|
||||
// token, not an entry on these files; a legitimate new OPERATION is added to
|
||||
// pretoken_operations.json never — new operations are simply never members of
|
||||
// it, by construction, since nothing regenerates it either.
|
||||
func TestPretokenBaselinesNeverGrow(t *testing.T) {
|
||||
const (
|
||||
wantParamEntries = 137
|
||||
wantBodyEntries = 85
|
||||
wantOps = 41
|
||||
)
|
||||
baseline := loadPretokenBaseline(t)
|
||||
paramEntries := 0
|
||||
for _, params := range baseline {
|
||||
paramEntries += len(params)
|
||||
}
|
||||
if paramEntries != wantParamEntries {
|
||||
t.Errorf("testdata/pretoken_parameters.json has %d grandfathered parameters, want exactly %d "+
|
||||
"(frozen the day the rule was written); if this moved, something added a new exemption instead "+
|
||||
"of a token", paramEntries, wantParamEntries)
|
||||
}
|
||||
|
||||
bodyBaseline := loadPretokenBodyBaseline(t)
|
||||
bodyEntries := 0
|
||||
for _, members := range bodyBaseline {
|
||||
bodyEntries += len(members)
|
||||
}
|
||||
if bodyEntries != wantBodyEntries {
|
||||
t.Errorf("testdata/pretoken_request_body_members.json has %d grandfathered body members, want exactly %d",
|
||||
bodyEntries, wantBodyEntries)
|
||||
}
|
||||
|
||||
existingOps := loadPretokenOperations(t)
|
||||
if len(existingOps) != wantOps {
|
||||
t.Errorf("testdata/pretoken_operations.json has %d operations, want exactly %d "+
|
||||
"(frozen the day the new-operation exemption was added)", len(existingOps), wantOps)
|
||||
}
|
||||
}
|
||||
|
||||
// TestUntokenedParameterRuleFires is the rule's own falsification, required
|
||||
// because TestNewParameterOnExistingOperationHasABehaviorToken is permanently
|
||||
// green against a spec written to satisfy it: a synthetic operation proves
|
||||
// the CHECK itself still distinguishes the cases it exists to tell apart,
|
||||
// independent of anything the real document currently says.
|
||||
func TestUntokenedParameterRuleFires(t *testing.T) {
|
||||
doc := map[string]any{} // no $refs in the fixtures below; resolveRef never consults it
|
||||
newOp := func(desc string) specOp {
|
||||
return specOp{
|
||||
method: "GET",
|
||||
path: "/synthetic",
|
||||
op: map[string]any{
|
||||
"parameters": []any{
|
||||
map[string]any{"name": "widget", "description": desc},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
noBody := map[string][]string{}
|
||||
allExisting := map[string]bool{"syntheticOp": true}
|
||||
validTokens := map[string]bool{"synthetic.widget": true, "issues.list": true}
|
||||
|
||||
ops := map[string]specOp{"syntheticOp": newOp("plain prose, no token at all")}
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, allExisting, validTokens); !slices.Equal(got, []string{"syntheticOp.widget"}) {
|
||||
t.Fatalf("untokened, non-grandfathered parameter: got %v, want [syntheticOp.widget]", got)
|
||||
}
|
||||
|
||||
if got := untokenedParameters(t, doc, ops, map[string][]string{"syntheticOp": {"widget"}}, noBody, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("grandfathered parameter still reported: got %v, want none", got)
|
||||
}
|
||||
|
||||
ops["syntheticOp"] = newOp("carries the `synthetic.widget` token")
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("tokened parameter still reported: got %v, want none", got)
|
||||
}
|
||||
|
||||
// A backticked string shaped like a token but not one Capabilities()
|
||||
// actually serves must still fire: shape alone is not proof (review HIGH).
|
||||
ops["syntheticOp"] = newOp("see `metadata.json` for details")
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, allExisting, validTokens); !slices.Equal(got, []string{"syntheticOp.widget"}) {
|
||||
t.Fatalf("bogus (unserved) token: got %v, want [syntheticOp.widget]", got)
|
||||
}
|
||||
|
||||
// A REAL token, just not one this parameter actually advertises, passes:
|
||||
// Capabilities() has no per-parameter binding to check against, so
|
||||
// membership in the served set is the full extent of this rule (review
|
||||
// HIGH says "a token must be one advertised by Capabilities()", not that
|
||||
// it must be the specific token for this parameter).
|
||||
ops["syntheticOp"] = newOp("reuses an unrelated real token (`issues.list`)")
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("real-but-unrelated token: got %v, want none", got)
|
||||
}
|
||||
|
||||
// A brand-new operation (absent from the existingOps baseline) is exempt
|
||||
// even with no token at all (review MEDIUM, "don't fire on brand-new
|
||||
// operations"). syntheticOp still carries its real-but-unrelated token
|
||||
// from the previous case, so it reports nothing either.
|
||||
ops["brandNewOp"] = newOp("plain prose, no token at all")
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("brand-new operation must not be reported: got %v", got)
|
||||
}
|
||||
// And a nil existingOps (the behavior with no freeze gate at all) does
|
||||
// catch it, so the gate is additive, not a silent replacement for the
|
||||
// baseline check.
|
||||
if got := untokenedParameters(t, doc, ops, noBody, noBody, nil, validTokens); !slices.Equal(got, []string{"brandNewOp.widget"}) {
|
||||
t.Fatalf("nil existingOps must not exempt anything: got %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestUntokenedRequestBodyMemberRuleFires is TestUntokenedParameterRuleFires'
|
||||
// sibling for request body members (review MEDIUM, "extend the rule to
|
||||
// request-body members on existing operations").
|
||||
func TestUntokenedRequestBodyMemberRuleFires(t *testing.T) {
|
||||
doc := map[string]any{
|
||||
"components": map[string]any{
|
||||
"schemas": map[string]any{
|
||||
"SyntheticRequest": map[string]any{
|
||||
"type": "object",
|
||||
"properties": map[string]any{
|
||||
"widget": map[string]any{"type": "string", "description": "plain prose, no token at all"},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
so := specOp{
|
||||
method: "POST",
|
||||
path: "/synthetic",
|
||||
op: map[string]any{
|
||||
"requestBody": map[string]any{
|
||||
"content": map[string]any{
|
||||
"application/json": map[string]any{
|
||||
"schema": map[string]any{"$ref": "#/components/schemas/SyntheticRequest"},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
ops := map[string]specOp{"syntheticOp": so}
|
||||
noParams := map[string][]string{}
|
||||
allExisting := map[string]bool{"syntheticOp": true}
|
||||
validTokens := map[string]bool{"synthetic.widget": true}
|
||||
|
||||
if got := untokenedParameters(t, doc, ops, noParams, noParams, allExisting, validTokens); !slices.Equal(got, []string{"syntheticOp body.widget"}) {
|
||||
t.Fatalf("untokened, non-grandfathered body member: got %v, want [syntheticOp body.widget]", got)
|
||||
}
|
||||
|
||||
if got := untokenedParameters(t, doc, ops, noParams, map[string][]string{"syntheticOp": {"widget"}}, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("grandfathered body member still reported: got %v, want none", got)
|
||||
}
|
||||
|
||||
props := doc["components"].(map[string]any)["schemas"].(map[string]any)["SyntheticRequest"].(map[string]any)["properties"].(map[string]any)
|
||||
props["widget"] = map[string]any{"type": "string", "description": "carries the `synthetic.widget` token"}
|
||||
if got := untokenedParameters(t, doc, ops, noParams, noParams, allExisting, validTokens); len(got) != 0 {
|
||||
t.Fatalf("tokened body member still reported: got %v, want none", got)
|
||||
}
|
||||
}
|
||||
|
||||
func specParam(t *testing.T, so specOp, name string) map[string]any {
|
||||
t.Helper()
|
||||
raw, ok := so.op["parameters"].([]any)
|
||||
|
|
@ -682,7 +1088,8 @@ func TestDefaultsMatchCLIFlags(t *testing.T) {
|
|||
// re-adding one costs a test edit.
|
||||
var contextResponseAllowlist = []string{
|
||||
"api_version", "backend", "bd_version", "beads_dir", "capabilities",
|
||||
"database", "dolt_mode", "project_id", "repo_root", "schema_version",
|
||||
"database", "dolt_mode", "min_client_wire_revision", "project_id",
|
||||
"repo_root", "schema_version", "wire_revision",
|
||||
}
|
||||
|
||||
// TestContextResponseAllowlist pins that field set from both sides: the
|
||||
|
|
|
|||
43
internal/httpapi/testdata/pretoken_operations.json
vendored
Normal file
43
internal/httpapi/testdata/pretoken_operations.json
vendored
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
[
|
||||
"addComment",
|
||||
"addDependencies",
|
||||
"applyBatch",
|
||||
"batchCloseIssues",
|
||||
"batchCreateIssues",
|
||||
"claimIssue",
|
||||
"claimNextIssue",
|
||||
"closeIssue",
|
||||
"compareAndSetMetadata",
|
||||
"countDependencyEdges",
|
||||
"countIssues",
|
||||
"countReadyWork",
|
||||
"createIssue",
|
||||
"deleteIssues",
|
||||
"forgetMemory",
|
||||
"getContext",
|
||||
"getDependencyTree",
|
||||
"getIssue",
|
||||
"getMemory",
|
||||
"getSetting",
|
||||
"getStats",
|
||||
"health",
|
||||
"listBlockingAnnotations",
|
||||
"listDependencies",
|
||||
"listDependencyCycles",
|
||||
"listEvents",
|
||||
"listIssues",
|
||||
"listMemories",
|
||||
"listReadyWork",
|
||||
"listRelatedIssues",
|
||||
"listSettings",
|
||||
"queryIssues",
|
||||
"releaseIssue",
|
||||
"rememberMemory",
|
||||
"removeDependency",
|
||||
"reopenIssue",
|
||||
"setSetting",
|
||||
"sweepIssues",
|
||||
"unsetSetting",
|
||||
"updateIssue",
|
||||
"watchEvents"
|
||||
]
|
||||
195
internal/httpapi/testdata/pretoken_parameters.json
vendored
Normal file
195
internal/httpapi/testdata/pretoken_parameters.json
vendored
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
{
|
||||
"addComment": [
|
||||
"id"
|
||||
],
|
||||
"claimIssue": [
|
||||
"id"
|
||||
],
|
||||
"claimNextIssue": [
|
||||
"assignee",
|
||||
"exclude_label",
|
||||
"exclude_type",
|
||||
"has_metadata_key",
|
||||
"include_deferred",
|
||||
"include_ephemeral",
|
||||
"label",
|
||||
"label_any",
|
||||
"label_pattern",
|
||||
"label_regex",
|
||||
"metadata_field",
|
||||
"parent",
|
||||
"priority",
|
||||
"sort",
|
||||
"type",
|
||||
"unassigned"
|
||||
],
|
||||
"closeIssue": [
|
||||
"id"
|
||||
],
|
||||
"compareAndSetMetadata": [
|
||||
"id"
|
||||
],
|
||||
"countDependencyEdges": [
|
||||
"direction",
|
||||
"issue_id",
|
||||
"status",
|
||||
"type"
|
||||
],
|
||||
"countIssues": [
|
||||
"assignee",
|
||||
"closed_after",
|
||||
"closed_before",
|
||||
"created_after",
|
||||
"created_before",
|
||||
"desc_contains",
|
||||
"empty_description",
|
||||
"group_by",
|
||||
"has_metadata_key",
|
||||
"id",
|
||||
"include_ephemeral",
|
||||
"include_infra",
|
||||
"label",
|
||||
"label_any",
|
||||
"metadata_field",
|
||||
"no_assignee",
|
||||
"no_labels",
|
||||
"notes_contains",
|
||||
"priority",
|
||||
"priority_max",
|
||||
"priority_min",
|
||||
"status",
|
||||
"title",
|
||||
"title_contains",
|
||||
"type",
|
||||
"updated_after",
|
||||
"updated_before"
|
||||
],
|
||||
"countReadyWork": [
|
||||
"assignee",
|
||||
"exclude_label",
|
||||
"exclude_type",
|
||||
"has_metadata_key",
|
||||
"include_deferred",
|
||||
"include_ephemeral",
|
||||
"label",
|
||||
"label_any",
|
||||
"label_pattern",
|
||||
"label_regex",
|
||||
"metadata_field",
|
||||
"parent",
|
||||
"priority",
|
||||
"type",
|
||||
"unassigned"
|
||||
],
|
||||
"forgetMemory": [
|
||||
"key"
|
||||
],
|
||||
"getDependencyTree": [
|
||||
"direction",
|
||||
"max_depth",
|
||||
"root_id",
|
||||
"status"
|
||||
],
|
||||
"getIssue": [
|
||||
"brief_deps",
|
||||
"id",
|
||||
"include_comments",
|
||||
"include_dependents"
|
||||
],
|
||||
"getMemory": [
|
||||
"key"
|
||||
],
|
||||
"getSetting": [
|
||||
"key"
|
||||
],
|
||||
"getStats": [
|
||||
"assignee",
|
||||
"skip_blocked"
|
||||
],
|
||||
"listBlockingAnnotations": [
|
||||
"issue_id"
|
||||
],
|
||||
"listDependencies": [
|
||||
"issue_id",
|
||||
"type"
|
||||
],
|
||||
"listEvents": [
|
||||
"limit",
|
||||
"since"
|
||||
],
|
||||
"listIssues": [
|
||||
"all",
|
||||
"assignee",
|
||||
"brief",
|
||||
"created_after",
|
||||
"created_before",
|
||||
"cursor",
|
||||
"exclude_label",
|
||||
"has_metadata_key",
|
||||
"include_ephemeral",
|
||||
"include_gates",
|
||||
"include_infra",
|
||||
"include_templates",
|
||||
"label",
|
||||
"label_any",
|
||||
"limit",
|
||||
"metadata_field",
|
||||
"parent",
|
||||
"status",
|
||||
"type"
|
||||
],
|
||||
"listMemories": [
|
||||
"search"
|
||||
],
|
||||
"listReadyWork": [
|
||||
"assignee",
|
||||
"brief",
|
||||
"exclude_label",
|
||||
"exclude_type",
|
||||
"has_metadata_key",
|
||||
"include_deferred",
|
||||
"include_ephemeral",
|
||||
"label",
|
||||
"label_any",
|
||||
"label_pattern",
|
||||
"label_regex",
|
||||
"limit",
|
||||
"metadata_field",
|
||||
"parent",
|
||||
"priority",
|
||||
"sort",
|
||||
"type",
|
||||
"unassigned"
|
||||
],
|
||||
"listRelatedIssues": [
|
||||
"direction",
|
||||
"id",
|
||||
"type"
|
||||
],
|
||||
"queryIssues": [
|
||||
"all",
|
||||
"limit",
|
||||
"q",
|
||||
"reverse",
|
||||
"sort"
|
||||
],
|
||||
"releaseIssue": [
|
||||
"id"
|
||||
],
|
||||
"reopenIssue": [
|
||||
"id"
|
||||
],
|
||||
"setSetting": [
|
||||
"key"
|
||||
],
|
||||
"unsetSetting": [
|
||||
"key"
|
||||
],
|
||||
"updateIssue": [
|
||||
"id"
|
||||
],
|
||||
"watchEvents": [
|
||||
"Last-Event-ID",
|
||||
"since"
|
||||
]
|
||||
}
|
||||
123
internal/httpapi/testdata/pretoken_request_body_members.json
vendored
Normal file
123
internal/httpapi/testdata/pretoken_request_body_members.json
vendored
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
{
|
||||
"addComment": [
|
||||
"author",
|
||||
"text"
|
||||
],
|
||||
"addDependencies": [
|
||||
"actor",
|
||||
"edges"
|
||||
],
|
||||
"applyBatch": [
|
||||
"actor",
|
||||
"force_id_prefix",
|
||||
"items",
|
||||
"provenance",
|
||||
"skip_per_edge_cycle_check"
|
||||
],
|
||||
"batchCloseIssues": [
|
||||
"actor",
|
||||
"force",
|
||||
"items",
|
||||
"session"
|
||||
],
|
||||
"batchCreateIssues": [
|
||||
"actor",
|
||||
"items"
|
||||
],
|
||||
"claimIssue": [
|
||||
"actor"
|
||||
],
|
||||
"claimNextIssue": [
|
||||
"actor"
|
||||
],
|
||||
"closeIssue": [
|
||||
"actor",
|
||||
"expected_version",
|
||||
"force",
|
||||
"reason",
|
||||
"session"
|
||||
],
|
||||
"compareAndSetMetadata": [
|
||||
"actor",
|
||||
"expected",
|
||||
"key",
|
||||
"value"
|
||||
],
|
||||
"createIssue": [
|
||||
"acceptance_criteria",
|
||||
"actor",
|
||||
"assignee",
|
||||
"defer_until",
|
||||
"dependencies",
|
||||
"description",
|
||||
"design",
|
||||
"due_at",
|
||||
"ephemeral",
|
||||
"estimated_minutes",
|
||||
"external_ref",
|
||||
"force_id_prefix",
|
||||
"id",
|
||||
"inherit_labels_from_parent",
|
||||
"issue_type",
|
||||
"labels",
|
||||
"metadata",
|
||||
"no_history",
|
||||
"notes",
|
||||
"owner",
|
||||
"parent_id",
|
||||
"priority",
|
||||
"sender",
|
||||
"status",
|
||||
"title",
|
||||
"waits_for"
|
||||
],
|
||||
"deleteIssues": [
|
||||
"actor",
|
||||
"cascade",
|
||||
"dry_run",
|
||||
"expected_version",
|
||||
"force",
|
||||
"ids"
|
||||
],
|
||||
"releaseIssue": [
|
||||
"actor",
|
||||
"expected_assignee",
|
||||
"force"
|
||||
],
|
||||
"rememberMemory": [
|
||||
"content",
|
||||
"key"
|
||||
],
|
||||
"removeDependency": [
|
||||
"actor",
|
||||
"depends_on_id",
|
||||
"issue_id"
|
||||
],
|
||||
"reopenIssue": [
|
||||
"actor",
|
||||
"expected_version",
|
||||
"reason"
|
||||
],
|
||||
"setSetting": [
|
||||
"value"
|
||||
],
|
||||
"sweepIssues": [
|
||||
"actor",
|
||||
"closed_before",
|
||||
"dry_run",
|
||||
"pattern",
|
||||
"protect_referenced",
|
||||
"tier"
|
||||
],
|
||||
"updateIssue": [
|
||||
"actor",
|
||||
"claim",
|
||||
"expected_assignee",
|
||||
"expected_status",
|
||||
"expected_version",
|
||||
"force_assignee_transfer",
|
||||
"force_close_policy",
|
||||
"force_notes_overwrite",
|
||||
"patch"
|
||||
]
|
||||
}
|
||||
99
internal/httpapi/wire_revision.go
Normal file
99
internal/httpapi/wire_revision.go
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
package httpapi
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// WireRevisionHeader names the optional per-request wire-floor declaration. A
|
||||
// client that knows the revision it was compiled against puts that revision
|
||||
// here; checkWireRevision refuses the request when it names a revision below
|
||||
// MinClientWireRevision, before the client can act on a body shaped for a
|
||||
// revision it has already said it cannot decode. The header is optional and
|
||||
// absent by default: an older client that never sends it is served exactly as
|
||||
// before, which is what keeps this additive rather than a new precondition.
|
||||
const WireRevisionHeader = "Bd-Wire-Revision"
|
||||
|
||||
// CurrentWireRevision is ContextResponse.wire_revision: the wire-shape counter
|
||||
// for THIS build. See the `wire_revision` property in openapi.v0.yaml for the
|
||||
// full revision history and what bumps it. It increases only alongside a
|
||||
// deliberate, non-additive wire change AND a matching update to the
|
||||
// internal/httpapi/wireshape golden digest — TestWireShapeDigest fails closed
|
||||
// the moment the two disagree.
|
||||
const CurrentWireRevision = 2
|
||||
|
||||
// MinClientWireRevision is ContextResponse.min_client_wire_revision: the
|
||||
// oldest client-declared revision this build still answers correctly. Raising
|
||||
// it is the deliberate act of dropping support for clients built against an
|
||||
// older wire shape; it must never exceed CurrentWireRevision.
|
||||
const MinClientWireRevision = 0
|
||||
|
||||
// checkWireRevision enforces the optional per-request wire-floor declaration.
|
||||
// A client that knows the revision it was compiled against may assert it in
|
||||
// the Bd-Wire-Revision header; if that revision is below s.minClientWireRevision,
|
||||
// the request is refused before the server spends any work building a body the
|
||||
// caller has already said it cannot decode. It returns nil when the request
|
||||
// may proceed, or the 400 to write.
|
||||
//
|
||||
// s.minClientWireRevision starts at the package constant MinClientWireRevision
|
||||
// and is a Server field — rather than a direct read of that constant — only so
|
||||
// a test can raise the floor; production never overrides it.
|
||||
//
|
||||
// Three paths return nil. An ABSENT header is the backward-compatible one: an
|
||||
// older client never sends it, so enforcement triggers only when the header
|
||||
// arrives and adds no precondition to any request already in the field. A
|
||||
// non-negative integer at or above s.minClientWireRevision is in range. A value
|
||||
// that fails to parse as a non-negative integer is NOT this check's refusal —
|
||||
// it is a malformed header, reported as `invalid_value` rather than
|
||||
// `wire_revision_unsupported`, which is reserved for a revision this server
|
||||
// has read and understood to be too old.
|
||||
//
|
||||
// The refusal is recorded on the request line like every other middleware
|
||||
// refusal, so a client persistently declaring a dropped revision is
|
||||
// attributable down to the local process.
|
||||
func (s *Server) checkWireRevision(r *http.Request) *Result {
|
||||
raw := r.Header.Get(WireRevisionHeader)
|
||||
if raw == "" {
|
||||
return nil
|
||||
}
|
||||
got, ok := parseStrictNonNegativeInt(raw)
|
||||
if !ok {
|
||||
requestInfo(r.Context()).refuse(raw)
|
||||
res := InvalidArgument(WireRevisionHeader, ReasonInvalidValue,
|
||||
"the "+WireRevisionHeader+" header must be a non-negative integer")
|
||||
return &res
|
||||
}
|
||||
if got >= s.minClientWireRevision {
|
||||
return nil
|
||||
}
|
||||
requestInfo(r.Context()).refuse(raw)
|
||||
res := WireRevisionUnsupported(got, s.minClientWireRevision, CurrentWireRevision, s.ctxBody.BdVersion)
|
||||
return &res
|
||||
}
|
||||
|
||||
// parseStrictNonNegativeInt accepts exactly the plain-decimal shape this
|
||||
// header is documented to carry: one or more ASCII digits, no sign, and no
|
||||
// leading zero unless the whole value is the single digit "0". strconv.Atoi
|
||||
// alone is looser than that — it also accepts a leading "+", and it accepts
|
||||
// leading zeros like "007" — both of which would let two different header
|
||||
// bytes name the same revision, which is a wire ambiguity this header exists
|
||||
// to avoid, not a client convenience to extend to it.
|
||||
func parseStrictNonNegativeInt(raw string) (int, bool) {
|
||||
if raw == "" || strings.ContainsAny(raw, "+-") {
|
||||
return 0, false
|
||||
}
|
||||
if len(raw) > 1 && raw[0] == '0' {
|
||||
return 0, false
|
||||
}
|
||||
for _, c := range raw {
|
||||
if c < '0' || c > '9' {
|
||||
return 0, false
|
||||
}
|
||||
}
|
||||
got, err := strconv.Atoi(raw)
|
||||
if err != nil {
|
||||
return 0, false
|
||||
}
|
||||
return got, true
|
||||
}
|
||||
252
internal/httpapi/wire_revision_test.go
Normal file
252
internal/httpapi/wire_revision_test.go
Normal file
|
|
@ -0,0 +1,252 @@
|
|||
package httpapi
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"slices"
|
||||
"strconv"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// These are pure, like the rest of the package's edge tests: the whole
|
||||
// request lifecycle runs over a real listener against a fake provider, so the
|
||||
// Bd-Wire-Revision gate — where it sits in route(), what it refuses, and
|
||||
// that it reaches the identity handshake too — is covered on every pull
|
||||
// request by the unconditional Go test job.
|
||||
|
||||
// wireRevisioned drives a request carrying (or omitting) the Bd-Wire-Revision
|
||||
// header. An empty raw value sends no header at all, which is the
|
||||
// backward-compatible path.
|
||||
func (ts *testServer) wireRevisioned(t *testing.T, method, path, raw string) *http.Response {
|
||||
t.Helper()
|
||||
req, err := http.NewRequest(method, ts.base+path, nil)
|
||||
if err != nil {
|
||||
t.Fatalf("new %s %s: %v", method, path, err)
|
||||
}
|
||||
if raw != "" {
|
||||
req.Header.Set(WireRevisionHeader, raw)
|
||||
}
|
||||
resp, err := ts.client.Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("%s %s: %v", method, path, err)
|
||||
}
|
||||
t.Cleanup(func() { _ = resp.Body.Close() })
|
||||
return resp
|
||||
}
|
||||
|
||||
func assertWireRevisionUnsupported(t *testing.T, resp *http.Response, wantMin int) {
|
||||
t.Helper()
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
|
||||
}
|
||||
if got := resp.Header.Get("Content-Type"); got != "application/problem+json; charset=utf-8" {
|
||||
t.Errorf("Content-Type = %q, want problem+json", got)
|
||||
}
|
||||
body := decodeBody(t, resp)
|
||||
if body["code"] != string(CodeInvalidArgument) {
|
||||
t.Errorf("code = %v, want %s", body["code"], CodeInvalidArgument)
|
||||
}
|
||||
if body["param"] != WireRevisionHeader {
|
||||
t.Errorf("param = %v, want %s", body["param"], WireRevisionHeader)
|
||||
}
|
||||
if body["reason"] != string(ReasonWireRevisionUnsupported) {
|
||||
t.Errorf("reason = %v, want %s", body["reason"], ReasonWireRevisionUnsupported)
|
||||
}
|
||||
// The one member that scopes the disclosure: it carries this server's own
|
||||
// floor, and it is present ONLY on this refusal.
|
||||
min, ok := body["min_wire_revision"].(float64)
|
||||
if !ok || int(min) != wantMin {
|
||||
t.Errorf("min_wire_revision = %#v, want %d", body["min_wire_revision"], wantMin)
|
||||
}
|
||||
// wire_revision and bd_version ride alongside min_wire_revision on this
|
||||
// same refusal, so a client logging it can report what this server
|
||||
// currently is without a second /v0/beads/context round trip.
|
||||
wire, ok := body["wire_revision"].(float64)
|
||||
if !ok || int(wire) != CurrentWireRevision {
|
||||
t.Errorf("wire_revision = %#v, want %d", body["wire_revision"], CurrentWireRevision)
|
||||
}
|
||||
// bd_version mirrors this server's own ContextResponse.bd_version, which a
|
||||
// bare test fixture with no version wired in reports as "" — a string, not
|
||||
// an absence, is what's being pinned here.
|
||||
if _, ok := body["bd_version"].(string); !ok {
|
||||
t.Errorf("bd_version = %#v, want a string", body["bd_version"])
|
||||
}
|
||||
}
|
||||
|
||||
// wireRevisionReadServer is newReadServer's provider wiring (reads_test.go),
|
||||
// needed here because /v0/beads/ready 500s against the bare default
|
||||
// fakeProvider{} newTestServer(t, Config{}) otherwise falls back to — that
|
||||
// fake answers the claim path only, not a read.
|
||||
func wireRevisionReadServer(t *testing.T, tune ...func(*Server)) *testServer {
|
||||
t.Helper()
|
||||
cfg := Config{Provider: &fakeProvider{
|
||||
issues: &fakeIssues{},
|
||||
readIssues: &recordingIssues{},
|
||||
readConfig: emptyConfig{},
|
||||
}}
|
||||
return newTestServer(t, cfg, tune...)
|
||||
}
|
||||
|
||||
// TestWireRevisionAbsentIsTodaysBehavior is the backward-compatibility
|
||||
// contract: a client that sends no Bd-Wire-Revision header is served exactly
|
||||
// as before, on both an ordinary route and the identity handshake.
|
||||
func TestWireRevisionAbsentIsTodaysBehavior(t *testing.T) {
|
||||
ts := wireRevisionReadServer(t)
|
||||
|
||||
for _, path := range []string{"/v0/beads/ready", "/v0/beads/context"} {
|
||||
resp := ts.wireRevisioned(t, http.MethodGet, path, "")
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Errorf("GET %s with no header = %d, want 200: %s", path, resp.StatusCode, readAll(t, resp))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestWireRevisionAtOrAboveFloorServes: a declared revision at or above
|
||||
// MinClientWireRevision is in range and the request runs exactly as an
|
||||
// undeclared one does.
|
||||
func TestWireRevisionAtOrAboveFloorServes(t *testing.T) {
|
||||
ts := wireRevisionReadServer(t)
|
||||
|
||||
resp := ts.wireRevisioned(t, http.MethodGet, "/v0/beads/ready", strconv.Itoa(MinClientWireRevision))
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Fatalf("status = %d, want 200 for a floor-equal revision: %s", resp.StatusCode, readAll(t, resp))
|
||||
}
|
||||
}
|
||||
|
||||
// TestWireRevisionBelowFloorRefusesEveryEnforcedRoute mirrors
|
||||
// TestProjectStampMismatchRefusesEveryEnforcedRoute: a declared revision below
|
||||
// the server's floor is refused on an ordinary read AND on the identity
|
||||
// handshake — the one route Bd-Project-Id is exempt on but this header is
|
||||
// deliberately not, since the handshake is where catching the mismatch is
|
||||
// cheapest.
|
||||
//
|
||||
// The floor is raised to 3 via the tune hook (mirroring semTimeout et al in
|
||||
// newTestServer's tune pattern) rather than read at its production default of
|
||||
// 0: a non-negative integer strictly below a floor of 0 does not exist, so
|
||||
// MinClientWireRevision itself could never exercise this path.
|
||||
func TestWireRevisionBelowFloorRefusesEveryEnforcedRoute(t *testing.T) {
|
||||
const floor = 3
|
||||
ts := wireRevisionReadServer(t, func(s *Server) { s.minClientWireRevision = floor })
|
||||
below := strconv.Itoa(floor - 1)
|
||||
|
||||
for _, path := range []string{"/v0/beads/ready", "/v0/beads/context"} {
|
||||
t.Run(path, func(t *testing.T) {
|
||||
resp := ts.wireRevisioned(t, http.MethodGet, path, below)
|
||||
assertWireRevisionUnsupported(t, resp, floor)
|
||||
})
|
||||
}
|
||||
|
||||
// Attributable, like every other middleware refusal.
|
||||
line := findLogLine(t, ts.stderr.String(), "op="+OpListReadyWork)
|
||||
for _, want := range []string{"status=400", "code=invalid_argument", "refused=" + logValue(below)} {
|
||||
if !strings.Contains(line, want) {
|
||||
t.Errorf("the refused request's log line is missing %q:\n%s", want, line)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestWireRevisionMalformedIsInvalidValueNotUnsupported: a header that does
|
||||
// not parse as a non-negative integer is a different client mistake than a
|
||||
// revision this server has read and understood to be too old, and must not
|
||||
// be confused with one by carrying min_wire_revision.
|
||||
func TestWireRevisionMalformedIsInvalidValueNotUnsupported(t *testing.T) {
|
||||
ts := wireRevisionReadServer(t)
|
||||
|
||||
for _, raw := range []string{"not-a-number", "-1", "1.5", "+1", "01", "007", ""} {
|
||||
if raw == "" {
|
||||
continue // the empty string is the absent-header case, tested elsewhere
|
||||
}
|
||||
t.Run(raw, func(t *testing.T) {
|
||||
resp := ts.wireRevisioned(t, http.MethodGet, "/v0/beads/ready", raw)
|
||||
if resp.StatusCode != http.StatusBadRequest {
|
||||
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
|
||||
}
|
||||
body := decodeBody(t, resp)
|
||||
if body["reason"] != string(ReasonInvalidValue) {
|
||||
t.Errorf("reason = %v, want %s", body["reason"], ReasonInvalidValue)
|
||||
}
|
||||
if _, present := body["min_wire_revision"]; present {
|
||||
t.Errorf("a malformed header disclosed min_wire_revision: %v", body["min_wire_revision"])
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestHealthAnswersDespiteABelowFloorRevision: liveness is exempt. A kubelet
|
||||
// probe carries no Bd-Wire-Revision of its own, and must not be refused for a
|
||||
// header it never had a reason to send.
|
||||
func TestHealthAnswersDespiteABelowFloorRevision(t *testing.T) {
|
||||
ts := newTestServer(t, Config{})
|
||||
|
||||
resp := ts.wireRevisioned(t, http.MethodGet, "/healthz", strconv.Itoa(MinClientWireRevision-1))
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Errorf("GET /healthz with a below-floor revision = %d, want 200 (this route is exempt)", resp.StatusCode)
|
||||
}
|
||||
}
|
||||
|
||||
// TestContextAdvertisesWireRevision: the handshake carries both members every
|
||||
// client needs to decide whether it can safely proceed.
|
||||
func TestContextAdvertisesWireRevision(t *testing.T) {
|
||||
ts := newTestServer(t, Config{})
|
||||
|
||||
body := decodeBody(t, ts.get(t, "/v0/beads/context"))
|
||||
wire, ok := body["wire_revision"].(float64)
|
||||
if !ok || int(wire) != CurrentWireRevision {
|
||||
t.Errorf("wire_revision = %#v, want %d", body["wire_revision"], CurrentWireRevision)
|
||||
}
|
||||
min, ok := body["min_client_wire_revision"].(float64)
|
||||
if !ok || int(min) != MinClientWireRevision {
|
||||
t.Errorf("min_client_wire_revision = %#v, want %d", body["min_client_wire_revision"], MinClientWireRevision)
|
||||
}
|
||||
}
|
||||
|
||||
// TestWireRevisionExemptRoutesAreExactlyHealth pins the exempt column by
|
||||
// enumeration: exactly {OpHealth} skips the Bd-Wire-Revision floor check.
|
||||
// Unlike projectExempt, the identity handshake is deliberately NOT on this
|
||||
// list — see wireRevisionExempt's doc comment for why the two diverge.
|
||||
func TestWireRevisionExemptRoutesAreExactlyHealth(t *testing.T) {
|
||||
var exempt []string
|
||||
for _, rt := range routeTable {
|
||||
if rt.wireRevisionExempt {
|
||||
exempt = append(exempt, rt.op)
|
||||
}
|
||||
}
|
||||
slices.Sort(exempt)
|
||||
want := []string{OpHealth}
|
||||
if !slices.Equal(exempt, want) {
|
||||
t.Errorf("wireRevisionExempt routes = %v, want exactly {OpHealth}", exempt)
|
||||
}
|
||||
}
|
||||
|
||||
// TestRetiredRevisionsStayBelowTheFloor pins the PRESENCE guarantee
|
||||
// documented on the `wire_revision` property: 0 and 1 are permanently
|
||||
// retired, so a decoded 0 can only mean "the server omitted the field," never
|
||||
// a value a current or future server actually sent. That reading breaks the
|
||||
// moment either constant moves the wrong way — CurrentWireRevision dropping
|
||||
// below 2 would let a real server send one of the retired values again, and
|
||||
// MinClientWireRevision exceeding CurrentWireRevision would make every
|
||||
// request refused as unsupported by this build's own floor.
|
||||
func TestRetiredRevisionsStayBelowTheFloor(t *testing.T) {
|
||||
if CurrentWireRevision < 2 {
|
||||
t.Errorf("CurrentWireRevision = %d, want >= 2: 0 and 1 are retired and must stay below every revision a server can actually send", CurrentWireRevision)
|
||||
}
|
||||
if MinClientWireRevision > CurrentWireRevision {
|
||||
t.Errorf("MinClientWireRevision = %d, want <= CurrentWireRevision (%d)", MinClientWireRevision, CurrentWireRevision)
|
||||
}
|
||||
}
|
||||
|
||||
// TestCapabilitiesAdvertiseIssuesListSort: a client learns this server
|
||||
// accepts GET /v0/beads/issues' sort parameter from the capability list,
|
||||
// never from the version string.
|
||||
func TestCapabilitiesAdvertiseIssuesListSort(t *testing.T) {
|
||||
ts := newTestServer(t, Config{})
|
||||
|
||||
caps, _ := decodeBody(t, ts.get(t, "/v0/beads/context"))["capabilities"].([]any)
|
||||
var got []string
|
||||
for _, c := range caps {
|
||||
got = append(got, c.(string))
|
||||
}
|
||||
if !slices.Contains(got, CapIssuesListSort) {
|
||||
t.Errorf("capabilities %v do not advertise %q", got, CapIssuesListSort)
|
||||
}
|
||||
}
|
||||
26
internal/httpapi/wireshape/BUILD.bazel
Normal file
26
internal/httpapi/wireshape/BUILD.bazel
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
load("@rules_go//go:def.bzl", "go_library", "go_test")
|
||||
|
||||
go_library(
|
||||
name = "wireshape",
|
||||
srcs = [
|
||||
"doc.go",
|
||||
"wireshape.go",
|
||||
],
|
||||
importpath = "github.com/steveyegge/beads/internal/httpapi/wireshape",
|
||||
visibility = ["//:__subpackages__"],
|
||||
deps = [
|
||||
"//internal/httpapi/spec",
|
||||
"@in_gopkg_yaml_v3//:yaml_v3",
|
||||
],
|
||||
)
|
||||
|
||||
go_test(
|
||||
name = "wireshape_test",
|
||||
srcs = [
|
||||
"wireshape_internal_test.go",
|
||||
"wireshape_test.go",
|
||||
],
|
||||
data = glob(["testdata/**"]),
|
||||
embed = [":wireshape"],
|
||||
deps = ["//internal/httpapi"],
|
||||
)
|
||||
25
internal/httpapi/wireshape/cmd/gendigest/BUILD.bazel
Normal file
25
internal/httpapi/wireshape/cmd/gendigest/BUILD.bazel
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
load("@rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
|
||||
|
||||
go_library(
|
||||
name = "gendigest_lib",
|
||||
srcs = ["main.go"],
|
||||
importpath = "github.com/steveyegge/beads/internal/httpapi/wireshape/cmd/gendigest",
|
||||
visibility = ["//visibility:private"],
|
||||
deps = [
|
||||
"//internal/httpapi",
|
||||
"//internal/httpapi/wireshape",
|
||||
],
|
||||
)
|
||||
|
||||
go_binary(
|
||||
name = "gendigest",
|
||||
embed = [":gendigest_lib"],
|
||||
visibility = ["//:__subpackages__"],
|
||||
)
|
||||
|
||||
go_test(
|
||||
name = "gendigest_test",
|
||||
srcs = ["main_test.go"],
|
||||
embed = [":gendigest_lib"],
|
||||
deps = ["//internal/httpapi/wireshape"],
|
||||
)
|
||||
103
internal/httpapi/wireshape/cmd/gendigest/main.go
Normal file
103
internal/httpapi/wireshape/cmd/gendigest/main.go
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
// Command gendigest regenerates internal/httpapi/wireshape/testdata/golden.json
|
||||
// from the embedded OpenAPI document and the Go CurrentWireRevision constant.
|
||||
//
|
||||
// Run it after a deliberate, revision-bumped wire-shape change — never to make
|
||||
// a failing TestWireShapeDigest pass on an accidental one. A diff this command
|
||||
// produces that only adds entries is additive and needs no revision bump; a
|
||||
// diff that changes or removes an entry without a CurrentWireRevision bump is
|
||||
// the exact drift the test exists to catch, not something to paper over by
|
||||
// running this.
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
|
||||
"github.com/steveyegge/beads/internal/httpapi"
|
||||
"github.com/steveyegge/beads/internal/httpapi/wireshape"
|
||||
)
|
||||
|
||||
func main() {
|
||||
initFlag := flag.Bool("init", false, "create golden.json when none exists yet")
|
||||
flag.Parse()
|
||||
|
||||
out, err := goldenPath()
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, "gendigest:", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
digest, err := wireshape.Compute(httpapi.CurrentWireRevision)
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, "gendigest:", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
if err := writeGolden(out, digest, *initFlag); err != nil {
|
||||
fmt.Fprintln(os.Stderr, "gendigest:", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println("wrote", out)
|
||||
}
|
||||
|
||||
// goldenPath resolves testdata/golden.json relative to this source file, so
|
||||
// the command works from any cwd, the same way `go generate` directives in
|
||||
// this repo do.
|
||||
func goldenPath() (string, error) {
|
||||
_, thisFile, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
return "", errors.New("could not resolve own source path")
|
||||
}
|
||||
return filepath.Join(filepath.Dir(thisFile), "..", "..", "testdata", "golden.json"), nil
|
||||
}
|
||||
|
||||
// writeGolden writes digest to out, under two guards.
|
||||
//
|
||||
// First, an EXISTING golden: refuse to overwrite one that would silently
|
||||
// launder a failing TestWireShapeDigest. A changed or removed entry must come
|
||||
// with a CurrentWireRevision bump ABOVE what's already committed, never from
|
||||
// just re-running this command (wireshape.SafeToWrite); a purely additive
|
||||
// diff always writes, unless digest's wire_revision is LOWER than the
|
||||
// golden's, which SafeToWrite refuses whatever the entries.
|
||||
//
|
||||
// Second, a MISSING golden: refuse to create one unless initFlag is set. A
|
||||
// golden that is merely absent — the testdata file moved, got deleted by
|
||||
// accident, or this is being pointed at the wrong path — must not be treated
|
||||
// as implicit permission to start a fresh history from whatever the working
|
||||
// tree happens to compute right now; -init is the explicit, one-time act of
|
||||
// starting that history (the real first run, or a deliberate reset), not
|
||||
// gendigest's default behavior for "I don't see a file there."
|
||||
func writeGolden(out string, digest wireshape.Digest, initFlag bool) error {
|
||||
// #nosec G304 -- out is this command's own source-relative output path,
|
||||
// never request- or argv-influenced; reading it back is the write guard.
|
||||
existing, err := os.ReadFile(out)
|
||||
switch {
|
||||
case err == nil:
|
||||
var golden wireshape.Digest
|
||||
if err := json.Unmarshal(existing, &golden); err != nil {
|
||||
return fmt.Errorf("decode existing golden: %w", err)
|
||||
}
|
||||
if ok, reason := wireshape.SafeToWrite(golden, digest); !ok {
|
||||
return errors.New(reason)
|
||||
}
|
||||
case os.IsNotExist(err):
|
||||
if !initFlag {
|
||||
return fmt.Errorf("no golden at %s yet; pass -init to create one (a missing file is not this command's default to fill in)", out)
|
||||
}
|
||||
default:
|
||||
return fmt.Errorf("read existing golden: %w", err)
|
||||
}
|
||||
|
||||
blob, err := json.MarshalIndent(digest, "", " ")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
blob = append(blob, '\n')
|
||||
|
||||
return os.WriteFile(out, blob, 0o600)
|
||||
}
|
||||
71
internal/httpapi/wireshape/cmd/gendigest/main_test.go
Normal file
71
internal/httpapi/wireshape/cmd/gendigest/main_test.go
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/httpapi/wireshape"
|
||||
)
|
||||
|
||||
func sampleDigest(revision int) wireshape.Digest {
|
||||
return wireshape.Digest{
|
||||
WireRevision: revision,
|
||||
Entries: []wireshape.Entry{
|
||||
{Schema: "Widget", Member: "name", Type: "string", Required: true},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// TestWriteGoldenRequiresInitWhenMissing is LOW-2 from the re-review: a
|
||||
// missing golden.json must not be filled in silently. Without -init, the one
|
||||
// failure mode that most needs a loud error — pointing this command at a path
|
||||
// that lost its file by accident — would otherwise look exactly like a
|
||||
// successful first run.
|
||||
func TestWriteGoldenRequiresInitWhenMissing(t *testing.T) {
|
||||
out := filepath.Join(t.TempDir(), "golden.json")
|
||||
|
||||
if err := writeGolden(out, sampleDigest(2), false); err == nil {
|
||||
t.Fatal("writeGolden with no existing file and initFlag=false: want an error naming -init, got nil")
|
||||
}
|
||||
if _, err := os.Stat(out); !os.IsNotExist(err) {
|
||||
t.Errorf("writeGolden refused but a file exists at %s anyway", out)
|
||||
}
|
||||
}
|
||||
|
||||
// TestWriteGoldenInitCreatesWhenMissing is the other half: -init is how a
|
||||
// real first run (or a deliberate reset) still works.
|
||||
func TestWriteGoldenInitCreatesWhenMissing(t *testing.T) {
|
||||
out := filepath.Join(t.TempDir(), "golden.json")
|
||||
|
||||
if err := writeGolden(out, sampleDigest(2), true); err != nil {
|
||||
t.Fatalf("writeGolden with initFlag=true: %v", err)
|
||||
}
|
||||
if _, err := os.Stat(out); err != nil {
|
||||
t.Errorf("writeGolden -init did not create %s: %v", out, err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestWriteGoldenIgnoresInitWhenGoldenExists: -init only matters for the
|
||||
// missing-file case. An existing golden is still governed exclusively by
|
||||
// SafeToWrite, whether or not -init was passed.
|
||||
func TestWriteGoldenIgnoresInitWhenGoldenExists(t *testing.T) {
|
||||
out := filepath.Join(t.TempDir(), "golden.json")
|
||||
if err := writeGolden(out, sampleDigest(2), true); err != nil {
|
||||
t.Fatalf("seed write: %v", err)
|
||||
}
|
||||
|
||||
// A same-revision changed entry is unsafe per SafeToWrite, -init or not.
|
||||
changed := sampleDigest(2)
|
||||
changed.Entries[0].Type = "integer"
|
||||
if err := writeGolden(out, changed, true); err == nil {
|
||||
t.Error("writeGolden over an existing golden with an unsafe diff and initFlag=true: want an error, got nil")
|
||||
}
|
||||
|
||||
// A higher-revision changed entry is safe, with no -init needed.
|
||||
bumped := sampleDigest(3)
|
||||
bumped.Entries[0].Type = "integer"
|
||||
if err := writeGolden(out, bumped, false); err != nil {
|
||||
t.Errorf("writeGolden over an existing golden with a revision-bumped diff and initFlag=false: %v", err)
|
||||
}
|
||||
}
|
||||
54
internal/httpapi/wireshape/doc.go
Normal file
54
internal/httpapi/wireshape/doc.go
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
// Package wireshape is the CI drift gate for ContextResponse.wire_revision.
|
||||
//
|
||||
// It computes a digest of every member reachable from any response schema AND
|
||||
// any request body schema in internal/httpapi/spec/openapi.v0.yaml — walking
|
||||
// $refs through components.schemas and components.responses, and flattening
|
||||
// a schema's own allOf/oneOf — recording, per member, the (schema, member,
|
||||
// type, format, enum, required, nullable) tuple the document promises, plus
|
||||
// the item shape of an array member and the value shape of an
|
||||
// additionalProperties map.
|
||||
//
|
||||
// It ALSO covers every operation PARAMETER (query, path and header) across
|
||||
// every operation in the document, keyed by operationId + location + name
|
||||
// rather than by schema — two different operations' same-named parameter are
|
||||
// two independent wire contracts, even when they happen to share a shape
|
||||
// today. Each parameter entry records type, item shape (for an array
|
||||
// parameter), enum, required, style, explode and default — style and explode
|
||||
// as their effective values, OpenAPI 3.0's defaults filled in where the
|
||||
// document leaves them unset — so a parameter silently retyped,
|
||||
// re-enumerated, narrowed, re-serialized, switched required, or removed is
|
||||
// exactly as visible here as the same change to a response or request body
|
||||
// member — the gap closed after the first revision of this gate shipped
|
||||
// without it.
|
||||
//
|
||||
// TestWireShapeDigest compares that digest against the committed golden in
|
||||
// testdata/golden.json and fails on any difference: a member or parameter
|
||||
// added needs only a regenerate (an additive change never bumps
|
||||
// wire_revision), but a member's or parameter's type, format, enum
|
||||
// vocabulary, required-ness, nullability, style, explode or default changing
|
||||
// — or either disappearing — is exactly the class of change
|
||||
// internal/httpapi/wire_revision.go's CurrentWireRevision exists to gate, and
|
||||
// the golden's own "wire_revision" field is compared too, so a shape change
|
||||
// recorded against the OLD revision number still fails, and so does a
|
||||
// CurrentWireRevision lower than the golden's.
|
||||
//
|
||||
// The digest is a boundary, not the whole wire. Value constraints such as
|
||||
// maxLength, maximum, pattern or maxItems are outside it, on members and
|
||||
// parameters alike, and so is a composition keyword on a single member's own
|
||||
// value (the document uses none); an object-typed parameter, or one described
|
||||
// by content rather than schema, is recorded only as its container. A new
|
||||
// member or parameter always counts as additive, even a REQUIRED one an old
|
||||
// client will not send. Each of those changes needs its own review against
|
||||
// wire_revision: nothing here asks for a bump for any of them.
|
||||
//
|
||||
// Regenerate the golden after a deliberate, revision-bumped change with:
|
||||
//
|
||||
// go run ./internal/httpapi/wireshape/cmd/gendigest
|
||||
//
|
||||
// That command itself refuses to write a changed or removed entry unless
|
||||
// wire_revision has moved past what the existing golden recorded, refuses any
|
||||
// write at a wire_revision LOWER than the golden's, and refuses to create a
|
||||
// golden that does not exist yet unless run with -init — a missing file is
|
||||
// not treated as permission to start a fresh history silently. Never
|
||||
// hand-edit testdata/golden.json.
|
||||
package wireshape
|
||||
5537
internal/httpapi/wireshape/testdata/golden.json
vendored
Normal file
5537
internal/httpapi/wireshape/testdata/golden.json
vendored
Normal file
File diff suppressed because it is too large
Load diff
626
internal/httpapi/wireshape/wireshape.go
Normal file
626
internal/httpapi/wireshape/wireshape.go
Normal file
|
|
@ -0,0 +1,626 @@
|
|||
package wireshape
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"reflect"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"gopkg.in/yaml.v3"
|
||||
|
||||
"github.com/steveyegge/beads/internal/httpapi/spec"
|
||||
)
|
||||
|
||||
// Entry is one member of one schema reachable from an operation's response OR
|
||||
// request body, OR one operation parameter (query, path or header). Schema is
|
||||
// the component's name (or, for a member whose own value is an inline object
|
||||
// or array with no $ref of its own, a synthetic dotted path rooted at the
|
||||
// nearest named schema) so that two members with the same name on different
|
||||
// schemas are never confused with one another. For a parameter, Schema is
|
||||
// instead "param:"+operationId and Member is in+":"+name (see
|
||||
// paramKey) — operation-scoped rather than schema-scoped, because two
|
||||
// different operations' same-named "status" query parameter are two
|
||||
// independent wire contracts even when today they happen to share a shape.
|
||||
//
|
||||
// The Item* and AdditionalProps* fields exist because a property's own
|
||||
// Type/Format/Enum/Nullable describe the CONTAINER, not what it contains: a
|
||||
// `type: array` property is always `Type: "array"` whether its items are
|
||||
// strings or integers, and a `type: object` property with no `properties` of
|
||||
// its own (a map, via `additionalProperties`) is always `Type: "object"`
|
||||
// whether its values are strings or integers. Without these fields, changing
|
||||
// Issue.labels' item type from string to integer, or IssueCount.groups'
|
||||
// value type from integer to string, is invisible to this digest even though
|
||||
// it is exactly the non-additive wire change CurrentWireRevision exists to
|
||||
// gate — the other half of #6053 alongside the request-body coverage below.
|
||||
type Entry struct {
|
||||
Schema string `json:"schema"`
|
||||
Member string `json:"member"`
|
||||
Type string `json:"type"`
|
||||
Format string `json:"format,omitempty"`
|
||||
Enum []string `json:"enum,omitempty"`
|
||||
Required bool `json:"required"`
|
||||
// Nullable records `nullable: true` on this member's own schema node. A
|
||||
// response member moving from always-present-when-returned to
|
||||
// sometimes-null is exactly as breaking to a client as the type itself
|
||||
// changing, and before this field nothing here could see it.
|
||||
Nullable bool `json:"nullable,omitempty"`
|
||||
|
||||
// ItemType, ItemFormat, ItemEnum and ItemNullable describe a `type: array`
|
||||
// member's own items node. They are set whenever Type == "array" and the
|
||||
// items schema resolves to something, regardless of whether the items are
|
||||
// a scalar (only these fields describe it) or an object with its own
|
||||
// named members (which ALSO get walked and recorded as their own
|
||||
// Entry-ies under schema+"."+member+"[]", same as before).
|
||||
ItemType string `json:"item_type,omitempty"`
|
||||
ItemFormat string `json:"item_format,omitempty"`
|
||||
ItemEnum []string `json:"item_enum,omitempty"`
|
||||
ItemNullable bool `json:"item_nullable,omitempty"`
|
||||
|
||||
// AdditionalPropsType and AdditionalPropsFormat describe a `type: object`
|
||||
// member's `additionalProperties` schema — the map-value shape of a
|
||||
// member like IssueCount.groups, which has no `properties` of its own.
|
||||
// Set only when additionalProperties is a schema (not the boolean `true`
|
||||
// or `false` some operations use for "no constraint" / "sealed").
|
||||
AdditionalPropsType string `json:"additional_props_type,omitempty"`
|
||||
AdditionalPropsFormat string `json:"additional_props_format,omitempty"`
|
||||
|
||||
// Style, Explode and Default are set only for parameter entries (see
|
||||
// paramKey): the serialization style OpenAPI uses to flatten an array or
|
||||
// object parameter into a query/path string, whether it repeats the name
|
||||
// per value or explodes/collapses, and the literal default value. A
|
||||
// server that starts expecting `label=a,b` breaks every client still
|
||||
// sending `label=a&label=b`, even though neither Type nor Enum changed —
|
||||
// exactly the gap the parameter digest closes.
|
||||
//
|
||||
// Style and Explode are the EFFECTIVE values, with OpenAPI 3.0's defaults
|
||||
// filled in where the document leaves them unset (see walkParam), so a
|
||||
// parameter that spells out its default is the same entry as one that
|
||||
// relies on it, while `explode: false` added to a form parameter that
|
||||
// relied on the implicit `true` is a changed entry.
|
||||
Style string `json:"style,omitempty"`
|
||||
Explode bool `json:"explode,omitempty"`
|
||||
Default string `json:"default,omitempty"`
|
||||
}
|
||||
|
||||
// paramSchemaPrefix marks an Entry.Schema as naming an operation (via
|
||||
// operationId) rather than an OpenAPI component schema. Grepping for this
|
||||
// prefix is how a reader tells a parameter entry apart from a schema member
|
||||
// entry in golden.json.
|
||||
const paramSchemaPrefix = "param:"
|
||||
|
||||
// paramKey returns the Schema/Member pair a parameter entry is filed under:
|
||||
// operation-scoped by operationId, then by location and name. Location is
|
||||
// part of the key (not just the name) because OpenAPI allows the same name in
|
||||
// two different locations on one operation (a path `id` and a query `id`
|
||||
// would otherwise collide).
|
||||
func paramKey(operationID, in, name string) (schema, member string) {
|
||||
return paramSchemaPrefix + operationID, in + ":" + name
|
||||
}
|
||||
|
||||
// Digest is the golden document: the wire revision it was computed against,
|
||||
// plus every member entry, sorted for a stable diff.
|
||||
type Digest struct {
|
||||
WireRevision int `json:"wire_revision"`
|
||||
Entries []Entry `json:"entries"`
|
||||
}
|
||||
|
||||
// CompareResult is the outcome of diffing two digests by "schema\x00member"
|
||||
// key: Changed holds keys present in both whose Entry differs, Removed holds
|
||||
// keys only want has, and Added holds keys only got has.
|
||||
type CompareResult struct {
|
||||
Changed []string
|
||||
Removed []string
|
||||
Added []string
|
||||
}
|
||||
|
||||
// Compare diffs want (typically the committed golden) against got (typically
|
||||
// a fresh Compute()). It is the one comparison TestWireShapeDigest and
|
||||
// gendigest's SafeToWrite guard both need, extracted here so the write guard
|
||||
// and the test can never disagree about what counts as a change.
|
||||
func Compare(want, got Digest) CompareResult {
|
||||
wantByKey := map[string]Entry{}
|
||||
for _, e := range want.Entries {
|
||||
wantByKey[e.Schema+"\x00"+e.Member] = e
|
||||
}
|
||||
gotByKey := map[string]Entry{}
|
||||
for _, e := range got.Entries {
|
||||
gotByKey[e.Schema+"\x00"+e.Member] = e
|
||||
}
|
||||
|
||||
var result CompareResult
|
||||
for key, w := range wantByKey {
|
||||
g, ok := gotByKey[key]
|
||||
if !ok {
|
||||
result.Removed = append(result.Removed, key)
|
||||
continue
|
||||
}
|
||||
if !reflect.DeepEqual(w, g) {
|
||||
result.Changed = append(result.Changed, key)
|
||||
}
|
||||
}
|
||||
for key := range gotByKey {
|
||||
if _, ok := wantByKey[key]; !ok {
|
||||
result.Added = append(result.Added, key)
|
||||
}
|
||||
}
|
||||
sort.Strings(result.Changed)
|
||||
sort.Strings(result.Removed)
|
||||
sort.Strings(result.Added)
|
||||
return result
|
||||
}
|
||||
|
||||
// SafeToWrite is gendigest's write guard (review MEDIUM: "refuse to write
|
||||
// changed or removed entries unless CurrentWireRevision is higher than the
|
||||
// golden's recorded revision. Additive entries are allowed."). A pure
|
||||
// addition is always safe regardless of revision; a changed or removed entry
|
||||
// is only safe when candidate's WireRevision is strictly greater than
|
||||
// golden's — the exact bump TestWireShapeDigest itself requires to go green,
|
||||
// so gendigest can never be used to silently launder a failing test instead
|
||||
// of fixing it. A candidate whose WireRevision is LOWER than golden's is
|
||||
// refused whatever its entries: the revision table is append-only, so writing
|
||||
// it would record a rollback the spec forbids.
|
||||
func SafeToWrite(golden, candidate Digest) (bool, string) {
|
||||
if candidate.WireRevision < golden.WireRevision {
|
||||
return false, fmt.Sprintf(
|
||||
"refusing to write: wire_revision %d is lower than the existing golden's %d — wire_revision only "+
|
||||
"ever increases (the revision table in openapi.v0.yaml's wire_revision property is append-only), "+
|
||||
"so restore CurrentWireRevision (internal/httpapi/wire_revision.go) instead of writing the "+
|
||||
"golden backwards",
|
||||
candidate.WireRevision, golden.WireRevision)
|
||||
}
|
||||
cmp := Compare(golden, candidate)
|
||||
if len(cmp.Changed) == 0 && len(cmp.Removed) == 0 {
|
||||
return true, ""
|
||||
}
|
||||
if candidate.WireRevision > golden.WireRevision {
|
||||
return true, ""
|
||||
}
|
||||
return false, fmt.Sprintf(
|
||||
"refusing to write: %d changed and %d removed entr(ies) but wire_revision %d is not greater than "+
|
||||
"the existing golden's %d (changed=%v removed=%v) — bump CurrentWireRevision "+
|
||||
"(internal/httpapi/wire_revision.go) and the revision table in openapi.v0.yaml's "+
|
||||
"wire_revision property FIRST, then regenerate",
|
||||
len(cmp.Changed), len(cmp.Removed), candidate.WireRevision, golden.WireRevision, cmp.Changed, cmp.Removed)
|
||||
}
|
||||
|
||||
var httpVerbs = map[string]bool{
|
||||
"get": true, "put": true, "post": true, "delete": true, "patch": true,
|
||||
"head": true, "options": true, "trace": true,
|
||||
}
|
||||
|
||||
// Compute walks the embedded OpenAPI document and builds the digest for the
|
||||
// current revision. wireRevision is passed in rather than read from a
|
||||
// constant here so this package carries no dependency on internal/httpapi
|
||||
// (which would otherwise be a cycle: internal/httpapi imports nothing from
|
||||
// here, and this package must stay that way to run from the standalone
|
||||
// gendigest command without pulling in the server).
|
||||
//
|
||||
// RESPONSE schemas, REQUEST BODY schemas, and operation PARAMETERS (query,
|
||||
// path and header — see paramKey) are all walked. A request-body-only shape
|
||||
// change — DeleteIssuesRequest.expected_version moving from string to
|
||||
// integer, say — is exactly as much an undocumented break to an existing
|
||||
// client as a response change, and the other half of #6053 was invisible
|
||||
// here until request bodies were added alongside responses. Parameters are
|
||||
// the same story again: a `limit` query parameter silently retyped,
|
||||
// re-enumerated, or switched from optional to required never touched a
|
||||
// response or request body schema, so it was invisible to this digest until
|
||||
// parameter coverage was added.
|
||||
func Compute(wireRevision int) (Digest, error) {
|
||||
return computeFrom(spec.OpenAPIV0(), wireRevision)
|
||||
}
|
||||
|
||||
// computeFrom is Compute over any OpenAPI document, so this package's own
|
||||
// tests can drive the walk with a synthetic document instead of the embedded
|
||||
// one.
|
||||
func computeFrom(document []byte, wireRevision int) (Digest, error) {
|
||||
var doc map[string]any
|
||||
if err := yaml.Unmarshal(document, &doc); err != nil {
|
||||
return Digest{}, fmt.Errorf("parse openapi document: %w", err)
|
||||
}
|
||||
|
||||
c := &collector{doc: doc, visited: map[string]bool{}, byKey: map[string]Entry{}}
|
||||
|
||||
paths, _ := doc["paths"].(map[string]any)
|
||||
for _, item := range paths {
|
||||
methods, ok := item.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for method, raw := range methods {
|
||||
if !httpVerbs[strings.ToLower(method)] {
|
||||
continue
|
||||
}
|
||||
op, ok := raw.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
|
||||
responses, _ := op["responses"].(map[string]any)
|
||||
for _, rawResp := range responses {
|
||||
respMap, ok := rawResp.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
respMap = c.resolveAny(respMap)
|
||||
c.walkContent(respMap)
|
||||
}
|
||||
|
||||
if rb, ok := op["requestBody"].(map[string]any); ok {
|
||||
rb = c.resolveAny(rb)
|
||||
c.walkContent(rb)
|
||||
}
|
||||
|
||||
operationID := asString(op["operationId"])
|
||||
params, _ := op["parameters"].([]any)
|
||||
for _, rawParam := range params {
|
||||
paramMap, ok := rawParam.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
c.walkParam(operationID, c.resolveAny(paramMap))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
entries := make([]Entry, 0, len(c.byKey))
|
||||
for _, e := range c.byKey {
|
||||
entries = append(entries, e)
|
||||
}
|
||||
sort.Slice(entries, func(i, j int) bool {
|
||||
if entries[i].Schema != entries[j].Schema {
|
||||
return entries[i].Schema < entries[j].Schema
|
||||
}
|
||||
return entries[i].Member < entries[j].Member
|
||||
})
|
||||
return Digest{WireRevision: wireRevision, Entries: entries}, nil
|
||||
}
|
||||
|
||||
// walkContent walks every media type's schema under a resolved response or
|
||||
// requestBody node's `content` map. Shared by Compute's response and request
|
||||
// body loops: a response object and a resolved requestBody object are both
|
||||
// shaped `{content: {mediaType: {schema: ...}}}`.
|
||||
func (c *collector) walkContent(node map[string]any) {
|
||||
content, _ := node["content"].(map[string]any)
|
||||
for _, rawMedia := range content {
|
||||
media, ok := rawMedia.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
schemaNode, ok := media["schema"].(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
c.walk(schemaNode, "")
|
||||
}
|
||||
}
|
||||
|
||||
// walkParam records one resolved parameter object (already $ref-followed by
|
||||
// the caller) as a single Entry keyed by paramKey(operationID, in, name). A
|
||||
// parameter's own Required/Style/Explode live on the parameter object itself;
|
||||
// Type/Format/Enum/Nullable/Default and, for arrays, the Item* fields, live
|
||||
// one level down on its `schema` node. Unlike walk, a parameter's schema is
|
||||
// never itself filed under its own named Entry — this document's parameter
|
||||
// schemas are all inline scalars or inline arrays of scalars (confirmed by
|
||||
// grep: no operation parameter uses an object schema), so there is nothing
|
||||
// further to recurse into, and ANY future object-shaped parameter schema
|
||||
// still gets its Type/Enum/Required seen here even without recursion.
|
||||
//
|
||||
// Style and Explode are recorded as OpenAPI 3.0's effective values: an unset
|
||||
// style is `form` for a query or cookie parameter and `simple` for a path or
|
||||
// header one, and an unset explode is true exactly when the style is `form`.
|
||||
// Recording the raw keys instead would file an unset explode and an explicit
|
||||
// `explode: false` as the same entry, though one sends `label=a&label=b` and
|
||||
// the other `label=a,b`. OpenAPI 3.0 applies style and explode only to a
|
||||
// parameter described by `schema`: one described by `content` is serialized
|
||||
// by its media type, so the location default recorded for it is a
|
||||
// placeholder, not a wire promise (this document has no such parameter).
|
||||
func (c *collector) walkParam(operationID string, node map[string]any) {
|
||||
name := asString(node["name"])
|
||||
in := asString(node["in"])
|
||||
if name == "" || in == "" {
|
||||
// Not a parameter object this document recognizes (for instance, a
|
||||
// dangling or unresolved $ref) — nothing to record.
|
||||
return
|
||||
}
|
||||
|
||||
schema, _ := node["schema"].(map[string]any)
|
||||
schema = c.resolveAny(schema)
|
||||
|
||||
style := asString(node["style"])
|
||||
if style == "" {
|
||||
style = defaultParamStyle(in)
|
||||
}
|
||||
explode, ok := node["explode"].(bool)
|
||||
if !ok {
|
||||
explode = style == "form"
|
||||
}
|
||||
|
||||
entrySchema, entryMember := paramKey(operationID, in, name)
|
||||
entry := Entry{
|
||||
Schema: entrySchema,
|
||||
Member: entryMember,
|
||||
Type: asString(schema["type"]),
|
||||
Format: asString(schema["format"]),
|
||||
Enum: toStringSlice(schema["enum"]),
|
||||
Required: asBool(node["required"]),
|
||||
Nullable: asBool(schema["nullable"]),
|
||||
Style: style,
|
||||
Explode: explode,
|
||||
Default: defaultString(schema["default"]),
|
||||
}
|
||||
|
||||
if entry.Type == "array" {
|
||||
if items, ok := schema["items"].(map[string]any); ok {
|
||||
resolvedItems := c.resolveAny(items)
|
||||
entry.ItemType = asString(resolvedItems["type"])
|
||||
entry.ItemFormat = asString(resolvedItems["format"])
|
||||
entry.ItemEnum = toStringSlice(resolvedItems["enum"])
|
||||
entry.ItemNullable = asBool(resolvedItems["nullable"])
|
||||
}
|
||||
}
|
||||
|
||||
c.byKey[entry.Schema+"\x00"+entry.Member] = entry
|
||||
}
|
||||
|
||||
// defaultParamStyle is OpenAPI 3.0's `style` for a parameter that sets none:
|
||||
// `form` in a query or cookie, `simple` in a path or header.
|
||||
func defaultParamStyle(in string) string {
|
||||
switch in {
|
||||
case "query", "cookie":
|
||||
return "form"
|
||||
case "path", "header":
|
||||
return "simple"
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
type collector struct {
|
||||
doc map[string]any
|
||||
visited map[string]bool
|
||||
byKey map[string]Entry // "schema\x00member" -> Entry
|
||||
}
|
||||
|
||||
// lookup resolves one local $ref to the node it names. It returns nil for
|
||||
// anything this document does not use (a remote ref, or a path with no node).
|
||||
func lookup(doc map[string]any, ref string) map[string]any {
|
||||
rest := strings.TrimPrefix(ref, "#/")
|
||||
var cur any = doc
|
||||
for _, part := range strings.Split(rest, "/") {
|
||||
m, ok := cur.(map[string]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
cur = m[part]
|
||||
}
|
||||
m, _ := cur.(map[string]any)
|
||||
return m
|
||||
}
|
||||
|
||||
// schemaRefName reports the component schema name a $ref names, or "" when
|
||||
// the ref points somewhere else (components.responses, for instance).
|
||||
func schemaRefName(ref string) string {
|
||||
const prefix = "#/components/schemas/"
|
||||
name, ok := strings.CutPrefix(ref, prefix)
|
||||
if !ok {
|
||||
return ""
|
||||
}
|
||||
return name
|
||||
}
|
||||
|
||||
// resolveAny follows a $ref chain to its concrete node, however many hops it
|
||||
// takes (a response $ref lands on a response object; it is never itself a
|
||||
// further $ref in this document, but the walk tolerates it either way).
|
||||
func (c *collector) resolveAny(node map[string]any) map[string]any {
|
||||
seen := 0
|
||||
for {
|
||||
ref, ok := node["$ref"].(string)
|
||||
if !ok {
|
||||
return node
|
||||
}
|
||||
next := lookup(c.doc, ref)
|
||||
if next == nil {
|
||||
return node
|
||||
}
|
||||
node = next
|
||||
seen++
|
||||
if seen > 32 {
|
||||
// Defensive only: this document has no ref cycle, and 32 hops is
|
||||
// far beyond anything a hand-written spec would ever chain.
|
||||
return node
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func toStringSlice(v any) []string {
|
||||
raw, ok := v.([]any)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
out := make([]string, 0, len(raw))
|
||||
for _, e := range raw {
|
||||
out = append(out, fmt.Sprint(e))
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
func asString(v any) string {
|
||||
s, _ := v.(string)
|
||||
return s
|
||||
}
|
||||
|
||||
func asBool(v any) bool {
|
||||
b, _ := v.(bool)
|
||||
return b
|
||||
}
|
||||
|
||||
// defaultString renders a schema's `default` value (which, unlike enum
|
||||
// members, is a single scalar of whatever type the schema declares — string,
|
||||
// number or bool) as a comparable string, or "" when the schema has none. A
|
||||
// literal "" default and "no default at all" are indistinguishable here,
|
||||
// which matches every default this document actually declares (none are the
|
||||
// empty string).
|
||||
func defaultString(v any) string {
|
||||
if v == nil {
|
||||
return ""
|
||||
}
|
||||
return fmt.Sprint(v)
|
||||
}
|
||||
|
||||
// walk records every property of the schema node reaches (following $refs and
|
||||
// flattening allOf and oneOf), then recurses into each property's own object
|
||||
// or array shape. label names an anonymous (non-$ref) node for entries
|
||||
// recorded under it; a $ref always overrides it with the component's own
|
||||
// name.
|
||||
//
|
||||
// Every NAMED schema is walked at most once (the visited guard), which is
|
||||
// what makes a cycle between named schemas (and there is at least the
|
||||
// potential for one as this document grows) a no-op rather than a stack
|
||||
// overflow, and what makes the digest the same whichever operation reaches a
|
||||
// shared schema first.
|
||||
func (c *collector) walk(node map[string]any, label string) {
|
||||
name := label
|
||||
for {
|
||||
ref, ok := node["$ref"].(string)
|
||||
if !ok {
|
||||
break
|
||||
}
|
||||
if n := schemaRefName(ref); n != "" {
|
||||
name = n
|
||||
}
|
||||
next := lookup(c.doc, ref)
|
||||
if next == nil {
|
||||
return
|
||||
}
|
||||
node = next
|
||||
}
|
||||
|
||||
if merged, ok := c.mergeCombinator(node, "allOf"); ok {
|
||||
node = merged
|
||||
} else if merged, ok := c.mergeCombinator(node, "oneOf"); ok {
|
||||
// oneOf is a union, not an intersection — merging its branches'
|
||||
// properties together is not semantically a "oneOf" anymore. This
|
||||
// document uses oneOf nowhere today (confirmed by grep), so this
|
||||
// branch is defensive only: a best-effort shape so a future oneOf is
|
||||
// SEEN by the digest rather than silently invisible, not a claim
|
||||
// that the merge is the right model for real union validation.
|
||||
node = merged
|
||||
}
|
||||
|
||||
if name != "" {
|
||||
if c.visited[name] {
|
||||
return
|
||||
}
|
||||
c.visited[name] = true
|
||||
}
|
||||
|
||||
if props, ok := node["properties"].(map[string]any); ok {
|
||||
required := map[string]bool{}
|
||||
for _, r := range toStringSlice(node["required"]) {
|
||||
required[r] = true
|
||||
}
|
||||
members := make([]string, 0, len(props))
|
||||
for m := range props {
|
||||
members = append(members, m)
|
||||
}
|
||||
sort.Strings(members)
|
||||
for _, member := range members {
|
||||
propRaw := props[member]
|
||||
propMap, ok := propRaw.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
resolved := c.resolveAny(propMap)
|
||||
entry := Entry{
|
||||
Schema: name,
|
||||
Member: member,
|
||||
Type: asString(resolved["type"]),
|
||||
Format: asString(resolved["format"]),
|
||||
Enum: toStringSlice(resolved["enum"]),
|
||||
Required: required[member],
|
||||
Nullable: asBool(resolved["nullable"]),
|
||||
}
|
||||
|
||||
var itemsNode, addlPropsNode map[string]any
|
||||
switch entry.Type {
|
||||
case "array":
|
||||
if items, ok := resolved["items"].(map[string]any); ok {
|
||||
resolvedItems := c.resolveAny(items)
|
||||
entry.ItemType = asString(resolvedItems["type"])
|
||||
entry.ItemFormat = asString(resolvedItems["format"])
|
||||
entry.ItemEnum = toStringSlice(resolvedItems["enum"])
|
||||
entry.ItemNullable = asBool(resolvedItems["nullable"])
|
||||
itemsNode = items
|
||||
}
|
||||
case "object":
|
||||
if ap, ok := resolved["additionalProperties"].(map[string]any); ok {
|
||||
resolvedAP := c.resolveAny(ap)
|
||||
entry.AdditionalPropsType = asString(resolvedAP["type"])
|
||||
entry.AdditionalPropsFormat = asString(resolvedAP["format"])
|
||||
addlPropsNode = ap
|
||||
}
|
||||
}
|
||||
|
||||
c.byKey[entry.Schema+"\x00"+entry.Member] = entry
|
||||
|
||||
switch entry.Type {
|
||||
case "object":
|
||||
c.walk(propMap, name+"."+member)
|
||||
if addlPropsNode != nil {
|
||||
// A map value that is itself a named/object schema gets
|
||||
// its own members walked too, under a label distinct
|
||||
// from an array's "[]" so the two can never collide.
|
||||
c.walk(addlPropsNode, name+"."+member+"{}")
|
||||
}
|
||||
case "array":
|
||||
if itemsNode != nil {
|
||||
c.walk(itemsNode, name+"."+member+"[]")
|
||||
}
|
||||
}
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
if asString(node["type"]) == "array" {
|
||||
if items, ok := node["items"].(map[string]any); ok {
|
||||
itemLabel := name
|
||||
if itemLabel == "" {
|
||||
itemLabel = label
|
||||
}
|
||||
c.walk(items, itemLabel+"[]")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// mergeCombinator flattens node[key] (allOf or oneOf: a list of subschemas)
|
||||
// into a synthetic object node with merged properties and required lists, the
|
||||
// way the pre-existing allOf handling always worked. It reports ok == false
|
||||
// when node has no such key, leaving node untouched.
|
||||
func (c *collector) mergeCombinator(node map[string]any, key string) (map[string]any, bool) {
|
||||
list, ok := node[key].([]any)
|
||||
if !ok {
|
||||
return nil, false
|
||||
}
|
||||
mergedProps := map[string]any{}
|
||||
var mergedRequired []any
|
||||
for _, rawSub := range list {
|
||||
subMap, ok := rawSub.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
sub := c.resolveAny(subMap)
|
||||
if props, ok := sub["properties"].(map[string]any); ok {
|
||||
for k, v := range props {
|
||||
mergedProps[k] = v
|
||||
}
|
||||
}
|
||||
if req, ok := sub["required"].([]any); ok {
|
||||
mergedRequired = append(mergedRequired, req...)
|
||||
}
|
||||
}
|
||||
return map[string]any{
|
||||
"type": "object",
|
||||
"properties": mergedProps,
|
||||
"required": mergedRequired,
|
||||
}, true
|
||||
}
|
||||
155
internal/httpapi/wireshape/wireshape_internal_test.go
Normal file
155
internal/httpapi/wireshape/wireshape_internal_test.go
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
package wireshape
|
||||
|
||||
import (
|
||||
"reflect"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// paramDoc is a minimal OpenAPI document with one operation, listWidgets,
|
||||
// whose only parameter is param: a YAML flow mapping, so a case spells its
|
||||
// whole parameter object on one line. components holds what the $ref cases
|
||||
// point at.
|
||||
func paramDoc(param string) []byte {
|
||||
return []byte(`openapi: 3.0.3
|
||||
paths:
|
||||
/widgets:
|
||||
get:
|
||||
operationId: listWidgets
|
||||
parameters:
|
||||
- ` + param + `
|
||||
responses: {}
|
||||
components:
|
||||
parameters:
|
||||
WidgetColor: {name: color, in: query, required: true, schema: {$ref: '#/components/schemas/Color'}}
|
||||
schemas:
|
||||
Color: {type: string, enum: [red, green]}
|
||||
Shade: {type: integer, format: int32, nullable: true}
|
||||
`)
|
||||
}
|
||||
|
||||
// paramDigest runs computeFrom — the walk Compute runs — over paramDoc(param).
|
||||
// The document has no response or request body, so every entry is a
|
||||
// parameter entry.
|
||||
func paramDigest(t *testing.T, param string) Digest {
|
||||
t.Helper()
|
||||
d, err := computeFrom(paramDoc(param), 2)
|
||||
if err != nil {
|
||||
t.Fatalf("computeFrom: %v", err)
|
||||
}
|
||||
return d
|
||||
}
|
||||
|
||||
// TestWalkParam pins every Entry field walkParam extracts, feeding each
|
||||
// synthetic parameter object through computeFrom so a $ref'd parameter is
|
||||
// resolved exactly as Compute resolves it. TestParameterMutationsAreCaught
|
||||
// cannot see a wrongly extracted field: it mutates golden entries after the
|
||||
// fact.
|
||||
func TestWalkParam(t *testing.T) {
|
||||
const op = "param:listWidgets"
|
||||
for _, tc := range []struct {
|
||||
name string
|
||||
param string
|
||||
want []Entry // nil: nothing recorded
|
||||
}{
|
||||
{"query array relying on the defaults records form and explode",
|
||||
`{name: tags, in: query, schema: {type: array, items: {type: string, enum: [b, a]}}}`,
|
||||
[]Entry{{Schema: op, Member: "query:tags", Type: "array", ItemType: "string", ItemEnum: []string{"a", "b"}, Style: "form", Explode: true}}},
|
||||
{"explicit explode false is recorded",
|
||||
`{name: tags, in: query, explode: false, schema: {type: array, items: {type: string}}}`,
|
||||
[]Entry{{Schema: op, Member: "query:tags", Type: "array", ItemType: "string", Style: "form"}}},
|
||||
{"explicit non-form style defaults explode to false",
|
||||
`{name: tags, in: query, style: pipeDelimited, schema: {type: array, items: {type: string}}}`,
|
||||
[]Entry{{Schema: op, Member: "query:tags", Type: "array", ItemType: "string", Style: "pipeDelimited"}}},
|
||||
{"path parameter defaults to simple",
|
||||
`{name: id, in: path, required: true, schema: {type: string}}`,
|
||||
[]Entry{{Schema: op, Member: "path:id", Type: "string", Required: true, Style: "simple"}}},
|
||||
{"header parameter defaults to simple",
|
||||
`{name: X-Trace, in: header, schema: {type: integer}}`,
|
||||
[]Entry{{Schema: op, Member: "header:X-Trace", Type: "integer", Style: "simple"}}},
|
||||
{"cookie parameter defaults to form",
|
||||
`{name: session, in: cookie, schema: {type: string}}`,
|
||||
[]Entry{{Schema: op, Member: "cookie:session", Type: "string", Style: "form", Explode: true}}},
|
||||
{"format, nullable and default come from the schema",
|
||||
`{name: limit, in: query, schema: {type: integer, format: int32, nullable: true, default: 50}}`,
|
||||
[]Entry{{Schema: op, Member: "query:limit", Type: "integer", Format: "int32", Nullable: true, Default: "50", Style: "form", Explode: true}}},
|
||||
{"a false default is still a default",
|
||||
`{name: all, in: query, schema: {type: boolean, default: false}}`,
|
||||
[]Entry{{Schema: op, Member: "query:all", Type: "boolean", Default: "false", Style: "form", Explode: true}}},
|
||||
{"a $ref'd parameter and its $ref'd schema are both resolved",
|
||||
`{$ref: '#/components/parameters/WidgetColor'}`,
|
||||
[]Entry{{Schema: op, Member: "query:color", Type: "string", Enum: []string{"green", "red"}, Required: true, Style: "form", Explode: true}}},
|
||||
{"$ref'd array items fill the Item fields",
|
||||
`{name: shades, in: query, schema: {type: array, items: {$ref: '#/components/schemas/Shade'}}}`,
|
||||
[]Entry{{Schema: op, Member: "query:shades", Type: "array", ItemType: "integer", ItemFormat: "int32", ItemNullable: true, Style: "form", Explode: true}}},
|
||||
{"a content parameter is recorded only as its container",
|
||||
`{name: filter, in: query, content: {application/json: {schema: {type: object}}}}`,
|
||||
[]Entry{{Schema: op, Member: "query:filter", Style: "form", Explode: true}}},
|
||||
{"missing in records nothing",
|
||||
`{name: orphan, schema: {type: string}}`,
|
||||
nil},
|
||||
{"missing name records nothing",
|
||||
`{in: query, schema: {type: string}}`,
|
||||
nil},
|
||||
{"a dangling $ref records nothing",
|
||||
`{$ref: '#/components/parameters/Missing'}`,
|
||||
nil},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
got := paramDigest(t, tc.param).Entries
|
||||
if len(got) == 0 {
|
||||
got = nil
|
||||
}
|
||||
if !reflect.DeepEqual(got, tc.want) {
|
||||
t.Errorf("entries:\n got %+v\n want %+v", got, tc.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestEffectiveSerializationIsCompared is the Compute-level falsification for
|
||||
// recording effective style/explode values: changing how a parameter that
|
||||
// relied on its defaults is serialized must be a changed entry SafeToWrite
|
||||
// refuses at the same revision, while spelling those same defaults out must
|
||||
// change nothing.
|
||||
func TestEffectiveSerializationIsCompared(t *testing.T) {
|
||||
for _, tc := range []struct {
|
||||
name string
|
||||
before, after string
|
||||
wantChanged bool
|
||||
}{
|
||||
{"explode false on a query array that relied on form's implicit explode",
|
||||
`{name: tags, in: query, schema: {type: array, items: {type: string}}}`,
|
||||
`{name: tags, in: query, explode: false, schema: {type: array, items: {type: string}}}`,
|
||||
true},
|
||||
{"a non-form style on a query array that relied on form",
|
||||
`{name: tags, in: query, schema: {type: array, items: {type: string}}}`,
|
||||
`{name: tags, in: query, style: spaceDelimited, schema: {type: array, items: {type: string}}}`,
|
||||
true},
|
||||
{"label style on a path parameter that relied on simple",
|
||||
`{name: id, in: path, required: true, schema: {type: string}}`,
|
||||
`{name: id, in: path, required: true, style: label, schema: {type: string}}`,
|
||||
true},
|
||||
{"spelling out a query parameter's default style and explode",
|
||||
`{name: tags, in: query, schema: {type: array, items: {type: string}}}`,
|
||||
`{name: tags, in: query, style: form, explode: true, schema: {type: array, items: {type: string}}}`,
|
||||
false},
|
||||
{"spelling out a path parameter's default style and explode",
|
||||
`{name: id, in: path, required: true, schema: {type: string}}`,
|
||||
`{name: id, in: path, required: true, style: simple, explode: false, schema: {type: string}}`,
|
||||
false},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
before, after := paramDigest(t, tc.before), paramDigest(t, tc.after)
|
||||
cmp := Compare(before, after)
|
||||
if len(cmp.Removed) > 0 || len(cmp.Added) > 0 {
|
||||
t.Fatalf("parameter key moved: removed=%v added=%v", cmp.Removed, cmp.Added)
|
||||
}
|
||||
if changed := len(cmp.Changed) > 0; changed != tc.wantChanged {
|
||||
t.Errorf("Compare changed=%v, want a change: %v", cmp.Changed, tc.wantChanged)
|
||||
}
|
||||
if ok, _ := SafeToWrite(before, after); ok == tc.wantChanged {
|
||||
t.Errorf("SafeToWrite at the same revision = %v, want %v", ok, !tc.wantChanged)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
371
internal/httpapi/wireshape/wireshape_test.go
Normal file
371
internal/httpapi/wireshape/wireshape_test.go
Normal file
|
|
@ -0,0 +1,371 @@
|
|||
package wireshape_test
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/httpapi"
|
||||
"github.com/steveyegge/beads/internal/httpapi/wireshape"
|
||||
)
|
||||
|
||||
// TestWireShapeDigest is the drift gate ContextResponse.wire_revision
|
||||
// documents: it fails the moment the shape of any EXISTING response member,
|
||||
// request-body member or operation parameter changes without
|
||||
// CurrentWireRevision increasing to match.
|
||||
//
|
||||
// It is deliberately not one struct-equal, because the ways this can go red
|
||||
// call for different instructions (goldenDrift picks one). A changed or
|
||||
// removed entry at the SAME wire_revision is drift nobody signed off on —
|
||||
// regenerate only after bumping CurrentWireRevision (see
|
||||
// internal/httpapi/wire_revision.go) and the `wire_revision` property's
|
||||
// revision table in openapi.v0.yaml, never before. A wire_revision LOWER than
|
||||
// the golden's is never fixed by regenerating: that table is append-only, so
|
||||
// the constant itself is wrong. Any other difference — a bumped
|
||||
// wire_revision, or entries only added — means this golden is simply stale;
|
||||
// regenerate it with:
|
||||
//
|
||||
// go run ./internal/httpapi/wireshape/cmd/gendigest
|
||||
func TestWireShapeDigest(t *testing.T) {
|
||||
golden := loadGolden(t)
|
||||
got, err := wireshape.Compute(httpapi.CurrentWireRevision)
|
||||
if err != nil {
|
||||
t.Fatalf("compute digest: %v", err)
|
||||
}
|
||||
|
||||
if len(got.Entries) < 20 {
|
||||
// The document describes dozens of response members; a near-empty
|
||||
// digest means the walk found nothing, which would make every
|
||||
// assertion below pass vacuously.
|
||||
t.Fatalf("digest has %d entries, want the full walk", len(got.Entries))
|
||||
}
|
||||
|
||||
if drift := goldenDrift(golden, got); drift != "" {
|
||||
t.Error(drift)
|
||||
}
|
||||
}
|
||||
|
||||
// goldenDrift is TestWireShapeDigest's verdict, factored out so
|
||||
// TestGoldenDrift can drive every arm with synthetic digests. It returns ""
|
||||
// only when golden records exactly got — the same entries at the same
|
||||
// wire_revision. Every other state fails; the arms only choose which
|
||||
// instruction the failure gives.
|
||||
func goldenDrift(golden, got wireshape.Digest) string {
|
||||
if got.WireRevision < golden.WireRevision {
|
||||
return fmt.Sprintf("CurrentWireRevision is %d, LOWER than the %d the golden records: wire_revision only "+
|
||||
"ever increases (the revision table in openapi.v0.yaml's `wire_revision` property is append-only), "+
|
||||
"so restore CurrentWireRevision (internal/httpapi/wire_revision.go) — never regenerate the golden "+
|
||||
"backwards", got.WireRevision, golden.WireRevision)
|
||||
}
|
||||
|
||||
cmp := wireshape.Compare(golden, got)
|
||||
changed, removed, added := cmp.Changed, cmp.Removed, cmp.Added
|
||||
|
||||
switch {
|
||||
case len(changed) > 0 || len(removed) > 0:
|
||||
if got.WireRevision <= golden.WireRevision {
|
||||
return fmt.Sprintf("wire shape (response/request-body member or parameter) changed without a "+
|
||||
"wire_revision bump: changed=%v removed=%v\n"+
|
||||
"bump CurrentWireRevision (internal/httpapi/wire_revision.go) and the revision table "+
|
||||
"in openapi.v0.yaml's `wire_revision` property, THEN regenerate the golden with "+
|
||||
"`go run ./internal/httpapi/wireshape/cmd/gendigest`", changed, removed)
|
||||
}
|
||||
return fmt.Sprintf("wire shape (response/request-body member or parameter) changed (changed=%v "+
|
||||
"removed=%v) and wire_revision moved %d -> %d, but the golden was not regenerated: run "+
|
||||
"`go run ./internal/httpapi/wireshape/cmd/gendigest` and commit the result",
|
||||
changed, removed, golden.WireRevision, got.WireRevision)
|
||||
case len(added) > 0:
|
||||
if got.WireRevision == golden.WireRevision {
|
||||
return fmt.Sprintf("wire shape (response/request-body member or parameter) added (%v) but the "+
|
||||
"golden was not regenerated: this is additive and needs no wire_revision bump, but still run "+
|
||||
"`go run ./internal/httpapi/wireshape/cmd/gendigest` and commit the result", added)
|
||||
}
|
||||
// Passing here would leave the golden a revision behind
|
||||
// CurrentWireRevision, and a later non-additive change at that
|
||||
// already-moved constant would then be told only to regenerate (which
|
||||
// SafeToWrite allows) instead of to bump.
|
||||
return fmt.Sprintf("wire shape (response/request-body member or parameter) added (%v) and "+
|
||||
"wire_revision moved %d -> %d, but the golden was not regenerated: run "+
|
||||
"`go run ./internal/httpapi/wireshape/cmd/gendigest` and commit the result",
|
||||
added, golden.WireRevision, got.WireRevision)
|
||||
case got.WireRevision != golden.WireRevision:
|
||||
return fmt.Sprintf("CurrentWireRevision is %d but the golden still says %d, with no shape change to justify "+
|
||||
"either: regenerate with `go run ./internal/httpapi/wireshape/cmd/gendigest`",
|
||||
got.WireRevision, golden.WireRevision)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// TestGoldenDrift is TestWireShapeDigest's own falsification: every way the
|
||||
// committed golden can disagree with a fresh Compute must fail, each with its
|
||||
// own instruction. "Added after a bump" is the state review found passing
|
||||
// silently — no arm fired when entries were only added and wire_revision had
|
||||
// also moved — and a LOWERED wire_revision was told to regenerate, which
|
||||
// would have written the golden's revision backwards.
|
||||
func TestGoldenDrift(t *testing.T) {
|
||||
golden := wireshape.Digest{
|
||||
WireRevision: 2,
|
||||
Entries: []wireshape.Entry{
|
||||
{Schema: "Widget", Member: "name", Type: "string", Required: true},
|
||||
},
|
||||
}
|
||||
changed := []wireshape.Entry{{Schema: "Widget", Member: "name", Type: "integer", Required: true}}
|
||||
added := append(append([]wireshape.Entry{}, golden.Entries...),
|
||||
wireshape.Entry{Schema: "Widget", Member: "color", Type: "string"})
|
||||
|
||||
for _, tc := range []struct {
|
||||
name string
|
||||
got wireshape.Digest
|
||||
want []string // phrases the failure must contain; none means the golden is current
|
||||
}{
|
||||
{"identical digest is current",
|
||||
golden, nil},
|
||||
{"changed entry at the same revision asks for a bump",
|
||||
wireshape.Digest{WireRevision: 2, Entries: changed}, []string{"changed without a wire_revision bump"}},
|
||||
{"removed entry at the same revision asks for a bump",
|
||||
wireshape.Digest{WireRevision: 2}, []string{"changed without a wire_revision bump"}},
|
||||
{"changed entry after a bump asks for a regenerate",
|
||||
wireshape.Digest{WireRevision: 3, Entries: changed}, []string{"changed (changed=", "moved 2 -> 3", "not regenerated"}},
|
||||
{"added entry at the same revision asks for a regenerate",
|
||||
wireshape.Digest{WireRevision: 2, Entries: added}, []string{"added (", "needs no wire_revision bump"}},
|
||||
{"added entry after a bump asks for a regenerate",
|
||||
wireshape.Digest{WireRevision: 3, Entries: added}, []string{"added (", "moved 2 -> 3", "not regenerated"}},
|
||||
{"bump with no shape change asks for a regenerate",
|
||||
wireshape.Digest{WireRevision: 3, Entries: golden.Entries}, []string{"no shape change"}},
|
||||
{"lowered revision with no shape change asks to restore the constant",
|
||||
wireshape.Digest{WireRevision: 1, Entries: golden.Entries}, []string{"LOWER than the 2", "never regenerate the golden backwards"}},
|
||||
{"changed entry at a lowered revision asks to restore the constant",
|
||||
wireshape.Digest{WireRevision: 1, Entries: changed}, []string{"LOWER than the 2"}},
|
||||
{"added entry at a lowered revision asks to restore the constant",
|
||||
wireshape.Digest{WireRevision: 1, Entries: added}, []string{"LOWER than the 2"}},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
drift := goldenDrift(golden, tc.got)
|
||||
if len(tc.want) == 0 {
|
||||
if drift != "" {
|
||||
t.Fatalf("current golden reported as drift: %s", drift)
|
||||
}
|
||||
return
|
||||
}
|
||||
if drift == "" {
|
||||
t.Fatal("stale golden passed silently")
|
||||
}
|
||||
for _, phrase := range tc.want {
|
||||
if !strings.Contains(drift, phrase) {
|
||||
t.Errorf("drift %q does not contain %q", drift, phrase)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestSafeToWrite is the gendigest write guard's own falsification (review
|
||||
// MEDIUM: "refuse to write changed or removed entries unless
|
||||
// CurrentWireRevision is higher than the golden's recorded revision"), plus
|
||||
// the refusal of any candidate whose revision is LOWER than the golden's.
|
||||
func TestSafeToWrite(t *testing.T) {
|
||||
base := wireshape.Digest{
|
||||
WireRevision: 2,
|
||||
Entries: []wireshape.Entry{
|
||||
{Schema: "Widget", Member: "name", Type: "string", Required: true},
|
||||
},
|
||||
}
|
||||
|
||||
t.Run("pure addition at the same revision is always safe", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{
|
||||
WireRevision: 2,
|
||||
Entries: append(append([]wireshape.Entry{}, base.Entries...),
|
||||
wireshape.Entry{Schema: "Widget", Member: "color", Type: "string"}),
|
||||
}
|
||||
if ok, reason := wireshape.SafeToWrite(base, candidate); !ok {
|
||||
t.Fatalf("pure addition refused: %s", reason)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("identical digest is always safe", func(t *testing.T) {
|
||||
if ok, reason := wireshape.SafeToWrite(base, base); !ok {
|
||||
t.Fatalf("identical digest refused: %s", reason)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("changed entry at the same revision is refused", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{
|
||||
WireRevision: 2,
|
||||
Entries: []wireshape.Entry{{Schema: "Widget", Member: "name", Type: "integer", Required: true}},
|
||||
}
|
||||
if ok, _ := wireshape.SafeToWrite(base, candidate); ok {
|
||||
t.Fatal("changed entry at the same revision was allowed")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("removed entry at the same revision is refused", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{WireRevision: 2, Entries: nil}
|
||||
if ok, _ := wireshape.SafeToWrite(base, candidate); ok {
|
||||
t.Fatal("removed entry at the same revision was allowed")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("changed entry with a lower revision is refused", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{
|
||||
WireRevision: 1,
|
||||
Entries: []wireshape.Entry{{Schema: "Widget", Member: "name", Type: "integer", Required: true}},
|
||||
}
|
||||
if ok, _ := wireshape.SafeToWrite(base, candidate); ok {
|
||||
t.Fatal("changed entry with a LOWER revision was allowed")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("unchanged entries with a lower revision are refused", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{WireRevision: 1, Entries: base.Entries}
|
||||
ok, reason := wireshape.SafeToWrite(base, candidate)
|
||||
if ok {
|
||||
t.Fatal("unchanged entries with a LOWER revision were allowed — the golden's revision would move backwards")
|
||||
}
|
||||
if !strings.Contains(reason, "append-only") {
|
||||
t.Errorf("refusal %q does not point at the append-only revision table", reason)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("pure addition with a lower revision is refused", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{
|
||||
WireRevision: 1,
|
||||
Entries: append(append([]wireshape.Entry{}, base.Entries...),
|
||||
wireshape.Entry{Schema: "Widget", Member: "color", Type: "string"}),
|
||||
}
|
||||
if ok, _ := wireshape.SafeToWrite(base, candidate); ok {
|
||||
t.Fatal("pure addition with a LOWER revision was allowed — the golden's revision would move backwards")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("changed entry with a higher revision is safe", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{
|
||||
WireRevision: 3,
|
||||
Entries: []wireshape.Entry{{Schema: "Widget", Member: "name", Type: "integer", Required: true}},
|
||||
}
|
||||
if ok, reason := wireshape.SafeToWrite(base, candidate); !ok {
|
||||
t.Fatalf("changed entry with a higher revision refused: %s", reason)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("removed entry with a higher revision is safe", func(t *testing.T) {
|
||||
candidate := wireshape.Digest{WireRevision: 3, Entries: nil}
|
||||
if ok, reason := wireshape.SafeToWrite(base, candidate); !ok {
|
||||
t.Fatalf("removed entry with a higher revision refused: %s", reason)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestParameterMutationsAreCaught is the falsification for how Compare and
|
||||
// SafeToWrite treat the parameter side of the digest (review: "the digest
|
||||
// doesn't cover operation PARAMETERS ... so a type, enum, required, or
|
||||
// removal change on an existing parameter passes the gate silently"). It
|
||||
// mutates real entries out of the committed golden — not a synthetic fixture
|
||||
// — so a future rename of the `listIssues` limit/sort parameters breaks this
|
||||
// test loudly instead of letting the coverage go stale unnoticed. Because it
|
||||
// mutates entries after the fact, it cannot see a field walkParam extracts
|
||||
// wrongly; that is TestWalkParam's job (wireshape_internal_test.go).
|
||||
//
|
||||
// Each case checks the same two things TestSafeToWrite checks for schema
|
||||
// members: the mutation is refused at the golden's own wire_revision, and
|
||||
// allowed once the candidate's wire_revision is strictly higher — proving
|
||||
// SafeToWrite treats a parameter entry exactly as non-additively as a
|
||||
// response or request-body entry, using nothing parameter-specific.
|
||||
func TestParameterMutationsAreCaught(t *testing.T) {
|
||||
golden := loadGolden(t)
|
||||
|
||||
withEntry := func(mutate func(e wireshape.Entry) wireshape.Entry, schema, member string) []wireshape.Entry {
|
||||
out := make([]wireshape.Entry, 0, len(golden.Entries))
|
||||
for _, e := range golden.Entries {
|
||||
if e.Schema == schema && e.Member == member {
|
||||
e = mutate(e)
|
||||
}
|
||||
out = append(out, e)
|
||||
}
|
||||
return out
|
||||
}
|
||||
withoutEntry := func(schema, member string) []wireshape.Entry {
|
||||
out := make([]wireshape.Entry, 0, len(golden.Entries))
|
||||
for _, e := range golden.Entries {
|
||||
if e.Schema == schema && e.Member == member {
|
||||
continue
|
||||
}
|
||||
out = append(out, e)
|
||||
}
|
||||
return out
|
||||
}
|
||||
mustFind := func(schema, member string) wireshape.Entry {
|
||||
t.Helper()
|
||||
for _, e := range golden.Entries {
|
||||
if e.Schema == schema && e.Member == member {
|
||||
return e
|
||||
}
|
||||
}
|
||||
t.Fatalf("golden has no %s/%s entry (has the spec changed? update this test's fixture keys)", schema, member)
|
||||
return wireshape.Entry{}
|
||||
}
|
||||
|
||||
// listIssues' `limit` query parameter: {type: integer, default: "50"}.
|
||||
limit := mustFind("param:listIssues", "query:limit")
|
||||
if limit.Type != "integer" {
|
||||
t.Fatalf("param:listIssues query:limit is %q in the current golden, not \"integer\" — update this test's fixture", limit.Type)
|
||||
}
|
||||
// listIssues' `sort` query parameter: {type: string, enum: [created, priority]}.
|
||||
sortEntry := mustFind("param:listIssues", "query:sort")
|
||||
if len(sortEntry.Enum) < 2 {
|
||||
t.Fatalf("param:listIssues query:sort has %v enum values in the current golden, want >= 2 — update this test's fixture", sortEntry.Enum)
|
||||
}
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
mutations []wireshape.Entry
|
||||
}{
|
||||
{
|
||||
name: "removing a parameter",
|
||||
mutations: withoutEntry("param:listIssues", "query:limit"),
|
||||
},
|
||||
{
|
||||
name: "retyping a parameter",
|
||||
mutations: withEntry(func(e wireshape.Entry) wireshape.Entry {
|
||||
e.Type = "string"
|
||||
return e
|
||||
}, "param:listIssues", "query:limit"),
|
||||
},
|
||||
{
|
||||
name: "narrowing a parameter's enum",
|
||||
mutations: withEntry(func(e wireshape.Entry) wireshape.Entry {
|
||||
e.Enum = e.Enum[:1]
|
||||
return e
|
||||
}, "param:listIssues", "query:sort"),
|
||||
},
|
||||
}
|
||||
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
sameRevision := wireshape.Digest{WireRevision: golden.WireRevision, Entries: tc.mutations}
|
||||
if ok, _ := wireshape.SafeToWrite(golden, sameRevision); ok {
|
||||
t.Fatalf("%s at the same wire_revision was allowed — the digest did not see the change", tc.name)
|
||||
}
|
||||
|
||||
higherRevision := wireshape.Digest{WireRevision: golden.WireRevision + 1, Entries: tc.mutations}
|
||||
if ok, reason := wireshape.SafeToWrite(golden, higherRevision); !ok {
|
||||
t.Fatalf("%s with a bumped wire_revision was refused: %s", tc.name, reason)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func loadGolden(t *testing.T) wireshape.Digest {
|
||||
t.Helper()
|
||||
blob, err := os.ReadFile(filepath.Join("testdata", "golden.json"))
|
||||
if err != nil {
|
||||
t.Fatalf("read golden: %v", err)
|
||||
}
|
||||
var d wireshape.Digest
|
||||
if err := json.Unmarshal(blob, &d); err != nil {
|
||||
t.Fatalf("decode golden: %v", err)
|
||||
}
|
||||
return d
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue