beads/internal/httpapi/reads.go
Julian Knutsen 4af58c97fd
feat(count): Counter scope — ParentID, NoParent, ExcludeTypes, ExcludeStatus (issues.count.scope) (#7199)
* 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(count): add Counter scope fields (S8) — ParentID, NoParent, ExcludeTypes, ExcludeStatus

Extends issueops.CountRequest with ParentID, NoParent, ExcludeTypes and
ExcludeStatus, closing the gap where bd count could not express the
filters bd list already has, forcing downstream consumers like gc to
fall back to listing everything just to get a count.

- issueops.Counter: four new CountRequest fields, documented against the
  List equivalents they mirror (ParentID/ExcludeTypes) or newly define
  (NoParent, ExcludeStatus has no List counterpart). Status "all" is
  pinned as equivalent to unset, matching BuildListFilter's own "all" and
  preserving count/list cardinality parity (the role's reason to exist).
- internal/workapi.BuildCountFilter: maps the four fields onto the one
  types.IssueFilter builder all three storage legs (dolt, embeddeddolt,
  uow) already share via internal/storage/issueops and sqlbuild, so no
  per-leg storage code was needed.
- cmd/bd: --parent, --no-parent, --exclude-type, --exclude-status flags.
- HTTP: adds parent/no_parent/exclude_type/exclude_status to GET
  /v0/beads/issues:count, behind the new issues.count.scope behavior
  token (routes.go), wired in reads.go's countFilters, documented in
  openapi.v0.yaml with per-parameter tokens and an extended capabilities
  description. gendigest confirms a byte-identical golden.json: query
  parameters are outside the wire-shape digest's scope, so this is a
  zero-diff, no-revision-bump change as expected.
- backend/conformance: four new Counter contract cases (ParentID scoping,
  NoParent's edge-only semantics vs ParentID's edge-or-dotted-id match,
  ExcludeTypes composing with include_infra's own exclusions, and
  ExcludeStatus), run identically against all three storage legs via a
  new CounterFixture.AddDependency hook shared with ReaderFixture.

Verified: go build ./...; go test ./internal/httpapi/... ./internal/workapi/...
./issueops/... and the Counter contract on all three legs (dolt via
testcontainers, embeddeddolt, uow via local dolt binary); make api-gen
(additive-only apigen diff) and make api-check; go vet and golangci-lint
clean; gofmt clean; gazelle diff empty (no new files/imports). Mutation
testing: dropping issues.count.scope from behaviorCapabilities turns
TestCapabilitiesAdvertiseEveryImplementedOperation,
TestSpecCapabilityVocabularyMatchesTheRouteTable and
TestNewParameterOnExistingOperationHasABehaviorToken red; no-op'ing
ExcludeStatus in BuildCountFilter turns
TestBuildCountFilterExcludeStatusTakesNamesAsWritten and the
embeddeddolt ExcludeStatusNarrowsThePredicate conformance case red. Both
reverted and reconfirmed green.

Deviation: DESIGN.txt's literal text would make count --status all an
ErrValidation; shipped behind a test and a doc comment instead, since
"all" already means "every status" on both count and list and rejecting
it would break the count/list parity this role exists to guarantee.

S3/S4 note: no OSS HTTP client exists yet to enforce capability-token
skew. A doc comment on CapIssuesCountScope in routes.go specifies the
required behavior once one lands: check issues.count.scope against the
cached handshake capabilities and refuse locally with a typed
ErrUnsupported{Capability} before sending any of the four new params to
an older server.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(count): S8 review follow-ups — refusal parity, exclude-status validation, doc fixes, parity tests

Addresses the Opus review's six required changes for S8 (bd count scope
fields):

1. BuildCountFilter now refuses ParentID+NoParent together as ErrValidation,
   matching bd list's CLI refusal wording; wired through the role, the CLI,
   and invalid_argument classification in internal/httpapi/reads.go.
2. Status:"all" is documented in DESIGN.txt as every status, matching List's
   no-filter reading (count/list cardinality parity) — a coordinator decision
   recorded in beads-design/DESIGN.txt, outside this worktree.
3. ExcludeStatus names are now validated against the workspace vocabulary
   (built-in statuses plus workspace-custom ones); an unknown name is
   ErrValidation instead of a silent no-op, since a typo here would overcount.
4. Fixed openapi.v0.yaml and issueops/reader.go doc claims about bd list
   --parent's default tree-walk vs. the one-level role answer that bd count
   --parent agrees with (confirmed by tracing list_show_filter_modes.go); fixed
   an Oxford-comma nit in routes.go and the spec.
5. Added storage-level count == len(List) parity tests for ParentID, NoParent
   and ExcludeTypes (List has no ExcludeStatus counterpart), plus wisp-child
   and closed-child contract cases, across all three backends (dolt,
   embeddeddolt, uow). CounterFixture gained a List hook for this.
6. Extended the routes.go skew note: gc's ErrCountUnsupported fallback to List
   is now named explicitly, with a note that S3/S4 must add a skew test that
   masks the token and asserts the fallback fires.

Also fixed RunCounterExcludeStatusNarrowsThePredicate's now-stale "unrecognized
status excludes nothing" assertion to expect ErrValidation instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(count): PR #7199 review follow-ups — exclude-status config load, ParentID doc swap

Addresses bee's REQUEST-CHANGES on gastownhall/beads#7199 (S8):

1. BLOCKER: storecounter.filter and uow.countFilter only loaded the
   workspace list config when IncludeInfra was set, so BuildCountFilter's
   ExcludeStatus validation refused a workspace's own custom status unless
   the caller also passed the unrelated IncludeInfra flag. Both legs now
   load the config when IncludeInfra OR len(ExcludeStatus) > 0, with
   comments corrected to say so. Added leg-level regression tests (the
   conformance fixture cannot drive a workspace-configured custom status)
   on embeddeddolt and uow, reproducing the reviewer's CLI repro directly,
   plus an HTTP-level probe in cmd/bd's real-Dolt proxied count test.
2. issueops.ReadyRequest.ParentID's comment had been overwritten with the
   one-level direct-children wording that belongs to ListRequest.ParentID;
   Ready actually walks all descendants via GetDescendantIDsInTx (GH#3396).
   Restored the descendants comment on ReadyRequest.ParentID and moved the
   one-level explanation to ListRequest.ParentID, which had none.

Verified: make api-check; dolt-server, embeddeddolt and uow Counter
contract legs (BEADS_TEST_DOLT_SERVER=local with a pinned dolt binary for
uow; Docker for the dolt-server leg); the new proxied HTTP exclude_status
probe (BEADS_TEST_PROXIED_SERVER=1).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* chore(wireshape): add the countIssues scope parameters to the wire-shape golden

#7182 now digests operation parameters. The four new issues:count parameters
(parent, no_parent, exclude_type, exclude_status) are additive entries, so no
wire_revision bump is needed; regenerated with gendigest.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(conformance): register the S8 count-scope cases with RunRoleContracts (adopt-pr #7199)

The PR adds nine RunCounter* contract cases to counter_contract.go and wires
them into the three in-tree TestCounterContract legs, but not into the
Counter row of roleContractCases. TestRoleContractCasesCoverEveryContractCase
derives the expected set from source, so it fails on the PR head, and an
external backend running RunRoleContracts would never see the new cases.

Register them in source-declaration order (after
RunCounterAnUnknownStatusMatchesNothing), which the same guard enforces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(count): correct the S8 scope docs the review found wrong (adopt-pr #7199)

Comment and spec-description fixes only; no behavior change. Review-loop
iterations 1 and 2 of the #7199 relaunch.

- ListRequest.ParentID (issueops/reader.go) said "DIRECT children only
  ... the same one-level clause". The sqlbuild clause has two arms and
  neither walks: the parent-child edge arm stops at one level, but the
  dotted-prefix arm (`id LIKE CONCAT(?, '.%')` for rows with no
  parent-child edge) reaches every edge-less dotted id at any depth, which
  RunReaderListParentReachesEveryDescendantAndOnlyItsOwn pins with an
  edge-less X.1.1. State both arms, and say the CLI tree view re-runs the
  clause against the store once per level (findAllDescendants calls
  SearchIssues, not the role). Document ListRequest.NoParent, which had no
  doc. The contributor's ReadyRequest.ParentID text is kept; only its
  cross-reference to this field changes from "one-level" to "non-walking".
- CountRequest.NoParent (issueops/counter.go) and the count flag comment
  (cmd/bd/count.go) said NoParent counts rows with "neither" an edge nor a
  dotted prefix. Its SQL checks only the edge table, so an edge-less X.1
  is counted by both --parent X and --no-parent, as bd list lists it.
- RunCounterExcludeStatusNarrowsThePredicate's header said an
  unrecognized name "excludes nothing rather than failing" while its body
  asserts ErrValidation. The header now matches the body.
- The OpCountIssues entry in problem.go's operationCodes said the role has
  "exactly one reachable refusal". It has three: an invalid metadata key,
  an unrecognized exclude_status name, and parent with no_parent (named
  no_parent), all classified by invalidFilterParam. The code set is
  unchanged.
- BuildCountFilter's header said cfg is "only read under IncludeInfra".
  It is also read to validate ExcludeStatus against the workspace's
  custom statuses, which is why both callers load it when ExcludeStatus is
  non-empty.
- The countIssues `parent` description in openapi.v0.yaml carried the
  same one-level claim as ListRequest.ParentID; it now states both arms.
  types.gen.go is regenerated (make api-gen); make api-check passes.

Review fixes (iteration 2), still comment and spec text only:
- The iteration-1 problem.go rewrite called all three count refusals
  ErrValidation. Only the exclude_status and parent-with-no_parent
  refusals wrap issueops.ErrValidation (internal/workapi/count.go). The
  metadata-key refusal is ValidateMetadataFilters' plain fmt.Errorf
  chain, so errors.Is(err, ErrValidation) is false for it; it reaches the
  wire as a 400 only because invalidFilterParam matches message prefixes.
  The comment now says that, so a later move to typed errors cannot trust
  it and demote the metadata-key refusal to a 500. The sentinel itself is
  not added here: ValidateMetadataFilters is shared with the list and
  ready builders.
- invalidFilterParam's comment on the count rows pointed at the
  metadata-key rows as "above"; they come after it in the switch.
- The countIssues `parent` description said the CLI tree mode walks
  "every edge-linked descendant". findAllDescendants re-runs the full
  two-arm predicate per level, so it also descends through edge-less
  dotted ids; it now says "every descendant reachable through either
  arm". types.gen.go is regenerated; make api-check passes.

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>

* chore(wireshape): re-record the count scope params under the base's param digest (adopt-pr #7199)

The base branch (feat/wire-revision-signal, #7182 be1f0bad72) now digests
the effective style/explode of scalar query parameters. This PR's golden
entries for countIssues query:parent and query:no_parent were written by
the old algorithm, so after the base refresh TestWireShapeDigest reported
them as "changed without a wire_revision bump".

No bump is owed: all four count-scope entries (parent, no_parent,
exclude_type, exclude_status) are additions this PR introduces and are
absent from the base golden. golden.json was reset to the base copy and
regenerated with `go run ./internal/httpapi/wireshape/cmd/gendigest`. The
result is four pure additions against the base (+35/-0); parent and
no_parent gain "style": "form" and "explode": true, and wire_revision
stays 2.

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>

* ci: place the PR's new embedded counter test in the shard manifest

TestCounterExcludeStatusAcceptsAWorkspaceCustomStatusWithoutIncludeInfra,
added to internal/storage/embeddeddolt in f23bf5ddbf, is a new top-level
embedded storage test. The 15-shard block of
.github/scripts/embedded-storage-test-shards.txt must list every
discovered test exactly once. Without the entry,
TestStorageEmbeddedShardManifestGeneratorNotStale (scripts/) fails, both
on the reviewed head 89a387de6c and on the merge. CI never ran the check
on this PR: pr.yml runs only for PRs based on main, release/** or
hotfix/**, and this PR was based on feat/wire-revision-signal until the
retarget.

Generated with
`python3 scripts/ci/gen_embedded_storage_shard_manifest.py 15 --weights=duration --write`.
The incremental write adds this one line, in shard 4, and moves no other
test.

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>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
2026-10-05 02:57:14 -07:00

655 lines
26 KiB
Go

package httpapi
import (
"net/http"
"strings"
"github.com/steveyegge/beads/internal/httpapi/apigen"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// The issue-collection reads. Each one decodes its parameters, hands the whole
// request to a role, and shapes the answer onto the wire. Three are on
// issueops.Reader (ready, list, detail); the count and the query are on
// ReadyCounter and Querier, siblings reached the same way through the same
// provider accessors. What follows is about the Reader three, and holds for
// the other two in every respect but which role they name.
//
// WHAT IS NOT HERE IS THE POINT. No filter is built, no ConfigSource is wired,
// no default limit is applied, no status exclusion is chosen, no wisp fallback
// is arranged: all of that is inside issueops.Reader's implementation, which
// `bd show --json` reaches through the same accessor. A handler that skipped a
// step of that construction — which is exactly how a hosted viewer once shipped
// a bare IssueFilter and silently served in_progress rows as "ready" — is not
// writable from here.
//
// That is a MACHINE claim, not a convention, and it takes two rules because
// there are two ways to build a filter. The depguard rule
// httpapi-transport-boundary denies internal/workapi from this package's
// non-test files, so the builders are not importable here at all. That alone
// would leave the door the hosted viewer actually walked through: it did not
// misuse a builder, it hand-rolled `IssueFilter{}` — and internal/types is
// reachable from here, for CheckFieldLen and IssueWithCounts below. So the
// forbidigo rule in .golangci.yml denies NAMING types.IssueFilter or
// types.WorkFilter in this package at all — every file of it, so a file added
// here tomorrow is covered the moment it exists. Both rules run in
// `make ci-pr-lint`, which the PR workflow runs on every pull request and
// aggregates into its ci-gate job; what that gate is and is not worth as
// enforcement is stated once, in doc.go.
//
// `bd ready` and `bd list` still call the builders directly, for the reasons
// issueops.Reader's doc comment sets out. They are not unguarded for it: they
// build from the same request types through the same builders, and they run
// the same workapi.FinishPage epilogue the reader below runs — `bd list` in
// every mode but the hierarchical --parent tree, `bd ready` on its proxied
// route only. Where both hold, what a CLI listing and one of these bodies can
// differ by is presentation, not the query and not the page. `bd show --json`
// is on the role outright, on both its routes.
//
// What DOES stay here is transport: parameter decoding, the opaque cursor
// codec, the bind-mode refusal of an unlimited read, and the wire envelopes.
// handleReady answers GET /v0/beads/ready.
func (s *Server) handleReady(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
req := readyFilters(q)
// EXPLICIT, always. The storage layer maps an EMPTY sort policy to hybrid,
// and forwarding an absent `sort` as "" would silently adopt that fallback
// while the document still read `default: priority`. It is not a cosmetic
// difference: hybrid demotes older high-priority work, so the item SET
// changes as soon as `limit` truncates — and only for the clients this API
// exists to migrate off `bd ready`, whose flag registers a concrete default
// and never sends empty.
req.Sort = q.oneOf("sort", readySortDefault, "hybrid", "priority", "oldest")
req.Limit = q.limit()
// Decoded here and not in readyFilters, which is the vocabulary the count
// shares: this is a projection of the rows a page returns, in the same
// class as the two lines above it, and the count returns no rows to project.
req.Brief = q.boolean("brief")
if !s.acceptQuery(w, r, q) {
return
}
if !s.allowUnlimited(w, r, req.Limit) {
return
}
rd, err := s.reader(r)
if err != nil {
s.failErr(w, r, err)
return
}
page, err := rd.Ready(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
writeJSON(w, apigen.ReadyPage{
Items: wireItems(page.Items),
HasMore: page.HasMore,
})
}
// readyFilters decodes the ready-work filter vocabulary the two ready
// operations share — everything except the PAGE, which only the listing has,
// and the ORDER, which only the listing needs.
//
// It is one function because the two operations must admit exactly the same
// filters: countReadyWork answers with the size of the set listReadyWork
// returns, and a parameter one of them decoded and the other did not would
// make that identity false for any client that sent it.
func readyFilters(q *query) issueops.ReadyRequest {
return issueops.ReadyRequest{
Assignee: q.str("assignee"),
Unassigned: q.boolean("unassigned"),
IssueType: q.str("type"),
ExcludeTypes: q.list("exclude_type"),
Labels: q.list("label"),
LabelsAny: q.list("label_any"),
ExcludeLabels: q.list("exclude_label"),
LabelPattern: q.str("label_pattern"),
LabelRegex: q.str("label_regex"),
Priority: q.integer("priority"),
ParentID: q.str("parent"),
MetadataFields: q.metadataFields("metadata_field"),
HasMetadataKey: q.str("has_metadata_key"),
IncludeEphemeral: q.boolean("include_ephemeral"),
IncludeDeferred: q.boolean("include_deferred"),
}
}
// handleCountReady answers GET /v0/beads/ready:count.
//
// THE REQUEST IS THE LISTING'S REQUEST with the page taken off, which is what
// makes the answer the size of the page the listing would return. It is not
// assembled here beyond that: the role refuses a Limit and an Offset itself
// (issueops.ReadyCounter.CountReady), so this handler could not smuggle a
// bounded count past it even if a parameter for one existed.
//
// THE SORT IS SENT ANYWAY, and the operation publishes no parameter for it. A
// count has no order, but the request still has to be one the builder accepts,
// and sending "" would adopt the storage layer's hybrid fallback that no front
// door relies on.
func (s *Server) handleCountReady(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
req := readyFilters(q)
req.Sort = readySortDefault
if !s.acceptQuery(w, r, q) {
return
}
counter, err := s.readyCounter(r)
if err != nil {
s.failErr(w, r, err)
return
}
result, err := counter.CountReady(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
writeJSON(w, apigen.ReadyCount{Total: result.Total})
}
// readySortDefault is the ordering this operation applies when `sort` is
// absent. It is the same value `bd ready --sort` registers.
//
// Three things have to agree: the frozen document, the CLI flag, and this.
// TestDefaultsMatchCLIFlags compares all three against each other and
// TestReadyForwardsAnExplicitSortPolicy asserts the LITERAL "priority" on the
// filter the handler built — deliberately not this constant, because an
// assertion against the value the handler itself read would hold for every
// value it could take.
const readySortDefault = "priority"
// countFilters decodes the count's predicate: every filter the role publishes
// and nothing about a page, an order or a bucket.
//
// It is a function of its own for readyFilters' reason turned inside out. That
// one is shared because two operations must admit the same parameters; this one
// has a single caller, and it is split off so a test can drive it over an empty
// query and read back the EXACT set of names this handler asks for
// (query.read). That is what makes the parameter-parity check mechanical rather
// than a second hand-rolled list beside the document's.
func countFilters(q *query) issueops.CountRequest {
return issueops.CountRequest{
// ONE status, not the listing's comma-separated OR set. The role says so
// and the document says so; reading it with q.csv here would publish a
// set the role would answer 0 for.
Status: q.str("status"),
IssueType: q.str("type"),
Assignee: q.str("assignee"),
Priority: q.integer("priority"),
PriorityMin: q.integer("priority_min"),
PriorityMax: q.integer("priority_max"),
Labels: q.list("label"),
LabelsAny: q.list("label_any"),
TitleSearch: q.str("title"),
// A COMMA-SEPARATED string, handed over as written: the role splits,
// trims and de-duplicates it, and a handler that pre-split it would be
// deciding what an id set means.
IDFilter: q.str("id"),
TitleContains: q.str("title_contains"),
DescContains: q.str("desc_contains"),
NotesContains: q.str("notes_contains"),
CreatedAfter: q.timestamp("created_after"),
CreatedBefore: q.timestamp("created_before"),
UpdatedAfter: q.timestamp("updated_after"),
UpdatedBefore: q.timestamp("updated_before"),
ClosedAfter: q.timestamp("closed_after"),
ClosedBefore: q.timestamp("closed_before"),
EmptyDesc: q.boolean("empty_description"),
NoAssignee: q.boolean("no_assignee"),
NoLabels: q.boolean("no_labels"),
MetadataFields: q.metadataFields("metadata_field"),
HasMetadataKey: q.str("has_metadata_key"),
// The plane switches, each forwarded as the boolean the caller sent.
// What include_infra MEANS — merge the wisps tier, drop templates, drop
// gates, and route an infra type to the ephemeral tier — is four
// decisions the role makes from the WORKSPACE's own infra vocabulary,
// which is a config load this handler must never perform.
IncludeInfra: q.boolean("include_infra"),
// include_ephemeral is the first of those four and none of the rest, so
// it reaches the role as its own field and never as IncludeInfra: folded
// into it, a plane-only count would also lose its templates and gates.
IncludeEphemeral: q.boolean("include_ephemeral"),
// The four scope fields behind `issues.count.scope` (S8): ParentID and
// ExcludeTypes are read exactly as the listing reads them (q.str("parent"),
// q.list("exclude_type")), because the role documents its own ParentID and
// ExcludeTypes as spelling ListRequest's fields identically. NoParent and
// ExcludeStatus have no listing counterpart to mirror — NoParent is a new
// boolean switch and ExcludeStatus is a Count-only capability the listing
// never exposed — so both are read with this file's own conventions for
// their kind (q.boolean, q.list) rather than a listing precedent.
ParentID: q.str("parent"),
NoParent: q.boolean("no_parent"),
ExcludeTypes: q.list("exclude_type"),
ExcludeStatus: q.list("exclude_status"),
}
}
// countGroupOf reads the bucketing dimension and reports whether one was asked
// for.
//
// PRESENCE is the signal, which is why this returns a boolean beside the value:
// an absent `group_by` selects the scalar method, and q.oneOf's fallback alone
// would collapse "no bucketing asked for" into a dimension. An unknown value is
// refused HERE rather than at the role, so the 400 names the parameter — the
// role's own rule (an unknown dimension is ErrValidation, never an empty
// answer) with the member name a client dispatches on added.
func countGroupOf(q *query) (issueops.CountGroup, bool) {
grouped := q.has("group_by")
return issueops.CountGroup(q.oneOf("group_by", "", countGroupNames()...)), grouped
}
// countGroups is the closed dimension vocabulary, in the document's order, so
// the schema's enum and the values this server accepts are one list read twice
// rather than two lists kept in step by hand.
//
// It is spelled with the ROLE's constants rather than as bare strings: the wire
// names and issueops.CountGroup's values are the same strings today, and
// deriving one from the other is what keeps them the same tomorrow.
var countGroups = []issueops.CountGroup{
issueops.CountGroupStatus,
issueops.CountGroupPriority,
issueops.CountGroupType,
issueops.CountGroupAssignee,
issueops.CountGroupLabel,
}
// countGroupNames is countGroups as the strings q.oneOf compares against.
func countGroupNames() []string {
names := make([]string, len(countGroups))
for i, g := range countGroups {
names[i] = string(g)
}
return names
}
// handleCountIssues answers GET /v0/beads/issues:count.
//
// ONE HANDLER FOR BOTH OF THE ROLE'S METHODS, because `group_by` chooses
// between two shapes of one answer rather than between two questions: the same
// predicate over the same set, differing only in whether the reply is one
// number or a number per bucket. The grouped result carries the scalar total
// itself, which is why splitting them would have put one role's promise inside
// the other's result.
//
// WHAT IS NOT HERE is this file's whole point, and on a count it is more than
// usual. No filter is built, no ConfigSource is wired, and the workspace's
// INFRA VOCABULARY is never read — that config load is precisely what
// issueops.Counter exists to keep off a front door.
//
// The default answer is the ROLE's too, and it is NOT the listing's: an empty
// request counts every durable row including closed, pinned, template and gate
// ones. A handler that "helpfully" applied the listing's exclusions would be
// answering a different question with the same parameters.
func (s *Server) handleCountIssues(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
req := countFilters(q)
group, grouped := countGroupOf(q)
if !s.acceptQuery(w, r, q) {
return
}
counter, err := s.counter(r)
if err != nil {
s.failErr(w, r, err)
return
}
if grouped {
// THE SAME PREDICATE reaches both methods, which is the identity the
// role promises: a grouped count is a scalar count plus a dimension, so
// the two cannot be asked of different sets.
result, err := counter.CountByGroup(r.Context(), issueops.CountByGroupRequest{Filter: req, GroupBy: group})
if err != nil {
s.failReadErr(w, r, err)
return
}
// `groups` is PRESENT because the request asked for buckets, even when
// the answer has none: an empty object means "nothing matched" and an
// absent member means "you did not ask", and a client must be able to
// tell those apart without re-reading its own request. The role promises
// a non-nil map; this does not lean on that promise, because a nil map
// would marshal as `{}` anyway and leaning on it would make the
// difference invisible if it ever broke.
groups := result.Groups
if groups == nil {
groups = map[string]int{}
}
writeJSON(w, apigen.IssueCount{Total: result.Total, Groups: &groups})
return
}
result, err := counter.Count(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
writeJSON(w, apigen.IssueCount{Total: result.Total})
}
// handleListIssues answers GET /v0/beads/issues.
func (s *Server) handleListIssues(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
req := issueops.ListRequest{
Status: q.csv("status"),
IssueType: q.str("type"),
Assignee: q.str("assignee"),
Labels: q.list("label"),
LabelsAny: q.list("label_any"),
ExcludeLabels: q.list("exclude_label"),
ParentID: q.str("parent"),
Brief: q.boolean("brief"),
AllFlag: q.boolean("all"),
IncludeTemplates: q.boolean("include_templates"),
IncludeGates: q.boolean("include_gates"),
IncludeInfra: q.boolean("include_infra"),
IncludeEphemeral: q.boolean("include_ephemeral"),
CreatedBefore: q.timestamp("created_before"),
CreatedAfter: q.timestamp("created_after"),
MetadataFields: q.metadataFields("metadata_field"),
HasMetadataKey: q.str("has_metadata_key"),
Limit: q.limit(),
}
// THE ORDER AND THE CURSOR ARE ONE DECISION. Each served order is a keyset
// contract — its own position shape and its own strictly-after predicate —
// so `sort` selects the ORDER BY and, with it, what a position means. The
// vocabulary is closed for that reason and not for tidiness: the seven
// other orders `bd list --sort` takes have no proven total key (mutable,
// nullable, or not expressible in SQL at all), and serving one behind a
// cursor would page a walk that skips and repeats rows.
//
// SortBy takes the wire value verbatim, which is safe only because the two
// vocabularies coincide by construction: sqlbuild.SortDefs already spells
// these orders `created` and `priority`, and `priority` there is exactly
// (priority ASC, created_at DESC, id ASC) — `bd list`'s flagless order.
order := listOrder(q.oneOf("sort", string(listOrderDefault), listOrders...))
req.SortBy = string(order)
token := q.str("cursor")
if !s.acceptQuery(w, r, q) {
return
}
if token != "" {
// Decoded AGAINST the order this request asked for. A token minted in
// the other order is refused rather than reinterpreted: its instant and
// its id would decode perfectly and mean something else, which is a
// skipped-and-duplicated page served with a 200.
pos, ok := decodeCursor(token, order)
if !ok {
requestInfo(r.Context()).refuse(token)
s.fail(w, r, InvalidCursor())
return
}
req.AfterCreatedAt = &pos.CreatedAt
req.AfterID = pos.ID
req.AfterPriority = pos.Priority
}
if !s.allowUnlimited(w, r, req.Limit) {
return
}
rd, err := s.reader(r)
if err != nil {
s.failErr(w, r, err)
return
}
page, err := rd.List(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
body := apigen.IssuesPage{
Items: wireItems(page.Items),
HasMore: page.HasMore,
}
if page.HasMore {
// Present if and only if has_more, which the document states as a
// biconditional: a client that sees one and not the other has no way
// to know whether paging is finished.
// Minted in the order this page was SERVED in, so the token a client
// hands back is a position the next request can only be read against
// the same way.
if next := cursorFor(page.Items, order); next != "" {
body.NextCursor = &next
}
}
writeJSON(w, body)
}
// handleQueryIssues answers GET /v0/beads/issues:query.
//
// The EXPRESSION IS NOT PARSED HERE. Parsing, evaluation, the predicate
// decision and the scan bound all live inside the role, so this handler cannot
// make the truncating one: it reads five parameters and hands the sentence
// over.
func (s *Server) handleQueryIssues(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
req := issueops.QueryRequest{
Expression: q.str("q"),
IncludeClosed: q.boolean("all"),
SortBy: q.oneOf("sort", "", querySorts...),
Reverse: q.boolean("reverse"),
Limit: q.limit(),
// No Offset. The document publishes no parameter for one, because the
// two database sources this server can be built on disagree about
// whether they can honor it — see issueops.QueryRequest.Offset.
}
if !s.acceptQuery(w, r, q) {
return
}
if !s.allowUnlimited(w, r, req.Limit) {
return
}
qr, err := s.querier(r)
if err != nil {
s.failErr(w, r, err)
return
}
page, err := qr.Query(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
writeJSON(w, apigen.QueryPage{
Items: wireItems(page.Items),
HasMore: page.HasMore,
})
}
// querySorts is the display-order vocabulary this operation publishes, in the
// document's order. It is the set workapi.CompareIssuesBy can order by; a value
// outside it is refused here rather than accepted and ignored, because a page
// returned unordered under a sort the caller named is indistinguishable from
// one whose order the caller does not understand.
var querySorts = []string{"priority", "created", "updated", "closed", "status", "id", "title", "type", "assignee"}
// handleGetIssue answers GET /v0/beads/issues/{id}.
func (s *Server) handleGetIssue(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
// Both default off, so a request that names neither builds the request this
// handler built when the operation had no parameters at all.
req := issueops.GetRequest{
IncludeComments: q.boolean("include_comments"),
IncludeDependents: q.boolean("include_dependents"),
BriefDeps: q.boolean("brief_deps"),
}
// Before the id bound, which is the order this operation had when
// requireNoQuery ran first: a refused query string is a 400 that names what
// to fix, and deciding the id first would answer it with a 404 instead.
if !s.acceptQuery(w, r, q) {
return
}
id := r.PathValue("id")
// The id is bounded HERE, before the request buys a concurrency slot and a
// database round trip, exactly as the claim route bounds its own. The
// column is VARCHAR(255) and the document calls this an exact canonical
// id, so a longer one — or one carrying a control character, which a
// percent-escape in the path decodes to — names no row that can exist.
// The refusal is the SAME 404 a real miss gets: a distinct answer would
// let a caller map this server's notion of a well-formed id, and there is
// nothing to learn from it.
if id == "" || types.CheckFieldLen("id", id) != nil || strings.ContainsFunc(id, isControlChar) {
s.fail(w, r, NotFound())
return
}
req.ID = id
rd, err := s.reader(r)
if err != nil {
s.failErr(w, r, err)
return
}
details, err := rd.Get(r.Context(), req)
if err != nil {
s.failReadErr(w, r, err)
return
}
writeJSON(w, *details)
}
// acceptQuery answers a refused query string and reports whether the request
// may proceed.
func (s *Server) acceptQuery(w http.ResponseWriter, r *http.Request, q *query) bool {
res := q.result()
if res == nil {
return true
}
requestInfo(r.Context()).refuse(res.offender())
s.fail(w, r, *res)
return false
}
// allowUnlimited enforces the one mode-dependent refusal on this surface: an
// unlimited read buffers the whole active set and its JSON encoding inside one
// shared process, which must not be reachable by arbitrary network peers.
//
// The bind mode is deliberately NOT advertised in ContextResponse. A client
// that wants an unlimited read asks for one and, on this 400, re-issues with
// an explicit limit; it is a client-side fix, never a retry.
func (s *Server) allowUnlimited(w http.ResponseWriter, r *http.Request, limit *int) bool {
if !s.cfg.AllowNonLoopback || limit == nil || *limit != 0 {
return true
}
requestInfo(r.Context()).refuse("0")
s.fail(w, r, InvalidArgument("limit", ReasonInvalidValue,
"unlimited reads are loopback-only; pass an explicit limit"))
return false
}
// failReadErr answers a failed read. It exists so that a filter-construction
// refusal — an unknown status, an issue type outside the workspace vocabulary,
// an invalid metadata key — reaches the client as the 400 it is rather than as
// a 500, while every storage failure keeps going through the one mapping in
// problem.go.
//
// The builders are the authority on what those messages say (the CLI prints
// them verbatim), so the detail is the builder's own text: it reflects the
// caller's own input back, which is what a 4xx detail is for.
func (s *Server) failReadErr(w http.ResponseWriter, r *http.Request, err error) {
if param, ok := invalidFilterParam(err); ok {
requestInfo(r.Context()).refuse(param)
s.fail(w, r, InvalidArgument(param, ReasonInvalidValue, err.Error()))
return
}
s.failErr(w, r, err)
}
// invalidFilterParam maps a filter-construction failure back to the query
// parameter that caused it.
//
// It matches on the builder's message prefixes, and that is a deliberate,
// bounded exception to this package's "never classify by prose" rule: these
// are THIS repository's own error strings, not a foreign library's. The
// alternative — typed errors for each — is the right end state and is a change
// to internal/workapi, not to the wire. A message that stops matching degrades
// to a 500, which is loud, rather than to a wrong 400.
//
// Every row here is driven end to end by a case in
// TestABuilderRefusalIsTheDocumentedBadRequest, so a reworded builder message
// fails a test rather than silently demoting its parameter to a 500. That
// test IS the pin: the builders' golden files record successful filters only,
// and cannot see a message at all.
func invalidFilterParam(err error) (string, bool) {
msg := err.Error()
switch {
case strings.HasPrefix(msg, "invalid status "):
return "status", true
// The count role's own refusals (S8 review fix): a misspelled
// --exclude-status entry, and --parent set together with --no-parent.
// Both are the ROLE's ErrValidation. They are named here the same way as
// the `status` row above and the metadata-key rows below, so the client
// learns which parameter to fix rather than reading an unclassified 500.
case strings.HasPrefix(msg, "invalid exclude-status "):
return "exclude_status", true
case strings.HasPrefix(msg, "--parent and --no-parent are mutually exclusive"):
return "no_parent", true
case strings.HasPrefix(msg, "invalid issue type "):
return "type", true
case strings.HasPrefix(msg, "invalid sort policy "):
return "sort", true
case strings.HasPrefix(msg, "invalid metadata field key"):
return "metadata_field", true
case strings.HasPrefix(msg, "invalid metadata key filter"):
return "has_metadata_key", true
// The query role's refusal. It is the caller's SENTENCE being wrong, which
// is a 400 on `q` rather than the 500 an unclassified error would give.
case strings.HasPrefix(msg, "invalid query expression"):
return "q", true
}
return "", false
}
// wireItems projects the reader's page onto the generated envelope's element
// type.
//
// The element type is an ALIAS of types.IssueWithCounts — the same struct the
// CLI's --json marshals — so this copies a header and shares everything under
// it. There is no second wire struct here and there must never be one: that is
// what keeps `bd list --json` and this body one compatibility domain.
func wireItems(items []*types.IssueWithCounts) []apigen.IssueWithCounts {
out := make([]apigen.IssueWithCounts, 0, len(items))
for _, item := range items {
if item == nil {
continue
}
out = append(out, *item)
}
return out
}