Files
mesh-sdk/go/seatlist/seatlist.go
T
jschoubben 9f9e34301a S3: the seat-list reader asks again on a timeout (issue 1966, ADR 0668)
Closes the gap #184 left: the read is safe to repeat, so a timed-out ask is asked again.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 02:52:19 +01:00

510 lines
19 KiB
Go

// Package seatlist is the runtime's reader of the seat list (novox/hq ADR 0635 §1, ADR 0636 §1, §3, §4): the seat
// definitions the seat mesh-catalog keeps, read through its verb `seat-definitions` and followed on its events
// `seat-definition-changed` and `seat-definition-removed`. The manifest validator, the node-engine, the tool runner,
// claude-code, the grants part and every other caller of `catalogue` get their seats here and give them to `catalogue`
// as an input; mesh-sdk compiles no seat list and imports no contracts module.
//
// **What it asks and hears.** The seat's verb with no seat (every trunk definition's name and digest, Listing) and with
// one seat (that definition, Answer); the seat's two events, whose bodies name the seat (Changed). It calls the seat,
// never the module that holds it, and only trunk definitions are held: a pull request's are the indexer's to judge.
// An ask that reached no one (busretry.Undelivered: the bus's "no responders", as while the seat's holder re-serves) is
// asked again within the bus's retry bound (busretry.Bound, about 30 s, backing off; issue 774's form, issue 1966), and so is one
// that timed out: the ask is a read, safe to make again (busretry.DoRepeatable; novox/hq ADR 0668).
// Nothing else polls or waits on a timer: a reader that could not ask says so in its Status and reads again on the
// next event or on Reload, which the host offers as a tool (Tools).
//
// **A reader that has not heard acts on nothing new** (ADR 0636 §1): MayAct says what a host may start, compose, grant
// or judge meanwhile, which is only the modules whose seats the bootstrapped definitions name (ADR 0636 §2). It keeps
// running what it runs; a missing or removed definition only refuses a new claim, invoke or grant of that seat (Has).
//
// **What it names.** The one seat that serves the list (Seat and Verb), which ADR 0636 §4 fixes as the runtime's own
// way in; no module, no other seat.
package seatlist
import (
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
"sync"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/busretry"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
const (
// Seat is the seat that serves the seat list (ADR 0636 §4); the bootstrapped definitions name it (ADR 0636 §2).
Seat = "mesh-catalog"
// Verb is its verb: with no seat, every trunk seat with its digest; with a seat, that definition.
Verb = "seat-definitions"
// ChangedEvent and RemovedEvent are its events: a trunk's definition moved, or went.
ChangedEvent = "seat-definition-changed"
RemovedEvent = "seat-definition-removed"
// SourceTrunk is the only source this reader holds.
SourceTrunk = "trunk"
// SourceBootstrap is what a definition is held from before the seat has named it.
SourceBootstrap = "bootstrap"
)
// Key is the address a reader asks (`seat:<seat>.<verb>`, as stdio.Ask takes it); a host's manifest `invokes` lists the
// verb. Pattern is what it subscribes to for an event (`<seat>.<event>`), which the host's manifest `consumes`.
func Key() string { return "seat:" + Seat + "." + Verb }
// Pattern is the subscription of one of the seat's events.
func Pattern(event string) string { return Seat + "." + event }
// Bus is what the reader needs of its host: a call by its address and a subscription to an event pattern. StdioBus is
// the one a bundle has; the node-engine and the tool runner give theirs.
type Bus interface {
Ask(key string, body any) (json.RawMessage, error)
Subscribe(pattern string, handle func(key string, body json.RawMessage) error) error
}
// Entry is one definition as the seat answers it: the seat, its source, the digest of the file, and, in an answer for one
// seat, the definition resolved with the parts it includes.
type Entry struct {
Seat string `json:"seat"`
Source string `json:"source,omitempty"`
Digest string `json:"digest,omitempty"`
Definition json.RawMessage `json:"definition,omitempty"`
Unparsed string `json:"unparsed,omitempty"`
}
// Listing is the seat's answer with no seat: every trunk seat with its digest, and the revision of its state.
type Listing struct {
Revision uint64 `json:"revision"`
Seats []Entry `json:"seats"`
}
// Answer is the seat's answer with one seat.
type Answer struct {
Seat string `json:"seat"`
Found bool `json:"found"`
Entry *Entry `json:"entry,omitempty"`
Revision uint64 `json:"revision"`
}
// Changed is an event's body.
type Changed struct {
Seat string `json:"seat"`
Source string `json:"source,omitempty"`
Digest string `json:"digest,omitempty"`
}
// Config is what a host gives Start.
type Config struct {
// Bus is the host's way to the seat; StdioBus() for a bundle.
Bus Bus
// Bootstrap are the definitions known before the seat is heard (ADR 0636 §2); Bootstrapped() is the mesh's.
Bootstrap []seatdef.Definition
// OnChange, when set, is called after the held set changed, with the seats in reading order. It runs on the
// goroutine that heard the change: it returns quickly.
OnChange func([]catalogue.Seat)
}
// Reader holds the seat list.
type Reader struct {
cfg Config
mu sync.Mutex
defs map[string]seatdef.Definition // by seat
digests map[string]string // by seat: the digest of the trunk file held
boot map[string]bool // seats held from the bootstrap, not yet from the seat
refused map[string]string // seats whose trunk definition cannot be parsed, with why: the one that stands stays
// what the last ask of the seat came to (Status)
spoken bool
ready chan struct{} // closed once the first read of the seat has come to an end, answered or not
revision uint64
lastErr string
again chan struct{} // the read ReloadIfUnread began, closed when it has come to an end
}
// Held is one definition a reader holds: its seat, where from, and the digest of the trunk file it came from.
type Held struct {
Seat string `json:"seat"`
Source string `json:"source"`
Digest string `json:"digest,omitempty"`
}
// Status is what the reader holds and what it waits for (ADR 0636 §1, §7), for the host's health and its tool: Heard says
// the seat has answered, Waiting are the seats still held from the bootstrap alone (the seat has not named them), Refused
// are the seats whose trunk definition did not parse (the one held stands), LastError is why the last ask failed, and
// Revision is the seat's state revision of the last listing.
type Status struct {
Heard bool `json:"heard"`
// Reading says the first read of the seat has not come to an end yet.
Reading bool `json:"reading,omitempty"`
Held []Held `json:"held"`
Waiting []string `json:"waiting,omitempty"`
Refused map[string]string `json:"refused,omitempty"`
LastError string `json:"last-error,omitempty"`
Revision uint64 `json:"revision,omitempty"`
}
// Status is the reader's state of mind.
func (r *Reader) Status() Status {
r.mu.Lock()
defer r.mu.Unlock()
st := Status{Heard: r.spoken, Reading: !r.isReady(), LastError: r.lastErr, Revision: r.revision, Held: []Held{}}
for seat := range r.defs {
h := Held{Seat: seat, Source: SourceTrunk, Digest: r.digests[seat]}
if r.boot[seat] {
h.Source = SourceBootstrap
st.Waiting = append(st.Waiting, seat)
}
st.Held = append(st.Held, h)
}
sort.Slice(st.Held, func(i, j int) bool { return st.Held[i].Seat < st.Held[j].Seat })
sort.Strings(st.Waiting)
if len(r.refused) > 0 {
st.Refused = map[string]string{}
for k, v := range r.refused {
st.Refused[k] = v
}
}
return st
}
// Health is Status as the one line a module's health says: empty when the seat has been heard and nothing waits.
func (st Status) Health() string {
switch {
case st.Reading:
return fmt.Sprintf("the seat list is held from the bootstrap (%d seats) and nothing new is acted on: the first read of the seat %s has not ended", len(st.Held), Seat)
case !st.Heard:
return fmt.Sprintf("the seat list is held from the bootstrap (%d seats) and nothing new is acted on: the seat %s has not answered%s",
len(st.Held), Seat, withError(st.LastError))
case len(st.Waiting) > 0:
return fmt.Sprintf("%d seats are held from the bootstrap alone, the seat %s names none of them: %s", len(st.Waiting), Seat, strings.Join(st.Waiting, ", "))
}
return ""
}
func withError(e string) string {
if e == "" {
return ""
}
return " (" + e + ")"
}
// Start returns at once a reader holding the bootstrap, following the seat's two events, and reads the seat for every
// definition on a goroutine of its own, so a slow seat holds nobody's start (ADR 0636 §1). Until that read has come to an
// end the reader acts on nothing new (MayAct) and Status says it is reading; Ready is closed then. A first read the seat
// did not answer is no failure: the reader holds the bootstrap and reads again on the seat's next event or on Reload.
// Start returns the subscription's error alone, which the host may ask again by calling Start again on a new reader.
func Start(cfg Config) (*Reader, error) {
if cfg.Bus == nil {
return nil, errors.New("seatlist: no bus to read the seat list through")
}
r := &Reader{cfg: cfg, defs: map[string]seatdef.Definition{}, digests: map[string]string{}, boot: map[string]bool{}, refused: map[string]string{}, ready: make(chan struct{})}
for _, d := range cfg.Bootstrap {
r.defs[d.Seat] = d
r.boot[d.Seat] = true
}
for _, ev := range []string{ChangedEvent, RemovedEvent} {
if err := cfg.Bus.Subscribe(Pattern(ev), r.heard); err != nil {
return r, fmt.Errorf("seatlist: following %s: %w", ev, err)
}
}
go func() {
_ = r.Reload()
close(r.ready)
}()
return r, nil
}
// Ready is closed once the first read of the seat, which Start began, has come to an end, whether the seat answered or
// not: a test or a host that needs the reader's first state waits on it.
func (r *Reader) Ready() <-chan struct{} { return r.ready }
func (r *Reader) isReady() bool {
select {
case <-r.ready:
return true
default:
return false
}
}
// Seats are the held seats in reading order, as catalogue takes them.
func (r *Reader) Seats() []catalogue.Seat {
r.mu.Lock()
defer r.mu.Unlock()
return r.seatsLocked()
}
// Definitions are the held definitions, by seat name.
func (r *Reader) Definitions() map[string]seatdef.Definition {
r.mu.Lock()
defer r.mu.Unlock()
out := make(map[string]seatdef.Definition, len(r.defs))
for k, v := range r.defs {
out[k] = v
}
return out
}
// Has says whether the reader holds a definition of the seat: a claim, invoke or grant of a seat it does not hold is
// refused, and nothing already running is stopped for it (ADR 0636 §3).
func (r *Reader) Has(seat string) bool {
r.mu.Lock()
defer r.mu.Unlock()
_, ok := r.defs[seat]
return ok
}
// MayAct says whether a host may start, compose, grant or judge a module that claims, invokes or provides the given seats
// (ADR 0636 §1): once the seat list has been read, any; before, only a module whose seats are all bootstrapped
// ones (ADR 0636 §2), and at least one. It changes nothing a module already runs.
func (r *Reader) MayAct(seats ...string) bool {
r.mu.Lock()
defer r.mu.Unlock()
if r.spoken {
return true
}
if len(seats) == 0 {
return false
}
for _, s := range seats {
if !r.boot[s] {
return false
}
}
return true
}
func (r *Reader) seatsLocked() []catalogue.Seat {
ds := make([]seatdef.Definition, 0, len(r.defs))
for _, d := range r.defs {
ds = append(ds, d)
}
return catalogue.SeatsFromDefinitions(ds)
}
// Reload asks the seat for its trunk seats and digests and then for each definition it holds a different digest of,
// and drops the trunk seats it no longer lists; a bootstrapped seat the seat does not list stays and waits. An answer that
// cannot be read is returned and changes nothing; one definition that does not parse leaves the one held standing and is
// said in Status.
func (r *Reader) Reload() error {
raw, err := r.ask(map[string]any{}, "the seat list")
if err != nil {
return r.failed(fmt.Errorf("seatlist: asking %s: %w", Key(), err))
}
var l Listing
if err := json.Unmarshal(raw, &l); err != nil {
return r.failed(fmt.Errorf("seatlist: %s answered what is not a listing: %w", Key(), err))
}
listed := map[string]bool{}
var first error
for _, e := range l.Seats {
if e.Seat == "" || (e.Source != "" && e.Source != SourceTrunk) {
continue
}
listed[e.Seat] = true
r.mu.Lock()
same := !r.boot[e.Seat] && e.Digest != "" && r.digests[e.Seat] == e.Digest
r.mu.Unlock()
if same {
continue
}
if err := r.fetch(e.Seat); err != nil && first == nil {
first = err
}
}
r.mu.Lock()
r.spoken, r.revision = true, l.Revision
if first == nil {
r.lastErr = ""
}
for seat := range r.defs {
if !r.boot[seat] && !listed[seat] {
r.dropLocked(seat)
}
}
r.mu.Unlock()
r.changed()
if first != nil {
return r.failed(first)
}
return nil
}
// ReloadIfUnread reads the list again, on a goroutine of its own, when the seat has not answered yet; it is for a host whose
// path for the seat's events has just become live. The seat may have said it speaks before that path existed, and events
// start at the stream's end, so without this call the list would stay unread until the seat's next event (ADR 0636 §1).
// It returns nil when the list is already read; otherwise a channel closed when the read has come to an end, which is the
// reader's first read or the read a call before began while one is still running, never a second one beside it. Whether the
// seat answered is Status().Heard; an unanswered read leaves the list unread, to be read at the seat's next event.
func (r *Reader) ReloadIfUnread() <-chan struct{} {
r.mu.Lock()
defer r.mu.Unlock()
if r.spoken {
return nil
}
if !r.isReady() {
return r.ready
}
if r.again != nil {
select {
case <-r.again:
default:
return r.again
}
}
done := make(chan struct{})
r.again = done
go func() {
_ = r.Reload()
close(done)
}()
return done
}
// ask asks the seat's verb, and again while the ask reached no one or timed out, within the bus's retry bound: a holder
// that re-serves for a few seconds while the reader starts leaves no list unread (issue 1966). The ask is a read, so it
// is safe to make again on a timeout (busretry.DoRepeatable; novox/hq ADR 0668). An answer or a refusal is never asked
// again.
func (r *Reader) ask(body map[string]any, what string) (json.RawMessage, error) {
return busretry.DoRepeatable(what, func() (json.RawMessage, error) {
return r.cfg.Bus.Ask(Key(), body)
}, nil)
}
// fetch asks the seat for one definition and holds it, or drops it when the seat holds none.
func (r *Reader) fetch(seat string) error {
raw, err := r.ask(map[string]any{"seat": seat}, "the seat "+seat)
if err != nil {
return fmt.Errorf("seatlist: asking %s for %s: %w", Key(), seat, err)
}
var a Answer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("seatlist: %s answered for %s what is not an answer: %w", Key(), seat, err)
}
r.mu.Lock()
defer r.mu.Unlock()
switch {
case !a.Found || a.Entry == nil || (a.Entry.Source != "" && a.Entry.Source != SourceTrunk):
r.dropLocked(seat)
case a.Entry.Unparsed != "" || len(a.Entry.Definition) == 0:
r.refused[seat] = a.Entry.Unparsed // the definition that stands stays: a trunk's that does not parse is never written over it
default:
d, err := seatdef.Parse(a.Entry.Definition)
if err != nil {
r.refused[seat] = err.Error()
return nil
}
r.defs[seat], r.digests[seat] = d, a.Entry.Digest
delete(r.boot, seat)
delete(r.refused, seat)
}
return nil
}
// dropLocked forgets a seat: its definition is gone, so a new claim of it is refused (ADR 0636 §3).
func (r *Reader) dropLocked(seat string) {
delete(r.defs, seat)
delete(r.digests, seat)
delete(r.boot, seat)
delete(r.refused, seat)
}
// heard takes one of the seat's events: a trunk definition moved, so that seat is asked again, or went, so it is dropped.
// An error is returned so the bus offers the event again.
func (r *Reader) heard(key string, body json.RawMessage) error {
r.mu.Lock()
unread := !r.spoken
r.mu.Unlock()
if unread {
// the seat was silent when the reader started and speaks now: read the whole list, not only the seat named
if err := r.Reload(); err != nil {
return err
}
return nil
}
var c Changed
if err := json.Unmarshal(body, &c); err != nil || c.Seat == "" {
return nil
}
if c.Source != "" && c.Source != SourceTrunk {
return nil
}
r.mu.Lock()
spoken := r.spoken
r.mu.Unlock()
if !spoken {
// The seat was silent when this reader started: its event says it speaks now, so the whole list is read, not this
// seat alone, and the reader is heard (MayAct) from here on.
return r.Reload()
}
if strings.HasSuffix(key, "."+RemovedEvent) {
r.mu.Lock()
r.dropLocked(c.Seat)
r.mu.Unlock()
r.changed()
return nil
}
if err := r.fetch(c.Seat); err != nil {
return r.failed(err)
}
r.changed()
return nil
}
func (r *Reader) failed(err error) error {
r.mu.Lock()
r.lastErr = err.Error()
r.mu.Unlock()
return err
}
func (r *Reader) changed() {
if r.cfg.OnChange != nil {
r.cfg.OnChange(r.Seats())
}
}
// Tools are the reader's two runtime tools (ADR 0636 §7), for a host's bundle: read, which says what the reader holds
// (every definition, its source and digest) and what it waits for; and again, which makes it read the list now, and
// answers only to the callers the host's list names (the operator and the healers). The host names the tools and the list;
// again records nothing but the read it asked.
func Tools(r *Reader, read, again string, callers []string) []stdio.Tool {
return []stdio.Tool{
{Name: read,
Description: "The seat list this part holds (novox/hq ADR 0636): each seat's definition with its source (trunk or bootstrap) and " +
"the digest of the file it came from, the seats still held from the bootstrap alone, definitions refused because they " +
"do not parse, whether the seat " + Seat + " has answered and why not.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) {
return map[string]any{"status": r.Status(), "health": r.Status().Health()}, nil
}},
{Name: again,
Description: "Read the seat list again now, from the seat " + Seat + " (a hand act for a part that waits or holds a stale definition), " +
"and answer what it holds afterwards. Answered only to the operator and the healers.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(args map[string]any) (any, error) {
if err := Refusal(again, callers, stdio.CallerOf(args)); err != nil {
return nil, err
}
err := r.Reload()
st := r.Status()
out := map[string]any{"status": st, "health": st.Health()}
if err != nil {
out["error"] = err.Error()
}
return out, nil
}},
}
}
// Refusal is why caller may not make the reader read again, or nil: the caller's proof, never an argument, against
// callers, the entries of a verb's list as VerbCallers reads them, so stdio.AnyPerson names every operator's session
// the runtime proved (person.<name>) and a module name its instances (ADR 0636 §7).
func Refusal(tool string, callers []string, caller string) error {
if err := (stdio.VerbCallers{tool: callers}).Allowed(tool, caller); err != nil {
return fmt.Errorf("%s is refused to %q: it answers only %s (novox/hq ADR 0636 §7)", tool, caller, strings.Join(callers, ", "))
}
return nil
}