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:
parent
59a1df98b5
commit
8baf16989d
3 changed files with 32 additions and 99 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue