Files
mesh-delivery/modules/mesh-delivery-assigner/internal/assign/wants.go
T
jschoubben bdbfa12aa1 A9: a node whose node-engine reads no want by version is held, awaiting its hand placement
The want of a node whose node-engine does not state the word want:version of
the seat node-engine, as the engine reads keeper holds it from
manifest-reads-changed, is written with hold and the words
awaits-hand-placement; once the engine states the word, the next pass writes
the want unheld.

Builds: design 47 H §772; H-A-45, H-A-73

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

182 lines
8.4 KiB
Go

package assign
import (
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/catalogkey"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-delivery-assigner/internal/puts"
)
// A want names the newest released version whose pipeline passed (design 47 H §750): for every node whose assignment places
// a module on a watched branch, the want names the version, the pipeline and the mover's rank in it, written tier by tier
// (§751). It is held for nothing else: the rules of ADR 0429 §6 (the build done, not held, the canary and step, every
// provider healthy, the grant, the composition and the reader capabilities, the provisions, the served verbs and the bus
// state), the network hold and A-428's exceptions end (H-A-55). A put owns its node's want as before (ADR 0546), and the
// operator's yes on a module of policy record is the node-engine's have and the asker's (the pass's yeses).
// Target is the build a node's want names: its fingerprint and released version, with the pipeline whose passed end released
// it and the mover's rank in that pipeline; a placement's build names no pipeline and no rank (design 47 H §750, H-A-37).
type Target struct {
Fp string
Version string
Pipeline string
Rank int64
}
// Module is what the want rule reads of one module: the nodes it is assigned to, the build each node's want names, the puts
// that own a node's want and the nodes that compose it themselves.
type Module struct {
Name string
Manifest catalogue.Manifest
// Chosen is a person's choice of the module's upgrade policy (the assigner's `policies`, ADR 0565 §7); nil: none.
Chosen *catalogue.PersonPolicy
Nodes []string
// Target is the build node's want names: the newest version of the module released on the branch the node's placement
// names whose pipeline passed and whose tier is written (§750, §751), or the placement's build (H-A-5); false: none yet,
// and the want written stays.
Target func(node string) (Target, bool)
// Allowed says whether the operator answered yes to the record ask about the move of this module on node to the composition
// with this digest (ADR 0539 §14). Nil: none did.
Allowed func(node, digest string) bool
// Puts are the puts of the module, by node (ADR 0546): while one owns a node's want (PutOwns), the rule passes over it.
Puts map[string]puts.Put
// Self says whether node composes the module itself: the catalogue's assignments names the node (ADR 0547 §2). Nil: no
// node does.
Self func(node string) bool
// ReadsVersion says whether node's node-engine states that it reads a want by version (the word want:version of the seat
// node-engine, design 47 H §772, H-A-45); a node whose engine does not is written its want held, awaiting its hand placement
// (H-A-73). Nil: every node does.
ReadsVersion func(node string) bool
}
func (m Module) selfOn(node string) bool { return m.Self != nil && m.Self(node) }
// Nodes is what the pass reads of the nodes: whether each is online (the watchman's presence), each module's have and the
// node-engine seat's last `running`.
type Nodes struct {
Online map[string]bool
Haves map[string]map[string]nodeengine.HaveByNodeModuleValue
// Running is, by node and module, the last `running` the node-engine seat said (design 47 G §309). Nil: the seat's events
// are not heard.
Running map[string]map[string]nodeengine.Running
// Providers is, by provision, the modules that provide it, with the nodes each is assigned to.
Providers map[string]map[string][]string
// Reads is, by node, the reader capabilities its node-engine states (nodeengine.NodeRecord.ManifestReads, ADR 0614 §4).
Reads map[string][]string
}
// Failed says whether a have's health check failed once the node is done moving.
func Failed(h nodeengine.HaveByNodeModuleValue) bool { return failed(h) }
// runsHealthy says whether module runs healthy on node: the node-engine seat's last `running` of it names a build, does not say it
// stopped and does not say `healthy` false (design 47 G §520); nothing heard of it counts as not healthy.
func (n Nodes) runsHealthy(node, module string) bool {
r, ok := n.Running[node][module]
return ok && !r.Stopped && r.Fingerprint != "" && (r.Healthy == nil || *r.Healthy)
}
// RunsHealthy says whether the build of module at fp runs healthy on node, from the node-engine seat's last `running` of it alone
// (design 47 G §520). The have is never read for it.
func (n Nodes) RunsHealthy(node, module, fp string) bool {
r, ok := n.Running[node][module]
return ok && n.runsHealthy(node, module) && r.Fingerprint == fp
}
// Outcome is what one module's pass decides: each node's want to write (only those that change).
type Outcome struct {
Wants map[string]mwc.Want
}
// Wants is the pass of one module m: for each of its nodes, the want naming its Target, starting from the want written before
// (wants, by node). A put that owns a node's want writes the put's; a node with no target keeps the want written. A node that
// wants m but is no longer among its nodes gets its want written removed, never deleted (ADR 0408 §4).
func Wants(m Module, wants map[string]mwc.Want) Outcome {
out := Outcome{Wants: map[string]mwc.Want{}}
for _, node := range m.Nodes {
before, had := wants[node]
p, put := m.Puts[node]
if !put && had && before.Put && before.Hold {
// The want is the truth (ADR 0546 clause 5): a want marked put and held stands while its put is not heard; only a put
// heard released gives it back to the rule.
p, put = puts.Put{FP: before.Fp, Hold: true, Why: strings.TrimPrefix(before.Words, "put: "), Step: puts.Holding}, true
}
if put {
if want, owns := PutOwns(p); owns {
if want != nil && (!had || !mwc.SameWant(normal(before), normal(*want))) {
out.Wants[node] = *want
}
continue
}
}
t, ok := Target{}, false
if m.Target != nil {
t, ok = m.Target(node)
}
if !ok || t.Fp == "" {
continue
}
next := mwc.Want{Fp: t.Fp, Version: t.Version, Pipeline: t.Pipeline, Rank: t.Rank, Self: m.selfOn(node)}
if had && !before.Removed && !before.Put && before.Fp == t.Fp {
// The answers the want carries stay while its build does: a failed backup's (ADR 0539 §16), a held revert's, the yes.
next.Backup, next.Words, next.Revert, next.Yes, next.Release = before.Backup, before.Words, before.Revert, before.Yes, before.Release
}
if m.ReadsVersion != nil && !m.ReadsVersion(node) {
// A node-engine that cannot read a want by version is placed by hand when its machine is back (design 47 H §772).
next.Hold, next.Words, next.Backup, next.Revert = true, mwc.HoldAwaitsHandPlacement, "", ""
}
if !had || !mwc.SameWant(normal(before), normal(next)) {
out.Wants[node] = next
}
}
for node, before := range wants {
if !slices.Contains(m.Nodes, node) && !before.Removed {
out.Wants[node] = mwc.Want{Removed: true, Words: fmt.Sprintf("%s is no longer assigned to %s", m.Name, node)}
}
}
return out
}
// failed says whether a have's health check failed once the node is done moving: phase running or failed (never removed, held, or
// moving).
func failed(h nodeengine.HaveByNodeModuleValue) bool {
return h.Health == nodeengineclient.HealthFailed && (h.Phase == nodeengineclient.PhaseRunning || h.Phase == nodeengineclient.PhaseFailed)
}
// normal is a want without its version, as a decoded and a composed one are compared.
func normal(w mwc.Want) mwc.Want {
w.V = 0
return w
}
func short(fp string) string {
part, err := catalogkey.KeyPart(fp)
if err != nil || len(part) < 12 {
return fp
}
return part[:12]
}
// RecordNeed is a move of a module of policy record on a node that waits for the operator's yes: the digest the node-engine's have
// waits on, its judgement of the move and its words (ADR 0539 §14).
type RecordNeed struct {
Node string
Digest string
Judgement Judgement
Words string
}
// KeptBuild is what the assigner knows of a build: the digest of each of its parts by `<module>:<artifact>` and the build node that
// keeps it, as the builder's `build.ended` says them, and its released version as the catalog's `version-released` says it (design
// 47 G §379, A-96). A want names the version alone (design 47 H §750).
type KeptBuild struct {
Parts map[string]string
KeptOn string
Version string
}