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>
15 lines
839 B
Go
15 lines
839 B
Go
// Package apigen holds the Go types generated from the bd serve OpenAPI
|
|
// document (spec-first: internal/httpapi/spec/openapi.v0.yaml is the source of
|
|
// truth, this package is its output).
|
|
//
|
|
// Do NOT hand-edit types.gen.go — change the spec and run `make api-gen`.
|
|
// `make api-check` regenerates, fails on any diff, and runs the spec tests, so
|
|
// an un-regenerated spec edit cannot merge.
|
|
//
|
|
// Types only: no server stubs, no router, no request validation. The handlers
|
|
// stay hand-written and framework-free, which is also why the query decoders
|
|
// must reject unknown parameters explicitly (spec, "Unknown query parameters
|
|
// are rejected") — a types-only decoder ignores them by default.
|
|
//
|
|
//go:generate go tool oapi-codegen -generate types,skip-prune -package apigen -o types.gen.go ../spec/openapi.v0.yaml
|
|
package apigen
|