beads/internal/httpapi/doc.go
CI Bot 5bd29359b3 docs(httpapi): stop the orientation prose enumerating a surface it no longer has
doc.go still opened with "the three reads ... and the one write, POST
/v0/beads/issues/{id}:claim" and stated that "the claim OPERATION is the
only mutation this surface has". bd-serve-v0.md still opened its surface
section with "Six operations" over a six-row table, sized the server
under "Claim throughput — the claim is the only mutation in v0", and
scoped the no-hooks and no-auto-commit contracts to the claim alone. The
route table serves twenty-seven operations, eleven of them writes. Both
pages name themselves sources of truth, and bd-serve-v0.md's own header
rule says nothing in it may contradict the spec, doc.go or the reader
role — so this was the rule violating itself.

The counts are not corrected, they are removed. routes.go is the router,
TestSpecRouteParity welds it to the spec by exact set equality in both
directions, and capabilities is derived from the same table: a fourth
copy of the list, spelled in prose, can only ever go stale — as this one
did, silently, across five merged PRs. Both pages now describe the
MECHANISM and point at it. What replaces the table in bd-serve-v0.md is
the surface's shape, which is what a design page is for and which does
not change when an operation is added: what answers from the process,
how reads reach roles, the two spellings a write comes in, and the
posture every write shares.

Statements that were true only of the claim are widened where the code
widened them (the JSON content type is enforced for every body-carrying
operation; hooks fire for no write; the idempotent-write commit skip is
the re-claim, the re-close and the reopen) and narrowed where they were
overstated (the reader property covers three named reads, not "all"
reads — the count, the query, stats, config, memories and the dependency
reads are on sibling roles). The design page's error table gains the
three codes the wave added, with the extension members each carries and
the absence that distinguishes the two dependency_cycle refusals.

Also sweeps the seven stale "one write on this surface" comments in
claim.go, claim_test.go, roles_test.go and update_test.go, and reads.go's
"the three read operations" header over a file that now holds five.

No wire change, no behavior change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-08 01:34:33 +00:00

144 lines
9 KiB
Go

