Delete the comment ghosts this series left in internal/httpapi

Waves 2, 3 and 4 each widened the roles-backed database source, and each one
rewrote the same paragraphs to say "and also this new role" — without deleting
the sentence it was replacing. Six blocks accumulated two or three overlapping
variants, and some of the leftovers were sentence FRAGMENTS with no subject:

	// a nil dereference inside a handler, and a pair without a ready counter
	// would do the same on the one read that is not the reader's.

Others were actively wrong by the time the next wave landed — Config's field
doc still opened "Reader, Claimer, Settings and Stats are the roles" above
thirteen fields, checkDatabaseSource carried three versions of one paragraph,
and a test doc said "drives all six" directly above "drives all five".

Each block now keeps one statement, phrased so the next role does not require
rewriting it: "the fields below", "every database-touching operation", "one
issueops role each". The worked example in Config no longer enumerates
accessors it would fall behind on; it names cmd/bd's serveIssueRoles, which is
that loop written out and is compile-checked against the real set.

No behavior change; comments and one test doc only.

Found by scanning this series' whole diff for near-duplicate lines inside a
single comment block, which is what the accumulation looks like mechanically.
The other seven hits that scan produced were false positives — CHANGELOG lines
that differ only in an issue number, and code samples inside comments.
This commit is contained in:
CI Bot 2026-08-06 05:43:43 +00:00
commit 8baf16989d
3 changed files with 32 additions and 99 deletions

View file

