mesh-sdk/go/compose/judge/judge.go

// Package judge is how the seat mesh-placement's holder judges a proposal (novox/hq ADR 0567 §3, §4): which nodes must
// answer it and what it changes on each (Intended), and the verdict of their answers (JudgeAnswers). Moved here from
// the assigner, where it judged a catalogue pull request's placement (ADR 0559 §5), with a proposal in place of a pull
// request's change. It holds no bus client and no timer: the holder gives it what it read.
package judge

import (
	"fmt"
	"reflect"
	"sort"
	"strings"
	"time"

	"git.novox.be/novox/mesh-sdk/go/compose"
	"git.novox.be/novox/mesh-sdk/go/delivery"
)

// AnswerBound is how long the holder waits for a node's answer after its candidate was written (ADR 0567 §4): the time to
// live of the node's pulse key (delivery.PulseAnswerKey), whose expiry names it silent, never passed. A variable so a test
// on the bus can shorten it.
var AnswerBound = 10 * time.Minute

// Intended is, by node, the modules whose composition the proposal changes, and the nodes that must answer it (§3).
// current is the composition input with the current placement and laidInput the same with the proposal's placements
// (laid, by node; nil removes the node's key) laid over it; nodes is every node to look at (every node with a record).
// A node's set holds the modules the proposal adds, removes or whose placed entry differs on that node, and those whose
// composition differs between the two inputs (delivery.CompareComposed), the node's own named "node". Must is every node
// whose key the proposal changes and every other whose set is not empty, sorted. A node that has no key now gets an
// empty set (§7: the seed is answered as the same). A node whose compositions cannot be made on either side keeps the
// modules its entries name, said in notes; such a node is in Must only when its key changes.
func Intended(current, laidInput *compose.Input, currentPlaced map[string]delivery.Placement, laid map[string]*delivery.Placement,
	nodes []string, fps map[string]string) (intended map[string]map[string]bool, must []string, notes []string) {
	intended = map[string]map[string]bool{}
	inMust := map[string]bool{}
	all := map[string]bool{}
	for _, n := range nodes {
		all[n] = true
	}
	for n := range laid {
		all[n] = true
		inMust[n] = true
	}
	names := make([]string, 0, len(all))
	for n := range all {
		names = append(names, n)
	}
	sort.Strings(names)
	for _, node := range names {
		before, placed := currentPlaced[node]
		set := map[string]bool{}
		after, changesKey := laid[node]
		if changesKey && !placed {
			intended[node] = set // a node new to placement: every answer must be the same
			continue
		}
		if changesKey {
			var afterModules []delivery.PlacedModule
			if after != nil {
				afterModules = after.Modules
			}
			entries := map[string]delivery.PlacedModule{}
			for _, m := range before.Modules {
				entries[m.Module] = m
			}
			seen := map[string]bool{}
			for _, m := range afterModules {
				seen[m.Module] = true
				if e, ok := entries[m.Module]; !ok || !reflect.DeepEqual(e, m) {
					set[m.Module] = true
				}
			}
			for name := range entries {
				if !seen[name] {
					set[name] = true
				}
			}
		}
		if placed && current != nil && laidInput != nil {
			was, _, _, errB := compose.CompositionsShadow(*current, node, fps)
			now, _, _, errA := compose.CompositionsShadow(*laidInput, node, fps)
			if errA == nil && errB == nil {
				running := make([]delivery.Composed, 0, len(was))
				for _, c := range was {
					running = append(running, c)
				}
				cmp := delivery.CompareComposed(now, running)
				for _, d := range cmp.Differs {
					set[d.Module] = true
				}
				for _, d := range cmp.Added {
					set[d.Module] = true
				}
				for _, m := range cmp.Removed {
					set[m] = true
				}
			} else if changesKey {
				notes = append(notes, fmt.Sprintf("what the proposal changes on %s is read from its placement alone: its "+
					"compositions cannot be made (now: %v; proposed: %v)", node, errB, errA))
			}
		}
		if len(set) > 0 {
			inMust[node] = true
		}
		if inMust[node] {
			intended[node] = set
		}
	}
	for n := range inMust {
		must = append(must, n)
	}
	sort.Strings(must)
	return intended, must, notes
}

