`bd dep list a b c --direction=down` asks a different question from every
other dep read: it answers with RAW EDGE ROWS keyed by source, for many
anchors at once, and it has to say per anchor whether that anchor exists.
Both routes answered it off-role — the direct one out of
GetDependencyRecordsForIssues, the proxied one out of a unit of work — and
neither could tell "this issue has no dependencies" from "there is no such
issue".
THE ROLE. Relations is the near sibling and it cannot answer this. It is
SINGLE-ANCHOR, it answers with the ISSUES on the far end of an anchor's
edges, and an edge whose target this database has no row for — an
`external:` reference, an id in another repository — is silently not a
neighbor. A missing anchor is ErrNotFound there, which a batch cannot use
without discarding the anchors it did find. Different answer shape,
different miss policy, different arity: three, so a new role and a new
accessor rather than a second Relations method. Q12 confirmed the split
against merging it with BlockingAnnotator, which answers a derived
best-effort decoration rather than stored rows.
The direction is OUTGOING only and there is no parameter for it. The inbound
bulk read is a different read against a different key with its own
cross-table de-duplication, and no front door asks for it; a direction
nothing sets would be a promise nothing checks.
TWO DEFECTS THE ADOPTION FIXES, both of them the same shape — a silent
change of JSON document:
- the KNOWN DEFECT. The direct route's batched read fell through to the
hydrated neighbor listing on ANY error, so a transient failure turned
`bd dep list a b --json` from an array of dependency records into an
array of ISSUES, with no error and no warning.
- the same fall-through fired whenever routing split the anchors across
stores, so a cross-rig batch emitted that other document every time. The
role is reached per store now and the answers merge back into argument
order, so a routed batch and a local one have one shape.
Also fixed on both routes: `--type` used to test emptiness BEFORE filtering,
so an anchor whose every edge the filter rejected printed a header with no
rows under it. The role filters, so it prints "has no dependencies".
USER-VISIBLE, approved in the Q11 batch: PROXIED `bd dep list` NOW REPORTS
GHOST ANCHORS. It used to hand the raw arguments to the dependency use case,
which keys its answer by source and has no entry for an id that names
nothing, so a typo printed "<id> has no dependencies" and a script read a
clean graph. The role probes each anchor, so a typo now prints the warning
the direct route has always printed for an argument it could not resolve —
on stderr, in both modes, which is what leaves `--json` the flat array of
dependency records the command documents. The proxied route still resolves
nothing: ids go to the role exactly as the caller spelled them, because that
route has never done partial-id resolution.
One behaviour had no prior decision behind it and is recorded as Q15 rather
than chosen quietly: a repeated anchor now collapses onto its first mention,
where the old loop over a keyed map printed it twice.
CONFORMANCE. backend/conformance/edge_reader_contract.go holds fourteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks. They are TWO independent bodies plus an engine check, not
three: dolt and embeddeddolt both call storage/issueops.ExecuteEdgeRead
inside their own read transaction, and the unit-of-work provider is the
second body — it probes existence through two batched by-id use-case reads
where the stores run one batched EXISTS over both tables.
The store-backed body is an InTx function rather than an
internal/workapi/store<role> package, which is a documented deviation from
the twelve-step checklist and the reason is Relations': the anchor probe and
the edge read must share ONE transaction, or an anchor can be reported
missing by a probe that raced a create the edge read then saw. That cannot
be expressed above storage.DoltStorage. engdocs/ADDING_AN_ISSUEOPS_ROLE.md
now names that variant, including why it needs no depguard entry — the
shared function takes a transaction, so no front door can call it.
HTTP. GET /v0/beads/dependencies is new canonical surface, spec written
first and the types generated from it. `items` is an array of the already
x-go-type-pinned `Dependency`, so the CLI's `--json` and this body stay one
compatibility domain; the new `DependencyEdges` envelope carries no allOf,
so the oapi-codegen v2.6.0 pin-dropping trap does not apply, and the
generated `Dependency` is still an alias. A ghost anchor is on `missing`
rather than a 404, for the reason the role reports it per anchor. There is
no `limit` and no cursor: `bd dep list` has none either, so the QUESTION is
bounded instead — at most 100 `issue_id` values — which bounds the work
without truncating an answer a client could not then page.
httpapi.Config's roles source grows from two roles to three, and Listen
refuses a partially-set set for the reason it already refused a half-set
pair: the missing role is a nil dereference in a handler on a live server.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean; TestEdgeReaderContract green at dolt (14/14), embeddeddolt (14/14)
and uow (14/14); ./internal/httpapi green; TestCorpusGolden green, so the
committed `bd dep list --json` fixture is byte-identical; TestEmbeddedDep
and TestProxiedServerDep2 green with their gates set; TestProxiedLookup
green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
36 lines
1.2 KiB
Go
36 lines
1.2 KiB
Go
package telemetry
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/steveyegge/beads/issueops"
|
|
)
|
|
|
|
// EdgeReader returns the inner store's stored-edge surface wrapped in this
|
|
// layer's instrumentation. It recurses instead of delegating: a blind
|
|
// delegation would return the inner reader unspanned and untimed.
|
|
func (s *InstrumentedStorage) EdgeReader() (issueops.EdgeReader, error) {
|
|
inner, err := s.Unwrap().EdgeReader()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return s.WrapEdgeReader(inner), nil
|
|
}
|
|
|
|
// WrapEdgeReader instruments guarded stored-edge reads with this storage
|
|
// layer's existing telemetry meter and tracer.
|
|
func (s *InstrumentedStorage) WrapEdgeReader(inner issueops.EdgeReader) issueops.EdgeReader {
|
|
return &instrumentedEdgeReader{storage: s, inner: inner}
|
|
}
|
|
|
|
type instrumentedEdgeReader struct {
|
|
storage *InstrumentedStorage
|
|
inner issueops.EdgeReader
|
|
}
|
|
|
|
func (r *instrumentedEdgeReader) ReadEdges(ctx context.Context, request issueops.EdgeReadRequest) (result issueops.EdgeReadResult, err error) {
|
|
ctx, span, started := r.storage.op(ctx, "EdgeReader.ReadEdges")
|
|
result, err = r.inner.ReadEdges(ctx, request)
|
|
r.storage.done(ctx, span, started, err)
|
|
return result, err
|
|
}
|