GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.
THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.
THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:
- CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
answer about a log, and a poller whose steady state was a 404 would have to
treat this surface's miss vocabulary as its happy path.
- DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
zero rows and a head of zero — byte-identical to an enabled journal nothing
has written yet — so without this gate a consumer would poll a workspace
that will never emit a record and call itself caught up forever. Activation
is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
and handed in; this package resolves no workspace state of its own. A 409
for CodeNotClosable's reason: a statement about state the client cannot see,
which the same request stops earning once an operator changes it.
- PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
and `head`. It is the surface's only 410 and it is the right one: those
records existed, were addressable by exactly this request, and were
deliberately deleted — retrying the same `since` can never succeed, which is
what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
on the typed error with errors.As, so neither database source can forget it;
the code is storage's own constant, so the CLI's `--json` failure and this
body cannot drift to two spellings of one condition.
`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.
The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.
EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.
`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.
Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
261 lines
8.1 KiB
Go
261 lines
8.1 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"fmt"
|
|
"net/url"
|
|
"slices"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
)
|
|
|
|
// query decodes one request's query string against the operation's parameter
|
|
// table, and is the single place the document's unknown-parameter rule is
|
|
// enforced for an operation that HAS parameters.
|
|
//
|
|
// The rule is strict on purpose. Silently ignoring an unrecognized FILTER
|
|
// parameter WIDENS the result set, so a client one version ahead of the server
|
|
// would receive — and act on — rows it believed it had filtered out. It is
|
|
// also a client's only per-parameter capability probe, since `capabilities` is
|
|
// operation-level.
|
|
//
|
|
// Every accessor records the name it read, so the allowlist is the parameter
|
|
// table itself rather than a second copy of it that can drift: a parameter the
|
|
// handler never asks for is, by construction, one this server does not know.
|
|
type query struct {
|
|
values url.Values
|
|
read map[string]bool
|
|
// res holds the FIRST refusal. First rather than last so the answer does
|
|
// not depend on the order the handler happens to read its parameters in;
|
|
// `param` is what a client dispatches on.
|
|
res *Result
|
|
}
|
|
|
|
func newQuery(values url.Values) *query {
|
|
return &query{values: values, read: map[string]bool{}}
|
|
}
|
|
|
|
// refuse records a refusal unless one is already recorded.
|
|
func (q *query) refuse(res Result) {
|
|
if q.res == nil {
|
|
q.res = &res
|
|
}
|
|
}
|
|
|
|
func (q *query) invalid(param, detail string) {
|
|
q.refuse(InvalidArgument(param, ReasonInvalidValue, detail))
|
|
}
|
|
|
|
// has reports whether the parameter was supplied, and marks it known.
|
|
func (q *query) has(name string) bool {
|
|
q.read[name] = true
|
|
return len(q.values[name]) > 0
|
|
}
|
|
|
|
// str reads a single-valued string parameter. A repeated parameter is refused
|
|
// rather than silently resolved to one of its values.
|
|
func (q *query) str(name string) string {
|
|
if !q.has(name) {
|
|
return ""
|
|
}
|
|
vals := q.values[name]
|
|
if len(vals) > 1 {
|
|
q.invalid(name, "this parameter takes a single value")
|
|
return ""
|
|
}
|
|
return vals[0]
|
|
}
|
|
|
|
// list reads a repeatable parameter, returning the values as supplied. Comma
|
|
// splitting, where the document allows it, happens in the filter builder that
|
|
// owns the vocabulary — not here.
|
|
func (q *query) list(name string) []string {
|
|
q.read[name] = true
|
|
return q.values[name]
|
|
}
|
|
|
|
// csv reads a repeatable parameter whose values the builder parses as one
|
|
// comma-separated selector.
|
|
func (q *query) csv(name string) string {
|
|
vals := q.list(name)
|
|
if len(vals) == 0 {
|
|
return ""
|
|
}
|
|
return strings.Join(vals, ",")
|
|
}
|
|
|
|
// boolean reads an optional boolean, defaulting to false as the document
|
|
// documents for every flag on this surface.
|
|
func (q *query) boolean(name string) bool {
|
|
raw := q.str(name)
|
|
if raw == "" {
|
|
return false
|
|
}
|
|
v, err := strconv.ParseBool(raw)
|
|
if err != nil {
|
|
q.invalid(name, fmt.Sprintf("%q is not a boolean", raw))
|
|
return false
|
|
}
|
|
return v
|
|
}
|
|
|
|
// integer reads an optional integer, returning nil when absent so a caller can
|
|
// tell "unset" from an explicit value.
|
|
func (q *query) integer(name string) *int {
|
|
raw := q.str(name)
|
|
if raw == "" {
|
|
return nil
|
|
}
|
|
v, err := strconv.Atoi(raw)
|
|
if err != nil {
|
|
q.invalid(name, fmt.Sprintf("%q is not an integer", raw))
|
|
return nil
|
|
}
|
|
return &v
|
|
}
|
|
|
|
// integer64 reads an optional 64-bit integer, returning nil when absent.
|
|
//
|
|
// It is separate from integer above because `int` is 32 bits on a 32-bit build,
|
|
// and the one parameter that needs this — a journal sequence number — is
|
|
// declared int64 in the document and int64 in storage. Parsing it through Atoi
|
|
// would make a checkpoint past 2^31 unreadable on some builds and readable on
|
|
// others, which is the kind of divergence a consumer discovers years later.
|
|
func (q *query) integer64(name string) *int64 {
|
|
raw := q.str(name)
|
|
if raw == "" {
|
|
return nil
|
|
}
|
|
v, err := strconv.ParseInt(raw, 10, 64)
|
|
if err != nil {
|
|
q.invalid(name, fmt.Sprintf("%q is not a 64-bit integer", raw))
|
|
return nil
|
|
}
|
|
return &v
|
|
}
|
|
|
|
// limit reads the page limit: absent stays nil (the shared default), and a
|
|
// negative value is refused. 0 is legal and means unlimited, so it is not
|
|
// bounded here — the loopback-only refusal of an unlimited read is a bind-mode
|
|
// decision and lives with the handler that knows the bind mode.
|
|
func (q *query) limit() *int {
|
|
v := q.integer("limit")
|
|
if v != nil && *v < 0 {
|
|
q.invalid("limit", "limit must be zero or greater; 0 means unlimited")
|
|
return nil
|
|
}
|
|
return v
|
|
}
|
|
|
|
// boundedLimit reads a page limit that has a hard ceiling and no unlimited
|
|
// spelling, substituting fallback when it is absent.
|
|
//
|
|
// It is a SECOND limit decoder rather than a mode of limit() above, because the
|
|
// two operations mean different things by the same parameter name and a shared
|
|
// one would have to hide that behind a flag. On the issue listings `0` means
|
|
// unlimited and the only refusal is a bind-mode one; on a journal read there is
|
|
// no unlimited — a caller with an old checkpoint would ask one process to
|
|
// buffer the entire retained window, which under the shipped floors is a
|
|
// hundred thousand records — so the ceiling is unconditional and `0` is refused
|
|
// by name instead of being reinterpreted as "the default". A parameter that
|
|
// means unlimited on one operation and something else on another is exactly the
|
|
// silent divergence this decoder exists to prevent.
|
|
func (q *query) boundedLimit(fallback, ceiling int) int {
|
|
v := q.integer("limit")
|
|
if v == nil {
|
|
return fallback
|
|
}
|
|
if *v < 1 || *v > ceiling {
|
|
q.invalid("limit", fmt.Sprintf("limit must be between 1 and %d (default %d); this operation has no unlimited read", ceiling, fallback))
|
|
return fallback
|
|
}
|
|
return *v
|
|
}
|
|
|
|
// timestamp reads an optional RFC 3339 instant.
|
|
func (q *query) timestamp(name string) *time.Time {
|
|
raw := q.str(name)
|
|
if raw == "" {
|
|
return nil
|
|
}
|
|
t, err := time.Parse(time.RFC3339, raw)
|
|
if err != nil {
|
|
q.invalid(name, fmt.Sprintf("%q is not an RFC 3339 timestamp", raw))
|
|
return nil
|
|
}
|
|
return &t
|
|
}
|
|
|
|
// metadataFields reads the repeatable `key=value` equality filter, split on the
|
|
// FIRST `=` so a value may contain one.
|
|
func (q *query) metadataFields(name string) map[string]string {
|
|
raw := q.list(name)
|
|
if len(raw) == 0 {
|
|
return nil
|
|
}
|
|
out := make(map[string]string, len(raw))
|
|
for _, entry := range raw {
|
|
k, v, ok := strings.Cut(entry, "=")
|
|
if !ok || k == "" {
|
|
q.invalid(name, fmt.Sprintf("%q is not key=value", entry))
|
|
return nil
|
|
}
|
|
out[k] = v
|
|
}
|
|
return out
|
|
}
|
|
|
|
// oneOf reads a parameter constrained to a closed vocabulary, substituting
|
|
// fallback when it is absent. An unrecognized value is refused: the vocabulary
|
|
// is in the document, so a client that sends something else is asking for
|
|
// behavior this server does not have.
|
|
func (q *query) oneOf(name, fallback string, allowed ...string) string {
|
|
raw := q.str(name)
|
|
if raw == "" {
|
|
return fallback
|
|
}
|
|
if !slices.Contains(allowed, raw) {
|
|
q.invalid(name, fmt.Sprintf("%q is not one of %s", raw, strings.Join(allowed, ", ")))
|
|
}
|
|
return raw
|
|
}
|
|
|
|
// result reports the refusal this request earned, if any. The
|
|
// unknown-parameter check runs LAST so that a malformed value on a parameter
|
|
// the server does know is reported as invalid_value rather than as version
|
|
// skew — the two carry opposite client recoveries.
|
|
func (q *query) result() *Result {
|
|
if q.res != nil {
|
|
return q.res
|
|
}
|
|
var unknown []string
|
|
for name := range q.values {
|
|
if !q.read[name] {
|
|
unknown = append(unknown, name)
|
|
}
|
|
}
|
|
if len(unknown) == 0 {
|
|
return nil
|
|
}
|
|
// One offender, chosen deterministically: `param` is what the client
|
|
// dispatches on, so it must not depend on map order.
|
|
offender := slices.Min(unknown)
|
|
res := InvalidArgument(offender, ReasonUnknownParameter,
|
|
"this server does not know that parameter for this operation")
|
|
if offender == "" {
|
|
// The degenerate `?=1` spelling parses to a parameter whose name is the
|
|
// empty string. InvalidArgument reads "" as "this input has no nameable
|
|
// part" and omits `param`; the document promises `param` on every 400
|
|
// but an unparseable body. Name it.
|
|
res.Problem.Param = &offender
|
|
}
|
|
return &res
|
|
}
|
|
|
|
// offender names the value a refusal turned down, for the request line.
|
|
func (r Result) offender() string {
|
|
if r.Problem.Param != nil {
|
|
return *r.Problem.Param
|
|
}
|
|
return ""
|
|
}
|