A module may declare its own seats (novox/hq ADR 0118)
The manifest carries seats and uses; registration refuses a mesh-* name, a duplicate declarer, an undeclared uses or claim, a seat with no protocol, a scope mismatch, and a holder that does not answer what its seat promises. The parser stops judging unknown claim names, because it cannot: another module may declare that seat, and one manifest cannot tell. The test that encoded the old rule is rewritten to assert the refusal at registration, and a new one pins the case the parser could not have distinguished. Tools are declared for the first time, under their own key — serves already means a provision's facts.
This commit is contained in:
@@ -0,0 +1,240 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Seats a module declares of its own (novox/hq ADR 0118).
|
||||
//
|
||||
// The set of seats a mesh has is **derived**: the mesh's own, in seats.go, plus those declared by
|
||||
// every module it has registered. Still closed — a seat named nowhere is refused — but computed
|
||||
// from the catalogue rather than written in the controller, which is what ADR 0110 actually
|
||||
// needed and a hand-maintained table could not keep. Its own evidence: the enumeration done by
|
||||
// hand while that record was written reported eleven claims where there were thirteen.
|
||||
//
|
||||
// **What can be checked from one manifest and what cannot.** A declaration's shape, its scope,
|
||||
// and the reserved prefix are facts about the manifest in front of you. Whether a seat anybody
|
||||
// names actually exists, whether two modules declared the same one, and whether a holder
|
||||
// satisfies the protocol are facts about the *catalogue* — so they are checked at registration,
|
||||
// by CatalogueProblems, which is the last moment the mesh can still say no.
|
||||
|
||||
// meshSeatPrefix is reserved to the mesh. The prefix *is* the reservation rule: no list of
|
||||
// reserved names to maintain, no way for the mesh's own namespace to be colonised by a manifest,
|
||||
// and nothing to keep in step when a mesh seat is added.
|
||||
const meshSeatPrefix = "mesh-"
|
||||
|
||||
// A SeatDeclaration is a role a module offers on the bus: what may be sent to it, what it says,
|
||||
// and what it answers. A caller declares that it uses the *seat*, never the module, so the
|
||||
// implementation can be replaced under it.
|
||||
type SeatDeclaration struct {
|
||||
Name string `json:"name"`
|
||||
Scope string `json:"scope,omitempty"`
|
||||
|
||||
// Accepts are the verbs others may submit work on. Each becomes a work-queue subject, and
|
||||
// the holder is the only consumer — so exactly one worker does the job, by construction
|
||||
// rather than by how carefully somebody wrote a subscribe call.
|
||||
Accepts []string `json:"accepts,omitempty"`
|
||||
// Emits are the verbs the holder publishes: 1:many, nobody obliged to act.
|
||||
Emits []string `json:"emits,omitempty"`
|
||||
// Serves are the verbs the holder answers: request and reply, awaited.
|
||||
Serves []string `json:"serves,omitempty"`
|
||||
|
||||
// RetainSeconds is how long the inbound backlog survives with no holder, zero for the
|
||||
// mesh's default. Retention belongs to whoever owns the namespace (design 29 §3) — a seat
|
||||
// owns its own, which is why a seat is also the answer for a module that needs retention
|
||||
// its events cannot have.
|
||||
RetainSeconds int `json:"retain-seconds,omitempty"`
|
||||
}
|
||||
|
||||
// At is this declaration's scope, with the default applied. Mesh by default, because a seat
|
||||
// declared by a module is nearly always "there is one of these in the mesh" — a per-node worker
|
||||
// is the deliberate case, and says so.
|
||||
func (s SeatDeclaration) At() string {
|
||||
if s.Scope == "" {
|
||||
return ScopeMesh
|
||||
}
|
||||
return s.Scope
|
||||
}
|
||||
|
||||
// verbs is everything the protocol names, for the checks that do not care which half.
|
||||
func (s SeatDeclaration) verbs() []string {
|
||||
out := append([]string{}, s.Accepts...)
|
||||
out = append(out, s.Emits...)
|
||||
return append(out, s.Serves...)
|
||||
}
|
||||
|
||||
// declaredSeatProblems is what one manifest can be judged on alone.
|
||||
func declaredSeatProblems(m Manifest) []string {
|
||||
var problems []string
|
||||
seen := map[string]bool{}
|
||||
|
||||
for _, s := range m.Seats {
|
||||
switch {
|
||||
case s.Name == "":
|
||||
problems = append(problems, fmt.Sprintf("%s declares a seat with no name", m.Module))
|
||||
continue
|
||||
case !name.MatchString(s.Name):
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares a seat named %q, which is not a usable name", m.Module, s.Name))
|
||||
continue
|
||||
case strings.HasPrefix(s.Name, meshSeatPrefix):
|
||||
// The mesh's own code dereferences its seats by name — the resolver *is* the thing
|
||||
// that finds the store — so the prefix is not a convention, it is a namespace.
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares a seat named %q; %q is reserved to the mesh, which defines its own "+
|
||||
"seats (novox/hq ADR 0118)", m.Module, s.Name, meshSeatPrefix+"*"))
|
||||
continue
|
||||
}
|
||||
if seen[s.Name] {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares the seat %q twice", m.Module, s.Name))
|
||||
continue
|
||||
}
|
||||
seen[s.Name] = true
|
||||
|
||||
if _, isMesh := SeatNamed(s.Name); isMesh {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares %q, which is a seat the mesh already defines", m.Module, s.Name))
|
||||
}
|
||||
switch s.At() {
|
||||
case ScopeNode, ScopeSite, ScopeMesh:
|
||||
default:
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares seat %s at scope %q; a seat is held per node, per site or per mesh",
|
||||
m.Module, s.Name, s.Scope))
|
||||
}
|
||||
if len(s.verbs()) == 0 {
|
||||
// A seat with no protocol is exclusion with nothing on the other side of it. If a
|
||||
// module only wants "there is one of me", that is a claim, and saying so keeps the
|
||||
// word "seat" meaning something callers can depend on.
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares seat %s with no protocol; a seat says what may be sent to it, what "+
|
||||
"it emits and what it serves", m.Module, s.Name))
|
||||
}
|
||||
for _, v := range s.verbs() {
|
||||
if !name.MatchString(v) {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares %s.%s, which is not a usable verb", m.Module, s.Name, v))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for _, u := range m.Uses {
|
||||
if !name.MatchString(u) {
|
||||
problems = append(problems, fmt.Sprintf("%s uses %q, which is not a usable seat name", m.Module, u))
|
||||
}
|
||||
}
|
||||
return problems
|
||||
}
|
||||
|
||||
// A Shelf is every manifest the mesh has registered, by module name.
|
||||
type Shelf map[string]Manifest
|
||||
|
||||
// CatalogueProblems are the rules no single manifest can be judged against.
|
||||
//
|
||||
// Run at registration, which is the last moment the mesh can still refuse: after it, a caller is
|
||||
// bound to a seat and a refusal is an outage rather than a conversation.
|
||||
func CatalogueProblems(shelf Shelf) []string {
|
||||
var problems []string
|
||||
|
||||
// Who declares what, and who declared it first.
|
||||
declaredBy := map[string]string{}
|
||||
declared := map[string]SeatDeclaration{}
|
||||
for _, module := range shelfOrder(shelf) {
|
||||
for _, s := range shelf[module].Seats {
|
||||
if s.Name == "" {
|
||||
continue
|
||||
}
|
||||
if first, taken := declaredBy[s.Name]; taken {
|
||||
// The second loses. A seat name meaning two different protocols is the failure
|
||||
// nobody could diagnose afterwards — a caller would bind to whichever happened
|
||||
// to register first, and the symptom would appear in the other module.
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s declares the seat %q, which %s already declares; a seat name means one "+
|
||||
"protocol", module, s.Name, first))
|
||||
continue
|
||||
}
|
||||
declaredBy[s.Name] = module
|
||||
declared[s.Name] = s
|
||||
}
|
||||
}
|
||||
|
||||
exists := func(seat string) bool {
|
||||
if _, isMesh := SeatNamed(seat); isMesh {
|
||||
return true
|
||||
}
|
||||
_, ok := declaredBy[seat]
|
||||
return ok
|
||||
}
|
||||
|
||||
for _, module := range shelfOrder(shelf) {
|
||||
m := shelf[module]
|
||||
|
||||
// A `uses` naming nothing is where ADR 0110's guarantee lands under a derived set: the
|
||||
// same refusal, at the same moment, from a set nobody maintains by hand.
|
||||
for _, u := range m.Uses {
|
||||
if !exists(u) {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s uses the seat %q, which no module declares and the mesh does not define",
|
||||
module, u))
|
||||
}
|
||||
}
|
||||
|
||||
for _, c := range m.Claims {
|
||||
if !exists(c.Name) {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s claims the seat %q, which no module declares and the mesh does not define",
|
||||
module, c.Name))
|
||||
continue
|
||||
}
|
||||
s, isModuleSeat := declared[c.Name]
|
||||
if !isModuleSeat {
|
||||
continue // a mesh seat: already judged by claimProblems
|
||||
}
|
||||
if c.At() != s.At() {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s claims %s at scope %q, and %s declares it at %s",
|
||||
module, c.Name, c.At(), declaredBy[c.Name], s.At()))
|
||||
}
|
||||
// A holder that does not answer what the seat promises is a caller's timeout, found
|
||||
// at assignment instead.
|
||||
if missing := unserved(m, s); len(missing) > 0 {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s claims %s but does not serve %s, which that seat's protocol promises",
|
||||
module, c.Name, strings.Join(missing, ", ")))
|
||||
}
|
||||
}
|
||||
}
|
||||
sort.Strings(problems)
|
||||
return problems
|
||||
}
|
||||
|
||||
// unserved is what a seat's protocol promises and the claimant does not answer. Only the tools
|
||||
// are checked: `accepts` and `emits` are wired by the runtime from the declaration, while a tool
|
||||
// is code the module either has or has not written.
|
||||
func unserved(m Manifest, s SeatDeclaration) []string {
|
||||
has := map[string]bool{}
|
||||
for _, t := range m.Tools {
|
||||
has[t] = true
|
||||
}
|
||||
var missing []string
|
||||
for _, t := range s.Serves {
|
||||
if !has[t] {
|
||||
missing = append(missing, t)
|
||||
}
|
||||
}
|
||||
return missing
|
||||
}
|
||||
|
||||
// shelfOrder is the catalogue in a stable order, so two runs report the same problems in the same
|
||||
// sequence — a refusal that reorders itself is a refusal nobody can diff.
|
||||
func shelfOrder(shelf Shelf) []string {
|
||||
out := make([]string, 0, len(shelf))
|
||||
for k := range shelf {
|
||||
out = append(out, k)
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
Reference in New Issue
Block a user