jschoubben
7232d6df4b
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.
241 lines
8.9 KiB
Go
241 lines
8.9 KiB
Go
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
|
|
}
|