Files
mesh-delivery/modules/mesh-delivery-watchman/internal/watch/takein.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

184 lines
7.3 KiB
Go

package watch
import (
"encoding/json"
"fmt"
"maps"
"slices"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-indexer/takein"
)
// KindTakeInWaits is a source revision or a delivery group the indexer holds back and has not taken in within its bound
// (novox/hq ADR 0633 §5, issue 1585): a revision for the indexer build it names, a group for its end. It stands until a
// `take-in.taken` ends the wait, whoever ended it (the named indexer, a revert, a hand take-in or a drop).
const KindTakeInWaits = "take-in-waits"
// The bounds of a take-in wait, from the `take-in.pending` event's own since.
const (
TakeInRevisionBound = 60 * time.Minute
TakeInGroupBound = 30 * time.Minute
)
// takeInRow is the signals table's row of a take-in wait.
const takeInRow = "take-in"
// TakeIn hears one take-in event of the indexer, by its name relative to the indexer (`take-in.<kind>`), the wait's key
// in its body: a pending one starts the wait for its key, whose bound runs from the event's since, and a taken one ends it. A group's
// taken event ends the group's wait only: the revision it becomes is its own key and starts its own, longer wait.
func (w *Watchman) TakeIn(event string, body []byte) {
kind, err := takein.ParseTakeInEvent(event)
if err != nil {
w.say("a take-in event is left: %v", err)
return
}
t, err := takein.DecodeTakeIn(body)
if err != nil {
w.say("the body of %s cannot be read, left: %v", event, err)
return
}
if t.Kind != kind {
w.say("the body of %s says the kind %q, left", event, t.Kind)
return
}
// The wait names the watched branch it is of (design 47 G §493), by the contract's body.
var named meshcatalog.TakeInPending
_ = json.Unmarshal(body, &named)
var taken meshcatalog.TakeInTaken
_ = json.Unmarshal(body, &taken)
key := t.Key
w.mu.Lock()
defer w.mu.Unlock()
w.takeIn(kind, key, t)
w.pendingOf(kind, key, named.Branch)
if kind == takein.TakeInTaken && taken.Branch != "" && taken.Source != 0 && len(taken.Entries) > 0 {
var modules []string
for _, e := range taken.Entries {
modules = append(modules, e.Module)
}
w.takenEntries[fmt.Sprintf("%s.%d", taken.Branch, taken.Source)] = modules // a record's milestone (A-200)
w.rejudgeRecords()
}
}
// SeedTakeIn starts, at the watchman's start and before its consumer on the take-in stream, the wait of every revision
// and group the indexer holds now, as indexer_pending answers them (ADR 0633 §5): the consumer is durable, so the
// pending events it acknowledged before a restart are not heard again, and a wait within its bound would otherwise be
// lost. Each wait's bound runs from its own since, as a pending event's does; the stream's events that follow replace
// or end it. A wait or finding the answer does not name is ended.
func (w *Watchman) SeedTakeIn(a takein.PendingAnswer) {
w.mu.Lock()
defer w.mu.Unlock()
// A wait or finding of a key the answer does not name is ended as a take-in.taken would end it: the finding a previous
// run wrote (read at the start, before the seed), a wait held from an event, a signal standing (design 47, Taken in by
// the indexer it names). Only an answered seed gets here: one that could not ask ends nothing.
named := map[string]bool{}
for _, wait := range a.Waits {
named[wait.Key] = true
}
stale := map[string]bool{}
for _, value := range w.findings {
if f, err := DecodeFinding(value); err == nil && f.Scope == ScopeDelivery && f.Kind == KindTakeInWaits && !named[f.ID] {
stale[f.ID] = true
}
}
for _, due := range w.signals {
if due.Finding.Kind == KindTakeInWaits && due.Finding.Scope == ScopeDelivery && !named[due.Finding.ID] {
stale[due.Finding.ID] = true
}
}
for key := range w.takeInHeld {
if !named[key] {
stale[key] = true
}
}
for _, key := range slices.Sorted(maps.Keys(stale)) {
w.takeIn(takein.TakeInTaken, key, takein.TakeIn{Kind: takein.TakeInTaken, Key: key})
}
for _, wait := range a.Waits {
w.takeIn(takein.TakeInPending, wait.Key, takein.TakeIn{Kind: takein.TakeInPending, Key: wait.Key, What: wait.What,
Merges: wait.Merges, Group: wait.Group, Members: wait.Members, WaitsFor: wait.WaitsFor, Since: wait.Since})
}
}
// pendingOf records or ends the branch an open take-in wait names (design 47 G §497), w.mu held: the head of a branch behind a
// pending revision raises no `pipeline-stands`, and is timed again, from the move of the head, once the branch has none.
func (w *Watchman) pendingOf(kind, key, branch string) {
if kind == takein.TakeInTaken {
branch = w.pendingBranch[key]
delete(w.pendingBranch, key)
if branch != "" && !w.branchPending(branch) {
w.timeHead(branch)
}
return
}
if branch == "" {
return
}
w.pendingBranch[key] = branch
if _, ok := w.heads[branch]; ok {
id := headID(branch)
w.unsignal(headRow, id)
w.unfind(FindingKey(ScopeDelivery, id, KindPipelineStands))
}
}
// takeIn is one take-in event of key, w.mu held.
func (w *Watchman) takeIn(kind, key string, t takein.TakeIn) {
finding := FindingKey(ScopeDelivery, key, KindTakeInWaits)
if kind == takein.TakeInTaken {
delete(w.takeInHeld, key)
w.unsignal(takeInRow, key)
w.unfind(finding)
return
}
bound, what := TakeInRevisionBound, "a source revision waits for the indexer build "+t.WaitsFor
if t.Unknown != "" {
what = "a source revision is held because the indexer cannot learn the build it runs (" + t.Unknown + ")"
}
if t.What == takein.TakeInGroup {
bound, what = TakeInGroupBound, "a delivery group is gathered and its end has not come"
}
var merges []string
for _, m := range t.Merges {
merges = append(merges, m.Repository)
}
f := Finding{Scope: ScopeDelivery, ID: key, Kind: KindTakeInWaits, Severity: Warning, Source: "take-in", Since: t.Since,
Summary: fmt.Sprintf("%s: %s, since %s (%s)", key, what, stamp(t.Since), strings.Join(merges, ", ")),
Said: fmt.Sprintf("held for %s", bound),
Headline: "A merged change is held back by the indexer",
Explanation: "The indexer holds " + what + " and has not taken it in within " + bound.String() + ", so what the merge changes does " +
"not reach the machines.",
Needs: "the indexer build it waits for to run, or the take-in by hand (indexer_take_in_pending), or a drop (indexer_drop_pending)"}
left := bound - w.now().Sub(t.Since)
w.unfind(finding)
w.unsignal(takeInRow, key)
delete(w.takeInHeld, key)
switch {
case left > 0:
w.signal(takeInRow, key, left, signalDue{Do: dueFind, Finding: f})
case !w.takeInCaught:
// Past its bound while the stream is still being replayed: the taken event that ended it may be a few messages on,
// so it is said once the replay has caught up (TakeInCaughtUp), and a taken event before that cancels it.
w.takeInHeld[key] = f
default:
w.find(f)
}
}
// TakeInCaughtUp tells the watchman its consumer has read the stream up to its end (the last message it delivered said no
// message pending, or the consumer had none pending at its bind): every wait past its bound that no taken event ended is
// said now, and the ones heard after are said as they come.
func (w *Watchman) TakeInCaughtUp() {
w.mu.Lock()
defer w.mu.Unlock()
w.takeInCaught = true
for _, key := range slices.Sorted(maps.Keys(w.takeInHeld)) {
w.find(w.takeInHeld[key])
}
w.takeInHeld = map[string]Finding{}
}