Files
mesh-delivery/modules/mesh-delivery-view/internal/view/tiers.go
T
jschoubben f8eea0000a V1: the view reads the H1 want, source, source-moved and held take-ins
A want counts as applied by its fingerprint and a motion event is keyed by
it; the want's newest and rule, and the state held back read from them, go
with the assigner's holds. A branch's source is {v, source, call, heads}
with no group, its source-moved is read by its source, and the delivered
event names no group. indexer_pending's held take-ins are said in the
tiers' pending words with their branch, source, why and since, naming no
module. The view reads no source stamp on a module. Its seat list, its
first-view tool answers and its manifest name no callers; its source invoke
reads call, not group.

Builds: design 47 H §737, §744, §750, §752, §764 (the gate's groups; the indexer's pending and groups; the assigner's holds; the callers lists); lead answers H-A-26, H-A-37, H-A-48, H-A-66, H-A-78, H-A-102, H-A-109 (hq 3433db0e)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:20:33 +01:00

282 lines
11 KiB
Go

package view
import (
"encoding/json"
"fmt"
"maps"
"slices"
"strconv"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate"
)
// The tiers of a source revision are a view, worked out at each call and never stored (novox/hq ADR 0603 §1, §6): the
// modules the revision moves, ordered by the module graph's ordering edges among them (a base, a provision or bus state
// awaited from another of them, a verb another of them serves whose edge the graph keeps, ADR 0614 §1), and for each module
// what it waits on now: its build key, each node's want (named by its edge: a verb, a reader capability) and have, and
// each provision it awaits on each node, with the rule and the words of the part that holds it, and the verb edges the
// graph leaves out. Nothing in the mesh waits on
// a tier; the tiers say where the revision stands. A node the watchman says is offline is named away and left out of
// what the revision waits on (ADR 0603 §7).
// TiersTool is the view's read tool of a source revision's tiers.
const TiersTool = "view_tiers"
// TiersMost is the most modules view_tiers answers (ADR 0603 §2); past it the answer says how many it left out.
const TiersMost = 500
// Tiers is a source revision's tiers: Revision the source revision (the gate's source key's revision), Modules how many
// modules it moves (each whose fingerprint last changed at it, meshcatalog.ModulesByModuleValue.FPSrc), Tiers those modules in order, the
// first tier waiting on none of the others. Cut says when the answer holds fewer than Modules, Graph why the module graph
// could not be read (then every module is in the first tier), Cycle a cycle among them (its modules form the last
// tier), and Away the nodes left out.
type Tiers struct {
// Branch is the watched branch whose newest source revision it is, when view_tiers was given no revision (A-173).
Branch string `json:"branch,omitempty"`
Revision uint64 `json:"revision"`
Modules int `json:"modules"`
Tiers [][]TierModule `json:"tiers"`
Cut string `json:"cut,omitempty"`
Graph string `json:"graph,omitempty"`
// Pending says each take-in the indexer holds (its branch, source, why and since; design 47 H-A-109), or why they could not
// be read, and why the parts' waits could not be read.
Pending string `json:"pending,omitempty"`
}
// TierModule is one module of a tier (design 47 G §512): its build (the fingerprint the difference says it is to run), the
// modules it is ordered after with the edge's kind, and each wait of its own now, from the parts' wait-held (no wait is a
// module that reached every node present).
type TierModule struct {
Module string `json:"module"`
// FP is the build.
FP string `json:"build,omitempty"`
After []TierAfter `json:"after,omitempty"`
Waits []TierWait `json:"waits,omitempty"`
}
// TierAfter is a module a module is ordered after, with the kind of the edge that orders it (design 47 G §512, §378).
type TierAfter struct {
Module string `json:"module"`
Kind string `json:"kind"`
}
// TierWait is one wait of a module, as the part that holds it said it (design 47 G §512, §498): the seat or module that holds it
// (Owner), its step, the node it is on, what it waits on, its bound, since when, and its own words.
type TierWait struct {
Owner string `json:"owner"`
Step string `json:"step"`
Node string `json:"node,omitempty"`
On string `json:"on,omitempty"`
Bound string `json:"bound,omitempty"`
Since time.Time `json:"since,omitzero"`
Words string `json:"words,omitempty"`
}
// BranchTiers is view_tiers' answer given no revision: the tiers of each watched branch's newest source revision, in branch
// order (design 47 G A-173).
type BranchTiers struct {
Branches []Tiers `json:"branches"`
}
// Newest works out the tiers of each watched branch's newest source revision, as the gate's verb source answers it.
func (r Reader) Newest() (BranchTiers, error) {
if r.Sources == nil {
return BranchTiers{}, fmt.Errorf("the gate's source cannot be read here: name the source revision")
}
revs, err := r.Sources()
if err != nil {
return BranchTiers{}, fmt.Errorf("the gate's source: %w", err)
}
out := BranchTiers{Branches: []Tiers{}}
for _, branch := range slices.Sorted(maps.Keys(revs)) {
if revs[branch] == 0 {
continue
}
t, err := r.Tiers(revs[branch])
if err != nil {
return BranchTiers{}, fmt.Errorf("%s: %w", branch, err)
}
t.Branch = branch
out.Branches = append(out.Branches, t)
}
if len(out.Branches) == 0 {
return BranchTiers{}, fmt.Errorf("the gate holds no source revision of any watched branch yet")
}
return out, nil
}
// Tiers works out the tiers of one source revision (not 0): the difference of the kept assignment revision that carries it
// against the one kept before it, as the assigner's verb difference answers it with its tiers and each change's after
// (design 47 G §512, §186, A-242). The view orders nothing itself.
func (r Reader) Tiers(revision uint64) (Tiers, error) {
if revision == 0 {
return Tiers{}, fmt.Errorf("name the source revision")
}
out := Tiers{Revision: revision}
from, to, err := r.revisionsOf(revision)
if err != nil {
return Tiers{}, err
}
var d meshwants.Difference
if from > 0 {
if d, err = r.Difference(from, to); err != nil {
return Tiers{}, fmt.Errorf("the assigner's difference of %d and %d: %w", from, to, err)
}
} else {
out.Graph = fmt.Sprintf("no assignment revision is kept before %d, so the difference names nothing", to)
}
// One module per name, in the highest tier any of its nodes is in; the changes name each module's build and what it is
// ordered after.
changes := map[string][]meshwants.Change{}
for _, c := range d.Changes {
changes[c.Module] = append(changes[c.Module], c)
}
tierOf := map[string]int{}
for i, tier := range d.Tiers {
for _, ref := range tier {
tierOf[ref.Module] = max(tierOf[ref.Module], i)
}
}
names := slices.Sorted(maps.Keys(changes))
out.Modules = len(names)
if len(names) > TiersMost {
out.Cut = fmt.Sprintf("the revision moves %d modules: the first %d by name are shown, %s and the %d after it are not",
len(names), TiersMost, names[TiersMost], len(names)-TiersMost-1)
names = names[:TiersMost]
}
r.heldTakeIns(&out)
waits := r.waitsHeld(&out)
for _, n := range names {
t := tierOf[n]
for len(out.Tiers) <= t {
out.Tiers = append(out.Tiers, nil)
}
tm := TierModule{Module: n}
seen := map[string]bool{}
for _, c := range changes[n] {
if tm.FP == "" {
tm.FP = c.To
}
for _, a := range c.After {
if k := a.Module + "\x00" + a.Kind; !seen[k] && a.Module != n {
seen[k] = true
tm.After = append(tm.After, TierAfter{Module: a.Module, Kind: a.Kind})
}
}
}
slices.SortFunc(tm.After, func(a, b TierAfter) int { return strings.Compare(a.Module+"\x00"+a.Kind, b.Module+"\x00"+b.Kind) })
tm.Waits = waits[n]
out.Tiers[t] = append(out.Tiers[t], tm)
}
compact := out.Tiers[:0]
for _, t := range out.Tiers {
if len(t) > 0 {
compact = append(compact, t)
}
}
out.Tiers = compact
return out, nil
}
// HeldTakeIn is one take-in the indexer holds, as its tool indexer_pending answers it (design 47 H §744, H-A-102): the seat
// mesh-catalog's form with since, when it was held.
type HeldTakeIn struct {
meshcatalog.TakeInPending
Since time.Time `json:"since"`
}
// HeldTakeIns is the answer of indexer_pending (design 47 H-A-102): every branch's held take-in.
type HeldTakeIns struct {
Held []HeldTakeIn `json:"held"`
}
// DecodeHeldTakeIns reads the answer of indexer_pending, refusing a held take-in with no branch, source or since.
func DecodeHeldTakeIns(raw []byte) (HeldTakeIns, error) {
var a HeldTakeIns
if err := json.Unmarshal(raw, &a); err != nil {
return HeldTakeIns{}, fmt.Errorf("not an answer of indexer_pending: %w", err)
}
for _, h := range a.Held {
if h.Branch == "" || h.Source == 0 || h.Since.IsZero() {
return HeldTakeIns{}, fmt.Errorf("indexer_pending names a held take-in with no branch, source or since: %+v", h)
}
}
return a, nil
}
// heldTakeIns says each take-in the indexer holds in out.Pending, read through its tool indexer_pending: its branch, source,
// why and since. A held take-in names no module, since its movers are known only once it is taken in (design 47 H-A-109).
func (r Reader) heldTakeIns(out *Tiers) {
if r.Pending == nil {
return
}
a, err := r.Pending()
if err != nil {
out.Pending = "the indexer's held take-ins cannot be read: " + err.Error()
return
}
var said []string
for _, h := range a.Held {
said = append(said, fmt.Sprintf("the indexer holds the take-in of source revision %d of %s since %s: %s",
h.Source, h.Branch, h.Since.UTC().Format(time.RFC3339), h.Why))
}
out.Pending = strings.Join(said, "; ")
}
// waitsHeld are the waits the parts hold, by module, from the view's own state waits (written from their wait-held and wait-ended,
// design 47 G §512, §376, A-242): each in the words its sayer gave. A state that cannot be read says so in out.Pending.
func (r Reader) waitsHeld(out *Tiers) map[string][]TierWait {
held := map[string][]TierWait{}
if r.WaitsState.Keys == nil || r.WaitsState.Get == nil {
return held
}
all, err := values(r.WaitsState)
if err != nil {
out.Pending += "the parts' waits cannot be read, so no module is named waiting on a part: " + err.Error()
return held
}
for _, key := range slices.Sorted(maps.Keys(all)) {
w, err := viewstate.ReadWait("", all[key])
if err != nil || w.Module == "" {
continue
}
held[w.Module] = append(held[w.Module], TierWait{Owner: w.Owner, Step: w.Step, Node: w.Node, On: w.On, Bound: w.Bound, Since: w.Since, Words: w.Words})
}
return held
}
// tiersRevision reads the tool's revision argument: a number, as JSON gives it or as text; 0 for the gate's newest.
func tiersRevision(v any) (uint64, error) {
switch x := v.(type) {
case nil:
return 0, nil
case float64:
if x < 0 || x != float64(uint64(x)) {
return 0, fmt.Errorf("the revision %v is no source revision", x)
}
return uint64(x), nil
case string:
if strings.TrimSpace(x) == "" {
return 0, nil
}
return strconv.ParseUint(strings.TrimSpace(x), 10, 64)
}
return 0, fmt.Errorf("the revision %v is no source revision", v)
}
// TiersOf is view_tiers' answer for its arguments.
func (r Reader) TiersOf(args map[string]any) (any, error) {
revision, err := tiersRevision(args["revision"])
if err != nil {
return nil, err
}
if revision == 0 {
return r.Newest()
}
return r.Tiers(revision)
}