Files
mesh-delivery/modules/mesh-delivery-watchman/internal/watch/waits.go
T
jschoubben 161d6e6451 WM16: a record is covered only by what is late for the entries of its own revision
record-opened is joined to the take-in.taken of its milestone, <branch>.<source revision>, whose entries name the modules; the
record-open finding is left unwritten only while one of those modules is held by an acting-part-late wait (or a store says full),
no longer while any wait is late. A record whose revision is not known taken is covered by a standing take-in-waits.

Builds: design 47 G §502, A-200

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 05:56:33 +01:00

212 lines
8.7 KiB
Go

package watch
import (
"encoding/json"
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// What the holders of an acting part's wait say, heard as the seats' events (design 47 G §266, §269, ADR 0596 §2), never read
// from their state: `wait-held` and `wait-ended` of a wait (the seat mesh-wants, and the seat mesh-pipeline-runner for its
// `pipeline` step). A wait held past its bound is the finding `acting-part-late`, timed by that bound alone from the time
// `wait-held` carries as `clock-from` (its `since` where it carries none), and ended by `wait-ended`, whoever ended it (the
// part's new version running, or a release). Its pulse is its bound, written at the event, so a restart loses none.
// actingRow is the row of the signals table of an acting part's wait.
const actingRow = "acting-wait"
func waitID(seat string, a meshwants.Wait) string {
return strings.Join([]string{seat, a.Step, a.Part, a.Node, a.Module}, "-")
}
// WaitHeld hears a seat's `wait-held`: the finding is due when the wait's bound has run from its clock.
func (w *Watchman) WaitHeld(seat string, body []byte) {
a, ok := decodeWait(w, seat, "wait-held", body)
if !ok {
return
}
w.mu.Lock()
defer w.mu.Unlock()
w.waitHeld(seat, a)
}
// WaitEnded hears a seat's `wait-ended`: the wait ran or was released, so its finding and its pulse end.
func (w *Watchman) WaitEnded(seat string, body []byte) {
a, ok := decodeWait(w, seat, "wait-ended", body)
if !ok {
return
}
w.mu.Lock()
defer w.mu.Unlock()
id := waitID(seat, a)
w.unsignal(actingRow, id)
w.unfind(FindingKey(ScopeDelivery, id, KindActingPartLate))
w.unfind(FindingKey(ScopeDelivery, id, KindPutStands))
w.rejudgeRecords()
}
func decodeWait(w *Watchman, seat, event string, body []byte) (meshwants.Wait, bool) {
var a meshwants.Wait
if err := json.Unmarshal(body, &a); err != nil || (a.Part == "" && a.Step != meshwants.WaitStepPut) || a.Module == "" || a.Since.IsZero() {
w.say("the %s of the seat %s does not read, left: %v", event, seat, err)
return a, false
}
return a, true
}
// waitHeld is one wait held, w.mu held.
func (w *Watchman) waitHeld(seat string, a meshwants.Wait) {
bound, err := time.ParseDuration(a.Bound)
if err != nil || bound <= 0 {
w.say("the wait of %s at %s says no bound (%q), so it is never late", a.Module, a.Part, a.Bound)
return
}
from := a.Since
if a.ClockFrom != nil {
from = *a.ClockFrom
}
id := waitID(seat, a)
if a.Step == meshwants.WaitStepPut {
w.putStands(id, a, bound, from)
return
}
f := Finding{Scope: ScopeDelivery, ID: id, Kind: KindActingPartLate, Severity: Warning, Source: actingRow, Since: a.Since,
Summary: fmt.Sprintf("%s on %s waits for %s to run %s at the step %s, since %s (bound %s)", a.Module, orWords(a.Node, "no node"), a.Part,
orWords(a.Version, "its new version"), a.Step, stamp(a.Since), bound),
Said: "held for " + bound.String(),
Headline: "An acting part's new version has not come",
Explanation: "A step waits until " + a.Part + " runs its new version, and its bound of " + bound.String() +
" has run, so what the step does is held back.",
Needs: "the part's new version to run, or the wait released by hand (the holder's release tool)"}
left := bound - w.now().Sub(from)
w.unsignal(actingRow, id)
w.unfind(f.Key())
if left > 0 {
w.signal(actingRow, id, left, signalDue{Do: dueFind, Finding: f})
return
}
w.find(f)
w.rejudgeRecords() // a record whose entry this wait holds is covered now (§502)
}
// putStands is a put's wait held (`step: put`, design 47 G §498): a put without hold that stands past its bound is said as the
// finding `put-stands`, never `acting-part-late`, since no acting part is waited for. w.mu held.
func (w *Watchman) putStands(id string, a meshwants.Wait, bound time.Duration, from time.Time) {
f := Finding{Scope: ScopeDelivery, ID: id, Kind: KindPutStands, Severity: Warning, Source: actingRow, Since: a.Since,
Summary: fmt.Sprintf("a put of %s on %s at %s stands, since %s (bound %s)", a.Module, orWords(a.Node, "no node"),
orWords(a.Fingerprint, "its build"), stamp(a.Since), bound),
Said: "stands for " + bound.String(),
Headline: "A put has not gone through",
Explanation: "A put of " + a.Module + " without a hold has stood past its bound of " + bound.String() +
", so the node's want is not at the build that was put.",
Needs: "the put to go on, or released by hand (assigner_release)"}
left := bound - w.now().Sub(from)
w.unsignal(actingRow, id)
w.unfind(f.Key())
if left > 0 {
w.signal(actingRow, id, left, signalDue{Do: dueFind, Finding: f})
return
}
w.find(f)
}
// What a node-engine says of a hold it keeps (design 47 G §499, §541), heard on the seat node-engine's `wait-held` and `wait-ended`
// (`mesh.seat.node-engine.event.<event>.<node>.<module>`, the node the one that says it): a hold of the composition (`step:
// compose`, with its reason) standing past composing's 30 minutes (§266) is the finding `delivery-waits`, naming the node, the
// module and the reason, and a wait for a kept build (`step: kept-build`, naming the build node) standing past building's default
// bound of 60 minutes is `kept-build-waits`. Each clears on `wait-ended`.
// The findings of a node-engine's waits, and the bounds that stand when its event names none.
const (
KindDeliveryWaits = "delivery-waits"
KindKeptBuildWaits = "kept-build-waits"
ComposeBound = 30 * time.Minute
KeptBuildBound = 60 * time.Minute
)
// engineRow is the row of the signals table of a node-engine's wait.
const engineRow = "engine-wait"
func engineWaitID(node, module string) string { return node + "." + module }
// EngineWaitHeld hears the node-engine of node saying `wait-held` for module.
func (w *Watchman) EngineWaitHeld(node, module string, body []byte) {
var a nodeengine.Wait
if err := json.Unmarshal(body, &a); err != nil || a.Since.IsZero() {
w.say("a wait-held of the node-engine of %s for %s does not read, left: %v", node, module, err)
return
}
kind, bound := KindDeliveryWaits, ComposeBound
if a.Step == nodeengine.WaitStepKeptBuild {
kind, bound = KindKeptBuildWaits, KeptBuildBound
}
if d, err := time.ParseDuration(a.Bound); err == nil && d > 0 {
bound = d
}
from := a.Since
if a.ClockFrom != nil {
from = *a.ClockFrom
}
id := engineWaitID(node, module)
what := "holds the composition of " + module
if a.Step == nodeengine.WaitStepKeptBuild {
what = "waits for the kept build of " + module + " on " + orWords(a.Node, "no node")
}
f := Finding{Scope: ScopeDelivery, ID: id, Kind: kind, Severity: Warning, Machine: node, Source: engineRow, Since: a.Since,
Summary: fmt.Sprintf("the node-engine of %s %s: %s, since %s (bound %s)", node, what, orWords(a.Reason, "no reason said"), stamp(a.Since), bound),
Said: "held for " + bound.String(),
Headline: "A module's delivery is held on a machine",
Explanation: "The node-engine of " + node + " " + what + " (" + orWords(a.Reason, "no reason said") + ") and its bound of " +
bound.String() + " has run, so the module is not at the build wanted there.",
Needs: "what it waits on to come: " + orWords(a.Words, orWords(a.Reason, "the node-engine's wait to end"))}
w.mu.Lock()
defer w.mu.Unlock()
w.unsignal(engineRow, id)
w.unfind(f.Key())
if left := bound - w.now().Sub(from); left > 0 {
w.signal(engineRow, id, left, signalDue{Do: dueFind, Finding: f})
return
}
w.find(f)
}
// EngineWaitEnded hears the node-engine of node saying `wait-ended` for module: the hold is over, whichever kind it was.
func (w *Watchman) EngineWaitEnded(node, module string) {
id := engineWaitID(node, module)
w.mu.Lock()
defer w.mu.Unlock()
w.unsignal(engineRow, id)
w.unfind(FindingKey(ScopeDelivery, id, KindDeliveryWaits))
w.unfind(FindingKey(ScopeDelivery, id, KindKeptBuildWaits))
}
// ModuleWaitHeld hears a module's `wait-held` on its own stream (`mesh.stream.<module>.event.wait-held.<module>.<fingerprint>`), the form
// the builder says a key queued behind a package in, with the package as its `part` (design 47 G A-192, ADR 0603 §8): it is timed as any
// acting part's wait. A wait naming no part is a toolchain wait, which the builder times itself (§672), and is left.
func (w *Watchman) ModuleWaitHeld(holder string, body []byte) {
var a meshwants.Wait
if json.Unmarshal(body, &a) == nil && a.Part == "" {
return
}
a2, ok := decodeWait(w, holder, "wait-held", body)
if !ok {
return
}
w.mu.Lock()
defer w.mu.Unlock()
w.waitHeld(holder, a2)
}
// ModuleWaitEnded hears the same module's `wait-ended`.
func (w *Watchman) ModuleWaitEnded(holder string, body []byte) {
var a meshwants.Wait
if json.Unmarshal(body, &a) == nil && a.Part == "" {
return
}
w.WaitEnded(holder, body)
}