Commit graph

1 commit

Author SHA1 Message Date
CI Bot
87c64ec8f1 feat(serve): bd serve skeleton — lifecycle, mode gate, /healthz, /v0/beads/context (bd-60z)
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>
2026-07-31 10:07:14 +00:00