// Package httpapi implements the HTTP surface described by
// internal/httpapi/spec/openapi.v0.yaml — the /v0 wire contract `bd serve`
// answers on.
//
// What is live: the process lifecycle (Listen and Serve), the bind policy, the
// route table and the request path in front of it — Host allowlist, connection
// cap, database semaphore, per-request deadline, structured request log — and
// every operation routeTable carries.
//
// WHICH operations those are is deliberately not restated here. routes.go is
// the router, TestSpecRouteParity welds it to the document by exact set
// equality in both directions, and ContextResponse.capabilities is derived from
// the same table gated on `implemented` — so the table, the spec and a running
// server's own handshake are three spellings of one answer, and a fourth
// spelled in prose could only ever go stale. Read the surface from routeTable
// or ask a server for it; a release cut mid-slice never advertises an operation
// that does not work.
//
// Two rows answer from the process itself and touch no database (GET /healthz
// and GET /v0/beads/context); they carry bypassSemaphore for that reason, and
// nothing else may.
//
// No handler here holds query logic of its own. Each decodes its parameters
// and hands the whole request to a role obtained from the provider's own
// capability accessor — the same roles, reached the same way, the CLI reaches
// on a store. Three of them reach issueops.Reader (GET /v0/beads/ready,
// GET /v0/beads/issues, GET /v0/beads/issues/{id}), which is the role `bd show
// --json` reaches and the one the property below is about; the rest reach
// siblings of it, one role per operation. Filter construction, the workspace
// config it depends on, the default limits and the wisp fallback all live
// inside the role. A handler cannot WRITE a filter here, and that is
// machine-checked by
// two rules in .golangci.yml covering the two ways one gets written:
// httpapi-transport-boundary (depguard) denies internal/workapi from this
// package's non-test files, so the builders are not callable; the forbidigo
// rule denies naming types.IssueFilter or types.WorkFilter here at all, so a
// hand-rolled one is not writable either. The second is the one that
// matches the failure — the hosted viewer's bug was a bare IssueFilter, not a
// misused builder. What does stay here is transport — parameter decoding, the
// opaque cursor codec, the loopback-only refusal of an unlimited read, and the
// wire envelopes.
//
// The other front door is only PARTLY on the role, and the accurate statement
// of the anti-drift property is worth getting exactly right, because
// overstating it is what stops the next person checking.
//
// `bd show --json` is on the role, on both its routes. `bd ready` and `bd
// list` are not, on either: they consume the filter for modes the role does
// not express (see issueops.Reader's doc comment for the list, and for why
// splitting those commands would be worse). What they share instead is
// CONSTRUCTION — the same request types through the same builders, pinned by
// the builders' golden files — and, where it reaches, EXECUTION:
// workapi.FinishPage, the sort, trim and has-more verdict this surface's
// reader runs too, is `bd list`'s epilogue on both routes in every mode but
// the hierarchical --parent tree (which renders its recursive walk's result
// directly, on either route), and `bd ready`'s on the proxied route only.
// `bd ready`'s direct route keeps its own epilogue because it publishes a
// hidden-row TOTAL this surface has no member for.
//
// THE CLAIM, stated once and in full so it can be checked sentence by
// sentence. SHARED: the three reads named above go through issueops.Reader,
// and so does `bd show --json`'s detail view on both its routes — this says
// nothing about the surface's OTHER reads, which are on sibling roles and
// carry their own conformance suites; `bd list` and `bd ready` are not on the
// role and share instead the
// request types, the two builders in internal/workapi that their golden files
// pin, and workapi.FinishPage — `bd list` on both routes in every mode but the
// hierarchical --parent tree, `bd ready` on its proxied route only.
// ENFORCED, and by what: depguard (httpapi-transport-boundary) denies
// internal/workapi from every non-test file of this package, so no builder is
// callable here, and a forbidigo rule denies naming types.IssueFilter or
// types.WorkFilter here at all, so no filter is writable here either — both
// are directory-scoped with no per-file exception, so a file added to this
// package tomorrow is covered the moment it exists. That same forbidigo rule
// covers cmd/bd deny-by-default with 64 named exceptions, so the files
// implementing `bd list` and `bd show` cannot write a filter, and neither can
// a file they are split or renamed into unless the new name lands on that
// list. NOT ENFORCED: the rule forbids NAMING those types, not holding a
// value, so the property is "no filter is written here", not "every filter
// here came from a builder"; test files are exempt from both rules, because
// the oracles hold filters in order to inspect them; GET /healthz and GET
// /v0/beads/context answer from the process and its startup snapshot, are not
// issue queries, and are on no role; `bd ready`'s direct route and `bd list`'s
// hierarchical tree run epilogues of their own; and none of this is a merge
// gate — the rules run in `make ci-pr-lint` on every pull request and
// aggregate into the ci-gate job, but main carries no branch protection beyond
// deletion and non-fast-forward, so no check is GitHub-required and a red gate
// binds by convention.
//
// A THIRD rule closes the other way past the roles. Denying internal/workapi
// stops a handler building a filter; it says nothing about a handler taking
// uw.IssueUseCase() and calling the domain straight, which needs no filter and
// no builder — and which is what the proxied CLI did for years. depguard
// (httpapi-domain-boundary) therefore denies internal/storage/domain from this
// package's non-test files, deny-by-default so a file added tomorrow is covered
// the moment it exists. It has exactly two named holes, both for a VALUE the
// embedder assembled rather than a use case: server.go, whose Config.Workspace
// is the domain.ContextInfo startup snapshot it is handed, and handlers.go,
// whose contextResponse projects that snapshot through domain.PublishedContext
// — the same projection `bd context` publishes, and where the credential and
// host-path exclusions live. No handler file is on that list, and adding one
// to it is the edit review has to catch.
//
// EVERY MUTATION ON THIS SURFACE CARRIES THE CLAIM'S POSTURE, and claim.go
// states the two things a client must know before adopting any of them: the
// actor is caller-asserted provenance rather than authenticated identity, and
// hooks do not fire — nor does the per-command auto-commit machinery, so
// durability is per request. The claim was the first write and is where that
// posture is written down in full; each write added since restates only what
// is its own and points here for the rest. Which rows are writes is read from
// routeTable, not from a list kept here.
//
// The claim shares no function with `bd update --claim` above the transaction
// and deliberately so — the CAS itself is already one implementation one level
// down, in the domain's issue use case, which both reach. claimOnUOW says why
// nothing above that is worth extracting.
//
// The Host allowlist is the DNS-rebinding defense, and it has no off switch.
// Every bind answers to the loopback spellings and to the bound address itself;
// a WILDCARD bind (0.0.0.0, ::) has no single configured address, so it answers
// to any numeric IP literal and still refuses foreign DNS names. That last rule
// is the one place this deviates from the design's letter, which enumerated
// "the configured bind address" without saying what a wildcard means: a rebound
// page cannot produce an IP-literal Host, because the browser sends the hostname
// from the attacker's URL, so allowing literals keeps --allow-non-loopback
// usable on every interface while the defense survives — including on the
// serving host's own loopback, which is rebinding's canonical target. Matching
// is on parsed addresses, so every spelling of an allowed address is allowed.
//
// Around that sit the inert pieces the contract needs regardless: the
// problem+json error mapping, the shared limit defaults, and the compile-time
// pins that keep the generated types welded to the canonical structs.
//
// Two rules govern everything added here:
//
// The spec is the source of truth. Types come from it (`make api-gen`), never
// the other way round, and `make api-check` fails a change that edits one
// without the other.
//
// There is no wire struct. Responses marshal internal/types values directly,
// so the CLI's --json output and these bodies are one compatibility domain —
// which also means a serialized field on types.Issue cannot be renamed or
// removed without breaking the HTTP contract, not just the CLI's.
package httpapi