Compare commits

...
Sign in to create a new pull request.

4 commits

Author SHA1 Message Date
Eddie the Engineer
d05dac1c3e test(roles): pin the BatchGetter pure tier and the spec ids caps
Review fixes, iteration 1. The review approved with no blocker or major
finding and three minors, and this commit takes all three. It changes
tests and one comment only, and every new assertion was mutation-probed
with go test -overlay.

- storage/issueops: add batchget_test.go, the database-free tier that
  FinishGetMany's doc already claimed ("pinned without a database") but
  that no test supplied. It pins:
  - the cap is checked before the blank scan (an over-cap request with
    a blank at position 0 answers *TooManyIDsError);
  - the bound is inclusive;
  - dedupe keeps the first mention, does not trim, and never writes
    through the caller's slice;
  - Issues and Missing both follow request order;
  - both slices are never nil;
  - ExecuteGetMany refuses one id repeated past the cap before any
    query (a sqlmock with no expectations).
  Ten mutants were each killed by exactly their intended test, with the
  rest of the package green: last-mention, sort, trim, in-place dedupe,
  blank-before-cap, >=, nil Missing, nil Issues, dedupe-before-validate
  and validate-after-query.
- httpapi: TestSpecDefaultsMatchSharedConstants now checks ids.maxItems
  against the enforced bound on the two request bodies that carry an
  `ids` list: batchGetIssues against issueops.MaxGetManyIDs, and
  deleteIssues against maxDeleteIDs. Each body is reached through its
  operation's own requestBody $ref. Setting either constant to 999 turns
  only this test red. The spec's other list caps (batch
  create/close/apply items, dependency edge lists) stay ungated, as
  before.
- cmd/bd/serve.go: the batchGetter field comment said its accessor
  "does NOT recurse through the hook decorator". HookFiringStore.
  BatchGetter does recurse to the inner getter; it just doesn't wrap
  the result. The comment now says that.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 17:40:58 +00:00
Eddie the Engineer
923563f12a fix(roles): sync client vocabulary and repo gates with issues:batchGet
The S7 route landed on the server without the sibling tables that hold
the rest of the tree set-equal with the server's surface, so five
tests and two manifest gates went red on the PR head:

- httpclient/wire: mirror batchGetIssues into the client vocabulary,
  CLASSIFIED, not wired, the way the wire wave and #7250's
  issues.count.scope landed: OpBatchGetIssues, its issues.batchGet
  token on opCapability, its identity row, and the first-slice skew
  dimension 35 -> 36 (TestCapabilityTableMatchesTheServerRouteTable).
- httpclient/wire: BatchGetIssue is the first golden.json schema with
  a `revision` member that needs no legacy-integer tolerance — the
  route postdates #6053 and types.BatchGetIssue declares Revision a
  string, and a pre-#6053 server never advertises issues.batchGet, so
  Preflight refuses before any body is decoded. Exempt it with that
  reason in a new revisionSchemaExempt table rather than adding an
  issues[] rewrite no legacy server can reach; the gate refuses an
  entry that is both covered and exempt, a stale exemption, and an
  empty reason.
- httpclient/encode: give the oracle's role set a BatchGetter stub —
  httpapi.Listen requires the whole set, so all three oracle tests
  failed to bind.
- storage/uow: exempt IssueUseCase.GetMany from the notifying-parity
  partition as a read, the reason hook_batch_getter.go gives.
- shard manifest: place TestBatchGetterContract in the 15-shard
  embedded storage block (generator --write, incremental).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 16:18:57 +00:00
Julian Knutsen
348717787f fix(roles): close S7 review gaps — revision on wire, BUILD sync, handler tests
Addresses the S7 Opus review's FIX-FIRST items on BatchGetter/issues:batchGet:

HIGH
- batchGetResponse now projects apigen.BatchGetIssue (types.BatchGetIssue +
  NewBatchGetIssue), carrying `revision` per issue the way IssueDetails does;
  spec, apigen and the wire-shape golden regenerated (additive, no
  wire_revision bump).
- make bazel-sync: the 12 files missing from BUILD.bazel srcs are back in
  sync across 9 BUILD.bazel files.
- New internal/httpapi/batch_get_test.go: success incl. revision, missing
  ids, empty arrays not null, unknown member refused, missing/null ids
  refused, query parameter refused, 1001 ids refused with the full request
  reaching the role, 1000 ids accepted.

MED
- RunBatchGetterAcceptsExactlyTheCap pins the cap boundary (> vs >=).
- RunBatchGetterHydratesLabels pins Labels survive projection.
- RunBatchGetterReadsOneSnapshot renamed to
  RunBatchGetterSharesOneReadStructurally with a doc that no longer
  overclaims atomicity; a real interleaving test needs a hook on the frozen
  roleFixtureKit, out of scope here.
- Doc comments across ExecuteGetMany, GetManyResult.Issues and the
  BatchGetter interface now say hydration is labels only.

LOW
- failBatchGetErr's doc no longer claims blank entries are "already caught".
- PR #7247 references kept.

Re-ran build/vet/gofmt/lint, make api-check, make bazel-sync(-check), the
full internal/httpapi suite, and all three conformance legs (dolt via the
pinned local server, embeddeddolt, uow) plus targeted cmd/bd serve tests —
all green. Live-mutate-guard reverified: cap >=, dropping Missing from the
response, and clearing Labels each now fail the relevant test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-05 15:47:43 +00:00
Julian Knutsen
d74b4f8a11 feat(roles): BatchGetter role and issues:batchGet route (S7)
Adds BatchGetter.GetMany(ids) -> {Issues, Missing}, a one-snapshot,
order-preserving, deduped, 1000-id-capped batch read, wired through all
three library legs (dolt, embedded dolt, uow) behind the existing
hook/telemetry decorator chain, plus the POST /v0/beads/issues:batchGet
HTTP route (spec, apigen, wire-shape golden, issues.batchGet capability
token). Conformance contract (RunBatchGetter*, 12 cases) passes on all
three legs against real backends. No HTTP client leg yet (waits on the
generator / PR #7247); left as a documented seam on BatchGetter's doc
comment.

CLI GetIssuesByIDs call sites are left unmigrated this slice and marked
with TODO(batchgetter) comments: every call site reads an unbounded id
list today, and GetMany's 1000-id cap has no chunking/fallback in any
caller yet, so swapping them in now would add a new, unhandled failure
mode to already-shipped CLI paths (export, import, molecule port,
ready-explain, wisp sweep).

Verified via three live-mutate guards against
internal/storage/issueops/batchget.go (disabling the cap check, dropping
the Missing append, and replacing ordered iteration with map iteration):
each turns the embedded-dolt contract red, confirming the cap, Missing
reporting, and order-preservation assertions actually catch a break.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-05 15:47:43 +00:00
61 changed files with 2886 additions and 26 deletions

View file

@ -353,6 +353,7 @@
15 8 TestRemoteVerbPlainRemoteWithoutAuthPresentsNone
15 8 TestTransactionCleanupAfterSQLCommitIsIndeterminate
15 9 TestBatchGetterContract
15 9 TestCommenterContract
15 9 TestEmbeddedBatchCloserBackendFailureReturnsNoOutcomes
15 9 TestEmbeddedClaimerReclaimsItsOwnInProgressIssueWithoutWriting

View file

@ -13,6 +13,7 @@ go_library(
"batch_apply_contract.go",
"batch_closer_contract.go",
"batch_creator_contract.go",
"batch_getter_contract.go",
"blocked_state.go",
"blocking_annotator_contract.go",
"bootstrapper_contract.go",

View file

@ -0,0 +1,419 @@
package conformance
import (
"context"
"errors"
"fmt"
"testing"
"github.com/steveyegge/beads/internal/types"
publicops "github.com/steveyegge/beads/issueops"
)
// This file holds the contract every implementation of publicops.BatchGetter
// must satisfy. Each case asserts what issueops/batchgetter.go PROMISES, cited
// by symbol; a backend that disagrees is parked at its own wiring site with
// skipKnownDivergence so the case still runs on the ones that agree.
//
// THREE LEGS, ONE BODY, GraphCounterFixture's reason: all three reach the same
// storage/issueops.ExecuteGetMany, which itself reaches GetIssuesByIDsInTx for
// the actual read. The two stores wrap it in their own read transaction, and
// the unit-of-work provider reaches it through the domain repository, whose
// runner publishes exactly the DBTX method set that function takes. So a
// three-leg run here is ONE READING plus two engine checks and three wrapper
// checks, and the cases are written for that: they assert the result's shape
// and order rather than message text, so a wrapper that loses the request,
// drops ordering or breaks errors.Is is what a per-leg failure would actually
// be.
//
// EVERY CASE NAMES THE EXACT IDS IT SEEDED, GraphCounterFixture's reason: the
// three fixtures share one database per suite and the two store fixtures share
// it with every other role's cases.
type BatchGetterFixture struct {
// IssuePrefix namespaces the ids each assertion seeds, so several of them
// can share one database.
IssuePrefix string
BatchGetter publicops.BatchGetter
// CreateIssue seeds a durable issue in the issues plane.
CreateIssue func(context.Context, *types.Issue, string) error
// CreateWisp seeds an ephemeral issue in the wisps plane. It is a separate
// field rather than an Ephemeral flag on CreateIssue because the three
// adapters reach the two planes through different verbs.
CreateWisp func(context.Context, *types.Issue, string) error
// CountHistory reports how many history entries the fixture's branch has.
// A nil hook means "this backend cannot observe history", and the case that
// needs it SKIPS rather than passing quietly.
CountHistory func(context.Context) (int, error)
}
// RunBatchGetterFindsRequestedIssues pins the found half of GetManyResult: an
// id a GetManyRequest names and the store holds comes back hydrated, with the
// id that resolved it.
func RunBatchGetterFindsRequestedIssues(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
first := fixture.IssuePrefix + "-found-a"
second := fixture.IssuePrefix + "-found-b"
seedBatchGetterIssues(t, ctx, fixture, first, second)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{first, second}})
assertBatchGetterIssueIDs(t, result, first, second)
assertBatchGetterMissingIDs(t, result)
}
// RunBatchGetterReportsMissingIDs pins GetManyResult.Missing: an id naming no
// stored row is reported there, beside whatever else resolved, rather than
// refusing the whole call. The ghost sits BETWEEN two real ids, the same
// placement RunGraphCounterDistinguishesNoEdgesFromNoAnchor uses, so a body
// that short-circuited on the first miss cannot pass by accident.
func RunBatchGetterReportsMissingIDs(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
first := fixture.IssuePrefix + "-missing-real1"
ghost := fixture.IssuePrefix + "-missing-ghost"
second := fixture.IssuePrefix + "-missing-real2"
seedBatchGetterIssues(t, ctx, fixture, first, second)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{first, ghost, second}})
assertBatchGetterIssueIDs(t, result, first, second)
assertBatchGetterMissingIDs(t, result, ghost)
}
// RunBatchGetterCollapsesRepeatedIDs pins GetManyRequest.IDs's repeats clause:
// an id named twice is one entry, at the position of its first mention. The
// repeat is placed AFTER a different id, RunGraphCounterCollapsesRepeatedAnchors'
// reason: a body that de-duplicated by sorting rather than by first mention
// would answer b, a instead of a, b.
func RunBatchGetterCollapsesRepeatedIDs(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
first := fixture.IssuePrefix + "-dup-b"
second := fixture.IssuePrefix + "-dup-a"
seedBatchGetterIssues(t, ctx, fixture, first, second)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{
IDs: []string{first, second, first, second, first},
})
assertBatchGetterIssueIDs(t, result, first, second)
}
// RunBatchGetterAnswersInRequestOrder pins GetManyResult.Issues' ordering
// clause: the answer comes back in the REQUEST's order, never the storage
// engine's natural order. The ids are seeded in the opposite order from the one
// requested, so a body that forwarded the storage engine's order would fail.
func RunBatchGetterAnswersInRequestOrder(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
first := fixture.IssuePrefix + "-order-c"
second := fixture.IssuePrefix + "-order-b"
third := fixture.IssuePrefix + "-order-a"
// Seeded in storage order third, second, first — the reverse of the
// request below — so a body that forwarded insertion order would fail.
seedBatchGetterIssues(t, ctx, fixture, third, second, first)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{first, second, third}})
assertBatchGetterIssueIDs(t, result, first, second, third)
}
// RunBatchGetterResolvesIDsExactly pins the exactness GetManyRequest.IDs
// documents: a prefix of a real id and a real id padded with whitespace are
// both reported Missing rather than resolved, the same exactness
// RunGraphCounterResolvesIDsExactly pins for EdgeCountRequest.IDs.
func RunBatchGetterResolvesIDsExactly(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
real := fixture.IssuePrefix + "-exact-real"
seedBatchGetterIssues(t, ctx, fixture, real)
prefix := real[:len(real)-2]
spaced := " " + real + " "
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{real, prefix, spaced}})
assertBatchGetterIssueIDs(t, result, real)
assertBatchGetterMissingIDs(t, result, prefix, spaced)
}
// RunBatchGetterAnswersAnEmptyRequest pins GetManyRequest.IDs's empty-slice
// clause: no ids is not an error, it is an answer with no issues — and both
// slices are never nil, so a front door that marshals them emits [] rather
// than null.
func RunBatchGetterAnswersAnEmptyRequest(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
result, err := fixture.BatchGetter.GetMany(ctx, publicops.GetManyRequest{})
if err != nil {
t.Fatalf("GetMany with no ids = %v, want an empty answer", err)
}
if len(result.Issues) != 0 {
t.Fatalf("GetMany with no ids returned %d issues, want none", len(result.Issues))
}
if result.Issues == nil {
t.Error("Issues is nil; the contract promises it is never nil for a successful call")
}
if result.Missing == nil {
t.Error("Missing is nil; the contract promises it is never nil for a successful call")
}
}
// RunBatchGetterRefusesAnUnusableRequest pins the request vocabulary
// ValidateGetManyRequest applies: an empty-string id is refused with
// ErrValidation.
func RunBatchGetterRefusesAnUnusableRequest(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
real := fixture.IssuePrefix + "-refuse-real"
seedBatchGetterIssues(t, ctx, fixture, real)
_, err := fixture.BatchGetter.GetMany(ctx, publicops.GetManyRequest{IDs: []string{real, ""}})
if !errors.Is(err, publicops.ErrValidation) {
t.Errorf("GetMany with an empty id beside a real one = %v, want ErrValidation", err)
}
}
// RunBatchGetterRefusesOverTheCap pins MaxGetManyIDs: a request naming more
// ids than the cap is refused with a *publicops.TooManyIDsError that wraps
// ErrValidation, counted on the request as sent, BEFORE deduplication — the
// request below repeats one id past the cap, so a body that checked the
// deduplicated count would wrongly let it through.
func RunBatchGetterRefusesOverTheCap(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
real := fixture.IssuePrefix + "-cap-real"
seedBatchGetterIssues(t, ctx, fixture, real)
ids := make([]string, publicops.MaxGetManyIDs+1)
for i := range ids {
ids[i] = real
}
_, err := fixture.BatchGetter.GetMany(ctx, publicops.GetManyRequest{IDs: ids})
var tooMany *publicops.TooManyIDsError
if !errors.As(err, &tooMany) {
t.Fatalf("GetMany over the cap = %v, want *publicops.TooManyIDsError", err)
}
if tooMany.Requested != len(ids) {
t.Errorf("TooManyIDsError.Requested = %d, want %d (the count before deduplication)", tooMany.Requested, len(ids))
}
if tooMany.Cap != publicops.MaxGetManyIDs {
t.Errorf("TooManyIDsError.Cap = %d, want %d", tooMany.Cap, publicops.MaxGetManyIDs)
}
if !errors.Is(err, publicops.ErrValidation) {
t.Errorf("GetMany over the cap = %v, want it to also match ErrValidation", err)
}
}
// RunBatchGetterAcceptsExactlyTheCap pins the boundary MaxGetManyIDs draws:
// a request naming EXACTLY the cap's worth of distinct ids is accepted and
// answered in full, not refused. RunBatchGetterRefusesOverTheCap pins the
// cap+1 side of this line; without this case a `>` to `>=` mutation on the
// comparison would still refuse a one-over request (cap+1 is still > cap-1)
// and pass that case while silently refusing every legitimate cap-sized
// request.
func RunBatchGetterAcceptsExactlyTheCap(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
ids := make([]string, publicops.MaxGetManyIDs)
for i := range ids {
ids[i] = fmt.Sprintf("%s-atcap-%d", fixture.IssuePrefix, i)
}
seedBatchGetterIssues(t, ctx, fixture, ids...)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: ids})
if len(result.Issues) != publicops.MaxGetManyIDs {
t.Fatalf("GetMany with exactly MaxGetManyIDs (%d) ids returned %d issues, want %d",
publicops.MaxGetManyIDs, len(result.Issues), publicops.MaxGetManyIDs)
}
assertBatchGetterMissingIDs(t, result)
}
// RunBatchGetterHydratesLabels pins that a resolved issue's Labels come back
// populated: hydration for this role is LABELS ONLY (no dependencies,
// dependents or comments — issueops.GetManyResult.Issues documents the
// scope), so Labels is the one piece of relational data a regression here
// could silently drop without any other case noticing.
func RunBatchGetterHydratesLabels(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
id := fixture.IssuePrefix + "-labels-a"
seed := batchGetterSeed(id, false)
seed.Labels = []string{"alpha", "beta"}
if err := fixture.CreateIssue(ctx, seed, "batch-getter-seed"); err != nil {
t.Fatalf("seed issue %s: %v", id, err)
}
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{id}})
assertBatchGetterIssueIDs(t, result, id)
got := result.Issues[0].Labels
want := []string{"alpha", "beta"}
if len(got) != len(want) {
t.Fatalf("GetMany(%s).Labels = %v, want %v", id, got, want)
}
seen := make(map[string]bool, len(got))
for _, l := range got {
seen[l] = true
}
for _, l := range want {
if !seen[l] {
t.Errorf("GetMany(%s).Labels = %v, want it to include %q", id, got, l)
}
}
}
// RunBatchGetterLeavesTheRequestAlone pins the no-mutation clause on
// BatchGetter: IDs is the one member a body could write through to the caller
// — de-duplication is exactly the step that would — and the contract says a
// body de-duplicates into its own copy.
func RunBatchGetterLeavesTheRequestAlone(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
first := fixture.IssuePrefix + "-immutable-a"
second := fixture.IssuePrefix + "-immutable-b"
seedBatchGetterIssues(t, ctx, fixture, first, second)
ids := []string{first, first, second}
getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: ids})
if len(ids) != 3 || ids[0] != first || ids[1] != first || ids[2] != second {
t.Errorf("the request's IDs slice is now %v; the contract says a body de-duplicates into its own copy", ids)
}
}
// RunBatchGetterSharesOneReadStructurally pins the STRUCTURAL half of the
// one-snapshot clause on BatchGetter.GetMany: the existence check and the
// hydration are one call answering one found id and one missing id together
// against a STATIC fixture, which is consistent with — but does not by
// itself PROVE — the two sharing one transaction under a concurrent writer.
// A body that split the probe from the hydration into two round trips could
// still pass this case against a fixture nothing else is mutating, so it
// checks both halves of one GetManyResult instead of asserting on two
// separate calls the way RunBatchGetterFindsRequestedIssues and
// RunBatchGetterReportsMissingIDs do, but it is NOT a concurrency test: no
// writer races the read here.
//
// Renamed from RunBatchGetterReadsOneSnapshot, which overclaimed an
// atomicity guarantee this case alone does not empirically demonstrate. A
// real interleaving test — a concurrent writer racing GetMany's transaction
// so the case can show a found id and a racing create or delete resolve
// consistently with ONE snapshot boundary — needs a synchronization hook
// (e.g. "pause this leg's read transaction after its query, before it
// returns, so a second goroutine can write and commit") that roleFixtureKit
// does not expose today; that kit is FROZEN (see role_fixture_kit_test.go)
// and a role slice does not edit it. Adding the hook is tracked as follow-up
// work rather than done here, so this case stays honestly structural.
func RunBatchGetterSharesOneReadStructurally(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
present := fixture.IssuePrefix + "-snapshot-present"
ghost := fixture.IssuePrefix + "-snapshot-ghost"
seedBatchGetterIssues(t, ctx, fixture, present)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{present, ghost}})
if len(result.Issues) != 1 || len(result.Missing) != 1 {
t.Fatalf("GetMany([%s, %s]) = %d issues, %d missing; want exactly one of each from the same read",
present, ghost, len(result.Issues), len(result.Missing))
}
assertBatchGetterIssueIDs(t, result, present)
assertBatchGetterMissingIDs(t, result, ghost)
}
// RunBatchGetterCrossesBothPlanes pins that GetMany resolves ids regardless of
// which dependency plane stores them: a durable issue and an ephemeral wisp
// named in the same request both come back hydrated.
func RunBatchGetterCrossesBothPlanes(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
issue := fixture.IssuePrefix + "-plane-issue"
wisp := fixture.IssuePrefix + "-plane-wisp"
seedBatchGetterIssues(t, ctx, fixture, issue)
seedBatchGetterWisp(t, ctx, fixture, wisp)
result := getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{issue, wisp}})
assertBatchGetterIssueIDs(t, result, issue, wisp)
}
// RunBatchGetterWritesNothing pins BatchGetter's read clause: a GetMany
// records no history entry. The delta is taken around the calls rather than as
// an absolute count, RunGraphCounterWritesNothing's reason: the seeds above it
// are versioned writes of their own.
func RunBatchGetterWritesNothing(t *testing.T, ctx context.Context, fixture BatchGetterFixture) {
t.Helper()
if fixture.CountHistory == nil {
t.Skip("this backend cannot observe history, so the writes-nothing clause cannot be checked here")
}
real := fixture.IssuePrefix + "-quiet-real"
ghost := fixture.IssuePrefix + "-quiet-ghost"
seedBatchGetterIssues(t, ctx, fixture, real)
before, err := fixture.CountHistory(ctx)
if err != nil {
t.Fatalf("CountHistory before: %v", err)
}
getMany(t, ctx, fixture, publicops.GetManyRequest{IDs: []string{real, ghost}})
// A refusal changes nothing either, so the same delta covers both.
_, _ = fixture.BatchGetter.GetMany(ctx, publicops.GetManyRequest{IDs: []string{""}})
after, err := fixture.CountHistory(ctx)
if err != nil {
t.Fatalf("CountHistory after: %v", err)
}
if after != before {
t.Fatalf("history entries went %d -> %d across two GetMany calls, want no change", before, after)
}
}
func getMany(t *testing.T, ctx context.Context, fixture BatchGetterFixture, request publicops.GetManyRequest) publicops.GetManyResult {
t.Helper()
result, err := fixture.BatchGetter.GetMany(ctx, request)
if err != nil {
t.Fatalf("GetMany(%v): %v", request.IDs, err)
}
return result
}
func seedBatchGetterIssues(t *testing.T, ctx context.Context, fixture BatchGetterFixture, ids ...string) {
t.Helper()
for _, id := range ids {
if err := fixture.CreateIssue(ctx, batchGetterSeed(id, false), "batch-getter-seed"); err != nil {
t.Fatalf("seed issue %s: %v", id, err)
}
}
}
func seedBatchGetterWisp(t *testing.T, ctx context.Context, fixture BatchGetterFixture, id string) {
t.Helper()
if err := fixture.CreateWisp(ctx, batchGetterSeed(id, true), "batch-getter-seed"); err != nil {
t.Fatalf("seed wisp %s: %v", id, err)
}
}
func batchGetterSeed(id string, ephemeral bool) *types.Issue {
return &types.Issue{
ID: id,
Title: id,
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
Ephemeral: ephemeral,
}
}
func batchGetterIssueIDs(result publicops.GetManyResult) []string {
out := make([]string, 0, len(result.Issues))
for _, issue := range result.Issues {
out = append(out, issue.ID)
}
return out
}
func assertBatchGetterIssueIDs(t *testing.T, result publicops.GetManyResult, want ...string) {
t.Helper()
got := batchGetterIssueIDs(result)
if len(got) != len(want) {
t.Fatalf("issues = %v, want %v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("issues = %v, want %v", got, want)
}
}
}
func assertBatchGetterMissingIDs(t *testing.T, result publicops.GetManyResult, want ...string) {
t.Helper()
got := result.Missing
if len(got) != len(want) {
t.Fatalf("missing = %v, want %v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("missing = %v, want %v", got, want)
}
}
if got == nil {
t.Error("Missing is nil; the contract promises it is never nil for a successful call")
}
}

