From d74b4f8a11d2da6c736ce4e2381cdf778f52d261 Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Mon, 5 Oct 2026 14:49:29 +0000 Subject: [PATCH 1/4] 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 --- backend/conformance/batch_getter_contract.go | 349 ++++++++++++++++++ cmd/bd/export_auto.go | 4 + cmd/bd/import_shared.go | 5 + cmd/bd/mol_current.go | 3 + cmd/bd/mol_port.go | 6 + cmd/bd/ready.go | 3 + cmd/bd/ready_proxied_server.go | 3 + cmd/bd/serve.go | 22 +- cmd/bd/serve_source_test.go | 14 + cmd/bd/serve_store_identity_test.go | 9 + cmd/bd/wisp.go | 3 + internal/httpapi/apigen/types.gen.go | 24 +- internal/httpapi/batch_get.go | 158 ++++++++ internal/httpapi/claim.go | 7 + internal/httpapi/problem.go | 13 + internal/httpapi/roles_test.go | 31 ++ internal/httpapi/routes.go | 13 + internal/httpapi/server.go | 29 +- internal/httpapi/spec/openapi.v0.yaml | 165 ++++++++- .../httpapi/wireshape/testdata/golden.json | 21 ++ .../dolt/batch_getter_contract_test.go | 85 +++++ internal/storage/dolt/batchgetter.go | 45 +++ internal/storage/domain/db/issue.go | 8 + internal/storage/domain/issue.go | 17 + .../batch_getter_contract_test.go | 76 ++++ internal/storage/embeddeddolt/batchgetter.go | 44 +++ .../storage/externaldeps/uow_decorator.go | 5 +- internal/storage/hook_batch_getter.go | 17 + internal/storage/issueops/batchget.go | 103 ++++++ .../storage/role_accessor_decorator_test.go | 10 + internal/storage/storage.go | 6 + .../storage/uow/batch_getter_contract_test.go | 88 +++++ internal/storage/uow/batchgetter.go | 44 +++ internal/storage/uow/notifying.go | 5 + internal/telemetry/batch_getter.go | 36 ++ .../telemetry/role_accessor_decorator_test.go | 8 + issue_roles_external_test.go | 29 ++ issueops/batchgetter.go | 144 ++++++++ 38 files changed, 1639 insertions(+), 13 deletions(-) create mode 100644 backend/conformance/batch_getter_contract.go create mode 100644 internal/httpapi/batch_get.go create mode 100644 internal/storage/dolt/batch_getter_contract_test.go create mode 100644 internal/storage/dolt/batchgetter.go create mode 100644 internal/storage/embeddeddolt/batch_getter_contract_test.go create mode 100644 internal/storage/embeddeddolt/batchgetter.go create mode 100644 internal/storage/hook_batch_getter.go create mode 100644 internal/storage/issueops/batchget.go create mode 100644 internal/storage/uow/batch_getter_contract_test.go create mode 100644 internal/storage/uow/batchgetter.go create mode 100644 internal/telemetry/batch_getter.go create mode 100644 issueops/batchgetter.go diff --git a/backend/conformance/batch_getter_contract.go b/backend/conformance/batch_getter_contract.go new file mode 100644 index 000000000..79efc3f54 --- /dev/null +++ b/backend/conformance/batch_getter_contract.go @@ -0,0 +1,349 @@ +package conformance + +import ( + "context" + "errors" + "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) + } +} + +// 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) + } +} + +// RunBatchGetterReadsOneSnapshot pins the one-snapshot clause on +// BatchGetter.GetMany: the existence check and the hydration share one read, +// so a found id and a missing id resolved by the SAME call answer correctly +// together. A body that split the probe from the hydration into two +// round trips could not be told apart from a correct one by any single-field +// assertion, which is why this case checks both halves of one GetManyResult +// instead of asserting on two separate calls the way +// RunBatchGetterFindsRequestedIssues and RunBatchGetterReportsMissingIDs do. +func RunBatchGetterReadsOneSnapshot(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") + } +} diff --git a/cmd/bd/export_auto.go b/cmd/bd/export_auto.go index 95f8ca705..e8fd4807c 100644 --- a/cmd/bd/export_auto.go +++ b/cmd/bd/export_auto.go @@ -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) diff --git a/cmd/bd/import_shared.go b/cmd/bd/import_shared.go index 7e0c9cce8..85d39f78a 100644 --- a/cmd/bd/import_shared.go +++ b/cmd/bd/import_shared.go @@ -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) } diff --git a/cmd/bd/mol_current.go b/cmd/bd/mol_current.go index 2969db871..f3d92d33f 100644 --- a/cmd/bd/mol_current.go +++ b/cmd/bd/mol_current.go @@ -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 diff --git a/cmd/bd/mol_port.go b/cmd/bd/mol_port.go index 1e314328b..e915f9030 100644 --- a/cmd/bd/mol_port.go +++ b/cmd/bd/mol_port.go @@ -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) diff --git a/cmd/bd/ready.go b/cmd/bd/ready.go index 7c6ccdc66..71b1e8f22 100644 --- a/cmd/bd/ready.go +++ b/cmd/bd/ready.go @@ -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) diff --git a/cmd/bd/ready_proxied_server.go b/cmd/bd/ready_proxied_server.go index 2b2734c59..97180dee8 100644 --- a/cmd/bd/ready_proxied_server.go +++ b/cmd/bd/ready_proxied_server.go @@ -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) diff --git a/cmd/bd/serve.go b/cmd/bd/serve.go index 3110191da..464062fc5 100644 --- a/cmd/bd/serve.go +++ b/cmd/bd/serve.go @@ -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,18 @@ 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 accessor does NOT recurse through + // the hook decorator — it answers no writes — 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 diff --git a/cmd/bd/serve_source_test.go b/cmd/bd/serve_source_test.go index b44d6d91c..a0abf2235 100644 --- a/cmd/bd/serve_source_test.go +++ b/cmd/bd/serve_source_test.go @@ -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. diff --git a/cmd/bd/serve_store_identity_test.go b/cmd/bd/serve_store_identity_test.go index dc69978ed..322adc4c3 100644 --- a/cmd/bd/serve_store_identity_test.go +++ b/cmd/bd/serve_store_identity_test.go @@ -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 diff --git a/cmd/bd/wisp.go b/cmd/bd/wisp.go index 44ba3268a..329b1734f 100644 --- a/cmd/bd/wisp.go +++ b/cmd/bd/wisp.go @@ -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)) diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index 1edee6f7b..5c2517f81 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -818,6 +818,25 @@ type BatchCreateResponse struct { Items []Issue `json:"items"` } +// 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. + Issues []Issue `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::` reference. @@ -1010,7 +1029,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 +2732,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 diff --git a/internal/httpapi/batch_get.go b/internal/httpapi/batch_get.go new file mode 100644 index 000000000..a51468779 --- /dev/null +++ b/internal/httpapi/batch_get.go @@ -0,0 +1,158 @@ +package httpapi + +import ( + "encoding/json" + "errors" + "net/http" + "slices" + "strings" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "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) — because the blank-entry case above already +// catches the handler's own copy of that check before the role is ever +// called. 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.Issue` dereferenced: 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. +func batchGetResponse(result issueops.GetManyResult) apigen.BatchGetIssuesResult { + body := apigen.BatchGetIssuesResult{ + Issues: []apigen.Issue{}, + Missing: []string{}, + } + for _, issue := range result.Issues { + if issue == nil { + continue + } + body.Issues = append(body.Issues, *issue) + } + body.Missing = append(body.Missing, result.Missing...) + return body +} diff --git a/internal/httpapi/claim.go b/internal/httpapi/claim.go index 58590b313..24d79093b 100644 --- a/internal/httpapi/claim.go +++ b/internal/httpapi/claim.go @@ -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 diff --git a/internal/httpapi/problem.go b/internal/httpapi/problem.go index 31e336eac..d3252ed9a 100644 --- a/internal/httpapi/problem.go +++ b/internal/httpapi/problem.go @@ -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. diff --git a/internal/httpapi/roles_test.go b/internal/httpapi/roles_test.go index 1540dbbf8..083923e9c 100644 --- a/internal/httpapi/roles_test.go +++ b/internal/httpapi/roles_test.go @@ -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{} } diff --git a/internal/httpapi/routes.go b/internal/httpapi/routes.go index 1fe26aab0..0aa93b109 100644 --- a/internal/httpapi/routes.go +++ b/internal/httpapi/routes.go @@ -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, diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 26de31cdb..a3b928390 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -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. diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index 4b36dee2d..39ebd44a7 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -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 @@ -7582,7 +7678,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 +8168,70 @@ 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. + items: + $ref: '#/components/schemas/Issue' + 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 diff --git a/internal/httpapi/wireshape/testdata/golden.json b/internal/httpapi/wireshape/testdata/golden.json index 30ff61ebe..c78f9d7df 100644 --- a/internal/httpapi/wireshape/testdata/golden.json +++ b/internal/httpapi/wireshape/testdata/golden.json @@ -697,6 +697,27 @@ "required": true, "item_type": "object" }, + { + "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", diff --git a/internal/storage/dolt/batch_getter_contract_test.go b/internal/storage/dolt/batch_getter_contract_test.go new file mode 100644 index 000000000..ae56c38cb --- /dev/null +++ b/internal/storage/dolt/batch_getter_contract_test.go @@ -0,0 +1,85 @@ +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("LeavesTheRequestAlone", func(t *testing.T) { + conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture) + }) + t.Run("ReadsOneSnapshot", func(t *testing.T) { + conformance.RunBatchGetterReadsOneSnapshot(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() + } +} diff --git a/internal/storage/dolt/batchgetter.go b/internal/storage/dolt/batchgetter.go new file mode 100644 index 000000000..e350a5696 --- /dev/null +++ b/internal/storage/dolt/batchgetter.go @@ -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 +} diff --git a/internal/storage/domain/db/issue.go b/internal/storage/domain/db/issue.go index 276a740f8..a9d2e3c7a 100644 --- a/internal/storage/domain/db/issue.go +++ b/internal/storage/domain/db/issue.go @@ -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") diff --git a/internal/storage/domain/issue.go b/internal/storage/domain/issue.go index 1c7df0508..a6ce46a83 100644 --- a/internal/storage/domain/issue.go +++ b/internal/storage/domain/issue.go @@ -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) } diff --git a/internal/storage/embeddeddolt/batch_getter_contract_test.go b/internal/storage/embeddeddolt/batch_getter_contract_test.go new file mode 100644 index 000000000..5f5940cdf --- /dev/null +++ b/internal/storage/embeddeddolt/batch_getter_contract_test.go @@ -0,0 +1,76 @@ +//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("LeavesTheRequestAlone", func(t *testing.T) { + conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture) + }) + t.Run("ReadsOneSnapshot", func(t *testing.T) { + conformance.RunBatchGetterReadsOneSnapshot(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, + } +} diff --git a/internal/storage/embeddeddolt/batchgetter.go b/internal/storage/embeddeddolt/batchgetter.go new file mode 100644 index 000000000..1d68fb991 --- /dev/null +++ b/internal/storage/embeddeddolt/batchgetter.go @@ -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 +} diff --git a/internal/storage/externaldeps/uow_decorator.go b/internal/storage/externaldeps/uow_decorator.go index 9db47cd44..0b9e9293b 100644 --- a/internal/storage/externaldeps/uow_decorator.go +++ b/internal/storage/externaldeps/uow_decorator.go @@ -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) diff --git a/internal/storage/hook_batch_getter.go b/internal/storage/hook_batch_getter.go new file mode 100644 index 000000000..e88239f1c --- /dev/null +++ b/internal/storage/hook_batch_getter.go @@ -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() +} diff --git a/internal/storage/issueops/batchget.go b/internal/storage/issueops/batchget.go new file mode 100644 index 000000000..dfdc9ae1a --- /dev/null +++ b/internal/storage/issueops/batchget.go @@ -0,0 +1,103 @@ +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. +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 +} diff --git a/internal/storage/role_accessor_decorator_test.go b/internal/storage/role_accessor_decorator_test.go index 58027bb5b..aa8ce3b57 100644 --- a/internal/storage/role_accessor_decorator_test.go +++ b/internal/storage/role_accessor_decorator_test.go @@ -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() }}, diff --git a/internal/storage/storage.go b/internal/storage/storage.go index ab27581d8..8abe0b0fd 100644 --- a/internal/storage/storage.go +++ b/internal/storage/storage.go @@ -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 diff --git a/internal/storage/uow/batch_getter_contract_test.go b/internal/storage/uow/batch_getter_contract_test.go new file mode 100644 index 000000000..46693cbd8 --- /dev/null +++ b/internal/storage/uow/batch_getter_contract_test.go @@ -0,0 +1,88 @@ +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("LeavesTheRequestAlone", func(t *testing.T) { + conformance.RunBatchGetterLeavesTheRequestAlone(t, ctx, fixture) + }) + t.Run("ReadsOneSnapshot", func(t *testing.T) { + conformance.RunBatchGetterReadsOneSnapshot(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, + } +} diff --git a/internal/storage/uow/batchgetter.go b/internal/storage/uow/batchgetter.go new file mode 100644 index 000000000..c379d2102 --- /dev/null +++ b/internal/storage/uow/batchgetter.go @@ -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) + }) +} diff --git a/internal/storage/uow/notifying.go b/internal/storage/uow/notifying.go index d61b68529..f1e9930e5 100644 --- a/internal/storage/uow/notifying.go +++ b/internal/storage/uow/notifying.go @@ -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) diff --git a/internal/telemetry/batch_getter.go b/internal/telemetry/batch_getter.go new file mode 100644 index 000000000..1b4f5cddb --- /dev/null +++ b/internal/telemetry/batch_getter.go @@ -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 +} diff --git a/internal/telemetry/role_accessor_decorator_test.go b/internal/telemetry/role_accessor_decorator_test.go index 0d7caece4..e7c9b7c9c 100644 --- a/internal/telemetry/role_accessor_decorator_test.go +++ b/internal/telemetry/role_accessor_decorator_test.go @@ -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() }}, diff --git a/issue_roles_external_test.go b/issue_roles_external_test.go index f5c70fc34..b6e6dd38a 100644 --- a/issue_roles_external_test.go +++ b/issue_roles_external_test.go @@ -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 { diff --git a/issueops/batchgetter.go b/issueops/batchgetter.go new file mode 100644 index 000000000..2a54deaa7 --- /dev/null +++ b/issueops/batchgetter.go @@ -0,0 +1,144 @@ +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. + // + // 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 and in what a miss means: Get answers +// ONE id with *IssueDetails or ErrNotFound, this answers MANY ids with a +// result whose Missing field is how a caller tells "this one does not exist" +// from "the call failed." 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, hydrated, the way Reader.Get +// does for one. +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) +} From 348717787f8cab55b0f66864298ab9f36de80ddb Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Mon, 5 Oct 2026 14:49:29 +0000 Subject: [PATCH 2/4] =?UTF-8?q?fix(roles):=20close=20S7=20review=20gaps=20?= =?UTF-8?q?=E2=80=94=20revision=20on=20wire,=20BUILD=20sync,=20handler=20t?= =?UTF-8?q?ests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- backend/conformance/BUILD.bazel | 1 + backend/conformance/batch_getter_contract.go | 88 ++++- internal/httpapi/BUILD.bazel | 2 + internal/httpapi/apigen/types.gen.go | 7 +- internal/httpapi/batch_get.go | 29 +- internal/httpapi/batch_get_test.go | 303 +++++++++++++++ internal/httpapi/pinning.go | 2 + internal/httpapi/spec/openapi.v0.yaml | 229 ++++++++++- .../httpapi/wireshape/testdata/golden.json | 357 ++++++++++++++++++ internal/storage/BUILD.bazel | 1 + internal/storage/dolt/BUILD.bazel | 2 + .../dolt/batch_getter_contract_test.go | 10 +- internal/storage/embeddeddolt/BUILD.bazel | 2 + .../batch_getter_contract_test.go | 10 +- internal/storage/issueops/BUILD.bazel | 1 + internal/storage/issueops/batchget.go | 4 + internal/storage/uow/BUILD.bazel | 2 + .../storage/uow/batch_getter_contract_test.go | 10 +- internal/telemetry/BUILD.bazel | 1 + internal/types/types.go | 21 ++ issueops/BUILD.bazel | 1 + issueops/batchgetter.go | 19 +- 22 files changed, 1067 insertions(+), 35 deletions(-) create mode 100644 internal/httpapi/batch_get_test.go diff --git a/backend/conformance/BUILD.bazel b/backend/conformance/BUILD.bazel index 89773dfbd..1bd7e0271 100644 --- a/backend/conformance/BUILD.bazel +++ b/backend/conformance/BUILD.bazel @@ -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", diff --git a/backend/conformance/batch_getter_contract.go b/backend/conformance/batch_getter_contract.go index 79efc3f54..6cfdd6590 100644 --- a/backend/conformance/batch_getter_contract.go +++ b/backend/conformance/batch_getter_contract.go @@ -3,6 +3,7 @@ package conformance import ( "context" "errors" + "fmt" "testing" "github.com/steveyegge/beads/internal/types" @@ -191,6 +192,61 @@ func RunBatchGetterRefusesOverTheCap(t *testing.T, ctx context.Context, fixture } } +// 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 @@ -209,15 +265,29 @@ func RunBatchGetterLeavesTheRequestAlone(t *testing.T, ctx context.Context, fixt } } -// RunBatchGetterReadsOneSnapshot pins the one-snapshot clause on -// BatchGetter.GetMany: the existence check and the hydration share one read, -// so a found id and a missing id resolved by the SAME call answer correctly -// together. A body that split the probe from the hydration into two -// round trips could not be told apart from a correct one by any single-field -// assertion, which is why this case checks both halves of one GetManyResult -// instead of asserting on two separate calls the way -// RunBatchGetterFindsRequestedIssues and RunBatchGetterReportsMissingIDs do. -func RunBatchGetterReadsOneSnapshot(t *testing.T, ctx context.Context, fixture BatchGetterFixture) { +// 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" diff --git a/internal/httpapi/BUILD.bazel b/internal/httpapi/BUILD.bazel index 091375c48..4e559636e 100644 --- a/internal/httpapi/BUILD.bazel +++ b/internal/httpapi/BUILD.bazel @@ -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", diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index 5c2517f81..ac64377c4 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -818,6 +818,9 @@ 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. @@ -831,7 +834,9 @@ type BatchGetIssuesRequest struct { // 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. - Issues []Issue `json:"issues"` + // + // 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"` diff --git a/internal/httpapi/batch_get.go b/internal/httpapi/batch_get.go index a51468779..7548c0931 100644 --- a/internal/httpapi/batch_get.go +++ b/internal/httpapi/batch_get.go @@ -8,6 +8,7 @@ import ( "strings" "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -116,11 +117,13 @@ func batchGetMemberList() string { // failBatchGetErr answers a failed batch get. The role's only refusal over the // wire is ErrValidation — an oversized `ids` (*issueops.TooManyIDsError, -// counted before deduplication) — because the blank-entry case above already -// catches the handler's own copy of that check before the role is ever -// called. 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. +// 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 @@ -138,20 +141,24 @@ func (s *Server) failBatchGetErr(w http.ResponseWriter, r *http.Request, err err // // 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.Issue` dereferenced: 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. +// 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.Issue{}, + Issues: []apigen.BatchGetIssue{}, Missing: []string{}, } for _, issue := range result.Issues { if issue == nil { continue } - body.Issues = append(body.Issues, *issue) + body.Issues = append(body.Issues, types.NewBatchGetIssue(*issue)) } body.Missing = append(body.Missing, result.Missing...) return body diff --git a/internal/httpapi/batch_get_test.go b/internal/httpapi/batch_get_test.go new file mode 100644 index 000000000..a0e058c83 --- /dev/null +++ b/internal/httpapi/batch_get_test.go @@ -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) diff --git a/internal/httpapi/pinning.go b/internal/httpapi/pinning.go index 1c47d1b5f..2144038fb 100644 --- a/internal/httpapi/pinning.go +++ b/internal/httpapi/pinning.go @@ -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 ) diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index 39ebd44a7..4c5b22462 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -6726,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: >- @@ -8219,8 +8442,12 @@ components: `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/Issue' + $ref: '#/components/schemas/BatchGetIssue' missing: type: array description: >- diff --git a/internal/httpapi/wireshape/testdata/golden.json b/internal/httpapi/wireshape/testdata/golden.json index c78f9d7df..ff6021bb6 100644 --- a/internal/httpapi/wireshape/testdata/golden.json +++ b/internal/httpapi/wireshape/testdata/golden.json @@ -697,6 +697,363 @@ "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", diff --git a/internal/storage/BUILD.bazel b/internal/storage/BUILD.bazel index d9d737885..fb8f51af9 100644 --- a/internal/storage/BUILD.bazel +++ b/internal/storage/BUILD.bazel @@ -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", diff --git a/internal/storage/dolt/BUILD.bazel b/internal/storage/dolt/BUILD.bazel index 8f4276b2d..29113ca75 100644 --- a/internal/storage/dolt/BUILD.bazel +++ b/internal/storage/dolt/BUILD.bazel @@ -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", diff --git a/internal/storage/dolt/batch_getter_contract_test.go b/internal/storage/dolt/batch_getter_contract_test.go index ae56c38cb..9fc0ff654 100644 --- a/internal/storage/dolt/batch_getter_contract_test.go +++ b/internal/storage/dolt/batch_getter_contract_test.go @@ -46,11 +46,17 @@ func TestBatchGetterContract(t *testing.T) { 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("ReadsOneSnapshot", func(t *testing.T) { - conformance.RunBatchGetterReadsOneSnapshot(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) diff --git a/internal/storage/embeddeddolt/BUILD.bazel b/internal/storage/embeddeddolt/BUILD.bazel index 8f563a3cb..c07059454 100644 --- a/internal/storage/embeddeddolt/BUILD.bazel +++ b/internal/storage/embeddeddolt/BUILD.bazel @@ -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", diff --git a/internal/storage/embeddeddolt/batch_getter_contract_test.go b/internal/storage/embeddeddolt/batch_getter_contract_test.go index 5f5940cdf..2da37613d 100644 --- a/internal/storage/embeddeddolt/batch_getter_contract_test.go +++ b/internal/storage/embeddeddolt/batch_getter_contract_test.go @@ -45,11 +45,17 @@ func TestBatchGetterContract(t *testing.T) { 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("ReadsOneSnapshot", func(t *testing.T) { - conformance.RunBatchGetterReadsOneSnapshot(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) diff --git a/internal/storage/issueops/BUILD.bazel b/internal/storage/issueops/BUILD.bazel index d774d7aff..07dba8324 100644 --- a/internal/storage/issueops/BUILD.bazel +++ b/internal/storage/issueops/BUILD.bazel @@ -6,6 +6,7 @@ go_library( "aggregate.go", "as_of.go", "batch_apply.go", + "batchget.go", "batching.go", "blocked.go", "blocked_consistency.go", diff --git a/internal/storage/issueops/batchget.go b/internal/storage/issueops/batchget.go index dfdc9ae1a..f3686dd35 100644 --- a/internal/storage/issueops/batchget.go +++ b/internal/storage/issueops/batchget.go @@ -83,6 +83,10 @@ func FinishGetMany(ids []string, found map[string]*publicops.Issue) publicops.Ge // 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 diff --git a/internal/storage/uow/BUILD.bazel b/internal/storage/uow/BUILD.bazel index e181e1fcc..14c638c84 100644 --- a/internal/storage/uow/BUILD.bazel +++ b/internal/storage/uow/BUILD.bazel @@ -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", diff --git a/internal/storage/uow/batch_getter_contract_test.go b/internal/storage/uow/batch_getter_contract_test.go index 46693cbd8..9821923b4 100644 --- a/internal/storage/uow/batch_getter_contract_test.go +++ b/internal/storage/uow/batch_getter_contract_test.go @@ -49,11 +49,17 @@ func TestBatchGetterContract(t *testing.T) { 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("ReadsOneSnapshot", func(t *testing.T) { - conformance.RunBatchGetterReadsOneSnapshot(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) diff --git a/internal/telemetry/BUILD.bazel b/internal/telemetry/BUILD.bazel index a8e863458..a643c5b60 100644 --- a/internal/telemetry/BUILD.bazel +++ b/internal/telemetry/BUILD.bazel @@ -6,6 +6,7 @@ go_library( "batch_applier.go", "batch_closer.go", "batch_creator.go", + "batch_getter.go", "blockingannotator.go", "bootstrapper.go", "commenter.go", diff --git a/internal/types/types.go b/internal/types/types.go index fcba02e45..d92838761 100644 --- a/internal/types/types.go +++ b/internal/types/types.go @@ -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 diff --git a/issueops/BUILD.bazel b/issueops/BUILD.bazel index eb0076988..3e26c2f1a 100644 --- a/issueops/BUILD.bazel +++ b/issueops/BUILD.bazel @@ -6,6 +6,7 @@ go_library( "batchapplier.go", "batchcloser.go", "batchcreator.go", + "batchgetter.go", "blockedstate.go", "blockingannotator.go", "bootstrapper.go", diff --git a/issueops/batchgetter.go b/issueops/batchgetter.go index 2a54deaa7..6d6914c41 100644 --- a/issueops/batchgetter.go +++ b/issueops/batchgetter.go @@ -85,6 +85,9 @@ type GetManyResult struct { // 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. @@ -118,13 +121,15 @@ type GetManyResult struct { // 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 and in what a miss means: Get answers -// ONE id with *IssueDetails or ErrNotFound, this answers MANY ids with a -// result whose Missing field is how a caller tells "this one does not exist" -// from "the call failed." 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, hydrated, the way Reader.Get -// does for one. +// 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 From 923563f12af0cb51a27072b784356c00ead95843 Mon Sep 17 00:00:00 2001 From: Eddie the Engineer Date: Mon, 5 Oct 2026 16:18:57 +0000 Subject: [PATCH 3/4] fix(roles): sync client vocabulary and repo gates with issues:batchGet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../scripts/embedded-storage-test-shards.txt | 1 + internal/httpclient/encode/oracle_test.go | 2 ++ internal/httpclient/wire/handshake.go | 4 +++ internal/httpclient/wire/paths.go | 1 + .../httpclient/wire/revision_tolerance.go | 4 ++- .../wire/revision_tolerance_test.go | 34 ++++++++++++++++--- internal/httpclient/wire/skew_test.go | 16 ++++----- internal/httpclient/wire/vocabulary_test.go | 1 + internal/storage/uow/notifying_parity_test.go | 1 + 9 files changed, 51 insertions(+), 13 deletions(-) diff --git a/.github/scripts/embedded-storage-test-shards.txt b/.github/scripts/embedded-storage-test-shards.txt index 1502ba993..9d033d94a 100644 --- a/.github/scripts/embedded-storage-test-shards.txt +++ b/.github/scripts/embedded-storage-test-shards.txt @@ -353,6 +353,7 @@ 15 8 TestRemoteVerbPlainRemoteWithoutAuthPresentsNone 15 8 TestTransactionCleanupAfterSQLCommitIsIndeterminate +15 9 TestBatchGetterContract 15 9 TestCommenterContract 15 9 TestEmbeddedBatchCloserBackendFailureReturnsNoOutcomes 15 9 TestEmbeddedClaimerReclaimsItsOwnInProgressIssueWithoutWriting diff --git a/internal/httpclient/encode/oracle_test.go b/internal/httpclient/encode/oracle_test.go index e50e06dc7..d127a83c4 100644 --- a/internal/httpclient/encode/oracle_test.go +++ b/internal/httpclient/encode/oracle_test.go @@ -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 } diff --git a/internal/httpclient/wire/handshake.go b/internal/httpclient/wire/handshake.go index feae076dc..3960c50e1 100644 --- a/internal/httpclient/wire/handshake.go +++ b/internal/httpclient/wire/handshake.go @@ -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 diff --git a/internal/httpclient/wire/paths.go b/internal/httpclient/wire/paths.go index 097e5534f..195c101c3 100644 --- a/internal/httpclient/wire/paths.go +++ b/internal/httpclient/wire/paths.go @@ -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 diff --git a/internal/httpclient/wire/revision_tolerance.go b/internal/httpclient/wire/revision_tolerance.go index 82001d839..94b55748b 100644 --- a/internal/httpclient/wire/revision_tolerance.go +++ b/internal/httpclient/wire/revision_tolerance.go @@ -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): diff --git a/internal/httpclient/wire/revision_tolerance_test.go b/internal/httpclient/wire/revision_tolerance_test.go index 28a31660f..9b410298f 100644 --- a/internal/httpclient/wire/revision_tolerance_test.go +++ b/internal/httpclient/wire/revision_tolerance_test.go @@ -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) + } + } } diff --git a/internal/httpclient/wire/skew_test.go b/internal/httpclient/wire/skew_test.go index 6cf0465af..bf431d7c8 100644 --- a/internal/httpclient/wire/skew_test.go +++ b/internal/httpclient/wire/skew_test.go @@ -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 diff --git a/internal/httpclient/wire/vocabulary_test.go b/internal/httpclient/wire/vocabulary_test.go index 168f77ebb..4db0f3813 100644 --- a/internal/httpclient/wire/vocabulary_test.go +++ b/internal/httpclient/wire/vocabulary_test.go @@ -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 diff --git a/internal/storage/uow/notifying_parity_test.go b/internal/storage/uow/notifying_parity_test.go index 5bccc063e..5114f2212 100644 --- a/internal/storage/uow/notifying_parity_test.go +++ b/internal/storage/uow/notifying_parity_test.go @@ -145,6 +145,7 @@ func TestRecordingIssueUseCaseCoversItsSurface(t *testing.T) { "GetEpicsEligibleForClosure": reads, "GetIssue": reads, "GetIssuesByIDs": reads, + "GetMany": reads, "GetNewlyUnblockedByClose": reads, "GetNewlyUnblockedByCloseWisp": reads, "GetReadyWork": reads, From d05dac1c3eef9a69331488269cbb086d40612983 Mon Sep 17 00:00:00 2001 From: Eddie the Engineer Date: Mon, 5 Oct 2026 17:40:58 +0000 Subject: [PATCH 4/4] 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 --- cmd/bd/serve.go | 7 +- internal/httpapi/spec_parity_test.go | 26 ++++ internal/storage/issueops/BUILD.bazel | 1 + internal/storage/issueops/batchget_test.go | 136 +++++++++++++++++++++ 4 files changed, 167 insertions(+), 3 deletions(-) create mode 100644 internal/storage/issueops/batchget_test.go diff --git a/cmd/bd/serve.go b/cmd/bd/serve.go index 464062fc5..fd5b1ad76 100644 --- a/cmd/bd/serve.go +++ b/cmd/bd/serve.go @@ -849,9 +849,10 @@ type serveRoles struct { edges issueops.EdgeReader edgeCounter issueops.GraphCounter // batchGetter is the one-snapshot, many-ids read behind - // POST /v0/beads/issues:batchGet. Its accessor does NOT recurse through - // the hook decorator — it answers no writes — so it is taken off the - // peeled store with the rest for uniformity rather than out of necessity. + // 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 diff --git a/internal/httpapi/spec_parity_test.go b/internal/httpapi/spec_parity_test.go index b299f2b02..3d9fb664d 100644 --- a/internal/httpapi/spec_parity_test.go +++ b/internal/httpapi/spec_parity_test.go @@ -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 diff --git a/internal/storage/issueops/BUILD.bazel b/internal/storage/issueops/BUILD.bazel index 07dba8324..71512f91a 100644 --- a/internal/storage/issueops/BUILD.bazel +++ b/internal/storage/issueops/BUILD.bazel @@ -129,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", diff --git a/internal/storage/issueops/batchget_test.go b/internal/storage/issueops/batchget_test.go new file mode 100644 index 000000000..70ceb16cf --- /dev/null +++ b/internal/storage/issueops/batchget_test.go @@ -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) + } +}