request_id was optional in the document and unconditional on the wire. Every
non-2xx flows through the fail path, which mints the id in the outermost
middleware — the panic path included — and 5xx `detail` is a fixed static
string by design, so request_id is the only actionable member of a 5xx. The
schema was the only place not saying so.
The description now splits contract from implementation note, so a
multi-instance deployment can satisfy the contract with an edge trace id
instead of this server's per-process one.
Regen consequence, expected: apigen.Problem.RequestId is a non-pointer string,
so WithRequestID loses its pointer assignment and its empty-string guard. An
id this server failed to mint now travels as an empty string rather than as a
missing required member.
`type` is declared but never emitted, so `about:blank` stays implied here. It
is counter-specified rather than left open: one stable URI per status+code
pair, never a dispatch key, never subdividing a code — a deployment that hosts
problem documentation may supply it without forking error identity away from
`code`. It stays out of `required`; a profile requiring it is a legal
tightening. RFC `instance` stays undeclared — request_id is the occurrence
identifier.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The id path segment was the one input on this write path with no edge
check, in a slice whose whole posture is refuse-before-database-work: any
length up to net/http's request-line budget, and any percent-decoded byte
including newlines, reached storage and spent a concurrency slot plus two
round trips before the miss was found.
There is no injection to fix — id and actor are parameterized in both the
CAS and the state read, the table names are constants, and the commit
message is a bound parameter — so this is purely about not doing work for
an id no row can hold. `issues.id` is VARCHAR(255) and the document calls
the parameter an exact canonical id, so an over-long or control-carrying
id is provably a miss.
The refusal is the same 404 a real miss gets, built by a new shared
NotFound() so the two sites cannot drift; telling them apart would let a
caller map which ids the server considers well-formed. Five rows in
TestClaimRefusesUnrowableIDsBeforeAnyDatabaseWork fail without the guard,
all with a 200 and an opened unit of work.
A client that hung up while queued on the semaphore, or during NewUOW, was
answered with 500 internal AND an event=request_error carrying
error="context canceled". acquire returns ctx.Err() on <-ctx.Done(),
ClassifyError deliberately keeps context.Canceled out of isUnavailable so it
falls through to CodeInternal, and failErr emits request_error for every
>=500. So on a saturated server — precisely when clients time out and hang up,
and precisely when an operator is watching — every impatient disconnect
inflated the 500 count and the error stream that gets alerted on.
failErr now recognizes context.Canceled and records a log-only outcome,
code=client_closed on the request line, with no request_error event. Nothing
about the wire changes: the status stays as classified and goes to a socket
nobody is reading. codeClientClosed is deliberately absent from codeStatus,
operationCodes and the document, so it cannot leak into the vocabulary.
An expired request deadline keeps the contract's specified 500/internal and
its request_error: nothing about it says the client left.
Test: TestClientHangupIsNotBookedAsAServerFault, both rows — the hangup row
fails without this change, the deadline row is the control that pins the
mapping that must not move.
The first slice that runs a server. Proxied-server workspaces go live; the
read and claim operations are registered as transitional 501 stubs so route
and spec parity can be proved all at once instead of growing a hole per slice.
`bd serve --addr 127.0.0.1:0 [--allow-non-loopback]`, and no other flags in
v0. The bound address is stdout's first line, because under the ephemeral
default it is the only way to find the port. Shutdown rides the signal context
the root command already installs. No lock file, pid file or discovery file:
serve is operator-invoked and the TCP bind IS the mutual exclusion — dbproxy
needs that machinery only because clients race to auto-spawn it.
The mode gate says two different things, deliberately. Embedded is a PERMANENT
typed storage.ErrUnsupported: there is no unit-of-work provider for that
backend. Dolt server mode is STAGED — the provider construction exists and is
tested, it just is not wired in yet — so the text names what works today and
says this does not, rather than reading as an architectural limit that would
send an operator off to change their topology for nothing.
One unit of work per request, closed through a DETACHED context. The
transaction layer poisons the pinned connection when a ROLLBACK send fails
(doltserver_tx.go), so closing with the request's own canceled context would
burn a session on every client disconnect.
Front-tier hardening lands here, not later, because without it a hung Dolt
becomes a silently growing black hole: slots fill with immortal queries,
/healthz stays green because it never touches the database, and recovery
produces a thundering herd. So: a Host-header allowlist (DNS-rebinding defense
for an unauthenticated, browser-reachable loopback service), a
netutil.LimitListener connection cap (Go spawns a goroutine per connection, so
the database semaphore alone does not bound what is accepted), a database
semaphore with a BOUNDED 10s wait mapping to the already-documented 503 busy,
a 60s per-request deadline, and explicit pool limits on the provider's *sql.DB
via a new uow.PoolTuner knob — openDB set none, and database/sql's default is
unlimited.
/v0/beads/context serializes an explicit ten-field allowlist and nothing else.
SyncRemote is hard-excluded in this and every future version: it is populated
unconditionally from config sync.remote, and remote URLs routinely embed
credentials. The database bind endpoint and the remaining absolute host paths
are excluded too. `capabilities` is derived from IMPLEMENTED handlers only, so
a release cut between this slice and the endpoint slices advertises only what
actually works.
The observability floor is an acceptance criterion, not a convention: one
structured stderr line per request (method, path, status, problem code,
duration, semaphore wait, unit-of-work acquire), startup and shutdown lines, a
semaphore-saturation event, and a request_id on every problem response. That
last one required documenting request_id on the spec's Problem schema — the
only spec edit here, additive, with types regenerated.
Decisions implemented as given: hooks do not fire (a user-controlled
subprocess per mutation is an unbounded latency multiplier and an orphaned
child at shutdown); the per-command auto-commit globals are never touched
(nothing to exclude — proxied PersistentPostRunE only closes the provider);
and actor on an HTTP request stays caller-asserted provenance, which the
context and capabilities wording does not contradict.
Tests: TestSpecRouteParity asserts set equality between the route table and
the document's paths, and builds the real mux so a pattern ServeMux would
refuse fails here rather than on the first request.
TestSpecStatusCodesMatchHandlerTable carries a commented, enumerated 501
exemption that is self-deleting — it fails if the route table and the list
disagree, and fails again if the list outlives the last stub. The context
allowlist is enforced from the handler out, over a body built from a snapshot
with every field populated and a credential-bearing sync remote.
TestWithUOWClosesWithADetachedContext records the close context's state AT
close time, which is the only moment it says anything.
Verified: build, vet and golangci-lint clean (the two gosec findings in
cmd/bd/main.go pre-date this change); internal/httpapi green under -race;
protocol corpus byte-identical with BEADS_PROTOCOL_REQUIRE_DOLT=1; and a real
server started against a proxied workspace, answered both endpoints, refused
a foreign Host, an unknown query key and a second bind, and drained to exit 0
on SIGTERM.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Description-only, plus two Go doc comments that had to move with them. No
schema, parameter, status or code changes. Each one is a place a client would
have believed something the server does not do:
- ready `type` claimed "singular/plural spellings are accepted". The contracted
normalization is alias expansion (mr, feat, mol, enhancement, dec, adr) and
nothing else, so `type=bugs` would have matched nothing and returned 200 with
an empty items array — a silently empty result set, the exact failure the
unknown-parameter policy exists to prevent, and invisible to the CLI parity
oracles because no CLI invocation would send it. Now names the real aliases,
says there is no plural folding, and says an unknown type is empty-not-error
here — while listIssues' `type` 400s, because `bd list` validates and this
operation keeps that.
- ready's default type exclusions (merge-request, gate, molecule, rig, the
configured infra types) were undocumented, as was the fact that setting
`type` drops them entirely. A limit=0 "scan the active set" client could not
learn from the document that whole type classes never appear.
- IssueDetails.comments/dependents said "populated only when explicitly
requested", but v0 has no way to request them and rejects every query key, so
they are never populated. The wording invited a client to probe for a
parameter that answers 400. Says plainly: not in v0, use the counts, keep
`bd show --json --include-comments` for bodies; adding the parameters later
is additive.
- listIssues did not say that an explicit `status` REPLACES the default status
exclusions (so `status=closed` alone works, no `all=true` needed), and did not
mention that ephemeral/wisp rows are out of scope with no include_ephemeral
here.
- The cursor contract nailed opacity but left lifetime and misuse undefined.
Now: no expiry, no server-side state, survives restart, invalidated only by an
encoding change; the invalid_cursor recovery (restart with no cursor) is
normative rather than buried in a detail string; and repeating a cursor under
different filters is explicitly UNDETECTABLE by the server, which serves the
new filters from the old position.
- The mode-dependent limit=0 refusal named no machine-readable reason. It is
`param: "limit"`, `reason: "invalid_value"`, and the Problem.reason vocabulary
now covers legal-but-refused-in-this-configuration instead of only
"malformed" — no new vocabulary, since a third reason value would be
permanent surface. Also states that the bind mode is deliberately not
advertised, so probing is the intended discovery path.
- The document-level carve-out claimed the per-operation responses "list only
the codes the operation's own handler can produce", while the unknown-
parameter 400 lives in every operation's decoder — so health, getContext and
getIssue could answer 400 with no machine-readable trace of it. Both uniform
400s are now stated together, and the per-operation lists are described as
what an operation produces BEYOND them, with an explicit warning to generated
clients.
- Issue.metadata is `type: object`, but the store validates only well-formed
JSON, so `bd create --metadata '[1,2]'` mints a row that violates it. The
schema keeps the intended shape (every producer and both metadata filters
assume it) and now discloses the gap instead of asserting something the
storage path does not enforce.
- The pinned-schema notes said four schemas; there are seven.
Lands the bd serve wire contract and the machinery that keeps it honest. No
runtime behavior: nothing routes, nothing serves, and no CLI surface changes.
internal/httpapi/spec/openapi.v0.yaml is hand-written and is the source of
truth; internal/httpapi/apigen is generated from it with oapi-codegen
types-only (no server stubs, no router), via a go.mod tool directive so
contributors need no extra install.
The decisions this slice fixes, because they are one-way doors:
- No second wire struct. Issue, IssueWithCounts, IssueDetails and
IssueWithDependencyMetadata are pinned to the canonical Go types with
x-go-type, so the generator emits type aliases and the CLI's --json, the
JSONL interchange and the HTTP bodies all marshal one struct. A hand-written
Go-to-Go mapping layer would recreate the drift disease this epic exists to
cure. Guarded by a two-way JSON-tag bijection test, not a round-trip fixture:
a new omitempty field absent from a fixture round-trips cleanly in both
directions and proves nothing.
- limit=0 means unlimited, matching the CLI exactly, with defaults 50 (list)
and 100 (ready) documented as the shared constants. The only exception --
refusal under --allow-non-loopback -- is in the limit description.
- ready returns IssueWithCounts, not bare Issue.
- Unknown query parameters are rejected with 400 invalid_argument naming the
parameter in a machine-readable extension member: with types-only codegen the
decoders are hand-written, and Go's silent-ignore default would WIDEN a
filtered result set under version skew.
- /v0/beads/issues forces (created_at DESC, id ASC) on every request, and the
spec documents the deliberate divergence from bd list's priority ordering.
- One RFC 9457 problem+json envelope everywhere, with a frozen code vocabulary
mapped from the sentinels via errors.Is. 5xx bodies carry a static per-code
detail; the real error goes only to the log, because driver and dial errors
routinely embed the DSN.
- Only the status codes the six operations need are documented. Every
documented status+code pair is permanent wire surface.
Two traps found while building this, both now guarded:
- oapi-codegen v2.6.0 silently drops x-go-type from a component that also
carries allOf. An allOf-composed IssueWithCounts generated
"type IssueWithCounts = types.Issue" -- the ready endpoint would have shipped
with the count fields gone. The pinned schemas therefore repeat their
property lists, and internal/httpapi/pinning.go turns a regression into a
build failure.
- context.DeadlineExceeded satisfies net.Error, so a tripped request deadline
would have mapped to 503 db_unavailable instead of a generic 500.
make api-check is the three-part gate (regenerate, diff-or-fail, spec tests)
and runs from scripts/ci/pr-policy.sh, i.e. in a required PR job -- the Main
workflow is perpetually concurrency-cancelled, so a gate living only there
would be unenforced.
The go.mod diff is the tool directive and its closure. The protocol corpus is
untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>