View file

@ -1272,6 +1272,10 @@ func tryIncrementalExport(ctx context.Context, fullPath, fromCommit, toCommit st
var records map[string][]byte
droppedByFilter := make(map[string]bool)
if len(upsertIDs) > 0 {
// TODO(batchgetter): this read is unbounded; issueops.BatchGetter caps a
// request at MaxGetManyIDs (1000) and this call site has not been
// audited for id volume or given chunking, so it still goes through
// GetIssuesByIDs rather than the role. See issueops.BatchGetter's doc.
issues, fetchErr := store.GetIssuesByIDs(ctx, upsertIDs)
if fetchErr != nil {
return 0, 0, nil, false, fmt.Errorf("GetIssuesByIDs: %w", fetchErr)

View file

@ -110,6 +110,11 @@ type ImportChange struct {
// classifiers need. The classic storage.DoltStorage satisfies it, and so does
// the proxied unit of work's domain.IssueUseCase, so both modes classify
// incoming rows against local state with the same code.
// TODO(batchgetter): both callers below read an unbounded id list through
// this interface; issueops.BatchGetter caps a request at MaxGetManyIDs
// (1000) and neither call site has been audited for id volume or given
// chunking, so this interface still names GetIssuesByIDs rather than the
// role. See issueops.BatchGetter's doc.
type importIssueLookup interface {
GetIssuesByIDs(ctx context.Context, ids []string) ([]*types.Issue, error)
}

View file

@ -457,6 +457,9 @@ func findParentMolecules(ctx context.Context, s molReader, issueIDs []string) ma
rootIDs = append(rootIDs, id)
}
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
// the importIssueLookup TODO in import_shared.go for why this is not yet
// routed through the role.
rootIssues, err := s.GetIssuesByIDs(ctx, rootIDs)
if err != nil {
return nil

View file

@ -14,6 +14,12 @@ import (
"github.com/steveyegge/beads/internal/workapi"
)
// TODO(batchgetter): GetIssuesByIDs below reads an unbounded id list;
// issueops.BatchGetter caps a request at MaxGetManyIDs (1000) and this
// interface's one implementation (uowMolReader) has not been audited for id
// volume or given chunking, so it still forwards to
// IssueUseCase().GetIssuesByIDs rather than GetMany. See
// issueops.BatchGetter's doc.
type molReader interface {
GetIssue(ctx context.Context, id string) (*types.Issue, error)
GetIssuesByIDs(ctx context.Context, ids []string) ([]*types.Issue, error)

View file

@ -567,6 +567,9 @@ func runReadyExplain(_ *cobra.Command) error {
}
// Build ready items with explanations
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
// the importIssueLookup TODO in import_shared.go for why this is not yet
// routed through the role.
blockerIssues, err := activeStore.GetIssuesByIDs(ctx, blockerIDList)
if err != nil {
debug.Logf("warning: failed to get blocker issues: %v", err)

View file

@ -330,6 +330,9 @@ func runReadyProxiedExplain(ctx context.Context, uw uow.UnitOfWork, _ readyInput
for id := range allBlockerIDs {
blockerIDList = append(blockerIDList, id)
}
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
// the importIssueLookup TODO in import_shared.go for why this is not yet
// routed through GetMany.
blockerIssues, err := uw.IssueUseCase().GetIssuesByIDs(ctx, blockerIDList)
if err != nil {
debug.Logf("warning: failed to get blocker issues: %v", err)

View file

@ -317,6 +317,7 @@ func runServe() error {
CycleDetector: roles.cycles,
EdgeReader: roles.edges,
GraphCounter: roles.edgeCounter,
BatchGetter: roles.batchGetter,
Relations: roles.relations,
Commenter: roles.commenter,
BlockingAnnotator: roles.blocking,
@ -672,6 +673,7 @@ type serveRoleSource interface {
CycleDetector() (issueops.CycleDetector, error)
EdgeReader() (issueops.EdgeReader, error)
GraphCounter() (issueops.GraphCounter, error)
BatchGetter() (issueops.BatchGetter, error)
IssueRelations() (issueops.Relations, error)
Commenter() (issueops.Commenter, error)
BlockingAnnotator() (issueops.BlockingAnnotator, error)
@ -738,6 +740,7 @@ func serveIssueRoles(src serveRoleSource, journalEnabled bool) (serveRoles, erro
{"cycle detector", func() (err error) { roles.cycles, err = src.CycleDetector(); return }},
{"edge reader", func() (err error) { roles.edges, err = src.EdgeReader(); return }},
{"graph counter", func() (err error) { roles.edgeCounter, err = src.GraphCounter(); return }},
{"batch getter", func() (err error) { roles.batchGetter, err = src.BatchGetter(); return }},
{"issue relations", func() (err error) { roles.relations, err = src.IssueRelations(); return }},
{"commenter", func() (err error) { roles.commenter, err = src.Commenter(); return }},
{"blocking annotator", func() (err error) { roles.blocking, err = src.BlockingAnnotator(); return }},
@ -838,13 +841,19 @@ type serveRoles struct {
// hook decorator like the two below it — a release is an update, so
// HookFiringStore.Releaser fires the workspace's on_update script — which
// is why it comes off the PEELED store with the rest.
releaser issueops.Releaser
lifecycle issueops.Lifecycle
settings issueops.WorkspaceConfig
stats issueops.StatsReporter
cycles issueops.CycleDetector
edges issueops.EdgeReader
edgeCounter issueops.GraphCounter
releaser issueops.Releaser
lifecycle issueops.Lifecycle
settings issueops.WorkspaceConfig
stats issueops.StatsReporter
cycles issueops.CycleDetector
edges issueops.EdgeReader
edgeCounter issueops.GraphCounter
// batchGetter is the one-snapshot, many-ids read behind
// POST /v0/beads/issues:batchGet. Its hook decorator recurses to the inner
// getter WITHOUT wrapping it — a read fires no completion hooks — so it is
// taken off the peeled store with the rest for uniformity rather than out
// of necessity.
batchGetter issueops.BatchGetter
relations issueops.Relations
commenter issueops.Commenter
blocking issueops.BlockingAnnotator

View file

@ -106,6 +106,7 @@ func TestServeIssueRolesComeFromBeneathTheHookDecorator(t *testing.T) {
metadataCAS: &serveStubMetadataCAS{},
counter: &serveStubCounter{},
edgeCounter: &serveStubGraphCounter{},
batchGetter: &serveStubBatchGetter{},
relations: &serveStubRelations{},
commenter: &serveStubCommenter{},
batchCreator: &serveStubBatchCreator{},
@ -411,6 +412,7 @@ type serveRolesStore struct {
metadataCAS *serveStubMetadataCAS
counter *serveStubCounter
edgeCounter *serveStubGraphCounter
batchGetter *serveStubBatchGetter
relations *serveStubRelations
commenter *serveStubCommenter
batchCreator *serveStubBatchCreator
@ -519,6 +521,10 @@ func (s *serveRolesStore) Counter() (issueops.Counter, error) { return s.counter
// moment the binding landed.
func (s *serveRolesStore) GraphCounter() (issueops.GraphCounter, error) { return s.edgeCounter, nil }
// BatchGetter is declared for GraphCounter's reason: the many-ids read is also
// a read, so hook_batch_getter.go recurses and the recursion lands here.
func (s *serveRolesStore) BatchGetter() (issueops.BatchGetter, error) { return s.batchGetter, nil }
// IssueRelations is the FIRST role added to serveIssueRoles since this type
// stopped embedding a nil store, and it is worth recording what that changed —
// because the two comments above it describe the old regime and are now history
@ -587,6 +593,14 @@ func (*serveStubGraphCounter) CountEdges(context.Context, issueops.EdgeCountRequ
return issueops.EdgeCountResult{}, errors.ErrUnsupported
}
// serveStubBatchGetter is the many-ids read role's stand-in, ErrUnsupported
// like every stub here.
type serveStubBatchGetter struct{}
func (*serveStubBatchGetter) GetMany(context.Context, issueops.GetManyRequest) (issueops.GetManyResult, error) {
return issueops.GetManyResult{}, errors.ErrUnsupported
}
// serveStubCounter is the count role's stand-in. It answers ErrUnsupported like
// every stub here: this file's subject is which LAYER a role comes from, never
// what the role answers.

View file

@ -235,6 +235,14 @@ func (*serveIdentityStore) GraphCounter() (issueops.GraphCounter, error) {
return serveIdentityRole{}, nil
}
// BatchGetter is declared at depth 1 for GraphCounter's reason: the many-ids
// read is also a read, so its hook decorator (hook_batch_getter.go) recurses
// and the recursion would land on a nil-embedded promotion if this were not
// here.
func (*serveIdentityStore) BatchGetter() (issueops.BatchGetter, error) {
return serveIdentityRole{}, nil
}
// IssueRelations is the first role added to serveIssueRoles since this stub
// stopped embedding a nil store, so the comment above it is now a record of the
// old regime rather than a warning about this one: GraphCounter had to be found
@ -297,6 +305,7 @@ type serveIdentityRole struct {
issueops.CycleDetector
issueops.EdgeReader
issueops.GraphCounter
issueops.BatchGetter
issueops.Relations
issueops.Commenter
issueops.BlockingAnnotator

View file

@ -879,6 +879,9 @@ func findAbandonedWisps(ctx context.Context, r molReader, cleanAll bool, ageThre
for id := range childIDs {
childIDSlice = append(childIDSlice, id)
}
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc
// and the importIssueLookup TODO in import_shared.go for why this is
// not yet routed through the role.
childIssues, fetchErr := r.GetIssuesByIDs(ctx, childIDSlice)
if fetchErr == nil {
abandonedSet := make(map[string]bool, len(abandoned))

View file

@ -7,6 +7,7 @@ go_library(
"batch_apply.go",
"batch_close.go",
"batch_create.go",
"batch_get.go",
"blocking.go",
"claim.go",
"claim_next.go",
@ -65,6 +66,7 @@ go_test(
"batch_apply_test.go",
"batch_close_test.go",
"batch_create_test.go",
"batch_get_test.go",
"blocking_test.go",
"brief_projection_test.go",
"claim_next_test.go",

View file

@ -818,6 +818,30 @@ type BatchCreateResponse struct {
Items []Issue `json:"items"`
}
// BatchGetIssue One resolved entry of `BatchGetIssuesResult.issues`: an `Issue` plus its current `revision`. Property semantics other than `revision` are documented on `Issue`; the spec repeats the list rather than composing it (see the note at the top of this document).
type BatchGetIssue = types.BatchGetIssue
// BatchGetIssuesRequest Which issues to read, in one snapshot. There is no predicate here — the caller already knows the ids — which is `DeleteIssuesRequest`'s own reason for carrying none.
//
// `additionalProperties: false`, so an unknown member is a `400` naming the member.
type BatchGetIssuesRequest struct {
// Ids The issues to read, exact ids, in either plane. DUPLICATES COLLAPSE: a repeated id is answered once, in the position of its first mention. An EMPTY array is legal and answers with both `issues` and `missing` empty — it is not refused the way `DeleteIssuesRequest.ids` refuses one, because a read that found nothing to read is not a mistake the way a delete that erased nothing usually is.
//
// The cap is on the REQUEST, counted before deduplication: a caller sending 1500 mentions of 3 distinct ids still names a request this operation refuses, because the obligation the cap bounds is reading the request apart, not reading the rows it resolves to.
Ids []string `json:"ids"`
}
// BatchGetIssuesResult The issues that resolved, hydrated, plus the ids that did not — both read from the SAME snapshot. Never a `404`: an id naming no stored row is reported in `missing`, not refused, the same set-read answer `DependencyEdges` and `EdgeCounts` give.
type BatchGetIssuesResult struct {
// Issues One entry per requested id that resolved, in the REQUEST's order (the caller's first mention of each distinct id), never the storage engine's natural order. Each issue carries its current `revision`, so a caller that goes on to write one back has the optimistic-concurrency token a lifecycle write wants without a second round trip. Empty array (never null) when nothing resolved.
//
// HYDRATION IS LABELS ONLY: no dependencies, dependents or comments — use `GET /v0/beads/issues/{id}` (`IssueDetails`) for those.
Issues []BatchGetIssue `json:"issues"`
// Missing The requested ids that resolved to no stored row, in the same first-mention order as the request. An id here contributes no entry to `issues`, and the two arrays' lengths always sum to the number of DISTINCT ids the request named. Empty array (never null) when every named id resolved.
Missing []string `json:"missing"`
}
// Blocker One live blocker named by a blocked-issue refusal.
type Blocker struct {
// Id The blocker: a local issue id, or the full `external:<project>:<capability>` reference.
@ -1010,7 +1034,7 @@ type ContextResponse struct {
// OPTIONAL, and absent means only that this server does not disclose its filesystem layout — never that it has no workspace. A client MUST NOT require it, MUST NOT treat absence as an error, and has no use for the value beyond display: it is a path on the SERVER's filesystem, which the client cannot open. Identify the workspace by `project_id` and `database`, which are required.
BeadsDir *string `json:"beads_dir,omitempty"`
// Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway, and `issues.list.sort`, which announces that `GET /v0/beads/issues` accepts the `sort` query parameter (two closed, pageable total orders — see that parameter) rather than silently answering `unknown_parameter`, and `issues.count.scope`, which announces that `GET /v0/beads/issues:count` accepts `parent`, `no_parent`, `exclude_type`, and `exclude_status` (see those parameters) rather than silently answering `unknown_parameter` for all four. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string.
// Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchGet`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway, and `issues.list.sort`, which announces that `GET /v0/beads/issues` accepts the `sort` query parameter (two closed, pageable total orders — see that parameter) rather than silently answering `unknown_parameter`, and `issues.count.scope`, which announces that `GET /v0/beads/issues:count` accepts `parent`, `no_parent`, `exclude_type`, and `exclude_status` (see those parameters) rather than silently answering `unknown_parameter` for all four. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string.
//
// THIS LIST IS BUILD-LEVEL, NOT WORKSPACE-LEVEL. It says which operations this binary serves, and for every entry but two that is the whole answer. `events.list` and `events.watch` are the exceptions: the durable events journal is a per-workspace setting that is OFF by default, so a server that advertises them may still refuse every request to both with 409 `events_journal_disabled` — correctly, because the operations exist and the workspace has no journal. A consumer of either MUST treat the capability as "this server speaks it" and the 409 as "not on this workspace", and must not read the capability as a promise that records will arrive.
Capabilities []string `json:"capabilities"`
@ -2713,6 +2737,9 @@ type BatchCloseIssuesJSONRequestBody = BatchCloseRequest
// BatchCreateIssuesJSONRequestBody defines body for BatchCreateIssues for application/json ContentType.
type BatchCreateIssuesJSONRequestBody = BatchCreateRequest
// BatchGetIssuesJSONRequestBody defines body for BatchGetIssues for application/json ContentType.
type BatchGetIssuesJSONRequestBody = BatchGetIssuesRequest
// ClaimNextIssueJSONRequestBody defines body for ClaimNextIssue for application/json ContentType.
type ClaimNextIssueJSONRequestBody = ClaimNextRequest

View file

@ -0,0 +1,165 @@
package httpapi
import (
"encoding/json"
"errors"
"net/http"
"slices"
"strings"
"github.com/steveyegge/beads/internal/httpapi/apigen"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// The request body's whole member vocabulary. The schema is
// additionalProperties: false, so anything else is refused BY NAME, the same
// discipline deleteMembers documents.
const batchGetIDsMember = "ids"
// batchGetMembers is the whole vocabulary, in one place, for batchGetMemberList
// below.
var batchGetMembers = []string{batchGetIDsMember}
// handleBatchGetIssues answers POST /v0/beads/issues:batchGet.
//
// WHAT THIS HANDLER DOES NOT DO is the point of it, as for delete and sweep.
// It does not decide which id is missing, does not pick a snapshot, and does
// not hydrate a row. All of that is issueops.BatchGetter, the same library
// surface gc's ready veto and the CLI's own id-resolution passes are meant to
// move onto (see the role's own doc for the migration this slice did not make
// — the HTTP client leg waits on the generator). Everything above the role
// here is argument validation and projection.
//
// NO ACTOR, NO VERSION GUARD, NO FLAGS: this operation reads and changes
// nothing, so it carries none of delete's write vocabulary. Its only member is
// `ids`.
func (s *Server) handleBatchGetIssues(w http.ResponseWriter, r *http.Request) {
if !s.requireNoQuery(w, r) {
return
}
if !s.requireJSONContent(w, r) {
return
}
request, ok := s.batchGetRequest(w, r)
if !ok {
return
}
getter, err := s.batchGetter(r)
if err != nil {
s.failErr(w, r, err)
return
}
result, err := getter.GetMany(r.Context(), request)
if err != nil {
s.failBatchGetErr(w, r, err)
return
}
writeJSON(w, batchGetResponse(result))
}
// batchGetRequest decodes the body into the role's request.
//
// UNLIKE delete's handler, it enforces NEITHER the cap NOR the per-entry blank
// check itself. Both reach the wire through the role's own ErrValidation and
// failBatchGetErr below, and that is deliberate rather than an omission: `ids`
// is the ONLY member this operation has, so there is no second member a
// pre-check could need to disambiguate from, and checking here first would
// risk disagreeing with ValidateGetManyRequest's own order — the cap is
// checked BEFORE the blank-entry scan, against the request as sent — for a
// request that trips both. Letting the role answer keeps the wire's order
// identical to the library's, by construction.
func (s *Server) batchGetRequest(w http.ResponseWriter, r *http.Request) (issueops.GetManyRequest, bool) {
members, res := decodeJSONObjectBody(w, r)
if res != nil {
s.fail(w, r, *res)
return issueops.GetManyRequest{}, false
}
var unknown []string
for name := range members {
if !slices.Contains(batchGetMembers, name) {
unknown = append(unknown, name)
}
}
if len(unknown) > 0 {
offender := slices.Min(unknown)
requestInfo(r.Context()).refuse(offender)
s.fail(w, r, InvalidArgument(offender, ReasonUnknownParameter,
"this operation's request body carries "+batchGetMemberList()+" and nothing else"))
return issueops.GetManyRequest{}, false
}
raw, ok := members[batchGetIDsMember]
if !ok {
s.fail(w, r, InvalidArgument(batchGetIDsMember, ReasonInvalidValue,
"`"+batchGetIDsMember+"` is required"))
return issueops.GetManyRequest{}, false
}
var ids *[]string
if err := json.Unmarshal(raw, &ids); err != nil || ids == nil {
s.fail(w, r, InvalidArgument(batchGetIDsMember, ReasonInvalidValue,
"`"+batchGetIDsMember+"` must be an array of strings"))
return issueops.GetManyRequest{}, false
}
return issueops.GetManyRequest{IDs: *ids}, true
}
func batchGetMemberList() string {
quoted := make([]string, len(batchGetMembers))
for i, name := range batchGetMembers {
quoted[i] = "`" + name + "`"
}
return strings.Join(quoted, ", ")
}
// failBatchGetErr answers a failed batch get. The role's only refusal over the
// wire is ErrValidation — an oversized `ids` (*issueops.TooManyIDsError,
// counted before deduplication); there is no handler-side blank-entry
// pre-check to catch anything first, so EVERY validation failure, blank
// entries included, reaches the wire through this function, which is why
// batchGetRequest above enforces neither the cap nor the per-entry blank
// check itself. Nothing here is a 404 or a 409: a batch read reports a miss
// in the response body, it does not refuse the request over one, and this
// operation changes nothing to guard.
//
// UNLIKE failDeleteErr, it takes no request value: this operation has no
// version-mismatch case (it writes nothing) and only one member to blame, so
// there is nothing in the request this function would need to read.
func (s *Server) failBatchGetErr(w http.ResponseWriter, r *http.Request, err error) {
if !errors.Is(err, issueops.ErrValidation) {
s.failErr(w, r, err)
return
}
requestInfo(r.Context()).refuse(batchGetIDsMember)
s.fail(w, r, InvalidArgument(batchGetIDsMember, ReasonInvalidValue, err.Error()))
}
// batchGetResponse projects the role's result onto the wire envelope.
//
// Both members are non-nil so the body carries `[]` rather than `null` on an
// empty answer, the same promise wireEdges and deleteResponse's `orphaned`
// make. `issues` holds `apigen.BatchGetIssue`, each built by
// types.NewBatchGetIssue rather than a bare `apigen.Issue`: Issue.RowVersion
// is `json:"-"`, so the Issue body alone cannot carry the row's revision, and
// NewBatchGetIssue is the one projection that puts it on the wire the same
// way NewIssueDetails does for `GET /v0/beads/issues/{id}`.
// GetManyResult.Issues never carries a nil entry for a successful call, and a
// wire array of pointers would let json encode a `null` element the role's
// own contract forbids, so each entry is dereferenced before projection.
func batchGetResponse(result issueops.GetManyResult) apigen.BatchGetIssuesResult {
body := apigen.BatchGetIssuesResult{
Issues: []apigen.BatchGetIssue{},
Missing: []string{},
}
for _, issue := range result.Issues {
if issue == nil {
continue
}
body.Issues = append(body.Issues, types.NewBatchGetIssue(*issue))
}
body.Missing = append(body.Missing, result.Missing...)
return body
}

View file

@ -0,0 +1,303 @@
package httpapi
import (
"encoding/json"
"fmt"
"net/http"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// These cover the transport half of POST /v0/beads/issues:batchGet — the body
// shape, this operation's own bounds, and how the role's result is projected
// onto the wire. Everything below the wire (the cap, deduplication, snapshot
// sharing, labels-only hydration) is issueops.BatchGetter's, pinned by
// backend/conformance/batch_getter_contract.go at all three backends.
const batchGetPath = "/v0/beads/issues:batchGet"
func newBatchGetServer(t *testing.T, getter *roleBatchGetter) *testServer {
t.Helper()
return newTestServer(t, rolesConfig(Config{BatchGetter: getter}))
}
func batchGetIssue(id string, rowVersion int64) *types.Issue {
return &types.Issue{
ID: id,
Title: "title for " + id,
Priority: 1,
IssueType: types.TypeTask,
Status: types.StatusOpen,
Labels: []string{"api"},
RowVersion: rowVersion,
CreatedAt: time.Date(2026, 7, 31, 12, 0, 0, 0, time.UTC),
UpdatedAt: time.Date(2026, 7, 31, 12, 0, 0, 0, time.UTC),
}
}
// TestBatchGetIssuesAnswersWithRevision pins HIGH item 1: each item in
// `issues` carries its own `revision`, projected from the issue's RowVersion
// the same way IssueDetails.Revision is for GET /v0/beads/issues/{id}. The
// fixture uses guardToken, past 2^53, so a response member that had been
// decoded (or encoded) as a float64 anywhere on this path would read back a
// NEARBY number rather than the real one.
func TestBatchGetIssuesAnswersWithRevision(t *testing.T) {
issue := batchGetIssue("bd-1", guardToken)
getter := &roleBatchGetter{result: issueops.GetManyResult{
Issues: []*types.Issue{issue},
Missing: []string{},
}}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, `{"ids":["bd-1"]}`)
if resp.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp))
}
raw := readAll(t, resp)
var body struct {
Issues []struct {
ID *string `json:"id"`
Revision *string `json:"revision"`
} `json:"issues"`
Missing []string `json:"missing"`
}
if err := json.Unmarshal([]byte(raw), &body); err != nil {
t.Fatalf("decode %q: %v", raw, err)
}
if len(body.Issues) != 1 {
t.Fatalf("issues = %v, want 1 entry: %s", body.Issues, raw)
}
got := body.Issues[0]
if got.ID == nil || *got.ID != "bd-1" {
t.Errorf("id = %v, want bd-1", got.ID)
}
if got.Revision == nil {
t.Fatalf("the issue carries no `revision`: %s", raw)
}
token, err := types.ParseRevisionToken(*got.Revision)
if err != nil {
t.Fatalf("parse revision %q: %v", *got.Revision, err)
}
if token != guardToken {
t.Errorf("revision = %d, want the row's %d", token, guardToken)
}
if len(body.Missing) != 0 {
t.Errorf("missing = %v, want none", body.Missing)
}
reqs := getter.getManyRequests()
if len(reqs) != 1 || len(reqs[0].IDs) != 1 || reqs[0].IDs[0] != "bd-1" {
t.Fatalf("role calls = %+v, want one call naming bd-1", reqs)
}
}
// TestBatchGetIssuesReportsMissingIDs pins that an id naming no stored row
// comes back in `missing` rather than vanishing or refusing the request, and
// that a found id and a missing one can ride in the same answer.
func TestBatchGetIssuesReportsMissingIDs(t *testing.T) {
issue := batchGetIssue("bd-1", 1)
getter := &roleBatchGetter{result: issueops.GetManyResult{
Issues: []*types.Issue{issue},
Missing: []string{"bd-gone"},
}}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, `{"ids":["bd-1","bd-gone"]}`)
if resp.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp))
}
body := decodeBody(t, resp)
missing, _ := body["missing"].([]any)
if len(missing) != 1 || missing[0] != "bd-gone" {
t.Errorf("missing = %v, want [bd-gone]", body["missing"])
}
issues, _ := body["issues"].([]any)
if len(issues) != 1 {
t.Errorf("issues = %v, want exactly the one found row", body["issues"])
}
}
// TestBatchGetIssuesAnswersEmptyArraysNotNull pins the one thing a Go nil
// slice gets wrong on the way out, for BOTH members: a client is entitled to
// range over `issues` and `missing` without a nil check even when neither
// carries anything.
func TestBatchGetIssuesAnswersEmptyArraysNotNull(t *testing.T) {
getter := &roleBatchGetter{result: issueops.GetManyResult{
Issues: []*types.Issue{},
Missing: []string{"bd-gone"},
}}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, `{"ids":["bd-gone"]}`)
if resp.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp))
}
raw := readAll(t, resp)
if !strings.Contains(raw, `"issues":[]`) {
t.Errorf("body = %s, want an empty `issues` array rather than null", raw)
}
allMissing := &roleBatchGetter{result: issueops.GetManyResult{
Issues: []*types.Issue{},
Missing: []string{},
}}
ts2 := newBatchGetServer(t, allMissing)
resp2 := ts2.claim(t, batchGetPath, `{"ids":[]}`)
if resp2.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200: %s", resp2.StatusCode, readAll(t, resp2))
}
raw2 := readAll(t, resp2)
if !strings.Contains(raw2, `"missing":[]`) {
t.Errorf("body = %s, want an empty `missing` array rather than null", raw2)
}
}
// TestBatchGetIssuesRefusesAnUnknownMember pins that the body is
// additionalProperties: false and the refusal names the offending member: `ids`
// is the whole vocabulary.
func TestBatchGetIssuesRefusesAnUnknownMember(t *testing.T) {
getter := &roleBatchGetter{}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, `{"ids":["bd-1"],"dry_run":true}`)
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
}
body := decodeBody(t, resp)
if body["code"] != string(CodeInvalidArgument) {
t.Errorf("code = %v, want %q", body["code"], CodeInvalidArgument)
}
if body["param"] != "dry_run" {
t.Errorf("param = %v, want dry_run", body["param"])
}
if calls := getter.getManyRequests(); len(calls) != 0 {
t.Errorf("the role was called %d times for a refused request", len(calls))
}
}
// TestBatchGetIssuesRefusesAMissingOrNullIDs pins that `ids` is required and
// must actually be an array: absent and explicit null are both refused, before
// the role is ever reached.
func TestBatchGetIssuesRefusesAMissingOrNullIDs(t *testing.T) {
for _, tc := range []struct {
name string
body string
}{
{"no ids member at all", `{}`},
{"ids is explicitly null", `{"ids":null}`},
{"ids is a string, not an array", `{"ids":"bd-1"}`},
} {
t.Run(tc.name, func(t *testing.T) {
getter := &roleBatchGetter{}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, tc.body)
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
}
body := decodeBody(t, resp)
if body["code"] != string(CodeInvalidArgument) {
t.Errorf("code = %v, want %q", body["code"], CodeInvalidArgument)
}
if body["param"] != "ids" {
t.Errorf("param = %v, want ids", body["param"])
}
if calls := getter.getManyRequests(); len(calls) != 0 {
t.Errorf("the role was called %d times for a refused request", len(calls))
}
})
}
}
// TestBatchGetIssuesRefusesAQueryParameter pins that the document-level
// unknown-parameter rule reaches this operation too: it declares no
// parameters, so every query key is refused.
func TestBatchGetIssuesRefusesAQueryParameter(t *testing.T) {
getter := &roleBatchGetter{}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath+"?dry_run=true", `{"ids":["bd-1"]}`)
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
}
body := decodeBody(t, resp)
if body["param"] != "dry_run" || body["reason"] != string(ReasonUnknownParameter) {
t.Errorf("param/reason = %v/%v, want dry_run/unknown_parameter", body["param"], body["reason"])
}
if calls := getter.getManyRequests(); len(calls) != 0 {
t.Errorf("the role was called %d times for a refused request", len(calls))
}
}
// TestBatchGetIssuesRefusesOverTheCap pins the wire's half of MaxGetManyIDs:
// the fake stands in for the role's own refusal (as
// TestCountDependencyEdgesNamesTheRefusedParameter does for GraphCounter),
// and the handler still answers 400 with the error envelope the operation's
// only member takes, naming the FULL 1001-entry request as sent.
func TestBatchGetIssuesRefusesOverTheCap(t *testing.T) {
const over = issueops.MaxGetManyIDs + 1
getter := &roleBatchGetter{err: &issueops.TooManyIDsError{Requested: over, Cap: issueops.MaxGetManyIDs}}
ts := newBatchGetServer(t, getter)
ids := make([]string, over)
for i := range ids {
ids[i] = fmt.Sprintf(`"bd-%d"`, i)
}
resp := ts.claim(t, batchGetPath, `{"ids":[`+strings.Join(ids, ",")+`]}`)
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp))
}
body := decodeBody(t, resp)
if body["code"] != string(CodeInvalidArgument) {
t.Errorf("code = %v, want %q", body["code"], CodeInvalidArgument)
}
if body["param"] != "ids" {
t.Errorf("param = %v, want ids", body["param"])
}
if body["reason"] != string(ReasonInvalidValue) {
t.Errorf("reason = %v, want invalid_value", body["reason"])
}
reqs := getter.getManyRequests()
if len(reqs) != 1 {
t.Fatalf("role calls = %d, want 1: the role, not the handler, is where this is counted", len(reqs))
}
if len(reqs[0].IDs) != over {
t.Errorf("the role received %d ids, want the full %d sent: the handler must not pre-trim the request", len(reqs[0].IDs), over)
}
}
// TestBatchGetIssuesAcceptsExactlyTheCap pins the wire's half of the
// boundary MED item 4 names at the role: a request at exactly MaxGetManyIDs
// is not refused by anything above the role, so every id reaches it.
func TestBatchGetIssuesAcceptsExactlyTheCap(t *testing.T) {
const atCap = issueops.MaxGetManyIDs
ids := make([]string, atCap)
issues := make([]*types.Issue, atCap)
for i := range ids {
id := fmt.Sprintf("bd-%d", i)
ids[i] = `"` + id + `"`
issues[i] = batchGetIssue(id, 1)
}
getter := &roleBatchGetter{result: issueops.GetManyResult{
Issues: issues,
Missing: []string{},
}}
ts := newBatchGetServer(t, getter)
resp := ts.claim(t, batchGetPath, `{"ids":[`+strings.Join(ids, ",")+`]}`)
if resp.StatusCode != http.StatusOK {
t.Fatalf("at the cap: status = %d, want 200: %s", resp.StatusCode, readAll(t, resp))
}
reqs := getter.getManyRequests()
if len(reqs) != 1 || len(reqs[0].IDs) != atCap {
t.Fatalf("the role received %d ids, want the full %d at the cap", len(reqs[0].IDs), atCap)
}
}
var _ issueops.BatchGetter = (*roleBatchGetter)(nil)

View file

@ -349,6 +349,7 @@ var (
_ uow.CycleDetectorSource = timedProvider{}
_ uow.EdgeReaderSource = timedProvider{}
_ uow.GraphCounterSource = timedProvider{}
_ uow.BatchGetterSource = timedProvider{}
_ uow.RelationsSource = timedProvider{}
_ uow.CommenterSource = timedProvider{}
_ uow.BlockingAnnotatorSource = timedProvider{}
@ -467,6 +468,12 @@ func (p timedProvider) GraphCounter() (issueops.GraphCounter, error) {
return uow.NewGraphCounter(p)
}
// BatchGetter builds the batch-read role OVER THIS WRAPPER, for the same
// reason and with the same hazard as IssueReader.
func (p timedProvider) BatchGetter() (issueops.BatchGetter, error) {
return uow.NewBatchGetter(p)
}
// IssueRelations builds the single-anchor neighbor role OVER THIS WRAPPER, for
// the same reason and with the same hazard as IssueReader. It is the one
// accessor here whose name is not the role's: the seam spells it IssueRelations

View file

@ -27,6 +27,7 @@ var (
_ apigen.Issue = types.Issue{}
_ apigen.IssueWithCounts = types.IssueWithCounts{}
_ apigen.IssueDetails = types.IssueDetails{}
_ apigen.BatchGetIssue = types.BatchGetIssue{}
_ apigen.IssueWithDependencyMetadata = types.IssueWithDependencyMetadata{}
_ apigen.Dependency = types.Dependency{}
_ apigen.TreeNode = types.TreeNode{}
@ -71,6 +72,7 @@ var (
_ []types.Dependency = apigen.DependencyEdges{}.Items
_ []issueops.IssueBlocking = apigen.BlockingAnnotations{}.Items
_ []types.Issue = apigen.BatchCreateResponse{}.Items
_ []types.BatchGetIssue = apigen.BatchGetIssuesResult{}.Issues
_ []eventsjournal.Record = apigen.EventsPage{}.Records
)

View file

@ -459,6 +459,13 @@ const (
// answers about a set of ISSUES described by a predicate, and this one about
// EDGES anchored on ids, per anchor.
OpCountDependencyEdges = "countDependencyEdges"
// OpBatchGetIssues reads several issues by id in ONE snapshot, behind
// issueops.BatchGetter. It is NOT getIssue repeated: that operation names
// one id and answers 404 on a miss, and this one names many and reports an
// absent id in `missing` beside whatever else resolved — the set-read
// answer EdgeCountRequest.IDs and EdgeReadRequest already give, applied to
// the issues themselves rather than their edges.
OpBatchGetIssues = "batchGetIssues"
// OpListRelatedIssues reads ONE issue's neighbors in a named direction,
// behind issueops.Relations. It is NOT listDependencies narrowed to one
// anchor: that operation answers the stored edge ROWS with their targets
@ -707,6 +714,12 @@ var operationCodes = map[string][]Code{
// client as the 400 it is, on the sentinel, with the parameter named in the
// validator's own order.
OpCountDependencyEdges: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
// No not_found, for OpListDependencies' reason restated about issues rather
// than edges: an id naming no stored row is reported in `missing`, not
// refused, so this operation's only 400s are the role's own — an oversized
// `ids` (*issueops.TooManyIDsError) and a blank entry. An empty `ids` is
// legal and answers with an empty result, so it earns no refusal at all.
OpBatchGetIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
// The same vocabulary as the stored-edge read beside it, and no not_found
// for a stronger version of the same reason: this operation probes no id's
// existence at all, so there is nothing it could 404 on.

View file

@ -134,6 +134,34 @@ func (c *roleGraphCounter) countRequests() []issueops.EdgeCountRequest {
return append([]issueops.EdgeCountRequest(nil), c.counts...)
}
// roleBatchGetter is the many-ids read role of the store-shaped source, its own
// fake beside roleGraphCounter for its same reason: a separate role on a
// separate accessor, so one fake answering both would let a test pass on a
// server that had wired the batch-get handler to the wrong role.
type roleBatchGetter struct {
result issueops.GetManyResult
err error
mu sync.Mutex
calls []issueops.GetManyRequest
}
func (g *roleBatchGetter) GetMany(_ context.Context, req issueops.GetManyRequest) (issueops.GetManyResult, error) {
g.mu.Lock()
g.calls = append(g.calls, req)
g.mu.Unlock()
if g.err != nil {
return issueops.GetManyResult{}, g.err
}
return g.result, nil
}
func (g *roleBatchGetter) getManyRequests() []issueops.GetManyRequest {
g.mu.Lock()
defer g.mu.Unlock()
return append([]issueops.GetManyRequest(nil), g.calls...)
}
// roleRelations is the single-anchor NEIGHBOR role of the store-shaped source,
// its own fake beside roleEdgeReader for roleGraphCounter's reason: the two sit
// on adjacent accessors and answer about the same edges, so one fake serving
@ -929,6 +957,9 @@ func rolesConfig(cfg Config) Config {
if cfg.GraphCounter == nil {
cfg.GraphCounter = &roleGraphCounter{}
}
if cfg.BatchGetter == nil {
cfg.BatchGetter = &roleBatchGetter{}
}
if cfg.Relations == nil {
cfg.Relations = &roleRelations{}
}

View file

@ -728,6 +728,19 @@ var routeTable = []route{
implemented: true,
handler: (*Server).handleDelete,
},
{
op: OpBatchGetIssues,
method: http.MethodPost,
// A literal collection-level custom method, registered and preferred
// over the claim's wildcard for the sweep row's reason. POST rather
// than GET: the request names up to MaxGetManyIDs ids, which does not
// fit a query string reliably, and the delete beside it makes the same
// choice for the same reason.
pattern: "/v0/beads/issues:batchGet",
capability: "issues.batchGet",
implemented: true,
handler: (*Server).handleBatchGetIssues,
},
{
op: OpAddDependencies,
method: http.MethodPost,

View file

@ -279,6 +279,14 @@ type Config struct {
// and neither can answer the other's question. Required on the same terms
// as every field here.
GraphCounter issueops.GraphCounter
// BatchGetter is the one-snapshot, many-ids read behind
// POST /v0/beads/issues:batchGet. It is a SEPARATE field from Reader for
// the reason EdgeReader and GraphCounter are separate from each other:
// Reader.Get answers ONE id with *IssueDetails or ErrNotFound, and this
// answers MANY ids with a result whose Missing field reports an absent row
// rather than refusing the call. Required on the same terms as every field
// here.
BatchGetter issueops.BatchGetter
// Relations is the single-anchor neighbor read behind
// GET /v0/beads/issues/{id}/related. It is a SEPARATE field from EdgeReader
// for the reason issueops.EdgeReader's own doc gives at length: that role
@ -414,6 +422,7 @@ type Server struct {
issueCycles issueops.CycleDetector
issueEdges issueops.EdgeReader
issueEdgeCounter issueops.GraphCounter
issueBatchGetter issueops.BatchGetter
issueRelations issueops.Relations
issueCommenter issueops.Commenter
issueBlocking issueops.BlockingAnnotator
@ -625,6 +634,7 @@ func Listen(cfg Config) (*Server, error) {
issueCycles: cfg.CycleDetector,
issueEdges: cfg.EdgeReader,
issueEdgeCounter: cfg.GraphCounter,
issueBatchGetter: cfg.BatchGetter,
issueRelations: cfg.Relations,
issueCommenter: cfg.Commenter,
issueBlocking: cfg.BlockingAnnotator,
@ -747,12 +757,12 @@ func Listen(cfg Config) (*Server, error) {
// "all or nothing" would turn an honest condition into a special case inside
// three functions. It is checked once, on its own, below.
func sourceRoles(cfg Config) []any {
return []any{cfg.Reader, cfg.Claimer, cfg.ReadyClaimer, cfg.Releaser, cfg.Lifecycle, cfg.BatchCloser, cfg.Settings, cfg.Stats, cfg.CycleDetector, cfg.EdgeReader, cfg.GraphCounter, cfg.Relations, cfg.Commenter, cfg.BlockingAnnotator, cfg.TreeWalker, cfg.ReadyCounter, cfg.Counter, cfg.Querier, cfg.Sweeper, cfg.Deleter, cfg.BatchCreator, cfg.DependencyEditor, cfg.BatchApplier, cfg.Memories, cfg.MetadataCAS}
return []any{cfg.Reader, cfg.Claimer, cfg.ReadyClaimer, cfg.Releaser, cfg.Lifecycle, cfg.BatchCloser, cfg.Settings, cfg.Stats, cfg.CycleDetector, cfg.EdgeReader, cfg.GraphCounter, cfg.BatchGetter, cfg.Relations, cfg.Commenter, cfg.BlockingAnnotator, cfg.TreeWalker, cfg.ReadyCounter, cfg.Counter, cfg.Querier, cfg.Sweeper, cfg.Deleter, cfg.BatchCreator, cfg.DependencyEditor, cfg.BatchApplier, cfg.Memories, cfg.MetadataCAS}
}
// roleSourceNames spells sourceRoles for the refusal message, in the same
// order, so a caller reading the error learns the whole set it must pass.
const roleSourceNames = "Reader, Claimer, ReadyClaimer, Releaser, Lifecycle, BatchCloser, Settings, Stats, CycleDetector, EdgeReader, GraphCounter, Relations, Commenter, BlockingAnnotator, TreeWalker, ReadyCounter, Counter, Querier, Sweeper, Deleter, BatchCreator, DependencyEditor, BatchApplier, Memories and MetadataCAS"
const roleSourceNames = "Reader, Claimer, ReadyClaimer, Releaser, Lifecycle, BatchCloser, Settings, Stats, CycleDetector, EdgeReader, GraphCounter, BatchGetter, Relations, Commenter, BlockingAnnotator, TreeWalker, ReadyCounter, Counter, Querier, Sweeper, Deleter, BatchCreator, DependencyEditor, BatchApplier, Memories and MetadataCAS"
func anyRoleSet(cfg Config) bool {
return slices.ContainsFunc(sourceRoles(cfg), func(r any) bool { return r != nil })
@ -1126,6 +1136,21 @@ func (s *Server) graphCounter(r *http.Request) (issueops.GraphCounter, error) {
return src.GraphCounter()
}
// batchGetter returns the many-ids read surface for one request, built the
// same two ways as edgeReader above and held by INTERFACE so
// uow.BatchGetterSource is load-bearing rather than decorative.
//
// It goes out UNWRAPPED, for graphCounter's reason: the role answers with a
// VALUE whose slices a nil-safe range walks, so no handler dereferences a
// pointer it returned.
func (s *Server) batchGetter(r *http.Request) (issueops.BatchGetter, error) {
if s.provider == nil {
return s.issueBatchGetter, nil
}
var src uow.BatchGetterSource = timedProvider{inner: s.provider, rec: requestInfo(r.Context())}
return src.BatchGetter()
}
// relations returns the single-anchor neighbor surface for one request, built
// the same two ways as edgeReader above and held by INTERFACE so
// uow.RelationsSource is load-bearing rather than decorative.

View file

@ -63,7 +63,7 @@ info:
outside its own parameter table with `400` / `code: invalid_argument` /
`reason: "unknown_parameter"` and `param` naming the offending key.
Operations that declare no QUERY parameter at all reject every query key
the same way. Today that is twenty-five of the forty-one operations
the same way. Today that is twenty-six of the forty-two operations
here — `GET /healthz`, `GET /v0/beads/context`,
`GET /v0/beads/dependencies/cycles`, `POST /v0/beads/issues`,
`PATCH /v0/beads/issues/{id}`,
@ -74,6 +74,7 @@ info:
`POST /v0/beads/issues/{id}:reopen`,
`POST /v0/beads/issues/{id}:casMetadata`, `POST /v0/beads/issues:sweep`,
`POST /v0/beads/issues:delete`,
`POST /v0/beads/issues:batchGet`,
`POST /v0/beads/issues:batchCreate`,
`POST /v0/beads/issues:batchApply`,
`POST /v0/beads/issues:batchClose`, `GET /v0/beads/config`,
@ -3795,6 +3796,101 @@ paths:
'503':
$ref: '#/components/responses/Unavailable'
/v0/beads/issues:batchGet:
post:
operationId: batchGetIssues
summary: Read many issues by id in one snapshot
description: >-
Reads every issue the request NAMES, hydrated, in ONE snapshot. It is
the operation behind `issueops.BatchGetter`, and exists because the
obvious way to read N issues — `GET /v0/beads/issues/{id}` repeated N
times — costs N round trips to answer a question a caller already
knows the shape of: "which of these ids exist, and what do they look
like right now."
A POST rather than a `GET` with a repeated query parameter: the request
names up to 1000 ids, which does not fit a query string reliably, and
`issues:delete` beside it makes the same choice for the same reason.
## What a miss means
AN ID THAT NAMES NO STORED ROW IS NOT AN ERROR. It is reported in
`missing`, in the order it was first named, beside whatever else
resolved — the same answer `GET /v0/beads/dependencies` and
`GET /v0/beads/dependencies:count` give a miss on their own anchors,
and the opposite of `GET /v0/beads/issues/{id}`, which answers ONE id
with the issue or a `404`. There is no `404` on this operation: a
batch read that discarded the ids that DID resolve because one did not
would be strictly worse than reporting both.
DUPLICATES COLLAPSE. A request naming the same id twice gets it back
once, in `issues` or in `missing`, in the position of its FIRST
mention — never both. `issues` and `missing` partition the DISTINCT
ids the request named; their lengths always sum to that count.
An empty `ids` is legal and answers with both arrays empty — the same
empty-request answer `EdgeCountRequest.ids` documents, because "no
ids" is a legitimate thing to ask for 0 issues about.
## One snapshot
The existence check and the hydration share ONE transaction, so a
response never reports an id missing while a concurrent write was
creating it, or hands back a row for an id a concurrent write had
already deleted. Each returned issue carries its current `revision`,
so a caller that goes on to write one back has the
optimistic-concurrency token a lifecycle write wants without a second
round trip.
## No HTTP client leg yet
This operation ships a server and a library role on every leg (dolt,
embedded dolt, the unit-of-work provider), but no generated HTTP
CLIENT method. A caller on the wrong side of that door reaches it
through the raw request this document describes rather than through a
typed client call, until the client generator lands.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGetIssuesRequest'
security:
- bearerToken: []
responses:
'200':
description: >-
The ids that resolved, hydrated, plus the ids that did not.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGetIssuesResult'
'400':
description: >-
Invalid request: an unparseable or oversized body, an unknown body
member, an `ids` carrying more than 1000 entries (counted before
deduplication), or a blank entry.
x-bd-codes: [invalid_argument]
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
$ref: '#/components/responses/Unauthenticated'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/Unavailable'
/v0/beads/issues:batchCreate:
post:
operationId: batchCreateIssues
@ -6630,6 +6726,229 @@ components:
payload:
type: string
BatchGetIssue:
type: object
description: >-
One resolved entry of `BatchGetIssuesResult.issues`: an `Issue` plus
its current `revision`. Property semantics other than `revision` are
documented on `Issue`; the spec repeats the list rather than
composing it (see the note at the top of this document).
x-go-type: types.BatchGetIssue
x-go-type-import:
name: types
path: github.com/steveyegge/beads/internal/types
required: [id, title, priority, created_at, updated_at, revision]
properties:
id:
type: string
description: Canonical issue id, e.g. `bd-abc`.
title:
type: string
description:
type: string
design:
type: string
acceptance_criteria:
type: string
notes:
type: string
spec_id:
type: string
status:
type: string
description: >-
`open`, `in_progress`, `blocked`, `closed`, or any custom status
configured for the workspace. NOT a closed vocabulary: clients must
treat an unrecognized value as "some status I do not know".
priority:
type: integer
description: 0 (most urgent) through 4. Always present; 0 is a real value.
issue_type:
type: string
description: >-
`bug`, `feature`, `task`, `epic`, `chore`, `gate`, and workspace
configured types. Not a closed vocabulary.
is_blocked:
type: boolean
description: >-
The persisted readiness projection — true when an open blocking
dependency keeps this issue out of the ready set. Derived from the
dependency graph; never set by a client.
NOT POPULATED by the /v0 read endpoints today: they hydrate issues
without it, so the field is absent from their responses and its
absence says nothing about whether an issue is blocked. Use
`/v0/beads/ready` or the dependency endpoints to answer that. The
field is carried by events-journal snapshots, which is where it is
read back, and it is documented here because those snapshots
serialize the same type this schema is pinned to.
assignee:
type: string
description: The actor currently holding the issue, if any.
owner:
type: string
estimated_minutes:
type: integer
created_at:
type: string
format: date-time
created_by:
type: string
updated_at:
type: string
format: date-time
started_at:
type: string
format: date-time
closed_at:
type: string
format: date-time
close_reason:
type: string
closed_by_session:
type: string
lease_expires_at:
type: string
format: date-time
description: Expiry of the current claim's lease, when one is active.
heartbeat_at:
type: string
format: date-time
lease_granted_node:
type: string
description: >-
The replica that granted the lease. Empty means the provenance is
unknown, which is treated as local.
due_at:
type: string
format: date-time
defer_until:
type: string
format: date-time
external_ref:
type: string
source_system:
type: string
metadata:
type: object
additionalProperties: true
description: >-
Arbitrary caller-supplied JSON object. VALUES MAY BE OF ANY JSON
TYPE — string, number, boolean, array or nested object — because
typed values enter through the explicit JSON metadata path and
persist in older rows. Clients MUST NOT decode this into a
string-to-string map; a strict decode fails on the first typed
value and takes the whole response with it. That prohibition is on
assuming a narrower type when reading THIS document: a profile MAY
declare a narrower value schema under the rules in **Profiles**,
and a client of that profile may rely on the profile's declaration.
The object-at-top-level shape is the contract every producer and
every metadata filter (`metadata_field`, `has_metadata_key`)
assumes, but be aware the store validates only that the value is
WELL-FORMED JSON: a row created with a non-object (e.g.
`bd create --metadata '[1,2]'`) can carry an array or a scalar
here. That is a storage-side gap, not licence for a producer to
emit one — but a tolerant client should skip such a row rather than
fail the whole response.
compaction_level:
type: integer
compacted_at:
type: string
format: date-time
compacted_at_commit:
type: string
original_size:
type: integer
labels:
type: array
items:
type: string
dependencies:
type: array
description: >-
Dependency edges. Populated in export/interchange contexts; the
detail endpoint returns richer entries — see `IssueDetails`.
items:
$ref: '#/components/schemas/Dependency'
comments:
type: array
items:
$ref: '#/components/schemas/Comment'
sender:
type: string
ephemeral:
type: boolean
description: Ephemeral records are not synced.
no_history:
type: boolean
wisp_type:
type: string
storage_class:
type: string
description: >-
The record's history/replication contract. Empty means unset, which
resolves to ephemeral for wisp-plane records and versioned
otherwise.
pinned:
type: boolean
is_template:
type: boolean
bonded_from:
type: array
items:
$ref: '#/components/schemas/BondRef'
await_type:
type: string
description: Gate condition type.
await_id:
type: string
timeout:
type: integer
format: int64
description: >-
NANOSECONDS. This is a Go `time.Duration`, which encodes as an
int64 nanosecond count — a pre-existing wire fact, not a choice.
waiters:
type: array
items:
type: string
source_formula:
type: string
source_location:
type: string
mol_type:
type: string
work_type:
type: string
event_kind:
type: string
actor:
type: string
description: >-
For event records, the entity that caused the event. Unrelated to
the claiming actor in `ClaimRequest`.
target:
type: string
payload:
type: string
revision:
type: string
description: >-
The row's optimistic-concurrency token, spelled the way
`IssueDetails.revision` spells it — a decimal string, never a
number (a JSON number loses precision past 2^53 and the token
spans the full int64 range). EQUALITY-ONLY: compare it, never
order or interpret it. Send it back verbatim as an
`expected_version` on a lifecycle write.
NO omitempty: it is ALWAYS PRESENT, including as `"0"` for a
legacy migration-0054 row that has not been mutated since, the
same rule `IssueDetails.revision` states in full.
IssueWithCounts:
type: object
description: >-
@ -7582,7 +7901,8 @@ components:
`issues.batchClose`,
`issues.claim`, `issues.claimNext`, `issues.release`,
`issues.close`, `issues.reopen`, `issues.update`,
`issues.sweep`, `issues.delete`, `issues.batchCreate`,
`issues.sweep`, `issues.delete`, `issues.batchGet`,
`issues.batchCreate`,
`issues.batchApply`,
`stats.get`, `config.list`, `config.get`, `config.set`,
`config.unset`, `dependencies.cycles`,
@ -8071,6 +8391,74 @@ components:
items:
type: string
BatchGetIssuesRequest:
type: object
additionalProperties: false
required: [ids]
description: >-
Which issues to read, in one snapshot. There is no predicate here —
the caller already knows the ids — which is `DeleteIssuesRequest`'s
own reason for carrying none.
`additionalProperties: false`, so an unknown member is a `400` naming
the member.
properties:
ids:
type: array
maxItems: 1000
description: >-
The issues to read, exact ids, in either plane. DUPLICATES
COLLAPSE: a repeated id is answered once, in the position of its
first mention. An EMPTY array is legal and answers with both
`issues` and `missing` empty — it is not refused the way
`DeleteIssuesRequest.ids` refuses one, because a read that found
nothing to read is not a mistake the way a delete that erased
nothing usually is.
The cap is on the REQUEST, counted before deduplication: a caller
sending 1500 mentions of 3 distinct ids still names a request this
operation refuses, because the obligation the cap bounds is
reading the request apart, not reading the rows it resolves to.
items:
type: string
BatchGetIssuesResult:
type: object
required: [issues, missing]
description: >-
The issues that resolved, hydrated, plus the ids that did not — both
read from the SAME snapshot. Never a `404`: an id naming no stored row
is reported in `missing`, not refused, the same set-read answer
`DependencyEdges` and `EdgeCounts` give.
properties:
issues:
type: array
description: >-
One entry per requested id that resolved, in the REQUEST's order
(the caller's first mention of each distinct id), never the
storage engine's natural order. Each issue carries its current
`revision`, so a caller that goes on to write one back has the
optimistic-concurrency token a lifecycle write wants without a
second round trip. Empty array (never null) when nothing resolved.
HYDRATION IS LABELS ONLY: no dependencies, dependents or comments
— use `GET /v0/beads/issues/{id}` (`IssueDetails`) for those.
items:
$ref: '#/components/schemas/BatchGetIssue'
missing:
type: array
description: >-
The requested ids that resolved to no stored row, in the same
first-mention order as the request. An id here contributes no
entry to `issues`, and the two arrays' lengths always sum to the
number of DISTINCT ids the request named. Empty array (never null)
when every named id resolved.
items:
type: string
SweepRequest:
type: object
additionalProperties: false

View file

@ -17,6 +17,7 @@ import (
"github.com/steveyegge/beads/internal/httpapi/apigen"
"github.com/steveyegge/beads/internal/httpapi/spec"
"github.com/steveyegge/beads/internal/workapi"
"github.com/steveyegge/beads/issueops"
)
// These tests are the spec drift gates. They are pure — no database, no
@ -418,6 +419,31 @@ func TestSpecDefaultsMatchSharedConstants(t *testing.T) {
t.Errorf("%s: issue_id minItems = %v, want 1", opID, schema["minItems"])
}
}
// The id bound on the two request bodies that carry an `ids` list, for the
// anchor bound's reason: each is enforced in code — maxDeleteIDs in the
// delete handler, issueops.MaxGetManyIDs in the role behind batchGet — and
// restated as the member's maxItems, which is where a generated client
// learns it. Each body is reached through its operation's own $ref, so a
// row cannot go on checking a schema its operation stopped using.
for _, tc := range []struct {
opID string
want int
}{
{OpBatchGetIssues, issueops.MaxGetManyIDs},
{OpDeleteIssues, maxDeleteIDs},
} {
so, ok := ops[tc.opID]
if !ok {
t.Fatalf("operation %q missing from the spec", tc.opID)
}
media := mapAt(t, mapAt(t, mapAt(t, so.op, "requestBody"), "content"), "application/json")
body := resolveRef(t, doc, mapAt(t, media, "schema"))
ids := resolveRef(t, doc, mapAt(t, mapAt(t, body, "properties"), "ids"))
if got, ok := ids["maxItems"].(int); !ok || got != tc.want {
t.Errorf("%s: ids maxItems = %v, want the enforced bound %d", tc.opID, ids["maxItems"], tc.want)
}
}
}
// capabilityToken matches one backticked capability token in the

View file

@ -697,6 +697,384 @@
"required": true,
"item_type": "object"
},
{
"schema": "BatchGetIssue",
"member": "acceptance_criteria",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "actor",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "assignee",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "await_id",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "await_type",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "bonded_from",
"type": "array",
"required": false,
"item_type": "object"
},
{
"schema": "BatchGetIssue",
"member": "close_reason",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "closed_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "closed_by_session",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "comments",
"type": "array",
"required": false,
"item_type": "object"
},
{
"schema": "BatchGetIssue",
"member": "compacted_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "compacted_at_commit",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "compaction_level",
"type": "integer",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "created_at",
"type": "string",
"format": "date-time",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "created_by",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "defer_until",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "dependencies",
"type": "array",
"required": false,
"item_type": "object"
},
{
"schema": "BatchGetIssue",
"member": "description",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "design",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "due_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "ephemeral",
"type": "boolean",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "estimated_minutes",
"type": "integer",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "event_kind",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "external_ref",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "heartbeat_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "id",
"type": "string",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "is_blocked",
"type": "boolean",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "is_template",
"type": "boolean",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "issue_type",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "labels",
"type": "array",
"required": false,
"item_type": "string"
},
{
"schema": "BatchGetIssue",
"member": "lease_expires_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "lease_granted_node",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "metadata",
"type": "object",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "mol_type",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "no_history",
"type": "boolean",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "notes",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "original_size",
"type": "integer",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "owner",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "payload",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "pinned",
"type": "boolean",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "priority",
"type": "integer",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "revision",
"type": "string",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "sender",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "source_formula",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "source_location",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "source_system",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "spec_id",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "started_at",
"type": "string",
"format": "date-time",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "status",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "storage_class",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "target",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "timeout",
"type": "integer",
"format": "int64",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "title",
"type": "string",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "updated_at",
"type": "string",
"format": "date-time",
"required": true
},
{
"schema": "BatchGetIssue",
"member": "waiters",
"type": "array",
"required": false,
"item_type": "string"
},
{
"schema": "BatchGetIssue",
"member": "wisp_type",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssue",
"member": "work_type",
"type": "string",
"required": false
},
{
"schema": "BatchGetIssuesRequest",
"member": "ids",
"type": "array",
"required": true,
"item_type": "string"
},
{
"schema": "BatchGetIssuesResult",
"member": "issues",
"type": "array",
"required": true,
"item_type": "object"
},
{
"schema": "BatchGetIssuesResult",
"member": "missing",
"type": "array",
"required": true,
"item_type": "string"
},
{
"schema": "Blocker",
"member": "id",

View file

@ -70,6 +70,7 @@ func startOracle(t *testing.T) *oracle {
CycleDetector: stubCycles{},
EdgeReader: stubEdges{},
GraphCounter: stubGraphCounter{},
BatchGetter: stubBatchGetter{},
Relations: stubRelations{},
Commenter: stubCommenter{},
BlockingAnnotator: stubBlocking{},
@ -268,6 +269,7 @@ type (
stubCycles struct{ issueops.CycleDetector }
stubEdges struct{ issueops.EdgeReader }
stubGraphCounter struct{ issueops.GraphCounter }
stubBatchGetter struct{ issueops.BatchGetter }
stubRelations struct{ issueops.Relations }
stubCommenter struct{ issueops.Commenter }
stubBlocking struct{ issueops.BlockingAnnotator }

View file

@ -98,6 +98,10 @@ var opCapability = map[string]string{
OpRememberMemory: "memories.remember",
OpGetMemory: "memories.get",
OpForgetMemory: "memories.forget",
// The batch read (upstream #7248) is CLASSIFIED, not wired, for the reason
// the block above states: the server publishes it ahead of the accessor
// that dials it, and the set-equality gate needs its token here first.
OpBatchGetIssues: "issues.batchGet",
}
// CapProjectEnforce is the behavior capability the server advertises to announce

View file

@ -56,6 +56,7 @@ const (
OpRememberMemory = "rememberMemory"
OpGetMemory = "getMemory"
OpForgetMemory = "forgetMemory"
OpBatchGetIssues = "batchGetIssues"
)
// The paths that carry no caller-supplied segment. A path with one is built by

View file

@ -33,7 +33,9 @@ const itemsKey = "items"
// here, at the reader, on the small, explicit set of types that carry it.
//
// The set is exactly the schemas internal/httpapi/wireshape's digest records
// with a `revision` member (TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember
// with a `revision` member, less the ones revision_tolerance_test.go's
// revisionSchemaExempt documents as unreachable by a legacy server
// (TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember
// pins this against the same golden.json TestWireShapeDigest guards, so a new
// revision-bearing schema cannot slip past both without the coverage test
// failing first):

View file

@ -274,6 +274,17 @@ var revisionSchemaCoverage = map[string]any{
"UpdateIssueResponse": &apigen.UpdateIssueResponse{},
}
// revisionSchemaExempt maps a golden.json schema that carries a `revision`
// member but needs no legacy-integer tolerance to the reason it needs none. A
// schema is covered or exempt, never both, and an exemption goes stale the same
// way a coverage entry does.
var revisionSchemaExempt = map[string]string{
"BatchGetIssue": "BatchGetIssuesResult.issues' element. issues:batchGet (upstream #7248) postdates " +
"#6053 and types.BatchGetIssue declares Revision a string, so every server that routes it " +
"answers the decimal-string shape; a pre-#6053 server never advertises issues.batchGet, so " +
"Preflight refuses the operation with a *CapabilityError before any body is decoded",
}
// TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember is
// review follow-up HIGH-a's exhaustiveness guard. It derives the set of
// schemas a legacy server's bare-integer `revision` can appear on from the
@ -282,9 +293,10 @@ var revisionSchemaCoverage = map[string]any{
// schema names a second time — the grep this file's first version was
// written against missed apigen.IssueDetails precisely because it is a type
// alias for types.IssueDetails, invisible to a grep for "type \w+ struct.*
// revision". A schema that gains a `revision` member later and is not added
// to revisionSchemaCoverage now fails HERE, rather than only showing up as a
// silent decode failure against a real legacy server.
// revision". A schema that gains a `revision` member later and is neither
// added to revisionSchemaCoverage nor exempted in revisionSchemaExempt now
// fails HERE, rather than only showing up as a silent decode failure against a
// real legacy server.
func TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember(t *testing.T) {
path := filepath.Join("..", "..", "httpapi", "wireshape", "testdata", "golden.json")
data, err := os.ReadFile(path)
@ -308,8 +320,14 @@ func TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember(t
}
seen[e.Schema] = true
out, covered := revisionSchemaCoverage[e.Schema]
if _, exempt := revisionSchemaExempt[e.Schema]; exempt {
if covered {
t.Errorf("golden.json schema %q is in both revisionSchemaCoverage and revisionSchemaExempt; keep exactly one", e.Schema)
}
continue
}
if !covered {
t.Errorf("golden.json schema %q carries a `revision` member with no entry in revisionSchemaCoverage; add one, and extend revisionBearingResponse (or document why it needs no legacy-integer tolerance)", e.Schema)
t.Errorf("golden.json schema %q carries a `revision` member with no entry in revisionSchemaCoverage; add one, and extend revisionBearingResponse (or exempt it in revisionSchemaExempt with the reason it needs no legacy-integer tolerance)", e.Schema)
continue
}
if !revisionBearingResponse(out) {
@ -324,4 +342,12 @@ func TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember(t
t.Errorf("revisionSchemaCoverage lists %q, but golden.json has no entry for it with member \"revision\" anymore; remove the stale entry", schema)
}
}
for schema, reason := range revisionSchemaExempt {
if !seen[schema] {
t.Errorf("revisionSchemaExempt lists %q, but golden.json has no entry for it with member \"revision\" anymore; remove the stale exemption", schema)
}
if strings.TrimSpace(reason) == "" {
t.Errorf("revisionSchemaExempt lists %q with no reason; say why it needs no legacy-integer tolerance", schema)
}
}
}

View file

@ -110,16 +110,16 @@ func TestAgainstAFirstSliceServerEveryPostBaselineOperationRefusesWithCaseTwoDat
t.Fatalf("post-baseline ops on a first-slice token = %v, want exactly [claimIssue]", compat)
}
// The dimension is pinned so the matrix cannot shrink silently: the first
// slice served six operations and the tip surface has forty-one, so
// thirty-five of them are things a first-slice server has never heard of. The
// slice served six operations and the tip surface has forty-two, so
// thirty-six of them are things a first-slice server has never heard of. The
// wire wave moved this from twenty-seven to thirty — claimNext, release and
// count — wave 2 to thirty-two, adding the dependency-edge count and the
// related read, and the mini-sync to thirty-five: the comment write and the
// two config writes. Each is an operation a first-slice server never served
// and this client does not yet dial, which is exactly the shape the refusal
// matrix is about.
if len(refused) != 35 {
t.Fatalf("the post-baseline set has %d operations a first-slice server never served, want 35", len(refused))
// related read, the mini-sync to thirty-five: the comment write and the two
// config writes, and the batch read (upstream #7248) to thirty-six. Each is
// an operation a first-slice server never served and this client does not
// yet dial, which is exactly the shape the refusal matrix is about.
if len(refused) != 36 {
t.Fatalf("the post-baseline set has %d operations a first-slice server never served, want 36", len(refused))
}
// The compat op forces the handshake yet preflights clean: issues.claim is on

View file

@ -67,6 +67,7 @@ func TestOperationIdsMatchTheServerRouteTable(t *testing.T) {
{OpCompareAndSetMetadata, httpapi.OpCompareAndSetMetadata},
{OpListEvents, httpapi.OpListEvents},
{OpWatchEvents, httpapi.OpWatchEvents},
{OpBatchGetIssues, httpapi.OpBatchGetIssues},
}
// The table is a HAND LIST, and a hand list's failure mode is omission: a new

View file

@ -23,6 +23,7 @@ go_library(
"hook_batch_applier.go",
"hook_batch_closer.go",
"hook_batch_creator.go",
"hook_batch_getter.go",
"hook_blockingannotator.go",
"hook_bootstrapper.go",
"hook_commenter.go",

View file

@ -8,6 +8,7 @@ go_library(
"batch_applier.go",
"batch_closer.go",
"batch_creator.go",
"batchgetter.go",
"blocked_recheck_raw.go",
"blockingannotator.go",
"bootstrap.go",
@ -135,6 +136,7 @@ go_test(
"batch_apply_contract_test.go",
"batch_closer_contract_test.go",
"batch_creator_contract_test.go",
"batch_getter_contract_test.go",
"blocked_consistency_test.go",
"blocked_full_repair_test.go",
"blocked_merge_test.go",

View file

@ -0,0 +1,91 @@
package dolt
import (
"context"
"testing"
"github.com/steveyegge/beads/backend/conformance"
)
// TestBatchGetterContract runs the BatchGetter contract against the
// server-backed store.
//
// It reaches the same tx-level body every other leg reaches
// (issueops.ExecuteGetMany), so this wiring is an ENGINE check and a wrapper
// check rather than an independent vote on the body — the contract file says
// so at the top and the cases are written for it.
//
// The cases are subtests of one parent so the whole role suite shares one store
// and one copy-on-write branch. setupTestStore already marks the PARENT
// parallel and no subtest here calls t.Parallel.
func TestBatchGetterContract(t *testing.T) {
fixture, ctx, cleanup := newDoltBatchGetterFixture(t, "bge")
defer cleanup()
t.Run("FindsRequestedIssues", func(t *testing.T) {
conformance.RunBatchGetterFindsRequestedIssues(t, ctx, fixture)
})
t.Run("ReportsMissingIDs", func(t *testing.T) {
conformance.RunBatchGetterReportsMissingIDs(t, ctx, fixture)
})
t.Run("CollapsesRepeatedIDs", func(t *testing.T) {
conformance.RunBatchGetterCollapsesRepeatedIDs(t, ctx, fixture)
})
t.Run("AnswersInRequestOrder", func(t *testing.T) {
conformance.RunBatchGetterAnswersInRequestOrder(t, ctx, fixture)
})
t.Run("ResolvesIDsExactly", func(t *testing.T) {
conformance.RunBatchGetterResolvesIDsExactly(t, ctx, fixture)
})
t.Run("AnswersAnEmptyRequest", func(t *testing.T) {
conformance.RunBatchGetterAnswersAnEmptyRequest(t, ctx, fixture)
})
t.Run("RefusesAnUnusableRequest", func(t *testing.T) {
conformance.RunBatchGetterRefusesAnUnusableRequest(t, ctx, fixture)
})
t.Run("RefusesOverTheCap", func(t *testing.T) {
conformance.RunBatchGetterRefusesOverTheCap(t, ctx, fixture)
})
t.Run("AcceptsExactlyTheCap", func(t *testing.T) {
conformance.RunBatchGetterAcceptsExactlyTheCap(t, ctx, fixture)
})
t.Run("LeavesTheRequestAlone", func(t *testing.T) {
conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture)
})
t.Run("SharesOneReadStructurally", func(t *testing.T) {
conformance.RunBatchGetterSharesOneReadStructurally(t, ctx, fixture)
})
t.Run("HydratesLabels", func(t *testing.T) {
conformance.RunBatchGetterHydratesLabels(t, ctx, fixture)
})
t.Run("CrossesBothPlanes", func(t *testing.T) {
conformance.RunBatchGetterCrossesBothPlanes(t, ctx, fixture)
})
t.Run("WritesNothing", func(t *testing.T) {
conformance.RunBatchGetterWritesNothing(t, ctx, fixture)
})
}
func newDoltBatchGetterFixture(t *testing.T, prefix string) (conformance.BatchGetterFixture, context.Context, func()) {
t.Helper()
store, storeCleanup := setupTestStore(t)
ctx, cancel := testContext(t)
getter, err := store.BatchGetter()
if err != nil {
cancel()
storeCleanup()
t.Fatalf("BatchGetter(): %v", err)
}
kit := newDoltRoleFixtureKit(store, prefix)
fixture := conformance.BatchGetterFixture{
IssuePrefix: kit.IssuePrefix,
BatchGetter: getter,
CreateIssue: kit.CreateIssue,
CreateWisp: kit.CreateWisp,
CountHistory: kit.CountHistory,
}
return fixture, ctx, func() {
cancel()
storeCleanup()
}
}

View file

@ -0,0 +1,45 @@
package dolt
import (
"context"
"database/sql"
"github.com/steveyegge/beads/internal/storage"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/issueops"
)
// BatchGetter returns the guarded batch-read surface for this store.
func (s *DoltStore) BatchGetter() (issueops.BatchGetter, error) {
if s == nil {
return nil, &storage.ErrUnsupported{Op: "BatchGetter", Backend: "nil"}
}
return &batchGetter{store: s}, nil
}
// batchGetter answers a GetMany from one read transaction.
//
// There is no shared constructor package for this role: the work is an
// existence probe and a hydration that must see ONE snapshot, and a
// transaction is not reachable through storage.DoltStorage. The sharing
// happens one level down at issueops.ExecuteGetMany, which the embedded store
// and the unit-of-work provider both reach as well — so what this leg checks
// is the WRAPPER, and the conformance contract says so at the top.
type batchGetter struct{ store *DoltStore }
var _ issueops.BatchGetter = (*batchGetter)(nil)
// GetMany runs the lookup in ONE read transaction, so an id cannot be reported
// missing by a probe that raced a create a second query then found.
func (g *batchGetter) GetMany(ctx context.Context, request issueops.GetManyRequest) (issueops.GetManyResult, error) {
var result issueops.GetManyResult
err := g.store.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
result, err = storeops.ExecuteGetMany(ctx, tx, request)
return err
})
if err != nil {
return issueops.GetManyResult{}, err
}
return result, nil
}

View file

@ -614,6 +614,14 @@ func (r *issueSQLRepositoryImpl) GetByIDs(ctx context.Context, ids []string, opt
return out, nil
}
// GetMany runs the SHARED batch-read body on r.runner, which publishes
// exactly the DBTX method set issueops.ExecuteGetMany takes. There is no
// table option here, the way CompareAndSetMetadataKey has none: the shared
// body routes both planes itself through GetIssuesByIDsInTx.
func (r *issueSQLRepositoryImpl) GetMany(ctx context.Context, request publicops.GetManyRequest) (publicops.GetManyResult, error) {
return issueops.ExecuteGetMany(ctx, r.runner, request)
}
func (r *issueSQLRepositoryImpl) Exists(ctx context.Context, id string, opts domain.IssueTableOpts) (bool, error) {
if id == "" {
return false, errors.New("db: Exists: id must not be empty")

View file

@ -66,6 +66,12 @@ type IssueSQLRepository interface {
Get(ctx context.Context, id string, opts IssueTableOpts) (*types.Issue, error)
AsOf(ctx context.Context, id, ref string) (*types.Issue, error)
GetByIDs(ctx context.Context, ids []string, opts IssueTableOpts) ([]*types.Issue, error)
// GetMany runs the SHARED batch-read body (issueops.ExecuteGetMany) on this
// repository's transaction, which is how the unit-of-work provider reaches
// the same function the two store backends wrap. It takes no table option:
// the body routes both planes itself, the way CompareAndSetMetadataKey's
// does.
GetMany(ctx context.Context, request publicops.GetManyRequest) (publicops.GetManyResult, error)
Exists(ctx context.Context, id string, opts IssueTableOpts) (bool, error)
CountForPrefix(ctx context.Context, prefix string, opts IssueTableOpts) (int, error)
NextCounterID(ctx context.Context, prefix string) (int, error)
@ -311,6 +317,9 @@ type UpdateSpec struct {
type IssueUseCase interface {
GetIssue(ctx context.Context, id string) (*types.Issue, error)
GetIssuesByIDs(ctx context.Context, ids []string) ([]*types.Issue, error)
// GetMany is the shape issueops.BatchGetter publishes; see
// IssueSQLRepository.GetMany for why it takes no table option.
GetMany(ctx context.Context, request publicops.GetManyRequest) (publicops.GetManyResult, error)
FindWispDependentsRecursive(ctx context.Context, ids []string) (map[string]bool, error)
SearchIssues(ctx context.Context, query string, filter types.IssueFilter) (SearchPage, error)
SearchIssuesWithCounts(ctx context.Context, query string, filter types.IssueFilter) (SearchCountsPage, error)
@ -472,6 +481,14 @@ func (u *issueUseCaseImpl) GetIssuesByIDs(ctx context.Context, ids []string) ([]
return u.getByIDs(ctx, ids, false)
}
// GetMany passes straight through to the repository with no pre-check and no
// error wrapping, CountEdges's reason: the request's whole vocabulary is
// validated inside the shared body (issueops.ExecuteGetMany), and there is no
// second implementation for a wrapper here to protect.
func (u *issueUseCaseImpl) GetMany(ctx context.Context, request publicops.GetManyRequest) (publicops.GetManyResult, error) {
return u.issueRepo.GetMany(ctx, request)
}
func (u *issueUseCaseImpl) FindWispDependentsRecursive(ctx context.Context, ids []string) (map[string]bool, error) {
return u.issueRepo.FindWispDependentsRecursive(ctx, ids)
}

View file

@ -7,6 +7,7 @@ go_library(
"batch_applier.go",
"batch_closer.go",
"batch_creator.go",
"batchgetter.go",
"blockingannotator.go",
"bootstrapper.go",
"cache.go",
@ -100,6 +101,7 @@ go_test(
"batch_apply_contract_test.go",
"batch_closer_contract_test.go",
"batch_creator_contract_test.go",
"batch_getter_contract_test.go",
"blocked_recheck_internal_test.go",
"blocked_recompute_test.go",
"blocking_annotator_contract_test.go",

View file

@ -0,0 +1,82 @@
//go:build cgo
package embeddeddolt_test
import (
"testing"
"github.com/steveyegge/beads/backend/conformance"
)
// TestBatchGetterContract runs the BatchGetter contract against the embedded
// store. It reaches the same tx-level body the server-backed store reaches
// (issueops.ExecuteGetMany) and differs only in the engine underneath; that is
// what this wiring catches, and it is NOT an independent vote on the body.
//
// One environment for the whole suite. Every case seeds ids under its own
// prefix and asserts only about those, so the subtests are order-independent.
func TestBatchGetterContract(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "bge")
ctx := t.Context()
fixture := newEmbeddedBatchGetterFixture(t, te, "bge")
t.Run("FindsRequestedIssues", func(t *testing.T) {
conformance.RunBatchGetterFindsRequestedIssues(t, ctx, fixture)
})
t.Run("ReportsMissingIDs", func(t *testing.T) {
conformance.RunBatchGetterReportsMissingIDs(t, ctx, fixture)
})
t.Run("CollapsesRepeatedIDs", func(t *testing.T) {
conformance.RunBatchGetterCollapsesRepeatedIDs(t, ctx, fixture)
})
t.Run("AnswersInRequestOrder", func(t *testing.T) {
conformance.RunBatchGetterAnswersInRequestOrder(t, ctx, fixture)
})
t.Run("ResolvesIDsExactly", func(t *testing.T) {
conformance.RunBatchGetterResolvesIDsExactly(t, ctx, fixture)
})
t.Run("AnswersAnEmptyRequest", func(t *testing.T) {
conformance.RunBatchGetterAnswersAnEmptyRequest(t, ctx, fixture)
})
t.Run("RefusesAnUnusableRequest", func(t *testing.T) {
conformance.RunBatchGetterRefusesAnUnusableRequest(t, ctx, fixture)
})
t.Run("RefusesOverTheCap", func(t *testing.T) {
conformance.RunBatchGetterRefusesOverTheCap(t, ctx, fixture)
})
t.Run("AcceptsExactlyTheCap", func(t *testing.T) {
conformance.RunBatchGetterAcceptsExactlyTheCap(t, ctx, fixture)
})
t.Run("LeavesTheRequestAlone", func(t *testing.T) {
conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture)
})
t.Run("SharesOneReadStructurally", func(t *testing.T) {
conformance.RunBatchGetterSharesOneReadStructurally(t, ctx, fixture)
})
t.Run("HydratesLabels", func(t *testing.T) {
conformance.RunBatchGetterHydratesLabels(t, ctx, fixture)
})
t.Run("CrossesBothPlanes", func(t *testing.T) {
conformance.RunBatchGetterCrossesBothPlanes(t, ctx, fixture)
})
t.Run("WritesNothing", func(t *testing.T) {
conformance.RunBatchGetterWritesNothing(t, ctx, fixture)
})
}
func newEmbeddedBatchGetterFixture(t *testing.T, te *testEnv, prefix string) conformance.BatchGetterFixture {
t.Helper()
getter, err := te.store.BatchGetter()
if err != nil {
t.Fatalf("BatchGetter(): %v", err)
}
kit := newEmbeddedRoleFixtureKit(te, prefix)
return conformance.BatchGetterFixture{
IssuePrefix: kit.IssuePrefix,
BatchGetter: getter,
CreateIssue: kit.CreateIssue,
CreateWisp: kit.CreateWisp,
CountHistory: kit.CountHistory,
}
}

View file

@ -0,0 +1,44 @@
//go:build cgo
package embeddeddolt
import (
"context"
"database/sql"
"github.com/steveyegge/beads/internal/storage"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/issueops"
)
// BatchGetter returns the guarded batch-read surface for this store.
func (s *EmbeddedDoltStore) BatchGetter() (issueops.BatchGetter, error) {
if s == nil {
return nil, &storage.ErrUnsupported{Op: "BatchGetter", Backend: "nil"}
}
return &batchGetter{store: s}, nil
}
// batchGetter answers a GetMany from one connection's transaction.
//
// It is a sibling of the server-backed store's body rather than a shared
// package for the reason that one gives: the probe and the hydration need a
// TRANSACTION, which storage.DoltStorage does not publish, so the sharing
// happens below both of them at issueops.ExecuteGetMany. The two stores differ
// here only in how they reach a transaction.
type batchGetter struct{ store *EmbeddedDoltStore }
var _ issueops.BatchGetter = (*batchGetter)(nil)
func (g *batchGetter) GetMany(ctx context.Context, request issueops.GetManyRequest) (issueops.GetManyResult, error) {
var result issueops.GetManyResult
err := g.store.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
result, err = storeops.ExecuteGetMany(ctx, tx, request)
return err
})
if err != nil {
return issueops.GetManyResult{}, err
}
return result, nil
}

View file

@ -69,7 +69,9 @@ func (p *uowProvider) EdgeReader() (publicops.EdgeReader, error) { return uow
func (p *uowProvider) BlockingAnnotator() (publicops.BlockingAnnotator, error) {
return uow.NewBlockingAnnotator(p)
}
func (p *uowProvider) TreeWalker() (publicops.TreeWalker, error) { return uow.NewTreeWalker(p) }
func (p *uowProvider) TreeWalker() (publicops.TreeWalker, error) { return uow.NewTreeWalker(p) }
func (p *uowProvider) BatchGetter() (publicops.BatchGetter, error) { return uow.NewBatchGetter(p) }
func (p *uowProvider) GraphCounter() (publicops.GraphCounter, error) {
return uow.NewGraphCounter(p)
}
@ -172,6 +174,7 @@ var (
_ uow.BlockingAnnotatorSource = (*uowProvider)(nil)
_ uow.TreeWalkerSource = (*uowProvider)(nil)
_ uow.GraphCounterSource = (*uowProvider)(nil)
_ uow.BatchGetterSource = (*uowProvider)(nil)
_ uow.CounterSource = (*uowProvider)(nil)
_ uow.ReadyCounterSource = (*uowProvider)(nil)
_ uow.ReadyClaimerSource = (*uowProvider)(nil)

View file

@ -0,0 +1,17 @@
package storage
import (
"github.com/steveyegge/beads/issueops"
)
// BatchGetter returns the inner store's batch-read surface.
//
// It recurses, like every other accessor on this decorator, rather than being
// absent: the accessor set is uniform across the chain, so a caller never has
// to know which decorators a store is wearing. What it does NOT do is wrap the
// result — reading issues by id fires no completion hooks, because nothing
// completed. That is the same statement hook_graph_counter.go makes, and it is
// why this file is three lines.
func (h *HookFiringStore) BatchGetter() (issueops.BatchGetter, error) {
return h.inner.BatchGetter()
}

View file

@ -6,6 +6,7 @@ go_library(
"aggregate.go",
"as_of.go",
"batch_apply.go",
"batchget.go",
"batching.go",
"blocked.go",
"blocked_consistency.go",
@ -128,6 +129,7 @@ go_test(
"aggregate_authorize_transfer_test.go",
"as_of_test.go",
"batch_apply_test.go",
"batchget_test.go",
"batching_test.go",
"blocked_consistency_test.go",
"blocked_recheck_test.go",

View file

@ -0,0 +1,107 @@
package issueops
import (
"context"
"fmt"
"github.com/steveyegge/beads/internal/storage"
publicops "github.com/steveyegge/beads/issueops"
)
// ValidateGetManyRequest applies the request rules every BatchGetter
// implementation shares.
//
// THE CAP IS CHECKED FIRST, against the request AS SENT, before
// deduplication: the obligation it bounds is reading the request apart (and,
// below the role, holding one snapshot open long enough to resolve it), not
// reading the rows the ids resolve to, so a caller cannot dodge it by
// repeating one id 1,500 times. The per-entry blank check that follows tells a
// caller's mistake from a legitimately empty request, exactly as
// ValidateEdgeCountRequest's does for EdgeCountRequest.IDs.
func ValidateGetManyRequest(request publicops.GetManyRequest) error {
if len(request.IDs) > publicops.MaxGetManyIDs {
return &publicops.TooManyIDsError{Requested: len(request.IDs), Cap: publicops.MaxGetManyIDs}
}
for i, id := range request.IDs {
if id == "" {
return fmt.Errorf("%w: get many id at position %d is empty", storage.ErrValidation, i)
}
}
return nil
}
// DedupeGetManyIDs collapses duplicates, keeping the caller's FIRST mention of
// each id. Unlike NormalizeDeleteIDs's sibling, it does NOT trim whitespace:
// GetManyRequest.IDs are exact ids, and a caller that padded one with
// whitespace gets that id back in Missing rather than a silently corrected
// lookup, the same exactness RunGraphCounterResolvesIDsExactly pins for
// EdgeCountRequest.IDs.
func DedupeGetManyIDs(ids []string) []string {
seen := make(map[string]struct{}, len(ids))
out := make([]string, 0, len(ids))
for _, id := range ids {
if _, ok := seen[id]; ok {
continue
}
seen[id] = struct{}{}
out = append(out, id)
}
return out
}
// FinishGetMany assembles the ordered answer from the ids a caller asked for
// (already deduplicated) and the issues a read actually found, keyed by id.
//
// It is a pure function beside the body for ExecuteEdgeCount's reason: the
// part that decides what the answer MEANS — an id not in found is Missing, and
// Issues/Missing both preserve the caller's order — is pinned without a
// database, and the conformance contract is left to assert what only a real
// backend can show.
func FinishGetMany(ids []string, found map[string]*publicops.Issue) publicops.GetManyResult {
result := publicops.GetManyResult{
Issues: make([]*publicops.Issue, 0, len(ids)),
Missing: make([]string, 0),
}
for _, id := range ids {
if issue, ok := found[id]; ok {
result.Issues = append(result.Issues, issue)
continue
}
result.Missing = append(result.Missing, id)
}
return result
}
// ExecuteGetMany returns the issues named by request.IDs from tx, in ONE
// snapshot. It is the body behind the BatchGetter accessor on ALL THREE legs:
// the two stores wrap it in their own read transaction, and the unit-of-work
// provider reaches it through the domain repository, whose runner publishes
// exactly the DBTX method set GetIssuesByIDsInTx takes.
//
// VALIDATION HAPPENS HERE, for ExecuteEdgeCount's reason: this body is the
// only body, so a leg that forgot to validate would be answering a different
// contract, and there is no second implementation for the check to belong to.
// It runs before the transaction's one query, so a request over MaxGetManyIDs
// never reaches storage.
//
// HYDRATION IS LABELS ONLY, because that is all GetIssuesByIDsInTx fills: no
// dependencies, dependents or comments. A caller that needs those reads
// Reader.Get instead, one id at a time.
func ExecuteGetMany(ctx context.Context, tx DBTX, request publicops.GetManyRequest) (publicops.GetManyResult, error) {
if err := ValidateGetManyRequest(request); err != nil {
return publicops.GetManyResult{}, err
}
ids := DedupeGetManyIDs(request.IDs)
if len(ids) == 0 {
return publicops.GetManyResult{Issues: []*publicops.Issue{}, Missing: []string{}}, nil
}
issues, err := GetIssuesByIDsInTx(ctx, tx, ids, nil)
if err != nil {
return publicops.GetManyResult{}, fmt.Errorf("get many: %w", err)
}
found := make(map[string]*publicops.Issue, len(issues))
for _, issue := range issues {
found[issue.ID] = issue
}
return FinishGetMany(ids, found), nil
}

View file

@ -0,0 +1,136 @@
package issueops
import (
"context"
"errors"
"slices"
"testing"
"github.com/DATA-DOG/go-sqlmock"
"github.com/steveyegge/beads/internal/storage"
publicops "github.com/steveyegge/beads/issueops"
)
// These are the parts of issueops.BatchGetter's answer that are decided
// without a database — the request rules, the first-mention collapse and the
// ordered split into Issues and Missing — so they are pinned here in
// milliseconds and the conformance contract is left to assert what only a real
// backend can show.
func TestValidateGetManyRequestChecksTheCapBeforeTheBlankScan(t *testing.T) {
// A request over the cap that ALSO carries a blank id has to report the
// cap: a caller told only about the blank would fix it and get a second,
// different refusal back for the same request. The blank sits at position
// 0, so a scan that ran first could not miss it.
ids := slices.Repeat([]string{"bd-1"}, publicops.MaxGetManyIDs+1)
ids[0] = ""
err := ValidateGetManyRequest(publicops.GetManyRequest{IDs: ids})
var tooMany *publicops.TooManyIDsError
if !errors.As(err, &tooMany) {
t.Fatalf("an over-cap request with a blank id = %v, want *TooManyIDsError", err)
}
if tooMany.Requested != len(ids) || tooMany.Cap != publicops.MaxGetManyIDs {
t.Errorf("refusal = %+v, want Requested %d and Cap %d", *tooMany, len(ids), publicops.MaxGetManyIDs)
}
if !errors.Is(err, storage.ErrValidation) {
t.Errorf("the cap refusal %v does not match ErrValidation", err)
}
}
func TestValidateGetManyRequestRefusals(t *testing.T) {
for _, test := range []struct {
name string
ids []string
want bool
}{
{"no ids at all", nil, false},
{"exactly the cap's worth of mentions", slices.Repeat([]string{"bd-1"}, publicops.MaxGetManyIDs), false},
{"one mention past the cap", slices.Repeat([]string{"bd-1"}, publicops.MaxGetManyIDs+1), true},
{"an empty id beside a real one", []string{"bd-1", ""}, true},
} {
err := ValidateGetManyRequest(publicops.GetManyRequest{IDs: test.ids})
if got := errors.Is(err, storage.ErrValidation); got != test.want {
t.Errorf("%s: ErrValidation = %t (err %v), want %t", test.name, got, err, test.want)
}
}
}
func TestDedupeGetManyIDsKeepsTheFirstMentionAndLeavesTheRequestAlone(t *testing.T) {
// The repeat of bd-b follows a different id, so a collapse that sorted, or
// that kept each id's LAST mention, would answer bd-a before bd-b. The
// padded id is a different exact id, not a duplicate to trim away.
request := []string{"bd-b", "bd-a", "bd-b", " bd-a "}
sent := slices.Clone(request)
got := DedupeGetManyIDs(request)
if want := []string{"bd-b", "bd-a", " bd-a "}; !slices.Equal(got, want) {
t.Errorf("DedupeGetManyIDs(%q) = %q, want %q", sent, got, want)
}
// GetManyRequest promises IDs is never written through, and collapsing in
// place is the idiomatic way to break that promise.
if !slices.Equal(request, sent) {
t.Errorf("DedupeGetManyIDs rewrote the caller's slice to %q, want %q", request, sent)
}
}
func TestFinishGetManySplitsTheRequestInItsOwnOrder(t *testing.T) {
// The id list is the order, not the found map — whose iteration order Go
// randomizes on purpose — and neither half is sorted, so a sorting
// assembly would answer differently on both.
result := FinishGetMany(
[]string{"c", "ghost-2", "a", "ghost-1"},
map[string]*publicops.Issue{"a": {ID: "a"}, "c": {ID: "c"}},
)
var issueIDs []string
for _, issue := range result.Issues {
issueIDs = append(issueIDs, issue.ID)
}
if want := []string{"c", "a"}; !slices.Equal(issueIDs, want) {
t.Errorf("Issues = %q, want %q (the request's order)", issueIDs, want)
}
if want := []string{"ghost-2", "ghost-1"}; !slices.Equal(result.Missing, want) {
t.Errorf("Missing = %q, want %q (the request's order)", result.Missing, want)
}
}
func TestFinishGetManyAnswersNeverNil(t *testing.T) {
// An all-found request answers with an empty, non-nil Missing, and an empty
// request with two: a front door that marshals them emits [] rather than
// null.
allFound := FinishGetMany([]string{"a"}, map[string]*publicops.Issue{"a": {ID: "a"}})
if allFound.Missing == nil || len(allFound.Missing) != 0 {
t.Errorf("Missing = %#v for an all-found request, want an empty, non-nil slice", allFound.Missing)
}
empty := FinishGetMany(nil, nil)
if empty.Issues == nil || len(empty.Issues) != 0 {
t.Errorf("Issues = %#v for an empty request, want an empty, non-nil slice", empty.Issues)
}
if empty.Missing == nil || len(empty.Missing) != 0 {
t.Errorf("Missing = %#v for an empty request, want an empty, non-nil slice", empty.Missing)
}
}
func TestExecuteGetManyRefusesOverTheCapBeforeTheQuery(t *testing.T) {
// A mock with no expectations fails any statement it is handed, so the
// refusal is proved to come from the body's own check rather than from
// storage. The request repeats ONE id past the cap, so a body that
// collapsed repeats before validating would have let it through to the
// query instead.
db, _, err := sqlmock.New()
if err != nil {
t.Fatalf("sqlmock.New: %v", err)
}
defer db.Close()
_, err = ExecuteGetMany(context.Background(), db, publicops.GetManyRequest{
IDs: slices.Repeat([]string{"bd-1"}, publicops.MaxGetManyIDs+1),
})
var tooMany *publicops.TooManyIDsError
if !errors.As(err, &tooMany) {
t.Fatalf("one id repeated past the cap = %v, want *TooManyIDsError before any query", err)
}
}

View file

@ -162,6 +162,7 @@ type roleAccessorStore struct {
blocking issueops.BlockingAnnotator
tree issueops.TreeWalker
graphCounter issueops.GraphCounter
batchGetter issueops.BatchGetter
counter issueops.Counter
settings issueops.WorkspaceConfig
memories memoryops.Memories
@ -195,6 +196,7 @@ func newRoleAccessorStore() *roleAccessorStore {
edges: sentinel,
blocking: sentinel,
graphCounter: sentinel,
batchGetter: sentinel,
counter: sentinel,
settings: sentinel,
versions: sentinel,
@ -272,6 +274,9 @@ func (s *roleAccessorStore) DependencyEditor() (issueops.DependencyEditor, error
func (s *roleAccessorStore) GraphCounter() (issueops.GraphCounter, error) {
return s.graphCounter, s.err
}
func (s *roleAccessorStore) BatchGetter() (issueops.BatchGetter, error) {
return s.batchGetter, s.err
}
func (s *roleAccessorStore) MetadataCAS() (issueops.MetadataCAS, error) {
return s.metadataCAS, s.err
}
@ -327,6 +332,9 @@ func (*roleAccessorSentinel) CountByGroup(context.Context, issueops.CountByGroup
func (*roleAccessorSentinel) CountEdges(context.Context, issueops.EdgeCountRequest) (issueops.EdgeCountResult, error) {
return issueops.EdgeCountResult{}, nil
}
func (*roleAccessorSentinel) GetMany(context.Context, issueops.GetManyRequest) (issueops.GetManyResult, error) {
return issueops.GetManyResult{}, nil
}
func (*roleAccessorSentinel) GetSetting(context.Context, issueops.GetSettingRequest) (issueops.SettingResult, error) {
return issueops.SettingResult{}, nil
}
@ -472,6 +480,7 @@ func TestHookFiringStoreWrapsTheWriteRolesAndPassesTheReadsThrough(t *testing.T)
{"BlockingAnnotator", func() (any, error) { return store.BlockingAnnotator() }, inner.blocking, false},
{"TreeWalker", func() (any, error) { return store.TreeWalker() }, inner.tree, false},
{"GraphCounter", func() (any, error) { return store.GraphCounter() }, inner.graphCounter, false},
{"BatchGetter", func() (any, error) { return store.BatchGetter() }, inner.batchGetter, false},
{"Counter", func() (any, error) { return store.Counter() }, inner.counter, false},
{"WorkspaceConfig", func() (any, error) { return store.WorkspaceConfig() }, inner.settings, false},
{"Memories", func() (any, error) { return store.Memories() }, inner.memories, false},
@ -529,6 +538,7 @@ func TestHookFiringStoreRoleAccessorsPropagateInnerErrors(t *testing.T) {
{"BlockingAnnotator", func() (any, error) { return store.BlockingAnnotator() }},
{"TreeWalker", func() (any, error) { return store.TreeWalker() }},
{"GraphCounter", func() (any, error) { return store.GraphCounter() }},
{"BatchGetter", func() (any, error) { return store.BatchGetter() }},
{"Counter", func() (any, error) { return store.Counter() }},
{"WorkspaceConfig", func() (any, error) { return store.WorkspaceConfig() }},
{"Memories", func() (any, error) { return store.Memories() }},

View file

@ -286,6 +286,12 @@ type Storage interface {
// EdgeReader (that one answers with the stored ROWS, outbound only). Reads
// fire no hooks, as for IssueReader.
GraphCounter() (issueops.GraphCounter, error)
// BatchGetter returns the guarded batch-read surface for this store: many
// issues by id, hydrated, in ONE snapshot. Its own role rather than a mode
// of IssueReader because a miss here is a RESULT FIELD (Missing) and not
// ErrNotFound — a batch GET is a set read, not a precondition on every
// member succeeding. Reads fire no hooks, as for IssueReader.
BatchGetter() (issueops.BatchGetter, error)
// ReadyCounter returns the guarded ready-count surface for this store: the
// size of the ready set, which is the number `bd ready`'s pagination
// publishes and which no other role answers. Counter's predicate is a

View file

@ -7,6 +7,7 @@ go_library(
"batch_applier.go",
"batch_closer.go",
"batch_creator.go",
"batchgetter.go",
"blocked_recheck.go",
"blockingannotator.go",
"bootstrapper.go",
@ -93,6 +94,7 @@ go_test(
"batch_apply_contract_test.go",
"batch_closer_contract_test.go",
"batch_creator_contract_test.go",
"batch_getter_contract_test.go",
"blocked_recheck_race_test.go",
"blocking_annotator_contract_test.go",
"bootstrapper_contract_test.go",

View file

@ -0,0 +1,94 @@
package uow
import (
"context"
"testing"
"github.com/steveyegge/beads/backend/conformance"
)
// TestBatchGetterContract runs the BatchGetter contract against the
// unit-of-work provider.
//
// For most roles this is the wiring where a genuine seam divergence shows up,
// because the unit of work is a second body. NOT FOR THIS ROLE: it reaches the
// same issueops.ExecuteGetMany through the domain repository, whose runner
// publishes exactly the DBTX method set that function takes. What this leg
// checks is the WRAPPER — that the request survives the trip and that
// ErrValidation still matches errors.Is after crossing two layers whose
// siblings wrap their errors.
//
// One provider for the whole suite and NO t.Parallel: this backend has no
// per-test copy-on-write branch, so the tables are database-global. Every case
// scopes itself by the ids it seeded.
func TestBatchGetterContract(t *testing.T) {
ctx := context.Background()
fixture := newUOWBatchGetterFixture(t, ctx, "bge")
t.Run("FindsRequestedIssues", func(t *testing.T) {
conformance.RunBatchGetterFindsRequestedIssues(t, ctx, fixture)
})
t.Run("ReportsMissingIDs", func(t *testing.T) {
conformance.RunBatchGetterReportsMissingIDs(t, ctx, fixture)
})
t.Run("CollapsesRepeatedIDs", func(t *testing.T) {
conformance.RunBatchGetterCollapsesRepeatedIDs(t, ctx, fixture)
})
t.Run("AnswersInRequestOrder", func(t *testing.T) {
conformance.RunBatchGetterAnswersInRequestOrder(t, ctx, fixture)
})
t.Run("ResolvesIDsExactly", func(t *testing.T) {
conformance.RunBatchGetterResolvesIDsExactly(t, ctx, fixture)
})
t.Run("AnswersAnEmptyRequest", func(t *testing.T) {
conformance.RunBatchGetterAnswersAnEmptyRequest(t, ctx, fixture)
})
t.Run("RefusesAnUnusableRequest", func(t *testing.T) {
conformance.RunBatchGetterRefusesAnUnusableRequest(t, ctx, fixture)
})
t.Run("RefusesOverTheCap", func(t *testing.T) {
conformance.RunBatchGetterRefusesOverTheCap(t, ctx, fixture)
})
t.Run("AcceptsExactlyTheCap", func(t *testing.T) {
conformance.RunBatchGetterAcceptsExactlyTheCap(t, ctx, fixture)
})
t.Run("LeavesTheRequestAlone", func(t *testing.T) {
conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture)
})
t.Run("SharesOneReadStructurally", func(t *testing.T) {
conformance.RunBatchGetterSharesOneReadStructurally(t, ctx, fixture)
})
t.Run("HydratesLabels", func(t *testing.T) {
conformance.RunBatchGetterHydratesLabels(t, ctx, fixture)
})
t.Run("CrossesBothPlanes", func(t *testing.T) {
conformance.RunBatchGetterCrossesBothPlanes(t, ctx, fixture)
})
t.Run("WritesNothing", func(t *testing.T) {
conformance.RunBatchGetterWritesNothing(t, ctx, fixture)
})
}
func newUOWBatchGetterFixture(t *testing.T, ctx context.Context, prefix string) conformance.BatchGetterFixture {
t.Helper()
provider := newUOWRoleFixtureProvider(t, ctx, prefix)
// Through the capability accessor, not NewBatchGetter: a provider that
// stopped offering the role is the regression, and a constructor call would
// hide it.
source, ok := provider.(BatchGetterSource)
if !ok {
t.Fatalf("provider %T does not offer the BatchGetter accessor", provider)
}
getter, err := source.BatchGetter()
if err != nil {
t.Fatalf("BatchGetter(): %v", err)
}
kit := newUOWRoleFixtureKit(provider, prefix)
return conformance.BatchGetterFixture{
IssuePrefix: kit.IssuePrefix,
BatchGetter: getter,
CreateIssue: kit.CreateIssue,
CreateWisp: kit.CreateWisp,
CountHistory: kit.CountHistory,
}
}

View file

@ -0,0 +1,44 @@
package uow
import (
"context"
"fmt"
publicops "github.com/steveyegge/beads/issueops"
)
// BatchGetterSource is the capability accessor a unit-of-work provider offers
// for the batch-read role, the sibling of CounterSource and GraphCounterSource.
type BatchGetterSource interface {
BatchGetter() (publicops.BatchGetter, error)
}
// batchGetter answers a GetMany through a unit of work.
type batchGetter struct {
provider UnitOfWorkProvider
}
// BatchGetter returns the guarded batch-read surface for this provider.
func (p *doltSQLProvider) BatchGetter() (publicops.BatchGetter, error) {
return NewBatchGetter(p)
}
// NewBatchGetter constructs a public BatchGetter backed by provider.
func NewBatchGetter(provider UnitOfWorkProvider) (publicops.BatchGetter, error) {
if isNilUnitOfWorkProvider(provider) {
return nil, fmt.Errorf("new batch getter: unit-of-work provider must not be nil")
}
return &batchGetter{provider: provider}, nil
}
var _ publicops.BatchGetter = (*batchGetter)(nil)
// GetMany reaches domain.IssueSQLRepository.GetMany inside ONE read-only unit
// of work, the same seam CountEdges reaches DependencyUseCase.CountEdges
// through: the request's whole vocabulary is validated inside the shared
// body (issueops.ExecuteGetMany), so this leg does no pre-check of its own.
func (c *batchGetter) GetMany(ctx context.Context, request publicops.GetManyRequest) (publicops.GetManyResult, error) {
return RunTxRead(ctx, c.provider, func(ctx context.Context, uw UnitOfWork) (publicops.GetManyResult, error) {
return uw.IssueUseCase().GetMany(ctx, request)
})
}

View file

@ -238,6 +238,10 @@ func (p *notifyingProvider) GraphCounter() (publicops.GraphCounter, error) {
return NewGraphCounter(p)
}
func (p *notifyingProvider) BatchGetter() (publicops.BatchGetter, error) {
return NewBatchGetter(p)
}
func (p *notifyingProvider) Counter() (publicops.Counter, error) { return NewCounter(p) }
func (p *notifyingProvider) ReadyCounter() (publicops.ReadyCounter, error) {
@ -400,6 +404,7 @@ var (
_ BlockingAnnotatorSource = (*notifyingProvider)(nil)
_ TreeWalkerSource = (*notifyingProvider)(nil)
_ GraphCounterSource = (*notifyingProvider)(nil)
_ BatchGetterSource = (*notifyingProvider)(nil)
_ CounterSource = (*notifyingProvider)(nil)
_ ReadyCounterSource = (*notifyingProvider)(nil)
_ ReadyClaimerSource = (*notifyingProvider)(nil)

View file

@ -145,6 +145,7 @@ func TestRecordingIssueUseCaseCoversItsSurface(t *testing.T) {
"GetEpicsEligibleForClosure": reads,
"GetIssue": reads,
"GetIssuesByIDs": reads,
"GetMany": reads,
"GetNewlyUnblockedByClose": reads,
"GetNewlyUnblockedByCloseWisp": reads,
"GetReadyWork": reads,

View file

@ -6,6 +6,7 @@ go_library(
"batch_applier.go",
"batch_closer.go",
"batch_creator.go",
"batch_getter.go",
"blockingannotator.go",
"bootstrapper.go",
"commenter.go",

View file

@ -0,0 +1,36 @@
package telemetry
import (
"context"
"github.com/steveyegge/beads/issueops"
)
// BatchGetter returns the inner store's batch-read surface wrapped in this
// layer's instrumentation. It recurses instead of delegating: a blind
// delegation would return the inner getter unspanned and untimed.
func (s *InstrumentedStorage) BatchGetter() (issueops.BatchGetter, error) {
inner, err := s.Unwrap().BatchGetter()
if err != nil {
return nil, err
}
return s.WrapBatchGetter(inner), nil
}
// WrapBatchGetter instruments guarded batch reads with this storage layer's
// existing telemetry meter and tracer.
func (s *InstrumentedStorage) WrapBatchGetter(inner issueops.BatchGetter) issueops.BatchGetter {
return &instrumentedBatchGetter{storage: s, inner: inner}
}
type instrumentedBatchGetter struct {
storage *InstrumentedStorage
inner issueops.BatchGetter
}
func (c *instrumentedBatchGetter) GetMany(ctx context.Context, request issueops.GetManyRequest) (result issueops.GetManyResult, err error) {
ctx, span, started := c.storage.op(ctx, "BatchGetter.GetMany")
result, err = c.inner.GetMany(ctx, request)
c.storage.done(ctx, span, started, err)
return result, err
}

View file

@ -133,6 +133,9 @@ func (s *roleAccessorStore) TreeWalker() (issueops.TreeWalker, error) { return s
func (s *roleAccessorStore) GraphCounter() (issueops.GraphCounter, error) {
return s.surface, s.err
}
func (s *roleAccessorStore) BatchGetter() (issueops.BatchGetter, error) {
return s.surface, s.err
}
func (s *roleAccessorStore) BlockingAnnotator() (issueops.BlockingAnnotator, error) {
return s.surface, s.err
}
@ -258,6 +261,9 @@ func (*roleAccessorSentinel) CountReady(context.Context, issueops.ReadyRequest)
func (*roleAccessorSentinel) CountEdges(context.Context, issueops.EdgeCountRequest) (issueops.EdgeCountResult, error) {
return issueops.EdgeCountResult{}, nil
}
func (*roleAccessorSentinel) GetMany(context.Context, issueops.GetManyRequest) (issueops.GetManyResult, error) {
return issueops.GetManyResult{}, nil
}
func (*roleAccessorSentinel) Query(context.Context, issueops.QueryRequest) (issueops.IssuePage, error) {
return issueops.IssuePage{}, nil
@ -355,6 +361,7 @@ func TestInstrumentedStorageInstrumentsEveryRoleAccessor(t *testing.T) {
{"BlockingAnnotator", func() (any, error) { return wrapped.BlockingAnnotator() }, sentinel},
{"TreeWalker", func() (any, error) { return wrapped.TreeWalker() }, sentinel},
{"GraphCounter", func() (any, error) { return wrapped.GraphCounter() }, sentinel},
{"BatchGetter", func() (any, error) { return wrapped.BatchGetter() }, sentinel},
{"Counter", func() (any, error) { return wrapped.Counter() }, sentinel},
{"WorkspaceConfig", func() (any, error) { return wrapped.WorkspaceConfig() }, sentinel},
{"Memories", func() (any, error) { return wrapped.Memories() }, memorySentinel},
@ -440,6 +447,7 @@ func TestInstrumentedStorageRoleAccessorsPropagateInnerErrors(t *testing.T) {
{"BlockingAnnotator", func() (any, error) { return wrapped.BlockingAnnotator() }},
{"TreeWalker", func() (any, error) { return wrapped.TreeWalker() }},
{"GraphCounter", func() (any, error) { return wrapped.GraphCounter() }},
{"BatchGetter", func() (any, error) { return wrapped.BatchGetter() }},
{"Counter", func() (any, error) { return wrapped.Counter() }},
{"WorkspaceConfig", func() (any, error) { return wrapped.WorkspaceConfig() }},
{"Memories", func() (any, error) { return wrapped.Memories() }},

View file

@ -1366,6 +1366,27 @@ func NewIssueDetails(issue Issue) *IssueDetails {
return &IssueDetails{Issue: issue, Revision: RevisionToken(issue.RowVersion)}
}
// BatchGetIssue is one entry of BatchGetIssuesResult.issues: a resolved issue
// plus its current revision token, projected the same way IssueDetails
// projects one off the embedded Issue's RowVersion (RowVersion is json:"-",
// so the Issue body alone cannot carry it). Hydration for a batch-get issue
// is LABELS ONLY — no dependencies, dependents or comments; a caller wanting
// those reads GET /v0/beads/issues/{id} (IssueDetails) instead.
//
// NewBatchGetIssue is the only door, for the same reason NewIssueDetails is:
// a struct literal with an unset Revision serializes a "0" indistinguishable
// from a legacy migration-0054 row.
type BatchGetIssue struct {
Issue
Revision string `json:"revision"`
}
// NewBatchGetIssue projects issue with its wire-visible revision token, the
// BatchGetIssuesResult.issues counterpart of NewIssueDetails.
func NewBatchGetIssue(issue Issue) BatchGetIssue {
return BatchGetIssue{Issue: issue, Revision: RevisionToken(issue.RowVersion)}
}
// DependencyType categorizes the relationship
type DependencyType string

View file

@ -654,6 +654,35 @@ func TestGraphCounterExposesTypedUnsupportedError(t *testing.T) {
}
}
// TestBatchGetterKeepsTelemetryOutermost is the READ answer again: reading
// issues by id fires no completion hooks, so the hook decorator adds no layer.
func TestBatchGetterKeepsTelemetryOutermost(t *testing.T) {
t.Setenv("BD_OTEL_STDOUT", "true")
instrumented, ok := telemetry.WrapStorage(&dolt.DoltStore{}).(*telemetry.InstrumentedStorage)
if !ok {
t.Fatal("WrapStorage() did not create InstrumentedStorage")
}
getter, err := storage.NewHookFiringStore(instrumented, nil).BatchGetter()
if err != nil {
t.Fatalf("BatchGetter() error = %v", err)
}
if got := reflect.TypeOf(getter).String(); got != "*telemetry.instrumentedBatchGetter" {
t.Fatalf("outer layer = %s, want the telemetry wrapper unwrapped by the hook decorator", got)
}
}
func TestBatchGetterExposesTypedUnsupportedError(t *testing.T) {
getter, err := (*dolt.DoltStore)(nil).BatchGetter()
if getter != nil {
t.Fatalf("BatchGetter() getter = %T, want nil", getter)
}
var unsupported *beads.ErrUnsupported
if !errors.As(err, &unsupported) {
t.Fatalf("BatchGetter() error = %v, want *beads.ErrUnsupported", err)
}
}
func TestCounterExposesTypedUnsupportedError(t *testing.T) {
counter, err := (*dolt.DoltStore)(nil).Counter()
if counter != nil {

View file

@ -6,6 +6,7 @@ go_library(
"batchapplier.go",
"batchcloser.go",
"batchcreator.go",
"batchgetter.go",
"blockedstate.go",
"blockingannotator.go",
"bootstrapper.go",

149
issueops/batchgetter.go Normal file
View file

@ -0,0 +1,149 @@
package issueops
import (
"context"
"fmt"
)
// MaxGetManyIDs is the largest request this role accepts in one call. It is a
// FLAT bound on the request, not a cost model over what a backend does with
// it: GetMany reads every named id in ONE snapshot, so the bound is really a
// bound on how long one request may hold a single read open.
//
// 1000 is the same number BatchApplier settled on (issueops.MaxApplyBatchItems)
// and the same number DeleteRequest.IDs caps at on the wire
// (openapi.v0.yaml's DeleteIssuesRequest). It is not borrowed for symmetry: a
// caller fanning out gc's ready veto or the CLI's own id-resolution passes
// already walks lists in exactly this range, and a cap an order of magnitude
// smaller would just reintroduce the per-id fan-out this role exists to
// replace.
const MaxGetManyIDs = 1000
// TooManyIDsError reports that a GetManyRequest named more ids than this role
// accepts in one call. It wraps ErrValidation, so a caller that only checks
// for a usable request classifies it correctly without knowing this type
// exists, and errors.As gets at Requested and Cap for a caller that wants to
// say how far over the line the request was.
type TooManyIDsError struct {
// Requested is the number of ids the request named, counted BEFORE
// deduplication: a caller that sent 1500 mentions of 3 distinct ids typed
// a request this role still refuses, because the obligation this cap
// bounds is reading the request apart, not reading the rows it resolves
// to.
Requested int
// Cap is MaxGetManyIDs, carried on the error so a caller does not need the
// constant in scope to report what it hit.
Cap int
}
func (e *TooManyIDsError) Error() string {
return fmt.Sprintf("get many accepts at most %d ids, got %d", e.Cap, e.Requested)
}
// Unwrap makes TooManyIDsError match ErrValidation.
func (e *TooManyIDsError) Unwrap() error { return ErrValidation }
// GetManyRequest names the issues to fetch in one read.
//
// Implementations never mutate caller-owned request values: IDs is read,
// never written through, and never sorted in place.
type GetManyRequest struct {
// IDs names the issues to fetch, in either plane, exact ids only. Prefix
// resolution and bd's other id conveniences happen at the front door,
// above this role, the same boundary DeleteRequest.IDs draws.
//
// DUPLICATES COLLAPSE and the surviving order is the caller's first
// mention of each id: a caller that asks for [a, b, a] gets back Issues
// in the order [a, b] (whichever of those resolve) and nothing about a
// twice.
//
// AN ID THAT NAMES NO STORED ROW IS NOT AN ERROR. It is reported in
// GetManyResult.Missing beside whatever else resolved — the same
// result-field answer EdgeCountResult.Anchors and EdgeReadResult give a
// miss, and the reason GetMany does not return ErrNotFound the way
// DeleteRequest's all-or-nothing id check does: a batch GET is a set
// read, not a precondition on every member succeeding.
//
// MORE THAN MaxGetManyIDs IS A REFUSAL: a *TooManyIDsError, counted on
// the request as sent, before deduplication.
//
// An empty slice is not an error. It answers with an empty result, the
// same empty-request answer EdgeCountRequest.IDs documents, because "no
// ids" is a legitimate thing to ask for 0 issues about and a caller that
// built its list by filtering should not have that filter's empty result
// turned into a different kind of failure than the one it already knows
// how to handle.
IDs []string
}
// GetManyResult answers a GetManyRequest from one snapshot.
type GetManyResult struct {
// Issues holds the hydrated rows for every id that resolved, in the
// REQUEST's order (the caller's first mention of each distinct id), never
// the storage engine's natural order. Each Issue carries its current
// RowVersion, so a caller that goes on to write one back has the
// optimistic-concurrency token a lifecycle write wants without a second
// round trip.
//
// HYDRATION IS LABELS ONLY: no dependencies, dependents or comments. A
// caller that needs those calls Reader.Get instead, one id at a time.
//
// Never nil for a successful call, even when it is empty: a front door
// that marshals this field emits [] rather than null, the same promise
// EdgeCountResult.Anchors makes.
Issues []*Issue
// Missing names every requested id that resolved to no stored row, in the
// same first-mention order as the request. An id that appears in Missing
// does not appear in Issues, and the two slices' lengths sum to the
// number of DISTINCT ids the request named.
//
// Never nil for a successful call: an all-found request answers with an
// empty, non-nil Missing.
Missing []string
}
// BatchGetter reads many issues by id in one snapshot.
//
// It exists because the obvious way to read N issues — one Get per id — is
// what gc's ready veto and the bd CLI both do today, and it costs N round
// trips (or N transactions, for a backend where each Get opens its own) to
// answer a single question a caller already knows the shape of: "which of
// these ids exist, and what do they look like right now." BatchGetter answers
// that in one call over one snapshot, the same trade EdgeCountRequest.IDs and
// EdgeReadRequest make for the edge-shaped versions of the same question.
//
// IT IS A FACADE-ONLY ROLE, for now: this slice wires every library leg
// (dolt, embedded dolt, the unit-of-work provider) and the
// POST /v0/beads/issues:batchGet HTTP handler, but ships no HTTP CLIENT leg.
// A caller on the wrong side of that door reaches this role through the raw
// HTTP request the handler answers, not through a typed client method, until
// the client generator lands (see the TODO beside the CLI call sites this
// slice did not migrate, and PR #7247). A later slice updates this doc and the
// client-side TODOs together once that leg exists.
//
// It differs from Reader.Get in arity, in hydration and in what a miss means:
// Get answers ONE id with *IssueDetails or ErrNotFound, labels, dependencies,
// dependents and comments included; this answers MANY ids with a result
// whose Missing field is how a caller tells "this one does not exist" from
// "the call failed," and whose Issues are hydrated LABELS ONLY — no
// dependencies, dependents or comments. A caller that needs those calls
// Reader.Get instead, one id at a time. It differs from EdgeReader and
// GraphCounter in what it is reading: those answer questions about the EDGES
// a set of anchors carries; this answers the ISSUES themselves.
type BatchGetter interface {
// GetMany reads every id GetManyRequest.IDs names, in ONE snapshot. The
// existence check and the hydration share that snapshot for the reason
// ExecuteEdgeCount's probe-and-tally share one: a probe in its own
// transaction could report an id missing while a second transaction
// created it, contradicting itself in one response body.
//
// Refuses with:
// - *TooManyIDsError, wrapping ErrValidation, when IDs carries more than
// MaxGetManyIDs entries (counted before deduplication);
// - ErrValidation for an empty-string entry in IDs, the same per-entry
// check EdgeCountRequest.IDs applies.
//
// Never returns ErrNotFound: an id naming no stored row is reported in
// GetManyResult.Missing, not refused.
GetMany(ctx context.Context, request GetManyRequest) (GetManyResult, error)
}