Files
mesh-delivery/modules/mesh-delivery-indexer/judge/busstate.go
T
jschoubben 8f7fd39e21 A-277: the manifest validator reads a state's max-mib and judges an approvals state as §677 declares it
The template state takes max-mib (1 to 8192, as the old state section reads it). A state named approvals is refused
without key-ttl true, with ttl-seconds other than 172800 (approval.KeptFor, 48 hours), or with max-mib above 64; with
none declared its bucket takes the default 64 MiB.

Builds: design 47 G A-277, A-270, §677

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:42:16 +01:00

520 lines
22 KiB
Go

package judge
import (
"bytes"
"encoding/json"
"fmt"
"maps"
"slices"
"strings"
"git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
// The rules for bus state asked for in `requires` (issue 1966 D1; novox/hq ADR 0595 §1 to §3, ADR 0596 §2, ADR 0597 §2,
// design 25 § 12.1). mesh-sdk keeps only the entry's shape (ADR 0578 §7); every bound below is this judge's. An entry is
// judged once, here, and a refusal names the module, the entry and the field.
// optionKind is what an option's value is.
type optionKind int
const (
optionInt optionKind = iota
optionFlag
optionText
optionEvents
)
// optionRule is one option a template takes: its kind, its bound where it is a number, and whether it must be given.
type optionRule struct {
kind optionKind
least, most int
required bool
}
// busTemplate is a template: the storage type it is on, the options it takes, and what it fixes in plain words.
type busTemplate struct {
storage string
options map[string]optionRule
fixed string
}
// busTemplates are the six templates of design 25 § 12.1 and the bounds of its table.
var busTemplates = map[string]busTemplate{
catalogue.TemplateState: {
storage: catalogue.StorageKeyValue,
fixed: "what happens when full, the size of a value and of the bucket, and the copies",
options: map[string]optionRule{
catalogue.OptionPastValues: {kind: optionInt, least: 1, most: catalogue.StateMostHistory},
catalogue.OptionTimeToLive: {kind: optionInt, least: 1, most: 315360000},
catalogue.OptionLifetimePerKey: {kind: optionFlag},
catalogue.OptionPerMachine: {kind: optionFlag},
// A-277: a state's cap is an option of its template, read as the old state section reads it.
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.ObjectsLeastMiB, most: catalogue.ObjectsMostMiB},
},
},
catalogue.TemplateEvents: {
storage: catalogue.StorageStream,
fixed: "what happens when full (the oldest is dropped) and the module's own subjects",
options: map[string]optionRule{
"events": {kind: optionEvents, required: true},
catalogue.OptionAgeDays: {kind: optionInt, least: catalogue.StreamLeastDays, most: catalogue.StreamMostDays},
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.StreamLeastMiB, most: catalogue.StreamMostMiB},
catalogue.OptionGrant: {kind: optionText},
},
},
catalogue.TemplateWorkQueue: {
storage: catalogue.StorageStream,
fixed: "what happens when full (a new message is refused), one taker, and no grant",
options: map[string]optionRule{
"events": {kind: optionEvents, required: true},
catalogue.OptionDeliveries: {kind: optionInt, least: catalogue.StreamLeastDeliveries, most: catalogue.StreamMostDeliveries},
catalogue.OptionDuplicates: {kind: optionInt, least: 1, most: catalogue.StreamMostDays * 86400},
catalogue.OptionAgeDays: {kind: optionInt, least: catalogue.StreamLeastDays, most: catalogue.StreamMostDays},
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.StreamLeastMiB, most: catalogue.StreamMostMiB},
},
},
catalogue.TemplateLog: {
storage: catalogue.StorageStream,
fixed: "what happens when full (a new entry is refused), that an entry is never rewritten, and its size",
options: map[string]optionRule{
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.StreamLeastMiB, most: catalogue.StreamMostMiB},
catalogue.OptionAgeDays: {kind: optionInt, least: 1, most: 3650},
},
},
catalogue.TemplateObjects: {
storage: catalogue.StorageObjectStore,
fixed: "what happens when full (a new object is refused) and that objects are kept for good",
options: map[string]optionRule{
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.ObjectsLeastMiB, most: catalogue.ObjectsMostMiB, required: true},
catalogue.OptionGrant: {kind: optionText},
},
},
catalogue.TemplateLedger: {
storage: catalogue.StorageLedger,
fixed: "what happens when full (a new entry is refused) and its state and index buckets",
options: map[string]optionRule{
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.StreamLeastMiB, most: catalogue.StreamMostMiB},
},
},
}
// bareStream is a stream of a module's own configuration, where no template fits: the three settings the judge
// refuses one for missing (design 25 § 12.1), and those it may also give.
var bareStream = map[string]optionRule{
catalogue.OptionCapMiB: {kind: optionInt, least: catalogue.StreamLeastMiB, most: catalogue.StreamMostMiB, required: true},
catalogue.OptionAgeDays: {kind: optionInt, least: 1, most: 3650, required: true},
catalogue.OptionGrant: {kind: optionText},
"events": {kind: optionEvents},
}
// ledgerConfiguration is what a ledger's own configuration may give: how long its history is kept (design 25 § 12.1).
var ledgerConfiguration = map[string]optionRule{
catalogue.OptionAgeDays: {kind: optionInt, least: 1, most: 3650},
}
// noAge is how a bare stream says it keeps its messages for good.
const noAge = "none"
// ledgerEffects are the four effects an operation may have (ADR 0597 §2).
var ledgerEffects = []string{catalogue.EffectSetFields, catalogue.EffectSetEntry, catalogue.EffectAppend, catalogue.EffectRemove}
// BusStateProblems is what is wrong with one manifest's bus state, judged on the manifest alone (issue 1966 D1).
func BusStateProblems(m catalogue.Manifest) []string {
if len(m.BusState) == 0 {
return nil
}
var problems []string
if !stateName.MatchString(m.Module) {
problems = append(problems, fmt.Sprintf(
"%s keeps bus state, and a module's name is part of its names on the bus, which take one plain name — "+
"no dot (novox/hq ADR 0201, ADR 0595 §1)", m.Module))
}
storageOf := map[string]string{}
oldSection := map[string]string{} // a local name an old section keeps, to that section (issue 1966 D2)
for _, st := range m.State {
oldSection[st.Name] = "state"
}
for _, l := range m.Logs {
oldSection[l.Name] = "logs"
}
for _, st := range m.Streams {
oldSection[st.Name] = "streams"
}
for _, o := range m.Objects {
oldSection[o.Name] = "objects"
}
terminal := catalogue.TerminalKeys(m)
for _, e := range m.BusState {
at := fmt.Sprintf("%s's bus state %q", m.Module, e.Name)
switch {
case strings.Contains(e.Name, "_"):
problems = append(problems, fmt.Sprintf(
"%s: its name holds an underscore, which separates the module from the local name on the bus; use a "+
"hyphen (novox/hq design 25 § 12.1)", at))
case !stateName.MatchString(e.Name):
problems = append(problems, fmt.Sprintf(
"%s: its name is a local name — lower-case letters, digits and hyphens, no dot and no underscore; the "+
"mesh derives the name on the bus (novox/hq ADR 0201)", at))
}
if first, taken := storageOf[e.Name]; taken {
problems = append(problems, fmt.Sprintf(
"%s: the name is used twice (as %s and as %s); each name is one, whatever its storage type (novox/hq "+
"ADR 0595 §1)", at, first, e.Storage))
}
storageOf[e.Name] = e.Storage
if section, kept := oldSection[e.Name]; kept {
problems = append(problems, fmt.Sprintf(
"%s: the name is also kept in the old section %s; one local name is one form, so a module that moves an "+
"entry removes it from the old section (novox/hq ADR 0595 §11)", at, section))
}
problems = append(problems, busEntryProblems(at, e, terminal)...)
}
return problems
}
// KeptFormProblems is what is wrong with the catch-up tool each kept data declares, in an old section or in `requires` by
// template (novox/hq design 47, *Its form is declared*): the tool a restore of it is followed by is one of the module's
// own tools, since the node agent calls it from the restore point and the delivery system names no module's tool. A form
// below 0 is refused by the reader.
func KeptFormProblems(m catalogue.Manifest) []string {
var problems []string
for _, k := range catalogue.KeptDeclarations(m) {
if k.CatchUp != nil && !slices.Contains(m.Tools, k.CatchUp.Tool) {
problems = append(problems, fmt.Sprintf("%s's kept %s %q: its catch-up tool %q is not among the module's tools (%s); a "+
"restore of it is followed by a tool of the module's own (novox/hq design 47)", m.Module, k.Kind, k.Name, k.CatchUp.Tool,
orNoneWords(m.Tools)))
}
}
return problems
}
// busEntryProblems judges one entry's storage type, template, options and configuration.
func busEntryProblems(at string, e catalogue.BusStateEntry, terminal []string) []string {
var problems []string
switch e.Storage {
case catalogue.StorageStream, catalogue.StorageKeyValue, catalogue.StorageObjectStore, catalogue.StorageLedger:
default:
return []string{fmt.Sprintf("%s: the storage type %q is unknown; it is %s", at, e.Storage,
strings.Join([]string{catalogue.StorageStream, catalogue.StorageKeyValue, catalogue.StorageObjectStore, catalogue.StorageLedger}, ", "))}
}
if e.Storage != catalogue.StorageLedger && len(e.Types) > 0 {
problems = append(problems, fmt.Sprintf("%s: types are a ledger's; storage type %s has none", at, e.Storage))
}
if e.Template == "" {
if e.Storage != catalogue.StorageStream {
return append(problems, fmt.Sprintf(
"%s: the storage type %s is asked for by its template; only a stream is asked for bare, with a "+
"configuration of its own (novox/hq design 25 § 12.1)", at, e.Storage))
}
if len(e.Options) > 0 {
problems = append(problems, fmt.Sprintf(
"%s: a bare stream gives its settings in its configuration, not in options", at))
}
return append(problems, settingsProblems(at, "configuration", e.Configuration, bareStream, "a bare stream", terminal, true)...)
}
tpl, known := busTemplates[e.Template]
switch {
case !known:
names := make([]string, 0, len(busTemplates))
for n := range busTemplates {
names = append(names, n)
}
slices.Sort(names)
return append(problems, fmt.Sprintf("%s: the template %q is unknown; it is %s", at, e.Template, strings.Join(names, ", ")))
case tpl.storage != e.Storage:
return append(problems, fmt.Sprintf(
"%s: the template %s is on the storage type %s, not %s", at, e.Template, tpl.storage, e.Storage))
}
problems = append(problems, settingsProblems(at, "options", e.Options, tpl.options, "the template "+e.Template+" (it fixes "+tpl.fixed+")", terminal, false)...)
if e.Template == catalogue.TemplateLedger {
problems = append(problems, settingsProblems(at, "configuration", e.Configuration, ledgerConfiguration, "a ledger's own configuration", terminal, false)...)
problems = append(problems, ledgerTypeProblems(at, e)...)
} else if len(e.Configuration) > 0 {
problems = append(problems, fmt.Sprintf(
"%s: the template %s is given a configuration; a configuration of its own is for a bare stream or a "+
"ledger whose history expires, and a template's settings are its options (novox/hq ADR 0595 §2)", at, e.Template))
}
if e.Template == catalogue.TemplateWorkQueue {
problems = append(problems, workQueueProblems(at, e)...)
}
if e.Template == catalogue.TemplateState && e.Name == approval.StateName {
problems = append(problems, approvalsStateProblems(at, e)...)
}
return problems
}
// approvalsMostMiB is the most an approvals state holds (design 47 G §677's 64 MiB); with none declared its bucket takes
// the default 64 MiB.
const approvalsMostMiB = 64
// approvalsStateProblems judges a holder's approvals state as §677 declares it (lead answers A-270, A-277): with key-ttl,
// since its bound keys `unanswered.<call>` need it, a lifetime of 48 hours and at most 64 MiB.
func approvalsStateProblems(at string, e catalogue.BusStateEntry) []string {
var problems []string
var keyTTL bool
if json.Unmarshal(e.Options[catalogue.OptionLifetimePerKey], &keyTTL) != nil || !keyTTL {
problems = append(problems, fmt.Sprintf("%s: an approvals state is declared with %s true, since its bound keys "+
"unanswered.<call> need it (novox/hq design 47 G §677, A-270)", at, catalogue.OptionLifetimePerKey))
}
want := int(approval.KeptFor.Seconds())
if ttl, ok := intOption(e.Options, catalogue.OptionTimeToLive); !ok || ttl != want {
problems = append(problems, fmt.Sprintf("%s: an approvals state keeps a value %d seconds (48 hours), so its %s is "+
"%d, not %s (novox/hq design 47 G §677, A-277)", at, want, catalogue.OptionTimeToLive, want, givenOr(e.Options, catalogue.OptionTimeToLive)))
}
if mib, ok := intOption(e.Options, catalogue.OptionCapMiB); ok && mib > approvalsMostMiB {
problems = append(problems, fmt.Sprintf("%s: an approvals state holds at most %d MiB, so its %s is at most %d, not %d "+
"(novox/hq design 47 G §677, A-277)", at, approvalsMostMiB, catalogue.OptionCapMiB, approvalsMostMiB, mib))
}
return problems
}
// intOption is an option's whole number, false where it is not given or no number.
func intOption(options map[string]json.RawMessage, name string) (int, bool) {
raw, given := options[name]
if !given {
return 0, false
}
var n int
if json.Unmarshal(raw, &n) != nil {
return 0, false
}
return n, true
}
// givenOr is an option's value as given, or "missing".
func givenOr(options map[string]json.RawMessage, name string) string {
if raw, given := options[name]; given {
return string(raw)
}
return "missing"
}
// settingsProblems judges the given settings against the rules: an unknown one is refused (a fixed setting among them),
// a number outside its bound, a kind mismatch, and a required one missing. A bare stream's when-full and age are read
// here too.
func settingsProblems(at, field string, given map[string]json.RawMessage, rules map[string]optionRule, of string, terminal []string, bare bool) []string {
var problems []string
for _, k := range sortedKeys(given) {
raw := given[k]
if bare && k == catalogue.ConfigWhenFull {
var v string
if json.Unmarshal(raw, &v) != nil || (v != catalogue.WhenFullRefuse && v != catalogue.WhenFullDropOldest) {
problems = append(problems, fmt.Sprintf(
"%s: %s %q is %s; a bare stream says %q or %q", at, field, k, string(raw), catalogue.WhenFullRefuse, catalogue.WhenFullDropOldest))
}
continue
}
rule, ok := rules[k]
if !ok {
if k == catalogue.ConfigWhenFull {
problems = append(problems, fmt.Sprintf(
"%s: %s %q is given to %s; what happens when full is fixed and is never an option (novox/hq ADR 0595 §3)", at, field, k, of))
continue
}
problems = append(problems, fmt.Sprintf(
"%s: %s %q is not a setting of %s (novox/hq ADR 0595 §3)", at, field, k, of))
continue
}
problems = append(problems, valueProblems(at, field, k, raw, rule, terminal, bare)...)
}
for _, k := range sortedKeys(rules) {
if _, given := given[k]; !given && rules[k].required {
problems = append(problems, fmt.Sprintf("%s: %s %q is missing; %s gives it", at, field, k, of))
}
}
if bare {
if _, given := given[catalogue.ConfigWhenFull]; !given {
problems = append(problems, fmt.Sprintf(
"%s: %s %q is missing; a bare stream says %q or %q", at, field, catalogue.ConfigWhenFull, catalogue.WhenFullRefuse, catalogue.WhenFullDropOldest))
}
}
return problems
}
// valueProblems judges one setting's value against its rule.
func valueProblems(at, field, key string, raw json.RawMessage, rule optionRule, terminal []string, bare bool) []string {
switch rule.kind {
case optionInt:
if bare && key == catalogue.OptionAgeDays {
var word string
if json.Unmarshal(raw, &word) == nil && word == noAge {
return nil
}
}
n, ok := wholeNumber(raw)
if !ok {
return []string{fmt.Sprintf("%s: %s %q is %s, which is not a whole number", at, field, key, string(raw))}
}
if n < rule.least || n > rule.most {
extra := ""
if key == catalogue.OptionPastValues && n == 0 {
extra = "; 0 is refused here"
}
return []string{fmt.Sprintf("%s: %s %q is %d, outside its bound of %d to %d%s", at, field, key, n, rule.least, rule.most, extra)}
}
case optionFlag:
var b bool
if json.Unmarshal(raw, &b) != nil {
return []string{fmt.Sprintf("%s: %s %q is %s, which is not true or false", at, field, key, string(raw))}
}
case optionText:
var config string
if json.Unmarshal(raw, &config) != nil || !slices.Contains(terminal, config) {
return []string{fmt.Sprintf(
"%s: %s %q names %s, which is not a trusted config value of the module, set only at the controller's "+
"terminal or on the operator's Approve (novox/hq ADR 0348 §8)", at, field, key, string(raw))}
}
case optionEvents:
var events []string
if json.Unmarshal(raw, &events) != nil || len(events) == 0 {
return []string{fmt.Sprintf("%s: %s %q is %s; it is a list of at least one event", at, field, key, string(raw))}
}
var out []string
for _, ev := range events {
if err := eventPattern(ev, false); err != nil {
out = append(out, fmt.Sprintf("%s: %s %q carries %q: %v", at, field, key, ev, err))
}
}
return out
}
return nil
}
// wholeNumber reads a JSON number that is a whole number.
func wholeNumber(raw json.RawMessage) (int, bool) {
dec := json.NewDecoder(bytes.NewReader(raw))
dec.UseNumber()
var n json.Number
if dec.Decode(&n) != nil {
return 0, false
}
i, err := n.Int64()
return int(i), err == nil
}
// workQueueProblems holds a work queue's duplicate window to its age (design 25 § 12.1: up to its age).
func workQueueProblems(at string, e catalogue.BusStateEntry) []string {
raw, given := e.Options[catalogue.OptionDuplicates]
if !given {
return nil
}
window, ok := wholeNumber(raw)
if !ok {
return nil // valueProblems said so
}
days := catalogue.StreamDefaultDays
if age, ok := wholeNumber(e.Options[catalogue.OptionAgeDays]); ok && age > 0 {
days = age
}
if window > days*86400 {
return []string{fmt.Sprintf(
"%s: options %q is %d seconds, longer than the queue's age of %d days (novox/hq design 25 § 12.1)",
at, catalogue.OptionDuplicates, window, days)}
}
return nil
}
// ledgerTypeProblems judges a ledger's types: named locally and once, and every operation's effect one of the four; a
// set-entry or remove names its `into` and `key`; an operation's `fields` and an index's `on` name fields of the type's
// schema; a `digest-of` names a text field of it (DLV-I12, ADR 0595 §8, ADR 0597 §2, §4).
func ledgerTypeProblems(at string, e catalogue.BusStateEntry) []string {
var problems []string
if len(e.Types) == 0 {
problems = append(problems, fmt.Sprintf("%s: a ledger names at least one type (novox/hq ADR 0597 §1)", at))
}
seen := map[string]bool{}
for _, t := range e.Types {
where := fmt.Sprintf("%s: type %q", at, t.Name)
switch {
case !stateName.MatchString(t.Name):
problems = append(problems, fmt.Sprintf("%s: its name is lower-case letters, digits and hyphens", where))
case seen[t.Name]:
problems = append(problems, fmt.Sprintf("%s: the type is named twice", where))
}
seen[t.Name] = true
operations := map[string]bool{}
for _, op := range t.Operations {
if operations[op.Name] {
problems = append(problems, fmt.Sprintf("%s: the operation %q is named twice", where, op.Name))
}
operations[op.Name] = true
if !slices.Contains(ledgerEffects, op.Effect) {
problems = append(problems, fmt.Sprintf(
"%s: the operation %q has the effect %q, outside the four (%s) (novox/hq ADR 0597 §2)",
where, op.Name, op.Effect, strings.Join(ledgerEffects, ", ")))
}
if op.Effect == catalogue.EffectSetEntry || op.Effect == catalogue.EffectRemove {
for field, v := range map[string]string{"into": op.Into, "key": op.Key} {
if strings.TrimSpace(v) == "" {
problems = append(problems, fmt.Sprintf("%s: the operation %q (%s) names no %s (novox/hq ADR 0597 §2)", where, op.Name, op.Effect, field))
}
}
}
for _, f := range op.Fields {
if _, ok := t.Schema[f]; !ok {
problems = append(problems, fmt.Sprintf("%s: the operation %q names the field %q, which the type's schema does not hold", where, op.Name, f))
}
}
}
for _, ix := range t.Indexes {
for _, f := range ix.On {
if _, ok := t.Schema[f]; !ok {
problems = append(problems, fmt.Sprintf("%s: the index %q is on the field %q, which the type's schema does not hold (novox/hq ADR 0597 §4)", where, ix.Name, f))
}
}
}
for _, name := range slices.Sorted(maps.Keys(t.Schema)) {
of := t.Schema[name].DigestOf
if of == "" {
continue
}
if src, ok := t.Schema[of]; !ok || src.Type != "text" {
problems = append(problems, fmt.Sprintf("%s: the field %q is the digest of %q, which is no text field of the type's schema", where, name, of))
}
}
}
return problems
}
// BusStateCatalogueProblems are the rules of bus state no single manifest can be judged against: two modules' names on
// the bus alike, and a `reads` naming bus state in the new form, which has no readers (novox/hq ADR 0596 §2).
func BusStateCatalogueProblems(shelf catalogue.Shelf) []string {
var problems []string
owner := map[string]string{} // a name on the bus, upper-cased, to the module asking for it
for _, module := range shelfOrder(shelf) {
for _, o := range shelf[module].Objects {
owner[strings.ToUpper(o.Bucket(module))] = module
}
}
for _, module := range shelfOrder(shelf) {
for _, e := range shelf[module].BusState {
name := catalogue.ObjectsBucket(module, e.Name)
if first, taken := owner[strings.ToUpper(name)]; taken && first != module {
problems = append(problems, fmt.Sprintf(
"%s's bus state %q has the name %s on the bus, which %s's already has or is alike; a name on the bus "+
"has one owner (novox/hq ADR 0201 §4)", module, e.Name, name, first))
continue
}
owner[strings.ToUpper(name)] = module
}
}
for _, module := range shelfOrder(shelf) {
for _, r := range shelf[module].Reads {
from, local, err := catalogue.ReadState(r)
if err != nil || from == module {
continue // StateProblems says why
}
for _, e := range shelf[from].BusState {
if e.Name == local {
problems = append(problems, fmt.Sprintf(
"%s reads %q, which %s has moved to bus state in `requires`; the new form has no readers: ask %s's "+
"tools, or hear its events (novox/hq ADR 0596 §2)", module, r, from, from))
}
}
}
}
return problems
}