* Publish POST /v0/beads/issues:claimNext: take ready work atomically (ga-g3gg8)
A client of this surface that wants the next piece of work composes
`GET /v0/beads/ready` with `POST /v0/beads/issues/{id}:claim`. That
composition is a RACE, and it is the reason this operation exists rather than
a round trip saved: between the listing that offered a row and the claim that
asked for it, another agent claims it — so the second agent earns a 409 for a
row it was correctly offered, and a fleet polling one queue spends its
requests losing races instead of doing work.
`claimNextIssue` publishes issueops.ReadyClaimer, where selection, the
compare-and-set that wins the row, and the hydration of the row that was won
are ONE transaction. The row cannot move between being chosen and being
reported.
THE FILTER IS THE LISTING'S, and not a copy of it. The parameters are decoded
by readyFilters — the same function `listReadyWork` and `countReadyWork` share
— because a claim that answered a different question than `bd ready` shows
would hand an agent work the listing never offered it, and two predicates that
are allowed to differ eventually do. The actor is the only body member: it is
provenance that lands in a column, and this surface has always carried that in
a body, while re-spelling the filter as a body object would create exactly the
second expression the shared decoder exists to prevent.
TestClaimNextAdmitsExactlyTheListingsFilters holds the DOCUMENT to the same
identity, since only the handler is protected by sharing the function.
`limit` is refused BY VALUE rather than left to the unknown-parameter rule,
and the distinction is two different client recoveries. `unknown_parameter`
means "this server does not know that name — version skew, degrade or fall
back", which would be false: it is a name this server knows perfectly well on
the sibling listing. It will not ACT on it, which is `invalid_value`, and the
reason is the role's: a claim delivers the one row it wins however large the
pool it scanned, and the scan must stay unbounded or a window that happens to
be full of rows a racing agent already took reports nothing to claim.
`sort` IS published, unlike on `ready:count`, because order decides WHICH row
a claim writes to where it cannot change a cardinality — and it is sent
explicitly for handleReady's reason, which bites harder here: an empty policy
adopts storage's hybrid fallback, and here that changes the row that gets
written rather than the order rows are printed in.
NOTHING ELIGIBLE IS A 200 WITH `claimed` ABSENT. An empty ready front is the
steady state of a drained queue, not a failure, and a polling agent that had
to classify an error to discover it would be pattern-matching prose. There is
no boolean beside the member and no scan count: a second member carrying the
same fact is a second member that can disagree with the first. This is the one
place the operation differs from `issues/{id}:claim`, which 404s an id that
names nothing — that one was asked about a ROW, and this one was asked a
question whose honest answer can be "none".
It documents no 409 and no 404 at all, and both absences are contract. There
is no id to have missed, and a row a racing agent took is simply not in the
set this claim scanned.
The real-Dolt leg asserts the guarantee a fake cannot express: nine concurrent
claimants against six ready rows win six distinct rows and never the same one
twice. The assertion is on duplicates rather than on timing, so it is
deterministic however the goroutines interleave.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish patch.add_labels and patch.remove_labels on updateIssue (ga-g3gg8)
The bead asked for "incremental label add/remove on the wire", noting that
labels are replace-only and that issueops.LabelPatch has Add and Remove. The
trace found the situation is narrower than that and more familiar: the role's
whole algebra IS already wire-expressible — as `labels.{replace,add,remove}`
on `issues:batchApply`'s update item, which has published `ApplyLabelPatch`
since it landed. What has no incremental spelling is `PATCH /v0/beads/issues/{id}`,
whose `patch.labels` is a bare array.
That is #5484's finding again, on the one member it did not close: two
operations for patching one issue, disagreeing about what patching one issue
means. This closes the gap from the same side, and this member is the last of
them.
`patch.labels` KEEPS ITS SHAPE, and that is a constraint rather than a
preference. Nesting it into an object the way `ApplyPatchBody` does would
RE-TYPE a published member, which is the one kind of change this document has
no additive route for — `## Profiles` names re-typing explicitly as not a
tightening, and the only remedies written down are a new optional member or
cutting /v1. So the increments arrive as two flat siblings, which is the shape
`notes` and `append_notes` already use for the same replace/increment pair on
this exact schema.
THEY ARE NOT MUTUALLY EXCLUSIVE WITH `labels`, and that is the difference from
that pair. The role defines an ORDER over all three — replace, then add, then
remove, so removal wins — so a request carrying all three has a defined result
and must reach the role whole. Notes have no such algebra, so there the two
members are a contradiction and are refused. The handler assembles one
LabelPatch in one loop for exactly this reason: a member decoded into its own
patch value would overwrite the others' fields and the last one decoded would
silently win.
The retired premise is worth stating, because it was written down and it was
half right. `patch.labels` said incremental edits were deferred because
"replacement is the only shape whose result the client already knows without a
read-back". That holds for a writer that knows it is alone and fails for every
other one: two agents each adding a tag to one row, each composing a
replacement from a read taken before the other wrote, silently drop each
other's label. `bd label add` and every agent that tags work concurrently are
that caller. The real-Dolt leg is written as exactly that scenario.
The length bound applies to all three members including `remove_labels`, where
a value the column could not hold could never have been stored: it is a rule
about what a label may BE, and the role refuses it there too and writes
nothing, so the edge refuses it where the 400 can name the member and the
index.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues:batchClose: close many, keep the survivors (ga-g3gg8)
`bd close a b c` is one transaction and one history entry. Over this surface it
has been N calls to `POST /v0/beads/issues/{id}:close`, which is N transactions
and N history entries, with no way for a caller to say it wanted them together.
The request is the transaction boundary, which is the whole reason
issueops.BatchCloser is a role rather than a loop.
IT IS THE ONE OPERATION HERE WHOSE 200 CARRIES REFUSALS, and that shape is the
ROLE's rather than an arrangement of it. An id the batch turns down is skipped
and the survivors commit, because an agent that finishes four of five steps and
mistypes the fifth should keep the four — so a per-item refusal is a RESULT of
the batch, not an error of it. `batchCreateIssues` is the deliberate opposite
and has said so in its own document since it landed: half a created plan cannot
be re-sent without duplicating the half that landed.
The division that falls out is the contract a client codes against, and it is
stated on both sides: a NON-2xx means the batch NEVER RAN, and a per-item
`code` means that item did not land while others may have.
`code` ON AN OUTCOME IS `Problem.code`'s VOCABULARY, restricted to `not_found`
and `not_closable`. A second vocabulary was the alternative and it was refused:
an item refusal and a request refusal are the same question asked at two
scopes, so a client made to learn two spellings would be classifying the SCOPE
rather than the condition. `open_children` keeps both of its readings, and both
are the single close's: present-and-a-count on a success (the number a forced
close bypassed, reported even for an idempotent re-close), and PRESENCE as the
discriminator between the two `not_closable` refusals on a failure, exactly as
on a problem document.
The projection fails CLOSED. An item error no arm recognizes becomes a refusal
carrying the generic code, never a success — because a success with no row is a
shape a client cannot tell from a real close, and a `default` that fell through
would produce exactly that.
NO COMPOSED CLAIM, and the omission is reasoned rather than partial. The role
can claim the next ready issue in the same transaction once the closes land;
publishing that member would need a second, BODY-shaped spelling of the ready
filter vocabulary that `GET /v0/beads/ready` and the `issues:claimNext` landing
beside this one both express as query parameters — and two spellings of one
predicate eventually disagree, which is the reason ReadyClaimer.Filter is the
listing's own request type. A client that wants both sends two requests and
loses the single transaction, which is a real loss and is named in the document
rather than papered over. It is additive later.
The per-item id is bounded HERE, which the single close gets from the
custom-method dispatcher and this operation has no dispatcher to get it from. It
is a 400 rather than a per-item `not_found`, because it is a statement about the
REQUEST and because reporting it as a miss would let a caller map this server's
notion of a well-formed id.
The real-Dolt leg asserts the claim the whole shape rests on: a batch whose
middle item names nothing still commits the two either side of it, each with its
OWN reason — read back through the CLI rather than off the response the batch
composed. A fake cannot state that, because it holds no rows to roll back.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Scope the label members' no-op wording to the labels (ga-g3gg8)
`add_labels` and `remove_labels` each said a no-op edit "reports
`changed: false`". That is the RESPONSE's member and it describes the whole
patch, so it is only true of a request whose sole content was the no-op edit —
a request that also moved a title changed the row and reports true.
They now say what is true of the member: the edit changes no labels. The
response's reading is stated once beside it, as a fact about the patch.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix two misspell findings inherited from the release merge (ga-lzcuv)
`main` is red on Lint as of 294af94be2, and both findings are prose from that
squash rather than from anything in this branch:
internal/httpapi/problem.go:85 `archaeology` -> misspell wants `archeology`
internal/httpapi/problem.go:591 `neighbour` -> misspell wants `neighbor`
`.golangci.yml` sets `misspell.locale: US`, so both are real under this
repository's configuration. They are fixed here because this branch merges next
and would otherwise carry a red Lint of its own making no changes to earn.
`neighbour` takes the US spelling. `archaeology` is REWORDED to `excavation`
rather than respelled: `archeology` is the spelling the linter wants and the
one most readers would read as a typo, and the sentence loses nothing by not
having the word in it. Rewording is the only one of the two options that leaves
the comment saying what it meant without looking wrong.
Neither is reachable from the local pre-commit hook, which fails at
golangci-lint config load in this environment before it analyses a file.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
309 lines
12 KiB
Go
309 lines
12 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"net/http"
|
|
"strings"
|
|
"unicode/utf8"
|
|
|
|
"github.com/steveyegge/beads/internal/httpapi/apigen"
|
|
"github.com/steveyegge/beads/internal/storage"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/issueops"
|
|
)
|
|
|
|
const (
|
|
// maxBatchCloseItems is the document's cap on `items`. It is
|
|
// maxBatchCreateItems for that constant's reason — it bounds how long one
|
|
// request may hold a write transaction — and it is a constant of its own
|
|
// rather than a reference to that one because the two operations are free
|
|
// to move independently and a shared name would make one move both.
|
|
maxBatchCloseItems = 100
|
|
// maxBatchCloseBodyBytes bounds the request body. A hundred items of an id
|
|
// and a bounded reason is a fraction of what a create carries, so the
|
|
// create's budget is generous here rather than tight.
|
|
maxBatchCloseBodyBytes = 4 << 20
|
|
)
|
|
|
|
// batchCloseRequestMembers and batchCloseItemMembers are the document's member
|
|
// lists at each level, refused BY NAME for the reason every other body on this
|
|
// surface is.
|
|
var (
|
|
batchCloseRequestMembers = []string{claimActorMember, "items", "session", "force"}
|
|
batchCloseItemMembers = []string{"id", "reason"}
|
|
)
|
|
|
|
// handleBatchClose closes many issues and commits them together.
|
|
//
|
|
// IT IS THE ONE OPERATION ON THIS SURFACE WHOSE 200 CARRIES REFUSALS, and that
|
|
// shape is the ROLE's rather than this handler's arrangement. An id the batch
|
|
// refuses is skipped and the survivors commit, because an agent that finishes
|
|
// four of five steps and mistypes the fifth should keep the four — so a refusal
|
|
// is a RESULT of the batch, not an error of it.
|
|
//
|
|
// The division that falls out of that is the contract a client codes against: a
|
|
// non-2xx means the batch NEVER RAN, and a per-item `code` means that item did
|
|
// not land while others may have. batchCreateIssues is the deliberate opposite
|
|
// and says so in its own document.
|
|
//
|
|
// A collection-level custom method, spelled the way issues:batchCreate is.
|
|
// Hooks do not fire and the per-command auto-commit machinery does not run.
|
|
func (s *Server) handleBatchClose(w http.ResponseWriter, r *http.Request) {
|
|
if !s.requireNoQuery(w, r) {
|
|
return
|
|
}
|
|
if !s.requireJSONContent(w, r) {
|
|
return
|
|
}
|
|
request, ok := s.batchCloseRequest(w, r)
|
|
if !ok {
|
|
return
|
|
}
|
|
|
|
closer, err := s.batchCloser(r)
|
|
if err != nil {
|
|
s.failBatchClose(w, r, err)
|
|
return
|
|
}
|
|
result, err := closer.CloseBatch(r.Context(), request)
|
|
if err != nil {
|
|
s.failBatchClose(w, r, err)
|
|
return
|
|
}
|
|
// The role promises one outcome per requested item in request order, and
|
|
// this projection preserves that: a client walks the array against its own
|
|
// argument list, so dropping or reordering an entry would silently
|
|
// misattribute every outcome after it.
|
|
outcomes := make([]apigen.CloseOutcome, 0, len(result.Outcomes))
|
|
for _, outcome := range result.Outcomes {
|
|
outcomes = append(outcomes, closeOutcome(outcome))
|
|
}
|
|
writeJSON(w, apigen.BatchCloseResponse{Outcomes: outcomes})
|
|
}
|
|
|
|
// closeOutcome projects one role outcome onto the wire.
|
|
//
|
|
// `code`'s PRESENCE is the discriminator the document publishes, so the two
|
|
// branches here are disjoint by construction rather than by convention: a
|
|
// refused item carries the code and nothing else, and a successful one carries
|
|
// the row, the idempotence flag and the count.
|
|
//
|
|
// THE REFUSAL BRANCH READS TYPED FIELDS, never prose — the same rule every 409
|
|
// on this surface follows, applied one scope down. `open_children` comes from
|
|
// *issueops.CloseOpenChildrenError's own field, filled inside the transaction
|
|
// that refused, and its ABSENCE is what tells a client the other not_closable
|
|
// refusal (a live blocker) apart from this one.
|
|
//
|
|
// AN UNRECOGNIZED ITEM ERROR IS NOT SILENTLY DROPPED. The role documents three
|
|
// refusals and this maps three; anything else becomes a `not_closable` carrying
|
|
// no members would be a lie, so it takes the outcome's only honest shape — a
|
|
// refusal with the generic internal code — rather than being reported as a
|
|
// success with no row, which is the shape a `default: success` would produce.
|
|
func closeOutcome(outcome issueops.CloseOutcome) apigen.CloseOutcome {
|
|
wire := apigen.CloseOutcome{IssueId: outcome.IssueID}
|
|
if outcome.Err == nil {
|
|
alreadyClosed := !outcome.Changed
|
|
openChildren := outcome.OpenChildren
|
|
issue := outcome.Issue
|
|
wire.AlreadyClosed = &alreadyClosed
|
|
wire.OpenChildren = &openChildren
|
|
if issue != nil {
|
|
wire.Issue = issue
|
|
}
|
|
return wire
|
|
}
|
|
|
|
var openChildren *issueops.CloseOpenChildrenError
|
|
var (
|
|
code Code
|
|
detail string
|
|
)
|
|
switch {
|
|
case errors.As(outcome.Err, &openChildren):
|
|
code, detail = CodeNotClosable, "this issue has open children; close them first, or send `force`"
|
|
count := openChildren.OpenChildren
|
|
wire.OpenChildren = &count
|
|
|
|
case errors.Is(outcome.Err, issueops.ErrCloseBlocked):
|
|
// No `open_children`, and its ABSENCE is what tells a client which of
|
|
// the two close-policy refusals this item got.
|
|
code, detail = CodeNotClosable, "this issue is blocked; clear the blocker, or send `force`"
|
|
|
|
case errors.Is(outcome.Err, storage.ErrNotFound):
|
|
code, detail = CodeNotFound, "no issue with this id in either plane"
|
|
|
|
default:
|
|
code, detail = CodeInternal, staticDetail[CodeInternal]
|
|
}
|
|
wire.Code = ptrTo(string(code))
|
|
wire.Detail = ptrTo(detail)
|
|
return wire
|
|
}
|
|
|
|
func ptrTo[T any](v T) *T { return &v }
|
|
|
|
// batchCloseRequest decodes and validates the body. Every refusal here happens
|
|
// BEFORE any database work, and every one of them means the batch never ran.
|
|
func (s *Server) batchCloseRequest(w http.ResponseWriter, r *http.Request) (issueops.CloseBatchRequest, bool) {
|
|
members, res := decodeJSONObject(w, r, maxBatchCloseBodyBytes)
|
|
if res != nil {
|
|
s.fail(w, r, *res)
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
if offender, unknown := unknownMember(members, batchCloseRequestMembers); unknown {
|
|
s.failUnknownMember(w, r, offender, batchCloseRequestMembers)
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
|
|
actor, ok := s.bodyActor(w, r, members)
|
|
if !ok {
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
session, ok := s.storedTextMember(w, r, members, "session")
|
|
if !ok {
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
force, ok := s.booleanMember(w, r, members, "force")
|
|
if !ok {
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
items, ok := s.batchCloseItems(w, r, members)
|
|
if !ok {
|
|
return issueops.CloseBatchRequest{}, false
|
|
}
|
|
// ClaimNext stays unset, and the document says why: expressing it would
|
|
// need a second, body-shaped spelling of the ready-filter vocabulary that
|
|
// listReadyWork and claimNext both express as query parameters.
|
|
return issueops.CloseBatchRequest{
|
|
Actor: actor,
|
|
Items: items,
|
|
Session: session,
|
|
Force: force,
|
|
}, true
|
|
}
|
|
|
|
// batchCloseItems validates `items` and projects it onto the role's items. It
|
|
// is batchCreateItems' body over a narrower item, and it refuses the same three
|
|
// request shapes for the same reasons.
|
|
func (s *Server) batchCloseItems(w http.ResponseWriter, r *http.Request, members map[string]json.RawMessage) ([]issueops.BatchCloseItem, bool) {
|
|
raw, ok := members["items"]
|
|
if !ok {
|
|
s.fail(w, r, InvalidArgument("items", ReasonInvalidValue, "`items` is required"))
|
|
return nil, false
|
|
}
|
|
var rawItems []map[string]json.RawMessage
|
|
if err := json.Unmarshal(raw, &rawItems); err != nil || rawItems == nil {
|
|
s.fail(w, r, InvalidArgument("items", ReasonInvalidValue, "`items` must be an array of objects"))
|
|
return nil, false
|
|
}
|
|
switch {
|
|
case len(rawItems) == 0:
|
|
s.fail(w, r, InvalidArgument("items", ReasonInvalidValue,
|
|
"`items` must carry at least one issue; a close that closes nothing is refused rather than answered"))
|
|
return nil, false
|
|
case len(rawItems) > maxBatchCloseItems:
|
|
s.fail(w, r, InvalidArgument("items", ReasonInvalidValue,
|
|
fmt.Sprintf("`items` carries %d issues; the limit is %d per request", len(rawItems), maxBatchCloseItems)))
|
|
return nil, false
|
|
}
|
|
|
|
items := make([]issueops.BatchCloseItem, 0, len(rawItems))
|
|
for i, rawItem := range rawItems {
|
|
if rawItem == nil {
|
|
s.fail(w, r, InvalidArgument(batchCloseItemParam(i, ""), ReasonInvalidValue, "an item must be a JSON object"))
|
|
return nil, false
|
|
}
|
|
if offender, unknown := unknownMember(rawItem, batchCloseItemMembers); unknown {
|
|
s.failUnknownMember(w, r, batchCloseItemParam(i, offender), batchCloseItemMembers)
|
|
return nil, false
|
|
}
|
|
item, res := batchCloseItem(i, rawItem)
|
|
if res != nil {
|
|
s.fail(w, r, *res)
|
|
return nil, false
|
|
}
|
|
items = append(items, item)
|
|
}
|
|
return items, true
|
|
}
|
|
|
|
// batchCloseItem projects one decoded item onto the role's item.
|
|
//
|
|
// The id is BOUNDED HERE, which the single close gets from the custom-method
|
|
// dispatcher and this operation has no dispatcher to get it from: an id longer
|
|
// than the column, or carrying a control character a percent-escape decoded to,
|
|
// names no row that can exist. It is a 400 rather than a per-item `not_found`
|
|
// because it is a statement about the REQUEST — the batch never ran — and
|
|
// because reporting it as a miss would let a caller map this server's notion of
|
|
// a well-formed id.
|
|
func batchCloseItem(index int, raw map[string]json.RawMessage) (issueops.BatchCloseItem, *Result) {
|
|
refuse := func(member, detail string) *Result {
|
|
res := InvalidArgument(batchCloseItemParam(index, member), ReasonInvalidValue, detail)
|
|
return &res
|
|
}
|
|
encoded, err := json.Marshal(raw)
|
|
if err != nil {
|
|
return issueops.BatchCloseItem{}, refuse("", "an item must be a JSON object")
|
|
}
|
|
var wire apigen.BatchCloseItem
|
|
if err := json.Unmarshal(encoded, &wire); err != nil {
|
|
return issueops.BatchCloseItem{}, refuse("", "an item member carries the wrong JSON type")
|
|
}
|
|
// The custom-method dispatcher's own two checks, applied here because this
|
|
// operation is not on its pattern.
|
|
switch {
|
|
case wire.Id == "":
|
|
return issueops.BatchCloseItem{}, refuse("id", "`id` is required")
|
|
case types.CheckFieldLen("id", wire.Id) != nil:
|
|
return issueops.BatchCloseItem{}, refuse("id",
|
|
fmt.Sprintf("`id` is %d characters; storage holds at most %d",
|
|
utf8.RuneCountInString(wire.Id), types.MaxFieldLen))
|
|
case strings.ContainsFunc(wire.Id, isControlChar):
|
|
return issueops.BatchCloseItem{}, refuse("id", "`id` must not contain control characters")
|
|
}
|
|
reason := ""
|
|
if wire.Reason != nil {
|
|
// storedTextMember's rules, applied to an item member: the value lands
|
|
// in a column a renderer prints, so an unfiltered C1 introducer would
|
|
// make a close reason an escape-sequence payload.
|
|
switch {
|
|
case types.CheckFieldLen("reason", *wire.Reason) != nil:
|
|
return issueops.BatchCloseItem{}, refuse("reason",
|
|
fmt.Sprintf("`reason` is %d characters; storage holds at most %d",
|
|
utf8.RuneCountInString(*wire.Reason), types.MaxFieldLen))
|
|
case strings.ContainsFunc(*wire.Reason, isControlChar):
|
|
return issueops.BatchCloseItem{}, refuse("reason", "`reason` must not contain control characters")
|
|
}
|
|
reason = *wire.Reason
|
|
}
|
|
return issueops.BatchCloseItem{IssueID: wire.Id, Reason: reason}, nil
|
|
}
|
|
|
|
// batchCloseItemParam names an item member the way a client reads it back off
|
|
// `param`: indexed, so an offender in a hundred-item request is found without a
|
|
// search. It is batchCreateItemParam's spelling, deliberately.
|
|
func batchCloseItemParam(index int, member string) string {
|
|
if member == "" {
|
|
return fmt.Sprintf("items[%d]", index)
|
|
}
|
|
return fmt.Sprintf("items[%d].%s", index, member)
|
|
}
|
|
|
|
// failBatchClose answers a request that never ran.
|
|
//
|
|
// The role's own error is reserved for request validation, cancellation and
|
|
// infrastructure — a non-nil error and populated outcomes are mutually
|
|
// exclusive — so there is nothing here to classify per item. The role's
|
|
// ErrValidation is defensively unreachable: an empty actor, an empty item list
|
|
// and a blank item id are all refused at the edge.
|
|
func (s *Server) failBatchClose(w http.ResponseWriter, r *http.Request, err error) {
|
|
if !errors.Is(err, storage.ErrValidation) {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
s.event("request_refused", "request_id", requestInfo(r.Context()).id, "error", err.Error())
|
|
s.fail(w, r, InvalidArgument("", ReasonInvalidValue,
|
|
"the request was refused by this workspace's own validation; nothing was written"))
|
|
}
|