@ -36,7 +36,6 @@ import (
// The vocabulary is a one-way door: renaming or removing a documented
// status+code pair breaks the wire. Adding one does not, which is why clients
// are told to default-branch on unknown codes within a status class. Keep it
// at what the seven v0 operations actually need.
// at what the v0 operations actually need.
type Code string
@ -194,8 +193,6 @@ const (
// /healthz — the Host-header middleware, and the unknown-query-parameter
// refusal every decoder performs — and both are deliberately absent from every
// row here. They are uniform rules, not per-operation behavior, and the spec
// documents them once at the document level rather than repeating them on all
// twelve operations; these rows carry what an operation produces beyond them.
// documents them once at the document level rather than repeating them on
// every operation; these rows carry what an operation produces beyond them.
// Keep the two documents in step: a row here and the document-level prose are

View file

@ -18,22 +18,9 @@ import (
)
// These tests cover the OTHER database source: a backend whose facade is a
// store rather than a unit-of-work provider, served by handing Listen the roles
// directly.
// store rather than a unit-of-work provider, served by handing Listen the issue
// store rather than a unit-of-work provider, served by handing Listen the
// roles directly.
//
// The fakes below implement issueops.Reader, issueops.Claimer,
// issueops.WorkspaceConfig and issueops.StatsReporter and NOTHING else —
// deliberately not uow.UnitOfWorkProvider, because "a backend that cannot
// produce a unit of work is still servable" is the property this whole seam
// exists for. If any of them ever grows a NewUOW method these tests stop
// proving it.
// The fakes below implement issueops.Reader, issueops.Claimer and
// issueops.EdgeReader and NOTHING else — deliberately not
// uow.UnitOfWorkProvider, because "a backend that cannot produce a unit of work
// is still servable" is the property this whole seam exists for. If any of them
// ever grows a NewUOW method these tests stop proving it.
// The fakes below implement one issueops role each and NOTHING else —
// deliberately not uow.UnitOfWorkProvider, because "a backend that cannot
// produce a unit of work is still servable" is the property this whole seam
@ -526,18 +513,12 @@ func countedPage() []*types.IssueWithCounts {
// replaced the old nil-provider check.
//
// The two refusals are different mistakes and must stay distinguishable. A
// HALF-SET set is the dangerous one: a Config carrying a reader and no claimer
// would bind, answer every read, and fail the one issue write on this surface
// with a nil dereference — at claim time, in a handler, on a live server.
// PARTIALLY-SET role set is the dangerous one: a Config carrying a reader and
// no claimer would bind, answer every read, and fail the one write on this
// surface with a nil dereference — at claim time, in a handler, on a live
// server. Each role an operation reaches has a row here for the same reason.
// PARTIAL set is the dangerous one: a Config carrying a reader and no claimer
// would bind, answer every read, and fail the one write on this surface with a
// nil dereference — at claim time, in a handler, on a live server. The set
// grows with the surface, so the case that matters most is the newest role
// missing: that is what a caller written against the previous release passes.
// nil dereference — at claim time, in a handler, on a live server. Each role an
// operation reaches has a row below for that reason, and the case that matters
// most is the NEWEST role missing: that is what a caller written against the
// previous release passes.
func TestListenRequiresExactlyOneDatabaseSource(t *testing.T) {
for _, tc := range []struct {
name string
@ -775,11 +756,6 @@ func TestConfiguredRolesServeTheSameReadyBytesAsAProvider(t *testing.T) {
}
}
// TestConfiguredRolesAnswerEveryDatabaseRoute drives all six
// TestConfiguredRolesAnswerEveryDatabaseRoute drives all five
// database-touching operations against a store-shaped source, which is the
// whole point: none of them can reach a unit of work here, because there is no
// provider to open one.
// TestConfiguredRolesAnswerEveryDatabaseRoute drives every database-touching
// operation against a store-shaped source, which is the whole point: none of
// them can reach a unit of work here, because there is no provider to open one.

View file

@ -120,35 +120,21 @@ type Config struct {
// Provider is where every database-touching handler opens its one unit of
// work per request.
Provider uow.UnitOfWorkProvider
// Reader, Claimer, Settings and Stats are the roles this server answers
// from, for a backend whose facade is a STORE rather than a unit-of-work
// provider. sourceRoles is the authoritative list.
// Reader, Claimer and EdgeReader are the issue roles this server answers
// Reader, Claimer and ReadyCounter are the issue roles this server answers
// from, for a backend whose facade is a STORE rather than a unit-of-work
// provider.
// The fields below are the roles this server answers from, for a backend
// whose facade is a STORE rather than a unit-of-work provider. sourceRoles
// is the authoritative list.
//
// Set them together, and only when Provider is nil: they are the other
// Set them all together, and only when Provider is nil: they are the other
// Set all three together, and only when Provider is nil: they are the other
// Set them ALL, and only when Provider is nil: together they are the other
// complete database source, not an override of one. Listen refuses every
// other combination, including a PARTIAL set — a reader without a claimer
// other combination, including a partial set — a reader without a claimer
// would bind, answer every read, and fail the one write on this surface with
// a nil dereference inside a handler, and the same is true of every
// operation whose role is missing.
// other combination, including a partial set — a server missing one role
// would bind, answer every other route, and fail that one with a nil
// dereference inside a handler on a live server, which is worse than not
// starting.
//
// The set grows as operations do: each role a new operation reaches becomes
// another field here and another one this source must carry, because a
// database source that answers some operations and faults on others is not
// a source.
// other combination, including a partially-set set — a server missing one
// role would bind, answer every other route, and fail that one with a nil
// dereference inside a handler on a live server. The set grows by one each
// time an operation reaches a role this source does not yet carry, and it
// grows in the same change as the operation for exactly that reason.
// a nil dereference inside a handler, and a pair without a ready counter
// would do the same on the one read that is not the reader's.
// another field here and another one this source must carry, in the same
// change as the operation, because a database source that answers some
// operations and faults on others is not a source.
//
// A caller with a store takes them off the store's own accessors, and WHICH
// store value it takes them off is the whole question. Every decorator a
@ -165,15 +151,10 @@ type Config struct {
// }
// rd, err := src.IssueReader()
// cl, err := src.IssueClaimer()
// wc, err := src.WorkspaceConfig()
// st, err := src.StatsReporter()
// httpapi.Listen(httpapi.Config{Reader: rd, Claimer: cl, Settings: wc, Stats: st, ...})
// ed, err := src.EdgeReader()
// httpapi.Listen(httpapi.Config{Reader: rd, Claimer: cl, EdgeReader: ed, ...})
// rc, err := src.ReadyCounter()
// httpapi.Listen(httpapi.Config{Reader: rd, Claimer: cl, ReadyCounter: rc, ...})
// qr, err := src.Querier()
// httpapi.Listen(httpapi.Config{Reader: rd, Claimer: cl, Querier: qr, ...})
// ... one per field below, all off the same src ...
// httpapi.Listen(httpapi.Config{Reader: rd, Claimer: cl, /* and the rest */})
//
// cmd/bd's serveIssueRoles is that loop, written out.
//
// Listen refuses a hook-firing role rather than trusting the paragraph
// above — see checkDatabaseSource.
@ -194,12 +175,10 @@ type Config struct {
// (see Server.reader) — and a role reached this way opens none through this
// server, so a rebuild would buy nothing.
//
// Every one of these is required for the reason the half-set pair is
// refused: a server that binds while unable to answer an operation its own
// capability list advertises is the failure this check exists to prevent,
// and a nil role would produce it on the first request to that route
// instead of at startup. Take them all off the same store, beneath the hook
// layer. sourceRoles is the authoritative list.
// Every one of these is required for one reason: a server that binds while
// unable to answer an operation its own capability list advertises is the
// failure this check exists to prevent, and a nil role would produce it on
// the first request to that route instead of at startup.
Reader issueops.Reader
Claimer issueops.Claimer
Settings issueops.WorkspaceConfig
@ -245,18 +224,10 @@ type Server struct {
cfg Config
provider uow.UnitOfWorkProvider
// These are the configured roles, set exactly when provider is nil. They
// are what reader(), claimer(), workspaceConfig() and statsReporter() hand
// back on the store-shaped source; some names differ from those methods
// because a struct cannot carry both.
// issueReader, issueClaimer and issueCycles are the configured roles, set
// exactly when provider is nil. They are what reader(), claimer() and
// cycleDetector() hand back on the store-shaped source; the names differ
// from those methods because a struct cannot carry both.
// issueReader, issueClaimer and issueEdges are the configured roles, set
// exactly when provider is nil. They are what reader(), claimer() and
// edgeReader() hand back on the store-shaped source; the names differ from
// those methods because a struct cannot carry both.
// The configured roles, set exactly when provider is nil. They are what
// reader(), claimer(), cycleDetector() and the rest of those accessors hand
// back on the store-shaped source; the field names differ from the method
// names because a struct cannot carry both.
issueReader issueops.Reader
issueClaimer issueops.Claimer
settings issueops.WorkspaceConfig
@ -435,21 +406,10 @@ func Listen(cfg Config) (*Server, error) {
// provider, or the roles this surface answers from (sourceRoles). A PARTIAL
// set is refused with the same message as none at all, because it is the same
// mistake and the failure it would otherwise produce is the worst shape
// available — a reader without a claimer binds, answers every read, and fails
// the one issue write on this surface with a nil dereference in a handler on a
// live server. A missing settings or summary role is the same failure on a
// different route, which is why the set is all-or-nothing rather than a
// required pair plus optional extras.
// provider, or the issue roles. A PARTIALLY-SET role set is refused with the
// same message as none at all, because it is the same mistake and the failure
// it would otherwise produce is the worst shape available — a config missing
// one role binds, answers every other route, and fails that one with a nil
// dereference in a handler on a live server.
// provider, or the issue roles. A PARTIAL set of roles is refused with the same
// message as none at all, because it is the same mistake and the failure it
// would otherwise produce is the worst shape available — a reader without a
// claimer binds, answers every read, and fails the one write on this surface
// with a nil dereference in a handler on a live server.
// available — a Config missing one role binds, answers every other route, and
// fails that one with a nil dereference in a handler on a live server. That is
// why the set is all-or-nothing rather than a required pair plus optional
// extras.
//
// The set GROWS as this surface grows, and that is deliberate rather than
// unfortunate: every operation added here is an operation a roles-backed