beads/internal/httpapi/problem_test.go
CI Bot e988fd002d feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb)
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>
2026-07-31 08:37:34 +00:00

280 lines
9.6 KiB
Go

package httpapi
import (
"context"
"database/sql"
"database/sql/driver"
"encoding/json"
"errors"
"fmt"
"net"
"net/http"
"net/http/httptest"
"strconv"
"strings"
"syscall"
"testing"
"github.com/go-sql-driver/mysql"
"github.com/steveyegge/beads/internal/storage"
)
// dsn is the shape a driver or dial error takes in the wild: it names the
// database user, host and port. No 5xx body may echo any of it.
const dsn = "dial tcp 127.0.0.1:3306: connect: connection refused (bd_user@tcp(127.0.0.1:3306)/beads)"
func TestProblemMapping(t *testing.T) {
tests := []struct {
name string
err error
wantStatus int
wantCode Code
retryAfter int
}{
{
name: "not found sentinel",
err: storage.ErrNotFound,
wantStatus: http.StatusNotFound,
wantCode: CodeNotFound,
},
{
name: "wrapped not found sentinel",
err: fmt.Errorf("get issue bd-1: %w", storage.ErrNotFound),
wantStatus: http.StatusNotFound,
wantCode: CodeNotFound,
},
{
// The real seam shape: the SQL repository returns a bare
// sql.ErrNoRows, which the shared read path normalizes. This row
// is the defense-in-depth half — a missing issue must never
// surface as a 500.
name: "wrapped sql.ErrNoRows",
err: fmt.Errorf("select issue: %w", sql.ErrNoRows),
wantStatus: http.StatusNotFound,
wantCode: CodeNotFound,
},
{
name: "already claimed",
err: storage.ErrAlreadyClaimed,
wantStatus: http.StatusConflict,
wantCode: CodeAlreadyClaimed,
},
{
// The CLI reconstructs the holder from this message fragment; the
// wire must not, which is why the extension members come from a
// same-transaction read instead.
name: "already claimed with the CLI message fragment",
err: fmt.Errorf("%w%salice", storage.ErrAlreadyClaimed, storage.ClaimedByFragment),
wantStatus: http.StatusConflict,
wantCode: CodeAlreadyClaimed,
},
{
name: "not claimable",
err: fmt.Errorf("%w%sclosed", storage.ErrNotClaimable, storage.NotClaimableStatusFragment),
wantStatus: http.StatusConflict,
wantCode: CodeNotClaimable,
},
{
name: "in-flight limiter timed out",
err: fmt.Errorf("acquire slot: %w", ErrBusy),
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeBusy,
retryAfter: retryAfterSaturation,
},
{
name: "serialization retry budget exhausted (deadlock)",
err: fmt.Errorf("claim %s: %w", dsn, &mysql.MySQLError{Number: 1213, Message: "Deadlock found"}),
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeBusy,
retryAfter: retryAfterContention,
},
{
name: "serialization retry budget exhausted (lock wait timeout)",
err: &mysql.MySQLError{Number: 1205, Message: "Lock wait timeout exceeded"},
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeBusy,
retryAfter: retryAfterContention,
},
{
name: "dial failure",
err: fmt.Errorf("new uow: %w", &net.OpError{Op: "dial", Net: "tcp", Err: syscall.ECONNREFUSED}),
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeDBUnavailable,
retryAfter: retryAfterContention,
},
{
name: "bad connection",
err: fmt.Errorf("query %s: %w", dsn, driver.ErrBadConn),
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeDBUnavailable,
retryAfter: retryAfterContention,
},
{
name: "invalid connection",
err: fmt.Errorf("query %s: %w", dsn, mysql.ErrInvalidConn),
wantStatus: http.StatusServiceUnavailable,
wantCode: CodeDBUnavailable,
retryAfter: retryAfterContention,
},
{
// context.DeadlineExceeded satisfies net.Error. A tripped
// per-request deadline is a plain 500, not a claim that the
// database is unreachable.
name: "request deadline",
err: fmt.Errorf("list issues: %w", context.DeadlineExceeded),
wantStatus: http.StatusInternalServerError,
wantCode: CodeInternal,
},
{
name: "client went away",
err: fmt.Errorf("list issues: %w", context.Canceled),
wantStatus: http.StatusInternalServerError,
wantCode: CodeInternal,
},
{
// The load-bearing negative: an arbitrary error is a 500, never a
// 404. "Every error is a not-found" is the failure this mapping
// exists to prevent.
name: "arbitrary error",
err: fmt.Errorf("scan row: %s: %w", dsn, errors.New("unexpected column count")),
wantStatus: http.StatusInternalServerError,
wantCode: CodeInternal,
},
{
name: "nil error",
err: nil,
wantStatus: http.StatusInternalServerError,
wantCode: CodeInternal,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
res := ClassifyError(tc.err)
if res.Problem.Status != tc.wantStatus {
t.Errorf("status = %d, want %d", res.Problem.Status, tc.wantStatus)
}
if res.Problem.Code != string(tc.wantCode) {
t.Errorf("code = %q, want %q", res.Problem.Code, tc.wantCode)
}
if res.RetryAfterSeconds != tc.retryAfter {
t.Errorf("Retry-After = %d, want %d", res.RetryAfterSeconds, tc.retryAfter)
}
rec := httptest.NewRecorder()
Write(rec, res)
if rec.Code != tc.wantStatus {
t.Errorf("written status = %d, want %d", rec.Code, tc.wantStatus)
}
if got := rec.Header().Get("Content-Type"); got != "application/problem+json; charset=utf-8" {
t.Errorf("Content-Type = %q, want application/problem+json", got)
}
wantRetry := ""
if tc.retryAfter > 0 {
wantRetry = strconv.Itoa(tc.retryAfter)
}
if got := rec.Header().Get("Retry-After"); got != wantRetry {
t.Errorf("Retry-After header = %q, want %q", got, wantRetry)
}
body := rec.Body.String()
var decoded map[string]any
if err := json.Unmarshal([]byte(body), &decoded); err != nil {
t.Fatalf("body is not JSON: %v (%s)", err, body)
}
if decoded["title"] != http.StatusText(tc.wantStatus) {
t.Errorf("title = %v, want %q", decoded["title"], http.StatusText(tc.wantStatus))
}
if tc.wantStatus < 500 {
return
}
// 5xx detail scrubbing: the wire carries a fixed string per code
// and the real error goes to the log only. Driver and dial errors
// embed the DSN, and this binary can be bound beyond loopback.
if got := decoded["detail"]; got != staticDetail[tc.wantCode] {
t.Errorf("detail = %v, want the static %q", got, staticDetail[tc.wantCode])
}
for _, leak := range []string{"127.0.0.1", "3306", "bd_user", "tcp", "connection refused", "Deadlock", "unexpected column count"} {
if strings.Contains(body, leak) {
t.Errorf("5xx body leaks %q from the underlying error: %s", leak, body)
}
}
})
}
}
func TestInvalidArgumentCarriesParamAndReason(t *testing.T) {
// A 400 must be machine-attributable without parsing prose: `param` names
// the offending input and `reason` separates "this server does not know
// that parameter" (version skew) from "your value is malformed" (a client
// bug). Substring-matching error text is the pathology this API deletes.
res := InvalidArgument("mol_type", ReasonUnknownParameter, `unknown query parameter "mol_type"`)
if res.Problem.Status != http.StatusBadRequest {
t.Errorf("status = %d, want 400", res.Problem.Status)
}
if res.Problem.Code != string(CodeInvalidArgument) {
t.Errorf("code = %q, want %q", res.Problem.Code, CodeInvalidArgument)
}
if res.Problem.Param == nil || *res.Problem.Param != "mol_type" {
t.Errorf("param = %v, want mol_type", res.Problem.Param)
}
if res.Problem.Reason == nil || *res.Problem.Reason != string(ReasonUnknownParameter) {
t.Errorf("reason = %v, want %q", res.Problem.Reason, ReasonUnknownParameter)
}
// 4xx details reflect the caller's own input back and stay specific.
if res.Problem.Detail == nil || !strings.Contains(*res.Problem.Detail, "mol_type") {
t.Errorf("detail = %v, want the offending parameter named", res.Problem.Detail)
}
if got := InvalidCursor(); got.Problem.Code != string(CodeInvalidCursor) || got.Problem.Status != http.StatusBadRequest {
t.Errorf("InvalidCursor = %d/%q, want 400/%q", got.Problem.Status, got.Problem.Code, CodeInvalidCursor)
}
}
func TestConflictExtensions(t *testing.T) {
// The 409 extension members are populated from a read in the claim's own
// transaction — never by parsing the sentinel's message fragments.
res := ClassifyError(storage.ErrAlreadyClaimed).WithAssignee("alice").WithIssueStatus("in_progress")
if res.Problem.Assignee == nil || *res.Problem.Assignee != "alice" {
t.Errorf("assignee = %v, want alice", res.Problem.Assignee)
}
if res.Problem.IssueStatus == nil || *res.Problem.IssueStatus != "in_progress" {
t.Errorf("issue_status = %v, want in_progress", res.Problem.IssueStatus)
}
rec := httptest.NewRecorder()
Write(rec, res)
var decoded map[string]any
if err := json.Unmarshal(rec.Body.Bytes(), &decoded); err != nil {
t.Fatalf("body is not JSON: %v", err)
}
if decoded["assignee"] != "alice" || decoded["issue_status"] != "in_progress" {
t.Errorf("extension members missing from the wire body: %v", decoded)
}
}
func TestCodeVocabularyIsFrozen(t *testing.T) {
// Every code the operation table can emit must have a frozen status, and
// nothing may sit in the vocabulary that no operation can produce: a
// documented status+code pair is permanent wire surface.
reachable := map[Code]bool{}
for op, codes := range operationCodes {
for _, c := range codes {
if c.Status() == 0 {
t.Errorf("%s: code %q has no frozen status", op, c)
}
reachable[c] = true
}
}
for c := range codeStatus {
if !reachable[c] {
t.Errorf("code %q is in the vocabulary but no operation can emit it", c)
}
}
}