* feat(issueops): type the blocked-close refusal as BlockedError
Every close-policy blocker refusal was fmt.Errorf("%w: %s is blocked by
%v", ErrCloseBlocked, ...), so the blocker list existed only as prose. A
caller reporting the refusal elsewhere (the HTTP surface) had to parse it
or drop it.
issueops.BlockedError carries IssueID, the typed []Blocker (id plus the
blocking edge type when known) and the wrapped sentinel. Its message is
byte-identical to the historical sentence, so the direct and proxied CLI
lines and failed[].error do not move, and errors.Is(ErrCloseBlocked) still
matches. The sentinel is a field rather than fixed so other "X is blocked
by Y" refusals (e.g. a blocked claim) can reuse the type.
The in-transaction guard keeps the edges typed (isBlockedByInTx, with
IsBlockedInTx formatting through Blocker.String), and the external guard
builds the error from IsBlocked's []string via ParseBlocker, the inverse
of that spelling.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* feat(httpapi): name the blockers on a live-blocker not_closable
The served close refusal said only "issue is blocked", so an HTTP client
could not tell the user what held the close, while bd close on the direct
and proxied routes prints "cannot close blocked issue: X is blocked by
[Y]".
A live-blocker not_closable now carries a `blockers` extension member,
[{id, kind: local|external, type?}], read from *issueops.BlockedError's
typed list, and a detail that opens with the direct route's sentence
built from the same list. It covers issues/{id}:close, per-item
issues:batchClose outcomes, PATCH into a done status and
issues:batchApply. The code, status and open_children discriminator are
unchanged; an error that only mentions blockers in prose keeps the old
generic detail and no member.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(issueops): test the external: prefix before the type split in ParseBlocker
Maintainer review fixup for #6893.
ParseBlocker tried the " (" / ")" split before the external: prefix
branch, so it won for any external reference whose capability ends in
")". validateExternalRef (cmd/bd/dep.go) constrains a capability to
non-empty only, so `external:remote:pay (beta)` is a legal reference
created by the sanctioned `bd dep add` path -- and it parsed to a
truncated ID of "external:remote:pay" plus Type "beta", a value outside
the documented blocks|waits-for|conditional-blocks vocabulary that
falsifies the spec's own promise that an external blocker carries no
type.
Only the structured half was wrong: the mis-split round-trips through
String(), so the prose detail and the CLI sentence stayed byte-identical
and the failure was silent on exactly the new `blockers` member this
change exists to make trustworthy.
Hoisting the prefix test is loss-free -- Blocker.Type's doc comment
already states an external reference never carries a reported type.
Pin: the ParseBlocker/String table in
TestBlockedErrorKeepsTheHistoricalSentence gains the paren-suffixed
external row; every external case tabled there was paren-free, which is
why this got through. Restoring the old ordering reds the new row.
The DeepEqual failure now prints %#v, because Blocker implements
String() and the default verbs render got and want identically for
precisely this defect.
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
313 lines
12 KiB
Go
313 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. That refusal's `blockers` come
|
|
// from *issueops.BlockedError's typed list, the same member the single close
|
|
// carries.
|
|
//
|
|
// 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. The blockers travel as
|
|
// the single close's do, so a client names them per item.
|
|
code = CodeNotClosable
|
|
detail, wire.Blockers = closeBlocked(outcome.Err, "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"))
|
|
}
|