Files
mesh-delivery/modules/mesh-delivery-watchman/internal/watch/mirror.go
T
jschoubben f6163349af W1: the watchman reads the H1 take-in, the mover's entry and the want
The watchman follows the one model in one pass. Its take-in waits are the seat's take-in.pending
and take-in.taken, keyed <branch>.<source>, timed from the message's own time by the setting
take-in-bound (60 minutes by default), and seeded from indexer_pending's held take-ins; the group
bound goes. A taken-in mover's bus state is read from its catalog entry by fingerprint through
the seat mesh-catalog's verb entry, bus-state-overdue timed from the take-in. The manifest
verdicts and their findings, the head timing of source-moved, acting-part-late and
delivery-waits go, with their readers, consumes and the indexer_verdicts invoke. A want awaiting
its hand placement is not timed, and the want readers follow the H1 want. A record-opened is
heard on record-opened.<call>.

Builds: design 47 H §741, §744, §764 (the indexer: manifest-refused, manifest-accepted, the
watchman's findings; the assigner: acting-part-late, delivery-waits), §772; lead answers H-A-25,
H-A-37, H-A-49, H-A-70, H-A-78 (2), H-A-79, H-A-91 (2), H-A-94, H-A-95 (1), H-A-97, H-A-102

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

201 lines
6.8 KiB
Go

package watch
import (
"encoding/json"
"strings"
"time"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"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/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
)
// A build ask taken by a node is a move (novox/hq ADR 0525 §4, issues 1887 A8b, 1908, 1909; design 47 G §483, §496, §602,
// A-136): the holder of the build seat says `ask-taken` when it takes any ask, `step-progress` once a minute while it runs
// it, and `step-ended` when it ends it. The pulse of the move is the pulse of the bucket named as the seat's stream
// (buildstep.AskStream), under the ask's id, and it begins at the latest of the ask's taking and its progress, so a step
// that runs long but says its progress raises nothing, and one whose holder stops is stuck within the progress bound.
//
// **An ask still waiting in the stream is a backlog, not a stall** (issue 1908): no pulse is made for a waiting ask, so none
// can expire into a false stuck row; the view shows the backlog and the oldest waiting ask's age (delivery view, A8a).
// ProgressBound is how long a running ask may say nothing of its progress (design 47 G §75: five minutes).
const ProgressBound = 5 * time.Minute
// languageOfSeat is the build language whose seat is seat, and whether it is a build seat.
func languageOfSeat(seat string) (string, bool) {
for _, lang := range buildstep.AskLanguages {
if s, err := buildstep.BuildSeat(lang); err == nil && s == seat {
return lang, true
}
}
return "", false
}
// AskTaken hears a build seat's `ask-taken` (node: the subject's last token): the ask is taken, so its clock begins at the
// event's time.
func (w *Watchman) AskTaken(seat, node string, body []byte) {
var e nodebuildgo.AskTakenEvent
if err := json.Unmarshal(body, &e); err != nil || e.Ask == "" {
w.say("an ask-taken of %s does not read, left: %v", seat, err)
return
}
w.askClock(seat, node, e.Ask, e.At)
}
// StepProgress hears a build seat's `step-progress`: the running ask says it lives, so its clock begins again at the
// event's time.
func (w *Watchman) StepProgress(seat, node string, body []byte) {
var e nodebuildgo.StepProgressEvent
if err := json.Unmarshal(body, &e); err != nil || e.Ask == "" {
w.say("a step-progress of %s does not read, left: %v", seat, err)
return
}
w.mu.Lock()
w.stepsHeardOf(e.Ask, e.At)
w.mu.Unlock()
w.askClock(seat, node, e.Ask, e.At)
}
// AskEnded hears a build seat's `step-ended`, whatever its asker: the ask's clock ends.
func (w *Watchman) AskEnded(seat string, body []byte) {
lang, ok := languageOfSeat(seat)
if !ok {
return
}
bucket, err := buildstep.AskStream(lang)
if err != nil {
return
}
var e nodebuildgo.StepEndedEvent
if err := json.Unmarshal(body, &e); err != nil || e.Ask == "" {
w.say("a step-ended of %s does not read, left: %v", seat, err)
return
}
w.mu.Lock()
defer w.mu.Unlock()
w.stepsHeardOf(e.Ask, e.At)
w.moved(bucket, e.Ask)
}
func (w *Watchman) askClock(seat, node, ask string, at time.Time) {
lang, ok := languageOfSeat(seat)
if !ok {
return
}
bucket, err := buildstep.AskStream(lang)
if err != nil {
w.say("no pulse for the ask %s: %v", ask, err)
return
}
w.mu.Lock()
defer w.mu.Unlock()
if at.IsZero() {
at = w.now()
}
w.mirrorWithin(w.progressBound, bucket, ask, describe("the ask %s to end on %s", ask, node), node, at, 0)
}
// A want is a move too (novox/hq ADR 0539 §19, issue 1906): the assigner writes `want.<node>.<module>` in its wants bucket,
// and the node's agent owes the node-engine's have naming the want's fingerprint. The pulse is the pulse of that bucket under
// the want's key, owed by the node's agent, and it begins when the assigner wrote the want. The have naming the fingerprint
// ends it; a want that is removed, or a key deleted, ends it as well. Nothing renews it: the bound is how long a node may
// take to apply a want, the same as a build step's (StepBound). Keys of that bucket that are not a want of a module (a hold,
// and the node's own key) are left.
// Want is a change of a key of the assigner's wants bucket, read from the watch (at the start the keys that stand, then each
// change), at the time the entry was written.
func (w *Watchman) Want(key string, value []byte, op Op, at time.Time) {
node, module, err := meshwantsclient.ParseWantKey(key)
if err != nil {
return
}
w.mu.Lock()
defer w.mu.Unlock()
if w.wantsBucket() == "" {
return // no holder of the seat mesh-wants is followed: the key names no bucket (A-321)
}
switch op {
case Expired:
return
case Delete:
delete(w.wants, key)
w.moved(w.wantsBucket(), key)
return
}
w.stands(w.wantsBucket(), key)
want, err := meshwantsclient.DecodeWant(value)
if err != nil {
w.say("the want %s cannot be read, and is left: %v", key, err)
return
}
if want.Removed {
delete(w.wants, key)
w.moved(w.wantsBucket(), key)
return
}
if want.Hold {
// A want awaiting its hand placement (design 47 H §772) is not progress owed, so it is not timed (H-A-95 (1)).
delete(w.wants, key)
w.moved(w.wantsBucket(), key)
return
}
w.wants[key] = want.Fp
if w.have(node, module) == want.Fp {
w.moved(w.wantsBucket(), key)
return
}
if at.IsZero() {
at = w.now()
}
w.mirrorWithin(w.stepBound, w.wantsBucket(), key,
describe("the node agent of %s to run %s at %s", node, module, shortFP(want.Fp)), want.Fp, at, 0)
}
// EngineRunning hears the node-engine of node saying `running` for module (design 47 G §541, A-192, A-197): the fingerprint it runs, or
// that it runs none (stopped). One that names the fingerprint of the node's want for the module ends the want's pulse.
func (w *Watchman) EngineRunning(node, module string, body []byte) {
var r nodeengine.Running
if err := json.Unmarshal(body, &r); err != nil {
w.say("a running of the node-engine of %s for %s does not read, left: %v", node, module, err)
return
}
key, err := nodeengineclient.HaveKey(node, module)
if err != nil {
return
}
w.mu.Lock()
defer w.mu.Unlock()
if r.Stopped || r.Fingerprint == "" {
delete(w.haves, key)
return
}
w.haves[key] = r.Fingerprint
wk, err := meshwantsclient.WantKey(node, module)
if err != nil {
return
}
if fp, ok := w.wants[wk]; ok && fp == r.Fingerprint {
w.moved(w.wantsBucket(), wk)
}
}
func (w *Watchman) have(node, module string) string {
key, err := nodeengineclient.HaveKey(node, module)
if err != nil {
return ""
}
return w.haves[key]
}
func shortFP(fp string) string {
hex := strings.TrimPrefix(fp, meshcatalogclient.SourcePrefix2)
if len(hex) > 12 {
hex = hex[:12]
}
return hex
}