// JudgeAnswers is the verdict of a proposal's answers (§4). answers is by node its HaveNode.Candidates entry for the
// proposal (nil when it has none) and revisions by node the revision of its candidate key: an answer counts when it
// names the proposal and that revision. It fails on a refusal by a node that must answer, and on every node of Must with
// no answer that counts once its pulse key has ended (pulsing false: the bound's expiry, heard on the bus); while it
// stands it waits for them.
// A difference fails nothing: one Intended computed is listed under Intended, one it did not under Unintended, both
// shown in the ask's brief. The seed alone fails on any difference.
func JudgeAnswers(p delivery.PlacementProposal, intended map[string]map[string]bool, answers map[string]*delivery.CandidateAnswer,
	revisions map[string]uint64, online map[string]bool, pulsing map[string]bool, now time.Time) delivery.PlacementVerdict {
	v := delivery.PlacementVerdict{At: now.UTC(), Intended: map[string][]string{}, Unintended: map[string][]string{},
		Answers: map[string]delivery.CandidateAnswer{}}
	for node, set := range intended {
		for m := range set {
			v.Intended[node] = append(v.Intended[node], m)
		}
		sort.Strings(v.Intended[node])
	}
	must := p.Must
	if len(must) == 0 {
		must = p.Nodes()
	}
	for _, node := range must {
		a := answers[node]
		if a == nil || a.Proposal != p.ID || a.Revision == 0 || a.Revision != revisions[node] {
			v.Silent = append(v.Silent, node)
			continue
		}
		v.Answers[node] = *a
		if a.Refused != "" {
			v.Fails = append(v.Fails, fmt.Sprintf("%s cannot compose the proposal: %s", node, a.Refused))
			continue
		}
		for _, r := range a.Refusals {
			v.Fails = append(v.Fails, fmt.Sprintf("%s refuses the proposal for %s: %s", node, r.Module, r.Why))
		}
		want := intended[node]
		differs := func(module, words string) {
			if p.Seed {
				v.Fails = append(v.Fails, fmt.Sprintf("%s %s with the seed, which must be the same as what runs", node, words))
				return
			}
			if !want[module] {
				v.Unintended[node] = append(v.Unintended[node], module)
			}
		}
		for _, d := range a.Differs {
			differs(d.Module, fmt.Sprintf("composes %s differently (%s)", d.Module, d.Why))
		}
		for _, d := range a.Added {
			differs(d.Module, "would run "+d.Module)
		}
		for _, m := range a.Removed {
			differs(m, "would stop running "+m)
		}
		sort.Strings(v.Unintended[node])
	}
	if len(v.Intended) == 0 {
		v.Intended = nil
	}
	if len(v.Unintended) == 0 {
		v.Unintended = nil
	}
	if len(v.Answers) == 0 {
		v.Answers = nil
	}
	var waiting, gone []string
	for _, node := range v.Silent {
		named := node
		if online != nil && !online[node] {
			named += " (offline)"
		}
		if pulsing[node] {
			waiting = append(waiting, named)
		} else {
			gone = append(gone, named)
		}
	}
	if len(waiting) > 0 {
		v.Notes = append(v.Notes, fmt.Sprintf("waits for the answers of %s, each for %s from its candidate's write",
			strings.Join(waiting, ", "), AnswerBound))
	}
	if len(gone) > 0 {
		v.Fails = append(v.Fails, fmt.Sprintf("%s did not answer within %s of its candidate's write; judged again when it "+
			"answers", strings.Join(gone, ", "), AnswerBound))
	}
	switch {
	case len(v.Fails) > 0:
		v.State = delivery.VerdictFail
	case len(waiting) > 0:
		v.State = delivery.VerdictWaits
	default:
		v.State = delivery.VerdictPass
	}
	return v
}

// Brief is the verdict as the ask's brief shows it, by node (§5): what the proposal changes and what each node answered
// beside it, marked, with the proposal's why.
func Brief(p delivery.PlacementProposal, v delivery.PlacementVerdict) string {
	var b strings.Builder
	fmt.Fprintf(&b, "%s (proposed by %s)", p.Why, p.By)
	nodes := map[string]bool{}
	for n := range v.Intended {
		nodes[n] = true
	}
	for n := range v.Unintended {
		nodes[n] = true
	}
	for _, n := range p.Nodes() {
		nodes[n] = true
	}
	names := make([]string, 0, len(nodes))
	for n := range nodes {
		names = append(names, n)
	}
	sort.Strings(names)
	for _, n := range names {
		fmt.Fprintf(&b, "; %s:", n)
		if m := v.Intended[n]; len(m) > 0 {
			fmt.Fprintf(&b, " changes %s", strings.Join(m, ", "))
		} else {
			b.WriteString(" composes the same")
		}
		if m := v.Unintended[n]; len(m) > 0 {
			fmt.Fprintf(&b, "; also differs, not computed: %s", strings.Join(m, ", "))
		}
	}
	return b.String()
}