Files
mesh-catalog/modules/mesh-config/cmd/mesh-config/findings.go
T

146 lines
7.2 KiB
Go

package main
// mesh-config's findings (novox/hq ADR 0564 clause 2): what it sees wrong about a rename or a retirement, kept in its
// state `findings` as the condition keeper reads them, written when what they say changes and deleted when the fault
// is gone. The keeper raises and clears the condition of the same key (mesh-conditions' Observers and Homes).
import (
"context"
"fmt"
"slices"
"strings"
"time"
meshconditions "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
// FindingsState is the state, meshconditions.StateFindings.
const FindingsState = "findings"
// The kinds of finding mesh-config writes.
const (
// FindingRenameRefused is a move mesh-config refused; cleared once the value moved or `renamed-from` left the
// trunk's manifest.
FindingRenameRefused = "rename-refused"
// FindingWindowHeld is a rename window held open seven days by a node; cleared when the window closes.
FindingWindowHeld = "rename-window-held"
// FindingRetireUnanswered is a retirement's ask unanswered after it was asked once more; cleared by an answer, a
// cancel, or the value read again.
FindingRetireUnanswered = "retiring-unanswered"
// FindingRetireHeld is a retirement waiting seven days for a node still running a build that reads the value.
FindingRetireHeld = "retirement-held"
)
// findingID is the id of a finding about a module on a node: the module, the node when there is one, and the ref
// (`<module>.<node>.<ref>`), each escaped as a key's name is, since the kind is a fixed word (design 47 G A-14).
func findingID(module, node, ref string) string {
id := keys.EscapeName(module)
if node != "" {
id += "." + keys.EscapeName(node)
}
return id + "." + keys.EscapeName(ref)
}
func finding(kind, module, node, ref, summary, headline, explanation, needs, said string, at time.Time) meshconditions.Finding {
id := findingID(module, node, ref)
return meshconditions.Finding{Scope: "module", ID: id, Kind: kind,
Subject: meshconditions.Subject{Scope: "module", ID: id, Machine: node},
Severity: meshconditions.FindingSeverityWarning, Resolver: "operator", Summary: summary, Headline: headline,
Explanation: explanation, Needs: needs,
Evidence: []meshconditions.Evidence{{At: at.UTC(), Said: said}}, Source: "config", Observer: Module, At: at.UTC()}
}
// renameRefused is the finding of a move mesh-config refused.
func renameRefused(module, to, from, why string, at time.Time) meshconditions.Finding {
return finding(FindingRenameRefused, module, "", to,
fmt.Sprintf("the rename of %s's config value %s to %s is refused: %s", module, from, to, why),
fmt.Sprintf("%s's value %s is not moved to %s", module, from, to),
fmt.Sprintf("The new version of %s names %s as the new name of its config value %s, and mesh-config refused to move the value: %s. Nothing was moved.", module, to, from, why),
fmt.Sprintf("put the cause right, then move it with config_rename_again (module %s, to %s); the details name it.", module, to),
why, at)
}
// windowHeld is the finding of a rename window held open past HeldFinding by a node.
func windowHeld(r Rename, node string, at time.Time) meshconditions.Finding {
return finding(FindingWindowHeld, r.Module, node, r.To,
fmt.Sprintf("%s on %s has held the old config name %s open for %d days", r.Module, node, r.From, int(HeldFinding.Hours()/24)),
fmt.Sprintf("%s on %s still runs the old config name", r.Module, node),
fmt.Sprintf("The rename of %s's config value %s to %s is not complete on %s: its node-engine has not reported a build that reads %s (it may be away).", r.Module, r.From, r.To, node, r.To),
fmt.Sprintf("bring %s back, or drop it from the window with config_rename_close.", node),
fmt.Sprintf("the window opened %s and %s has not reported a build reading %s", r.Nodes[node].Since.UTC().Format(time.RFC3339), node, r.To), at)
}
// FindingsWriter is the module's held finding writer (views.HeldWriter), through which mesh-config writes and clears its
// findings and reads what it holds (design 47 G §689, A-29, A-38): the module keeps no set of its own.
type FindingsWriter interface {
Write(ctx context.Context, finding meshconditions.Finding) error
Clear(ctx context.Context, scope, id, kind, why string) error
Held() []meshconditions.Finding
}
// setFinding writes a finding when it differs from the one held; the module and ref are the parts of its id.
func (c *Config) setFinding(module, ref string, f meshconditions.Finding) {
if c.Findings == nil {
return
}
if err := views.CheckFinding(f); err != nil {
c.logf("[mesh-config] a finding is not valid: %v", err)
return
}
key := views.FindingKey(f.Scope, f.ID, f.Kind)
c.findMu.Lock()
defer c.findMu.Unlock()
for _, old := range c.Findings.Held() {
if views.FindingKey(old.Scope, old.ID, old.Kind) == key && old.Summary == f.Summary {
return // what it says has not changed
}
}
if err := c.Findings.Write(context.Background(), f); err != nil {
c.logf("[mesh-config] the finding %s is not written: %v", key, err)
}
}
// clearFinding clears the findings of a kind and ref about a module, on whatever node but those in keep.
func (c *Config) clearFinding(kind, module, ref string, keep ...string) {
if c.Findings == nil {
return
}
c.findMu.Lock()
defer c.findMu.Unlock()
for _, f := range c.Findings.Held() {
if f.Kind != kind || f.ID != findingID(module, f.Subject.Machine, ref) ||
(f.Subject.Machine != "" && slices.Contains(keep, f.Subject.Machine)) {
continue
}
if err := c.Findings.Clear(context.Background(), f.Scope, f.ID, f.Kind, "the fault is gone"); err != nil {
c.logf("[mesh-config] the finding %s is not cleared: %v", views.FindingKey(f.Scope, f.ID, f.Kind), err)
}
}
}
// retirementHeld is the finding of a retirement that waits seven days for nodes that still run a build reading the value.
func retirementHeld(e Retiring, at time.Time) meshconditions.Finding {
node := ""
if len(e.Nodes) > 0 {
node = e.Nodes[0]
}
return finding(FindingRetireHeld, e.Module, node, e.Key,
fmt.Sprintf("%s's %s has waited %d days to retire: %s still run a build that reads it", e.Module, e.Key, int(HeldFinding.Hours()/24), strings.Join(e.Nodes, ", ")),
fmt.Sprintf("%s's %s cannot be retired yet", e.Module, e.Key),
fmt.Sprintf("No manifest reads %s's %s any more, but %s still run a build that does, so the operator is not asked to remove it.", e.Module, e.Key, strings.Join(e.Nodes, ", ")),
"bring those nodes up to date, or cancel the retirement with config_retiring.",
"retiring since "+e.Since.UTC().Format(time.RFC3339)+", still read on "+strings.Join(e.Nodes, ", "), at)
}
// retireUnanswered is the finding of a retirement asked twice and not answered.
func retireUnanswered(e Retiring, at time.Time) meshconditions.Finding {
return finding(FindingRetireUnanswered, e.Module, "", e.Key,
fmt.Sprintf("the operator did not answer the ask to remove %s's %s, asked twice", e.Module, e.Key),
fmt.Sprintf("%s's %s waits for an answer", e.Module, e.Key),
fmt.Sprintf("No manifest reads %s's %s any more. The operator was asked twice whether to remove it and did not answer, so it stays.", e.Module, e.Key),
"answer the ask again with config_retiring ask-again, or cancel it.",
"asked "+e.Asked.UTC().Format(time.RFC3339)+" and once more", at)
}