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
510 lines
19 KiB
Go
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
|
|
}
|