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>
22 lines
691 B
Go
22 lines
691 B
Go
// Package spec holds the hand-written OpenAPI document for the bd serve HTTP
|
|
// API and embeds it into the binary.
|
|
//
|
|
// The document is the source of truth for the wire contract. The Go types in
|
|
// internal/httpapi/apigen are generated from it; the parity and bijection
|
|
// tests parse the embedded bytes, so they check the document that actually
|
|
// ships rather than a copy on disk.
|
|
package spec
|
|
|
|
import (
|
|
"bytes"
|
|
_ "embed"
|
|
)
|
|
|
|
//go:embed openapi.v0.yaml
|
|
var openAPIV0 []byte
|
|
|
|
// OpenAPIV0 returns the OpenAPI 3.0.3 document describing the /v0 surface.
|
|
// The returned slice is a copy: callers may not mutate the embedded bytes.
|
|
func OpenAPIV0() []byte {
|
|
return bytes.Clone(openAPIV0)
|
|
}
|