* 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>
* feat(httpclient): lift the HTTP client wire/encode layers from bd-enterprise (MIT contribution)
Contributed by gascity from bd-enterprise (github.com/gascity/bd-enterprise,
internal/enterprise/httpstore @ 49d1df2f6) to OSS beads under the MIT
license, with the owner's explicit approval. Every lifted file carries a
provenance header naming its source path.
Lifted into internal/httpclient:
- wire/ the HTTP transport, lazy handshake, project-identity stamping,
problem-code decoding, retry behaviour and the capability vocabulary
- encode/ request/response encoders for the role operations
- credential*.go, ca*.go, target*.go the bearer credential ladder,
host-scoped CA trust and the http_target.json sidecar
Not lifted (stays enterprise-only): the hosted gateway (httpgw/gwauth),
box-login, storage profiles and gasworks.
Deferred to later slices (kept aside, not in this tree): the store transport
seam (WireClient/WireDialer/process-wide dialer, which goes to S3 with
dial.go), the enterprise-only BatchCloseRequest.claim_next encoder
(ClaimNextBody; the OSS server has no claim_next on batch close), and the
tests that need the store/dial layer.
This commit is the mechanical lift: import paths rewritten, package renamed,
two compile gaps removed. The production code builds. Known follow-up in the
next commit: reconcile the client's vocabularies and encoder tables with the
OSS spec (e.g. the OSS problem code notes_overwrite_refused, policy/sort
differences), restore the test helpers the lifted tests need, and wire in the
S0 wire_revision handling and S1 OpenOptions credentials.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(httpclient): compile the lifted client and reconcile with the OSS wire
The lift in ab11cb1f8 carried relative test paths and vocabulary tables
from bd-enterprise's internal/enterprise/httpstore (4 directories below
repo root) into internal/httpclient (3 below), and several tables
described enterprise-only server behavior OSS does not serve. Reconcile:
- Add testTarget test helper (written fresh) so internal/httpclient
compiles and its tests pass.
- Fix four relative paths off by one "../" from the package relocation
(skew_test.go, ledger_render_test.go, bijection_test.go x2).
- skew_test.go: importsHTTPClient now matches internal/httpclient instead
of the retired internal/enterprise/httpstore path; the cmd/bd sweep no
longer hard-fails when it legitimately finds zero matching files (cmd/bd
does not import this client yet - that's S3's wiring).
- encode/table.go, encode/ledger_fields.go: removed a Reserved "reverse"
entry and a refused ExcludeIDs field claimed for listIssues/ReadyRequest;
OSS's listIssues never accepts "reverse" (confirmed against
internal/httpapi/reads.go and routes.go's CapIssuesListSort, which gates
`sort` only) and issueops.ReadyRequest carries no ExcludeIDs member in
OSS. Each removal is documented in place.
- encode/table.go, encode/encode.go, encode/roundtrip_test.go: countIssues
publishes has_metadata_key and include_ephemeral that CountRequest
carries and the table/encoder/round-trip corpus all silently dropped;
mapped and wired through.
- encode/ledger.go: ~70 ledger rows cited enterprise store-conformance and
cmd/bd subprocess-parity tests (dual-run reader, claim races, flag-mode
refusals) that don't exist in this package and belong to S3's store/dial
seam and cmd/bd wiring. Re-pinned to a documented TODO(S3) sentinel
(pinnedByS3Conformance) rather than deleted, per the ledger's own
well-formedness discipline.
- wire/handshake.go, wire/vocabulary_test.go: added CapBatchApplyLarge
(issues.batchApplyLarge) alongside the server's behaviorCapabilities.
- wire/problem.go: mapped the notes_overwrite_refused problem code to
issueops.ErrNotesOverwrite.
internal/httpclient/... is fully green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(httpclient): wire-revision handshake gate and batch cap from capability
S0 integration (task #2): Client.Handshake now reads ContextResponse's
wire_revision/min_client_wire_revision and refuses with a typed
*WireRevisionSkewError before any post-handshake call when the server's wire
shape falls outside [ClientMinWireRevision, ClientWireRevision] -- mirroring
DESIGN.txt sec 4's "Client rule". A decoded 0 is treated as "the server
omitted the member" per the permanently-retired-values rule, never as a value
needing refusal. The client now also stamps Bd-Wire-Revision on every request
(client.go's stampRequest), and problem.go gained the per-request mirror:
*WireRevisionUnsupportedError, decoded from the reason:"wire_revision_unsupported"
extension members, for the case where the SERVER refuses this client's
declared revision as too old. Both error types are deliberately distinct --
one is this client declining after reading a 200, the other is the server
refusing a request outright -- and neither branches on bd_version (only
assigns it into error text), so TestNoFeatureBranchesOnBdVersionOrSchemaVersion
stays green.
Also added legacyRevisionFields/decodeRevisionToken to problem.go: a
precondition_failed refusal's expected_version/actual_version, typed *string
on the generated Problem, now tolerates a pre-#6053 server sending either as a
bare JSON integer rather than the decimal string every server since has used,
recovering the field the primary decode silently drops rather than losing it.
Batch cap (task #3): ApplyBatch reads the handshake snapshot on every call and
enforces 100 items unless the server advertises issues.batchApplyLarge, in
which case the ceiling is issueops.MaxApplyBatchItems (1000) -- never a bare
compiled constant. A plan over the applicable cap refuses before the dial: via
the existing *CapabilityError machinery when advertising the capability would
help (D7 case 2), or via a new *BatchTooLargeError (unwraps to
issueops.ErrValidation) when it would not. BatchTooLargeError lives in
handshake.go rather than beside ApplyBatch because every exported method in
writes.go is swept by TestEveryOperationMethodRoutesThroughTheSharedDispatch as
an operation-dispatch method.
All three internal/httpclient/... packages build and `go test` passes with
TMPDIR=/data/projects/.scratch/s2t BEADS_TEST_SKIP=dolt.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(httpclient): REQUIRE-mode credential resolution bridge to backends.Credential
Task #4: adds the knob internal/storage/backends/backends.go's OpenOptions.Credential
doc explicitly deferred ("S1 does not add a RequireCredential knob to enforce
the multi-tenant rule mechanically -- that is deferred to S2").
ProvidedCredential wraps an embedder-supplied wire.CredentialProvider (via its
httpclient alias) as a backends.Credential, so a multi-tenant embedder (for
example gc, Gas City: one process serving many workspaces) can carry a
per-workspace credential through backends.OpenOptions without the backends
package needing to know this package's CredentialProvider shape.
ResolveCredential(opts, base, require) is the bridge itself:
- nil Credential, require=false: NewBearerProvider(base), the existing
single-tenant ambient bearer ladder (unchanged).
- nil Credential, require=true: ErrCredentialRequired -- the multi-tenant
fail-closed case backends.go's doc names: a missing per-workspace
credential must be a loud refusal, not a silent fall-through to
process-global ambient env that cannot tell one tenant's workspace from
another's.
- a ProvidedCredential with a non-nil Provider: returned directly,
regardless of require.
- a ProvidedCredential with a nil Provider, or any other
backends.Credential this package does not recognise: refused -- the
former as ErrCredentialRequired (a present-but-empty wrapper must not
look like "a credential was supplied"), the latter wrapping
backends.ErrUnsupportedCredential per the OpenWith contract
internal/storage/backends/open_with_test.go already pins
(TestBackendOpenWithRefusesUnsupportedCredentialType).
No bd-enterprise source was copied for this file; it is new code written
against the OSS backends.go contract and the existing BearerProvider/
CredentialProvider types already lifted into this package. Live-mutated all
three guards (the require branch, the ProvidedCredential type assertion, and
the nil-Provider check) and confirmed each produces a RED test before
reverting.
go build/vet/gofmt clean; `go test ./internal/httpclient/...` passes with
TMPDIR=/data/projects/.scratch/s2t BEADS_TEST_SKIP=dolt.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(httpclient): S2 task #6 wire-revision/legacy-decode coverage, fix legacyRevisionFields bug
Add httptest coverage for the two wire-revision mechanisms task #2 added
(commit 7ff68b29d8):
- handshake_wire_revision_test.go: the client-initiated skew gate
(checkWireRevision/WireRevisionSkewError) and the per-request
Bd-Wire-Revision header stamp. Live-mutated both switch arms in
checkWireRevision and the stamped header value; confirmed RED, reverted.
- problem_wire_revision_test.go: the server-initiated
wire_revision_unsupported refusal (reason-before-code dispatch priority)
and the legacy-integer revision-token fallback.
Writing the legacy-decode tests surfaced a real bug in legacyRevisionFields:
its presence guard treated any non-nil *string field as "already decoded,"
but encoding/json's indirect() pre-allocates a pointer to "" for a *string
field before discovering a type mismatch (e.g. a bare JSON integer). A
type-mismatched expected_version/actual_version therefore arrived as a
non-nil pointer to the empty string, not nil -- exactly the one case the
fallback exists to recover, and exactly the case the old guard skipped.
Fixed by adding revisionNeedsFallback(p) (nil-or-empty), used in place of
the bare nil checks. No legitimate server response uses a literal
empty-string revision token, so this changes no other behavior.
Live-mutated the fixed guard back to the old nil-only checks; confirmed RED
on both recovery tests, reverted.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(httpclient): S2 task #6 ApplyBatch item-cap coverage
Add writes_batch_cap_test.go: httptest coverage for ApplyBatch's
capability-gated item ceiling (task #3), separate from the generic
two-speed "is issues.batchApply routed at all" gate writes_twospeed_test.go
already covers.
Cases: at-or-under the 100-item floor succeeds without the capability;
over the floor without issues.batchApplyLarge refuses with a
*CapabilityError before any dial past the handshake; the capability raises
the ceiling to issueops.MaxApplyBatchItems (1000), both at the new ceiling
and strictly between the old floor and it; over the absolute ceiling
refuses with *BatchTooLargeError regardless of the capability, also
without dialing the batch-apply endpoint.
Live-mutated all three guards in ApplyBatch (the limit computation, the
n > limit check, and the capability-vs-absolute-ceiling branch); confirmed
each produces a distinct RED, reverted.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(httpclient): S2 task #6 live TLS coverage for wrong-CA refusal
Add ca_wrong_ca_test.go: an end-to-end httptest TLS dial proving
TransportFor's configured CA pool is actually enforced at the wire, not
just recorded on the transport struct. ca_test.go already proves the
latter (TestTransportForReplacesRootPoolNotExtends, via
x509.CertPool.Equal) and proves the RIGHT CA dials successfully
(TestTransportForFileRotationClosesSupersededIdleConnections's live GETs);
neither exercises a server whose leaf a DIFFERENT CA signed.
TestTransportForWrongCARefusesTheTLSHandshake dials a server through a
transport built from an unrelated CA file and asserts the handshake fails
with x509.UnknownAuthorityError. TestTransportForRightCASucceedsOverTLS is
the positive control, using the same (newly-exercised) ca.startServer
helper that was defined but had no caller before this test -- without it,
a mutation that drops RootCAs entirely (falling back to the system pool)
would still pass the wrong-CA test for the wrong reason; the positive
control catches that case. Live-mutated transportForFile to drop RootCAs;
confirmed the positive control goes RED, reverted.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* build(bazel): gazelle BUILD files for the lifted httpclient package tree
Task #7: bazel run //:gazelle, now that internal/httpclient and its
encode/wire subpackages exist in the OSS tree (ab11cb1f8) and have gained
this S2 slice's new files. No existing BUILD.bazel files changed; these
three packages previously had none.
Note for S3: bazel test //internal/httpclient/... fails on tests that read
sibling source trees by relative path at runtime
(TestLedgerRowsAreWellFormed, TestEveryEncoderTableParameterIsPublished,
TestDivergenceLedgerDocMatchesLedger in encode, and
TestNoFeatureBranchesOnBdVersionOrSchemaVersion,
TestEveryOperationMethodRoutesThroughTheSharedDispatch,
TestEveryOperationMethodIsCoveredByTheTwoSpeedTable in wire) -- paths like
../../../cmd/bd and ../../httpapi/spec/openapi.v0.yaml resolve under `go
test`'s working directory but not Bazel's sandbox, which gazelle cannot
infer `data` attributes for. Pre-existing in code from task #1/#2, not
introduced by this commit; `go test ./internal/httpclient/...`,
`go vet ./...`, `gofmt -l .`, `golangci-lint run ./internal/httpclient/...`,
and `make api-check` are all clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpclient/wire): tolerate bare-integer revision on success-path responses
Review HIGH #2: against a fake pre-#6053 server (one whose ContextResponse
omits wire_revision), CloseIssue and its revision-bearing siblings
(ApplyBatch, ReleaseIssue, ReopenIssue, UpdateIssue) failed with an untyped
`json: cannot unmarshal number ... revision of type string`. S0's
string-or-number tolerance (problem.go's legacyRevisionFields) only covered
the problem+json error path, never the success path.
Adds revision_tolerance.go: a pre-unmarshal rewrite that walks a response
body and turns a bare JSON number at a "revision" key into its exact decimal
string, scoped to the five apigen response types that carry the member and
gated on the handshake having seen no wire_revision at all. Left
apigen/types.gen.go and the OpenAPI spec untouched (both are
regenerate-and-diff gated by `make api-check`), rather than introducing a
custom Revision JSON type through codegen, to keep the fix's blast radius to
the wire package's own reader.
Updates ClientMinWireRevision's doc comment (handshake.go) to describe
tolerance on both halves of the wire instead of overclaiming the error-path
fix alone covered it. Adds revision_tolerance_test.go: a read (ListReadyWork)
and a guarded write (CloseIssue with ExpectedVersion) against a fake
pre-#6053 server, plus a modern-server control proving the rewrite never
fires when wire_revision is present. Mutation-tested: disabling the rewrite
reproduces the exact untyped UnmarshalTypeError the review reported.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* build(bazel): sandbox internal/httpclient's source-reading tests (Bazel gate green)
Review HIGH #1: the Bazel lane was red because three tests under
internal/httpclient read sibling/cross-package files by relative OS path at
runtime, which bazel test's sandbox does not materialize without an explicit
`data` dependency.
- internal/httpclient/encode/BUILD.bazel: encode_test gets
data = ["//cmd/bd:go_srcs", "//internal/httpapi/spec:openapi.v0.yaml",
"//:engdocs/design/http-divergence-ledger.md"] + glob(["*.go"]), covering
bijection_test.go's cmd/bd scan and ledger_render_test.go's golden-doc read.
- internal/httpclient/wire/BUILD.bazel: wire_test gets
data = ["//cmd/bd:go_srcs", "//internal/httpclient:go_srcs"] + glob(["*.go"]),
covering skew_test.go's AST sweep of both trees.
- internal/httpclient/BUILD.bazel gains a go_srcs filegroup via `make
bazel-sync` (tools/bazel/go_srcs.py): added "internal/httpclient" to the
script's managed PACKAGES list rather than hand-writing the block.
- internal/httpapi/spec/BUILD.bazel and the root BUILD.bazel gain
exports_files for openapi.v0.yaml and engdocs/design/http-divergence-ledger.md,
scoped to //internal/httpclient/encode:__pkg__.
- bijection_test.go's loadPublishedParameters now reads the wire contract
through spec.OpenAPIV0() (the package's existing go:embed) instead of a
relative os.ReadFile path, per review suggestion -- the embed makes the
parameter set reachable without a `data` dependency on the YAML at all; the
openapi.v0.yaml data entry above stays as defense in depth for any other
reader the package gains.
Ran via `bazel run //:gazelle` then `python3 tools/bazel/go_srcs.py`
(bazel-sync-check passes). `bazel test //internal/httpclient/...` is fully
green: 3/3 test targets pass.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs(httpclient): scrub private/enterprise infra references from code and docs
Review MEDIUM #3. Provenance headers ("Contributed by gascity from
bd-enterprise...") stay by design -- this removes references to private
infrastructure and unported internals from comment bodies and generated docs:
- wire/doc.go: dropped the internal/enterprise/hostedbeads and
internal/enterprise/storageprofile build-tag comparison (neither exists in
this OSS tree) and the dangling citation of the never-written
engdocs/design/http-client-backend.md, replacing both with an accurate
description of this package's own build-tag-free status and a pointer to
the divergence ledger that does exist.
- credential.go: CredentialProvider's doc no longer names gwauth/DPoP/gateway
auto-detection by their private spelling; describes the interface generically.
- ca.go: dropped "cherry-to-AWS RTT" (generalized to "a typical cross-region
RTT") and the cmd/bd/enterprise_connect.go file reference (generalized to
"a `bd connect --ca-file X`-style command").
- ca_permissions_unix.go / ca_permissions_unix_test.go: ~/.config/gascity and
/etc/gascity example paths replaced with ~/.config/bd and /etc/bd.
- encode/skew_test.go: beads.corp replaced with bd.example.invalid.
- encode/ledger_render.go + ledger_render_test.go: the generated-doc preamble
and regenerate-hint strings now name internal/httpclient/encode (this
package) instead of internal/enterprise/httpstore/encode; regenerated
engdocs/design/http-divergence-ledger.md via `go test
./internal/httpclient/encode -run TestDivergenceLedgerDocMatchesLedger
-update-ledger-doc` rather than hand-editing it.
Final grep for enterprise/cherry/gascity/corp/gwauth under internal/httpclient
and engdocs turns up only: provenance headers (kept deliberately), this
session's own "no bd-enterprise source copied" disclaimers, and a handful of
generic "enterprise-tagged"/"enterprise server" references describing a
build-tag or commercial-tier server concept in the abstract -- none name a
private host, path, or credential.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(httpclient): review LOW items -- S3 TODO, env-driven CA test, lockstep doc
Review LOW #4-#6:
- wire/skew_test.go: TODO(S3) on the branch where the cmd/bd AST sweep is
vacuous (no store/dial wiring yet), naming the slice that closes it.
- ca_wrong_ca_test.go: TestTransportForWrongCAViaEnvRefusesTheTLSHandshake,
the BEADS_HTTP_CA_FILE env-driven sibling of the existing direct-CAFile
wrong-CA test -- same live-TLS refusal, resolved through resolveCAFile's
host-scoped env syntax instead of Target.CAFile.
- vocabulary_test.go: expanded the ClientWireRevision/CurrentWireRevision
comment to explain why this repo holds them in strict lockstep (client and
server ship from the same commit) rather than merely <=, distinguishing it
from the real cross-version compatibility ClientMinWireRevision exists for.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpclient/wire): re-review HIGH-a/b -- cover IssueDetails, stop recursing into metadata
HIGH-a: the legacy-revision set was missing apigen.IssueDetails (GET
/v0/beads/issues/{id}'s body, an alias for types.IssueDetails that a grep for
"type ... struct" never sees). getIssue is a baseline op that can dispatch
with no cached handshake at all, so serverPredatesRevisionStrings now treats
"no snapshot" the same as "WireRevision == 0" instead of only the latter.
revisionBearingResponse's set is now pinned exhaustively against
internal/httpapi/wireshape/testdata/golden.json -- the same committed digest
TestWireShapeDigest guards -- by a new test
(TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember), so
a future schema gaining a `revision` member can't silently miss coverage
again. New coverage: both "with" and "without" a prior handshake for getIssue,
and an explicit items[].revision test for ApplyBatchResponse.
HIGH-b: the previous fix recursed into every nested object looking for a
bare-number "revision" key, which reached caller-owned blobs like
CloseIssueResponse.issue.metadata -- real user data shaped like
{"revision":3} came back silently coerced to a string, on every server the
broadened gate above now also covers. tolerateLegacyRevisionNumbers no longer
recurses at all: it rewrites only the body's own top-level "revision", and,
for *apigen.ApplyBatchResponse specifically, each item's top-level
"revision" in the top-level "items" array. New
TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata proves a metadata
document with "revision" keys at three nesting depths round-trips
byte-for-byte unchanged.
Mutation-tested both guards by hand (not committed): dropping the
IssueDetails case turns TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember
and both getIssue tests red with the exact missing-coverage/decode-failure
messages; reinstating a fully recursive rewrite turns
TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata red, showing the
metadata's revision keys silently rewritten at all three depths. Both
reverted clean before this commit.
internal/httpapi/wireshape/BUILD.bazel and internal/httpclient/wire/BUILD.bazel
export/declare testdata/golden.json as data for wire_test's new exhaustiveness
test.
Verified: go test ./internal/httpclient/... (ok, one pre-existing unrelated
flake in ca_wrong_ca_test.go confirmed not reproducible across 8 reruns),
golangci-lint run ./internal/httpclient/... (0 issues), make api-check (no
apigen drift), bazel test //internal/httpclient/... //internal/httpapi/wireshape/...
(5/5 PASSED).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpclient): stop the wrong-CA TLS tests racing Happy Eyeballs
Root cause: startServer rewrites its httptest TLS server's URL to the
hostname "localhost" so SNI is actually sent, but the server itself only
binds 127.0.0.1. net/http's default dialer does RFC 6555 Happy Eyeballs
for a hostname with more than one address family, racing a tcp6 dial to
::1:<port> against the real tcp4 dial. On this host, many unrelated
processes (JVM tooling) are bound to high ::1 ports, so the tcp6 race
occasionally "won" against a listener that had nothing to do with the
test, and the client spoke TLS to it instead -- surfacing as "tls: first
record does not look like a TLS handshake" rather than the expected
x509.UnknownAuthorityError. Confirmed via ss -tlnp captured at the moment
of failure (a java process holding the exact port raced) and via an
immediate manual redial to 127.0.0.1 on that port succeeding against the
real, still-live test server.
Fix: forceIPv4Loopback (new shared helper in ca_test.go) rewrites the
returned *http.Transport's DialContext to dial tcp4 only. SNI and the
request Host are unaffected, since crypto/tls and net/http derive both
from the URL, never from which address family carried the bytes. Wired
into every TLS fixture test in the package (ca_wrong_ca_test.go's three
tests, and ca_test.go's rotation test) -- grepped the rest of the repo
for the same "rewrite to localhost for SNI" pattern and found no other
occurrences.
Also fixed a latent bug this surfaced: TestTransportForWrongCAViaEnvRefusesTheTLSHandshake
called TransportFor(Target{}) with a nil BaseURL, so caHostMatches always
returned false and the CAFileEnv path was never actually exercised --
the nil RoundTripper was silently masked by http.Client's fallback to
http.DefaultTransport, which also failed to verify (via system roots)
for an unrelated reason. Now passes Target{BaseURL: u} so the test
exercises the host-scoped env-resolution path it documents.
go test -race -count=50 -run WrongCA: 8/8 clean. Whole package
go test -race -count=20: clean, twice. bazel test, golangci-lint,
make api-check: all green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpclient): repair CI-red tests and apply review fixes (adopt-pr #7210)
Three defects on the contributor head, none of them present on the base:
- test/docsync's TestEngdocsAndRootMarkdownLinks fails: the generated
divergence-ledger doc links http-client-backend.md, an architecture
spec this repository does not carry. Name it in a code span instead,
in ledgerDocPreamble, and regenerate the doc (-update-ledger-doc).
- TestCAFileHygieneRefusesGroupWritableFile fails under umask 022:
os.WriteFile's 0o660 passes through the umask, so the file lands 0640,
is never group-writable, and TransportForFile accepts it. Chmod it
explicitly. Its acceptance twin had the same gap on its file (only the
explicitly chmodded directory reached the user-private-group
exception), so chmod that file too: a mutant that drops the exception
for files alone passed the old test under umask 022 and fails the new
one.
- That acceptance twin calls the unix-only isUserPrivateGroup from
ca_test.go, which carries no build constraint, so the package's tests
do not compile for GOOS=windows. Move it, otherwise verbatim, into
ca_permissions_unix_test.go beside the other isUserPrivateGroup tests.
Review fixes (iteration 1):
- Encode dispatched through nine case arms of op/shape conjunctions
(cyclomatic 24). Switch on an (op, shape) struct key instead, and move
the getIssue and search-bridge arms into encodeGetIssue and
encodeSearch. The arms are disjoint, so dispatch and every error string
are unchanged. Cyclomatic 24 -> 10.
- EventStream.Next kept four accumulators and the per-field switch in
one loop (cognitive 27). Gather the accumulators into sseEvent and
fold each field line, per-event cap included, in applyField. Next
cognitive 27 -> 12; applyField is 11/11.
- The CA hygiene walk joined a relative symlink target onto the textual
containing directory, so with a/link -> ../b/c and b/c/x -> ../y it
resolved a/y where the kernel opens b/y: a valid CA was refused, or a
hygienic file at a/y was checked and read instead. readLinkTarget joins
onto the directory's EvalSymlinks path, taken after that directory's
own ancestors passed the hop-by-hop check. The regression test plants
a decoy at a/y; a lexical-join mutant reads it and fails.
- SaveTarget wrote a relative CAFile that every later LoadTarget
refuses. Both now go through checkCAFileAbsolute, so SaveTarget refuses
first, with LoadTarget's own message, and writes nothing.
- Document the cached transport TransportFor and TransportForFile return
as shared and read-only.
Review fixes (iteration 2):
- The walk still dropped a ".." inside a symlink target textually:
filepath.Join cleans a relative target, and an absolute target's
ancestors come from filepath.Dir, while the kernel takes that ".."
from wherever the component before it really leads. Both reviews
rated the relative leaf as a wrong-file read, and it is one: with
x/d -> ../e/s, x/L -> d/../y read a decoy at x/y where the kernel
opens e/y. The other three shapes are hygiene bypasses: an absolute
leaf target x/d/../y, and an ancestor link to d/../dir or x/d/../dir
with the CA at x/L/y, each read a file in a world-writable e that the
walk never checked. readLinkTarget now refuses a target with a ".."
after any other component, relative or absolute; a leading run of
".." is still taken from the directory's physical path. The test pins
all four shapes behind a control that refuses e/y named directly, and
a table pins hasInteriorDotDot's boundary. Mutants that drop the
refusal, limit it to relative targets, refuse every "..", or count
"." as a component each fail.
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>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
378 lines
16 KiB
Go
378 lines
16 KiB
Go
// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/parentwalk.go@49d1df2f6)
|
|
// to OSS beads under the MIT license.
|
|
package encode
|
|
|
|
import (
|
|
"net/url"
|
|
"slices"
|
|
"strings"
|
|
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/internal/workapi"
|
|
"github.com/steveyegge/beads/issueops"
|
|
)
|
|
|
|
// D4's `bd list --parent` walk, inverted.
|
|
//
|
|
// THE PROBLEM. The walk hands the store `bd list`'s whole built filter with only
|
|
// ParentID and Limit re-pointed per level (cmd/bd/list_show_filter_modes.go
|
|
// findAllDescendants), and workapi.BuildListFilter populates ExcludeStatus,
|
|
// Pinned, IsTemplate, ExcludeTypes, Ephemeral and SkipWisps on EVERY default
|
|
// listing. So the "ParentID-only shape" D4 originally named can never occur, and
|
|
// encoding those members verbatim is impossible anyway: listIssues publishes no
|
|
// exclude_status, no exclude_type and no is_template.
|
|
//
|
|
// THE RESOLUTION (escalation ga-2ieek, spec revision 6b428bf63). The wire
|
|
// publishes INTENTS — `all`, `include_templates`, `include_gates`,
|
|
// `include_infra` — not materialized exclusions, and the server's own role runs
|
|
// the SAME builder against the server's authoritative vocabulary. So the bridge
|
|
// inverts: it reads the intents back off the derived members, sends those, and
|
|
// lets the server re-derive. That is parity-positive as well as expressible —
|
|
// the re-derivation heals L7's degraded client-side vocabulary for the walk.
|
|
//
|
|
// WHY IT VERIFIES RATHER THAN PATTERN-MATCHES. Recognizing each member with its
|
|
// own hand-written rule would be a second encoder of BuildListFilter's
|
|
// semantics, and a second copy is a thing that can drift — which is exactly the
|
|
// objection recorded against inventing a reverse mapping. So the inversion reads
|
|
// the intents off the filter and then RE-RUNS THE REAL BUILDER to prove them:
|
|
// the intents are accepted only when the filter they produce carries the same
|
|
// derived members as the one in hand. The recognition is therefore not a copy of
|
|
// the derivation, it IS the derivation.
|
|
//
|
|
// ANY MEMBER THE RE-DERIVATION DOES NOT ACCOUNT FOR REFUSES, L12-style, citing
|
|
// its own ledger row — a user's `--exclude-type`, a `--pinned`, an
|
|
// `--include-templates` the intents cannot reach.
|
|
|
|
// ListConfig is the client-side status and type vocabulary the inversion
|
|
// recognizes with. It is workapi's own, because the filter being inverted was
|
|
// built from exactly this value: passing anything else would make the
|
|
// recognition an approximation of the derivation rather than the derivation.
|
|
type ListConfig = workapi.ListConfig
|
|
|
|
// ZeroVocabulary is the recognition set of an unconfigured workspace: the
|
|
// built-in statuses and the default infra types, which is the reading
|
|
// BuildListFilter itself gives one. Gates driving the table use it, and so does
|
|
// any caller with no store to ask.
|
|
func ZeroVocabulary() ListConfig { return ListConfig{} }
|
|
|
|
// NewListConfig assembles the recognition vocabulary from the three reads that
|
|
// are its only wire-visible source (D4's degraded-vocabulary row, L7).
|
|
//
|
|
// It exists so the STORE does not have to import workapi to build one. The
|
|
// bridge subpackage is the allowlisted home for that dependency and the store is
|
|
// not, which is the boundary the design's lint row draws — so the store reads
|
|
// the three values through its own settings role and hands them here.
|
|
func NewListConfig(customStatuses []types.CustomStatus, customTypes []string, infra map[string]bool) ListConfig {
|
|
return ListConfig{CustomStatuses: customStatuses, CustomTypes: customTypes, InfraSet: infra}
|
|
}
|
|
|
|
// The two stand-ins the re-derivation validates with.
|
|
//
|
|
// BuildListFilter validates `--status` and `--type` against the workspace
|
|
// vocabulary, and that check must NOT run here. The filter in hand already
|
|
// passed it on the way in, the value is being forwarded to a server that will
|
|
// apply its own AUTHORITATIVE vocabulary, and the client's copy is the degraded
|
|
// one (L7) — so re-validating client-side could refuse a table-backed custom
|
|
// status the server knows perfectly well.
|
|
//
|
|
// Substituting is exact rather than approximate because the derived members read
|
|
// these two fields only through predicates the stand-ins preserve: status
|
|
// matters as ""/"all"/"pinned"/"hooked"/other, and type matters as ""/"gate"/an
|
|
// infra name/other. Every "other" derives identically, so one representative
|
|
// stands for all of them.
|
|
const (
|
|
otherStatus = string(types.StatusOpen)
|
|
otherType = "task"
|
|
)
|
|
|
|
// derivedMember is one member BuildListFilter populates from the intent flags
|
|
// rather than from a user's filter, with the ledger row its mismatch cites.
|
|
//
|
|
// The order is the order the inversion compares in, and it is the order the
|
|
// encoder table declares them in, so a filter that diverges in two members
|
|
// always refuses on the same one.
|
|
var derivedMembers = []struct {
|
|
Field string
|
|
Ledger string
|
|
Equal func(got, want types.IssueFilter) bool
|
|
}{
|
|
{"ExcludeStatus", "P-IssueFilter.ExcludeStatus", func(g, w types.IssueFilter) bool { return sameSet(g.ExcludeStatus, w.ExcludeStatus) }},
|
|
{"Pinned", "P-IssueFilter.Pinned", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.Pinned, w.Pinned) }},
|
|
{"IsTemplate", "P-IssueFilter.IsTemplate", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.IsTemplate, w.IsTemplate) }},
|
|
{"ExcludeTypes", "P-IssueFilter.ExcludeTypes", func(g, w types.IssueFilter) bool { return sameSet(g.ExcludeTypes, w.ExcludeTypes) }},
|
|
{"Ephemeral", "P-IssueFilter.Ephemeral", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.Ephemeral, w.Ephemeral) }},
|
|
{"SkipWisps", "P-IssueFilter.SkipWisps", func(g, w types.IssueFilter) bool { return g.SkipWisps == w.SkipWisps }},
|
|
}
|
|
|
|
// walkIntents is what one walk filter is recognized as.
|
|
type walkIntents struct {
|
|
// Status is the user's `--status` value, forwarded verbatim. Empty means
|
|
// they named none.
|
|
Status string
|
|
// AllFlag, IncludeTemplates, IncludeGates, IncludeInfra and
|
|
// IncludeEphemeral are the five intent booleans listIssues publishes.
|
|
AllFlag bool
|
|
IncludeTemplates bool
|
|
IncludeGates bool
|
|
IncludeInfra bool
|
|
// IncludeEphemeral is the PLANE intent, and it arrived last: the listing
|
|
// published no way to merge the wisp plane when this inversion was written
|
|
// (D9 L1), so a wisp-inclusive walk had nowhere to go and refused. L1 is
|
|
// retired and the member is published, so the intent is read back off
|
|
// SkipWisps here like every other derived default.
|
|
IncludeEphemeral bool
|
|
}
|
|
|
|
// planParentWalk inverts a descendant-walk filter into listIssues parameters.
|
|
func planParentWalk(f types.IssueFilter, cfg ListConfig) (url.Values, error) {
|
|
intents, err := recognizeIntents(f, cfg)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
b := newBuilder(OpListIssues, string(SearchParentWalk))
|
|
// The residual sweep runs AFTER the inversion, which is the table's own
|
|
// order: the derived members are declared ahead of the plain refusals, so a
|
|
// filter that diverges in both refuses on the derived one.
|
|
b.refuseInexpressible(f)
|
|
|
|
b.str("parent", derefString(f.ParentID))
|
|
|
|
// The intents, in place of the exclusions they produced.
|
|
b.str("status", intents.Status)
|
|
b.boolean("all", intents.AllFlag)
|
|
b.boolean("include_templates", intents.IncludeTemplates)
|
|
b.boolean("include_gates", intents.IncludeGates)
|
|
b.boolean("include_infra", intents.IncludeInfra)
|
|
b.boolean("include_ephemeral", intents.IncludeEphemeral)
|
|
|
|
// The explicit user filters, under their documented parameters.
|
|
b.strPtr("type", (*string)(f.IssueType))
|
|
b.strPtr("assignee", f.Assignee)
|
|
b.list("label", f.Labels)
|
|
b.list("label_any", f.LabelsAny)
|
|
b.list("exclude_label", f.ExcludeLabels)
|
|
b.timestamp("created_before", f.CreatedBefore)
|
|
b.timestamp("created_after", f.CreatedAfter)
|
|
b.metadata(f.MetadataFields)
|
|
b.str("has_metadata_key", f.HasMetadataKey)
|
|
|
|
return b.done()
|
|
}
|
|
|
|
// recognizeIntents reads the intents off f's derived members and proves them by
|
|
// re-derivation, or refuses naming the member that does not fit.
|
|
//
|
|
// EVERY INTENT IS READ, NONE IS SEARCHED FOR. A search over candidate intents
|
|
// would find the right answer just as often, but it could not say WHICH member
|
|
// was wrong when it found none: every candidate mismatches somewhere, so
|
|
// reporting the first one tried would name an arbitrary member and the refusal
|
|
// would cite an arbitrary ledger row. Each intent is therefore derived from the
|
|
// member that uniquely determines it, ONE candidate is built, and the comparison
|
|
// attributes exactly.
|
|
//
|
|
// `all` is the intent no single member determines: it is read off the absence
|
|
// of the status exclusions together with the pinned default.
|
|
//
|
|
// UPSTREAM #5333 COLLAPSED ONE OF THE READINGS THIS USED TO MAKE. `--status all`
|
|
// used to leave the pinned default in place and was told apart from `--all` by
|
|
// exactly that; the fix stopped a selector that promises EVERY status from
|
|
// silently forcing Pinned=false, so the two spellings now build one identical
|
|
// filter and are one question here. What survives is the other direction: a
|
|
// pinned default with no status and no exclusions is now reachable only from an
|
|
// explicit `--all --no-pinned`, and the wire has no parameter for it, so it
|
|
// refuses on P-IssueFilter.Pinned instead of encoding a `status=all` that would
|
|
// now ask the server a wider question than the caller did.
|
|
func recognizeIntents(f types.IssueFilter, cfg ListConfig) (walkIntents, error) {
|
|
refuse := func(row string) (walkIntents, error) {
|
|
return walkIntents{}, &RefusedError{Op: OpListIssues, Shape: string(SearchParentWalk), Row: RowByID(row)}
|
|
}
|
|
|
|
issueType := derefString((*string)(f.IssueType))
|
|
intents := walkIntents{
|
|
Status: explicitStatus(f),
|
|
|
|
IncludeTemplates: f.IsTemplate == nil,
|
|
IncludeGates: !slices.Contains(f.ExcludeTypes, types.IssueType("gate")),
|
|
IncludeInfra: !carriesEveryInfraType(f.ExcludeTypes, cfg),
|
|
// SkipWisps is the only trace the plane intent leaves in a built
|
|
// filter, so a merged plane is read as `--include-ephemeral` and a
|
|
// skipped one as its absence.
|
|
IncludeEphemeral: !f.SkipWisps,
|
|
}
|
|
// An infra `--type`, or the type `gate` itself, suppresses its exclusions on
|
|
// its own, so their absence says nothing about the flag. Read it as unset:
|
|
// that omits a parameter the server does not need, and the verification
|
|
// below rejects the reading if it is ever wrong.
|
|
if issueType == "gate" {
|
|
intents.IncludeGates = false
|
|
}
|
|
if cfg.IsInfra(issueType) {
|
|
intents.IncludeInfra = false
|
|
}
|
|
// The same rule for the plane, and it has TWO suppressors rather than one:
|
|
// `--include-infra` admits the wisp plane as well as the infra types, and an
|
|
// infra `--type` routes to the plane on its own. Either one leaves SkipWisps
|
|
// false whatever the ephemeral flag was, so under either of them the pair is
|
|
// the same question as the infra intent alone — `--all --no-pinned` and
|
|
// `--status all` again — and inventing the second parameter would be a
|
|
// distinction the re-derivation cannot see.
|
|
if intents.IncludeInfra || cfg.IsInfra(issueType) {
|
|
intents.IncludeEphemeral = false
|
|
}
|
|
|
|
// The derivation's own reading of the status, which decides both the
|
|
// exclusion block and the pinned default.
|
|
derived := derivationStatus(intents.Status)
|
|
switch {
|
|
case len(f.ExcludeStatus) > 0:
|
|
// Exclusions survive only with no status and no `--all`.
|
|
intents.AllFlag = false
|
|
case derived != "":
|
|
// A named status suppresses the exclusions itself, so `all` shows only
|
|
// in the pinned default it also suppresses.
|
|
intents.AllFlag = f.Pinned == nil && derived != "pinned" && derived != "hooked"
|
|
case f.Pinned == nil:
|
|
intents.AllFlag = true
|
|
default:
|
|
// No status, no exclusions, and the pinned default still in place. Since
|
|
// upstream #5333 the only spelling that produces all three is
|
|
// `--all --no-pinned`, and the wire can carry neither half of it: `all`
|
|
// alone would drop the narrowing, and `status=all` no longer implies it
|
|
// server-side either. Refused here rather than read as `--status all`
|
|
// and left to the re-derivation below, which would refuse on the same
|
|
// member for a reason a reader would have to reconstruct.
|
|
return refuse("P-IssueFilter.Pinned")
|
|
}
|
|
|
|
want, err := workapi.BuildListFilter(issueops.ListRequest{
|
|
ParentID: derefString(f.ParentID),
|
|
Status: derived,
|
|
IssueType: derivationType(issueType, cfg),
|
|
AllFlag: intents.AllFlag,
|
|
IncludeTemplates: intents.IncludeTemplates,
|
|
IncludeGates: intents.IncludeGates,
|
|
IncludeInfra: intents.IncludeInfra,
|
|
IncludeEphemeral: intents.IncludeEphemeral,
|
|
}, cfg)
|
|
if err != nil {
|
|
// The stand-ins are drawn from the built-in vocabulary, so the builder
|
|
// cannot refuse them for being unknown. Reaching here means it refused
|
|
// the SHAPE, which is a client bug rather than a wire limitation — but
|
|
// it is still a refusal rather than a panic, because the alternative is
|
|
// answering a question this bridge has not understood.
|
|
return refuse("P-IssueFilter.unrecognized")
|
|
}
|
|
if row, mismatched := firstDerivedMismatch(f, want); mismatched {
|
|
return refuse(row)
|
|
}
|
|
return intents, nil
|
|
}
|
|
|
|
// firstDerivedMismatch reports the ledger row of the first derived member the
|
|
// recognized intents do not reproduce.
|
|
func firstDerivedMismatch(got, want types.IssueFilter) (string, bool) {
|
|
for _, member := range derivedMembers {
|
|
if !member.Equal(got, want) {
|
|
return member.Ledger, true
|
|
}
|
|
}
|
|
return "", false
|
|
}
|
|
|
|
// derivationStatus maps a user's status onto the representative the derivation
|
|
// behaves identically for. See otherStatus.
|
|
func derivationStatus(status string) string {
|
|
switch status {
|
|
case "", "all", "pinned", "hooked":
|
|
return status
|
|
default:
|
|
return otherStatus
|
|
}
|
|
}
|
|
|
|
// derivationType maps a user's type onto the representative the derivation
|
|
// behaves identically for. See otherType.
|
|
func derivationType(issueType string, cfg ListConfig) string {
|
|
switch {
|
|
case issueType == "":
|
|
return ""
|
|
case issueType == "gate":
|
|
return "gate"
|
|
case cfg.IsInfra(issueType):
|
|
return issueType
|
|
default:
|
|
return otherType
|
|
}
|
|
}
|
|
|
|
// explicitStatus renders the status intent that produced f's status members.
|
|
//
|
|
// A single status came from a bare `--status` name; several came from one
|
|
// comma-separated value, which is also how the wire's `status` parameter carries
|
|
// them (the operation reads it with the comma decoder and the role splits it
|
|
// again). Joining and re-splitting is therefore a round trip, not a guess.
|
|
func explicitStatus(f types.IssueFilter) string {
|
|
if f.Status != nil {
|
|
return string(*f.Status)
|
|
}
|
|
if len(f.Statuses) == 0 {
|
|
return ""
|
|
}
|
|
parts := make([]string, 0, len(f.Statuses))
|
|
for _, s := range f.Statuses {
|
|
parts = append(parts, string(s))
|
|
}
|
|
return strings.Join(parts, ",")
|
|
}
|
|
|
|
// carriesEveryInfraType reports whether the exclusions hold the whole
|
|
// client-derivable infra vocabulary, which is what `--include-infra` being off
|
|
// produces.
|
|
//
|
|
// EVERY member, not any: a partial overlap is a user's own `--exclude-type` that
|
|
// happens to name an infra type, and reading it as the derived default would
|
|
// drop the rest of their exclusion silently.
|
|
func carriesEveryInfraType(excluded []types.IssueType, cfg ListConfig) bool {
|
|
infra := cfg.InfraTypes()
|
|
if len(infra) == 0 {
|
|
return false
|
|
}
|
|
for _, t := range infra {
|
|
if !slices.Contains(excluded, types.IssueType(t)) {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
|
|
// sameSet compares two exclusion lists as SETS.
|
|
//
|
|
// Order is not part of the meaning and is not even stable on one side:
|
|
// ListConfig.InfraTypes ranges a map when the workspace configures its own, so
|
|
// the infra members BuildListFilter appends arrive in a different order run to
|
|
// run. A slice comparison would make the inversion flaky on exactly the
|
|
// workspaces that configured the vocabulary it exists to respect.
|
|
func sameSet[T ~string](a, b []T) bool {
|
|
if len(a) != len(b) {
|
|
return false
|
|
}
|
|
left, right := slices.Clone(a), slices.Clone(b)
|
|
slices.Sort(left)
|
|
slices.Sort(right)
|
|
return slices.Equal(left, right)
|
|
}
|
|
|
|
func boolPtrEqual(a, b *bool) bool {
|
|
if a == nil || b == nil {
|
|
return a == nil && b == nil
|
|
}
|
|
return *a == *b
|
|
}
|
|
|
|
func derefString[T ~string](p *T) string {
|
|
if p == nil {
|
|
return ""
|
|
}
|
|
return string(*p)
|
|
}
|