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>
318 lines
13 KiB
Go
318 lines
13 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"context"
|
|
"database/sql"
|
|
"database/sql/driver"
|
|
"encoding/json"
|
|
"errors"
|
|
"net"
|
|
"net/http"
|
|
"strconv"
|
|
"syscall"
|
|
|
|
"github.com/go-sql-driver/mysql"
|
|
|
|
"github.com/steveyegge/beads/internal/httpapi/apigen"
|
|
"github.com/steveyegge/beads/internal/storage"
|
|
"github.com/steveyegge/beads/internal/storage/uow"
|
|
)
|
|
|
|
// Every non-2xx byte this server emits is an RFC 9457 problem+json document
|
|
// (apigen.Problem, generated from the spec — there is one error shape here).
|
|
// This file owns the whole mapping: sentinel error in, status + machine code
|
|
// out, matched exclusively with errors.Is/errors.As. Never `err != nil ->
|
|
// status`.
|
|
//
|
|
// SENTINEL NOTE: the mapping keys on the sentinel VALUES, never on where they
|
|
// are declared. A parallel refactor relocates the canonical Err* declarations
|
|
// into a leaf issueops package and aliases them back from internal/storage
|
|
// with the same pointers, so errors.Is keeps matching either spelling with no
|
|
// edit here. Do not re-express these rows as package-path or message checks.
|
|
|
|
// Code is the machine-readable member of the problem envelope, and the only
|
|
// member a client may dispatch on.
|
|
//
|
|
// The vocabulary is a one-way door: renaming or removing a documented
|
|
// status+code pair breaks the wire. Adding one does not, which is why clients
|
|
// are told to default-branch on unknown codes within a status class. Keep it
|
|
// at what the six v0 operations actually need.
|
|
type Code string
|
|
|
|
// The v0 code vocabulary. Every value here is documented in the spec, and
|
|
// TestSpecStatusCodesMatchHandlerTable fails if the two ever disagree.
|
|
const (
|
|
// CodeInvalidArgument covers every request-validation refusal: an unknown
|
|
// query parameter, a malformed value, an invalid actor, an unparseable or
|
|
// oversized body, limit=0 under --allow-non-loopback, and the Host-header
|
|
// middleware. The 400 carries `param` and `reason` so clients never have
|
|
// to tell those cases apart by reading prose.
|
|
CodeInvalidArgument Code = "invalid_argument"
|
|
// CodeInvalidCursor is a separate code because a stale or foreign cursor
|
|
// is a normal client situation with an obvious recovery (restart paging),
|
|
// not a client bug.
|
|
CodeInvalidCursor Code = "invalid_cursor"
|
|
CodeNotFound Code = "not_found"
|
|
// CodeAlreadyClaimed carries the holder in the `assignee` extension
|
|
// member, read inside the same transaction — never parsed out of the
|
|
// sentinel's message text.
|
|
CodeAlreadyClaimed Code = "already_claimed"
|
|
CodeNotClaimable Code = "not_claimable"
|
|
// CodeBusy is retryable contention: the transaction retry budget was
|
|
// exhausted, or the in-flight request limit was saturated.
|
|
CodeBusy Code = "busy"
|
|
// CodeDBUnavailable is a retryable connectivity failure reaching the
|
|
// database.
|
|
CodeDBUnavailable Code = "db_unavailable"
|
|
CodeInternal Code = "internal"
|
|
)
|
|
|
|
// codeStatus freezes one HTTP status per code. A code that could arrive with
|
|
// two different statuses would defeat the point of dispatching on it.
|
|
var codeStatus = map[Code]int{
|
|
CodeInvalidArgument: http.StatusBadRequest,
|
|
CodeInvalidCursor: http.StatusBadRequest,
|
|
CodeNotFound: http.StatusNotFound,
|
|
CodeAlreadyClaimed: http.StatusConflict,
|
|
CodeNotClaimable: http.StatusConflict,
|
|
CodeBusy: http.StatusServiceUnavailable,
|
|
CodeDBUnavailable: http.StatusServiceUnavailable,
|
|
CodeInternal: http.StatusInternalServerError,
|
|
}
|
|
|
|
// Status returns the HTTP status frozen to c, or 0 if c is not in the v0
|
|
// vocabulary.
|
|
func (c Code) Status() int { return codeStatus[c] }
|
|
|
|
// Reason distinguishes the two client postures behind a 400
|
|
// CodeInvalidArgument, so that telling them apart never requires parsing
|
|
// `detail`. The set may grow; clients default-branch on unknown values.
|
|
type Reason string
|
|
|
|
const (
|
|
// ReasonUnknownParameter means this server does not know that parameter:
|
|
// version skew. The client degrades or falls back. It is also a client's
|
|
// only per-parameter capability probe, since `capabilities` is
|
|
// operation-level.
|
|
ReasonUnknownParameter Reason = "unknown_parameter"
|
|
// ReasonInvalidValue means the value is malformed: a client bug, fail
|
|
// loud.
|
|
ReasonInvalidValue Reason = "invalid_value"
|
|
)
|
|
|
|
// staticDetail is the ONLY `detail` a 5xx may carry. The underlying error goes
|
|
// to the server log and nowhere else: driver and dial errors routinely embed
|
|
// the DSN — go-sql-driver renders connection targets as
|
|
// user@tcp(127.0.0.1:PORT)/db, net dial errors carry the same host:port — and
|
|
// query errors can carry SQL fragments. The moment the server is bound with
|
|
// --allow-non-loopback, a verbose 5xx detail is an information-disclosure
|
|
// channel to network peers. 4xx details stay specific: they reflect the
|
|
// caller's own input back, not server internals.
|
|
var staticDetail = map[Code]string{
|
|
CodeBusy: "the server is busy; retry shortly",
|
|
CodeDBUnavailable: "database temporarily unavailable; retry",
|
|
CodeInternal: "internal server error",
|
|
}
|
|
|
|
// Retry-After values, in seconds.
|
|
const (
|
|
// retryAfterContention follows an exhausted transaction retry budget. The
|
|
// budget spans many seconds of observed write contention, so a one-second
|
|
// comeback would invite a convoy of retries that each hold a slot while
|
|
// they wait — starving reads exactly when the server is busiest.
|
|
retryAfterContention = 5
|
|
// retryAfterSaturation follows an in-flight-limit wait timeout. Slot
|
|
// pressure clears quickly.
|
|
retryAfterSaturation = 1
|
|
)
|
|
|
|
// ErrBusy reports that the in-flight request limiter refused to admit the
|
|
// request within its bounded wait. The limiter itself lands with the server;
|
|
// the sentinel lives here so the mapping owns the whole 503 vocabulary.
|
|
var ErrBusy = errors.New("server busy")
|
|
|
|
// Operation ids, matching the spec's operationId values exactly.
|
|
const (
|
|
OpHealth = "health"
|
|
OpGetContext = "getContext"
|
|
OpListReadyWork = "listReadyWork"
|
|
OpListIssues = "listIssues"
|
|
OpGetIssue = "getIssue"
|
|
OpClaimIssue = "claimIssue"
|
|
)
|
|
|
|
// operationCodes is the per-operation problem vocabulary: exactly the codes
|
|
// that operation's handler can produce, and therefore exactly what the spec
|
|
// documents for it. TestSpecStatusCodesMatchHandlerTable asserts set-equality
|
|
// in both directions, so an undocumented emission and an unemittable
|
|
// documented status both fail CI.
|
|
//
|
|
// The Host-header middleware's 400 invalid_argument is reachable on every
|
|
// route including /healthz, and is deliberately absent from every row here: it
|
|
// runs before any handler and is documented once at the document level rather
|
|
// than repeated on all six operations.
|
|
var operationCodes = map[string][]Code{
|
|
// Liveness answers from the process and touches nothing that can fail.
|
|
OpHealth: nil,
|
|
// v0 serves a startup snapshot without touching the database, so there is
|
|
// no 503 here. If a later slice makes this a DB-probing readiness
|
|
// endpoint, db_unavailable joins this row and the spec in the same change.
|
|
OpGetContext: {CodeInternal},
|
|
OpListReadyWork: {CodeInvalidArgument, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
OpListIssues: {CodeInvalidArgument, CodeInvalidCursor, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
OpGetIssue: {CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal},
|
|
OpClaimIssue: {
|
|
CodeInvalidArgument, CodeNotFound, CodeAlreadyClaimed, CodeNotClaimable,
|
|
CodeBusy, CodeDBUnavailable, CodeInternal,
|
|
},
|
|
}
|
|
|
|
// Result is a problem response ready to be written: the envelope plus the
|
|
// transport-level Retry-After the code implies.
|
|
type Result struct {
|
|
Problem apigen.Problem
|
|
// RetryAfterSeconds is written as the Retry-After header when positive.
|
|
RetryAfterSeconds int
|
|
}
|
|
|
|
// WithAssignee attaches the `assignee` extension member (the current holder of
|
|
// a claimed issue). Populate it from a read in the claim's own transaction —
|
|
// never by parsing the sentinel's message fragments.
|
|
func (r Result) WithAssignee(assignee string) Result {
|
|
r.Problem.Assignee = &assignee
|
|
return r
|
|
}
|
|
|
|
// WithIssueStatus attaches the `issue_status` extension member (the issue's
|
|
// status at the moment of refusal). Same rule as WithAssignee.
|
|
func (r Result) WithIssueStatus(status string) Result {
|
|
r.Problem.IssueStatus = &status
|
|
return r
|
|
}
|
|
|
|
func newResult(code Code, detail string) Result {
|
|
status := code.Status()
|
|
if status == 0 {
|
|
// Unreachable unless a code is added without a status; fail closed
|
|
// rather than emitting a 0 status line.
|
|
status = http.StatusInternalServerError
|
|
code = CodeInternal
|
|
detail = staticDetail[CodeInternal]
|
|
}
|
|
if static, ok := staticDetail[code]; ok {
|
|
// 5xx detail is fixed per code, whatever the caller passed.
|
|
detail = static
|
|
}
|
|
p := apigen.Problem{
|
|
Status: status,
|
|
Title: http.StatusText(status),
|
|
Code: string(code),
|
|
}
|
|
if detail != "" {
|
|
p.Detail = &detail
|
|
}
|
|
return Result{Problem: p}
|
|
}
|
|
|
|
// InvalidArgument builds the 400 for a request the server refuses to
|
|
// interpret. param names the offending query parameter, body member or header;
|
|
// pass "" only when the input has no nameable part (a body that fails to parse
|
|
// at all). detail may quote the caller's own input — it is not server state.
|
|
func InvalidArgument(param string, reason Reason, detail string) Result {
|
|
res := newResult(CodeInvalidArgument, detail)
|
|
if param != "" {
|
|
res.Problem.Param = ¶m
|
|
}
|
|
r := string(reason)
|
|
res.Problem.Reason = &r
|
|
return res
|
|
}
|
|
|
|
// InvalidCursor builds the 400 for a cursor this server did not issue, cannot
|
|
// decode, or issued under a different internal version.
|
|
func InvalidCursor() Result {
|
|
return newResult(CodeInvalidCursor, "cursor is not valid for this server; restart paging without it")
|
|
}
|
|
|
|
// ClassifyError maps an error from the storage seam onto the wire. The caller
|
|
// is responsible for logging err: everything mapped to a 5xx deliberately
|
|
// drops the error text on the floor (see staticDetail).
|
|
func ClassifyError(err error) Result {
|
|
switch {
|
|
case err == nil:
|
|
return newResult(CodeInternal, "")
|
|
|
|
// Not-found normalization belongs in the shared read path, which folds the
|
|
// two miss shapes (a wrapped sql.ErrNoRows, and a nil issue with a nil
|
|
// error) into storage.ErrNotFound. The bare sql.ErrNoRows row below is
|
|
// defense in depth for a path that has not been normalized yet: a missing
|
|
// issue must never surface as a 500. The converse mistake — treating any
|
|
// error as a miss — stays closed, because only these two sentinels reach
|
|
// 404 and everything else falls through to 500.
|
|
case errors.Is(err, storage.ErrNotFound), errors.Is(err, sql.ErrNoRows):
|
|
return newResult(CodeNotFound, "no issue or wisp with that id")
|
|
|
|
case errors.Is(err, storage.ErrAlreadyClaimed):
|
|
return newResult(CodeAlreadyClaimed, "issue is claimed by another actor")
|
|
|
|
case errors.Is(err, storage.ErrNotClaimable):
|
|
return newResult(CodeNotClaimable, "issue is not in a claimable state")
|
|
|
|
case errors.Is(err, ErrBusy):
|
|
res := newResult(CodeBusy, "")
|
|
res.RetryAfterSeconds = retryAfterSaturation
|
|
return res
|
|
|
|
// The retry budget is spent inside uow.RunTxResult; reaching here means it
|
|
// gave up, so the request is retryable at the client's cadence, not the
|
|
// server's.
|
|
case uow.IsSerializationError(err):
|
|
res := newResult(CodeBusy, "")
|
|
res.RetryAfterSeconds = retryAfterContention
|
|
return res
|
|
|
|
case isUnavailable(err):
|
|
res := newResult(CodeDBUnavailable, "")
|
|
res.RetryAfterSeconds = retryAfterContention
|
|
return res
|
|
|
|
default:
|
|
return newResult(CodeInternal, "")
|
|
}
|
|
}
|
|
|
|
// isUnavailable reports whether err is a failure to reach the database at all
|
|
// — the server or proxy being down, idle-stopped, or dropping connections —
|
|
// as opposed to a failure while executing a statement.
|
|
//
|
|
// The list is empirical and safe to extend: it only chooses between two 5xx
|
|
// codes that carry identical static detail, so a miss costs a less useful
|
|
// `code`, never a disclosure.
|
|
func isUnavailable(err error) bool {
|
|
// context.DeadlineExceeded satisfies net.Error, so it must be excluded
|
|
// before the net.Error test below: a tripped per-request deadline is a
|
|
// generic 500, not a claim that the database is unreachable.
|
|
if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
|
|
return false
|
|
}
|
|
if errors.Is(err, driver.ErrBadConn) || errors.Is(err, mysql.ErrInvalidConn) {
|
|
return true
|
|
}
|
|
if errors.Is(err, syscall.ECONNREFUSED) || errors.Is(err, syscall.ECONNRESET) || errors.Is(err, syscall.EPIPE) {
|
|
return true
|
|
}
|
|
var netErr net.Error
|
|
return errors.As(err, &netErr)
|
|
}
|
|
|
|
// Write emits res as application/problem+json. Success bodies are written by
|
|
// their handlers; every non-2xx byte goes through here.
|
|
func Write(w http.ResponseWriter, res Result) {
|
|
h := w.Header()
|
|
h.Set("Content-Type", "application/problem+json; charset=utf-8")
|
|
if res.RetryAfterSeconds > 0 {
|
|
h.Set("Retry-After", strconv.Itoa(res.RetryAfterSeconds))
|
|
}
|
|
w.WriteHeader(res.Problem.Status)
|
|
_ = json.NewEncoder(w).Encode(res.Problem)
|
|
}
|