// Package seatdef reads a seat's definition (novox/hq ADR 0608 §1, design 26 *A seat's definition*): one // language-neutral file per seat, `seats//seat.json` in a contracts module, with the parts it includes from // `parts/.json` and its conformance fixtures in `seats//fixtures/`. The format's own JSON Schema is // checked in beside the definitions (mesh-contracts `format/seat-definition.schema.json`); this package is the one // reader every part shares: the indexer, which keeps the definitions on the bus, and the build modules' generators, // which write the Go and TypeScript types from them. It generates nothing and holds no seat's contract. // // **A definition is read strictly.** A key the format does not know is refused, naming it, since a misspelt key would // describe a contract nobody serves; a newer format is a new number, which an older reader refuses by name. The // messages a definition describes are read leniently by their readers (ADR 0608 §6): that is the generated code's // rule, not this one's. package seatdef import ( "bytes" "encoding/json" "errors" "fmt" "regexp" "slices" "sort" "strings" "time" ) // MaxSize is the largest definition, or part, the mesh keeps (design 26: at most 256 KiB a definition). const MaxSize = 256 << 10 // Format is the one format number this reader knows. const Format = 1 // The two grains a definition is written at (ADR 0613 §1, §2; ADR 0620 §1): whole, with every verb's messages, its // events and their bodies, its states and its provisions' forms; or the seat list's, holding what mesh-sdk's // compiled seat list held, until its area's contract next changes. const ( Whole = "whole" SeatList = "seat-list" ) // The two scopes a seat is held at. const ( ScopeMesh = "mesh" ScopeNode = "node" ) // Domains are the glossary's domains that own a seat, by their headings (hq 00-META/glossary.md, ADR 0244). var Domains = []string{"Module", "Config", "Core", "Provisioning", "Identity and access", "Delivery", "Health and repair", "Data", "Connectivity", "Operator and conversation"} // Definition is one seat's contract. type Definition struct { Format int `json:"format"` Seat string `json:"seat"` Scope string `json:"scope"` Grain string `json:"grain"` // Decision is the record that made it a seat. Decision string `json:"decision"` // Domain is the glossary domain the seat belongs to, by its heading (ADR 0636 §5): the indexer takes a seat of the // mesh's own contracts only from that domain's contracts module. Domain string `json:"domain"` // Description says the role in one paragraph, for a person reading the definition. Description string `json:"description,omitempty"` // HolderDeclares says the seat is not in the mesh's compiled seat list: its holder's manifest declares it as a // seat of its own (ADR 0118), and the definition is its contract all the same (design 26: operator-channel). HolderDeclares bool `json:"holder-declares,omitempty"` // Delivers is the provision the seat's holder answers for, or empty. Delivers string `json:"delivers,omitempty"` // Replicated, PulledByKind, Yields and HeldByTheEngine are the seat list's marks of the same names. Replicated bool `json:"replicated,omitempty"` PulledByKind bool `json:"pulled-by-kind,omitempty"` Yields bool `json:"yields,omitempty"` HeldByTheEngine bool `json:"held-by-the-engine,omitempty"` // Includes names the parts whose verbs, events and types this definition takes whole, written once so the seats // sharing them cannot drift (design 26: the four registry seats' common part). Includes []string `json:"includes,omitempty"` Verbs []Verb `json:"verbs,omitempty"` // Accepts are what may be sent to the seat's holder on `mesh.seat..accept.`. Accepts []Message `json:"accepts,omitempty"` // Events are what is published on the seat's own subject, `mesh.seat..event.`. Events []Message `json:"events,omitempty"` // Family is where the seat's events are kept, when the definition fixes it. Family *Family `json:"family,omitempty"` // HolderEvents are the holder's own events that belong with the seat, listed beside it and never moved onto // its subject (ADR 0620 §2): they keep the holder's subjects. HolderEvents []HolderEvent `json:"holder-events,omitempty"` // States are the layouts of the state the seat's holder keeps on the bus, and the callers' writes into it (ADR // 0608 §1, ADR 0634 §6). States []State `json:"states,omitempty"` // Provisions are the forms of the provisions the seat's holder answers. Provisions []Provision `json:"provisions,omitempty"` // Receives and Paths are the seat list's contributions and owned paths. Receives []Receivable `json:"receives,omitempty"` Paths []Path `json:"paths,omitempty"` // Defs are named types a schema refers to as `{"$ref": "#/defs/"}`. Defs map[string]map[string]any `json:"defs,omitempty"` // Bodies are the bodies other modules say on their own streams, named: each a JSON Schema, referred to as // `{"$ref": "#/bodies/"}`. The grants part makes no seat event or stream from them (design 47 G §439, §409). Bodies map[string]map[string]any `json:"bodies,omitempty"` // Acts are the seat's acting rules (novox/hq ADR 0656 §1; design 47 *What ADR 0656 leaves to this design*): each step // of a delivery the seat's holder acts in, on which modules, and how long an entry waits there for the holder's new // version. At either grain: a seat-list definition names its holder's step too. Acts []ActingRule `json:"acts,omitempty"` } // ActingRule is one acting rule of a seat: the step its holder acts in, the modules it acts on (every module, or those // whose manifest says this language), and how long an entry waits in that step for the holder's new version, a // duration such as "30m"; none is the step's default (DefaultBound). type ActingRule struct { Step string `json:"step"` On string `json:"on,omitempty"` Bound string `json:"bound,omitempty"` } // The steps of a delivery a seat's holder acts in (design 47): what the indexer, the checker, the build modules, the // node-engine, the grants part and the assigner each do for a change. const ( StepTakeIn = "take-in" StepValidate = "validate" StepCheck = "check" StepBuild = "build" StepCompose = "compose" StepGrant = "grant" StepPlace = "place" // StepPipeline is the runner's step, in the place of StepCheck from G's delivery (design 47 G §203). StepPipeline = "pipeline" ) // Steps are the steps an acting rule names, in a delivery's order. var Steps = []string{StepTakeIn, StepValidate, StepCheck, StepBuild, StepCompose, StepGrant, StepPlace, StepPipeline} // OnEvery is an acting rule's `on` for every module; an absent `on` reads as it. const OnEvery = "every" // OnKindImage is an acting rule's `on` for the modules whose artifact entry's kind is image (design 47 G §324, §397). const OnKindImage = "kind:image" // DefaultBound is how long an entry waits in step for its acting part's new version when the rule names no bound // (design 47 *An acting part's new version acts first*): 60 minutes to build, 30 to compose, 20 to check (the first // tier's), 10 to grant and to place; the indexer's take-in and validate have no wait, so zero. func DefaultBound(step string) time.Duration { switch step { case StepBuild: return 60 * time.Minute case StepCompose: return 30 * time.Minute case StepCheck: return 20 * time.Minute case StepGrant, StepPlace: return 10 * time.Minute case StepPipeline: return 30 * time.Minute } return 0 } // Acting is the modules the rule acts on: OnEvery, or a language. func (r ActingRule) Acting() string { if r.On == "" { return OnEvery } return r.On } // ActsOn says whether the rule acts on a module whose manifest says language. func (r ActingRule) ActsOn(language string) bool { on := r.Acting() return on == OnEvery || strings.EqualFold(on, strings.TrimSpace(language)) } // Wait is how long an entry waits in the rule's step for its acting part's new version: its bound, or the step's // default. A bound the reader refused never reaches here; one that does not parse reads as the default. func (r ActingRule) Wait() time.Duration { if d, err := time.ParseDuration(r.Bound); err == nil && d > 0 { return d } return DefaultBound(r.Step) } func checkActs(rs []ActingRule) Problems { var ps Problems seen := map[string]bool{} for i, r := range rs { where := fmt.Sprintf("acts[%d]", i) switch { case r.Step == "": ps = append(ps, Problem{where + ".step", "missing"}) case !slices.Contains(Steps, r.Step): ps = append(ps, Problem{where + ".step", fmt.Sprintf("%q is not a step (%s)", r.Step, strings.Join(Steps, ", "))}) } if r.On != "" && r.On != OnEvery && r.On != OnKindImage && !wordName.MatchString(r.On) { ps = append(ps, Problem{where + ".on", fmt.Sprintf("%q is neither every, kind:image nor a language's lower-case name", r.On)}) } if r.Bound != "" { if d, err := time.ParseDuration(r.Bound); err != nil || d <= 0 { ps = append(ps, Problem{where + ".bound", fmt.Sprintf("%q is not a duration such as 30m", r.Bound)}) } } if k := r.Step + " " + r.Acting(); r.Step != "" && seen[k] { ps = append(ps, Problem{where, fmt.Sprintf("the step %s on %s twice", r.Step, r.Acting())}) } else { seen[k] = true } } return ps } // Verb is one verb the seat serves: its input and, written whole, its answer, each a JSON Schema. type Verb struct { Name string `json:"name"` Description string `json:"description,omitempty"` // Optional marks a verb a holder may not serve yet and still hold the seat (design 33 §7). Optional bool `json:"optional,omitempty"` // Replaces are the shell commands this verb is the mesh's way to do (ADR 0245). Replaces []string `json:"replaces,omitempty"` Input map[string]any `json:"input,omitempty"` Answer map[string]any `json:"answer,omitempty"` // Callers says who may call it, as a list (design 47 G §336) or, in the definitions before G, in words. Callers *Callers `json:"callers,omitempty"` // Class is the verb's class, ClassRead, ClassAct or ClassWarrant (design 47 G §391). Class string `json:"class,omitempty"` // NeedsApproval marks the verb for every holder: the operator approves a call of it first (design 46 *The approval // mark* §2). NeedsApproval bool `json:"needs-approval,omitempty"` // ByCaller says the holder's process answers the verb itself and tells callers apart by the account the bus proved // (design 47 G §554, §621, §656). ByCaller bool `json:"by-caller,omitempty"` // Chunks says the holder's process sends the answer's file in chunks, each acknowledged by the caller, on the // subjects mesh.seat..chunk... and mesh.seat..ack... (design 47 G §681). Chunks bool `json:"chunks,omitempty"` } // The streams an accepted kind may ride (design 47 G §415). const ( StreamCheck = "check" StreamDelivery = "delivery" ) // Message is one accepted message or one event of the seat, its body a JSON Schema. type Message struct { // Name is the message's name; an event's may be lower-case words joined by dots (pull.updated), as a module's // event keys are. Name string `json:"name"` Body map[string]any `json:"body,omitempty"` // ByCaller says the subject ends in the name of who sent it (or, for an event, of who it is for). ByCaller bool `json:"by-caller,omitempty"` // Subject is an event's subject after `mesh.seat..event.` when it carries parts (design 47 *What each step // says*: `owed..`, `running..`, `milestone..asked`): its tokens are // the name's words in order with parts between angle brackets among them, so a reader that knows only the name // still knows the event. Empty, the subject is the name. A part `` is the node that publishes it, which // the grants part grants a node's account alone (ADR 0363 §2). Subject string `json:"subject,omitempty"` // Keep says how an event is kept when not as the family keeps the seat's others, in a stream of its own named // KeptStream (design 47 G §396): its age, its cap and whether it keeps the last message of each subject only (the // node-engine's running.., so the last build of every module on every node stays on the bus however // long ago it was said). An event with a Keep has no dot in its name. Keep *Keep `json:"keep,omitempty"` // Callers says who may send an accepted kind, as a verb's (design 47 G §338). Callers *Callers `json:"callers,omitempty"` // Stream is the stream an accepted kind rides, StreamCheck or StreamDelivery: its queue, and its subject is the queue's, // `accept.`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it // `.`, so the same kind name may ride more than one stream (design 47 G §415). Stream string `json:"stream,omitempty"` } // What an event's keep says where it says less (design 47 G §396, §331). const ( // KeepDefaultAgeDays and KeepDefaultMiB are an event's age and cap when its keep names none. KeepDefaultAgeDays = 90 KeepDefaultMiB = 16 ) // KeptStream is the stream an event with Keep is kept in: `SEAT__` (design 47 G §260, §396). func KeptStream(seat string, m Message) string { return KeptStreamPrefix + seat + "_" + m.Name } // KeptStreamPrefix begins the name of every kept event's stream. const KeptStreamPrefix = "SEAT_" // KeptAgeDays is how long a kept event's stream keeps a message: the keep's age, 90 days when it names none, and 0 // for no age limit. func (m Message) KeptAgeDays() int { if m.Keep == nil || m.Keep.MaxAgeDays == nil { return KeepDefaultAgeDays } return *m.Keep.MaxAgeDays } // KeptMiB is the most a kept event's stream holds: the keep's cap, 16 MiB when it names none. func (m Message) KeptMiB() int { if m.Keep == nil || m.Keep.MaxMiB == nil { return KeepDefaultMiB } return *m.Keep.MaxMiB } // KeptLastPerSubject says the stream keeps only the last message of each subject. func (m Message) KeptLastPerSubject() bool { return m.Keep != nil && m.Keep.LastPerSubject } // SubjectPattern is the event's subject after the seat's event prefix with its parts between angle brackets: the // name itself when the definition gives no subject. func (m Message) SubjectPattern() string { if m.Subject == "" { return m.Name } return m.Subject } // Parts are the names of the subject's parts, in order; none for a subject that is the name. func (m Message) Parts() []string { var out []string for _, tok := range strings.Split(m.SubjectPattern(), ".") { if keyPartOK.MatchString(tok) { out = append(out, tok[1:len(tok)-1]) } } return out } // Local is the subject after the seat's event prefix with `*` for each part: what a manifest's `emits` and // `consumes` name of the event, and the filter that hears every instance of it. func (m Message) Local() string { toks := strings.Split(m.SubjectPattern(), ".") for i, tok := range toks { if keyPartOK.MatchString(tok) { toks[i] = "*" } } return strings.Join(toks, ".") } // checkSubject says what is wrong with an event's subject, or "". func checkSubject(m Message) string { if m.Subject == "" { return "" } if m.ByCaller { return "an event named by its caller ends in the caller's name; it carries no subject of its own" } var words, parts []string for _, tok := range strings.Split(m.Subject, ".") { switch { case keyPartOK.MatchString(tok): if slices.Contains(parts, tok) { return fmt.Sprintf("part %s twice", tok) } parts = append(parts, tok) case wordName.MatchString(tok): words = append(words, tok) default: return fmt.Sprintf("%q is neither a lower-case word nor a part between < and >", tok) } } if len(parts) == 0 { return "no part: an event whose subject is its name gives no subject" } if strings.Join(words, ".") != m.Name { return fmt.Sprintf("its words are %q, not the event's name %q", strings.Join(words, "."), m.Name) } return "" } // HolderEvent is one of the holder's own events listed beside the seat. type HolderEvent struct { Name string `json:"name"` // Subject is where it is published, with `` for the holding module's name. Subject string `json:"subject"` // Family is the stream or family it is kept in, when it is not the shared module events stream. Family string `json:"family,omitempty"` Body map[string]any `json:"body,omitempty"` } // Family is where a seat's events are kept: the shared events stream filtered to the seat's subjects, so its age is // the stream's (SharedEventsMaxAgeDays) and it has no cap of its own (the lead's ruling of 2026-11-04 13:0x: a // holder that keeps a longer history keeps it in a stream of its own module). type Family struct { Name string `json:"name"` MaxAgeDays int `json:"max-age-days"` } // SharedEventsMaxAgeDays is how long the shared events stream keeps a seat's events (mesh-sdk buscompose's // EventsStream, whose test holds the two equal). const SharedEventsMaxAgeDays = 7 // The templates a state is kept in (ADR 0595 §2): the same six names mesh-sdk's catalogue gives a module's `requires` // entry; a unit test holds the two lists equal. This package imports no catalogue. const ( TemplateState = "state" TemplateEvents = "events" TemplateWorkQueue = "work-queue" TemplateLog = "log" TemplateObjects = "objects" TemplateLedger = "ledger" ) // Templates are the six, in the order ADR 0595 gives them. var Templates = []string{TemplateState, TemplateEvents, TemplateWorkQueue, TemplateLog, TemplateObjects, TemplateLedger} // The writers of a state: the seat's holder (the default), or its callers, each writing its own key. const ( WriterHolder = "holder" WriterCaller = "caller" ) // State is one state of the seat, by its local name: the holder's name is never in it, since a contract names no // holder (ADR 0625 §4, §7); each reader takes the holder from its own manifest's `reads` entry. A state is kept in // one of the templates, and its keys have one form each, with the schema of the value under it. type State struct { Name string `json:"name"` Template string `json:"template"` // Writer is WriterHolder when empty. Writer string `json:"writer,omitempty"` KeyForms []KeyForm `json:"key-forms"` // History is how many past values a TemplateState's key keeps; MaxAgeDays is how long a stream template // (events, work queue, log) keeps a message. Neither is given where the template has no such setting. History int `json:"history,omitempty"` MaxAgeDays int `json:"max-age-days,omitempty"` Description string `json:"description,omitempty"` // View is true when the seat offers the state as a view for a module to follow by `consumes` (design 47 G §699). View bool `json:"view,omitempty"` } // KeyForm is one form a state's key takes: a pattern of named parts (`.`, a part between angle brackets, // the rest literal) and the JSON Schema of the value kept under keys of that form. type KeyForm struct { Key string `json:"key"` Value map[string]any `json:"value"` Description string `json:"description,omitempty"` } // Provision is the form of a provision the seat's holder answers. type Provision struct { Name string `json:"name"` Form map[string]any `json:"form"` } // Receivable is one kind of contribution the seat receives (ADR 0212), as the seat list has it. type Receivable struct { Kind string `json:"kind"` Comment string `json:"comment,omitempty"` Dirs bool `json:"dirs,omitempty"` Offered bool `json:"offered,omitempty"` Shape *Shape `json:"shape,omitempty"` } // Shape is a contribution kind given as data (ADR 0255). Its checks are code, the runtime's, never the definition's. type Shape struct { Places []PlaceField `json:"places,omitempty"` Order string `json:"order,omitempty"` Examples []map[string]any `json:"examples,omitempty"` Text bool `json:"text,omitempty"` } // PlaceField is one field a holder places by, and the values it takes. type PlaceField struct { Field string `json:"field"` Values []string `json:"values,omitempty"` } // Path is one path on its machine the seat's holder owns (ADR 0287). type Path struct { Path string `json:"path"` StepsBackFor string `json:"steps-back-for,omitempty"` } // Part is verbs, events and types several definitions include whole. type Part struct { Format int `json:"format"` Part string `json:"part"` Description string `json:"description,omitempty"` Verbs []Verb `json:"verbs,omitempty"` Events []Message `json:"events,omitempty"` Defs map[string]map[string]any `json:"defs,omitempty"` } // Fixture is one conformance case of a definition (design 26: data, never functions): a message as given, the // subject it travels on, and, when it differs from what was given, what a reader must read back. type Fixture struct { Name string `json:"name"` // Of is what the fixture is an instance of: `verb:.input`, `verb:.answer`, `accept:`, // `event:` or `holder-event:`. Of string `json:"of"` Subject string `json:"subject,omitempty"` Given any `json:"given"` // Wire is what a reader reads back when it is not Given: a field it does not know dropped (ADR 0608 §6). Wire any `json:"wire,omitempty"` Why string `json:"why,omitempty"` } // Problem is one thing wrong with a definition, naming where. type Problem struct { Where string What string } func (p Problem) Error() string { return p.Where + ": " + p.What } // Problems is every problem a definition has, in the order found. type Problems []Problem func (ps Problems) Error() string { out := make([]string, len(ps)) for i, p := range ps { out[i] = p.Error() } return strings.Join(out, "; ") } var ( seatName = regexp.MustCompile(`^[a-z][a-z0-9-]*[a-z0-9]$`) wordName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`) // eventName is a holder's event: its own words, dot-separated as a module's event keys are (preview.written). eventName = regexp.MustCompile(`^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$`) ) // ErrTooLarge is a definition or part over MaxSize. var ErrTooLarge = errors.New("larger than 256 KiB, the most a seat's definition may be (design 26)") // Parse reads one seat's definition and checks it, naming every field that is missing or wrong. func Parse(raw []byte) (Definition, error) { var d Definition if err := strict(raw, &d); err != nil { return Definition{}, err } if ps := d.check(); len(ps) > 0 { return Definition{}, ps } return d, nil } // ParsePart reads one part. func ParsePart(raw []byte) (Part, error) { var p Part if err := strict(raw, &p); err != nil { return Part{}, err } var ps Problems if p.Format != Format { ps = append(ps, Problem{"format", formatProblem(p.Format)}) } if !wordName.MatchString(p.Part) { ps = append(ps, Problem{"part", "missing, or not a lower-case name"}) } ps = append(ps, checkVerbs(p.Verbs, true)...) ps = append(ps, checkMessages("events", p.Events, true)...) if len(ps) > 0 { return Part{}, ps } return p, nil } // ParseFixtures reads a fixtures file: a list of cases. func ParseFixtures(raw []byte) ([]Fixture, error) { var fs []Fixture if err := strict(raw, &fs); err != nil { return nil, err } var ps Problems for i, f := range fs { where := fmt.Sprintf("fixtures[%d]", i) if f.Name == "" { ps = append(ps, Problem{where + ".name", "missing"}) } if _, _, ok := f.Instance(); !ok { ps = append(ps, Problem{where + ".of", fmt.Sprintf("%q is none of verb:.input, verb:.answer, "+ "accept:, event:, holder-event:, state:/", f.Of)}) } if f.Given == nil { ps = append(ps, Problem{where + ".given", "missing"}) } } if len(ps) > 0 { return nil, ps } return fs, nil } // Instance splits a fixture's Of into its kind (verb-input, verb-answer, accept, event, holder-event) and name. func (f Fixture) Instance() (kind, name string, ok bool) { k, rest, found := strings.Cut(f.Of, ":") if !found || rest == "" { return "", "", false } switch k { case "accept", "event", "holder-event": return k, rest, true case "state": // state:/: one value of the state under that key form. if n, form, ok := strings.Cut(rest, "/"); ok && n != "" && form != "" { return "state", rest, true } case "verb": if n, ok := strings.CutSuffix(rest, ".input"); ok && n != "" { return "verb-input", n, true } if n, ok := strings.CutSuffix(rest, ".answer"); ok && n != "" { return "verb-answer", n, true } } return "", "", false } func strict(raw []byte, into any) error { if len(raw) > MaxSize { return ErrTooLarge } dec := json.NewDecoder(bytes.NewReader(raw)) dec.DisallowUnknownFields() if err := dec.Decode(into); err != nil { if f, ok := strings.CutPrefix(err.Error(), "json: unknown field "); ok { return Problem{strings.Trim(f, `"`), "a field the format does not know"} } return fmt.Errorf("not a seat definition's JSON: %w", err) } if dec.More() { return errors.New("not a seat definition's JSON: more than one value") } return nil } func formatProblem(n int) string { if n == 0 { return "missing" } return fmt.Sprintf("format %d, and this reader knows format %d only", n, Format) } func (d Definition) check() Problems { var ps Problems if d.Format != Format { ps = append(ps, Problem{"format", formatProblem(d.Format)}) } if d.Seat == "" { ps = append(ps, Problem{"seat", "missing"}) } else if !seatName.MatchString(d.Seat) { ps = append(ps, Problem{"seat", fmt.Sprintf("%q is not a lower-case name", d.Seat)}) } switch d.Scope { case ScopeMesh, ScopeNode: case "": ps = append(ps, Problem{"scope", "missing"}) default: ps = append(ps, Problem{"scope", fmt.Sprintf("%q is neither mesh nor node", d.Scope)}) } switch d.Grain { case Whole, SeatList: case "": ps = append(ps, Problem{"grain", "missing"}) default: ps = append(ps, Problem{"grain", fmt.Sprintf("%q is neither whole nor seat-list", d.Grain)}) } if d.Decision == "" { ps = append(ps, Problem{"decision", "missing"}) } switch { case d.Domain == "": ps = append(ps, Problem{"domain", "missing"}) case !slices.Contains(Domains, d.Domain): ps = append(ps, Problem{"domain", fmt.Sprintf("%q is not a domain of the glossary (%s)", d.Domain, strings.Join(Domains, ", "))}) } whole := d.Grain == Whole if !whole && (len(d.Includes) > 0 || d.Family != nil || len(d.HolderEvents) > 0 || len(d.States) > 0 || len(d.Provisions) > 0 || len(d.Defs) > 0) { ps = append(ps, Problem{"grain", "seat-list holds the seat list's fields only; includes, family, " + "holder-events, states, provisions and defs are a whole definition's"}) } if d.HolderDeclares && !whole { ps = append(ps, Problem{"holder-declares", "only a whole definition describes a seat its holder declares"}) } for i, inc := range d.Includes { if !wordName.MatchString(inc) { ps = append(ps, Problem{fmt.Sprintf("includes[%d]", i), fmt.Sprintf("%q is not a part's name", inc)}) } } ps = append(ps, checkVerbs(d.Verbs, whole)...) ps = append(ps, checkMessages("accepts", d.Accepts, whole)...) ps = append(ps, checkMessages("events", d.Events, whole)...) if whole && len(d.Events) > 0 && d.Family == nil { ps = append(ps, Problem{"family", "missing: a whole definition with events says where they are kept"}) } if d.Family != nil { if d.Family.Name == "" { ps = append(ps, Problem{"family.name", "missing"}) } if d.Family.MaxAgeDays != SharedEventsMaxAgeDays { ps = append(ps, Problem{"family.max-age-days", fmt.Sprintf("missing, or not %d: a seat's events ride the "+ "shared events stream, which keeps them %d days", SharedEventsMaxAgeDays, SharedEventsMaxAgeDays)}) } } for i, e := range d.HolderEvents { where := fmt.Sprintf("holder-events[%d]", i) if !eventName.MatchString(e.Name) { ps = append(ps, Problem{where + ".name", "missing, or not lower-case words joined by dots"}) } // A holder's event is published under the holder's own module subjects, or, when it is kept in a stream of the // holder's own module (its family), under that stream's (buscompose.ModuleStreamSubject). own, stream := "mesh.mod..event."+e.Name, "mesh.stream..event."+e.Name switch { case e.Subject == "": ps = append(ps, Problem{where + ".subject", "missing"}) case e.Subject == stream && e.Family == "": ps = append(ps, Problem{where + ".subject", "a subject of the holder's own stream, and no family names that stream"}) case e.Subject == own && e.Family != "": ps = append(ps, Problem{where + ".subject", "a family names the holder's own stream, so the event is under " + stream}) case e.Subject != own && e.Subject != stream: ps = append(ps, Problem{where + ".subject", fmt.Sprintf("not %s, nor %s for an event kept in the holder's own stream", own, stream)}) } } ps = append(ps, checkStates(d.States)...) ps = append(ps, checkActs(d.Acts)...) for i, p := range d.Provisions { where := fmt.Sprintf("provisions[%d]", i) if p.Name == "" { ps = append(ps, Problem{where + ".name", "missing"}) } if p.Form == nil { ps = append(ps, Problem{where + ".form", "missing"}) } } for i, r := range d.Receives { if r.Kind == "" { ps = append(ps, Problem{fmt.Sprintf("receives[%d].kind", i), "missing"}) } } for i, p := range d.Paths { if !strings.HasPrefix(p.Path, "/") { ps = append(ps, Problem{fmt.Sprintf("paths[%d].path", i), "missing, or not absolute"}) } } return ps } var ( keyPart = regexp.MustCompile(`<[^<>]*>`) keyPartOK = regexp.MustCompile(`^<[a-z][a-z0-9-]*>$`) keyLiteral = regexp.MustCompile(`^[A-Za-z0-9_.\-/=:]*$`) ) func checkStates(ss []State) Problems { var ps Problems seen := map[string]bool{} for i, s := range ss { where := fmt.Sprintf("states[%d]", i) if !wordName.MatchString(s.Name) { ps = append(ps, Problem{where + ".name", "missing, or not a lower-case name"}) } else if seen[s.Name] { ps = append(ps, Problem{where + ".name", fmt.Sprintf("%q twice", s.Name)}) } seen[s.Name] = true known := false for _, t := range Templates { known = known || s.Template == t } switch { case s.Template == "": ps = append(ps, Problem{where + ".template", "missing"}) case !known: ps = append(ps, Problem{where + ".template", fmt.Sprintf("%q is none of %s", s.Template, strings.Join(Templates, ", "))}) } if s.Writer != "" && s.Writer != WriterHolder && s.Writer != WriterCaller { ps = append(ps, Problem{where + ".writer", fmt.Sprintf("%q is neither holder nor caller", s.Writer)}) } if s.History < 0 || (s.History > 0 && s.Template != TemplateState) { ps = append(ps, Problem{where + ".history", "a count of past values, of a state template only"}) } stream := s.Template == TemplateEvents || s.Template == TemplateWorkQueue || s.Template == TemplateLog if s.MaxAgeDays < 0 || (s.MaxAgeDays > 0 && !stream) { ps = append(ps, Problem{where + ".max-age-days", "days, of an events, work-queue or log template only"}) } if len(s.KeyForms) == 0 { ps = append(ps, Problem{where + ".key-forms", "missing: a state gives at least one key form"}) } forms := map[string]bool{} for j, f := range s.KeyForms { at := fmt.Sprintf("%s.key-forms[%d]", where, j) if f.Key == "" { ps = append(ps, Problem{at + ".key", "missing"}) } else if bad := badKey(f.Key); bad != "" { ps = append(ps, Problem{at + ".key", bad}) } else if forms[f.Key] { ps = append(ps, Problem{at + ".key", fmt.Sprintf("%q twice", f.Key)}) } forms[f.Key] = true if f.Value == nil { ps = append(ps, Problem{at + ".value", fmt.Sprintf("missing: key form %q gives its value's schema", f.Key)}) } } } return ps } // badKey says what is wrong with a key pattern: a part between angle brackets that is not a lower-case name, or a // literal outside what a bus key may hold. func badKey(key string) string { for _, part := range keyPart.FindAllString(key, -1) { if !keyPartOK.MatchString(part) { return fmt.Sprintf("part %s is not a lower-case name between < and >", part) } } if lit := keyPart.ReplaceAllString(key, ""); !keyLiteral.MatchString(lit) || strings.ContainsAny(lit, "<>") { return fmt.Sprintf("%q holds a character a key may not", key) } return "" } func checkVerbs(vs []Verb, whole bool) Problems { var ps Problems seen := map[string]bool{} for i, v := range vs { where := fmt.Sprintf("verbs[%d]", i) if !wordName.MatchString(v.Name) { ps = append(ps, Problem{where + ".name", "missing, or not a lower-case name"}) } else if seen[v.Name] { ps = append(ps, Problem{where + ".name", fmt.Sprintf("%q twice", v.Name)}) } seen[v.Name] = true ps = append(ps, checkCallers(where+".callers", v.Callers)...) if v.Class != "" && !slices.Contains(Classes, v.Class) { ps = append(ps, Problem{where + ".class", fmt.Sprintf("%q is not a class (%s)", v.Class, strings.Join(Classes, ", "))}) } if whole && v.Input == nil { ps = append(ps, Problem{where + ".input", "missing: a whole definition gives every verb's input"}) } if whole && v.Answer == nil { ps = append(ps, Problem{where + ".answer", "missing: a whole definition gives every verb's answer"}) } } return ps } func checkMessages(field string, ms []Message, whole bool) Problems { var ps Problems seen := map[string]bool{} for i, m := range ms { where := fmt.Sprintf("%s[%d]", field, i) named := wordName if field == "events" { named = eventName } if !named.MatchString(m.Name) { ps = append(ps, Problem{where + ".name", "missing, or not a lower-case name"}) } else if key := m.Stream + "/" + m.Name; seen[key] { ps = append(ps, Problem{where + ".name", fmt.Sprintf("%q twice", m.Name)}) } seen[m.Stream+"/"+m.Name] = true switch { case m.Stream != "" && field != "accepts": ps = append(ps, Problem{where + ".stream", "only an accepted kind rides a stream"}) case m.Stream != "" && m.Stream != StreamCheck && m.Stream != StreamDelivery: ps = append(ps, Problem{where + ".stream", fmt.Sprintf("%q is not %s or %s", m.Stream, StreamCheck, StreamDelivery)}) } switch { case m.Keep != nil && field != "events": ps = append(ps, Problem{where + ".keep", "only an event is kept"}) case m.Keep != nil && !m.Keep.Object: ps = append(ps, Problem{where + ".keep", fmt.Sprintf("%q is the old form: keep is an object of max-age-days, max-mib and last-per-subject", m.Keep.Mode)}) case m.Keep != nil: ps = append(ps, checkKeepObject(where+".keep", *m.Keep)...) if strings.Contains(m.Name, ".") { ps = append(ps, Problem{where + ".name", "an event with a keep has no dot in its name: its stream is named from it"}) } if m.Keep.LastPerSubject && len(m.Parts()) == 0 && !m.ByCaller { ps = append(ps, Problem{where + ".keep", "an event of one subject kept last per subject is one message: give it a subject with parts"}) } } if m.Callers != nil && field != "accepts" { ps = append(ps, Problem{where + ".callers", "only an accepted kind carries callers"}) } ps = append(ps, checkCallers(where+".callers", m.Callers)...) if m.Subject != "" && field != "events" { ps = append(ps, Problem{where + ".subject", "only an event carries a subject of its own"}) } else if why := checkSubject(m); why != "" { ps = append(ps, Problem{where + ".subject", why}) } if whole && m.Body == nil { ps = append(ps, Problem{where + ".body", "missing: a whole definition gives every message's body"}) } } return ps } // Resolve is a definition with every part it includes taken in: the part's verbs and events first, in the order // the definition names the parts, then its own; and the part's types beside its own. A part named that is not given, // or a name the part and the definition both define, is refused. func Resolve(d Definition, parts map[string]Part) (Definition, error) { if len(d.Includes) == 0 { return gated(d), nil } out := d out.Includes = nil out.Verbs, out.Events = nil, nil out.Defs = map[string]map[string]any{} var ps Problems for _, name := range d.Includes { p, ok := parts[name] if !ok { ps = append(ps, Problem{"includes", fmt.Sprintf("part %q is not given", name)}) continue } out.Verbs = append(out.Verbs, p.Verbs...) out.Events = append(out.Events, p.Events...) for k, v := range p.Defs { out.Defs[k] = v } } out.Verbs = append(out.Verbs, d.Verbs...) out.Events = append(out.Events, d.Events...) for k, v := range d.Defs { if _, twice := out.Defs[k]; twice { ps = append(ps, Problem{"defs." + k, "defined by a part it includes too"}) } out.Defs[k] = v } if len(out.Defs) == 0 { out.Defs = nil } ps = append(ps, checkVerbs(out.Verbs, d.Grain == Whole)...) ps = append(ps, checkMessages("events", out.Events, d.Grain == Whole)...) if len(ps) > 0 { return Definition{}, ps } return gated(out), nil } // What a definition with a marked verb gains (design 47 G §677, §697; lead answer A-264). const ( // GatedEndedEvent is the event a process holder says a held call's end on, subject // `gated-ended..`, kept last per subject for GatedEndedKeptDays. GatedEndedEvent = "gated-ended" // GatedEndedKeptDays is how long gated-ended keeps each call's end. GatedEndedKeptDays = 1 // ApprovalsVerb is the verb that reads a holder's waiting calls, `act.` keys and claims, served by the seat server. ApprovalsVerb = "approvals" ) // gated is d as every reader reads it (A-264): when a verb of it needs approval, each marked verb is by-caller, and it // gains the event gated-ended and the verb approvals (class read) where it does not name them itself; the seat's files // stay as written. A definition with no marked verb is d. func gated(d Definition) Definition { marked := false for _, v := range d.Verbs { marked = marked || v.NeedsApproval } if !marked { return d } verbs := make([]Verb, 0, len(d.Verbs)+1) for _, v := range d.Verbs { if v.NeedsApproval { v.ByCaller = true } verbs = append(verbs, v) } if !slices.Contains(VerbNames(verbs), ApprovalsVerb) { verbs = append(verbs, Verb{Name: ApprovalsVerb, Class: ClassRead, ByCaller: true, Description: "The holder's calls of its marked verbs: each waiting or ended call with its caller, ask and state, " + "the act keys and the claims; a call's arguments only to that call's caller.", Input: map[string]any{"type": "object"}, Answer: map[string]any{"type": "object", "required": []any{"calls", "acts", "claims"}, "properties": map[string]any{ "calls": map[string]any{"type": "array"}, "acts": map[string]any{"type": "array"}, "claims": map[string]any{"type": "array"}}}}) } d.Verbs = verbs if !slices.Contains(MessageNames(d.Events), GatedEndedEvent) { days := GatedEndedKeptDays events := append([]Message{}, d.Events...) d.Events = append(events, Message{Name: GatedEndedEvent, Subject: GatedEndedEvent + "..", Keep: &Keep{MaxAgeDays: &days, LastPerSubject: true, Object: true}, Body: map[string]any{"type": "object", "required": []any{"call", "ask", "act", "verb", "outcome"}, "properties": map[string]any{ "call": map[string]any{"type": "string"}, "ask": map[string]any{"type": "string"}, "act": map[string]any{"type": "string"}, "verb": map[string]any{"type": "string"}, "outcome": map[string]any{"enum": []any{"ran", "declined", "expired", "refused"}}, "answer": map[string]any{}, "approval": map[string]any{"type": "string"}, "error": map[string]any{"type": "string"}}}}) } return d } // EventSubject is where the seat's event is published; by a caller, the caller's name follows. func EventSubject(seat, event string) string { return "mesh.seat." + seat + ".event." + event } // AcceptSubject is where a message the seat accepts is sent. func AcceptSubject(seat, accept string) string { return "mesh.seat." + seat + ".accept." + accept } // Index is the reading order of a contracts module's seats, `seats/index.json`: the seat list is read in it. type Index struct { Format int `json:"format"` Seats []string `json:"seats"` } // ParseIndex reads the index, refusing a seat named twice. func ParseIndex(raw []byte) (Index, error) { var ix Index if err := strict(raw, &ix); err != nil { return Index{}, err } var ps Problems if ix.Format != Format { ps = append(ps, Problem{"format", formatProblem(ix.Format)}) } seen := map[string]bool{} for i, s := range ix.Seats { if seen[s] { ps = append(ps, Problem{fmt.Sprintf("seats[%d]", i), fmt.Sprintf("%q twice", s)}) } seen[s] = true } if len(ps) > 0 { return Index{}, ps } return ix, nil } // Names are the verbs', or messages', names in order. func VerbNames(vs []Verb) []string { out := make([]string, len(vs)) for i, v := range vs { out[i] = v.Name } return out } // MessageNames are the messages' names in order. func MessageNames(ms []Message) []string { out := make([]string, len(ms)) for i, m := range ms { out[i] = m.Name } return out } // DefNames are a definition's named types, sorted. func (d Definition) DefNames() []string { out := make([]string, 0, len(d.Defs)) for k := range d.Defs { out = append(out, k) } sort.Strings(out) return out }