beads/internal/httpapi/blocking.go
Julian Knutsen 70887e708a
feat(http): serve IsBlockedBatch through the BlockingAnnotator role behind dependencies.blocking.isBlocked (#7552)
* feat(http): serve IsBlockedBatch through the BlockingAnnotator role behind dependencies.blocking.isBlocked

gc's native ready cache needs bd's stored, transitive is_blocked column for
the active set (beads.BlockedQuerier.IsBlockedBatch). Over http the client
answered it with the generated stub, so every reconcile logged
`operation "IsBlockedBatch" not supported by the http backend`, the
projection stayed disabled and native Ready took ~5 s on the MC shadow.

No read a deployed (1.3.0) server serves can answer the column exactly:
the /v0 reads hydrate issues without is_blocked, the blocking decoration is
direct and two edge types only, and the flag also propagates down
parent-child edges and reads waits-for / conditional-blocks gates. So this
is an additive server behaviour plus a token, not a client-side
composition.

- issueops: BlockingRequest.IncludeIsBlocked asks for, and
  IssueBlocking.IsBlocked carries, each answered id's stored flag (nil =
  no row, never "free"). issueops.BlockedFlags is the one library entry
  for the batched read over the role, chunked at BlockedFlagsChunk (100,
  held equal to the served issue_id bound by an httpapi test).
- Bodies: storage/issueops.ExecuteBlockingAnnotation reads the flag with
  IsBlockedBatchInTx in the same read transaction (dolt, embeddeddolt and
  every sqlkit-style store that calls it); the unit-of-work body asks the
  new DependencyUseCase/Repository IsBlockedBatch (same shared SQL body).
  externaldeps keeps IsBlockedBatch's external-blocker invariant on the
  local and remote annotators, and its Store.IsBlockedBatch no longer makes
  the raw edge read over a role-served store.
- Wire: GET /v0/beads/dependencies/blocking accepts `is_blocked` behind the
  new behaviour token dependencies.blocking.isBlocked (spec, apigen,
  wire-shape golden). wire_revision stays 2.
- Client: httpBlockingAnnotator forwards IncludeIsBlocked and refuses it
  BEFORE dialing with *ErrUnsupported{Capability:
  dependencies.blocking.isBlocked} against a server that does not
  advertise it; Store.IsBlockedBatch is issueops.BlockedFlags over that
  annotator, so gc's errors.As latch still sees the typed refusal on an
  old server, now naming the token that lifts it.

Tests: conformance case RunBlockingAnnotatorReportsTheTransitiveBlockedFlag
(child of a blocked parent is blocked, free is false, a ghost has no flag,
unasked carries none, BlockedFlags agrees) on the dolt, embedded, uow and
served legs; httpapi handler and chunk-bound tests; client tests for
chunking, the wire shape and the zero-dial refusal; vocabulary/capability
gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(externaldeps): keep the external blocker on the unit-of-work IsBlockedBatch

bd serve on a server or proxied-server workspace serves through the
unit-of-work arm (WrapUOWProvider) and advertises
policy.external_dependencies, so a client trusts the server's answers and
adds no external term of its own. That arm's dependency use case did not
override IsBlockedBatch, so the new dependencies.blocking.isBlocked flag
answered the stored is_blocked column, which has no external term. An issue
blocked only by an unsatisfied external: ref came back is_blocked=false,
with that ref listed in its own blocked_by, while GET /v0/beads/ready
excluded it.

dependencyUseCase.IsBlockedBatch now raises every id that has an
unsatisfied external blocker, deciding by the edges and resolver
GetReadyWork excludes by, read through the same unit of work. Unlike Ready
it resolves only the refs of the ids the column answered: a client asks in
chunks, and no chunk should reopen every foreign project the workspace
names. An id naming no row stays absent.

Also correct the store decorator's IsBlockedBatch doc (the served flag now
comes from the annotator role), add the CHANGELOG entry for the new
capability, and pin the flag against Ready on every arm: WrapUOWProvider,
directly and through its BlockingAnnotator (an absent id stays absent), the
local annotator, and the served test, which now asserts the flag and the
batched read. A counting opener pins that the unit-of-work read opens only
the foreign projects its asked rows name.

Checked against a real bd serve on a proxied-server workspace. At
97bcb57738 an issue blocked by external:remote:payments answered
is_blocked=false while /ready excluded it. With this change it answers
true, and once the capability ships /ready includes the issue and
is_blocked is false. Asked about a free issue alone, the server resolves
no external project; asked about the remote-blocked issue, it resolves
remote and leaves alone the unconfigured project another issue names.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(externaldeps): pin that a satisfied external blocker leaves the unit-of-work is_blocked false

Review of 192b73676 (bee-ghosttrack): the two new IsBlockedBatch tests only
had unsatisfied external refs, so a body that raised every answered id with
any external record (ignoring the resolver) stayed green.

