Files
mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches.go
T
jschoubben 4938fb2d73 Names N2b: every seat list part's callers name seats, resolved from the seat-holders view
The builder, its tools bundle, the assigner (process and bundle) and the view's tools bundle answered
their seat list's again tool to the modules node-tools and mesh-healers. Their lists are now the
operator, seat:node-tool-runner and seat:mesh-healers, resolved by a holder function:
- meshcatalogclient's Branches.Claimant (moved from the builder's versions.HolderOf, which now asks it)
  names the claimant of mesh-module-assigner from the trunk's half, and Branches.SeatHolders follows
  that claimant's seat-holders view through the part's wiring. It drops the view and follows the new
  claimant's on a catalog change, asks nothing on a timer, and answers seatlist.HoldersIn.
- the assigner answers HoldersIn from its own seat-holders picture (its world in the process, the
  watched copy in the bundle).
The builder's and the view's manifests consume seat:mesh-module-assigner.views.seat-holders. The
assigner's seat-holders first-view tool answers both, by module as A-131 has it.

Builds: design 47 G A-298, A-295, A-296, A-210, A-131, §717, §616, §614

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 19:05:51 +01:00

443 lines
15 KiB
Go

package meshcatalogclient
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"sync"
"sync/atomic"
"time"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/sourcebranches"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/busretry"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
// SourceVerb is the gate's verb a part reads the branches the gate keeps a source revision of by, before the first
// registrations, as its manifest's invokes names it (design 47 G §614); the follower is the SDK's sourcebranches.
const SourceVerb = sourcebranches.SourceVerb
// EntryVerb is the seat verb a part reads an entry by its fingerprint by, as its manifest's invokes names it.
const EntryVerb = "seat:" + seat.Seat + "." + seat.VerbEntry
// Wiring is how Branches puts a view on its part's one reader and takes it off: ReaderWiring for a bundle's
// views.Reader, ProcessWiring for a process's views.ProcessReader. Adopt is the reader's Adopt, so a view adopted after
// the reader's Start takes its first view at once; Drop is its Drop, which clears every finding the view raised.
type Wiring interface {
Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error
Drop(owner, state string) error
}
type readerWiring struct{ r *views.Reader }
func (w readerWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error {
return w.r.Adopt(f, seat, event, hear)
}
func (w readerWiring) Drop(owner, state string) error { return w.r.Drop(owner + "." + state) }
type processWiring struct{ r *views.ProcessReader }
func (w processWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error {
_, err := w.r.Adopt(f, seat, event, hear)
return err
}
func (w processWiring) Drop(owner, state string) error { return w.r.Drop(owner, state) }
// ReaderWiring wires Branches on a bundle's reader.
func ReaderWiring(r *views.Reader) Wiring { return readerWiring{r} }
// Rows adds the list to the reader's `<module>_first_views`.
func (w readerWiring) Rows(name string, rows func() any) { w.r.Rows(name, rows) }
// ProcessWiring wires Branches on a process's reader.
func ProcessWiring(r *views.ProcessReader) Wiring { return processWiring{r} }
// Branches is the one branch follower of design 47 G §614, built once and used by every part that reads the catalog half:
// it follows the watched branches of the registrations (the first view of `registrations` at the start, then each
// `registration-changed`); before the first registration, the branches the gate's `source` answers (its first view at
// the start, then each `source-moved`), which it stops following at the first `registration-changed`; it adopts a Catalog
// view on the part's reader for each branch that comes and drops the view of each that goes, and keeps the entries by
// fingerprint a part asks of the verb `entry` (Entries). The part declares what §614 says in `consumes` and `invokes`.
type Branches struct {
// Registrations is the follower of the registrations, also the part's own reading of them.
Registrations *Registrations
// Entries is the cache of the entries read by fingerprint.
Entries *Entries
// claims are the seats each manifest digest claims (Claimant), holders the part's follow of the seat-holders view (SeatHolders).
claimsMu sync.Mutex
claims map[string][]string
holders atomic.Pointer[seatHolders]
// Changed, when not nil, is told of each change to a branch's view (module, its entry, deleted), set before Wire.
Changed func(branch, module string, entry json.RawMessage, deleted bool, at time.Time)
// Adopted, when not nil, is told on a goroutine of its own of each branch whose view was adopted, with that view (a part that waits for
// its first branch's first view, design 47 G §507), set before Wire.
Adopted func(branch string, c *Catalog)
// Logf, when not nil, says each view adopted and dropped.
Logf func(format string, args ...any)
call Call
w Wiring
mu sync.Mutex
source *sourcebranches.SourceBranches
left []string // the source's branches when it was left, kept until the registrations hold one
catalogs map[string]*Catalog
order []string
}
// NewBranches adopts the registrations and the gate's source on w, so the reader's Start asks them, and then adopts a
// Catalog per branch as the picture says. call asks the seat verbs.
func NewBranches(w Wiring, call Call) (*Branches, error) {
b := &Branches{call: call, w: w, catalogs: map[string]*Catalog{}, Entries: NewEntries(call)}
b.Registrations = NewRegistrations(call)
b.Registrations.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() }
b.source = sourcebranches.New(sourcebranches.Call(call))
b.source.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() }
if err := w.Adopt(b.Registrations.Follower, seat.Seat, seat.EventRegistrationChanged, b.hearRegistration); err != nil {
return nil, err
}
if err := w.Adopt(b.source.Follower, sourcebranches.Seat, sourcebranches.EventSourceMoved, b.source.Hear); err != nil {
return nil, err
}
if rw, ok := w.(interface {
Rows(name string, rows func() any)
}); ok { // the entries by fingerprint are said in the part's `<module>_first_views` (design 47 G A-103)
rw.Rows("entries", func() any { return b.EntryStatuses() })
}
return b, nil
}
// FollowBranches is NewBranches on a bundle's reader.
func FollowBranches(r *views.Reader, call Call) (*Branches, error) {
return NewBranches(ReaderWiring(r), call)
}
// FollowBranchesProcess is NewBranches on a process's reader.
func FollowBranchesProcess(r *views.ProcessReader, call Call) (*Branches, error) {
return NewBranches(ProcessWiring(r), call)
}
func (b *Branches) logf(format string, args ...any) {
if b.Logf != nil {
b.Logf(format, args...)
}
}
// hearRegistration is the handler of `registration-changed`: the first one ends the following of the gate's source.
func (b *Branches) hearRegistration(ctx context.Context, data []byte) error {
err := b.Registrations.Hear(ctx, data)
if err != nil {
return err
}
b.mu.Lock()
s := b.source
if s != nil {
b.left, b.source = s.Branches(), nil
}
b.mu.Unlock()
if s != nil {
if err := b.w.Drop(sourcebranches.Seat, sourcebranches.StateSourceBranches); err != nil {
b.logf("meshcatalogclient: the gate's source is not dropped: %v", err)
} else {
b.logf("meshcatalogclient: the first registration-changed is heard: the gate's source is followed no more")
}
b.reconcile()
}
return nil
}
// Followed is the branches (as named) whose views are adopted, in the order they came.
func (b *Branches) Followed() []string {
b.mu.Lock()
defer b.mu.Unlock()
out := make([]string, 0, len(b.order))
for _, e := range b.order {
out = append(out, b.catalogs[e].Branch)
}
return out
}
// Catalog is the view of one branch, as named; false when it is not followed.
func (b *Branches) Catalog(branch string) (*Catalog, bool) {
b.mu.Lock()
defer b.mu.Unlock()
c, ok := b.catalogs[keys.EscapeName(branch)]
return c, ok
}
// Resolve reads an entry by its fingerprint: from a branch's held half when one lists it, else from the entries kept
// by fingerprint, asked of `entry` once when none is kept. The state is `answered` for an entry at hand, `asked` while the
// ask is out, `not-found` once the holder said it holds none.
func (b *Branches) Resolve(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) {
b.mu.Lock()
cs := make([]*Catalog, 0, len(b.order))
for _, e := range b.order {
cs = append(cs, b.catalogs[e])
}
b.mu.Unlock()
for _, c := range cs {
if half, ok := c.View(); ok {
for _, e := range half.Entries {
if e.Fp == fingerprint {
return e, EntryAnswered
}
}
}
}
return b.Entries.Need(ctx, fingerprint)
}
// Listed says whether a branch's held half lists fingerprint.
func (b *Branches) Listed(fingerprint string) bool {
b.mu.Lock()
cs := make([]*Catalog, 0, len(b.order))
for _, e := range b.order {
cs = append(cs, b.catalogs[e])
}
b.mu.Unlock()
for _, c := range cs {
if half, ok := c.View(); ok {
for _, e := range half.Entries {
if e.Fp == fingerprint {
return true
}
}
}
}
return false
}
// reconcile adopts the view of each branch that is wanted and drops the view of each that is not: the registrations'
// branches, and the gate's source's while it is followed (and, once left, until the registrations hold a branch).
func (b *Branches) reconcile() {
b.mu.Lock()
defer b.mu.Unlock()
want := map[string]string{} // escaped -> as named
for _, reg := range b.Registrations.All() {
for _, br := range reg.Branches {
want[keys.EscapeName(br)] = br
}
}
var from []string
switch {
case b.source != nil:
from = b.source.Branches()
case len(want) == 0:
from = b.left
default:
b.left = nil
}
for _, e := range from {
if name, err := keys.UnescapeName(e); err == nil {
want[e] = name
}
}
for _, e := range slices.Sorted(mapsKeys(want)) {
if b.catalogs[e] != nil {
continue
}
c, err := NewCatalog(b.call, want[e])
if err != nil {
b.logf("meshcatalogclient: the branch %q is not followed: %v", want[e], err)
continue
}
branch := want[e]
c.Follower.Changed = func(module string, entry json.RawMessage, deleted bool, at time.Time) {
b.holders.Load().changed()
if b.Changed != nil {
b.Changed(branch, module, entry, deleted, at)
}
}
if err := b.w.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, c.Hear); err != nil {
b.logf("meshcatalogclient: the view of the branch %q is not adopted: %v", want[e], err)
continue
}
b.catalogs[e] = c
b.order = append(b.order, e)
b.logf("meshcatalogclient: the branch %q is followed", want[e])
if b.Adopted != nil {
go b.Adopted(branch, c)
}
}
for _, e := range slices.Clone(b.order) {
if _, ok := want[e]; ok {
continue
}
c := b.catalogs[e]
if err := b.w.Drop(seat.Seat, c.Follower.State); err != nil {
b.logf("meshcatalogclient: the view of the branch %q is not dropped: %v", c.Branch, err)
}
delete(b.catalogs, e)
b.order = slices.DeleteFunc(b.order, func(o string) bool { return o == e })
b.logf("meshcatalogclient: the branch %q is followed no more", c.Branch)
}
}
func mapsKeys(m map[string]string) func(func(string) bool) {
return func(yield func(string) bool) {
for k := range m {
if !yield(k) {
return
}
}
}
}
// EntryState is where an entry read by fingerprint stands.
type EntryState string
// The states of an entry kept by fingerprint (design 47 G §614, An older build's entry).
const (
EntryAsked EntryState = "asked"
EntryAnswered EntryState = "answered"
EntryNotFound EntryState = "not-found"
)
// EntryRow is one entry kept by fingerprint: its state, since when, and the entry once answered.
type EntryRow struct {
Fingerprint string
State EntryState
Since time.Time
// Detail says why an ask is still out when its last try failed.
Detail string
Entry *seat.CatalogEntry
}
// Entries keeps, beside a part's views, the entries by fingerprint it asked of `entry` (design 47 G §614): each is
// asked, answered or not found. The reader a part passes to a pure function answers from the views and these alone.
type Entries struct {
// Changed, when not nil, is told of each entry that was answered or found missing, so the part starts a new pass at
// once, or writes the finding `entry-not-found`.
Changed func(row EntryRow)
// Released, when not nil, is told of each entry removed by Release.
Released func(fingerprint string)
// Now is the clock, time.Now when nil.
Now func() time.Time
call Call
mu sync.Mutex
rows map[string]*EntryRow
}
// NewEntries is an Entries asking the seat through call.
func NewEntries(call Call) *Entries { return &Entries{call: call, rows: map[string]*EntryRow{}} }
func (e *Entries) now() time.Time {
if e.Now != nil {
return e.Now()
}
return time.Now()
}
// Need reads fingerprint's entry: one kept is answered as it stands (`asked` as pending, a state apart from none); one
// not kept is asked of `entry` once, on its own goroutine, and answered as `asked`.
func (e *Entries) Need(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) {
e.mu.Lock()
row := e.rows[fingerprint]
if row == nil {
row = &EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()}
e.rows[fingerprint] = row
e.mu.Unlock()
go e.ask(ctx, fingerprint)
return seat.CatalogEntry{}, EntryAsked
}
defer e.mu.Unlock()
if row.Entry != nil {
return *row.Entry, row.State
}
return seat.CatalogEntry{}, row.State
}
// Again asks fingerprint's entry now, whatever its state (the part's tool `<module>_entry_again`). It waits for the answer.
func (e *Entries) Again(ctx context.Context, fingerprint string) error {
e.mu.Lock()
row := e.rows[fingerprint]
if row == nil {
e.mu.Unlock()
return fmt.Errorf("meshcatalogclient: no entry of %s is kept", fingerprint)
}
*row = EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()}
e.mu.Unlock()
e.ask(ctx, fingerprint)
return nil
}
// Release removes fingerprint's entry: no `running` or `wanted` the part holds names it any more.
func (e *Entries) Release(fingerprint string) {
e.mu.Lock()
delete(e.rows, fingerprint)
e.mu.Unlock()
if e.Released != nil {
e.Released(fingerprint)
}
}
// Rows lists the entries kept, by fingerprint (the part's tool `<module>_first_views` lists them with their state and
// since when).
func (e *Entries) Rows() []EntryRow {
e.mu.Lock()
defer e.mu.Unlock()
out := make([]EntryRow, 0, len(e.rows))
for _, r := range e.rows {
out = append(out, *r)
}
slices.SortFunc(out, func(a, b EntryRow) int {
switch {
case a.Fingerprint < b.Fingerprint:
return -1
case a.Fingerprint > b.Fingerprint:
return 1
}
return 0
})
return out
}
// ask reads fingerprint's entry once. A call that failed to reach the holder leaves the entry asked, with its reason;
// the holder's own answer that it holds none is `not-found`, whether the call gives it in the reply or, as a process's
// call does, as its error (busretry.Answered).
func (e *Entries) ask(_ context.Context, fingerprint string) {
raw, err := e.call(EntryVerb, seat.EntryInput{Fingerprint: fingerprint})
var row EntryRow
e.mu.Lock()
cur := e.rows[fingerprint]
if cur == nil {
e.mu.Unlock()
return
}
var holderSaid *busretry.Answered
switch {
case errors.As(err, &holderSaid):
// A process's call gives the holder's own answer as its error: it holds none.
cur.State, cur.Since, cur.Detail = EntryNotFound, e.now(), holderSaid.Words
case err != nil:
cur.Detail = err.Error()
e.mu.Unlock()
return
default:
answer, said, ok := buscalls.Unwrap(raw)
var a seat.EntryAnswer
switch {
case !ok:
cur.State, cur.Since, cur.Detail = EntryNotFound, e.now(), said
case json.Unmarshal(answer, &a) != nil || a.Entry.Module == "":
cur.Detail = errors.New("answered no entry: " + clipBytes(answer)).Error()
e.mu.Unlock()
return
default:
entry := a.Entry
cur.State, cur.Since, cur.Detail, cur.Entry = EntryAnswered, e.now(), "", &entry
}
}
row = *cur
e.mu.Unlock()
if e.Changed != nil {
e.Changed(row)
}
}