* feat(roles): BatchGetter role and issues:batchGet route (S7)
Adds BatchGetter.GetMany(ids) -> {Issues, Missing}, a one-snapshot,
order-preserving, deduped, 1000-id-capped batch read, wired through all
three library legs (dolt, embedded dolt, uow) behind the existing
hook/telemetry decorator chain, plus the POST /v0/beads/issues:batchGet
HTTP route (spec, apigen, wire-shape golden, issues.batchGet capability
token). Conformance contract (RunBatchGetter*, 12 cases) passes on all
three legs against real backends. No HTTP client leg yet (waits on the
generator / PR #7247); left as a documented seam on BatchGetter's doc
comment.
CLI GetIssuesByIDs call sites are left unmigrated this slice and marked
with TODO(batchgetter) comments: every call site reads an unbounded id
list today, and GetMany's 1000-id cap has no chunking/fallback in any
caller yet, so swapping them in now would add a new, unhandled failure
mode to already-shipped CLI paths (export, import, molecule port,
ready-explain, wisp sweep).
Verified via three live-mutate guards against
internal/storage/issueops/batchget.go (disabling the cap check, dropping
the Missing append, and replacing ordered iteration with map iteration):
each turns the embedded-dolt contract red, confirming the cap, Missing
reporting, and order-preservation assertions actually catch a break.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(roles): close S7 review gaps — revision on wire, BUILD sync, handler tests
Addresses the S7 Opus review's FIX-FIRST items on BatchGetter/issues:batchGet:
HIGH
- batchGetResponse now projects apigen.BatchGetIssue (types.BatchGetIssue +
NewBatchGetIssue), carrying `revision` per issue the way IssueDetails does;
spec, apigen and the wire-shape golden regenerated (additive, no
wire_revision bump).
- make bazel-sync: the 12 files missing from BUILD.bazel srcs are back in
sync across 9 BUILD.bazel files.
- New internal/httpapi/batch_get_test.go: success incl. revision, missing
ids, empty arrays not null, unknown member refused, missing/null ids
refused, query parameter refused, 1001 ids refused with the full request
reaching the role, 1000 ids accepted.
MED
- RunBatchGetterAcceptsExactlyTheCap pins the cap boundary (> vs >=).
- RunBatchGetterHydratesLabels pins Labels survive projection.
- RunBatchGetterReadsOneSnapshot renamed to
RunBatchGetterSharesOneReadStructurally with a doc that no longer
overclaims atomicity; a real interleaving test needs a hook on the frozen
roleFixtureKit, out of scope here.
- Doc comments across ExecuteGetMany, GetManyResult.Issues and the
BatchGetter interface now say hydration is labels only.
LOW
- failBatchGetErr's doc no longer claims blank entries are "already caught".
- PR #7247 references kept.
Re-ran build/vet/gofmt/lint, make api-check, make bazel-sync(-check), the
full internal/httpapi suite, and all three conformance legs (dolt via the
pinned local server, embeddeddolt, uow) plus targeted cmd/bd serve tests —
all green. Live-mutate-guard reverified: cap >=, dropping Missing from the
response, and clearing Labels each now fail the relevant test.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(roles): sync client vocabulary and repo gates with issues:batchGet
The S7 route landed on the server without the sibling tables that hold
the rest of the tree set-equal with the server's surface, so five
tests and two manifest gates went red on the PR head:
- httpclient/wire: mirror batchGetIssues into the client vocabulary,
CLASSIFIED, not wired, the way the wire wave and #7250's
issues.count.scope landed: OpBatchGetIssues, its issues.batchGet
token on opCapability, its identity row, and the first-slice skew
dimension 35 -> 36 (TestCapabilityTableMatchesTheServerRouteTable).
- httpclient/wire: BatchGetIssue is the first golden.json schema with
a `revision` member that needs no legacy-integer tolerance — the
route postdates #6053 and types.BatchGetIssue declares Revision a
string, and a pre-#6053 server never advertises issues.batchGet, so
Preflight refuses before any body is decoded. Exempt it with that
reason in a new revisionSchemaExempt table rather than adding an
issues[] rewrite no legacy server can reach; the gate refuses an
entry that is both covered and exempt, a stale exemption, and an
empty reason.
- httpclient/encode: give the oracle's role set a BatchGetter stub —
httpapi.Listen requires the whole set, so all three oracle tests
failed to bind.
- storage/uow: exempt IssueUseCase.GetMany from the notifying-parity
partition as a read, the reason hook_batch_getter.go gives.
- shard manifest: place TestBatchGetterContract in the 15-shard
embedded storage block (generator --write, incremental).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(roles): pin the BatchGetter pure tier and the spec ids caps
Review fixes, iteration 1. The review approved with no blocker or major
finding and three minors, and this commit takes all three. It changes
tests and one comment only, and every new assertion was mutation-probed
with go test -overlay.
- storage/issueops: add batchget_test.go, the database-free tier that
FinishGetMany's doc already claimed ("pinned without a database") but
that no test supplied. It pins:
- the cap is checked before the blank scan (an over-cap request with
a blank at position 0 answers *TooManyIDsError);
- the bound is inclusive;
- dedupe keeps the first mention, does not trim, and never writes
through the caller's slice;
- Issues and Missing both follow request order;
- both slices are never nil;
- ExecuteGetMany refuses one id repeated past the cap before any
query (a sqlmock with no expectations).
Ten mutants were each killed by exactly their intended test, with the
rest of the package green: last-mention, sort, trim, in-place dedupe,
blank-before-cap, >=, nil Missing, nil Issues, dedupe-before-validate
and validate-after-query.
- httpapi: TestSpecDefaultsMatchSharedConstants now checks ids.maxItems
against the enforced bound on the two request bodies that carry an
`ids` list: batchGetIssues against issueops.MaxGetManyIDs, and
deleteIssues against maxDeleteIDs. Each body is reached through its
operation's own requestBody $ref. Setting either constant to 999 turns
only this test red. The spec's other list caps (batch
create/close/apply items, dependency edge lists) stay ungated, as
before.
- cmd/bd/serve.go: the batchGetter field comment said its accessor
"does NOT recurse through the hook decorator". HookFiringStore.
BatchGetter does recurse to the inner getter; it just doesn't wrap
the result. The comment now says that.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
149 lines
7.3 KiB
Go
149 lines
7.3 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
)
|
|
|
|
// MaxGetManyIDs is the largest request this role accepts in one call. It is a
|
|
// FLAT bound on the request, not a cost model over what a backend does with
|
|
// it: GetMany reads every named id in ONE snapshot, so the bound is really a
|
|
// bound on how long one request may hold a single read open.
|
|
//
|
|
// 1000 is the same number BatchApplier settled on (issueops.MaxApplyBatchItems)
|
|
// and the same number DeleteRequest.IDs caps at on the wire
|
|
// (openapi.v0.yaml's DeleteIssuesRequest). It is not borrowed for symmetry: a
|
|
// caller fanning out gc's ready veto or the CLI's own id-resolution passes
|
|
// already walks lists in exactly this range, and a cap an order of magnitude
|
|
// smaller would just reintroduce the per-id fan-out this role exists to
|
|
// replace.
|
|
const MaxGetManyIDs = 1000
|
|
|
|
// TooManyIDsError reports that a GetManyRequest named more ids than this role
|
|
// accepts in one call. It wraps ErrValidation, so a caller that only checks
|
|
// for a usable request classifies it correctly without knowing this type
|
|
// exists, and errors.As gets at Requested and Cap for a caller that wants to
|
|
// say how far over the line the request was.
|
|
type TooManyIDsError struct {
|
|
// Requested is the number of ids the request named, counted BEFORE
|
|
// deduplication: a caller that sent 1500 mentions of 3 distinct ids typed
|
|
// a request this role still refuses, because the obligation this cap
|
|
// bounds is reading the request apart, not reading the rows it resolves
|
|
// to.
|
|
Requested int
|
|
// Cap is MaxGetManyIDs, carried on the error so a caller does not need the
|
|
// constant in scope to report what it hit.
|
|
Cap int
|
|
}
|
|
|
|
func (e *TooManyIDsError) Error() string {
|
|
return fmt.Sprintf("get many accepts at most %d ids, got %d", e.Cap, e.Requested)
|
|
}
|
|
|
|
// Unwrap makes TooManyIDsError match ErrValidation.
|
|
func (e *TooManyIDsError) Unwrap() error { return ErrValidation }
|
|
|
|
// GetManyRequest names the issues to fetch in one read.
|
|
//
|
|
// Implementations never mutate caller-owned request values: IDs is read,
|
|
// never written through, and never sorted in place.
|
|
type GetManyRequest struct {
|
|
// IDs names the issues to fetch, in either plane, exact ids only. Prefix
|
|
// resolution and bd's other id conveniences happen at the front door,
|
|
// above this role, the same boundary DeleteRequest.IDs draws.
|
|
//
|
|
// DUPLICATES COLLAPSE and the surviving order is the caller's first
|
|
// mention of each id: a caller that asks for [a, b, a] gets back Issues
|
|
// in the order [a, b] (whichever of those resolve) and nothing about a
|
|
// twice.
|
|
//
|
|
// AN ID THAT NAMES NO STORED ROW IS NOT AN ERROR. It is reported in
|
|
// GetManyResult.Missing beside whatever else resolved — the same
|
|
// result-field answer EdgeCountResult.Anchors and EdgeReadResult give a
|
|
// miss, and the reason GetMany does not return ErrNotFound the way
|
|
// DeleteRequest's all-or-nothing id check does: a batch GET is a set
|
|
// read, not a precondition on every member succeeding.
|
|
//
|
|
// MORE THAN MaxGetManyIDs IS A REFUSAL: a *TooManyIDsError, counted on
|
|
// the request as sent, before deduplication.
|
|
//
|
|
// An empty slice is not an error. It answers with an empty result, the
|
|
// same empty-request answer EdgeCountRequest.IDs documents, because "no
|
|
// ids" is a legitimate thing to ask for 0 issues about and a caller that
|
|
// built its list by filtering should not have that filter's empty result
|
|
// turned into a different kind of failure than the one it already knows
|
|
// how to handle.
|
|
IDs []string
|
|
}
|
|
|
|
// GetManyResult answers a GetManyRequest from one snapshot.
|
|
type GetManyResult struct {
|
|
// Issues holds the hydrated rows for every id that resolved, in the
|
|
// REQUEST's order (the caller's first mention of each distinct id), never
|
|
// the storage engine's natural order. Each Issue carries its current
|
|
// RowVersion, so a caller that goes on to write one back has the
|
|
// optimistic-concurrency token a lifecycle write wants without a second
|
|
// round trip.
|
|
//
|
|
// HYDRATION IS LABELS ONLY: no dependencies, dependents or comments. A
|
|
// caller that needs those calls Reader.Get instead, one id at a time.
|
|
//
|
|
// Never nil for a successful call, even when it is empty: a front door
|
|
// that marshals this field emits [] rather than null, the same promise
|
|
// EdgeCountResult.Anchors makes.
|
|
Issues []*Issue
|
|
// Missing names every requested id that resolved to no stored row, in the
|
|
// same first-mention order as the request. An id that appears in Missing
|
|
// does not appear in Issues, and the two slices' lengths sum to the
|
|
// number of DISTINCT ids the request named.
|
|
//
|
|
// Never nil for a successful call: an all-found request answers with an
|
|
// empty, non-nil Missing.
|
|
Missing []string
|
|
}
|
|
|
|
// BatchGetter reads many issues by id in one snapshot.
|
|
//
|
|
// It exists because the obvious way to read N issues — one Get per id — is
|
|
// what gc's ready veto and the bd CLI both do today, and it costs N round
|
|
// trips (or N transactions, for a backend where each Get opens its own) to
|
|
// answer a single question a caller already knows the shape of: "which of
|
|
// these ids exist, and what do they look like right now." BatchGetter answers
|
|
// that in one call over one snapshot, the same trade EdgeCountRequest.IDs and
|
|
// EdgeReadRequest make for the edge-shaped versions of the same question.
|
|
//
|
|
// IT IS A FACADE-ONLY ROLE, for now: this slice wires every library leg
|
|
// (dolt, embedded dolt, the unit-of-work provider) and the
|
|
// POST /v0/beads/issues:batchGet HTTP handler, but ships no HTTP CLIENT leg.
|
|
// A caller on the wrong side of that door reaches this role through the raw
|
|
// HTTP request the handler answers, not through a typed client method, until
|
|
// the client generator lands (see the TODO beside the CLI call sites this
|
|
// slice did not migrate, and PR #7247). A later slice updates this doc and the
|
|
// client-side TODOs together once that leg exists.
|
|
//
|
|
// It differs from Reader.Get in arity, in hydration and in what a miss means:
|
|
// Get answers ONE id with *IssueDetails or ErrNotFound, labels, dependencies,
|
|
// dependents and comments included; this answers MANY ids with a result
|
|
// whose Missing field is how a caller tells "this one does not exist" from
|
|
// "the call failed," and whose Issues are hydrated LABELS ONLY — no
|
|
// dependencies, dependents or comments. A caller that needs those calls
|
|
// Reader.Get instead, one id at a time. It differs from EdgeReader and
|
|
// GraphCounter in what it is reading: those answer questions about the EDGES
|
|
// a set of anchors carries; this answers the ISSUES themselves.
|
|
type BatchGetter interface {
|
|
// GetMany reads every id GetManyRequest.IDs names, in ONE snapshot. The
|
|
// existence check and the hydration share that snapshot for the reason
|
|
// ExecuteEdgeCount's probe-and-tally share one: a probe in its own
|
|
// transaction could report an id missing while a second transaction
|
|
// created it, contradicting itself in one response body.
|
|
//
|
|
// Refuses with:
|
|
// - *TooManyIDsError, wrapping ErrValidation, when IDs carries more than
|
|
// MaxGetManyIDs entries (counted before deduplication);
|
|
// - ErrValidation for an empty-string entry in IDs, the same per-entry
|
|
// check EdgeCountRequest.IDs applies.
|
|
//
|
|
// Never returns ErrNotFound: an id naming no stored row is reported in
|
|
// GetManyResult.Missing, not refused.
|
|
GetMany(ctx context.Context, request GetManyRequest) (GetManyResult, error)
|
|
}
|