TestWrapUOWProviderBlockedFlagResolvesOnlyTheAskedRefs's opener now
returns a foreign store whose labelled index carries a CLOSED provider of
provides:payments (the decorator_test.go shape). be-shipped blocks on
external:remote:payments (satisfied) and must read false; be-blocked moves
to external:remote:invoices (still unsatisfied) and reads true; both still
open /projects/remote once. With the reviewer's mutant applied
(`if _, ok := answered[id]; ok && len(state.refsByIssue) >= 0 {`) the test
fails on be-shipped in both new cases; restored, it passes
(bazel test //internal/storage/externaldeps:externaldeps_test).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(externaldeps): pin the store arm's satisfied external ref and the unasked is_blocked flag

The store arm decides an external blocker in two places: IsBlockedBatch's
local loop skips a ref the resolver reports satisfied, and the
BlockingAnnotator role folds IsBlocked's verdict, which applies the same
filter, into the served flag. Both annotators, store and remote, add that
flag only when the request asks for it. No test checked either store answer
for a ref whose project had shipped the capability, or that an unasked
annotation carries no flag, so dropping any of those checks left the
package green.

Pin them: IsBlockedBatch and the store annotator answer false for a row
whose only blocker is external:remote:payments once remote has closed its
provides:payments issue, and neither annotator flags a row unasked, even
one an external ref blocks. This is the store half of bd-yewju3; the
previous commit pinned the unit-of-work half.

Each mutant below survives the package at the previous commit and fails
exactly one test here (go test -tags=gms_pure_go
./internal/storage/externaldeps/; unmutated, bazel test
//internal/storage/externaldeps:externaldeps_test passes):
- decorator.go IsBlockedBatch: `&& !satisfied[dep.DependsOnID]` made
  `&& len(satisfied) >= 0` fails TestIsBlockedBatchHonorsShippedExternalRef.
- decorator.go IsBlocked: `if !satisfied[ref.raw] {` made always true fails
  TestBlockingAnnotatorLeavesShippedExternalRefUnblocked.
- role_accessors.go: `if req.IncludeIsBlocked {` made `if true {` fails
  TestBlockingAnnotatorAddsNoFlagUnasked.
- remote_roles.go: dropping `req.IncludeIsBlocked &&` fails
  TestRemoteBlockingAnnotatorMergesExternalBlockers.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 08:46:13 +00:00

92 lines
3.7 KiB
Go

package httpapi
import (
"errors"
"fmt"
"net/http"
"github.com/steveyegge/beads/internal/httpapi/apigen"
"github.com/steveyegge/beads/issueops"
)
// handleBlockingAnnotations answers GET /v0/beads/dependencies/blocking.
//
// Everything below the wire is on issueops.BlockingAnnotator: which edge types
// count, which row's status decides an edge is live, that an unresolvable
// blocker still blocks, that a `parent-child` edge is the parent rather than a
// blocker, the order within each list and the de-duplication of a repeated id.
// What stays here is transport — decoding one repeatable parameter, the size
// bound, and an envelope whose element type is the role's own struct.
//
// The size bound is maxDependencyAnchors, shared with the stored-edge read
// beside it rather than given a constant of its own: the two operations bound
// the same thing for the same reason (the QUESTION, because neither answer has
// a cursor), they are asked about the same page of ids, and two numbers would
// mean a client could ask one of them about a page the other refuses.
func (s *Server) handleBlockingAnnotations(w http.ResponseWriter, r *http.Request) {
q := newQuery(r.URL.Query())
ids := q.list("issue_id")
// is_blocked rides CapDependenciesBlockingIsBlocked: the role's
// IncludeIsBlocked, each item's stored transitive flag.
includeIsBlocked := q.boolean("is_blocked")
if !s.acceptQuery(w, r, q) {
return
}
// Both bounds are checked here rather than left to the role, for the reason
// handleListDependencies gives: they are this operation's own limits, not
// statements about what a blocking annotation means, and the role answers an
// empty request with an empty result rather than a refusal.
if len(ids) == 0 {
requestInfo(r.Context()).refuse("issue_id")
s.fail(w, r, InvalidArgument("issue_id", ReasonInvalidValue, "name at least one issue_id"))
return
}
if len(ids) > maxDependencyAnchors {
requestInfo(r.Context()).refuse("issue_id")
s.fail(w, r, InvalidArgument("issue_id", ReasonInvalidValue,
fmt.Sprintf("at most %d issue_id values per request, got %d", maxDependencyAnchors, len(ids))))
return
}
annotator, err := s.blockingAnnotator(r)
if err != nil {
s.failErr(w, r, err)
return
}
result, err := annotator.AnnotateBlocking(r.Context(), issueops.BlockingRequest{IDs: ids, IncludeIsBlocked: includeIsBlocked})
if err != nil {
s.failBlockingErr(w, r, err)
return
}
writeJSON(w, wireBlocking(result))
}
// failBlockingErr answers a failed blocking annotation. The role's one
// request-validation refusal — an empty id — is the caller's own input and
// reaches the client as the 400 it is; everything else keeps going through the
// one mapping in problem.go. It classifies on the SENTINEL rather than on
// prose, as failEdgeReadErr does.
func (s *Server) failBlockingErr(w http.ResponseWriter, r *http.Request, err error) {
if !errors.Is(err, issueops.ErrValidation) {
s.failErr(w, r, err)
return
}
requestInfo(r.Context()).refuse("issue_id")
s.fail(w, r, InvalidArgument("issue_id", ReasonInvalidValue, err.Error()))
}
// wireBlocking projects the role's answer onto the generated envelope, whose
// element type is an ALIAS of the role's own struct — so this is a slice copy
// and nothing else. There is no second wire struct here and there must never be
// one.
//
// It exists for the one thing that is not free: the document says `items` is an
// empty array and never null, so the wire promise does not depend on the role
// keeping its own.
func wireBlocking(result issueops.BlockingResult) apigen.BlockingAnnotations {
if result.Items == nil {
return apigen.BlockingAnnotations{Items: []apigen.IssueBlocking{}}
}
return apigen.BlockingAnnotations{Items: result.Items}
}