* test(storage): measure ApplyBatchInTx SQL statement counts (B0) Adds a driver.Connector-level counting/latency-injecting wrapper (internal/storage/sqlcount) plus shared plan-request fixtures (internal/storage/batchfixtures: mol-normalized 356/712-item shapes and a 40-item classic shape) and backend-specific pinning tests + benchmarks (internal/storage/embeddeddolt, internal/storage/dolt) that measure the ACTUAL number of SQL statements issueops.ApplyBatchInTx issues for each shape, on both the embedded and Dolt (TCP) backends. Measured totals (Prepare+Exec+Query+StmtExec+StmtQuery inside one transaction): 356 items ~7008-7009, 712 items 14014-14015, 40 items 846, identical on both backends (expected: statement issuance is driven by Go application logic, not backend-specific SQL planning). Pinned with a small (+/-2) tolerance to absorb an observed, host-contention-driven +/-1 Query drift (Exec is deterministic on every run). This is the regression baseline slice B2 (a later, lighter fast path) must demonstrably lower. batchfixtures.UncappedPlan bypasses issueops.MaxApplyBatchItems so this measurement does not depend on slice B1's cap raise. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * feat(httpapi,issueops): raise batchApply envelope to 1000 items with bounded large-apply handling POST /v0/beads/issues:batchApply now accepts up to 1000 items (up from 100); issueops.MaxApplyBatchItems moves accordingly and the request body cap rises to 16 MiB. The whole plan still applies in exactly ONE transaction. A request over 100 items runs under a separate, flat, operator-configured whole-run budget (`bd serve --large-apply-ceiling`, 5 minutes by default) instead of the ordinary 60s request deadline; a request at or under 100 items is unaffected and keeps exactly the 60s deadline and 15s commit-retry ceiling it always had. Concurrency and shutdown are bounded, not just documented: - Oversized requests serialize through a dedicated one-wide semaphore, and at most one caller may wait for that semaphore at a time (a CAS-guarded single waiter) — a burst of oversized requests is shed with 503 rather than queuing and starving ordinary traffic behind the general semaphore. - The run deadline is stamped only once the slot is actually acquired, not at the time the request arrived. - Graceful shutdown closes new admissions before computing its drain budget, then waits out an in-flight large apply up to its own remaining deadline (plus a few seconds' grace for the response to write); any large apply still queued for the semaphore when shutdown begins is refused rather than extending the drain further. A queued caller that disconnects gets a clean 503, never a misclassified context error. `bd serve`'s orchestrator stop grace must be at least `--large-apply-ceiling` — see engdocs/SERVE_RUNBOOK.md. - ApplyBatch's commit-retry budget only extends past the ordinary 15s ceiling on this explicit large-apply path (via a context marker), with headroom reserved so the final retry attempt can't be killed mid-commit by the context's own expiry. A new `issues.batchApplyLarge` capability token on `GET /v0/beads/context` lets a client learn whether a given server accepts the raised envelope. Wall-clock measurement (embedded Dolt, whole-transaction build+commit) backs the 5-minute ceiling default: 356 items ~12.6s (23.8x headroom), 1000 items ~57.5s (5.2x headroom). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(httpapi,serve): wire the large-apply retry budget; repair stale pins Review fixes for the large batchApply envelope, on top of the test repairs the PR needed against main. The extended commit-retry budget was never switched on. internal/storage/uow's retryTxBudget lets a large apply keep retrying a commit-time conflict past the ordinary 15s ceiling only when its context carries issueops.WithExtendedRetryBudget's marker, and the docs on both sides say admitLargeApply sets it, but nothing did: the marker's only callers were the uow tests, which mark their contexts by hand. A 1000-item apply that hit a conflict still gave up after 15s with most of its 5-minute ceiling unused. admitLargeApply now marks the run context it builds, and TestApplyBatchMarksOnlyALargeApplyForTheExtendedRetryBudget pins the seam over HTTP: marked at 101 and 1000 items, unmarked at 100. Removing the mark fails the 101 and 1000 cases; marking every request in handleApplyBatch fails the 100 case. Smaller fixes from the same review: - `bd serve --large-apply-ceiling` repeated the 5m default as a literal of its own, and since bd serve always passes a positive ceiling, that literal, not httpapi's, was the default every deployment ran. Export httpapi.DefaultLargeApplyCeiling, default the flag to it, and pin the flag's 5m0s default in TestServeFlags. - admitLargeApply's release cancels the run context before clearing s.largeApplyDeadline, the order acquireLargeApply's doc states; it cleared the deadline first. - Drop the batchfixtures test's dead t.Skipf, which waited for the cap to reach 1000, and correct a graph-counter comment that still cited the 100-item cap and the TestServeFlags doc line that called the no-argument server unchanged. The PR raises issueops.MaxApplyBatchItems from 100 to 1000 and adds `bd serve --large-apply-ceiling`, but two base-owned tests still pinned the old surface and went red on every lane that runs them (Bazel / test, Test (macos-latest)): - TestServeFlags pins the exact `bd serve` flag list; add large-apply-ceiling. - TestPlanApplyBatchRefusesAnUnusableRequest/too_many_items built 101 items and expected "at most 100 items", a request the 1000 cap now plans successfully. Size the over-cap request and its message from issueops.MaxApplyBatchItems, as TestPlanApplyBatchAcceptsTheBoundary already does for the other side of the cap; the cap's value stays pinned by TestCapBatchApplyLargeTiesAllThreeLimits. The PR's own TestLargeApplyBurstNeverStarvesSmallRequestsForSemTimeout also went red in PR Core (-race, -p 4 on a 4-vCPU runner): all eight small requests took 160-165ms against a 100ms bound. The stall it guards against lasts semTimeout (5s), while a small request can still queue briefly behind the refused large requests, each holding a general sem slot while its body decodes. Bound it at a second, the "want well under a second" its sibling TestLargeApplyQueueDoesNotStarveOrdinaryRequests already uses. Pinned to four cores beside 24 busy loops, small requests measured 183ms mean and 338ms max, and the 1s bound passed 80/80 runs; with the one-waiter gate in acquireLargeApply disabled the test still fails 3/3, on its 2s never-completed check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(uow): stop a doomed large-apply retry before ctx cuts it off retryTxBudget sizes maxElapsed once at ApplyBatch entry, but says nothing about how long an individual attempt takes. A slow first attempt (e.g. 157s of a large apply's commit) left little of the budget for a retry, which then got killed mid-transaction by ctx's own deadline instead of finishing and reporting its own outcome -- surfacing as context.DeadlineExceeded (isUnavailable excludes it -> a generic 500) instead of the exhausted-write-conflict result this loop already reports correctly (-> 503 + Retry-After). RunTxResultWithin now tracks the previous attempt's duration and, before starting a new one, stops early with the last real serialization error when time left on ctx is less than that duration plus a fixed headroom -- but only when publicops.HasExtendedRetryBudget(ctx) is set (the same marker retryTxBudget itself checks). Applying the look-ahead unconditionally regressed TestApplyBatchHonorsAnExtendedRetryBudgetFromContext's unmarked case: ordinary requests have cheap attempts and are meant to run until their own ctx deadline ends the loop, and the large-apply-sized 5s headroom was tripping that for any short-ctx caller with a near-instant failing attempt. Adds TestRunTxResultWithin_SlowAttemptStopsBeforeADoomedRetry (a 1.2s commit against a 2s marked ctx must stop after one attempt with its own serialization error, never DeadlineExceeded, and never touch a second unit of work) and its control, TestRunTxResultWithin_ShortAttemptStillRetries (a 50ms attempt against the same shape must still retry and succeed). Both mutation-checked against the look-ahead condition and its gate. Also updates the stale "items accepts at most 100 entries" prose on the applyBatch endpoint description (openapi.v0.yaml) to the large-envelope wording already used elsewhere in the spec: 1000-item cap behind the issues.batchApplyLarge capability, large-apply-ceiling deadline extension, <=100 unaffected. dependencies:count's own "at most 100" lines are unrelated and untouched. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(ci,serve): fit the 1000-item cap's tests in the storage shard budget Review fixes for the relaunched #7051, iteration 1. Raising issueops.MaxApplyBatchItems from 100 to 1000 made the base-owned TestBatchApplyContract take 604s under -race, against 97s at the old cap (main run 35862663577). It hashed onto the legacy test-embedded-storage shard 2/5, beside ~5m of other tests, and that shard hit its 15m budget twice (PR Risk run 36807191489). PR Risk no longer runs the legacy tier on same-repo PRs (#7071), but Main's push run and fork PRs still do, so the merge would have carried the timeout to Main. Raising the jobs' timeout-minutes alone would not fix it: the shard script passes the binary its own -test.timeout=15m. So: - embedded-storage-test-shard.sh passes -test.timeout=20m (and its go test fallback -timeout 20m), as embedded-test-shard.sh does for cmd/bd. - test-embedded-storage in main.yml and pr-risk.yml: timeout-minutes 15 -> 25, the script's 20m plus setup. - embeddeddolt_embedded_test appends -test.timeout=19m, as bd_embedded_test does, so Go's timeout, which dumps every goroutine, fires before rbe-west's 1200s action kill, which does not. TestBazelEmbeddedJobMirrorsEmbeddedTier now checks the override on both sharded targets instead of only cmd/bd's, and the PR Risk coverage test pins the storage target's new args. - embedded-storage-test-shards.txt places TestBatchApplyContract on shard 4, which has ~3m of other tests, and the PR's two large-batch tests, TestLargeBatchApplyStatementCounts_Embedded (247s) and TestLargeBatchApplyWallClock_Embedded (261s), on shards 2 and 5. From the PR run's per-test times, the heaviest shard projects to ~13m, down from shard 2's 15m-plus. Also correct the stop-grace guidance. For an in-flight large apply, Serve's drain waits out the apply's remaining deadline plus drainGrace (5s), so the orchestrator's stop grace must be at least --large-apply-ceiling plus 5s, as Serve's own doc says. The runbook, the flag help, the LargeApplyCeiling field doc and the CHANGELOG entry asked for the ceiling alone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
286 lines
16 KiB
Go
286 lines
16 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
)
|
|
|
|
// EdgeDirection names which end of a dependency edge an anchor sits on. The set
|
|
// is CLOSED and there is no zero value in it: a request that leaves the
|
|
// direction unset is ErrValidation rather than a count in some default
|
|
// direction.
|
|
//
|
|
// Requiring it is the one deliberate unfriendliness on this request. The two
|
|
// answers are about DIFFERENT EDGE SETS — "what does this depend on" and "what
|
|
// depends on this" — and a workspace where most issues have edges in only one
|
|
// direction returns the same number for both often enough that a caller who
|
|
// meant the other one would not notice for a long time. The raw storage seam
|
|
// spells the difference in the METHOD NAME (CountDependents, CountDependencies)
|
|
// and cannot make that mistake; a request field can, so it is required instead.
|
|
type EdgeDirection string
|
|
|
|
const (
|
|
// EdgeDirectionOut counts the anchor's DEPENDENCIES: edges whose source is
|
|
// the anchor. This is the direction `bd dep list` reads and the number
|
|
// `bd show` prints as the dependency count.
|
|
EdgeDirectionOut EdgeDirection = "out"
|
|
// EdgeDirectionIn counts the anchor's DEPENDENTS: edges whose target is the
|
|
// anchor.
|
|
EdgeDirectionIn EdgeDirection = "in"
|
|
)
|
|
|
|
// EdgeCountRequest describes one edge-cardinality question asked of several
|
|
// anchors at once.
|
|
//
|
|
// IT IS THE COUNTING SIBLING OF EdgeReadRequest and is spelled to match it
|
|
// field for field where the two share a meaning — IDs de-duplicate onto first
|
|
// mention, Types narrows edges and never anchors, an empty slice asks about no
|
|
// anchors — so a caller holding both cannot believe the two questions are asked
|
|
// of different sets. Two things are here that are not there: Direction, which
|
|
// EdgeReadRequest deliberately lacks (edgereader.go's EdgeReader doc says the
|
|
// inbound bulk read "gets its own role" when something needs it, and counting
|
|
// is where something did), and Status.
|
|
//
|
|
// THERE IS NO PAGE, no limit and no offset, for the reason CountRequest gives:
|
|
// a count is a cardinality, and bounding the scan would answer "how many of the
|
|
// first N".
|
|
//
|
|
// THERE IS NO "BOTH" DIRECTION. A caller that wants the pair asks twice, which
|
|
// is what every front door in the tree already does — internal/workapi's detail
|
|
// assembly calls CountDependents and CountDependencies as two separate reads
|
|
// today. Answering both in one call would mean two numbers per anchor, and then
|
|
// Status — which narrows by a row only the inbound direction has (see that
|
|
// field) — would apply to one of them and silently not to the other. A field
|
|
// that quietly governs half an answer is the shape this request is written to
|
|
// avoid.
|
|
type EdgeCountRequest struct {
|
|
// IDs are the anchors, each an EXACT canonical id, with the same
|
|
// promise-rather-than-obligation EdgeReadRequest.IDs states: a case variant,
|
|
// surrounding whitespace, a prefix of a real id and a real id with a suffix
|
|
// are all MISSES, not resolutions. A front door that wants partial-id
|
|
// resolution resolves before it calls.
|
|
//
|
|
// A miss is PER ANCHOR and reported on that anchor — see
|
|
// AnchorEdgeCount.Missing — rather than failing the call.
|
|
//
|
|
// AN EMPTY ENTRY IS ErrValidation. The empty string names nothing a caller
|
|
// can have meant, and reporting it as a missing anchor would put a nameless
|
|
// row in an answer keyed by name.
|
|
//
|
|
// AN EMPTY SLICE IS NOT AN ERROR: it asks about no anchors and the answer is
|
|
// no anchors. The direction is still validated first, so EdgeCountRequest{}
|
|
// is ErrValidation on Direction and not an empty answer.
|
|
//
|
|
// REPEATS COLLAPSE onto the first mention, for EdgeReadRequest.IDs's reason:
|
|
// a second entry for the same anchor carries no second fact and would only
|
|
// invite a caller summing the result to count the same edges twice.
|
|
//
|
|
// THERE IS NO SIZE CAP HERE, exactly as there is none on EdgeReadRequest.IDs.
|
|
// The reads are batched internally, and an in-process caller that holds the
|
|
// role has already paid for the slice it is passing; a cap on the role would
|
|
// be a limit invented for a caller that is not the one that needs it. The
|
|
// bound belongs to the WIRE operation, where the request arrives from
|
|
// somewhere else and the cost of an unbounded one is a stranger's — the
|
|
// split ApplyBatchRequest.Items makes explicitly with MaxApplyBatchItems.
|
|
// The graph-counts wire slice set it: GET /v0/beads/dependencies:count
|
|
// bounds `issue_id` at minItems 1, maxItems 100.
|
|
IDs []string
|
|
|
|
// Direction is which edges the count is over, and it is REQUIRED. An empty
|
|
// or unrecognized value is ErrValidation. See EdgeDirection.
|
|
Direction EdgeDirection
|
|
|
|
// Types restricts the count to these edge types. Empty means every type.
|
|
//
|
|
// An entry is checked for being a value at all — non-empty, within the
|
|
// column's length — and NEVER for membership of a known-types list, exactly
|
|
// as EdgeReadRequest.Types is: the vocabulary is OPEN, so a workspace's own
|
|
// type has to be able to filter. An unusable entry is ErrValidation rather
|
|
// than a filter that quietly matches nothing; an unrecognized but usable one
|
|
// is accepted and matches no edge.
|
|
//
|
|
// The filter narrows EDGES, never anchors. An anchor whose every edge it
|
|
// rejects comes back present with a count of 0, which is a different fact
|
|
// from an anchor that is not there.
|
|
Types []DependencyType
|
|
|
|
// Status restricts the count to edges whose DEPENDENT — the issue at the
|
|
// SOURCE end, the one doing the depending — is in this stored status. Empty
|
|
// means every status.
|
|
//
|
|
// IT IS LEGAL ONLY WITH EdgeDirectionIn, and a non-empty Status beside
|
|
// EdgeDirectionOut is ErrValidation rather than a filter that is ignored.
|
|
// The asymmetry is the substrate's, not a preference: narrowing by status
|
|
// means joining the far end of the edge to the row that holds its status,
|
|
// and an OUTBOUND edge's far end may be a row this database does not hold at
|
|
// all — DependencyEditor accepts an "external:" reference and an id
|
|
// belonging to another repository as targets. A status filter on that
|
|
// direction would silently drop every dangling edge, which is precisely the
|
|
// class of edge EdgeReader exists to return verbatim. The raw storage seam
|
|
// has the same asymmetry and states it the same way: it publishes
|
|
// CountDependentsByStatus and no CountDependenciesByStatus.
|
|
//
|
|
// It is NOT validated against the workspace vocabulary and is NOT a
|
|
// comma-separated OR set: an unrecognized name matches nothing and counts 0
|
|
// rather than failing, exactly as CountRequest.Status does. A scripted
|
|
// caller counting a status its workspace has since dropped currently reads 0
|
|
// and should keep reading 0.
|
|
//
|
|
// The status is read from the dependent's OWN PLANE: a durable dependent's
|
|
// from the issues table, an ephemeral one's from the wisps table. An edge
|
|
// whose source row has been deleted out from under it joins to nothing and
|
|
// is not counted, which is the one way a status-narrowed count can be
|
|
// smaller than the unnarrowed count by more than the statuses explain.
|
|
Status string
|
|
}
|
|
|
|
// AnchorEdgeCount is one anchor's edge cardinality, or the report that the
|
|
// anchor is not there.
|
|
type AnchorEdgeCount struct {
|
|
// ID is the anchor, spelled exactly as the request spelled it.
|
|
ID string
|
|
// Count is how many stored edges match the request in the requested
|
|
// direction, after the type and status filters.
|
|
//
|
|
// IT SPANS BOTH DEPENDENCY PLANES. An edge lives in `dependencies` or in
|
|
// `wisp_dependencies` according to which plane its SOURCE sits on, and this
|
|
// count is the total across the two — so a durable issue's dependent count
|
|
// includes the wisps that depend on it, and a wisp's dependency count
|
|
// includes the durable issues it depends on. That is the shipped answer of
|
|
// every raw count this role covers and of the domain body behind the
|
|
// unit-of-work leg (CountDependencyEdgesInTx), and it is what makes the
|
|
// number agree with the row list a caller gets from the matching read.
|
|
//
|
|
// It is a SUM over the two planes and NOT a distinct count of edge rows. The
|
|
// two are the same number unless one row id is present in both tables, which
|
|
// is a durable/ephemeral mirror the paging read de-duplicates for its keyset
|
|
// contract (CountDependentRecords) and this count never has. Nothing in this
|
|
// contract's reach can produce one — a seeded edge is routed to exactly one
|
|
// plane by its source — so the distinction is stated rather than pinned.
|
|
//
|
|
// UNREACHABLE HERE IS NOT UNREACHABLE IN PRODUCTION, and the difference is
|
|
// worth the extra sentence because "the contract cannot build it" reads too
|
|
// easily as "it cannot happen". A collision is real: dependency row ids are
|
|
// derived from (issue_id, target) and omit the table, so a wisp PROMOTED to
|
|
// durable, or two Dolt clones MERGED, leave one logical edge in both tables.
|
|
// TestDependentRecordsCrossTableCollision constructs exactly that state and
|
|
// names those two paths. What this role promises against it is the sum, the
|
|
// same answer the raw counts give, and a caller that needs the distinct
|
|
// total is asking CountDependentRecords' question rather than this one.
|
|
//
|
|
// A missing anchor counts 0.
|
|
Count int64
|
|
// Missing reports that no issue and no wisp carries this id.
|
|
//
|
|
// It exists for AnchorEdges.Missing's reason and one sharper: a count of 0
|
|
// is otherwise indistinguishable from a typo, and 0 is the COMMON answer —
|
|
// most issues have no edges in at least one direction — so the typo would
|
|
// never surface. This is the field that keeps this role from being a
|
|
// question a caller cannot tell it got wrong.
|
|
//
|
|
// A missing anchor's count is 0 even where orphaned rows are still keyed to
|
|
// it: a dependency row whose source has been deleted is orphaned data, and
|
|
// counting it would contradict the flag beside it. That mirrors
|
|
// FinishEdgeRead, which drops such rows from a missing anchor's edge list.
|
|
//
|
|
// DANGLING EDGES ARE NOT MISSING ANCHORS. This flag is about the ANCHOR. An
|
|
// edge whose other end names nothing is counted like any other edge, and
|
|
// nothing here reports on it.
|
|
Missing bool
|
|
}
|
|
|
|
// EdgeCountResult is the per-anchor answer.
|
|
type EdgeCountResult struct {
|
|
// Anchors carries one entry per DISTINCT requested id, in the order the
|
|
// request first named it. It is never nil for a successful call, and it is a
|
|
// slice rather than a map for EdgeReadResult.Anchors's reason: the request's
|
|
// order is part of the answer, and a map would have made that ordering each
|
|
// surface's own invention. A map would also be the one result shape a wire
|
|
// operation cannot carry without inventing a key vocabulary.
|
|
Anchors []AnchorEdgeCount
|
|
}
|
|
|
|
// GraphCounter describes counting DEPENDENCY EDGES around several anchors at
|
|
// once — and, like Counter, EdgeReader and Relations, a role with its own
|
|
// accessor. A new capability gets a new role interface and its own accessor;
|
|
// never append a method here.
|
|
//
|
|
// IT IS ITS OWN ROLE RATHER THAN A THIRD Counter METHOD. Counter answers about
|
|
// a set of ISSUES described by a predicate over one table; its request carries
|
|
// twenty-odd filter fields and none of them says anything about an edge. This
|
|
// role answers about EDGES, is anchored on ids rather than described by a
|
|
// predicate, and its answer is per-anchor rather than one number. Folding it in
|
|
// would have meant a CountRequest carrying an anchor list and a direction that
|
|
// every other count must ignore.
|
|
//
|
|
// IT IS ALSO NOT EdgeReader COUNTED. That role answers with the edge ROWS, in a
|
|
// pinned order, for the outbound direction only; the rows are the answer there,
|
|
// and the front door prints them. Here the number is the answer, both directions
|
|
// are askable, and no row is materialized — which is the point, because the
|
|
// surfaces that want these numbers (`bd show`'s header, a list view's
|
|
// per-row decoration) want them for issues whose edges they will never print.
|
|
//
|
|
// WHAT IS DELIBERATELY NOT HERE, and why, since the never-append rule makes
|
|
// each of these a decision rather than an omission:
|
|
//
|
|
// - THE COMMENT COUNT. `bd show` prints one beside the two edge counts and
|
|
// the raw seam publishes CountIssueComments, so it is genuinely consumed —
|
|
// but a comment is not an edge, it has no direction, no type and no far
|
|
// end, and every field of EdgeCountRequest below IDs would be meaningless
|
|
// to it. It is a different QUESTION in the sense the role test means, and it
|
|
// belongs beside Commenter.
|
|
// - THE EVENT COUNT. CountEvents has no caller in this tree at all, and the
|
|
// audit journal is a plane of its own with its own retention and scoping
|
|
// rules. It follows the journal, not the graph.
|
|
// - THE ISSUE COUNT and its grouped form, which are Counter's, and the READY
|
|
// count, which is ReadyCounter's.
|
|
// - THE PAIRED, BLOCKS-ONLY BATCH the raw seam publishes as
|
|
// GetDependencyCounts. Its answer is expressible here as two calls with
|
|
// Types set to the blocking type, and its callers are front doors this role
|
|
// does not re-route; naming it as a third method would have added a shape
|
|
// — a map keyed by id carrying two numbers — that no wire operation can
|
|
// carry and that this result deliberately does not have.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply validation and normalization only to
|
|
// attempt-local clones. EdgeCountRequest travels by value, so IDs and Types are
|
|
// the members a body could otherwise write through to the caller: reading them
|
|
// into a set is fine, sorting or de-duplicating them in place is not.
|
|
//
|
|
// Counting edges is a READ. Nothing here records a history entry, fires a
|
|
// completion hook or changes a row, and a refusal changes nothing either.
|
|
// Deterministic request-validation failures match ErrValidation; result values
|
|
// are unspecified when error is non-nil.
|
|
//
|
|
// THERE WAS NO FRONT DOOR AT ALL IN THE SLICE THAT INTRODUCED THIS ROLE,
|
|
// neither CLI nor HTTP, and that was written down here rather than left to be
|
|
// inferred — the way VersionReconciler writes down its absent HTTP half and
|
|
// BatchApplier its absent CLI. What a facade-only slice buys is ONE place where
|
|
// the direction, the plane span, the missing-anchor rule and the status
|
|
// asymmetry are stated and held to on three legs, before either surface has to
|
|
// agree with the other.
|
|
//
|
|
// THE HTTP HALF HAS SINCE LANDED: GET /v0/beads/dependencies:count publishes
|
|
// this role's whole filter surface, and the anchor bound this request
|
|
// deliberately leaves to the wire is set there. THE CLI HALF STILL HAS NOT, and
|
|
// that is still a decision rather than a gap: the numbers this role answers are
|
|
// already printed by `bd show`, which reads them through internal/workapi's
|
|
// detail seam — a seam shared with an HTTP handler, so moving it is its own
|
|
// change with its own parity argument.
|
|
type GraphCounter interface {
|
|
// CountEdges returns each anchor's edge cardinality in the requested
|
|
// direction.
|
|
//
|
|
// The anchors' existence and their edge counts are read from ONE consistent
|
|
// view, so an anchor cannot be reported missing by a probe that raced a
|
|
// create the count then saw. That is the same promise EdgeReader.ReadEdges
|
|
// makes, and it is the reason this is one method rather than a caller's
|
|
// existence check followed by a caller's count.
|
|
//
|
|
// A request naming only anchors that are not there is a successful call
|
|
// whose every entry reports Missing with a count of 0: there is no
|
|
// ErrNotFound on this role, because a batch that failed for one absent id
|
|
// would throw away the answers for the ids that were found — and because a
|
|
// question about a set has an answer even when the set is empty, which is
|
|
// the whole of Counter's not-found story too.
|
|
CountEdges(ctx context.Context, req EdgeCountRequest) (EdgeCountResult, error)
|
|
}
|