VW2: the view's waits are the parts' wait-held, kept in its state waits

The view's process hears wait-held and wait-ended of every part (seats and modules; waits.go, manifest consumes) and keeps them in
its state waits under owner.step.node.module (viewstate/waits.go); view_tiers reads them through the tools bundle and names each
module's waits in the sayer's own words, {owner, step, node, on, bound, since, words} (tiers.go waitsHeld), beside the indexer's
pending revisions as the seat mesh-catalog's step take-in. No state of another module is read for a tier's waits.

Builds: design 47 G §512, §376, §498, A-242
This commit is contained in:
2026-11-12 09:19:18 +01:00
parent 316af50da3
commit 06e5980898
11 changed files with 326 additions and 320 deletions
@@ -434,6 +434,7 @@ func main() {
r := ownersRead(stdio.Ask, branches)
r.Builds, r.HavesState = read(stdio.State("mesh-delivery-builder.builds")), read(stdio.State("node-engine.have"))
r.ReachState = read(stdio.State("reach"))
r.WaitsState = read(stdio.State(viewstate.WaitsState))
r.SignersState = read(stdio.State("mesh-vault.signers"))
r.ConditionsState, r.AttemptsState = read(stdio.State(view.StatusConditionsState)), read(stdio.State(view.StatusAttemptsState))
r.PresenceState, r.StuckState = read(stdio.State(view.StatusPresenceState)), read(stdio.State(view.StatusStuckState))
@@ -4,22 +4,16 @@ import (
"encoding/json"
"errors"
"fmt"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-view/internal/view"
"reflect"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshwatchdogsclient"
"git.novox.be/novox/mesh-contracts/provisioning/go/clients/meshprovisionerclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-indexer/takein"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate"
"mesh-delivery-view/internal/view"
)
// encoded is v as its contract's encoder writes it, failing the test when it refuses.
@@ -34,39 +28,17 @@ func encoded(t *testing.T, v []byte, err error) string {
// short is a fingerprint as the assigner's words shorten it.
func short(fp string) string { return fp[:len("src2:")+12] }
// tiersToolSaysEachModulesWait: view_tiers orders a source revision's modules by the module graph and names each one's
// wait (ADR 0603 §6): a consumer after its provider, held by the assigner's provision rule and its provision not provided;
// a module whose build waits for a package; a provider with no wait; a node offline named away; older modules left out.
// tiersToolSaysEachModulesWait: view_tiers reads a source revision's tiers from the assigner's difference of the kept revision
// carrying it against the one before (design 47 G §512, A-242) and names each module's waits as the parts said them in
// wait-held (the view's state waits), in the sayer's own words, beside the indexer's pending revisions.
func tiersToolSaysEachModulesWait(t *testing.T) {
fp := func(c string) string { return "src2:" + strings.Repeat(c, 64) }
manifest := strings.Repeat("d", 64)
node := func(g graph.Node) string {
b, err := graph.Encode(g)
return encoded(t, b, err)
}
build := func(b builds.BuilderBuild) string {
v, err := builds.EncodeBuilderBuild(b)
return encoded(t, v, err)
}
want := func(w meshwantsclient.Want) string {
v, err := meshwantsclient.EncodeWant(w)
return encoded(t, v, err)
}
have := func(h nodeengine.HaveByNodeModuleValue) string {
v, err := nodeengineclient.EncodeHave(h)
return encoded(t, v, err)
}
key := func(k string, err error) string {
if err != nil {
t.Fatal(err)
}
return k
}
since := time.Date(2026, 11, 3, 16, 40, 0, 0, time.UTC)
r := fake{}.reader()
// The tiers are the assigner's difference of the kept revision carrying source revision 9 against the one before it (design
// 47 G §512, A-242): db and lib first, web after db by its provisioning edge; the view orders nothing.
ref := func(m string) meshwants.NodeEntryRef { return meshwants.NodeEntryRef{Node: "ace", Module: m, Digest: "sha256:" + m} }
// db and lib first, web after db by its provisioning edge; the view orders nothing.
ref := func(m string) meshwants.NodeEntryRef {
return meshwants.NodeEntryRef{Node: "ace", Module: m, Digest: "sha256:" + m}
}
kept := map[int64]meshwants.AssignmentRevision{
3: {Revision: 3, Catalogs: []meshwants.CatalogOf{{Branch: "release", Revision: 2, Source: 5}}},
4: {Revision: 4, Catalogs: []meshwants.CatalogOf{{Branch: "release", Revision: 3, Source: 8}}},
@@ -92,44 +64,33 @@ func tiersToolSaysEachModulesWait(t *testing.T) {
}
return meshwants.Difference{}, fmt.Errorf("no difference of %d and %d", from, to)
}
r.GraphState = fake{
"db": node(graph.Node{FP: fp("a"), Repository: "novox/mesh-catalog", Provides: []string{"database"}}),
"web": node(graph.Node{FP: fp("b"), Repository: "novox/mesh-catalog", Requires: []string{"database"}, Awaits: []string{"database"}}),
"lib": node(graph.Node{FP: fp("c"), Repository: "novox/mesh-catalog"}),
}.reader().State
r.Builds = fake{
key(builds.BuilderBuildKey("db", fp("a"))): build(builds.BuilderBuild{State: builds.BuildDone, Manifest: manifest}),
key(builds.BuilderBuildKey("web", fp("b"))): build(builds.BuilderBuild{State: builds.BuildDone, Manifest: manifest}),
key(builds.BuilderBuildKey("lib", fp("c"))): build(builds.BuilderBuild{State: builds.BuildQueued, Waits: "@novox/x@1.2.0"}),
}.reader().State
r.WantsState = fake{
key(meshwantsclient.WantKey("ace", "db")): want(meshwantsclient.Want{Fp: fp("a"), Self: true}),
key(meshwantsclient.WantKey("ace", "web")): want(meshwantsclient.Want{Self: true, Fp: fp("f"), Newest: fp("b"), Rule: meshwantsclient.RuleProvisions, Words: "the provision ace.web.database of web on ace is asked, not provided"}),
key(meshwantsclient.WantKey("g14", "web")): want(meshwantsclient.Want{Self: true, Fp: fp("f"), Newest: fp("b"), Rule: meshwantsclient.RuleCanary, Words: "the canary"}),
}.reader().State
r.WantsState.History = func(string) ([]view.Revision, error) { return []view.Revision{{At: since}}, nil }
r.HavesState = fake{key(nodeengineclient.HaveKey("ace", "db")): have(nodeengine.HaveByNodeModuleValue{Fp: fp("a"), Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})}.reader().State
p, err := meshprovisionerclient.Encode(meshprovisionerclient.Provision{Provision: "database", Consumer: meshprovisionerclient.End{Module: "web", Node: "ace"},
Provider: meshprovisionerclient.End{Module: "db", Node: "ace"}, State: meshprovisionerclient.Asked, Why: "the build db runs does not offer it", At: since})
r.ProvisionsState = fake{key(meshprovisionerclient.Key("ace", "web", "database", "")): encoded(t, p, err)}.reader().State
off, err := meshwatchdogsclient.EncodeNodePresence(meshwatchdogsclient.NodePresence{Online: false})
r.PresenceState = fake{key(meshwatchdogsclient.PresenceNodeKey("g14")): encoded(t, off, err)}.reader().State
// The waits the parts said, as the view's process keeps them: web's delivery wait by the assigner, lib's toolchain wait by
// the builder; db holds none. Their words are the sayers' own.
wait := func(w viewstate.Wait) string {
raw, err := json.Marshal(w)
if err != nil {
t.Fatal(err)
}
return string(raw)
}
webWait := viewstate.Wait{Owner: "mesh-wants", Step: "delivery", Node: "ace", Module: "web", Part: "db", Machines: []string{"g14"}, Since: since,
Bound: "60m", Words: "waiting for delivery of db to g14"}
libWait := viewstate.Wait{Owner: "mesh-delivery-builder", Step: "building", Module: "lib", On: "toolchain:go@1.27", Since: since, Words: "the toolchain go 1.27 is not agreed yet"}
r.WaitsState = fake{webWait.Key(): wait(webWait), libWait.Key(): wait(libWait)}.reader().State
out, err := run(t, r, view.TiersTool, map[string]any{"revision": float64(9)})
got, _ := out.(view.Tiers)
if err != nil || got.Revision != 9 || got.Modules != 3 || len(got.Tiers) != 2 || !reflect.DeepEqual(got.Away, []string{"g14"}) || got.Graph != "" {
if err != nil || got.Revision != 9 || got.Modules != 3 || len(got.Tiers) != 2 || got.Graph != "" {
t.Fatalf("view_tiers 9 = %+v, %v", out, err)
}
first := fmt.Sprint(got.Tiers[0])
if len(got.Tiers[0]) != 2 || got.Tiers[0][0].Module != "db" || len(got.Tiers[0][0].Waits) != 0 || got.Tiers[0][1].Module != "lib" ||
len(got.Tiers[0][1].Waits) != 1 || !strings.Contains(got.Tiers[0][1].Waits[0].Words, "waiting for the package @novox/x@1.2.0") {
t.Errorf("the first tier = %s, want db with no wait and lib's build waiting for its package", first)
if len(got.Tiers[0]) != 2 || got.Tiers[0][0].Module != "db" || got.Tiers[0][0].FP != fp("a") || len(got.Tiers[0][0].Waits) != 0 || got.Tiers[0][1].Module != "lib" ||
!reflect.DeepEqual(got.Tiers[0][1].Waits, []view.TierWait{{Owner: "mesh-delivery-builder", Step: "building", On: "toolchain:go@1.27", Since: since, Words: "the toolchain go 1.27 is not agreed yet"}}) {
t.Errorf("the first tier = %+v, want db with no wait and lib's toolchain wait in its sayer's words", got.Tiers[0])
}
web := got.Tiers[1][0]
if web.Module != "web" || !reflect.DeepEqual(web.After, []view.TierAfter{{Module: "db", Kind: "provisioning"}}) || len(web.Waits) != 2 ||
web.Waits[0].Edge != "want" || web.Waits[0].Node != "ace" || web.Waits[0].Rule != meshwantsclient.RuleProvisions || !web.Waits[0].Since.Equal(since) ||
web.Waits[1].Edge != "provision database" || !strings.Contains(web.Waits[1].Words, "asked: the build db runs does not offer it") {
t.Errorf("web = %+v, want after db, held on ace by the provision rule and its provision asked (g14 is away)", web)
if web.Module != "web" || !reflect.DeepEqual(web.After, []view.TierAfter{{Module: "db", Kind: "provisioning"}}) ||
!reflect.DeepEqual(web.Waits, []view.TierWait{{Owner: "mesh-wants", Step: "delivery", Node: "ace", Bound: "60m", Since: since, Words: "waiting for delivery of db to g14"}}) {
t.Errorf("web = %+v, want after db, waiting for the delivery of db in the assigner's words", web)
}
// ADR 0633 §5 (1585/T24): a module the indexer holds back, read through indexer_pending, waits on the edge take-in from the
// wait's since; a held module the revision does not move is named in the first tier with that wait alone, a group's wait
@@ -146,18 +107,18 @@ func tiersToolSaysEachModulesWait(t *testing.T) {
t.Fatalf("view_tiers with waits = %+v, %v", out, err)
}
web = held.Tiers[1][0]
if last := web.Waits[len(web.Waits)-1]; last.Edge != view.TakeInEdge || !last.Since.Equal(heldSince) || !strings.Contains(last.Words, "src2:abc") {
if last := web.Waits[len(web.Waits)-1]; last.Step != view.TakeInStep || !last.Since.Equal(heldSince) || !strings.Contains(last.Words, "src2:abc") {
t.Errorf("web = %+v, want its last wait on the edge take-in since %s", web, heldSince)
}
if lib := held.Tiers[0][1]; lib.Module != "lib" || lib.Waits[len(lib.Waits)-1].Edge != view.TakeInEdge || !strings.Contains(lib.Waits[len(lib.Waits)-1].Words, "group feat") {
if lib := held.Tiers[0][1]; lib.Module != "lib" || lib.Waits[len(lib.Waits)-1].Step != view.TakeInStep || !strings.Contains(lib.Waits[len(lib.Waits)-1].Words, "group feat") {
t.Errorf("lib = %+v, want its last wait the group's", lib)
}
if nm := held.Tiers[0][len(held.Tiers[0])-1]; nm.Module != "newmod" || len(nm.Waits) != 1 || nm.Waits[0].Edge != view.TakeInEdge {
if nm := held.Tiers[0][len(held.Tiers[0])-1]; nm.Module != "newmod" || len(nm.Waits) != 1 || nm.Waits[0].Step != view.TakeInStep {
t.Errorf("the first tier = %+v, want newmod, which the revision does not move, named with its take-in wait alone", held.Tiers[0])
}
r.Pending = func() (takein.PendingAnswer, error) { return takein.PendingAnswer{}, errors.New("no answer") }
if out, err = run(t, r, view.TiersTool, map[string]any{"revision": float64(9)}); err != nil || !strings.Contains(out.(view.Tiers).Pending, "no answer") ||
strings.Contains(fmt.Sprint(out.(view.Tiers).Tiers), view.TakeInEdge) {
strings.Contains(fmt.Sprint(out.(view.Tiers).Tiers), view.TakeInStep) {
t.Errorf("view_tiers with no answer of indexer_pending = %+v, %v", out, err)
}
r.Pending = nil
@@ -178,32 +139,6 @@ func tiersToolSaysEachModulesWait(t *testing.T) {
if !asked["seat:mesh-delivery.source release"] || !asked["seat:mesh-delivery.source beta"] {
t.Errorf("the gate's verb source was asked %v, want once per watched branch", asked)
}
// ADR 0614 §2-§5: a want held on a verb, a reader capability or bus state is named by its edge; bus state is no
// provisioner key (none is ever made for it), so a module asking it shows no provision wait of it; and each verb edge
// the graph leaves out on a cycle is named.
r.GraphState = fake{
"db": node(graph.Node{FP: fp("a"), Repository: "novox/mesh-catalog", Provides: []string{"database"}}),
"web": node(graph.Node{FP: fp("b"), Repository: "novox/mesh-catalog", Requires: []string{"database", graph.BusState}, Awaits: []string{"database", graph.BusState},
Invokes: []string{"seat:x.v", "db.loop"}, LeftOut: []string{"db.loop"}}),
"lib": node(graph.Node{FP: fp("c"), Repository: "novox/mesh-catalog"}),
}.reader().State
for words, edge := range map[string]string{
graph.VerbWaitWords("seat:x.v", "web", "ace"): "verb seat:x.v",
graph.ReaderWaitWords("ace", []string{"tool-runner"}, "web", short(fp("b"))): "reader capability tool-runner",
"the provision ace.web.database of web on ace is asked, not provided": "want",
} {
r.WantsState = fake{key(meshwantsclient.WantKey("ace", "web")): want(meshwantsclient.Want{Self: true, Fp: fp("f"), Newest: fp("b"), Rule: meshwantsclient.RuleProvisions, Words: words})}.reader().State
out, err := run(t, r, view.TiersTool, map[string]any{"revision": float64(9)})
got, _ := out.(view.Tiers)
if err != nil || len(got.Tiers) != 2 {
t.Fatalf("view_tiers 9 = %+v, %v", out, err)
}
web := got.Tiers[1][0]
if len(web.Waits) != 2 || web.Waits[0].Edge != edge || web.Waits[1].Edge != "provision database" ||
!reflect.DeepEqual(web.LeftOut, []string{"db.loop"}) {
t.Errorf("web held by %q = %+v, want its want named %s, no wait for a bus-state key and db.loop left out", words, web, edge)
}
}
// No revision kept before the one carrying the source: said, and no module named; past 500 modules the answer says it is cut
// short.
delete(kept, 4)
@@ -127,7 +127,11 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
return err
}
defer calls.Close()
reader := &views.ProcessReader{Module: viewstate.ViewModule, Call: calls.Call, Logf: logger.Printf}
// The module's one pull of its durable consumer: the reader's views events and the waits' events are handlers on it, and it is
// started once, after both (design 47 G §512, A-242).
hub := process.NewEventHub(logger.Printf)
defer hub.Stop()
reader := &views.ProcessReader{Module: viewstate.ViewModule, Call: calls.Call, Logf: logger.Printf, Hub: hub}
writer, err := findingWriter(ctx, cred, conn, js, calls.State("findings"), logger.Printf)
if err != nil {
return fmt.Errorf("the view's finding writer: %w", err)
@@ -162,6 +166,12 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
modules := &catalogModules{ctx: ctx, branches: branches, sources: sources, model: model, logger: logger, applied: map[string]bool{}}
branches.Changed = modules.changed
reader.Start(ctx, js, cred, statusBucket)
if err := hearWaits(ctx, hub, js, logger.Printf); err != nil {
return fmt.Errorf("the waits' events are not handled: %w", err)
}
if err := hub.StartUntilBound(ctx, js, cred, nil, nil); err != nil {
logger.Printf("the consumer is not heard yet (tried again until it is): %v", err)
}
go func() {
select {
case <-branches.Registrations.Follower.Ready():
@@ -0,0 +1,94 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate"
"git.novox.be/novox/mesh-sdk/go/process"
"github.com/nats-io/nats.go/jetstream"
)
// The events of a wait, said by every part that holds one (the seats mesh-wants, node-engine, mesh-pipeline-runner and
// mesh-grants on their subjects, the builder and the others on their module's): the view keeps them in its state waits
// (design 47 G §512, §376, A-242).
const (
eventWaitHeld = "wait-held"
eventWaitEnded = "wait-ended"
)
// waitPatterns are the subjects the view's hub handles for the waits: a seat's and a module's, each with and without the
// node or key the sayer adds after the event's name.
func waitPatterns() []string {
var out []string
for _, prefix := range []string{"mesh.seat.*.event.", "mesh.mod.*.event."} {
for _, event := range []string{eventWaitHeld, eventWaitEnded} {
out = append(out, prefix+event, prefix+event+".>")
}
}
return out
}
// applyWait keeps one wait event: wait-held puts the wait under its key, wait-ended deletes it. The owner is the seat or module
// of the subject unless the body names one.
func applyWait(subject string, body []byte, put func(key string, value []byte) error, del func(key string) error) error {
parts := strings.Split(subject, ".")
if len(parts) < 5 || parts[0] != "mesh" || (parts[1] != "seat" && parts[1] != "mod") || parts[3] != "event" {
return fmt.Errorf("%s is no wait's subject", subject)
}
w, err := viewstate.ReadWait(parts[2], body)
if err != nil {
return fmt.Errorf("%s: %w", subject, err)
}
switch parts[4] {
case eventWaitHeld:
raw, err := json.Marshal(w)
if err != nil {
return err
}
return put(w.Key(), raw)
case eventWaitEnded:
return del(w.Key())
}
return fmt.Errorf("%s is no wait's subject", subject)
}
// hearWaits registers the waits' handlers on the process's hub; each keeps its event in the state waits and acknowledges it, and
// one that could not be kept is not acknowledged, so the bus gives it again.
func hearWaits(ctx context.Context, hub *process.EventHub, js jetstream.JetStream, logf func(string, ...any)) error {
kv := func() (jetstream.KeyValue, error) { return js.KeyValue(ctx, viewstate.WaitsBucket) }
put := func(key string, value []byte) error {
b, err := kv()
if err != nil {
return err
}
_, err = b.Put(ctx, key, value)
return err
}
del := func(key string) error {
b, err := kv()
if err != nil {
return err
}
if err = b.Delete(ctx, key); errors.Is(err, jetstream.ErrKeyNotFound) {
return nil
}
return err
}
for _, pattern := range waitPatterns() {
if err := hub.Handle(pattern, func(m jetstream.Msg) {
if err := applyWait(m.Subject(), m.Data(), put, del); err != nil {
logf("the wait event %s is not kept (the bus gives it again): %v", m.Subject(), err)
_ = m.Nak()
return
}
_ = m.Ack()
}); err != nil {
return err
}
}
return nil
}
@@ -0,0 +1,36 @@
package main
import (
"strings"
"testing"
"git.novox.be/novox/mesh-sdk/go/process"
"github.com/nats-io/nats.go/jetstream"
)
func TestWaitEventsAreKeptUnderTheirKeyAndEnded(t *testing.T) {
kept := map[string]string{}
put := func(k string, v []byte) error { kept[k] = string(v); return nil }
del := func(k string) error { delete(kept, k); return nil }
held := `{"step":"delivery","module":"web","node":"ace","part":"db","machines":["g14"],"since":"2026-11-12T01:00:00Z","words":"waiting for delivery of db to g14"}`
if err := applyWait("mesh.seat.mesh-wants.event.wait-held", []byte(held), put, del); err != nil || len(kept) != 1 ||
!strings.Contains(kept["mesh-wants.delivery.ace.web"], "waiting for delivery of db to g14") {
t.Fatalf("kept %v, %v", kept, err)
}
if err := applyWait("mesh.mod.mesh-delivery-builder.event.wait-held.web.fp", []byte(`{"step":"building","module":"web","on":"toolchain:go@1","since":"2026-11-12T01:00:00Z"}`), put, del); err != nil || len(kept) != 2 {
t.Fatalf("a module's wait: %v, %v", kept, err)
}
if err := applyWait("mesh.seat.mesh-wants.event.wait-ended", []byte(`{"step":"delivery","module":"web","node":"ace","how":"ran","since":"2026-11-12T01:00:00Z"}`), put, del); err != nil || len(kept) != 1 {
t.Fatalf("ended: %v, %v", kept, err)
}
if err := applyWait("mesh.seat.mesh-wants.event.wait-held", []byte(`{"module":"web"}`), put, del); err == nil {
t.Error("a wait with no step was kept")
}
// None of the patterns overlaps another: the hub gives a message one taker.
hub := process.NewEventHub(func(string, ...any) {})
for _, p := range waitPatterns() {
if err := hub.Handle(p, func(jetstream.Msg) {}); err != nil {
t.Fatalf("the pattern %s overlaps another: %v", p, err)
}
}
}
@@ -56,6 +56,7 @@ type Reader struct {
DifferencesState StateRead // the assigner's differences
HavesState StateRead // the node-engine's haves
ReachState StateRead // the view's own reach (ADR 0556)
WaitsState StateRead // the view's own waits: the parts' wait-held (design 47 G §512, A-242)
// HeardState is the FORGE messages the indexer handled (issue 1126 note 76); unset reads none.
HeardState StateRead
// SignersState is the vault's public signing halves (ADR 0550 §2); unset reads none.
+41 -216
View File
@@ -1,7 +1,6 @@
package view
import (
"encoding/json"
"fmt"
"maps"
"slices"
@@ -9,15 +8,9 @@ import (
"strings"
"time"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshwatchdogsclient"
"git.novox.be/novox/mesh-contracts/provisioning/go/clients/meshprovisionerclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"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-indexer/takein"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"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
@@ -48,21 +41,19 @@ type Tiers struct {
Tiers [][]TierModule `json:"tiers"`
Cut string `json:"cut,omitempty"`
Graph string `json:"graph,omitempty"`
Away []string `json:"away,omitempty"`
// Pending says why the indexer's waits could not be read, so no module is named held by its revision's indexer (ADR 0633 §5).
Pending string `json:"pending,omitempty"`
}
// TierModule is one module of a tier: its fingerprint, the modules of the same revision it waits for (After), each
// wait of its own now (no wait is a module that reached every node present), and the verbs it invokes whose edge the
// module graph leaves out on a cycle, so nothing waits on them (LeftOut, ADR 0614 §3).
// 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 and the indexer's
// pending revisions (no wait is a module that reached every node present).
type TierModule struct {
Module string `json:"module"`
// FP is the build: the fingerprint the difference says the module is to run.
FP string `json:"build,omitempty"`
After []TierAfter `json:"after,omitempty"`
Waits []TierWait `json:"waits,omitempty"`
LeftOut []string `json:"left-out,omitempty"`
// 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).
@@ -71,16 +62,17 @@ type TierAfter struct {
Kind string `json:"kind"`
}
// TierWait is one thing a module waits on: the edge (build, have, provision <name>, or for a want held back want, verb
// <verb>, reader capability <capabilities> or bus state as the assigner's words name it, ADR 0614 §2, §4, §5), the node
// it waits on (none for its build), the assigner's rule for a want held back, the part's words and since when, where the
// part says it.
// 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. The pending revision of the
// indexer is Owner mesh-catalog and Step take-in.
type TierWait struct {
Edge string `json:"edge"`
Owner string `json:"owner"`
Step string `json:"step"`
Node string `json:"node,omitempty"`
Rule int `json:"rule,omitempty"`
Words string `json:"words"`
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
@@ -155,18 +147,7 @@ func (r Reader) Tiers(revision uint64) (Tiers, error) {
len(names), TiersMost, names[TiersMost], len(names)-TiersMost-1)
names = names[:TiersMost]
}
gr := graph.Graph{}
if raws, err := values(r.GraphState); err == nil {
for key, raw := range raws {
if n, err := graph.Decode(raw); err == nil {
gr[key] = n
}
}
}
away := r.away()
out.Away = slices.Sorted(maps.Keys(away))
wants, _ := values(r.WantsState)
provided, perr := values(r.ProvisionsState)
waits := r.waitsHeld(&out)
held, heldAll := r.heldBack(&out)
in := map[string]bool{}
for _, n := range names {
@@ -177,7 +158,7 @@ func (r Reader) Tiers(revision uint64) (Tiers, error) {
for len(out.Tiers) <= t {
out.Tiers = append(out.Tiers, nil)
}
tm := TierModule{Module: n, LeftOut: gr[n].LeftOut}
tm := TierModule{Module: n}
seen := map[string]bool{}
for _, c := range changes[n] {
if tm.FP == "" {
@@ -191,7 +172,7 @@ func (r Reader) Tiers(revision uint64) (Tiers, error) {
}
}
slices.SortFunc(tm.After, func(a, b TierAfter) int { return strings.Compare(a.Module+"\x00"+a.Kind, b.Module+"\x00"+b.Kind) })
tm.Waits = r.waitsOf(n, meshcatalog.ModulesByModuleValue{Fp2: tm.FP}, gr[n], wants, provided, perr, away)
tm.Waits = waits[n]
if w, ok := held[n]; ok {
tm.Waits = append(tm.Waits, w)
}
@@ -218,8 +199,12 @@ func (r Reader) Tiers(revision uint64) (Tiers, error) {
return out, nil
}
// TakeInEdge is the edge of a wait on the indexer a source revision or a group is held for (ADR 0633 §5).
const TakeInEdge = "take-in"
// TakeInStep and TakeInOwner are the step and the owner of a wait on the indexer a source revision or a group is held for
// (ADR 0633 §5, design 47 G §512): the pending revision's wait is the seat mesh-catalog's step take-in.
const (
TakeInStep = "take-in"
TakeInOwner = "mesh-catalog"
)
// heldBack are the modules the indexer holds back, by module, each with its wait, read through the indexer's tool
// indexer_pending (ADR 0633 §5), and the same modules sorted. A tool that cannot be asked says so in out.Pending.
@@ -242,193 +227,33 @@ func (r Reader) heldBack(out *Tiers) (map[string]TierWait, []string) {
}
for _, module := range w.Holds {
if _, ok := held[module]; !ok { // the oldest wait names it
held[module] = TierWait{Edge: TakeInEdge, Words: words, Since: w.Since}
held[module] = TierWait{Owner: TakeInOwner, Step: TakeInStep, Words: words, Since: w.Since}
}
}
}
return held, slices.Sorted(maps.Keys(held))
}
// away are the nodes the watchman's presence says are offline.
func (r Reader) away() map[string]bool {
out := map[string]bool{}
presence, err := values(r.PresenceState)
// 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 {
return out
out.Pending += "the parts' waits cannot be read, so no module is named waiting on a part: " + err.Error()
return held
}
for key, raw := range presence {
node, part, _, err := meshwatchdogsclient.ParsePresenceKey(key)
if err != nil || part != "" {
for _, key := range slices.Sorted(maps.Keys(all)) {
w, err := viewstate.ReadWait("", all[key])
if err != nil || w.Module == "" {
continue
}
if p, err := meshwatchdogsclient.DecodeNodePresence(raw); err == nil && !p.Online {
out[node] = true
}
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 out
}
// waitsOf is what module m waits on now: its build at its fingerprint, then on each node present that wants it, its want,
// its have, and each provision its graph node awaits.
func (r Reader) waitsOf(module string, m meshcatalog.ModulesByModuleValue, g graph.Node, wants, provided map[string]json.RawMessage,
perr error, away map[string]bool) []TierWait {
var out []TierWait
if m.Fp2 == "" {
return []TierWait{{Edge: "build", Words: "it has no fingerprint, so nothing is built: " + m.None2}}
}
if w, ok := r.buildWait(module, m.Fp2); ok {
out = append(out, w)
}
var nodes []string
for key := range wants {
node, mod, err := meshwantsclient.ParseWantKey(key)
if err == nil && mod == module {
nodes = append(nodes, node)
}
}
slices.Sort(nodes)
for _, node := range nodes {
if away[node] {
continue
}
w, err := meshwantsclient.DecodeWant(wants[mustWantKey(node, module)])
if err != nil || w.Removed {
continue
}
if w.Fp != m.Fp2 {
words := w.Words
if words == "" {
words = "the want names " + short(w.Fp) + ", not " + short(m.Fp2)
}
edge := graph.EdgeOfWords(w.Words)
if edge == "" {
edge = "want"
}
out = append(out, TierWait{Edge: edge, Node: node, Rule: int(w.Rule), Words: words, Since: r.since(r.WantsState, mustWantKey(node, module))})
} else if hw, ok := r.haveWait(node, module, m.Fp2); ok {
out = append(out, hw)
}
for _, a := range g.Awaits {
if a == graph.BusState {
// Bus state is offered with no credential of a consumer's own, so the provisioner keys nothing for it: its wait is
// the assigner's held want alone, named bus state from its words (ADR 0614 §5).
continue
}
out = append(out, provisionWaits(node, module, a, provided, perr)...)
}
}
return out
}
func mustWantKey(node, module string) string {
k, _ := meshwantsclient.WantKey(node, module)
return k
}
// buildWait is the wait of the build key <module>.<fp>, none when it is done.
func (r Reader) buildWait(module, fp string) (TierWait, bool) {
key, err := builds.BuilderBuildKey(module, fp)
if err != nil || r.Builds.Get == nil {
return TierWait{Edge: "build", Words: "the builder's builds cannot be read here"}, true
}
raw, err := r.Builds.Get(key)
switch {
case err != nil:
return TierWait{Edge: "build", Words: "the build key " + key + " cannot be read: " + err.Error()}, true
case raw == nil:
return TierWait{Edge: "build", Words: "the builder holds no build of " + short(fp) + " yet"}, true
}
b, err := builds.DecodeBuilderBuild(raw)
if err != nil {
return TierWait{Edge: "build", Words: "the build key " + key + " does not read: " + err.Error()}, true
}
switch b.State {
case builds.BuildDone:
return TierWait{}, false
case builds.BuildFailed:
return TierWait{Edge: "build", Words: "the build of " + short(fp) + " failed: " + b.Error}, true
}
words := "the build of " + short(fp) + " is " + b.State
if b.Waits != "" {
words += ", waiting for the package " + b.Waits
}
if b.Step != "" {
words += ": " + b.Step
}
return TierWait{Edge: "build", Words: words, Since: r.since(r.Builds, key)}, true
}
// haveWait is the wait of node's have of module at fp, none when it runs fp healthy.
func (r Reader) haveWait(node, module, fp string) (TierWait, bool) {
key, err := nodeengineclient.HaveKey(node, module)
if err != nil || r.HavesState.Get == nil {
return TierWait{}, false
}
raw, err := r.HavesState.Get(key)
if err != nil || raw == nil {
return TierWait{Edge: "have", Node: node, Words: node + " has not yet said what it runs of " + module}, true
}
h, err := nodeengineclient.DecodeHave(raw)
if err != nil {
return TierWait{Edge: "have", Node: node, Words: "its have does not read: " + err.Error()}, true
}
if h.Fp == fp && h.Phase == nodeengineclient.PhaseRunning && h.Health == nodeengineclient.HealthOK {
return TierWait{}, false
}
words := fmt.Sprintf("%s runs %s, %s", node, short(h.Fp), h.Phase)
if h.Health != "" {
words += ", health " + string(h.Health)
}
if h.Detail != "" {
words += ": " + h.Detail
}
return TierWait{Edge: "have", Node: node, Words: words, Since: r.since(r.HavesState, key)}, true
}
// provisionWaits are the waits of the provision a that module awaits on node: none once every key of it is provided.
func provisionWaits(node, module, a string, provided map[string]json.RawMessage, perr error) []TierWait {
edge := "provision " + a
if perr != nil {
return []TierWait{{Edge: edge, Node: node, Words: "the provisioner's keys cannot be read: " + perr.Error()}}
}
prefix, _ := meshprovisionerclient.Key(node, module, a, "")
var out []TierWait
found := false
for _, key := range slices.Sorted(maps.Keys(provided)) {
if key != prefix && !strings.HasPrefix(key, prefix+".") {
continue
}
found = true
p, err := meshprovisionerclient.Decode(provided[key])
if err != nil {
out = append(out, TierWait{Edge: edge, Node: node, Words: "the provision key " + key + " does not read: " + err.Error()})
continue
}
if p.State == meshprovisionerclient.Provided {
continue
}
words := "the provision " + key + " is " + p.State
if p.Why != "" {
words += ": " + p.Why
}
out = append(out, TierWait{Edge: edge, Node: node, Words: words, Since: p.At})
}
if !found {
out = append(out, TierWait{Edge: edge, Node: node, Words: "the provisioner holds no key of " + a + " for " + module + " on " + node + " yet"})
}
return out
}
// since is when key's value was written, from the state's history, or zero when it cannot say.
func (r Reader) since(s StateRead, key string) time.Time {
if s.History == nil {
return time.Time{}
}
revs, err := s.History(key)
if err != nil || len(revs) == 0 {
return time.Time{}
}
return revs[len(revs)-1].At
return held
}
// tiersRevision reads the tool's revision argument: a number, as JSON gives it or as text; 0 for the gate's newest.
+4 -2
View File
@@ -173,7 +173,9 @@ func TestManifestIsTakenAndReadsOnly(t *testing.T) { // 1134/AC7
t.Errorf("version = %q, want 0.1", m.Version)
}
if want := []string{"mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-delivery-assigner.views.assignments", "mesh-delivery-assigner.views.wants",
"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved", "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed", "mesh-delivery-indexer.views.candidates", "mesh-delivery-indexer.views.taken", "mesh-delivery-teller.views.answers"}; !reflect.DeepEqual(m.Consumes, want) {
"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved", "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed", "mesh-delivery-indexer.views.candidates", "mesh-delivery-indexer.views.taken", "mesh-delivery-teller.views.answers",
"mesh-wants.wait-held", "mesh-wants.wait-ended", "node-engine.wait-held", "node-engine.wait-ended", "mesh-pipeline-runner.wait-held", "mesh-pipeline-runner.wait-ended",
"mesh-grants.wait-held", "mesh-grants.wait-ended", "mesh-delivery-builder.wait-held", "mesh-delivery-builder.wait-ended"}; !reflect.DeepEqual(m.Consumes, want) { // design 47 G §512, A-242: every part's wait-held and wait-ended
t.Errorf("consumes = %v, want %v", m.Consumes, want)
}
// The one event the view says: a source revision is delivered (1906/D9, ADR 0539 §17), derived by it from the wants and the haves.
@@ -187,7 +189,7 @@ func TestManifestIsTakenAndReadsOnly(t *testing.T) { // 1134/AC7
// The states the view writes: the operator's answers to the asks that need no proof (ADR 0528 clause 6, 1297/B9), which the
// teller reads, and how far each repository reached (ADR 0556 clause 2, issue 1280), which the gate reads.
// Its first views of the owners' states and the finding of one unanswered past its bound (ADR 0615 §6).
if want := []state{{Name: "answers", History: 5}, {Name: "reach", History: 1}, {Name: "first-views", History: 1}, {Name: "view-marks", History: 1}}; !reflect.DeepEqual(m.State, want) {
if want := []state{{Name: "answers", History: 5}, {Name: "reach", History: 1}, {Name: "waits", History: 1}, {Name: "first-views", History: 1}, {Name: "view-marks", History: 1}}; !reflect.DeepEqual(m.State, want) {
t.Errorf("state = %+v, want %+v", m.State, want)
}
if _, ok := m.OwnSecrets["broker"]; !ok || len(m.OwnSecrets) != 1 {
+15 -1
View File
@@ -49,6 +49,10 @@
"name": "reach",
"history": 1
},
{
"name": "waits",
"history": 1
},
{
"name": "first-views",
"history": 1
@@ -70,7 +74,17 @@
"mesh-catalog.seat-definition-removed",
"mesh-delivery-indexer.views.candidates",
"mesh-delivery-indexer.views.taken",
"mesh-delivery-teller.views.answers"
"mesh-delivery-teller.views.answers",
"mesh-wants.wait-held",
"mesh-wants.wait-ended",
"node-engine.wait-held",
"node-engine.wait-ended",
"mesh-pipeline-runner.wait-held",
"mesh-pipeline-runner.wait-ended",
"mesh-grants.wait-held",
"mesh-grants.wait-ended",
"mesh-delivery-builder.wait-held",
"mesh-delivery-builder.wait-ended"
],
"invokes": [
"mesh-delivery-assigner.assigner_read_asks",
@@ -0,0 +1,69 @@
package viewstate
import (
"bytes"
"encoding/json"
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// WaitsState is the view's own state `waits`: every wait a part holds, as the parts say it (design 47 G §512, §376, A-242), one
// key `<owner>.<step>.<node>.<module>` each, written by the view's process when it hears `wait-held` and deleted when it hears
// `wait-ended`, and read by view_tiers through the view's own read tool.
const WaitsState = "waits"
// WaitsBucket is the bus's bucket of the state waits.
const WaitsBucket = ViewModule + "_waits"
// Wait is the value of a waits key: the fields of the seat mesh-wants' wait (§498, §512, §629) as the part that holds it said
// them. The view writes no words of its own: Words is the sayer's.
type Wait struct {
// Owner is the seat or module that says the wait.
Owner string `json:"owner"`
Step string `json:"step"`
Node string `json:"node,omitempty"`
Module string `json:"module,omitempty"`
On string `json:"on,omitempty"`
Bound string `json:"bound,omitempty"`
Since time.Time `json:"since"`
Words string `json:"words,omitempty"`
Reason string `json:"reason,omitempty"`
Part string `json:"part,omitempty"`
Version string `json:"version,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Machines []string `json:"machines,omitempty"`
}
// WaitKey is the key of a wait: owner, step, node and module, each as a key part (an absent one is `-`).
func WaitKey(owner, step, node, module string) string {
part := func(s string) string {
if s == "" {
return "-"
}
return keys.EscapeName(s)
}
return strings.Join([]string{part(owner), part(step), part(node), part(module)}, ".")
}
// Key is the wait's key.
func (w Wait) Key() string { return WaitKey(w.Owner, w.Step, w.Node, w.Module) }
// ReadWait reads the body of a wait-held or wait-ended said by owner (the seat or module of its subject): the owner is the
// body's own when it names one. A body with no step or a field the wait does not know is refused.
func ReadWait(owner string, body []byte) (Wait, error) {
var w Wait
dec := json.NewDecoder(bytes.NewReader(body))
if err := dec.Decode(&w); err != nil {
return Wait{}, fmt.Errorf("the wait does not read: %w", err)
}
if w.Owner == "" {
w.Owner = owner
}
if w.Step == "" || w.Owner == "" {
return Wait{}, fmt.Errorf("the wait names no step or no owner")
}
return w, nil
}
@@ -0,0 +1,19 @@
package viewstate
import "testing"
func TestAWaitIsKeyedByOwnerStepNodeAndModuleAndReadFromItsBody(t *testing.T) {
w, err := ReadWait("mesh-wants", []byte(`{"step":"delivery","module":"web","node":"ace","part":"db","machines":["g14"],"since":"2026-11-12T01:00:00Z","words":"waiting for delivery of db to g14","extra-field":1}`))
if err != nil || w.Owner != "mesh-wants" || w.Key() != "mesh-wants.delivery.ace.web" || w.Words != "waiting for delivery of db to g14" || w.Machines[0] != "g14" {
t.Fatalf("wait %+v, key %q, %v", w, w.Key(), err)
}
if k := WaitKey("node-engine", "kept-build", "", "x y"); k != "node-engine.kept-build.-.x=20y" {
t.Errorf("key %q", k)
}
if _, err := ReadWait("mesh-wants", []byte(`{"module":"web"}`)); err == nil {
t.Error("a wait with no step read")
}
if w, _ := ReadWait("a", []byte(`{"owner":"b","step":"put"}`)); w.Owner != "b" {
t.Errorf("owner %+v", w)
}
}