beads/internal/httpclient/wire/problem.go
Julian Knutsen 6d27a4f96e
fix(issueops): enforce the close guards on every close leg (#7425)
* fix(issueops): enforce the close guards on every close leg

The template read-only guard, the pin guard and the assignee authority
fence (be-035) lived only in cmd/bd (validateIssueClosable), so a close
through bd serve, issues:batchClose, a batch:apply close item or a library
caller of Lifecycle.Close / BatchCloser / BatchApplier closed what bd close
refused.

They now run inside the close's own transaction in CloseIssueCheckedInTx
(enforceCloseGuardsInTx), the body every checked close shares (dolt,
embedded, uow, and the server behind httpapi), for a target that is not
already closed:
- a template refuses with *issueops.TemplateReadOnlyError (no bypass);
- unless Force (CloseRequest, CloseBatchRequest, CloseItem) is set, a pinned
  issue refuses with *issueops.PinnedError and another actor's bead with
  *issueops.CloseNotAssigneeError (matches ErrNotOwner).

Wire: 409 template_read_only, issue_pinned and not_assignee (holder in
`assignee`, also on a batch-close outcome); the client rebuilds the typed
errors. The decision is one exported pure rule over the pre-image,
issueops.CheckClosable (internal/storage/issueops), which the in-tx guard
calls; bd close's direct and proxied preflights call it too, ahead of gate
satisfaction under the same already-closed skip, so bd close output, refusal
order and exit codes are unchanged (validateIssueClosable is gone). bd close
--if-revision now applies the guards too.

Conformance: RunLifecycleCloseEnforcesTheCloseGuards,
RunBatchCloserItemsAnswerToTheCloseGuards and
RunBatchApplyCloseItemsAnswerToTheCloseGuards on dolt, embedded, uow and
http, plus handler mapping tests, a CheckClosable table test, and a cmd/bd
test pinning that the guards outrank gate satisfaction.

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

* fix(httpclient): send force on the raw close; scope the close guards

Review fixes for #7425 (adopt-pr bd-0h0ao4, iterations 1 and 2).

The raw close keeps parity over http. httpclient.Store.CloseIssue maps the
off-role raw close onto the role's closeIssue op and sent force=false.
With the guards in the role, a pinned or claimed target then refused (409
issue_pinned / not_assignee) on http only: dolt, embedded and proxied run
the raw close as issueops.CloseIssueInTx, which applies neither the guards
nor close policy. The molecule auto-close, `bd gate resolve`,
`bd todo done` and `bd human dismiss` all make that call, and its
signature carries no force a caller could pass. It now sends force. Over
http that also stops applying close policy to the raw close, which it did
at base and no other backend does; parity is the point, so that goes too.
The template guard has no bypass on the wire, so a template still refuses
the raw close over http where the other backends close it; no raw caller
is known to close one. TestServedRawCloseKeepsParityWithTheOtherBackends
closes both pin spellings, a held bead and a parent with an open child
through Store.CloseIssue and requires the template refusal; with force
back to false it fails on 409 issue_pinned.

The close guards stay on the close verbs. A status update that crosses
into the done category (`bd update -s closed`, PATCH, a batchApply update
item) still answers to close policy only, so it closes a pinned issue or
another actor's bead on every backend, as it did before this PR. Guarding
it changes what the update legs admit and needs its own refusal mapping on
PATCH and batchApply, so it is left for a follow-up; the update.go and
domain/db comments now say the exclusion is deliberate.

CHANGELOG: the entry moves from Fixed to Changed as BREAKING, is scoped to
the close operations, names the two paths the guards do not cover, and
adds a Migration line (send force or reclaim; templates are never
closable). Docs: the OpBatchCloseIssues item codes, the CloseIssueChecked
and CloseIssueOptions.Force docs (storage, dolt, embeddeddolt), the
oracle-a scenario strings that named the retired validateIssueClosable,
and the TestCloseCheckOne_CloseGuardsOutrankGateSatisfaction doc, which
claimed a proxied route it does not drive.

Iteration 2: the wire contract says what force waives. The OpenAPI
`force` members of CloseIssueRequest, BatchCloseRequest and ApplyCloseItem
said force bypasses close policy "and nothing else"; it also waives the
pin and the assignee guard, and never the template guard. The batchClose
"only two answers" paragraph now says the same, and types.gen.go is
regenerated (`make api-gen`). "Close guards" names the close operations
instead of "every route to a close" and adds that a status update into
the done category is not one, and the PATCH done-crossing paragraph says
a patch is never refused `issue_pinned` or `not_assignee`. The conformance
comments that quoted the old Force sentence (batch_apply_contract.go,
batch_closer_contract.go, lifecycle_close_reopen_contract.go) quote the
current docs, and the batch_apply failure message no longer says Force
does nothing else. CHANGELOG: a `close` line of `bd batch` is named among
the raw closes, and "a template is never closable" becomes "the close
operations never close a template, forced or not". The storage interface
CloseIssue gains a doc that states its HTTP exception.

TestCloseGuardRefusalsPrintTheGuardSentenceOnEveryRoute pins the sentence
`bd close` prints for each guard (template, pin, assignee) through each
printer (closeDirectRefusal, closeDirectTypedRefusal, closeProxiedRefusal,
closeProxiedTypedRefusal), with the refusal bare, wrapped by the use case
and the SQL repository, or inside a served problem envelope. One pinned
refusal also goes through closeProxiedOutcomes and closeProxiedFailures,
where the stderr line and the `--json` error field must both be the
sentence. Six overlay mutants fail it: closeGuardRefusal recognizing no
guard, or not the pin, and each of the four printers skipping its call to
closeGuardRefusal.

Not done here: a CLI test that `--if-revision` exits 1 on a guard refusal,
not ExitGuardMismatch. External PR #7372 carries per-id fence tests for
that route (6 of 7 pass at this head); they are better absorbed with
credit than rewritten.

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 Opus 5.5 <noreply@anthropic.com>
2026-10-09 18:30:42 +00:00

856 lines
40 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
// actor is the request's acting identity (Request.Actor), which the
// not_assignee refusal names and the wire does not repeat.
actor 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 close guards (the first, template read-only, is every update's guard
// too), rebuilt whole so a caller reads the same typed error — and the same
// message — the embedded store returns. The row comes from the request or,
// on a batch, from `item_issue_id`; the holder from `assignee`; the closing
// actor from the request, which the wire does not repeat.
"template_read_only": func(e *ProblemError, t target) error {
return &issueops.TemplateReadOnlyError{IssueID: refusedIssueID(e, t)}
},
"issue_pinned": func(e *ProblemError, t target) error {
return &issueops.PinnedError{IssueID: refusedIssueID(e, t)}
},
"not_assignee": func(e *ProblemError, t target) error {
return &issueops.CloseNotAssigneeError{IssueID: refusedIssueID(e, t), Assignee: deref(e.Assignee), Actor: t.actor}
},
// 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'
}