beads/internal/httpclient/wire/problem.go
Julian Knutsen 6d7fecaa3e
feat(httpclient): OSS HTTP client wire/encode layers (contributed from bd-enterprise under MIT) (#7210)
* 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>
2026-10-05 02:58:34 -07:00

838 lines
39 KiB
Go

// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/problem.go@49d1df2f6)
// to OSS beads under the MIT license.
package wire
import (
"encoding/json"
"errors"
"fmt"
"net/http"
"slices"
"strconv"
"strings"
"time"
"unicode"
"github.com/steveyegge/beads/internal/httpapi/apigen"
"github.com/steveyegge/beads/issueops"
)
// The refusals with no analog in the local store's vocabulary, because each is
// a statement about a SERVER rather than about the workspace. Everything else
// in the code table maps to the canonical issueops sentinel the embedded store
// would have returned for the same refusal, so a caller classifies a remote
// refusal with the errors.Is arm it already has.
var (
// ErrInvalidCursor is a cursor this server did not issue, cannot decode, or
// issued under a different internal version. The recovery is to restart
// paging without it, which is why it is not folded into ErrValidation: a
// stale cursor is a normal client situation, not a client bug.
ErrInvalidCursor = errors.New("cursor is not valid for this server; restart paging")
// ErrUnauthenticated is a missing, malformed or unrecognized credential on
// a server that was configured with one. It never carries the credential or
// any hint of which of the three it was — the server refuses to say, and
// repeating a guess here would undo that.
ErrUnauthenticated = errors.New("bd serve refused the credential")
// ErrBusy is retryable contention: the server's transaction retry budget was
// exhausted, or its in-flight limit was saturated.
ErrBusy = errors.New("bd serve is busy")
// ErrDBUnavailable is a retryable failure to reach the served database.
ErrDBUnavailable = errors.New("bd serve cannot reach its database")
// ErrServerFault is an unexpected server-side failure. Its detail is a fixed
// string by design, so ProblemError.RequestID is the only handle on the log
// line that has the real error.
ErrServerFault = errors.New("bd serve failed")
// ErrBadRequest is the 4xx default branch: a code this client does not know,
// on a status class that says the request was wrong. Failing loud is the
// documented posture — an unknown 4xx is a client bug, and retrying or
// degrading past one hides it.
ErrBadRequest = errors.New("bd serve refused the request")
// The journal codes. This client dials no journal operation — httpstore
// carries no EventsJournal accessor, so nothing here can produce a request
// that earns one of these — and they are on the code table anyway, because
// the vocabulary gate is set-equality with the document rather than with
// what this client happens to reach today. A code the document publishes
// and this table omitted would take the 4xx default branch and be reported
// as a client bug on the day the journal accessor lands.
// ErrEventsJournalDisabled is the served workspace having its journal OFF.
// The recovery is entirely the operator's — set `events-journal true` and
// restart the server — so it is not folded into ErrValidation, which would
// send a caller looking at its own request.
ErrEventsJournalDisabled = errors.New("bd serve: the events journal is not enabled on the served workspace")
// ErrEventsWatchSaturated is the server already holding as many open
// journal streams as it will. It is NOT ErrBusy despite the shared 503:
// busy says the database is congested and the same request will work
// shortly, this says a bounded resource is fully subscribed by connections
// that may last hours, and the caller has a recovery busy does not offer —
// the paged read, which holds nothing between requests.
ErrEventsWatchSaturated = errors.New("bd serve: no journal stream slots are free")
// ErrPreconditionFailed is a compare-and-set guard that missed on an
// operation whose contract is that a miss refuses everything. It is the
// fallback for the shape the server did not name: when `param` says which
// guard missed, the table answers with the issueops sentinel the embedded
// store would have returned for the same miss.
ErrPreconditionFailed = errors.New("bd serve: a precondition on the request did not hold")
// ErrEventsJournalTruncated is a journal read whose checkpoint has fallen
// below the retained window. ProblemError carries the window itself
// (Since/Floor/Head), because the recovery is a decision the consumer makes
// from those three numbers rather than from this sentence.
ErrEventsJournalTruncated = errors.New("bd serve: the journal checkpoint is below the retained window")
// ErrUnknownItemCode is the PER-ITEM analog of the 4xx default branch above:
// a BatchCloseItemError.code this client does not recognize. Per-item codes
// grow additively exactly as Problem.code does — the schema tells clients to
// default-branch on an unknown one — so an unfamiliar code must not hard-fail
// the whole batch. It lands as a TYPED per-item outcome instead, so a caller
// tells "this item was refused for a reason my client is too old to name"
// from a success rather than reading it as one.
ErrUnknownItemCode = errors.New("bd serve refused a batch-close item with a code this client does not recognize")
)
// UnknownItemCodeError is the typed carrier for that per-item refusal. It keeps
// the code verbatim and the server's optional detail so a renderer can show what
// it could not classify, and unwraps to ErrUnknownItemCode so errors.Is reaches
// it. Both strings are server-controlled, so the layer that builds one strips
// their control runes the way mapProblem strips every other wire field.
type UnknownItemCodeError struct {
IssueID string
Code string
Detail string
}
func (e *UnknownItemCodeError) Error() string {
if e.Detail != "" {
return fmt.Sprintf("issue %s: bd serve refused it with an unrecognized batch-close code %q: %s", e.IssueID, e.Code, e.Detail)
}
return fmt.Sprintf("issue %s: bd serve refused it with an unrecognized batch-close code %q", e.IssueID, e.Code)
}
func (e *UnknownItemCodeError) Unwrap() error { return ErrUnknownItemCode }
// ProblemError is a non-2xx answer from bd serve, decoded from its RFC 9457
// problem+json body.
//
// It carries the whole envelope because the layers above reconstruct typed
// refusals and user-facing text from it: `code` is the dispatch key, `param`
// and `reason` turn a 400 back into the flag that produced it, `request_id` is
// what makes a 5xx actionable, and the extension members are the typed
// discriminators the server reads inside the refusing transaction.
//
// The extension members are POINTERS because presence is load-bearing on three
// of them: `open_children` separates the two not_closable refusals, `issue_id`
// separates a hierarchy conflict from a plain scheduling cycle, and
// `blocker_is_ancestor` is emitted in both polarities and so cannot use absence
// to mean false.
type ProblemError struct {
// Op is the operation id that was dialed, and ServerURL the base URL it was
// dialed against. Neither comes off the wire; both are what the refusal
// taxonomy needs to name the server in its text.
Op string
ServerURL string
Status int
Code string
Title string
Detail string
Param string
Reason string
RequestID string
// CredentialSource names the ladder rung whose credential the server refused,
// set only on a 401 and only when the provider can report it (design D7). It
// is a provenance label — an env var name, a command's env var, or the
// credentials file [host:port] — never the credential itself, so it is safe
// in error text bound for logs and terminals.
CredentialSource string
// RetryAfter is the server's Retry-After header, already bounded (see
// Options.MaxRetryAfter). Zero when the header was absent, unparseable or
// in the past.
RetryAfter time.Duration
Assignee *string
IssueStatus *string
OpenChildren *int
ExistingType *string
RequestedType *string
IssueID *string
BlockerID *string
BlockerIsAncestor *bool
// The compare-and-set guard's two sides, with `precondition_failed`. `param`
// says WHICH guard missed and these say what the request asked for and what
// the row was found holding, split BY TYPE rather than carried as one
// polymorphic pair — a member that is "a version or a status or an
// assignee" is a schema alternation, and this document spells three typed
// pairs instead.
//
// They are pointers for the reason every pointer here is one: PRESENCE is
// load-bearing on all six. An `expected_*` echoes the request, so its
// absence means the operation carried no such guard — and 0 and "" are both
// real guards, so neither zero value can stand in for absence. An `actual_*`
// is present only where the refusing operation can REPORT what it found: an
// all-or-nothing operation rolls its transaction back, and a value read
// after the fact would describe a row the refusal never saw, so absence
// there means "this server cannot tell you", never "it found zero".
//
// THE VERSIONS ARE CARRIED AS THE STRINGS THE WIRE SPELLS THEM IN. Since
// upstream #6053 every revision token on the surface is a decimal string
// (types.RevisionToken), never a JSON number, so nothing on this path can
// round one. They are deliberately NOT parsed back to int64 here: the token
// is opaque and equality-only, `expected_version` is the ECHO of what the
// request sent (a caller comparing it to its own guard compares
// types.RevisionToken(guard) to it), and `actual_version` is a diagnostic —
// the contract says to compose the next guard from a `revision` a WRITE
// answered with, never from a refusal. Parsing on the refusal path could
// only turn a well-formed 409 into a decode failure or drop a member whose
// presence is load-bearing, and nothing in this package reads them
// numerically. They are stripped like every other server-controlled string.
ExpectedVersion *string
ActualVersion *string
ExpectedStatus *string
ActualStatus *string
ExpectedAssignee *string
ActualAssignee *string
// The batch-item members, on a refusal from an operation whose items are
// HETEROGENEOUS and may be named — issues:batchApply is the whole
// population. They are the only place the offender exists: that operation
// is all or nothing, so a refusal carries no per-item result array for a
// client to find it in, and the server reads these off the role's own typed
// *issueops.ItemError inside the transaction that refused.
//
// PRESENCE IS LOAD-BEARING ON ALL OF THEM, which is why the index is a
// pointer and not an int: 0 is the FIRST ITEM and a real answer, so a bare
// int could not tell it from a refusal that named no item at all. Key and
// IssueID are absent for real states rather than gaps — not every item
// carries a key, and a create whose id was never minted has none to report.
//
// ItemIssueID is deliberately NOT ProblemError.IssueID, and the divergence
// is the server's rather than a spelling choice here: IssueID's PRESENCE
// discriminates the dependency_cycle hierarchy refusal from the plain
// scheduling one, so a batch reusing it would fire that discriminator on
// refusals it says nothing about.
ItemIndex *int
ItemKind *string
ItemKey *string
ItemIssueID *string
// DeclaredLater tells the two unresolvable-key diagnoses apart: true is an
// ORDERING mistake — the key IS declared, by a later item, and a key
// reaches backward only — and false is a key nothing in the request
// declares, which is a typo or a missing item. It is emitted in BOTH
// polarities, so it is a pointer for the reason BlockerIsAncestor is one:
// absence has to mean "this refusal was not about a key", never false.
DeclaredLater *bool
// The journal-truncation window, with `events_journal_truncated`: the
// checkpoint the window begins after, the lowest seq still retained, and the
// highest seq ever assigned.
//
// They are carried rather than folded into the sentinel because that
// sentinel is storage.EventsJournalTruncatedError, and this package
// deliberately imports no storage — the whole point of respelling the
// operation ids here is that a process talking to a bd serve does not link
// the engine. A consumer with a journal accessor rebuilds the typed error
// from these three; without them the recovery (resume from floor-1 and
// accept the gap, or re-baseline) would have to be parsed out of prose.
Since *int64
Floor *int64
Head *int64
// Err is the canonical sentinel this code maps to. It is what Unwrap
// returns, so errors.Is and errors.As reach it.
Err error
}
func (e *ProblemError) Error() string {
var b strings.Builder
fmt.Fprintf(&b, "%s: bd serve at %s answered %d", e.Op, e.ServerURL, e.Status)
if e.Code != "" {
fmt.Fprintf(&b, " %s", e.Code)
}
if e.Detail != "" {
fmt.Fprintf(&b, ": %s", e.Detail)
}
// The 5xx detail is a fixed string per code and says nothing about the
// underlying failure, so the correlation id is the client's only handle on
// the one server log line that has it.
if e.Status >= 500 && e.RequestID != "" {
fmt.Fprintf(&b, " (request_id %s)", e.RequestID)
}
// Naming the rung the refused credential came from is what turns "the server
// said 401" into something the operator can act on: it says WHICH source to
// rotate or fix (design D7). The server never says which of missing,
// malformed or unrecognized it was, and this does not guess — it reports only
// the client-side provenance of the credential it presented.
if e.Status == http.StatusUnauthorized && e.CredentialSource != "" {
fmt.Fprintf(&b, " (credential from %s)", e.CredentialSource)
}
return b.String()
}
func (e *ProblemError) Unwrap() error { return e.Err }
// Retryable reports whether the server said to come back. Only the 503 class
// says so: an unknown 4xx is a client bug and every other 5xx is a fault the
// same request will earn again.
func (e *ProblemError) Retryable() bool {
return e.Status == http.StatusServiceUnavailable ||
errors.Is(e.Err, ErrBusy) || errors.Is(e.Err, ErrDBUnavailable)
}
// ReasonProjectMismatch is the Problem `reason` the server sets on a refusal of
// a Bd-Project-Id stamp for the wrong workspace, spelled exactly as the server's
// httpapi.ReasonProjectMismatch (held to it by
// TestProjectMismatchReasonMatchesTheServerConstant). It is the discriminator
// mapProblem reads to build the typed *ProjectMismatchError, ahead of the code
// table: the code is the generic invalid_argument, so reason is the only thing
// that tells this wrong-server refusal from a malformed-argument one.
const ReasonProjectMismatch = "project_mismatch"
// ReasonWireRevisionUnsupported is the Problem `reason` the server sets when
// this client's declared Bd-Wire-Revision header named a revision below the
// server's own min_client_wire_revision, spelled exactly as the server's
// httpapi.ReasonWireRevisionUnsupported (held to it by
// TestTheProjectIdentityVocabularyMatchesTheServer). Like ReasonProjectMismatch
// it rides the generic invalid_argument code, so reason is the only thing that
// tells this refusal apart from an ordinary malformed argument.
const ReasonWireRevisionUnsupported = "wire_revision_unsupported"
// ErrWireRevisionUnsupported reports that bd serve refused this client's
// declared Bd-Wire-Revision header as older than the revision it now
// requires. See WireRevisionUnsupportedError.
var ErrWireRevisionUnsupported = errors.New("bd serve requires a newer client wire revision than this client declared")
// WireRevisionUnsupportedError is the per-request mirror of the handshake's
// own gate (wire.WireRevisionSkewError, handshake.go): the server has read
// this client's declared Bd-Wire-Revision header (wire.ClientWireRevision,
// stamped on every request by Client.stampRequest) and refused it as below
// the floor it enforces now. Unlike WireRevisionSkewError — raised locally,
// from a 200 ContextResponse, when THIS client decides the SERVER's wire
// shape is one it cannot speak — this one is the SERVER's own refusal, and it
// can arrive on any request, including the context fetch the handshake
// itself makes (ContextResponse.MinClientWireRevision's doc: "raised ... on
// GET /v0/beads/context too"), in which case it surfaces through
// Client.Handshake exactly the way any other *ProblemError from GetContext
// does — no separate handling is needed there.
type WireRevisionUnsupportedError struct {
ServerURL string
BdVersion string
// ClientWireRevision is this build's own declared revision, which is what
// was refused.
ClientWireRevision int
// MinClientWireRevision is the server's own floor, from the refusal's
// min_wire_revision extension member.
MinClientWireRevision int
// ServerWireRevision is the server's own current wire_revision, from the
// refusal's wire_revision extension member.
ServerWireRevision int
}
func (e *WireRevisionUnsupportedError) Error() string {
return fmt.Sprintf("bd serve at %s (bd_version %s) requires a client wire revision of at least %d; this client declared %d",
e.ServerURL, e.BdVersion, e.MinClientWireRevision, e.ClientWireRevision)
}
func (e *WireRevisionUnsupportedError) Unwrap() error { return ErrWireRevisionUnsupported }
// target names the ids the wire's conflict members leave out. The server does
// not echo the issue a claim refused or the edge a dependency_exists collided
// with — the request already said — so the caller supplies them and the
// reconstructed sentinel comes out whole.
type target struct {
op string
serverURL string
issueID string
dependsOnID string
// expectID is the workspace's own pinned project id (Client.expectID), which
// the wire never carries — it is a client-side fact. A project_mismatch
// refusal names the server's own id in server_project_id; pairing it with this
// expected id is what lets the typed *ProjectMismatchError say BOTH sides of
// the disagreement without the client parsing the refusal's prose.
expectID string
}
// mapProblem decodes an RFC 9457 body and maps it onto the canonical sentinel
// for its code.
//
// `code` is the ONLY dispatch key, per the document: a code carries one frozen
// status, so reading the status instead would be a second, weaker copy of the
// same table. The status is consulted for exactly one thing — the default
// branch for a code this client has never heard of, which is how the vocabulary
// stays additive.
func mapProblem(t target, status int, header http.Header, body []byte, maxRetryAfter time.Duration) *ProblemError {
var p apigen.Problem
// A non-2xx that is not problem+json at all is a real case: a proxy, a load
// balancer or a stray server on the port answers with HTML. It falls through
// to the status-class default branch with an empty code, which is exactly
// what an unrecognized code does.
_ = json.Unmarshal(body, &p)
// Every string that comes off the wire here is server-controlled and ends up
// in an error rendered to a terminal or a log line — often through a %v sink
// that never touches the CLI's output-boundary strip (bd close/show/reopen/
// update write each per-id failure straight to os.Stderr). So the control
// runes are removed HERE, the moment the bytes become a typed error, and both
// the direct fields AND the extension members the typed conflicts are
// reconstructed from below (sentinelFor) are cleaned — an issue id echoed by a
// dependency-cycle conflict is as server-controlled as the detail string. The
// pointer members keep their presence, which is load-bearing discrimination on
// three of them. Tab and newline are stripped too (unlike the display-layer
// strip): a problem field is a single value with no legitimate framing.
e := &ProblemError{
Op: t.op,
ServerURL: t.serverURL,
Status: status,
Code: stripControlRunes(p.Code),
Title: stripControlRunes(p.Title),
Detail: stripControlRunes(deref(p.Detail)),
Param: stripControlRunes(deref(p.Param)),
Reason: stripControlRunes(deref(p.Reason)),
RequestID: stripControlRunes(p.RequestId),
RetryAfter: retryAfter(header, maxRetryAfter),
Assignee: stripControlRunesPtr(p.Assignee),
IssueStatus: stripControlRunesPtr(p.IssueStatus),
OpenChildren: p.OpenChildren,
ExistingType: stripControlRunesPtr(p.ExistingType),
RequestedType: stripControlRunesPtr(p.RequestedType),
IssueID: stripControlRunesPtr(p.IssueId),
BlockerID: stripControlRunesPtr(p.BlockerId),
BlockerIsAncestor: p.BlockerIsAncestor,
Since: p.Since,
Floor: p.Floor,
Head: p.Head,
// The guard pair. All six are strings on the wire — the two versions
// are decimal revision tokens (types.RevisionToken) and are carried as
// the strings the server spelled, see the field comment — and all six
// are stripped like every other server-controlled field, keeping their
// PRESENCE, which is the state that discriminates.
ExpectedVersion: stripControlRunesPtr(p.ExpectedVersion),
ActualVersion: stripControlRunesPtr(p.ActualVersion),
ExpectedStatus: stripControlRunesPtr(p.ExpectedStatus),
ActualStatus: stripControlRunesPtr(p.ActualStatus),
ExpectedAssignee: stripControlRunesPtr(p.ExpectedAssignee),
ActualAssignee: stripControlRunesPtr(p.ActualAssignee),
// The batch-item members. The three strings are stripped like every
// other server-controlled field and keep their presence; the index and
// the ordering discriminator travel as the generated pointers, which is
// what keeps a zero index and a false polarity apart from absence.
ItemIndex: p.ItemIndex,
ItemKind: stripControlRunesPtr(p.ItemKind),
ItemKey: stripControlRunesPtr(p.ItemKey),
ItemIssueID: stripControlRunesPtr(p.ItemIssueId),
DeclaredLater: p.DeclaredLater,
}
legacyRevisionFields(body, e)
// The wrong-server arm, discriminated on REASON and taken BEFORE the code
// table. A project_mismatch is spelled invalid_argument on the wire, so the
// code table would map it to ErrValidation and lose the whole signal; the
// reason is what tells it apart. It is the one refusal that carries
// server_project_id — the id the server actually serves — which is stripped
// here at the decode boundary like every other server-controlled field and is
// deliberately NOT a generic ProblemError member: it exists only to build this
// typed error, paired with the workspace's own expected id, and unwraps
// ErrProjectMismatch so cmd/bd renders one recovery block for both this
// per-request path and the handshake identity gate. Database and RepoRoot are
// left empty: this refusal discloses only the server's id, not its location.
if e.Reason == ReasonProjectMismatch {
e.Err = &ProjectMismatchError{
ServerURL: t.serverURL,
Expected: t.expectID,
Got: stripControlRunes(deref(p.ServerProjectId)),
}
return e
}
// The other document-level arm, discriminated the same way and for the
// same reason: wire_revision_unsupported rides the generic
// invalid_argument code too, so reason is what tells it apart. The three
// extension members it alone carries are read straight off the problem —
// stripped like every other server-controlled field — rather than folded
// into the generic ProblemError, because this refusal is a statement about
// the SERVER's wire shape, not about the request's arguments.
if e.Reason == ReasonWireRevisionUnsupported {
e.Err = &WireRevisionUnsupportedError{
ServerURL: t.serverURL,
BdVersion: stripControlRunes(deref(p.BdVersion)),
ClientWireRevision: ClientWireRevision,
MinClientWireRevision: deref(p.MinWireRevision),
ServerWireRevision: deref(p.WireRevision),
}
return e
}
e.Err = sentinelFor(e, t)
return e
}
// decodeRevisionToken reads a revision-bearing problem member that may be
// encoded either as the decimal string every server since upstream #6053
// uses (types.RevisionToken) or as the bare JSON integer a server old enough
// to omit ContextResponse.wire_revision entirely still sends (see
// ClientMinWireRevision's doc: a decoded 0 means the server omitted the
// member, and 0 is exactly the pre-#6053 integer-token generation). Both
// shapes name the same opaque token — this client never parses either one
// back to int64 (ProblemError.ExpectedVersion's doc) — so tolerating the
// older shape here is only about surviving the decode, never about deriving a
// number from it.
func decodeRevisionToken(raw json.RawMessage) (string, bool) {
if len(raw) == 0 || string(raw) == "null" {
return "", false
}
var s string
if err := json.Unmarshal(raw, &s); err == nil {
return s, true
}
var n json.Number
if err := json.Unmarshal(raw, &n); err == nil {
return n.String(), true
}
return "", false
}
// revisionNeedsFallback reports whether a *string revision field still needs
// legacyRevisionFields' integer-tolerant recovery. A genuinely absent member
// decodes to nil, as expected — but encoding/json's indirect() allocates a
// pointer to the zero value ("") for a *string field BEFORE it discovers the
// JSON value's type doesn't match, when the member IS present with the wrong
// shape (a bare integer). That pre-allocation means a type-mismatched field
// comes out of the primary json.Unmarshal(body, &p) as a non-nil pointer to
// "", not nil — so checking only for nil here would never recover exactly the
// one case this fallback exists for. No legitimate server response uses a
// literal empty-string revision token (ProblemError.ExpectedVersion's doc:
// both are opaque, server-defined, non-numeric tokens an operation always
// names when it fires at all), so treating "" the same as nil costs nothing.
func revisionNeedsFallback(p *string) bool {
return p == nil || *p == ""
}
// legacyRevisionFields backfills expected_version/actual_version when the
// primary decode above left them needing fallback (see revisionNeedsFallback).
// That happens exactly when a pre-#6053 server sent one as a bare JSON
// integer rather than the decimal string every server since has used:
// json.Unmarshal(body, &p) already tolerates the mismatch (a bad field does
// not abort decoding the rest, and mapProblem deliberately discards that
// error), so the only member actually lost is the one with the wrong shape —
// and that is exactly what this recovers, from the same bytes, by parsing the
// two revision keys alone and accepting either shape.
func legacyRevisionFields(body []byte, e *ProblemError) {
if !revisionNeedsFallback(e.ExpectedVersion) && !revisionNeedsFallback(e.ActualVersion) {
return
}
var raw struct {
ExpectedVersion json.RawMessage `json:"expected_version"`
ActualVersion json.RawMessage `json:"actual_version"`
}
if json.Unmarshal(body, &raw) != nil {
return
}
if revisionNeedsFallback(e.ExpectedVersion) {
if v, ok := decodeRevisionToken(raw.ExpectedVersion); ok {
v = stripControlRunes(v)
e.ExpectedVersion = &v
}
}
if revisionNeedsFallback(e.ActualVersion) {
if v, ok := decodeRevisionToken(raw.ActualVersion); ok {
v = stripControlRunes(v)
e.ActualVersion = &v
}
}
}
// codeSentinel is the whole problem-code vocabulary this client knows, and the
// canonical error each code becomes.
//
// It is a table rather than a switch so the vocabulary is ENUMERABLE:
// TestTheCodeTableIsSetEqualWithTheDocumentedVocabulary walks it against the
// `x-bd-codes` rows of the shipped OpenAPI document, in both directions, which
// a switch statement could not be held to.
var codeSentinel = map[string]func(*ProblemError, target) error{
"invalid_argument": func(*ProblemError, target) error { return issueops.ErrValidation },
"invalid_cursor": func(*ProblemError, target) error { return ErrInvalidCursor },
"unauthenticated": func(*ProblemError, target) error { return ErrUnauthenticated },
"not_found": func(*ProblemError, target) error { return issueops.ErrNotFound },
"already_exists": func(*ProblemError, target) error { return issueops.ErrAlreadyExists },
"busy": func(*ProblemError, target) error { return ErrBusy },
"db_unavailable": func(*ProblemError, target) error { return ErrDBUnavailable },
"internal": func(*ProblemError, target) error { return ErrServerFault },
// The journal codes, on the table for the reason stated beside their
// sentinels: set-equality with the document, not with what this client
// reaches today.
"events_journal_disabled": func(*ProblemError, target) error { return ErrEventsJournalDisabled },
"events_journal_truncated": func(*ProblemError, target) error { return ErrEventsJournalTruncated },
"events_watch_saturated": func(*ProblemError, target) error { return ErrEventsWatchSaturated },
// `param` names WHICH guard missed, in the same spelling a 400 on the same
// operation would use, so the client answers with the issueops sentinel the
// embedded store returns for that miss and a caller classifies both
// backends with one errors.Is arm. An unrecognized (or absent) param takes
// the generic sentinel rather than guessing one of the three.
//
// The MEMBER is read off the end of the param rather than compared whole,
// because a batch operation qualifies it by the item that carried the
// guard: `items[1].update.expected_version` is the same member as
// `expected_version` and means the same miss. A whole-string comparison
// answered the generic sentinel for every guarded item in a plan, which is
// a caller told "a precondition failed" where a local backend tells it
// WHICH — see paramMember.
"precondition_failed": func(e *ProblemError, _ target) error {
switch paramMember(e.Param) {
case "expected_version":
return issueops.ErrVersionMismatch
case "expected_status":
return issueops.ErrStatusMismatch
case "expected_assignee":
return issueops.ErrAssigneeMismatch
default:
return ErrPreconditionFailed
}
},
"already_claimed": func(e *ProblemError, t target) error {
return claimConflict(e, t, issueops.ErrAlreadyClaimed)
},
"not_claimable": func(e *ProblemError, t target) error {
return claimConflict(e, t, issueops.ErrNotClaimable)
},
// Member PRESENCE is the discriminator the server documents: the
// open-children refusal carries the count, the live-blocker one carries
// nothing. Reading `detail` to tell them apart is exactly what the extension
// member exists to prevent.
"not_closable": func(e *ProblemError, t target) error {
if e.OpenChildren != nil {
return &issueops.CloseOpenChildrenError{IssueID: refusedIssueID(e, t), OpenChildren: *e.OpenChildren}
}
return issueops.ErrCloseBlocked
},
// not_releasable is the RELEASE's refusal, and it is REACHED: httpReleaser
// dials issues:release (releaser.go, client wave ga-f352s) and nine of the
// eleven Releaser contracts run through this mapping on the served tier.
//
// It was on this table BEFORE it was reachable, for the journal codes'
// reason — set-equality with the document rather than with what this client
// happens to dial — and that is worth keeping now that the wait is over: a
// code the document publishes and this table omitted would take the 4xx
// default branch and be reported as a client bug on the day an accessor
// started earning it.
//
// The role splits the refusal in two where the wire does not: ErrNotClaimed
// for a row holding no claim, ErrNotReleasable for a status that will not
// accept one. One code covers both by the server's own deliberate choice
// (see httpapi's CodeNotReleasable), and it carries no member that tells
// them apart, so this maps to the STATUS sentinel — the wider of the two,
// and the one whose message does not assert a fact the wire never sent.
"not_releasable": func(*ProblemError, target) error { return issueops.ErrNotReleasable },
// [Added: OSS publishes notes_overwrite_refused (internal/httpapi/problem.go
// CodeNotesOverwrite, status 409) for an update whose Patch.Notes would
// replace existing notes without an explicit overwrite flag. This code had
// no entry at all, so a server sending it fell through to the 4xx default
// and reported as an undifferentiated client bug instead of the typed
// sentinel callers already switch on locally.]
"notes_overwrite_refused": func(*ProblemError, target) error { return issueops.ErrNotesOverwrite },
// The same rule again: `issue_id` present means the edge named the issue's
// own ancestor or descendant, absent means a plain scheduling cycle. The
// three hierarchy members travel together and rebuild the typed error whole
// — including BlockerIsAncestor's false polarity, which is why the wire
// sends the boolean rather than omitting it.
"dependency_cycle": func(e *ProblemError, _ target) error {
if e.IssueID != nil {
return &issueops.DependencyHierarchyConflictError{
IssueID: *e.IssueID,
BlockerID: deref(e.BlockerID),
BlockerIsAncestor: deref(e.BlockerIsAncestor),
}
}
return issueops.ErrDependencyCycle
},
// The endpoints are not on the wire — the request already said them — so
// they come from the caller and the typed error comes out whole. A batch add
// that refused on one of many edges leaves them empty, because the wire does
// not say WHICH edge collided.
"dependency_exists": func(e *ProblemError, t target) error {
return &issueops.DependencyTypeConflictError{
IssueID: t.issueID,
DependsOnID: t.dependsOnID,
ExistingType: deref(e.ExistingType),
RequestedType: deref(e.RequestedType),
}
},
}
// Codes lists the problem codes this client maps, sorted. Anything outside it
// takes the status-class default branch.
func Codes() []string {
out := make([]string, 0, len(codeSentinel))
for code := range codeSentinel {
out = append(out, code)
}
slices.Sort(out)
return out
}
func sentinelFor(e *ProblemError, t target) error {
if row, ok := codeSentinel[e.Code]; ok {
return row(e, t)
}
// The default branch. Adding a code is not a breaking change, so a client
// that hard-failed on an unknown one would break on every server newer than
// itself; falling back to the status class is what makes the vocabulary
// additive.
switch {
case e.Status == http.StatusUnauthorized:
// A 401 is authentication whether or not the answer carried a problem
// document, and it must be classified BEFORE the 4xx default. bd serve's
// own 401 arrives with a code and never reaches here; what does is a 401
// from something in FRONT of it — a gateway or a proxy edge rejecting an
// expired credential before the request ever reaches bd — which answers
// with its own html or nothing at all. Falling through to ErrBadRequest
// told the caller its REQUEST was malformed, which sends an operator
// looking at flags for a credential to rotate.
return ErrUnauthenticated
case e.Status == http.StatusServiceUnavailable:
return ErrBusy
case e.Status >= 500:
return ErrServerFault
case e.Status >= 400:
return ErrBadRequest
default:
// A 1xx or 3xx reaching here is not a problem document at all. 3xx is
// refused before this point (redirects are not followed), so this is the
// unreachable arm — it fails as a server fault rather than as success.
return ErrServerFault
}
}
// claimConflict rebuilds *issueops.ClaimConflictError from the two extension
// members the refusing transaction read. The wrapped sentinel is what
// errors.Is matches, so a caller that only wants "someone else has it" needs no
// errors.As at all.
func claimConflict(e *ProblemError, t target, sentinel error) error {
return &issueops.ClaimConflictError{
IssueID: refusedIssueID(e, t),
Assignee: deref(e.Assignee),
Status: issueops.Status(deref(e.IssueStatus)),
Err: sentinel,
}
}
// refusedIssueID names the row a reconstructed conflict is about.
//
// The REQUEST is the first source and stays the first source: the conflict
// members the server leaves out are the ones the request already said, which is
// what target exists for. But a BATCH names as many rows as it has items, so
// there is no single request id to supply — and on that operation the server
// publishes the one it acted on as `item_issue_id`, read inside the refusing
// transaction. Without this fallback every conflict rebuilt from a plan named
// the empty string, which reads as "the server did not say" when the server
// said it plainly.
func refusedIssueID(e *ProblemError, t target) string {
if t.issueID != "" {
return t.issueID
}
return deref(e.ItemIssueID)
}
// paramMember reads the offending MEMBER off a problem's `param`.
//
// A single-resource operation spells it bare (`expected_version`); a batch
// qualifies it by the item that carried it (`items[1].update.expected_version`)
// so a client can find the offender in a request it composed. The member is the
// last dotted segment either way, and reading it is what lets one code table
// serve both spellings.
func paramMember(param string) string {
if i := strings.LastIndex(param, "."); i >= 0 {
return param[i+1:]
}
return param
}
// retryAfter reads the header RFC 9110 defines in two spellings and bounds it.
//
// The bound is not politeness: the header is server-controlled input, and an
// unbounded honor is a server (or anything that can answer as one) parking the
// caller's process for as long as it likes. A value past the bound is clamped
// rather than dropped, because the server still meant "not immediately".
//
// Honoring it means bounding it and handing it to the caller — this layer never
// sleeps and never resends. Half of this surface is non-idempotent custom-method
// POSTs (claim, close, sweep, delete, the dependency writes), and a transport
// that slept and resent one of those on a 503 would double-apply a write whose
// first attempt may well have committed before the server ran out of slots.
// Which 503s are safe to come back to is the dispatch layer's question, and it
// is the layer that knows the answer.
func retryAfter(header http.Header, max time.Duration) time.Duration {
raw := strings.TrimSpace(header.Get("Retry-After"))
if raw == "" {
return 0
}
var d time.Duration
if secs, err := strconv.Atoi(raw); err == nil {
d = time.Duration(secs) * time.Second
} else if at, err := http.ParseTime(raw); err == nil {
d = time.Until(at)
} else {
return 0
}
if d < 0 {
return 0
}
if max > 0 && d > max {
return max
}
return d
}
func deref[T any](p *T) T {
if p == nil {
var zero T
return zero
}
return *p
}
// stripControlRunes removes every control rune from a server-controlled problem
// field: category Cc — the C0 block, DEL and the C1 block, where ESC 0x1B and CSI
// 0x9B live — plus the U+2028/U+2029 line and paragraph separators. It mirrors the
// server's own actor rule (httpapi's isControlChar) and, unlike the CLI's
// display-layer strip, keeps nothing back: a problem field is a single value, so
// tab and newline in one are as much an injection as an escape introducer. This
// is the source-of-truth layer — it makes a decoded *ProblemError safe in EVERY
// field before it reaches any of the many stderr sinks that render it via %v.
func stripControlRunes(s string) string {
if !strings.ContainsFunc(s, isControlRune) {
return s
}
return strings.Map(func(r rune) rune {
if isControlRune(r) {
return -1
}
return r
}, s)
}
// stripControlRunesPtr strips a pointer member in place-safe fashion, preserving
// nil. Presence is load-bearing on three of the extension members (an explicit
// value versus an absent one discriminates two refusals), so a cleaned value is
// returned through a fresh pointer and an absent one stays absent.
func stripControlRunesPtr(p *string) *string {
if p == nil {
return nil
}
s := stripControlRunes(*p)
return &s
}
func isControlRune(r rune) bool {
return unicode.IsControl(r) || r == '\u2028' || r == '\u2029'
}