* feat(http): bd blocked over bd serve (blocked.list) through issueops.BlockedLister
`bd blocked` refused against an HTTP workspace: it called the legacy
GetBlockedIssues, which the HTTP backend stubs as unsupported. It now runs
one role on every route, and bd serve publishes that role.
- Role: issueops.BlockedLister.ListBlocked(BlockedRequest{ParentID, Labels,
LabelsAny, ExcludeLabels}) -> BlockedResult{Items}. One body,
internal/storage/issueops.ExecuteListBlockedInTx over the unchanged
GetBlockedIssuesInTx; labels normalized in the role (BlockedFilter);
Items never nil and in a total order (priority, created_at desc, id).
- Legs: DoltStore (read tx), EmbeddedDoltStore (read conn), uow (read unit
of work through the use case's GetBlockedIssues, so the
external-dependency uow decorator applies). Census: storage.DoltStorage
gains BlockedLister(); HookFiringStore passes it through (a read),
telemetry wraps it, uow.notifyingProvider, externaldeps.uowProvider and
httpapi.timedProvider build it.
- externaldeps.Store.BlockedLister is built over its own GetBlockedIssues,
so local `bd blocked` output is unchanged. Over a remote store it takes
the server's listing when the server advertises
policy.external_dependencies, else decorates the server's listing here
through EdgeReader and BatchGetter (decorateBlocked, factored out of
GetBlockedIssues).
- Wire: GET /v0/beads/blocked (listBlockedIssues; parent, label,
label_any, exclude_label) answering BlockedPage {items, has_more} with
the new x-go-type-pinned BlockedIssue schema, behind the new
blocked.list token. apigen and the wire-shape golden regenerated; the
golden diff is additive only, so wire_revision stays 2.
Config.BlockedLister is a required role, wired in bd serve.
- Client: httpclient.Store.BlockedLister dials through Store.dispatch, so
an older server is refused BEFORE the dial with *wire.CapabilityError
naming blocked.list. The legacy Store.GetBlockedIssues rides the role
(page and row cap applied to its answer) and leaves the unsupported
shell. Divergence ledger row F-blocked retired.
- CLI: `bd blocked` takes BlockedLister() from the store on the direct
routes and from the provider's BlockedListerSource on the proxied route;
runBlockedProxiedServer is deleted. --json output is the same rows in
the same order, [] when empty.
Tests: backend/conformance RunBlockedLister (10 cases: direct blocker,
child attributed to its blocked parent, closed blocker, wisp plane, pinned
status, parent filter, label filters with normalization, order, empty
slice, request not mutated) on dolt, embedded, uow and the served HTTP
client; httpapi handler tests (mapping, unknown/repeated params,
projection, capability); httpclient stub tests (pre-dial refusal naming
the token, encoding, projection, legacy door paging); skew and vocabulary
counts; TestE2E_BlockedOverHTTP (served `bd blocked --json` equals the
local command's after mapping ids and timestamps, member order included,
external blocker named, older-server refusal with no dial); corpus
gc-blocked re-marked and gc-blocked-parent added, both pending until the
reference server advertises blocked.list.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(blocked): pin server-side external decoration, refuse has_more, serve the legacy door over http
Review fixes for the blocked.list slice.
- Server-side external decoration is now pinned on the compositions bd
serve answers from. TestWrapUOWProviderBlockedListerNamesExternalBlockers
lists through the wrapped unit-of-work provider's own BlockedLister
accessor (the bd serve provider path) and requires an external-only row
and a mixed row to carry their external: refs; building that lister over
the inner provider fails it. TestServedBlockedListerCarriesExternalRefs-
WhenTheServerEnforces serves the store-shaped composition
(externaldeps.Store.BlockedLister, policy advertised) and requires the
operation's own answer, through the undecorated client role, to carry the
refs, and the client's decorated chain to return it unchanged; serving
the inner store's lister fails it.
- The client refuses an answer reporting has_more with the new typed
httpclient.TruncatedListingError instead of returning a short listing:
the operation has no cursor, and a caller reads a missing row as
unblocked. The legacy door inherits it.
- externaldeps.Store.GetBlockedIssues over an http store reads the extra
sources through the served roles (EdgeReader, BatchGetter) instead of the
raw GetIssuesByIDs / GetDependencyRecordsForIssues the http backend
refuses, and the decoration skips the source read when there is nothing
to load. The legacy door on the CLI chain (bd mol stale, the wisp
commands) now answers over http in both policy modes;
TestServedLegacyGetBlockedIssuesThroughTheDecorator pins it, paging
included. bd ready --explain still refuses on its other raw reads; the
CHANGELOG says so.
- Docs: the spec and the retired F-blocked ledger row state that the
listing is unpaged, bounded by the client's 32 MiB response limit
(refused, never read in part), and that has_more is refused.
- Contract: new cases for waits-for and conditional-blocks blockers, no
type exclusions (gate, epic), and a stale flag with no nameable blocker
(on the legs that can write the column: dolt, embedded; skipped
elsewhere with the reason). Order seeds explicit created_at values with
five rows tied on priority and created_at, two of them wisps, so only the
id tiebreak orders them; dropping the tiebreak now fails every run.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* feat(blocked): bd blocked --flags, the blocked flag per id from stdin
`bd blocked --flags [--json]` reads ids from stdin, one per line (blank
lines and repeats ignored), and prints the blocked flag bd holds for each:
with --json, [{"id","is_blocked"}] in the order the ids were first given,
omitting an id that names no row on either plane, [] for no input. It is
the readiness column a consumer otherwise had to read with `bd sql`, so no
such consumer needs a local-only command.
It is the FLAG, not the listing: `bd blocked` narrows the stored flag to
rows it can name a blocker for, and --flags does not, so a row whose flag
is set with no nameable blocker reads true here and is absent from the
listing. Where the external-dependency policy applies, an unsatisfied
external: blocker sets the flag, as it keeps the row out of `bd ready`.
One library entry on every route: issueops.BlockedFlags over the route's
BlockingAnnotator (the store's accessor on dolt, embedded and HTTP, the
provider's on the proxied route). Over HTTP that is listBlockingAnnotations
with is_blocked behind dependencies.blocking.isBlocked; a server without
that token is refused before the dial, naming it. No wire change. The
listing's filter flags are refused with --flags rather than ignored.
Tests: TestE2E_BlockedFlagsOverHTTP (served JSON equals the local command's
after mapping ids to titles, unknown id omitted, repeat collapsed, [] on
empty stdin, filters refused; a stale-flagged row with no blocker reads
true and is absent from `bd blocked --json`, which fails if --flags is
derived from the listing; an older server's handshake refused naming the
token with no dial); TestProxiedServerBlocked/flags_reads_ids_from_stdin on
the proxied route; corpus gc-blocked-flags, pending until the reference
server advertises the token. CHANGELOG entry.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* feat(blocked): bd blocked --flags --raw, the stored is_blocked column
`bd blocked --flags --raw [--json]` answers the stored is_blocked column
for each id read from stdin, exactly what reading is_blocked from the issues
and wisps tables returns, without the external-dependency policy: a row
blocked only by an unsatisfied external: ref reads false (the policy-aware
--flags reads true), and a stale flag reads true either way. Same output
shape as --flags. This lets a consumer move off a `bd sql` read of the
column with no change in what it reads. The default --flags is unchanged.
The role is taken from beneath every decorator: storage.UnwrapStore on the
direct routes, uow.UnwrapProvider on the proxied route. Over HTTP the
innermost store is the http client, whose annotation read is the server's
answer: against a server that does not advertise
policy.external_dependencies that answer is the column, and --raw is
served. A server that advertises it decorates the flag it answers, the v0
wire has no member asking it for the column, and the decorated flag cannot
be turned back into the column client-side, so --raw against such a server
is refused before the annotation read, naming the token, rather than
answered with the decorated flag. --raw without --flags is refused.
Tests: TestE2E_BlockedFlagsOverHTTP/raw_is_the_stored_column (served --raw
equals local --raw; the externally-blocked-only row reads true with --flags
and false with --raw on both; locally blocked rows agree; a stale-flagged
row reads true in both modes; --raw without --flags exits 1; a server
advertising the policy refuses --raw with no annotation request);
TestProxiedServerBlocked/flags_raw_is_the_stored_column; corpus
gc-blocked-flags-raw (pending until the reference server advertises
dependencies.blocking.isBlocked). Routing --raw through the decorated
annotator fails the e2e. CHANGELOG entry.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* docs(changelog): bd blocked --flags --raw is for the local and proxied routes
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(blocked): give the e2e gate-kid its own priority; document --flags answers closed ids
TestE2E_BlockedOverHTTP seeded gate-parent and gate-kid at one priority, so
when both landed in the same second their order fell to the generated ids,
which differ between the local and the served workspace: the comparison
failed intermittently. gate-kid now has its own priority. Ten runs on the
embedded lane pass.
bd blocked --flags answers a closed id too, with its stored flag; a SQL read
of the column filtered on status <> 'closed' leaves it out. Said in the
command's doc and the CHANGELOG.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(blocked): apply label filters to external-only blocked rows
The external-dependency policy appends a row blocked only by an
unsatisfied external: ref after the label query has run, so --label,
--label-any and --exclude-label never judged it: bd blocked and
GET /v0/beads/blocked listed it whatever its labels, on every route.
Both decorators now filter those rows by the request's labels. The uow
decorator reads them through GetMany, chunked at MaxGetManyIDs, so their
labels are hydrated; GetIssuesByIDs left them empty, which also printed
them unlabelled on the proxied route.
Review fixes (adopt-pr apply-fixes, iteration 1):
- major #1: label filters on external-only rows in the store and uow
decorators, with absence-asserting arms in the unit, served httpclient
(server- and client-enforced policy), e2e and proxied tiers; the spec
and the role doc say such rows are narrowed like every other row.
- minor #2: the policy.external_dependencies token prose names the
blocked listing (spec, routes.go, regenerated types.gen.go).
- minor #6: SERVE_RUNBOOK and the allowUnlimited comment record the
blocked listing's unbounded whole-set answer and why.
- minor #10: BlockedLister telemetry-outermost and typed-unsupported pins
beside the ReadyCounter pair, plus the externaldeps wrap pin.
- nit #9: F-blocked names --flags --raw's refusal against a server that
applies the policy (ledger.go and the regenerated ledger doc).
- nit #11: the remote BlockedLister no longer builds a local lister it
then discards.
Review fixes (adopt-pr apply-fixes, iteration 2; the review approved at
940 with one minor and two nits, none gating):
- minor (the --flags refusal list was unpinned): the new
TestBlockedFlagsRefusesEveryListingFilter pins blockedFlagFilterFlags
to the flags blockedCmd registers, in both directions. Every
registered flag except --flags and --raw must be refused, and every
entry must name a registered flag. The test walks Flags() rather than
LocalFlags(), so it does not merge the root's persistent flags into
blockedCmd, and it skips inherited root flags and cobra's --help.
Mutants:
- four fail it: a new filter flag left off the list, a dropped
entry, a misspelled entry, and --raw added to the list;
- a simulated earlier in-process run (merged root flags plus --help)
stays green, and fails once either skip is removed.
- nit (the remote branch's span): the remote BlockedLister comment now
says why that lister is not wrapped again. The inner lister already
carries telemetry's span, so wrapping would nest a second span of the
same name. The comment also says what runs outside that span.
- nit (duplicated order comparator): left as is. finishBlockedIssues
predates this PR, so merging the two sorts would refactor existing
code with no review pass left after this one.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
1729 lines
94 KiB
Go
1729 lines
94 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"context"
|
|
"database/sql"
|
|
"database/sql/driver"
|
|
"encoding/json"
|
|
"errors"
|
|
"net"
|
|
"net/http"
|
|
"strconv"
|
|
"syscall"
|
|
|
|
"github.com/go-sql-driver/mysql"
|
|
|
|
"github.com/steveyegge/beads/internal/httpapi/apigen"
|
|
"github.com/steveyegge/beads/internal/storage"
|
|
"github.com/steveyegge/beads/internal/storage/uow"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/issueops"
|
|
)
|
|
|
|
// Every non-2xx byte this server emits is an RFC 9457 problem+json document
|
|
// (apigen.Problem, generated from the spec — there is one error shape here).
|
|
// This file owns the whole mapping: sentinel error in, status + machine code
|
|
// out, matched exclusively with errors.Is/errors.As. Never `err != nil ->
|
|
// status`.
|
|
//
|
|
// SENTINEL NOTE: the mapping keys on the sentinel VALUES, never on where they
|
|
// are declared. A parallel refactor relocates the canonical Err* declarations
|
|
// into a leaf issueops package and aliases them back from internal/storage
|
|
// with the same pointers, so errors.Is keeps matching either spelling with no
|
|
// edit here. Do not re-express these rows as package-path or message checks.
|
|
|
|
// Code is the machine-readable member of the problem envelope, and the only
|
|
// member a client may dispatch on.
|
|
//
|
|
// The vocabulary is a one-way door: renaming or removing a documented
|
|
// status+code pair breaks the wire. Adding one does not, which is why clients
|
|
// are told to default-branch on unknown codes within a status class. Keep it
|
|
// at what the v0 operations actually need.
|
|
type Code string
|
|
|
|
// The v0 code vocabulary. Every value here is documented in the spec, and
|
|
// TestSpecStatusCodesMatchHandlerTable fails if the two ever disagree.
|
|
const (
|
|
// CodeInvalidArgument covers every request-validation refusal: an unknown
|
|
// query parameter, a malformed value, an invalid actor, an unparseable or
|
|
// oversized body, limit=0 under --allow-non-loopback, and the Host-header
|
|
// middleware. The 400 carries `param` and `reason` so clients never have
|
|
// to tell those cases apart by reading prose.
|
|
CodeInvalidArgument Code = "invalid_argument"
|
|
// CodeInvalidCursor is a separate code because a stale or foreign cursor
|
|
// is a normal client situation with an obvious recovery (restart paging),
|
|
// not a client bug.
|
|
CodeInvalidCursor Code = "invalid_cursor"
|
|
CodeNotFound Code = "not_found"
|
|
// CodeAlreadyClaimed reports a live foreign holder. Where the `assignee`
|
|
// extension member is present it is the holder, read inside the same
|
|
// transaction and never parsed out of the sentinel's message text — but
|
|
// PRESENCE IS PER PRODUCER, and there are four:
|
|
//
|
|
// - claimIssue always attaches it: the claim's conflict path reads the
|
|
// row it lost to, so it has the holder in hand.
|
|
// - updateIssue and applyBatch attach it CONDITIONALLY, when the refusing
|
|
// error carried one. The assignee fence
|
|
// (AuthorizeAssigneeTransferWithPools) refuses without naming the
|
|
// holder, so an implementation that reported none leaves it absent.
|
|
// - releaseIssue NEVER attaches it. It is the same fence pointed the
|
|
// other way and it names nobody.
|
|
//
|
|
// A client therefore treats the member as optional on every operation but
|
|
// the claim, and re-reads the row when it is absent. Absence means "this
|
|
// refusal could not name the holder", never "nobody holds it".
|
|
CodeAlreadyClaimed Code = "already_claimed"
|
|
CodeNotClaimable Code = "not_claimable"
|
|
// CodeNotReleasable is a row refusing to give up a claim, and it covers
|
|
// the two conditions releaseIssue's role reports for that: the row holds
|
|
// no claim, or its status is neither open nor in_progress.
|
|
//
|
|
// A 409 for CodeNotClosable's reason: the body is well-formed and STATE
|
|
// refuses it, so the same request succeeds or fails on something the client
|
|
// cannot see without reading it.
|
|
//
|
|
// IT IS MINTED RATHER THAN FOLDED INTO CodeNotClaimable, which is the
|
|
// nearest existing code and covers a superset of the same statuses today.
|
|
// The coincidence is not a contract: the release transition is pinned to
|
|
// {open, in_progress} by releasableStatus and the claim's eligibility is a
|
|
// separate predicate, so the two sets are free to diverge and would then be
|
|
// one code meaning two things. Worse, the unheld half would be an outright
|
|
// lie — an open, unassigned row is the MOST claimable row a workspace has,
|
|
// and answering `not_claimable` about it would send a client somewhere
|
|
// there is nothing to find.
|
|
//
|
|
// IT COVERS BOTH CONDITIONS UNDER ONE CODE, and that is a deliberate
|
|
// start-narrow CHOICE rather than a consequence of missing information.
|
|
//
|
|
// THE TWO CONDITIONS ARE FULLY DISTINGUISHABLE HERE. ErrNotClaimed and
|
|
// ErrNotReleasable are two distinct typed sentinels, and failRelease holds
|
|
// both in one case arm — so a future split needs no archeology and no
|
|
// prose-scraping: it is a mapping change in that arm plus a code in this
|
|
// block and a line in the document. What IS unavailable typed is the
|
|
// OBSERVATION either refusal made — the status it saw, the emptiness of the
|
|
// assignee — because both format those into their messages and this surface
|
|
// does not scrape its own prose. That is why the code carries no extension
|
|
// member, and it is a narrower statement than "the refusals are
|
|
// indistinguishable", which they are not.
|
|
//
|
|
// The split is deferred rather than refused because one code is the
|
|
// reversible direction: splitting later is an ADDITION, which the document
|
|
// already tells clients to tolerate, while merging two published codes into
|
|
// one is the removal that breaks the wire. A client that needs the
|
|
// distinction before then reads the row, which the operation description
|
|
// tells it to do for a safety reason rather than a taste one.
|
|
CodeNotReleasable Code = "not_releasable"
|
|
// CodeLeaseNotHeld is a heartbeat refused because the actor holds no live
|
|
// claim on the row: it is open, closed, released, reclaimed, moved off
|
|
// in_progress, or a wisp (wisps are never leased). The `issue_status`
|
|
// extension carries the status the refusing transaction observed, from
|
|
// *issueops.LeaseConflictError's typed field.
|
|
//
|
|
// It is MINTED rather than folded into CodeNotClaimable for
|
|
// CodeNotReleasable's reason: an open, unassigned row is the most claimable
|
|
// row a workspace has, and answering `not_claimable` about it would send a
|
|
// worker somewhere there is nothing to find. A FOREIGN holder is not this
|
|
// code: that is the claim's own `already_claimed`, naming the holder.
|
|
CodeLeaseNotHeld Code = "lease_not_held"
|
|
// CodeNotClosable is close policy refusing an unforced close: open
|
|
// children, or a live blocker. The open-children refusal carries the count
|
|
// in the `open_children` extension member, read inside the refusing
|
|
// transaction — never parsed out of the sentinel's message text — and its
|
|
// PRESENCE is how a client tells the two refusals apart without prose. The
|
|
// live-blocker refusal names its blockers in the `blockers` member, from
|
|
// *issueops.BlockedError's typed list (see closeBlocked).
|
|
//
|
|
// A 409 rather than the delete precedent's 400: this is a statement about
|
|
// the current state of one named resource, so the same request succeeds or
|
|
// fails on state the client cannot see without reading it. That is the
|
|
// not_claimable situation and it gets the not_claimable answer.
|
|
CodeNotClosable Code = "not_closable"
|
|
// CodeNotesOverwrite is a `patch.notes` that would replace existing
|
|
// non-empty notes with a different value, refused unless
|
|
// `force_notes_overwrite` is set. It is the notes analog of
|
|
// CodeAlreadyClaimed: a live-state fence with a force bypass — but unlike
|
|
// that fence it carries no compare-and-set alternative and no extension
|
|
// member, because there is no observation to attach: the refusal is
|
|
// entirely a statement about the request's own two values (the existing
|
|
// notes and the patched ones), not about a foreign actor's identity a
|
|
// client might need to display.
|
|
CodeNotesOverwrite Code = "notes_overwrite_refused"
|
|
// CodeTemplateReadOnly is a guarded mutation that names a template;
|
|
// operationCodes lists the operations that answer it, and not every verb
|
|
// guards templates yet (bd-jkp9v3). Templates are read-only — work comes
|
|
// out of one by pouring it, which creates new issues — so no force flag
|
|
// waives it: the same request refuses for as long as the row is a
|
|
// template. The one stand-down is updateIssue's `allow_template`, a
|
|
// deliberate template edit (bd label, bd set-state).
|
|
// A 409 for CodeNotClosable's reason: the body is well-formed and the
|
|
// STATE of the named row refuses it.
|
|
CodeTemplateReadOnly Code = "template_read_only"
|
|
// CodeIssuePinned is an unforced close of a pinned issue, by either of the
|
|
// two spellings bd pins with (the `pinned` flag or the `pinned` status).
|
|
// `force` is the bypass. It is its own code rather than a third
|
|
// `not_closable` because that code's member-presence discriminator already
|
|
// reads "no `open_children`" as a live blocker, and a pin is not one.
|
|
CodeIssuePinned Code = "issue_pinned"
|
|
// CodeNotAssignee is an unforced close by an actor who is not the issue's
|
|
// assignee (be-035): an unassigned issue is closable by anyone, an
|
|
// assigned one by its holder, compared separator-insensitively. `force` is
|
|
// the bypass. The holder the refusing transaction observed travels in the
|
|
// `assignee` member, so a client names it without reading `detail`; the
|
|
// closing actor is the one the request sent.
|
|
//
|
|
// It is minted rather than folded into CodeAlreadyClaimed, which a client
|
|
// maps to a lost CLAIM: answering it for a close would have the client
|
|
// read the operation, rather than the code, to decide what was refused.
|
|
CodeNotAssignee Code = "not_assignee"
|
|
// CodeDependencyCycle covers BOTH never-makes-progress refusals a requested
|
|
// edge set can earn: a scheduling cycle, and a blocking edge against the
|
|
// issue's own ancestor or descendant. They are one code because they have
|
|
// one client recovery — rethink the edge, with no force bypass for either —
|
|
// and codes are the vocabulary of recovery. The typed distinction is NOT
|
|
// lost: the hierarchy refusal additionally carries `issue_id`, `blocker_id`
|
|
// and `blocker_is_ancestor`, read inside the refusing transaction, and
|
|
// member presence is the discriminator.
|
|
CodeDependencyCycle Code = "dependency_cycle"
|
|
// CodeDependencyExists is the pair that already carries an edge of a
|
|
// DIFFERENT type, with both types in `existing_type`/`requested_type`.
|
|
CodeDependencyExists Code = "dependency_exists"
|
|
// CodeAlreadyExists is a create whose EXPLICIT id already names a stored
|
|
// row. `param` names the offending member and, on a batch operation, the
|
|
// item members name which item carried it.
|
|
//
|
|
// A 409 rather than a 400, and the distinction is the one CodeNotClosable
|
|
// draws: the request is well-formed and stays well-formed: what refuses it
|
|
// is STATE the client cannot see without reading it, and recovery is to
|
|
// look at that state — adopt the row, pick another id, or stop. A 400 says
|
|
// "this body is malformed, fix it and it will work", which is false here:
|
|
// the identical body succeeded before the id was taken and would succeed
|
|
// again against a workspace that never took it.
|
|
//
|
|
// It is minted rather than folded into CodeInvalidArgument because the two
|
|
// are not narrowable later: widening a 400 to a 409 changes the status an
|
|
// existing client dispatches on, while a 409 that turns out to be
|
|
// unreachable retires for free.
|
|
CodeAlreadyExists Code = "already_exists"
|
|
// CodePreconditionFailed is a compare-and-set guard that MISSED on an
|
|
// operation whose contract is that a miss refuses everything. The expected
|
|
// values travel in typed extension members; a batch operation adds the
|
|
// members naming which item carried the guard.
|
|
//
|
|
// A 409 for CodeNotClosable's reason: the request is fine as a request and
|
|
// the STATE refuses it, so the same body succeeds or fails on something the
|
|
// client cannot see without reading it.
|
|
//
|
|
// IT IS NOT THE ANSWER TO EVERY LOST COMPARE-AND-SET on this surface, and
|
|
// the split is the point. Where a miss is the ordinary path of a retry loop
|
|
// — the metadata compare-and-set — it is a 200 carrying the current value,
|
|
// because putting a loop's normal iteration in the error channel would make
|
|
// the value that loop needs next travel as a problem member. This code is
|
|
// for the opposite contract: a guard on one step of a plan the caller meant
|
|
// to land whole, where a miss took the entire request down and there is
|
|
// nothing to report but the refusal.
|
|
//
|
|
// The expected/actual members are SPLIT BY TYPE — expected_version and
|
|
// actual_version, expected_status and actual_status, expected_assignee and
|
|
// actual_assignee — rather than one polymorphic pair, because a generic
|
|
// `expected`/`actual` of "a version or a status or an assignee" is a schema
|
|
// alternation and this document's x-go-type doctrine admits no composition
|
|
// keyword to spell one.
|
|
CodePreconditionFailed Code = "precondition_failed"
|
|
// CodeEventsJournalDisabled is the events journal being OFF on the served
|
|
// workspace. It exists because the alternative answer is a lie: a disabled
|
|
// journal reads as zero rows and a head of zero, which is byte-identical to
|
|
// an enabled journal nothing has written to yet — so a consumer would poll a
|
|
// workspace that will never produce a record and call it "caught up"
|
|
// forever. This is the one refusal on this surface that a client cannot
|
|
// discover any other way.
|
|
//
|
|
// A 409 for the reason CodeNotClosable gives: it is a statement about the
|
|
// current state of the workspace, which the same request stops earning the
|
|
// moment an operator sets `events-journal true` and restarts the server.
|
|
// Not a 404 — the operation and the resource both exist — and not a 501,
|
|
// which this surface reserves for an operation this BUILD does not
|
|
// implement, whereas every build implements this one.
|
|
CodeEventsJournalDisabled Code = "events_journal_disabled"
|
|
// CodeEventsJournalTruncated is a journal read whose checkpoint has fallen
|
|
// below the retained window. The value is storage's own constant, so the
|
|
// code a `bd events tail --json` failure carries and the code this surface
|
|
// emits cannot drift to two spellings of one condition.
|
|
//
|
|
// A 410 Gone, and the only one in the vocabulary: the records the caller
|
|
// asked for existed, were addressable by exactly this request, and have been
|
|
// deliberately deleted. That is what 410 means and what 404 does not — a 404
|
|
// would say the resource never existed and invite a retry, and the whole
|
|
// point of this refusal is that retrying the same `since` can never succeed.
|
|
// The `since`, `floor` and `head` members carry the window the server can
|
|
// still serve, so the recovery (resume from `floor - 1` and accept the gap,
|
|
// or re-baseline) is a decision the client makes from data rather than prose.
|
|
CodeEventsJournalTruncated Code = Code(storage.EventsJournalTruncatedCode)
|
|
// CodeEventsWatchSaturated is this server already holding as many open
|
|
// journal streams as it will. It is not CodeBusy, even though both are a
|
|
// 503 with a Retry-After, because the two carry different recoveries: busy
|
|
// says the database is congested and the same request will work shortly,
|
|
// while this says a bounded resource is fully subscribed by connections that
|
|
// may last hours — and the caller has a second recovery available that busy
|
|
// does not offer, namely the paged read, which holds nothing between
|
|
// requests and is never refused for this reason.
|
|
CodeEventsWatchSaturated Code = "events_watch_saturated"
|
|
// CodeUnauthenticated is a missing, malformed or unrecognized bearer
|
|
// credential on a server that was configured with one. It is a DEPLOYMENT
|
|
// posture, not a property of the operation: a server started with no token
|
|
// file never emits it. The three client mistakes are deliberately one code
|
|
// — telling them apart on the wire would tell an unauthenticated caller
|
|
// which of its guesses was closer.
|
|
CodeUnauthenticated Code = "unauthenticated"
|
|
// CodeBusy is retryable contention: the transaction retry budget was
|
|
// exhausted, or the in-flight request limit was saturated.
|
|
CodeBusy Code = "busy"
|
|
// CodeDBUnavailable is a retryable connectivity failure reaching the
|
|
// database.
|
|
CodeDBUnavailable Code = "db_unavailable"
|
|
CodeInternal Code = "internal"
|
|
)
|
|
|
|
// codeClientClosed is a LOG-ONLY outcome, not wire vocabulary: it is
|
|
// deliberately absent from codeStatus, from operationCodes and from the
|
|
// document, and it never reaches a response body — the client it describes has
|
|
// already gone. It exists so that the request line does not book a client
|
|
// hanging up as a server fault. See failErr.
|
|
const codeClientClosed Code = "client_closed"
|
|
|
|
// codeStatus freezes one HTTP status per code. A code that could arrive with
|
|
// two different statuses would defeat the point of dispatching on it.
|
|
var codeStatus = map[Code]int{
|
|
CodeInvalidArgument: http.StatusBadRequest,
|
|
CodeInvalidCursor: http.StatusBadRequest,
|
|
CodeUnauthenticated: http.StatusUnauthorized,
|
|
CodeNotFound: http.StatusNotFound,
|
|
CodeAlreadyClaimed: http.StatusConflict,
|
|
CodeNotClaimable: http.StatusConflict,
|
|
CodeNotClosable: http.StatusConflict,
|
|
CodeNotesOverwrite: http.StatusConflict,
|
|
CodeTemplateReadOnly: http.StatusConflict,
|
|
CodeIssuePinned: http.StatusConflict,
|
|
CodeNotAssignee: http.StatusConflict,
|
|
CodeNotReleasable: http.StatusConflict,
|
|
CodeLeaseNotHeld: http.StatusConflict,
|
|
CodeDependencyCycle: http.StatusConflict,
|
|
CodeDependencyExists: http.StatusConflict,
|
|
CodeAlreadyExists: http.StatusConflict,
|
|
|
|
CodePreconditionFailed: http.StatusConflict,
|
|
|
|
CodeEventsJournalDisabled: http.StatusConflict,
|
|
CodeEventsJournalTruncated: http.StatusGone,
|
|
CodeEventsWatchSaturated: http.StatusServiceUnavailable,
|
|
|
|
CodeBusy: http.StatusServiceUnavailable,
|
|
CodeDBUnavailable: http.StatusServiceUnavailable,
|
|
CodeInternal: http.StatusInternalServerError,
|
|
}
|
|
|
|
// Status returns the HTTP status frozen to c, or 0 if c is not in the v0
|
|
// vocabulary.
|
|
func (c Code) Status() int { return codeStatus[c] }
|
|
|
|
// Reason distinguishes the two client postures behind a 400
|
|
// CodeInvalidArgument, so that telling them apart never requires parsing
|
|
// `detail`. The set may grow; clients default-branch on unknown values.
|
|
type Reason string
|
|
|
|
const (
|
|
// ReasonUnknownParameter means this server does not know that parameter:
|
|
// version skew. The client degrades or falls back. It is also a client's
|
|
// only per-parameter capability probe, since `capabilities` is
|
|
// operation-level.
|
|
ReasonUnknownParameter Reason = "unknown_parameter"
|
|
// ReasonInvalidValue means the server will not act on that value:
|
|
// malformed, outside the vocabulary, or legal-but-refused in this
|
|
// server's configuration (limit=0 under --allow-non-loopback). The
|
|
// recovery is always to send something different, never to retry; the
|
|
// detail says which case it was.
|
|
ReasonInvalidValue Reason = "invalid_value"
|
|
// ReasonProjectMismatch means the request stamped a Bd-Project-Id that is
|
|
// not the project this server serves. Like the Host-header refusal it is a
|
|
// document-level 400 reachable on every enforced route rather than
|
|
// per-operation behavior, and it is the one refusal that carries
|
|
// `server_project_id`. The recovery is to stop stamping this server with
|
|
// another workspace's id, never to retry the same request.
|
|
ReasonProjectMismatch Reason = "project_mismatch"
|
|
// ReasonWireRevisionUnsupported means the request's Bd-Wire-Revision header
|
|
// named a revision below this server's ContextResponse.min_client_wire_revision.
|
|
// Like ReasonProjectMismatch it is a document-level 400 reachable on every
|
|
// enforced route — including the identity handshake itself — rather than
|
|
// per-operation behavior, and it is the one refusal that carries
|
|
// `min_wire_revision`. The recovery is to stop talking to this server with a
|
|
// client built for a revision it no longer supports, never to retry the same
|
|
// request.
|
|
ReasonWireRevisionUnsupported Reason = "wire_revision_unsupported"
|
|
// ReasonEphemeral qualifies a 409 CodeLeaseNotHeld: the id names a wisp,
|
|
// which is never leased, so no claim on it can ever be heartbeaten. It is
|
|
// the typed form of issueops.LeaseConflictError.Ephemeral, so a client
|
|
// tells a wisp from an unclaimed issue without parsing `detail` (a wisp's
|
|
// `issue_status` can be in_progress).
|
|
ReasonEphemeral Reason = "ephemeral"
|
|
)
|
|
|
|
// staticDetail is the set of codes whose `detail` is FIXED, whatever the
|
|
// caller or the call site passed. newResult overrides the supplied detail for
|
|
// every code listed here, which is what makes the guarantee structural rather
|
|
// than a rule each call site has to remember.
|
|
//
|
|
// Every 5xx is on it. The underlying error goes to the server log and nowhere
|
|
// else: driver and dial errors routinely embed the DSN — go-sql-driver renders
|
|
// connection targets as user@tcp(127.0.0.1:PORT)/db, net dial errors carry the
|
|
// same host:port — and query errors can carry SQL fragments. The moment the
|
|
// server is bound with --allow-non-loopback, a verbose 5xx detail is an
|
|
// information-disclosure channel to network peers.
|
|
//
|
|
// The 401 is on it for the mirror-image reason, and it is the one row that is
|
|
// not a 5xx: the caller's own input here is a CREDENTIAL. Ordinary 4xx details
|
|
// stay specific precisely because they reflect the caller's input back, which
|
|
// is exactly what must never happen to a presented token — it would land in
|
|
// every client log and proxy trace between here and the caller.
|
|
var staticDetail = map[Code]string{
|
|
CodeUnauthenticated: "missing or invalid bearer token",
|
|
CodeBusy: "the server is busy; retry shortly",
|
|
CodeDBUnavailable: "database temporarily unavailable; retry",
|
|
CodeInternal: "internal server error",
|
|
}
|
|
|
|
// Retry-After values, in seconds.
|
|
const (
|
|
// retryAfterContention follows an exhausted transaction retry budget. The
|
|
// budget spans many seconds of observed write contention, so a one-second
|
|
// comeback would invite a convoy of retries that each hold a slot while
|
|
// they wait — starving reads exactly when the server is busiest.
|
|
retryAfterContention = 5
|
|
// retryAfterSaturation follows an in-flight-limit wait timeout. Slot
|
|
// pressure clears quickly.
|
|
retryAfterSaturation = 1
|
|
// retryAfterWatchSaturation follows a refused journal stream. Streams are
|
|
// held for as long as their consumers stay connected — minutes to hours —
|
|
// so a slot opens on a human timescale rather than a request one, and the
|
|
// one-second comeback the slot limiter offers would be a busy loop against a
|
|
// condition that has not changed.
|
|
retryAfterWatchSaturation = 30
|
|
)
|
|
|
|
// ErrBusy reports that the in-flight request limiter refused to admit the
|
|
// request within its bounded wait. The limiter itself lands with the server;
|
|
// the sentinel lives here so the mapping owns the whole 503 vocabulary.
|
|
var ErrBusy = errors.New("server busy")
|
|
|
|
// Operation ids, matching the spec's operationId values exactly.
|
|
const (
|
|
OpHealth = "health"
|
|
OpGetContext = "getContext"
|
|
OpListReadyWork = "listReadyWork"
|
|
OpGetStats = "getStats"
|
|
OpListIssues = "listIssues"
|
|
OpGetIssue = "getIssue"
|
|
OpClaimIssue = "claimIssue"
|
|
// OpBatchCloseIssues closes many issues as one transaction, behind
|
|
// issueops.BatchCloser. It is the surface's ONLY operation whose 200 body
|
|
// carries refusals: the role is deliberately not all-or-nothing, so an id
|
|
// it turns down is skipped and the survivors commit.
|
|
//
|
|
// Its problem vocabulary is therefore narrow rather than wide — everything
|
|
// an ITEM can earn lives in that item's outcome, and a problem document
|
|
// from this operation means the batch NEVER RAN.
|
|
OpBatchCloseIssues = "batchCloseIssues"
|
|
// OpClaimNextIssue takes ONE ready issue and hands it back claimed, behind
|
|
// issueops.ReadyClaimer. It is the surface's first operation that names no
|
|
// row at all: the caller sends a QUESTION — the ready listing's own filter
|
|
// vocabulary — and the role picks the answer.
|
|
//
|
|
// It exists to retire a RACE rather than a round trip. The listing-then-claim
|
|
// composition it replaces reads a row another agent claims before the second
|
|
// request arrives, so a fleet polling one queue earns 409s for rows it was
|
|
// correctly offered.
|
|
OpClaimNextIssue = "claimNextIssue"
|
|
// OpReleaseIssue gives a claim back — the claim's inverse, and what
|
|
// `bd unclaim` spells. It is a named lifecycle action rather than a status
|
|
// patch for OpCloseIssue's reason: an update spells the release three
|
|
// fields at a time, which puts the transition's definition in the caller,
|
|
// and the lease it drops is the part a patch cannot express at all.
|
|
//
|
|
// It is the one write on this surface that is NOT idempotent, and the
|
|
// asymmetry with the claim is a fact about the two post-states rather than
|
|
// a preference: a claim's post-state names the claimant, so a re-claim is
|
|
// recognizable and can answer 200. A release leaves an anonymous row, so
|
|
// "I released this twice", "a reaper beat me to it" and "nothing ever
|
|
// claimed it" are one row — and one 200 for three situations that want
|
|
// different things from a caller. It answers 409 instead and lets the
|
|
// caller decide which of them it can live with.
|
|
OpReleaseIssue = "releaseIssue"
|
|
// OpCloseIssue is the second half of the agent loop this surface exists to
|
|
// serve: claim, work, close. It is a named lifecycle action rather than a
|
|
// status patch because Close carries semantics a patch has nowhere to put —
|
|
// the reason and session under first-close-wins, the done-status
|
|
// normalization, and the close policy vocabulary.
|
|
OpCloseIssue = "closeIssue"
|
|
// OpAdvanceMolecule moves a molecule on after one of its steps closed: the
|
|
// operation behind `bd close --continue` (issueops.MoleculeStepper).
|
|
OpAdvanceMolecule = "advanceMolecule"
|
|
// OpReopenIssue is the close's mirror, and it completes the lifecycle pair
|
|
// so a recovery flow works end to end over this surface. It is the one write
|
|
// here with no POLICY conflict code: reopen takes an issue OUT of the done
|
|
// category, so there is no state of the graph that can refuse it. Its one
|
|
// 409 is the caller's own compare-and-set, which is a fact about the
|
|
// request's premise rather than about the graph.
|
|
OpReopenIssue = "reopenIssue"
|
|
// OpUpdateIssue edits the FIELDS of one issue, including the three that
|
|
// carry policy: `status`, `assignee` and `parent_id`.
|
|
//
|
|
// It USED to exclude all three, and to have no 409 because of it. The
|
|
// exclusion did not survive contact with a caller: an edit that moves a
|
|
// status alongside other fields in one transaction is the thing two calls
|
|
// cannot do, `issues:batchApply`'s update item has published all three since
|
|
// it landed, and keeping them off here meant the two operations disagreed
|
|
// about what patching one issue means. They are the SAME refusals here as
|
|
// there — close policy, the assignee fence, the graph's two — and the named
|
|
// lifecycle operations keep the semantics a status write has nowhere to put.
|
|
OpUpdateIssue = "updateIssue"
|
|
OpListSettings = "listSettings"
|
|
OpGetSetting = "getSetting"
|
|
OpListDependencyCycles = "listDependencyCycles"
|
|
// OpSetSetting stores one setting, replacing whatever was there. It is the
|
|
// surface's first PUT, and the method IS the argument: the caller names the
|
|
// resource by path and sends the value that becomes its whole state.
|
|
// rememberMemory posts to a COLLECTION because its key may be derived from
|
|
// the content; here the caller can always name what it is writing.
|
|
OpSetSetting = "setSetting"
|
|
// OpUnsetSetting removes one setting. It is the second DELETE on this
|
|
// surface and the one that does NOT 404 on a key nothing stored: this role
|
|
// reports no affected-row count, so the operation states an intended end
|
|
// state rather than an act performed. See its operationCodes row.
|
|
OpUnsetSetting = "unsetSetting"
|
|
// OpListDependencies reads STORED EDGE ROWS for several issues at once.
|
|
// It is a separate operation from getIssue's embedded `dependencies`
|
|
// member because it answers per named issue, reports the ids that named
|
|
// nothing, and returns edges whose target this database holds no row for.
|
|
OpListDependencies = "listDependencies"
|
|
// OpCountDependencyEdges sizes each anchor's edge set in ONE named
|
|
// direction, behind issueops.GraphCounter. It is NOT listDependencies
|
|
// counted: that operation is outgoing-only and takes no direction, this one
|
|
// REQUIRES one and answers about either end, so the two agree on a number
|
|
// only at direction=out. It is also not a third Counter method — that role
|
|
// answers about a set of ISSUES described by a predicate, and this one about
|
|
// EDGES anchored on ids, per anchor.
|
|
OpCountDependencyEdges = "countDependencyEdges"
|
|
// OpBatchGetIssues reads several issues by id in ONE snapshot, behind
|
|
// issueops.BatchGetter. It is NOT getIssue repeated: that operation names
|
|
// one id and answers 404 on a miss, and this one names many and reports an
|
|
// absent id in `missing` beside whatever else resolved — the set-read
|
|
// answer EdgeCountRequest.IDs and EdgeReadRequest already give, applied to
|
|
// the issues themselves rather than their edges.
|
|
OpBatchGetIssues = "batchGetIssues"
|
|
// OpReclaimIssues reverts every stale lease a request scopes back to ready,
|
|
// behind issueops.LeaseReclaimer. It is NOT releaseIssue repeated: that
|
|
// operation gives up ONE claim on the holder's say-so and refuses an unheld
|
|
// row, and this one sweeps MANY leases on a clock's say-so and reports an id
|
|
// that was not a stale lease by leaving it out of `reclaimed`.
|
|
OpReclaimIssues = "reclaimIssues"
|
|
// OpHeartbeatIssue refreshes the lease on one issue the actor holds, behind
|
|
// issueops.Heartbeater: what `bd heartbeat` spells. It is NOT claimIssue
|
|
// repeated: a re-claim is idempotent for the holder WITHOUT extending the
|
|
// lease, and this extends the lease. A refresh writes nothing else — no
|
|
// revision, no version, no updated_at, no event; a re-arm (`rearmed`) is
|
|
// recorded as a mutation and writes each of them.
|
|
OpHeartbeatIssue = "heartbeatIssue"
|
|
// OpListRelatedIssues reads ONE issue's neighbors in a named direction,
|
|
// behind issueops.Relations. It is NOT listDependencies narrowed to one
|
|
// anchor: that operation answers the stored edge ROWS with their targets
|
|
// spelled as stored, and this one answers the ISSUES on the far end — so an
|
|
// edge whose target this database holds no row for is a row there and no
|
|
// neighbor here, and the two answer different arities of question.
|
|
//
|
|
// It is a SUB-RESOURCE OF THE ISSUE rather than a member of the dependency
|
|
// collection, and the argument is ELEMENT IDENTITY rather than a claim about
|
|
// what that collection answers with — getDependencyTree answers hydrated
|
|
// TreeNodes, so "everything under /dependencies is about edges" would be
|
|
// false. What decides it is narrower and checkable: the rows here are the
|
|
// SAME pinned struct getIssue already carries under `dependencies` and
|
|
// `dependents`, so this operation is that pair, standalone,
|
|
// direction-parameterized and type-filterable — and it belongs on the
|
|
// resource whose members it publishes.
|
|
OpListRelatedIssues = "listRelatedIssues"
|
|
// OpListBlockingAnnotations reads the DERIVED blocking decoration for
|
|
// several issues at once — open blockers, issues blocked, and the parent.
|
|
// It is separate from listDependencies because it answers a summary over
|
|
// two edge types with a status rule applied, where that one returns the
|
|
// stored rows and applies nothing.
|
|
OpListBlockingAnnotations = "listBlockingAnnotations"
|
|
// OpGetDependencyTree walks the dependency graph from ONE root. It is
|
|
// separate from listDependencies because that one answers raw edge rows for
|
|
// many anchors at one hop, and this one recurses from a single anchor with a
|
|
// depth, a cycle policy and a node shape of its own.
|
|
OpGetDependencyTree = "getDependencyTree"
|
|
OpCountReadyWork = "countReadyWork"
|
|
// OpListBlockedIssues lists the blocked issues with the blockers bd names
|
|
// for each, behind issueops.BlockedLister: what `bd blocked` prints.
|
|
OpListBlockedIssues = "listBlockedIssues"
|
|
OpQueryIssues = "queryIssues"
|
|
// OpCountIssues sizes a set the ISSUE listing describes, behind
|
|
// issueops.Counter. It is a sibling of countReadyWork rather than a mode of
|
|
// it: that one sizes the READY predicate, which is dependency-aware and not
|
|
// expressible as a filter over one table, and this one sizes a predicate.
|
|
//
|
|
// It is also NOT `listIssues` with the page taken off, which is the mistake
|
|
// its own document spends a section on: a listing hides closed, pinned,
|
|
// template and gate rows and a count hides none of them, so the two answer
|
|
// about different sets for the same parameters. That difference is the
|
|
// ROLE's and is the reason Counter is not a counted variant of Reader.
|
|
//
|
|
// One operation carries both of the role's methods. `group_by` selects the
|
|
// bucketed shape, and the grouped response is the scalar response plus one
|
|
// member — the same schema, not a second contract wearing one id.
|
|
OpCountIssues = "countIssues"
|
|
// OpRemoveDependency is the first WRITE to the dependency graph on this
|
|
// surface, behind issueops.DependencyEditor. It names one edge by both its
|
|
// endpoints, because an edge has two and neither alone identifies it.
|
|
OpRemoveDependency = "removeDependency"
|
|
// OpAddDependencies is the graph's other write: a BATCH of edges asserted
|
|
// as one transaction, or none of them. It is the operation that owns both
|
|
// new conflict codes, because both are statements about the graph a
|
|
// requested edge set would produce.
|
|
OpAddDependencies = "addDependencies"
|
|
// OpSweepIssues is one of the two DESTRUCTIVE operations on this surface:
|
|
// bulk clearance of closed beads from one tier, behind issueops.Sweeper.
|
|
OpSweepIssues = "sweepIssues"
|
|
// OpDeleteIssues is the other DESTRUCTIVE operation: erasure of beads the
|
|
// request NAMES, behind issueops.Deleter. It is the one operation here whose
|
|
// refusals include a question about the GRAPH — a named bead with a
|
|
// dependent the request did not name.
|
|
OpDeleteIssues = "deleteIssues"
|
|
// OpCreateIssue creates ONE issue, with its parent, its explicit edges and
|
|
// its waits-for gate, as one transaction. It is the plain collection POST
|
|
// batchCreateIssues left free by spelling itself as a custom method.
|
|
//
|
|
// It publishes the whole create vocabulary rather than that operation's
|
|
// narrow item — `status`, `sender`, `metadata`, `ephemeral`, `no_history`
|
|
// and an explicit `id` included — which is what makes it usable for a
|
|
// caller composing a real row, and which is also where its two conflict
|
|
// codes come from: an occupied id, and the graph refusing the edges the
|
|
// request asked for.
|
|
OpCreateIssue = "createIssue"
|
|
// OpAddComment appends one comment to the thread an issue owns, behind
|
|
// issueops.Commenter. It is the surface's first write on a SUB-RESOURCE
|
|
// COLLECTION, and a plain collection POST for OpCreateIssue's reason:
|
|
// creating one member of the collection a path names is what POST means.
|
|
//
|
|
// The row it creates is the same pinned Comment getIssue already carries
|
|
// under `comments`, which is what puts the operation on the issue rather
|
|
// than on a collection of its own. The collection publishes no GET,
|
|
// deliberately: no role answers a comment PAGE, and inventing one here
|
|
// would be this surface deciding a paging contract the role declined.
|
|
OpAddComment = "addComment"
|
|
// OpBatchCreateIssues creates many issues as one transaction, or none.
|
|
OpBatchCreateIssues = "batchCreateIssues"
|
|
// OpApplyBatch applies an ORDERED, heterogeneous plan — creates, updates,
|
|
// closes and dependency edges together — as one transaction, or none of it.
|
|
// It is the only operation here whose request expresses a graph that
|
|
// references its own items: a create may NAME itself and later items address
|
|
// it by that name.
|
|
//
|
|
// It is therefore the widest refusal vocabulary on this surface, and every
|
|
// entry is inherited rather than invented: it can earn the lifecycle's
|
|
// close-policy conflict, the claim's assignee fence and both of the graph's
|
|
// conflicts, because it performs all three families of write.
|
|
OpApplyBatch = "applyBatch"
|
|
// OpRememberMemory stores one memory, behind memoryops.Memories. It is the
|
|
// first operation on this surface that reaches a role outside issueops: the
|
|
// memory plane is user data riding in the config table, not settings, and
|
|
// the two have different merge semantics and a different miss contract.
|
|
OpRememberMemory = "rememberMemory"
|
|
// OpGetMemory reads one memory by key. It is the ONE operation on this
|
|
// surface that answers a miss with a 404 where its settings counterpart
|
|
// deliberately does not: see its operationCodes row.
|
|
OpGetMemory = "getMemory"
|
|
// OpForgetMemory is the THIRD destructive operation on this surface, and the
|
|
// only one that is a DELETE method: it names one memory by path, carries no
|
|
// body and takes no flags, which is what that method already means. The two
|
|
// destructive issue operations are collection-level custom methods because
|
|
// they act on a set the request describes.
|
|
OpForgetMemory = "forgetMemory"
|
|
// OpListMemories enumerates the memory plane, narrowed by one search term.
|
|
// It is the operation that makes stored memories DISCOVERABLE rather than
|
|
// merely readable by a caller who already knows a key.
|
|
OpListMemories = "listMemories"
|
|
// OpListEvents pages the durable mutation journal from a caller-held
|
|
// checkpoint. It is the first operation on this surface whose paging is not
|
|
// a cursor this server minted: `since` is a sequence number the journal
|
|
// itself assigned, so a consumer's position survives a restart on either
|
|
// side and is meaningful to `bd events tail` as well.
|
|
//
|
|
// It is a READ of a log, not a subscription: the paged form has no follow
|
|
// mode and never will. The retention contract is what makes that safe to
|
|
// publish — a consumer that falls too far behind is told so with
|
|
// `events_journal_truncated` rather than served a silently shortened history.
|
|
OpListEvents = "listEvents"
|
|
// OpWatchEvents pushes the same journal over a held-open text/event-stream
|
|
// response, resuming from the same checkpoint. It is a sibling of the paged
|
|
// read rather than a mode of it: the contracts differ in media type,
|
|
// lifetime, limits and capacity, and one operation carrying both would have
|
|
// documented two of everything under one operationId.
|
|
//
|
|
// It is the surface's ONLY streaming operation, and the only one whose
|
|
// response can report a failure after its status is written — a prune that
|
|
// races an open stream arrives as a named event rather than as the 410 the
|
|
// same condition earns at connect.
|
|
OpWatchEvents = "watchEvents"
|
|
// OpCompareAndSetMetadata conditionally sets one metadata key on an issue.
|
|
// It is the only WRITE on this surface whose ordinary refusal is a 200: a
|
|
// lost race is the answer to the question the caller asked, and the value
|
|
// that refused the swap is what its retry needs next.
|
|
OpCompareAndSetMetadata = "compareAndSetMetadata"
|
|
)
|
|
|
|
// specBearerScheme is the name of the document's securityScheme for the bearer
|
|
// token. It is a constant so TestSpecSecurityMatchesRouteTable compares the
|
|
// route table's exemption column against the same string the document uses.
|
|
const specBearerScheme = "bearerToken"
|
|
|
|
// operationCodes is the per-operation problem vocabulary: exactly the codes
|
|
// that operation's handler can produce, and therefore exactly what the spec
|
|
// documents for it. TestSpecStatusCodesMatchHandlerTable asserts set-equality
|
|
// in both directions, so an undocumented emission and an unemittable
|
|
// documented status both fail CI.
|
|
//
|
|
// Two 400 invalid_argument paths are reachable on every route including
|
|
// /healthz — the Host-header middleware, and the unknown-query-parameter
|
|
// refusal every decoder performs — and both are deliberately absent from every
|
|
// row here. They are uniform rules, not per-operation behavior, and the spec
|
|
// documents them once at the document level rather than repeating them on
|
|
// every operation; these rows carry what an operation produces beyond them.
|
|
// Keep the two documents in step: a row here and the document-level prose are
|
|
// the only two places that carve-out exists.
|
|
//
|
|
// The 401 is NOT one of those uniform rules and does appear in the rows below.
|
|
// It is per-operation surface, and the policy is every operation except
|
|
// liveness: auth is enforced in route() for every row whose authExempt column
|
|
// is false, and OpHealth is the only row that sets it, so a probe can answer
|
|
// with no credential. Stating it per-operation rather than once at the document
|
|
// level is what makes TestSpecStatusCodesMatchHandlerTable require the 401s to
|
|
// be documented in the same change as the check that emits them — including for
|
|
// an operation added later, which inherits enforcement the moment it is routed
|
|
// and so must carry CodeUnauthenticated here from its first commit.
|
|
var operationCodes = map[string][]Code{
|
|
// Liveness answers from the process, touches nothing that can fail, and
|
|
// carries no credential: it is the one auth-exempt row of the route table.
|
|
OpHealth: nil,
|
|
// v0 serves a startup snapshot without touching the database, so there is
|
|
// no 503 here. If a later slice makes this a DB-probing readiness
|
|
// endpoint, db_unavailable joins this row and the spec in the same change.
|
|
OpGetContext: {CodeUnauthenticated, CodeInternal},
|
|
OpListReadyWork: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
OpListIssues: {CodeInvalidArgument, CodeInvalidCursor, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The 400 is this operation's own, the getStats precedent: a malformed
|
|
// `include_comments` or `include_dependents` is a bad value on a parameter
|
|
// this server knows, not the document-level unknown-key rule this table
|
|
// omits.
|
|
OpGetIssue: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No 400 of its own: the operation takes no parameters, so the only
|
|
// invalid_argument it can raise is the document-level unknown-query-key
|
|
// rule this table deliberately omits.
|
|
OpListSettings: {CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No 404: a key nothing stored and a key stored as the empty string are one
|
|
// answer on this surface, so the only refusal a key can earn is the 400
|
|
// that says it was not a key.
|
|
OpGetSetting: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// getSetting's row PLUS the ROLE's refusals, which is the whole difference
|
|
// between the read half and the write half. Two of the role's three are
|
|
// reachable — `issue_prefix` in either spelling, and a `status.custom` that
|
|
// does not parse — and both arrive as the 400 they are, on the sentinel,
|
|
// through the shared ErrValidation line every role-backed handler here draws.
|
|
//
|
|
// NO 404 and no conflict code, both inherited from the read beside it. A key
|
|
// nothing stored and a key stored empty are one answer on this plane, so
|
|
// there is no resource this write can fail to address; and the write is an
|
|
// unconditional replace, so there is no state for it to lose a race against.
|
|
// A `revision` guard would need a row version this plane does not hold.
|
|
OpSetSetting: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// getSetting's row EXACTLY, and that is this operation's whole error story:
|
|
// it takes the same parameter, judges it the same way, and reaches a role
|
|
// whose only refusal — an empty key — the path bound has already made
|
|
// unreachable. Its 400 is therefore entirely the transport's.
|
|
//
|
|
// THE ABSENT 404 IS THE DIVERGENCE FROM forgetMemory, which addresses the
|
|
// same shape of resource with the same method and answers 404 for a key it
|
|
// held nothing under. That role reports Found; this one cannot — the storage
|
|
// seam discards the affected-row count on all three legs — so a 404 here
|
|
// would publish a distinction this server would have to invent.
|
|
OpUnsetSetting: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The 400 here is this operation's own, not the document-level
|
|
// unknown-parameter rule: a malformed `skip_blocked`, and the EMPTY
|
|
// `assignee` the document refuses rather than answering with the rows that
|
|
// have no assignee.
|
|
OpGetStats: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The cycle sweep takes no parameters at all, so it has no 400 of its own:
|
|
// the two uniform ones above are the whole of its invalid-argument story.
|
|
OpListDependencyCycles: {CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No not_found here, deliberately: an id that names nothing is reported in
|
|
// the response's `missing` member, so a batch keeps the answers for the ids
|
|
// that were found. A 404 would discard them.
|
|
OpListDependencies: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The stored-edge read's vocabulary exactly, and no not_found for its
|
|
// reason: an id that names nothing is reported on its own anchor, so a
|
|
// batch keeps the answers for the ids that were found. The role has no
|
|
// ErrNotFound at all, which its doc states.
|
|
//
|
|
// Its 400 is BOTH the transport's and the ROLE's, which is what separates
|
|
// this row from GET /v0/beads/issues:count beside it. That operation
|
|
// refuses its one enum at the edge and reaches no role refusal; here
|
|
// ValidateEdgeCountRequest runs inside the single shared body — the role
|
|
// has one body on all three legs, so the check could not belong to an
|
|
// accessor — and four of its refusals are reachable over the wire: a
|
|
// missing or unrecognized direction, a status beside direction=out, an
|
|
// empty id, and a dependency type no edge could carry. Each reaches the
|
|
// client as the 400 it is, on the sentinel, with the parameter named in the
|
|
// validator's own order.
|
|
OpCountDependencyEdges: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No not_found, for OpListDependencies' reason restated about issues rather
|
|
// than edges: an id naming no stored row is reported in `missing`, not
|
|
// refused, so this operation's only 400s are the role's own — an oversized
|
|
// `ids` (*issueops.TooManyIDsError) and a blank entry. An empty `ids` is
|
|
// legal and answers with an empty result, so it earns no refusal at all.
|
|
OpBatchGetIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No not_found and no conflict: an id that is not a stale lease is left out
|
|
// of `reclaimed` rather than refused, and the sweep guards nothing a caller
|
|
// named a version of. Its only 400s are the role's own refusals and the
|
|
// handler's shape checks.
|
|
OpReclaimIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// Two 409s, and they answer different questions. `already_claimed` is a
|
|
// live FOREIGN holder, in the claim's own shape: `assignee` names the
|
|
// holder and `issue_status` the status, both from the refusing
|
|
// transaction's *issueops.LeaseConflictError. `lease_not_held` is the
|
|
// actor holding no live claim at all, with `issue_status`. No
|
|
// precondition_failed: the fence is the holder, not a revision.
|
|
OpHeartbeatIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodeAlreadyClaimed, CodeLeaseNotHeld,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// The same vocabulary as the stored-edge read beside it, and no not_found
|
|
// for a stronger version of the same reason: this operation probes no id's
|
|
// existence at all, so there is nothing it could 404 on.
|
|
OpListBlockingAnnotations: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// getDependencyTree's row exactly, and for its reasons: ONE anchor, so a
|
|
// miss is the 404 it is rather than a per-anchor flag — there is no other
|
|
// answer to preserve by reporting it in the body, and an empty neighbor
|
|
// list is the common case, so a typo answered with one would never surface.
|
|
//
|
|
// Its 400 is BOTH the transport's and the ROLE's. The transport owns the
|
|
// unknown key and the repeated single-valued parameter; ValidateRelatedRequest
|
|
// owns the two that are about this request's MEANING — a missing or
|
|
// unrecognized direction, and a dependency type no edge could carry — and each
|
|
// reaches the client as the 400 it is, on the sentinel, with the parameter
|
|
// named. The validator's third refusal, an empty anchor id, is unreachable
|
|
// here: the id is a PATH segment this handler bounds before the role is
|
|
// asked, and an id that fails that bound is the 404 a real miss gets.
|
|
OpListRelatedIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The 404 is the difference from the row above: this operation has ONE
|
|
// anchor, so there is no other answer to preserve by reporting the miss in
|
|
// the body. Its 400 is its own — an empty root, a direction outside the
|
|
// closed set, a non-positive max_depth — all three the ROLE's ErrValidation
|
|
// reaching the wire.
|
|
OpGetDependencyTree: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The same vocabulary as the listing it sizes: it takes the same filters
|
|
// and can refuse them the same way. limit=0's mode-dependent refusal has no
|
|
// analog here because there is no limit to pass.
|
|
OpCountReadyWork: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The blocked listing has no page, so no cursor or unlimited-read refusal,
|
|
// and no 404: nothing blocked is an empty list. Its 400s are the
|
|
// transport's (an unknown parameter, a repeated `parent`).
|
|
OpListBlockedIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// A cardinality has no page, so there is no cursor or unlimited-read
|
|
// refusal. It has no 404 either: a predicate matching nothing is 0.
|
|
//
|
|
// Its 400s come from both the transport and the ROLE. The transport refuses
|
|
// malformed values, repeated single-valued parameters and a `group_by`
|
|
// outside the closed set. countGroupOf stops that last case at the edge.
|
|
// The role has three reachable refusals, all from BuildCountFilter: an
|
|
// invalid metadata key (`metadata_field` or `has_metadata_key`), an
|
|
// unrecognized `exclude_status` name, and `parent` set together with
|
|
// `no_parent` (named `no_parent`). The last two carry ErrValidation; the
|
|
// metadata-key refusal does not, being a plain error from
|
|
// ValidateMetadataFilters, which the list and ready builders share.
|
|
// failReadErr classifies all three through invalidFilterParam by message
|
|
// prefix, not by sentinel, as a 400 naming the parameter each came from.
|
|
// An unrecognized `status` or `type` is not a refusal; the role promises
|
|
// it matches nothing and answers 0. Nor is an unrecognized `exclude_type`,
|
|
// which excludes nothing.
|
|
OpCountIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The listing's vocabulary minus the cursor: this operation has none, so
|
|
// invalid_cursor cannot arise. An unparseable EXPRESSION is an
|
|
// invalid_argument on `q` rather than a code of its own — a client's
|
|
// recovery is the same as for any other malformed parameter value.
|
|
OpQueryIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The 400 here is the widest on this surface, and most of it is not this
|
|
// handler's: the unfiltered durable sweep, the unrecognized tier and the
|
|
// malformed glob are all the ROLE's ErrValidation reaching the wire through
|
|
// failSweepErr. No 404 — this operation names no id — and no 409: a bead
|
|
// another sweep already took is simply not in the set.
|
|
OpSweepIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// CodeNotFound is the one this operation has and the sweep does not: a
|
|
// sweep describes a set that can legitimately be empty, while a delete
|
|
// names beads and an id that resolves to nothing is a caller mistake.
|
|
//
|
|
// precondition_failed is `expected_version`'s, and it is the 409 form for
|
|
// the reason that code documents: a miss refuses the whole request and
|
|
// leaves nothing to report but the refusal. It ranks BELOW the 404 — a
|
|
// request that named no row has nothing to be stale about — and ABOVE the
|
|
// dependents refusal, which is the role's own order and is what makes the
|
|
// wire's answer the same one `bd delete` gives.
|
|
//
|
|
// The ARITY refusal is a 400 rather than a second conflict: a token beside
|
|
// two distinct ids is a malformed request, not a statement about state.
|
|
OpDeleteIssues: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodePreconditionFailed,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
OpClaimIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeAlreadyClaimed, CodeNotClaimable,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// The NARROWEST write vocabulary on this surface, and the narrowness is the
|
|
// contract rather than an oversight. A problem document from this operation
|
|
// means the batch never ran; every refusal an ITEM can earn — not_found for
|
|
// an id naming no row, not_closable for close policy, template_read_only,
|
|
// issue_pinned and not_assignee for the close guards — travels in that
|
|
// item's outcome inside a 200. A 404 here would say the operation went to
|
|
// the wrong place, and a 409 would say the whole batch was refused, and
|
|
// neither is ever true of a per-item refusal.
|
|
OpBatchCloseIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// NO 409 AND NO 404, and both absences are this operation's contract rather
|
|
// than an omission. There is no id to have missed, and a row a racing agent
|
|
// took is simply not in the set this claim scanned — the role walks past it
|
|
// inside the transaction, which is the whole reason the operation exists.
|
|
// An empty ready front is a 200 with the row absent, not a refusal.
|
|
//
|
|
// The 400 is the ready listing's filter vocabulary plus this operation's own
|
|
// `limit` refusal plus the body rules, and the ROLE's ErrValidation behind
|
|
// them, which is defensively unreachable.
|
|
OpClaimNextIssue: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// THREE conflict codes, and only one of them is new. `already_claimed` is
|
|
// the ownership fence, inherited from updateIssue's assignee arm: the same
|
|
// situation — a live foreign owner refusing a write — with the same two
|
|
// bypasses, spelled `force` and `expected_assignee` here. `precondition_failed`
|
|
// is the `expected_assignee` guard, inherited from the same operation and
|
|
// carrying the same members for the same reason: the request's expectation,
|
|
// never an observation.
|
|
//
|
|
// `not_releasable` is the mint, and its own doc carries the analysis.
|
|
//
|
|
// The 404 is the path id's, on the terms updateIssue states. There is no
|
|
// `not_claimable` here even though the claim's status refusal is the nearest
|
|
// neighbor — see CodeNotReleasable for why that reuse was refused.
|
|
OpReleaseIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodeAlreadyClaimed, CodeNotReleasable, CodePreconditionFailed,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// Several 409s, and they answer different questions with `code` as the
|
|
// only discriminator a client needs.
|
|
//
|
|
// not_closable is close POLICY: an unforced close refused for open children
|
|
// or for a live blocker. The idempotent re-close is a 200 carrying
|
|
// `already_closed`, the claim's answer to the same question.
|
|
//
|
|
// template_read_only, issue_pinned and not_assignee are the CLOSE GUARDS
|
|
// the role applies before policy, in that order: a template (no bypass), a
|
|
// pin and closing work somebody else holds (both bypassed by `force`).
|
|
// There is no already_claimed: that code is a lost claim, and not_assignee
|
|
// carries the holder in `assignee` itself.
|
|
//
|
|
// precondition_failed is `expected_version`'s, in the 409 form for the
|
|
// reason that code documents, and it is CHECKED FIRST — before policy and
|
|
// before the idempotent re-close, which is the role's own order
|
|
// (issueops.Lifecycle.Close). `force` bypasses policy and never it: the two
|
|
// members make unrelated claims.
|
|
OpCloseIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeNotClosable, CodePreconditionFailed,
|
|
CodeTemplateReadOnly, CodeIssuePinned, CodeNotAssignee,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// No conflict code: a ready step another actor holds, or one moved out of
|
|
// a claimable status, is skipped for the next one rather than refused —
|
|
// the role's own rule — so the only 404 is the path id's.
|
|
OpAdvanceMolecule: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// ONE 409, and it is a PRECONDITION rather than a policy. Close has a policy
|
|
// guard — open children, a live blocker — and reopen is the direction that
|
|
// takes an issue OUT of the done category rather than putting it in, so
|
|
// there is no state of the graph that can refuse it: not_closable is absent
|
|
// here and always will be. What `expected_version` refuses is the request's
|
|
// own premise, which every write can have wrong. The idempotent case is
|
|
// still a 200 carrying `already_open`, unless a guard came with it.
|
|
OpReopenIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodePreconditionFailed,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// FOUR conflict codes, and the three members that publish them are exactly
|
|
// the ones this row used to say would drag them in: `status` brought close
|
|
// policy, `assignee` the fence, `parent_id` the graph vocabulary. Publishing
|
|
// the members is what made the codes reachable, and every one of them is
|
|
// inherited from an operation that already has it — this is applyBatch's row
|
|
// for a single update item, minus `already_exists`, which needs a create.
|
|
//
|
|
// precondition_failed is the guard trio's, and it is the 409 form rather
|
|
// than compareAndSetMetadata's 200 for the reason that code documents: a
|
|
// miss here refuses the whole write and leaves nothing to report but the
|
|
// refusal, where a lost metadata swap is a retry loop's ordinary iteration
|
|
// carrying the value it needs next.
|
|
//
|
|
// The 404 is still the PATH id only. A `patch.parent_id` that names nothing
|
|
// is an edge endpoint and stays a 400, conforming to addDependencies.
|
|
//
|
|
// The 400 is the body vocabulary plus the ROLE's ErrValidation — a
|
|
// workspace-vocabulary issue_type or status, a metadata key the query layer
|
|
// could not spell, a field-length refusal that slipped the edge check —
|
|
// through failUpdate.
|
|
//
|
|
// not_claimable arrived with `claim`, beside the already_claimed it shares
|
|
// with the fence: a refused claim answers as claimIssue does.
|
|
//
|
|
// template_read_only is the role refusing an update of a template:
|
|
// templates are read-only, no force flag waives it, and only
|
|
// `allow_template` stands it down.
|
|
OpUpdateIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodePreconditionFailed, CodeNotClosable, CodeAlreadyClaimed, CodeNotesOverwrite,
|
|
CodeTemplateReadOnly,
|
|
CodeNotClaimable, CodeDependencyCycle, CodeDependencyExists,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// No not_found. The role refuses an edge whose target names nothing, and
|
|
// that refusal is about the REQUEST BODY the client sent, not about a
|
|
// resource this operation was asked to address — there is no id in the path
|
|
// to have missed. A 404 here would tell a client its request went to the
|
|
// wrong place.
|
|
//
|
|
// No conflict code either: this operation publishes no `id` member, so no
|
|
// item can collide with a stored row and the role's ErrAlreadyExists is
|
|
// unreachable from the wire.
|
|
OpBatchCreateIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The batch's row plus the two codes its narrower vocabulary cannot earn,
|
|
// and both additions are members rather than judgement calls.
|
|
//
|
|
// already_exists arrives with `id`: that operation publishes none, so its
|
|
// items can never collide with a stored row and the role's ErrAlreadyExists
|
|
// is unreachable from its wire. Here it is reachable and it is a 409 for
|
|
// CodeNotClosable's reason — the body is well-formed and STATE refuses it.
|
|
//
|
|
// dependency_cycle arrives with `parent_id` and `dependencies[].reverse`:
|
|
// the first places the new row inside a hierarchy the caller cannot see, so
|
|
// a blocking edge against its own ancestor is refusable, and the second
|
|
// writes an edge INTO the id being minted, which is the only way a create
|
|
// can close a scheduling cycle at all. It is addDependencies' 409 unchanged,
|
|
// including the hierarchy discriminator.
|
|
//
|
|
// NO 404 and no dependency_exists. A target that names nothing is a
|
|
// statement about the request body rather than a resource this operation was
|
|
// asked to address — batchCreateIssues' argument, and there is no id in this
|
|
// path to have missed. And the only type conflict a create can raise is
|
|
// between two edges of the SAME request, which is a malformed body: no
|
|
// stored edge can name a pair whose endpoint is an id this request is
|
|
// minting.
|
|
OpCreateIssue: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeAlreadyExists, CodeDependencyCycle,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// The widest row here, and every code on it is inherited from an operation
|
|
// that already has it: this one performs the lifecycle's writes, the claim's
|
|
// assignee transfer and the graph's edge assertions inside one transaction,
|
|
// so it can earn any refusal any of them can.
|
|
//
|
|
// THERE IS A CONFLICT CODE HERE, unlike the metadata compare-and-set, and
|
|
// that is the whole difference between the two contracts rather than a
|
|
// difference of taste. A lost compare-and-set is that operation's ORDINARY
|
|
// path — a retry loop is its designed caller — so a 409 there would put the
|
|
// normal iteration in the error channel and force the value the loop needs
|
|
// next into a problem member. Here a precondition miss refuses every item in
|
|
// the request, so there is no partial outcome to report on a 200 and nothing
|
|
// for a client to do with one: the refusal IS the answer, and it belongs
|
|
// where every other "the state says no" on this surface lives.
|
|
//
|
|
// The 404 is the delete's, not the batch create's: `update` and `close`
|
|
// items NAME rows this request acts on, so a target that resolves to nothing
|
|
// is a resource the request failed to address. An EDGE endpoint stays a 400,
|
|
// conforming to addDependencies — nothing in that refusal is about a
|
|
// resource this operation was asked to address.
|
|
OpApplyBatch: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodePreconditionFailed, CodeNotClosable, CodeAlreadyClaimed, CodeNotesOverwrite, CodeAlreadyExists,
|
|
CodeTemplateReadOnly, CodeIssuePinned, CodeNotAssignee,
|
|
CodeDependencyCycle, CodeDependencyExists,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// getDependencyTree's row, and it is the same shape for the same two
|
|
// reasons: ONE anchor, so an id that names nothing is the 404 it is rather
|
|
// than a per-item flag, and a 400 that is BOTH the transport's and the
|
|
// ROLE's.
|
|
//
|
|
// NO CONFLICT CODE, and the absence is the operation's contract. A thread is
|
|
// append-only and this write touches no field of the issue, so there is no
|
|
// row state a guard could be stale about and no concurrent comment for this
|
|
// one to collide with — which is also why there is no `expected_version`
|
|
// member to earn a precondition_failed with.
|
|
//
|
|
// Of the role's three ErrValidation refusals exactly ONE is reachable here.
|
|
// An empty author is refused at the edge under `actor`'s rules, which are
|
|
// strictly stronger, and an empty issue id cannot arrive at all — a ServeMux
|
|
// wildcard does not match an empty segment, and an id that fails the path
|
|
// bound is the 404 a real miss gets. So the blank body is the whole of what
|
|
// the role can refuse over this wire, which is why failAddComment names one
|
|
// parameter rather than re-asking the validator's questions.
|
|
OpAddComment: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// No 404 and no conflict code: this is an UPSERT with a server-derivable
|
|
// key, so there is no resource it can fail to address and no row it can
|
|
// collide with. Its 400 is the body vocabulary plus the ROLE's two
|
|
// refusals — empty content, and content no key can be derived from.
|
|
OpRememberMemory: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// THE 404 IS THE DIVERGENCE, and it is deliberate. OpGetSetting has none
|
|
// because on that plane an absent key and a key stored empty are one answer
|
|
// the CLI itself prints identically, so a 404 would publish an invented
|
|
// distinction. Here the CLI already distinguishes a miss — `bd recall` has
|
|
// an exit-code contract for it — and the role answers Found rather than a
|
|
// value, so the 404 reports a distinction that exists. Found is row
|
|
// existence: a row stored as the empty string is a 200 with an empty value,
|
|
// and only an absent row is the 404, which the document states.
|
|
OpGetMemory: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The read's vocabulary exactly, because the two operations address the same
|
|
// resource the same way and this one's Found false is the same answer: a key
|
|
// nothing stored is a 404 and nothing was removed. No 409 — a memory another
|
|
// caller already forgot is simply not there, which is what the 404 says.
|
|
OpForgetMemory: {CodeInvalidArgument, CodeUnauthenticated, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The 400 here IS this operation's own, unlike listSettings' absent row: it
|
|
// has one parameter, and a repeated `q` is refused rather than resolved to
|
|
// one of its values. No 404 — a search matching nothing is an empty page,
|
|
// because a question about a set has an answer even when the set is empty.
|
|
OpListMemories: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The two journal codes are this operation's alone and neither has a
|
|
// precedent elsewhere on this surface, because no other operation reads a
|
|
// LOG. The 400 is its own too: `since` is required, and a negative or
|
|
// unparseable checkpoint is refused rather than treated as zero — `seq > -5`
|
|
// would quietly serve the whole journal as if it were a legitimate resume,
|
|
// which is the same refusal `bd events tail --since` makes.
|
|
//
|
|
// No 404. A checkpoint at or past the head is a caught-up 200 with an empty
|
|
// list, because "nothing new yet" is an answer about a log rather than a
|
|
// missing resource, and a poller that got a 404 for being up to date would
|
|
// have to treat the surface's miss vocabulary as a normal steady state.
|
|
OpListEvents: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeEventsJournalDisabled, CodeEventsJournalTruncated,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// THE PAGED READ'S VOCABULARY PLUS ONE, and the shared part is the point:
|
|
// every connect-time refusal a poller can earn, a stream earns identically,
|
|
// because the stream only opens once the same first read has succeeded. The
|
|
// 410 in particular is a real 410 here and not an in-band event — that
|
|
// mapping applies to a prune that races an ALREADY OPEN stream, where no
|
|
// status is left to send.
|
|
//
|
|
// events_watch_saturated is the addition, and it is the only code on this
|
|
// surface that describes a limit on connections rather than on data. Its 503
|
|
// therefore documents three codes where every other operation's documents
|
|
// two.
|
|
OpWatchEvents: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeEventsJournalDisabled, CodeEventsJournalTruncated,
|
|
CodeEventsWatchSaturated, CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
// NO 404, for a stronger version of the batch create's reason: an edge that
|
|
// is not there is `removed: false`, and an endpoint id that names nothing
|
|
// holds no edge either, so this operation probes no id's existence and has
|
|
// nothing it could report a miss on — listBlockingAnnotations' argument,
|
|
// applied to a write. No conflict code either: the removal is idempotent, so
|
|
// another caller having got there first is a success rather than a collision.
|
|
// NO CONFLICT CODE, and the absence is this operation's whole posture. A
|
|
// lost compare-and-set is a 200 carrying `swapped: false` and the current
|
|
// value, because a retry loop is the DESIGNED caller and a 409 would put its
|
|
// ordinary path in the error channel — and would have to smuggle the value
|
|
// that loop needs next into a problem extension member. The 404 is here for
|
|
// the id, which is the one refusal a caller cannot converge on.
|
|
OpCompareAndSetMetadata: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeNotFound,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
OpRemoveDependency: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
// The two conflict codes are this operation's alone, and both say the same
|
|
// kind of thing: the request is fine as a request and the GRAPH refuses it,
|
|
// which the caller cannot know without reading state it does not have. That
|
|
// is the claim's not_claimable situation and it gets the claim's answer, a
|
|
// typed 409 whose extension members are read inside the refusing
|
|
// transaction. The delete's 400-for-a-graph-refusal precedent does not
|
|
// apply: that one is about request COMPLETENESS — send cascade or force —
|
|
// and neither of these has a force to send.
|
|
//
|
|
// No 404: an endpoint that names nothing is a refusal of the request BODY,
|
|
// so it joins the 400 with every other body refusal (batchCreateIssues'
|
|
// argument). Nothing was written in any of these cases.
|
|
OpAddDependencies: {
|
|
CodeInvalidArgument, CodeUnauthenticated, CodeDependencyCycle, CodeDependencyExists,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
}
|
|
|
|
// Result is a problem response ready to be written: the envelope plus the
|
|
// transport-level Retry-After the code implies.
|
|
type Result struct {
|
|
Problem apigen.Problem
|
|
// RetryAfterSeconds is written as the Retry-After header when positive.
|
|
RetryAfterSeconds int
|
|
}
|
|
|
|
// WithAssignee attaches the `assignee` extension member (the current holder of
|
|
// a claimed issue). Populate it from a read in the claim's own transaction —
|
|
// never by parsing the sentinel's message fragments.
|
|
func (r Result) WithAssignee(assignee string) Result {
|
|
r.Problem.Assignee = &assignee
|
|
return r
|
|
}
|
|
|
|
// WithIssueStatus attaches the `issue_status` extension member (the issue's
|
|
// status at the moment of refusal). Same rule as WithAssignee.
|
|
func (r Result) WithIssueStatus(status string) Result {
|
|
r.Problem.IssueStatus = &status
|
|
return r
|
|
}
|
|
|
|
// WithReason attaches the `reason` member to a refusal other than the 400
|
|
// (InvalidArgument sets its own). Same rule as WithAssignee: it comes from the
|
|
// typed error's own field, never from parsing the refusal's prose.
|
|
func (r Result) WithReason(reason Reason) Result {
|
|
v := string(reason)
|
|
r.Problem.Reason = &v
|
|
return r
|
|
}
|
|
|
|
// WithOpenChildren attaches the `open_children` extension member (how many open
|
|
// children the transaction that refused a close observed). Same rule as
|
|
// WithAssignee: it comes from the typed error's own field, read inside that
|
|
// transaction, never from parsing the refusal's prose.
|
|
//
|
|
// Its PRESENCE is load-bearing. It is attached for the open-children refusal
|
|
// and withheld for the live-blocker one, which is how a client tells the two
|
|
// apart without reading `detail`.
|
|
func (r Result) WithOpenChildren(n int) Result {
|
|
r.Problem.OpenChildren = &n
|
|
return r
|
|
}
|
|
|
|
// Blocker kinds on the wire, the `kind` member of apigen.Blocker.
|
|
const (
|
|
blockerKindLocal = "local"
|
|
blockerKindExternal = "external"
|
|
)
|
|
|
|
// closeBlocked builds the live-blocker `not_closable` for one refusal site.
|
|
//
|
|
// subject and hint are the site's own words ("… closes a blocked issue",
|
|
// "clear the blocker, or send …"). When err carries the typed
|
|
// *issueops.BlockedError the refusing check filled, the subject is replaced by
|
|
// that error's own sentence — "cannot close blocked issue: <id> is blocked by
|
|
// [<blockers>]", byte-identical to what the direct CLI prints before its
|
|
// --force hint — and the list travels typed in the `blockers` member. Both are
|
|
// built from the typed fields, never parsed out of a message: an error that
|
|
// only MENTIONS blockers in prose keeps the generic detail and no member.
|
|
func closeBlocked(err error, subject, hint string) (string, *[]apigen.Blocker) {
|
|
blocked := closeBlockedError(err)
|
|
if blocked == nil {
|
|
return subject + "; " + hint, nil
|
|
}
|
|
return blocked.Error() + "; " + hint, wireBlockers(blocked.Blockers)
|
|
}
|
|
|
|
// closeBlockedError returns the typed close-policy refusal err carries, or nil
|
|
// when it carries none or names no blockers. The wrapped sentinel is checked
|
|
// too, so a BlockedError raised for some other refusal is never reported as a
|
|
// close's blockers.
|
|
func closeBlockedError(err error) *issueops.BlockedError {
|
|
var blocked *issueops.BlockedError
|
|
if !errors.As(err, &blocked) || !errors.Is(blocked.Err, issueops.ErrCloseBlocked) || len(blocked.Blockers) == 0 {
|
|
return nil
|
|
}
|
|
return blocked
|
|
}
|
|
|
|
// wireBlockers projects typed blockers onto the `blockers` member, in the
|
|
// order the refusing check reported them. `type` is omitted, not sent empty,
|
|
// when the refusal did not report the edge type.
|
|
func wireBlockers(blockers []issueops.Blocker) *[]apigen.Blocker {
|
|
out := make([]apigen.Blocker, 0, len(blockers))
|
|
for _, blocker := range blockers {
|
|
wire := apigen.Blocker{Id: blocker.ID, Kind: blockerKindLocal}
|
|
if blocker.External() {
|
|
wire.Kind = blockerKindExternal
|
|
}
|
|
if blocker.Type != "" {
|
|
wire.Type = ptrTo(string(blocker.Type))
|
|
}
|
|
out = append(out, wire)
|
|
}
|
|
return &out
|
|
}
|
|
|
|
// closeBlockedResult is closeBlocked as a problem document: the live-blocker
|
|
// `not_closable` with its `blockers` member when the refusal named them.
|
|
func closeBlockedResult(err error, subject, hint string) Result {
|
|
detail, blockers := closeBlocked(err, subject, hint)
|
|
res := newResult(CodeNotClosable, detail)
|
|
res.Problem.Blockers = blockers
|
|
return res
|
|
}
|
|
|
|
// WithDependencyTypeConflict attaches the two `dependency_exists` extension
|
|
// members: the type the pair already carries and the type the request asked
|
|
// for. Populate them from *issueops.DependencyTypeConflictError's fields — the
|
|
// typed error the role raises inside the transaction that saw the stored edge —
|
|
// never by parsing its message.
|
|
func (r Result) WithDependencyTypeConflict(existing, requested string) Result {
|
|
r.Problem.ExistingType = &existing
|
|
r.Problem.RequestedType = &requested
|
|
return r
|
|
}
|
|
|
|
// WithHierarchyConflict attaches the three extension members that distinguish
|
|
// the HIERARCHY refusal from a plain scheduling cycle inside the one
|
|
// `dependency_cycle` code. Their PRESENCE is the discriminator, and the three
|
|
// together are enough to rebuild
|
|
// *issueops.DependencyHierarchyConflictError whole — BlockerIsAncestor in both
|
|
// polarities included, which is why the boolean travels through a pointer and
|
|
// is emitted when false.
|
|
//
|
|
// They can only come from the refusing transaction, for the reason
|
|
// ClaimConflictError's do and more so: the conflicting hierarchy may exist only
|
|
// inside the batch that was rolled back, so no read after the fact can recover
|
|
// it.
|
|
func (r Result) WithHierarchyConflict(issueID, blockerID string, blockerIsAncestor bool) Result {
|
|
r.Problem.IssueId = &issueID
|
|
r.Problem.BlockerId = &blockerID
|
|
r.Problem.BlockerIsAncestor = &blockerIsAncestor
|
|
return r
|
|
}
|
|
|
|
// WithBatchItem attaches the four extension members that name WHICH item of a
|
|
// batch earned a refusal: its index, its kind, the key it gave itself or the
|
|
// key its target ref named, and the id it had resolved when the refusal
|
|
// happened.
|
|
//
|
|
// They come from *issueops.ItemError's own fields — the typed error the role
|
|
// raises rather than the prose it formats — for the reason every other typed
|
|
// member on this envelope does, and one more that is this operation's alone:
|
|
// the request is all or nothing, so there is no per-item result array for a
|
|
// client to find the offender in. These members are the only place it exists.
|
|
//
|
|
// `item_key` and `item_issue_id` are OMITTED WHEN EMPTY, and both absences mean
|
|
// something. An item that named nothing symbolically has no key; an item
|
|
// refused before its target resolved — a create whose id was never minted, a
|
|
// ref that resolved to nothing — has no id.
|
|
//
|
|
// It is `item_issue_id` rather than `issue_id` deliberately: `issue_id` is
|
|
// already a PRESENCE-DISCRIMINATING member of the `dependency_cycle` hierarchy
|
|
// refusal, and reusing it would make that discriminator fire on a refusal it
|
|
// says nothing about.
|
|
func (r Result) WithBatchItem(index int, kind, key, issueID string) Result {
|
|
r.Problem.ItemIndex = &index
|
|
r.Problem.ItemKind = &kind
|
|
if key != "" {
|
|
r.Problem.ItemKey = &key
|
|
}
|
|
if issueID != "" {
|
|
r.Problem.ItemIssueId = &issueID
|
|
}
|
|
return r
|
|
}
|
|
|
|
// WithDeclaredLater attaches the `declared_later` member, which tells an
|
|
// unresolvable key that IS declared by a later item from one nothing in the
|
|
// request declares at all. The first is an ordering mistake and the second is a
|
|
// typo, and a client fixes them differently.
|
|
//
|
|
// It is emitted in BOTH polarities and never omitted to mean false, for
|
|
// WithHierarchyConflict's reason applied to a 400: an absent member on this
|
|
// operation's 400s means "this refusal was not about a key" and must not be
|
|
// readable as "the key was not declared later".
|
|
func (r Result) WithDeclaredLater(declaredLater bool) Result {
|
|
r.Problem.DeclaredLater = &declaredLater
|
|
return r
|
|
}
|
|
|
|
// WithExpectedVersion attaches the `expected_version` member of a
|
|
// `precondition_failed`: the row version the request guarded on.
|
|
//
|
|
// It is the REQUEST's value rather than a read, which is why there is no
|
|
// `actual_version` beside it here — see PreconditionFailed.
|
|
//
|
|
// The parameter stays int64 because every caller holds the PARSED guard by the
|
|
// time it refuses; the member is a decimal string on the wire, so the echo goes
|
|
// back out through types.RevisionToken and a client comparing it to what it sent
|
|
// gets its own spelling back.
|
|
func (r Result) WithExpectedVersion(expected int64) Result {
|
|
token := types.RevisionToken(expected)
|
|
r.Problem.ExpectedVersion = &token
|
|
return r
|
|
}
|
|
|
|
// WithExpectedStatus attaches the `expected_status` member of a
|
|
// `precondition_failed`. Same source and same rule as WithExpectedVersion.
|
|
func (r Result) WithExpectedStatus(expected string) Result {
|
|
r.Problem.ExpectedStatus = &expected
|
|
return r
|
|
}
|
|
|
|
// WithExpectedAssignee attaches the `expected_assignee` member of a
|
|
// `precondition_failed`. Same source and same rule as WithExpectedVersion.
|
|
func (r Result) WithExpectedAssignee(expected string) Result {
|
|
r.Problem.ExpectedAssignee = &expected
|
|
return r
|
|
}
|
|
|
|
// PreconditionFailed builds the 409 for a compare-and-set guard that missed on
|
|
// an operation where a miss refuses the whole request.
|
|
//
|
|
// The detail says what a client does next rather than what the row held,
|
|
// because on this contract those are different facts: the transaction that saw
|
|
// the mismatch rolled back, so a value read afterwards describes a row the
|
|
// refusal never saw. The role's refusals carry the expectation and not the
|
|
// observation, so `actual_version`, `actual_status` and `actual_assignee` stay
|
|
// absent here — the envelope declares them for an operation whose role can
|
|
// report what it found, and inventing one from a later read would be worse than
|
|
// omitting it.
|
|
func PreconditionFailed() Result {
|
|
return newResult(CodePreconditionFailed,
|
|
"a precondition guard did not match; nothing was written, so re-read the row and recompose the request rather than retrying it")
|
|
}
|
|
|
|
// WithJournalWindow attaches the three `events_journal_truncated` extension
|
|
// members: the checkpoint the reported window begins after, the lowest seq
|
|
// still retained, and the highest seq ever assigned.
|
|
//
|
|
// They come from *storage.EventsJournalTruncatedError's own fields — computed
|
|
// inside the transaction that saw the gap — for the reason every other typed
|
|
// member on this envelope does, and one more: `since` is NOT always the value
|
|
// the caller sent. On an interior hole it is the last seq the server could
|
|
// serve contiguously from the caller's checkpoint, which is strictly the more
|
|
// useful number and cannot be recovered by a client that assumed it was
|
|
// echoing its own input back.
|
|
//
|
|
// All three are emitted together and none is omitted to mean zero: a head of 0
|
|
// is a real journal state (nothing has ever been written), and a client
|
|
// computing `floor - 1` needs the value rather than an absence to interpret.
|
|
func (r Result) WithJournalWindow(since, floor, head int64) Result {
|
|
r.Problem.Since = &since
|
|
r.Problem.Floor = &floor
|
|
r.Problem.Head = &head
|
|
return r
|
|
}
|
|
|
|
// WithRequestID sets the `request_id` member, the correlation id echoed in the
|
|
// request log line. It is what makes a 5xx actionable: the body carries a fixed
|
|
// static detail by design, so the id is the client's only handle on the one log
|
|
// line that has the real error. The document requires it on every problem
|
|
// response, which is why this sets it unconditionally — an id this server
|
|
// failed to mint travels as an empty string rather than as a missing required
|
|
// member.
|
|
func (r Result) WithRequestID(id string) Result {
|
|
r.Problem.RequestId = id
|
|
return r
|
|
}
|
|
|
|
func newResult(code Code, detail string) Result {
|
|
status := code.Status()
|
|
if status == 0 {
|
|
// Unreachable unless a code is added without a status; fail closed
|
|
// rather than emitting a 0 status line.
|
|
status = http.StatusInternalServerError
|
|
code = CodeInternal
|
|
detail = staticDetail[CodeInternal]
|
|
}
|
|
if static, ok := staticDetail[code]; ok {
|
|
// 5xx detail is fixed per code, whatever the caller passed.
|
|
detail = static
|
|
}
|
|
p := apigen.Problem{
|
|
Status: status,
|
|
Title: http.StatusText(status),
|
|
Code: string(code),
|
|
}
|
|
if detail != "" {
|
|
p.Detail = &detail
|
|
}
|
|
return Result{Problem: p}
|
|
}
|
|
|
|
// InvalidArgument builds the 400 for a request the server refuses to
|
|
// interpret. param names the offending query parameter, body member or header;
|
|
// pass "" only when the input has no nameable part (a body that fails to parse
|
|
// at all). detail may quote the caller's own input — it is not server state.
|
|
func InvalidArgument(param string, reason Reason, detail string) Result {
|
|
res := newResult(CodeInvalidArgument, detail)
|
|
if param != "" {
|
|
res.Problem.Param = ¶m
|
|
}
|
|
r := string(reason)
|
|
res.Problem.Reason = &r
|
|
return res
|
|
}
|
|
|
|
// ProjectMismatch builds the 400 for a request whose Bd-Project-Id header names
|
|
// a workspace this server does not serve. got is the id the client stamped; own
|
|
// is this server's own project id, disclosed in the `server_project_id`
|
|
// extension member so a stamped client can tell a wrong-server refusal from a
|
|
// malformed one without parsing `detail`.
|
|
//
|
|
// This is the ONLY refusal on the surface that sets `server_project_id`, and it
|
|
// is raised only after the request has cleared the Host gate (and, in a
|
|
// deployment that adds one, its authentication layer): a request turned away by
|
|
// an earlier gate is answered before the stamp is ever compared, so it never
|
|
// discloses the server's identity. Presence of the member is therefore the
|
|
// signal that this specific check — and nothing earlier — fired.
|
|
func ProjectMismatch(got, own string) Result {
|
|
res := InvalidArgument(ProjectIDHeader, ReasonProjectMismatch,
|
|
"the "+ProjectIDHeader+" header names project "+strconv.Quote(got)+", which this server does not serve")
|
|
res.Problem.ServerProjectId = &own
|
|
return res
|
|
}
|
|
|
|
// WireRevisionUnsupported builds the 400 for a request whose Bd-Wire-Revision
|
|
// header names a revision below this server's own
|
|
// ContextResponse.min_client_wire_revision. got is the revision the client
|
|
// declared; min is this server's floor, disclosed in the `min_wire_revision`
|
|
// extension member for the same reason ProjectMismatch discloses
|
|
// `server_project_id`: so a client that already knows it declared a revision
|
|
// can tell exactly how far behind it is without re-deriving the number from
|
|
// `bd_version`. current and bdVersion are this server's own
|
|
// ContextResponse.wire_revision and ContextResponse.bd_version, disclosed in
|
|
// the `wire_revision` and `bd_version` extension members so a client logging
|
|
// or reporting the refusal has the server's full version story without a
|
|
// second request to GET /v0/beads/context (review: "include the server's
|
|
// current wire_revision and bd_version in the refusal problem body").
|
|
//
|
|
// This is the ONLY refusal on the surface that sets `min_wire_revision`,
|
|
// `wire_revision` and `bd_version`, and — unlike ProjectMismatch, which is
|
|
// exempt on the identity handshake because that is where a client LEARNS the
|
|
// id it must stamp with — it is raised on GET /v0/beads/context too: a client
|
|
// that already knows the revision it was built for gains nothing from being
|
|
// served a body it has already said it cannot decode, and loses the chance to
|
|
// fail before acting on it.
|
|
func WireRevisionUnsupported(got, min, current int, bdVersion string) Result {
|
|
res := InvalidArgument(WireRevisionHeader, ReasonWireRevisionUnsupported,
|
|
"the "+WireRevisionHeader+" header names revision "+strconv.Itoa(got)+
|
|
", which is below the "+strconv.Itoa(min)+" this server still answers correctly")
|
|
res.Problem.MinWireRevision = &min
|
|
res.Problem.WireRevision = ¤t
|
|
res.Problem.BdVersion = &bdVersion
|
|
return res
|
|
}
|
|
|
|
// InvalidCursor builds the 400 for a cursor this server did not issue, cannot
|
|
// decode, or issued under a different internal version.
|
|
func InvalidCursor() Result {
|
|
return newResult(CodeInvalidCursor, "cursor is not valid for this server; restart paging without it")
|
|
}
|
|
|
|
// NotFound builds the 404 for an id this server cannot resolve. It is one
|
|
// function rather than a literal per site so that a handler which decides a
|
|
// miss WITHOUT reading storage — an id no row could hold — is indistinguishable
|
|
// on the wire from one that read and missed. A client that could tell them
|
|
// apart would be probing which ids are well-formed.
|
|
func NotFound() Result {
|
|
return newResult(CodeNotFound, "no issue or wisp with that id")
|
|
}
|
|
|
|
// EventsJournalDisabled builds the 409 for a workspace whose journal is off.
|
|
//
|
|
// The detail names the setting rather than describing the state, because the
|
|
// recovery is entirely on the SERVER side — a client can do nothing about it —
|
|
// and the human reading this response is the operator who has to go turn it on.
|
|
func EventsJournalDisabled() Result {
|
|
return newResult(CodeEventsJournalDisabled,
|
|
"the durable events journal is not enabled on this workspace; set `events-journal true` and restart the server")
|
|
}
|
|
|
|
// EventsJournalTruncated builds the 410 for a checkpoint below the retained
|
|
// window, carrying the window the server can still serve.
|
|
//
|
|
// The detail is the storage error's OWN sentence, which is the one `bd events
|
|
// tail` prints. A consumer that reads both surfaces sees one description of one
|
|
// condition, and this is a 4xx, so reflecting the server's own state here is
|
|
// within what staticDetail allows.
|
|
func EventsJournalTruncated(err *storage.EventsJournalTruncatedError) Result {
|
|
return newResult(CodeEventsJournalTruncated, err.Error()).
|
|
WithJournalWindow(err.Since, err.Floor, err.Head)
|
|
}
|
|
|
|
// EventsWatchSaturated builds the 503 for a stream this server will not hold.
|
|
//
|
|
// The detail names the alternative rather than the limit, because unlike every
|
|
// other 503 here this one has a recovery that is not "wait": the paged read
|
|
// answers the same records from the same checkpoint and is not capped this way.
|
|
func EventsWatchSaturated() Result {
|
|
res := newResult(CodeEventsWatchSaturated,
|
|
"this server is already holding as many journal streams as it will; retry later, or read the same records from the same checkpoint with GET /v0/beads/events")
|
|
res.RetryAfterSeconds = retryAfterWatchSaturation
|
|
return res
|
|
}
|
|
|
|
// MemoryNotFound builds the 404 for a key this workspace holds no memory under.
|
|
//
|
|
// A separate constructor rather than a detail argument on NotFound, because the
|
|
// two say different things: that one is about the issue id space, and reusing
|
|
// its sentence here would tell a client its memory key was an issue id. It is
|
|
// only ever the answer for an absent row: a row stored as the empty string is
|
|
// found, and the read answers it with a 200.
|
|
func MemoryNotFound() Result {
|
|
return newResult(CodeNotFound, "this workspace holds no memory under that key")
|
|
}
|
|
|
|
// ClassifyError maps an error from the storage seam onto the wire. The caller
|
|
// is responsible for logging err: everything mapped to a 5xx deliberately
|
|
// drops the error text on the floor (see staticDetail).
|
|
//
|
|
// ErrVersionMismatch — AND EVERY OTHER COMPARE-AND-SET SENTINEL — IS
|
|
// DELIBERATELY ABSENT FROM THIS FUNCTION, because the 409 it earns cannot be
|
|
// built from the error alone: `precondition_failed` echoes the value the
|
|
// REQUEST guarded on, and this function is handed an error and nothing else.
|
|
// So an operation that publishes `expected_version` (or `expected_status`, or
|
|
// `expected_assignee`) MUST match the sentinel TYPED in its own failure path,
|
|
// before anything reaches failErr — updateIssue, closeIssue, reopenIssue,
|
|
// deleteIssues, releaseIssue and applyBatch each do. A handler that forgets is
|
|
// not answering a worse 4xx: neither storage leg wraps these in ErrValidation,
|
|
// so the miss falls through the default arm below and every guard failure on
|
|
// that operation is a GENERIC 500. Mutation-verified on the single-issue
|
|
// handlers.
|
|
//
|
|
// THE RULE IS WRITTEN HERE BECAUSE SIX HANDLERS FOUND IT SEPARATELY. failUpdate
|
|
// worked it out, failRelease worked it out again and called it "failUpdate's
|
|
// hazard, in a sharper form", and the guard slice worked it out three more
|
|
// times. Six independent discoveries of one fact are a fact nobody recorded
|
|
// where the seventh author would look — which is here, since a handler author
|
|
// asking "does the shared mapping cover my sentinel?" reads this function and
|
|
// finds no row.
|
|
func ClassifyError(err error) Result {
|
|
// The one row that carries data out of the error rather than only a code.
|
|
// It lives HERE, in the shared mapping, rather than in the events handler:
|
|
// the journal read is reached from two database sources through two
|
|
// different plumbings, and a mapping a handler applied itself would be one
|
|
// `if` away from a pruned-past checkpoint arriving as a generic 500 on
|
|
// whichever arm forgot it.
|
|
var truncated *storage.EventsJournalTruncatedError
|
|
var notAssignee *issueops.CloseNotAssigneeError
|
|
|
|
switch {
|
|
case err == nil:
|
|
return newResult(CodeInternal, "")
|
|
|
|
case errors.As(err, &truncated):
|
|
return EventsJournalTruncated(truncated)
|
|
|
|
// Not-found normalization belongs in the shared read path, which folds the
|
|
// two miss shapes (a wrapped sql.ErrNoRows, and a nil issue with a nil
|
|
// error) into storage.ErrNotFound. The bare sql.ErrNoRows row below is
|
|
// defense in depth for a path that has not been normalized yet: a missing
|
|
// issue must never surface as a 500. The converse mistake — treating any
|
|
// error as a miss — stays closed, because only these two sentinels reach
|
|
// 404 and everything else falls through to 500.
|
|
case errors.Is(err, storage.ErrNotFound), errors.Is(err, sql.ErrNoRows):
|
|
return NotFound()
|
|
|
|
case errors.Is(err, storage.ErrAlreadyClaimed):
|
|
return newResult(CodeAlreadyClaimed, "issue is claimed by another actor")
|
|
|
|
case errors.Is(err, storage.ErrNotClaimable):
|
|
return newResult(CodeNotClaimable, "issue is not in a claimable state")
|
|
|
|
// The two close-policy refusals share one code. They are the same statement
|
|
// to a client — the close was refused for the state of the graph around
|
|
// this issue, and `force` is the bypass for both — and what distinguishes
|
|
// them on the wire is the `open_children` member failClose attaches, not a
|
|
// second vocabulary entry.
|
|
case errors.Is(err, issueops.ErrCloseOpenChildren):
|
|
return newResult(CodeNotClosable, "issue has open children; close them first or close with force")
|
|
|
|
case errors.Is(err, issueops.ErrCloseBlocked):
|
|
return closeBlockedResult(err, "issue is blocked", "clear the blocker or close with force")
|
|
|
|
// The close guards; the first, template read-only, is every update's guard
|
|
// too. Each detail is this server's own words rather than the role's
|
|
// message, for the reason Problem.detail gives; the typed members are what
|
|
// a client reconstructs the refusal from.
|
|
case errors.Is(err, issueops.ErrTemplateReadOnly):
|
|
return newResult(CodeTemplateReadOnly, "this issue is a template, and templates are read-only; pour it to create work")
|
|
|
|
case errors.Is(err, issueops.ErrPinned):
|
|
return newResult(CodeIssuePinned, "this issue is pinned; close with force to override")
|
|
|
|
case errors.As(err, ¬Assignee):
|
|
return newResult(CodeNotAssignee,
|
|
"this issue is assigned to another actor; reclaim it, or close with force").WithAssignee(notAssignee.Assignee)
|
|
|
|
case errors.Is(err, ErrBusy):
|
|
res := newResult(CodeBusy, "")
|
|
res.RetryAfterSeconds = retryAfterSaturation
|
|
return res
|
|
|
|
// The retry budget is spent inside uow.RunTxResult; reaching here means it
|
|
// gave up, so the request is retryable at the client's cadence, not the
|
|
// server's.
|
|
case uow.IsSerializationError(err):
|
|
res := newResult(CodeBusy, "")
|
|
res.RetryAfterSeconds = retryAfterContention
|
|
return res
|
|
|
|
case isUnavailable(err):
|
|
res := newResult(CodeDBUnavailable, "")
|
|
res.RetryAfterSeconds = retryAfterContention
|
|
return res
|
|
|
|
default:
|
|
return newResult(CodeInternal, "")
|
|
}
|
|
}
|
|
|
|
// isUnavailable reports whether err is a failure to reach the database at all
|
|
// — the server or proxy being down, idle-stopped, or dropping connections —
|
|
// as opposed to a failure while executing a statement.
|
|
//
|
|
// The list is empirical and safe to extend: it only chooses between two 5xx
|
|
// codes that carry identical static detail, so a miss costs a less useful
|
|
// `code`, never a disclosure.
|
|
func isUnavailable(err error) bool {
|
|
// context.DeadlineExceeded satisfies net.Error, so it must be excluded
|
|
// before the net.Error test below: a tripped per-request deadline is a
|
|
// generic 500, not a claim that the database is unreachable.
|
|
if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
|
|
return false
|
|
}
|
|
if errors.Is(err, driver.ErrBadConn) || errors.Is(err, mysql.ErrInvalidConn) {
|
|
return true
|
|
}
|
|
if errors.Is(err, syscall.ECONNREFUSED) || errors.Is(err, syscall.ECONNRESET) || errors.Is(err, syscall.EPIPE) {
|
|
return true
|
|
}
|
|
var netErr net.Error
|
|
return errors.As(err, &netErr)
|
|
}
|
|
|
|
// Write emits res as application/problem+json. Success bodies are written by
|
|
// their handlers; every non-2xx byte goes through here.
|
|
func Write(w http.ResponseWriter, res Result) {
|
|
h := w.Header()
|
|
h.Set("Content-Type", "application/problem+json; charset=utf-8")
|
|
if res.RetryAfterSeconds > 0 {
|
|
h.Set("Retry-After", strconv.Itoa(res.RetryAfterSeconds))
|
|
}
|
|
// RFC 9110 requires the challenge on a 401, and it is set here rather than
|
|
// at the refusal so a second 401 site could not forget it — the same reason
|
|
// Retry-After is set from the code above.
|
|
if res.Problem.Code == string(CodeUnauthenticated) {
|
|
h.Set("WWW-Authenticate", "Bearer")
|
|
}
|
|
w.WriteHeader(res.Problem.Status)
|
|
_ = json.NewEncoder(w).Encode(res.Problem)
|
|
}
|