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>
This commit is contained in:
parent
6a0896529e
commit
be1f0bad72
11 changed files with 778 additions and 185 deletions
36
CHANGELOG.md
36
CHANGELOG.md
|
|
@ -50,22 +50,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
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 exempt until
|
||||
its next change.
|
||||
(`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 response AND
|
||||
request-body member across the whole HTTP spec — including array item
|
||||
shape and `additionalProperties` value shape — recursing through `$ref`,
|
||||
`allOf`, and `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 (purely additive entries
|
||||
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, style, explode, and
|
||||
default — a parameter retyped, re-enumerated, narrowed, switched
|
||||
required, or removed is non-additive exactly like a response or
|
||||
request-body member.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -592,21 +592,38 @@ 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`, `allOf`, and `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. `TestWireShapeDigest` fails one of two
|
||||
ways: a changed or removed entry at an UNCHANGED `wire_revision` is drift
|
||||
nobody signed off on; a changed `wire_revision` with an unchanged entry set
|
||||
means the golden is simply stale. Either way the fix is the same explicit
|
||||
command, `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, so running
|
||||
it cannot silently launder drift into the baseline. A purely additive diff —
|
||||
new members, with no existing entry changed or removed — always writes,
|
||||
revision bump or not.
|
||||
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
|
||||
|
|
@ -622,8 +639,9 @@ baselines (`internal/httpapi/testdata/pretoken_parameters.json`,
|
|||
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 exempt from the
|
||||
rule entirely until its next change. A backticked `a.b`(`.c`)-shaped span in a
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1035,7 +1035,7 @@ 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.
|
||||
// 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:
|
||||
//
|
||||
|
|
@ -1069,7 +1069,7 @@ type ContextResponse struct {
|
|||
//
|
||||
// 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`, `allOf` and `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. 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, and refuses to create a golden that does not exist yet unless run with `-init`.
|
||||
// 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"`
|
||||
|
|
|
|||
|
|
@ -7540,7 +7540,13 @@ components:
|
|||
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.
|
||||
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:
|
||||
|
|
@ -7619,13 +7625,15 @@ components:
|
|||
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`, `allOf` and `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. It fails
|
||||
CI the moment any one of these — member or parameter — changes
|
||||
without this field's Go constant (`CurrentWireRevision`,
|
||||
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
|
||||
|
|
@ -7634,8 +7642,17 @@ components:
|
|||
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, and refuses to create a golden that
|
||||
does not exist yet unless run with `-init`.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -16,10 +16,11 @@ go_library(
|
|||
|
||||
go_test(
|
||||
name = "wireshape_test",
|
||||
srcs = ["wireshape_test.go"],
|
||||
data = glob(["testdata/**"]),
|
||||
deps = [
|
||||
":wireshape",
|
||||
"//internal/httpapi",
|
||||
srcs = [
|
||||
"wireshape_internal_test.go",
|
||||
"wireshape_test.go",
|
||||
],
|
||||
data = glob(["testdata/**"]),
|
||||
embed = [":wireshape"],
|
||||
deps = ["//internal/httpapi"],
|
||||
)
|
||||
|
|
|
|||
|
|
@ -62,7 +62,8 @@ func goldenPath() (string, error) {
|
|||
// 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.
|
||||
// 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
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
//
|
||||
// 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 recursing
|
||||
// through 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
|
||||
// $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
|
||||
|
|
@ -13,29 +13,42 @@
|
|||
// 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, so a parameter
|
||||
// silently retyped, re-enumerated, narrowed, switched required, or removed is
|
||||
// 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 is fine (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.
|
||||
// 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, 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.
|
||||
// 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
|
||||
|
|
|
|||
363
internal/httpapi/wireshape/testdata/golden.json
vendored
363
internal/httpapi/wireshape/testdata/golden.json
vendored
|
|
@ -4330,19 +4330,23 @@
|
|||
"schema": "param:addComment",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:claimIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
|
|
@ -4366,13 +4370,17 @@
|
|||
"schema": "param:claimNextIssue",
|
||||
"member": "query:has_metadata_key",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:include_deferred",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4380,6 +4388,8 @@
|
|||
"member": "query:include_ephemeral",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4404,13 +4414,17 @@
|
|||
"schema": "param:claimNextIssue",
|
||||
"member": "query:label_pattern",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:label_regex",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
|
|
@ -4425,13 +4439,17 @@
|
|||
"schema": "param:claimNextIssue",
|
||||
"member": "query:parent",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:priority",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
|
|
@ -4443,31 +4461,39 @@
|
|||
"priority"
|
||||
],
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "priority"
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:type",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:claimNextIssue",
|
||||
"member": "query:unassigned",
|
||||
"type": "boolean",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:closeIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:compareAndSetMetadata",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:countDependencyEdges",
|
||||
|
|
@ -4477,7 +4503,9 @@
|
|||
"in",
|
||||
"out"
|
||||
],
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countDependencyEdges",
|
||||
|
|
@ -4492,7 +4520,9 @@
|
|||
"schema": "param:countDependencyEdges",
|
||||
"member": "query:status",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countDependencyEdges",
|
||||
|
|
@ -4507,47 +4537,61 @@
|
|||
"schema": "param:countIssues",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:closed_after",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:closed_before",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:created_after",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:created_before",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:desc_contains",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:empty_description",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4561,25 +4605,33 @@
|
|||
"status",
|
||||
"type"
|
||||
],
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:has_metadata_key",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:id",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:include_ephemeral",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4587,6 +4639,8 @@
|
|||
"member": "query:include_infra",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4594,14 +4648,18 @@
|
|||
"member": "query:label",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"item_type": "string"
|
||||
"item_type": "string",
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:label_any",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"item_type": "string"
|
||||
"item_type": "string",
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
|
|
@ -4617,6 +4675,8 @@
|
|||
"member": "query:no_assignee",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4624,75 +4684,99 @@
|
|||
"member": "query:no_labels",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:notes_contains",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:priority",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:priority_max",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:priority_min",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:status",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:title",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:title_contains",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:type",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:updated_after",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countIssues",
|
||||
"member": "query:updated_before",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
|
|
@ -4716,13 +4800,17 @@
|
|||
"schema": "param:countReadyWork",
|
||||
"member": "query:has_metadata_key",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:include_deferred",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4730,6 +4818,8 @@
|
|||
"member": "query:include_ephemeral",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4754,13 +4844,17 @@
|
|||
"schema": "param:countReadyWork",
|
||||
"member": "query:label_pattern",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:label_regex",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
|
|
@ -4775,31 +4869,40 @@
|
|||
"schema": "param:countReadyWork",
|
||||
"member": "query:parent",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:priority",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:type",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:countReadyWork",
|
||||
"member": "query:unassigned",
|
||||
"type": "boolean",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:forgetMemory",
|
||||
"member": "path:key",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:getDependencyTree",
|
||||
|
|
@ -4811,6 +4914,8 @@
|
|||
"up"
|
||||
],
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "down"
|
||||
},
|
||||
{
|
||||
|
|
@ -4818,31 +4923,40 @@
|
|||
"member": "query:max_depth",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "50"
|
||||
},
|
||||
{
|
||||
"schema": "param:getDependencyTree",
|
||||
"member": "query:root_id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:getDependencyTree",
|
||||
"member": "query:status",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:getIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:getIssue",
|
||||
"member": "query:brief_deps",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4850,6 +4964,8 @@
|
|||
"member": "query:include_comments",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4857,31 +4973,39 @@
|
|||
"member": "query:include_dependents",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
"schema": "param:getMemory",
|
||||
"member": "path:key",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:getSetting",
|
||||
"member": "path:key",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:getStats",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:getStats",
|
||||
"member": "query:skip_blocked",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4916,6 +5040,8 @@
|
|||
"member": "query:limit",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "1000"
|
||||
},
|
||||
{
|
||||
|
|
@ -4923,26 +5049,34 @@
|
|||
"member": "query:since",
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:all",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:brief",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4950,20 +5084,26 @@
|
|||
"member": "query:created_after",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:created_before",
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:cursor",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
|
|
@ -4978,13 +5118,17 @@
|
|||
"schema": "param:listIssues",
|
||||
"member": "query:has_metadata_key",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
"member": "query:include_ephemeral",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4992,6 +5136,8 @@
|
|||
"member": "query:include_gates",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -4999,6 +5145,8 @@
|
|||
"member": "query:include_infra",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5006,6 +5154,8 @@
|
|||
"member": "query:include_templates",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5031,6 +5181,8 @@
|
|||
"member": "query:limit",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "50"
|
||||
},
|
||||
{
|
||||
|
|
@ -5046,7 +5198,9 @@
|
|||
"schema": "param:listIssues",
|
||||
"member": "query:parent",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listIssues",
|
||||
|
|
@ -5057,6 +5211,8 @@
|
|||
"priority"
|
||||
],
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "created"
|
||||
},
|
||||
{
|
||||
|
|
@ -5072,25 +5228,33 @@
|
|||
"schema": "param:listIssues",
|
||||
"member": "query:type",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listMemories",
|
||||
"member": "query:search",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:assignee",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:brief",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5115,13 +5279,17 @@
|
|||
"schema": "param:listReadyWork",
|
||||
"member": "query:has_metadata_key",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:include_deferred",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5129,6 +5297,8 @@
|
|||
"member": "query:include_ephemeral",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5153,19 +5323,25 @@
|
|||
"schema": "param:listReadyWork",
|
||||
"member": "query:label_pattern",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:label_regex",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:limit",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "100"
|
||||
},
|
||||
{
|
||||
|
|
@ -5181,13 +5357,17 @@
|
|||
"schema": "param:listReadyWork",
|
||||
"member": "query:parent",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:priority",
|
||||
"type": "integer",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
|
|
@ -5199,25 +5379,32 @@
|
|||
"priority"
|
||||
],
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "priority"
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:type",
|
||||
"type": "string",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listReadyWork",
|
||||
"member": "query:unassigned",
|
||||
"type": "boolean",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listRelatedIssues",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:listRelatedIssues",
|
||||
|
|
@ -5227,7 +5414,9 @@
|
|||
"in",
|
||||
"out"
|
||||
],
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:listRelatedIssues",
|
||||
|
|
@ -5243,6 +5432,8 @@
|
|||
"member": "query:all",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5250,19 +5441,25 @@
|
|||
"member": "query:limit",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "50"
|
||||
},
|
||||
{
|
||||
"schema": "param:queryIssues",
|
||||
"member": "query:q",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:queryIssues",
|
||||
"member": "query:reverse",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true,
|
||||
"default": "false"
|
||||
},
|
||||
{
|
||||
|
|
@ -5280,51 +5477,61 @@
|
|||
"type",
|
||||
"updated"
|
||||
],
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
},
|
||||
{
|
||||
"schema": "param:releaseIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:reopenIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:setSetting",
|
||||
"member": "path:key",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:unsetSetting",
|
||||
"member": "path:key",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:updateIssue",
|
||||
"member": "path:id",
|
||||
"type": "string",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:watchEvents",
|
||||
"member": "header:Last-Event-ID",
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"required": false
|
||||
"required": false,
|
||||
"style": "simple"
|
||||
},
|
||||
{
|
||||
"schema": "param:watchEvents",
|
||||
"member": "query:since",
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"required": true
|
||||
"required": true,
|
||||
"style": "form",
|
||||
"explode": true
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -68,9 +68,15 @@ type Entry struct {
|
|||
// 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
|
||||
// client that parses `limit=1,2,3` breaks the moment the server starts
|
||||
// sending `limit=1&limit=2&limit=3` instead, even though neither Type nor
|
||||
// Enum changed — exactly the gap the parameter digest closes.
|
||||
// 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"`
|
||||
|
|
@ -150,8 +156,18 @@ func Compare(want, got Digest) CompareResult {
|
|||
// 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.
|
||||
// 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, ""
|
||||
|
|
@ -190,9 +206,16 @@ var httpVerbs = map[string]bool{
|
|||
// 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(spec.OpenAPIV0(), &doc); err != nil {
|
||||
return Digest{}, fmt.Errorf("parse embedded openapi document: %w", err)
|
||||
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{}}
|
||||
|
|
@ -281,6 +304,16 @@ func (c *collector) walkContent(node map[string]any) {
|
|||
// 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"])
|
||||
|
|
@ -293,6 +326,15 @@ func (c *collector) walkParam(operationID string, node map[string]any) {
|
|||
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,
|
||||
|
|
@ -302,8 +344,8 @@ func (c *collector) walkParam(operationID string, node map[string]any) {
|
|||
Enum: toStringSlice(schema["enum"]),
|
||||
Required: asBool(node["required"]),
|
||||
Nullable: asBool(schema["nullable"]),
|
||||
Style: asString(node["style"]),
|
||||
Explode: asBool(node["explode"]),
|
||||
Style: style,
|
||||
Explode: explode,
|
||||
Default: defaultString(schema["default"]),
|
||||
}
|
||||
|
||||
|
|
@ -320,6 +362,18 @@ func (c *collector) walkParam(operationID string, node map[string]any) {
|
|||
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
|
||||
|
|
|
|||
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)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
|
@ -2,8 +2,10 @@ package wireshape_test
|
|||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/httpapi"
|
||||
|
|
@ -11,17 +13,20 @@ import (
|
|||
)
|
||||
|
||||
// TestWireShapeDigest is the drift gate ContextResponse.wire_revision
|
||||
// documents: it fails the moment the shape of any EXISTING response member
|
||||
// changes without CurrentWireRevision increasing to match.
|
||||
// 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 two separate comparisons rather than one struct-equal,
|
||||
// because the two ways this can go red call for different instructions. A
|
||||
// changed or removed entry at the SAME wire_revision is drift nobody signed
|
||||
// off on — regenerate only after bumping CurrentWireRevision (see
|
||||
// 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 changed wire_revision
|
||||
// with an unchanged entry set (or only additions) means this golden is simply
|
||||
// stale — regenerate it with:
|
||||
// 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) {
|
||||
|
|
@ -38,37 +43,129 @@ func TestWireShapeDigest(t *testing.T) {
|
|||
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
|
||||
|
||||
if len(changed) > 0 || len(removed) > 0 {
|
||||
switch {
|
||||
case len(changed) > 0 || len(removed) > 0:
|
||||
if got.WireRevision <= golden.WireRevision {
|
||||
t.Errorf("response member shape changed without a wire_revision bump: changed=%v removed=%v\n"+
|
||||
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)
|
||||
} else {
|
||||
t.Errorf("response member shape 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)
|
||||
}
|
||||
} else if len(added) > 0 && got.WireRevision == golden.WireRevision {
|
||||
t.Errorf("response members were 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)
|
||||
}
|
||||
|
||||
if got.WireRevision != golden.WireRevision && len(changed) == 0 && len(removed) == 0 && len(added) == 0 {
|
||||
t.Errorf("CurrentWireRevision is %d but the golden still says %d, with no shape change to justify "+
|
||||
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").
|
||||
// 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,
|
||||
|
|
@ -121,6 +218,28 @@ func TestSafeToWrite(t *testing.T) {
|
|||
}
|
||||
})
|
||||
|
||||
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,
|
||||
|
|
@ -139,13 +258,15 @@ func TestSafeToWrite(t *testing.T) {
|
|||
})
|
||||
}
|
||||
|
||||
// TestParameterMutationsAreCaught is the falsification for 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.
|
||||
// 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue