Keep a named push from sending builds a policy or a plan holds back

A named push flushed every other machine whose declaration differed from what it was last sent (hq ADR 0083). Under an upgrade policy of `record`, or a plan still waiting on its first machine (ADR 0218), every machine running the module differs, so `push <one>` sent the held build to all of them (hq issue 259). Each send now records which build of each module it carried (node.sent_builds, migration 0061). The cascade, and the bus holder added to a named push, skip a machine any of whose modules would move to a build its policy records or an open plan has not sent it, and say which module, which build, why, and that `push <node>` sends it. A machine whose last send was not recorded is held until it is named. The named machine itself, a whole-mesh push and `push --behind` are unchanged.
2026-10-05 22:22:03 +02:00
parent 8a400d165e
commit 2421b82ad2
13 changed files with 831 additions and 83 deletions
@@ -1158,6 +1158,37 @@ func (i *Inventory) SetUpgradeOf(ctx context.Context, module string, u Upgrade)
 	return nil
 }

+// CurrentBuild is the build a module is at and whether its policy rolls a new one out (novox/hq
+// issue 259).
+type CurrentBuild struct {
+	// Commit is the commit the module's manifest was read at — its `built_from` — and empty for a
+	// module held without a source.
+	Commit string
+	// RollOut is the module's upgrade policy, as Upgrade.RollOut.
+	RollOut bool
+}
+
+// CurrentBuilds is every module's current build and upgrade policy, in one read: what a send records
+// it carried, and what a push compares a machine's last send against.
+func (i *Inventory) CurrentBuilds(ctx context.Context) (map[string]CurrentBuild, error) {
+	rows, err := i.store.Pool().Query(ctx,
+		`select name, coalesce(built_from, ''), upgrade = 'roll-out' from module`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[string]CurrentBuild{}
+	for rows.Next() {
+		var name string
+		var b CurrentBuild
+		if err := rows.Scan(&name, &b.Commit, &b.RollOut); err != nil {
+			return nil, err
+		}
+		out[name] = b
+	}
+	return out, rows.Err()
+}
+
 // Running is every machine assigned a module, in a stable order.
 //
 // **Assigned, not reported.** A machine that is assigned the module and has not applied it yet is
@@ -189,7 +189,7 @@ func TestAMachineIsWaitingWhenWhatItWasSentIsNotWhatItShouldBe(t *testing.T) {
 	}

 	// Sent what it should be: not waiting.
-	if err := inv.RecordSent(ctx, anchor.ID, "aaa"); err != nil {
+	if err := inv.RecordSent(ctx, anchor.ID, "aaa", nil); err != nil {
 		t.Fatal(err)
 	}
 	waiting, err = inv.Waiting(ctx, map[string]string{"anchor": "aaa", "laptop": "bbb"})
@@ -234,7 +234,7 @@ func TestAMachineWithNothingComputedForItIsNotWaiting(t *testing.T) {
 	// It has been sent something before, which is what makes this the case the guard is for: a
 	// machine with a digest and nothing computed for it would compare against the empty string
 	// and look out of date, when the truth is that nobody worked out what it should be.
-	if err := inv.RecordSent(ctx, node.ID, "what-it-got-last-time"); err != nil {
+	if err := inv.RecordSent(ctx, node.ID, "what-it-got-last-time", nil); err != nil {
 		t.Fatal(err)
 	}
 	waiting, err := inv.Waiting(ctx, map[string]string{})
@@ -0,0 +1,14 @@
+-- A send records the build of each module it carried (novox/hq issue 259, ADR 0221).
+--
+-- A named push ends by sending every other machine whose declaration differs from what it was last
+-- sent (ADR 0083). Read from the declaration's digest alone, a module whose upgrade policy records
+-- rather than rolls out, or whose plan sends one machine first (ADR 0218), made every machine running
+-- it differ, so `push <one machine>` sent all of them the build the policy was holding back. Which
+-- build of each module a machine was last sent is what tells a held upgrade from a consequence of the
+-- push, and it is not in a digest.
+--
+-- Module name to the commit its build was made from — the module's `built_from` when the declaration
+-- was composed, empty for a module the mesh holds without a source. NULL for a machine last sent
+-- before this was kept, or sent a declaration by hand: what it carried is not known, and the push
+-- treats such a machine as held until it is pushed by name.
+alter table node add column sent_builds jsonb;
@@ -909,18 +909,53 @@ func (i *Inventory) LastReports(ctx context.Context) ([]Reported, error) {
 	return out, rows.Err()
 }

-// RecordSent keeps a digest of the declaration a machine was last sent.
+// RecordSent keeps a digest of the declaration a machine was last sent, and the build of each module
+// it carried.
 //
 // **A digest rather than the declaration.** The mesh can compute what a machine should be at any
 // moment; keeping a copy would be a second account of it, able to disagree with the first. What
 // cannot be recomputed is what was *actually sent*, and that is the whole difference between a
 // machine that is out of date and one that has never been told.
-func (i *Inventory) RecordSent(ctx context.Context, node, digest string) error {
+//
+// **And which build of each module** (novox/hq issue 259, ADR 0221): module name to the commit its
+// build was made from. A digest cannot say whether a machine differs because a module moved to a build
+// its upgrade policy holds back, or because of something a push made — a grant — and only the second
+// is a push's to send to a machine it did not name. Nil records that it is not known, as for a
+// declaration sent by hand.
+func (i *Inventory) RecordSent(ctx context.Context, node, digest string, builds map[string]string) error {
+	var carried *string
+	if builds != nil {
+		raw, err := json.Marshal(builds)
+		if err != nil {
+			return err
+		}
+		text := string(raw)
+		carried = &text
+	}
 	_, err := i.store.Pool().Exec(ctx,
-		`update node set sent = $2, sent_at = now() where id = $1`, node, digest)
+		`update node set sent = $2, sent_at = now(), sent_builds = $3::jsonb where id = $1`, node, digest, carried)
 	return err
 }

+// SentBuilds is the build of each module a machine was last sent, by its name: module to the commit
+// its build was made from (novox/hq issue 259). Known is false when that was not kept — a machine
+// last sent before it was, sent a declaration by hand, or one the mesh does not know.
+func (i *Inventory) SentBuilds(ctx context.Context, name string) (builds map[string]string, known bool, err error) {
+	var raw []byte
+	err = i.store.Pool().QueryRow(ctx, `select sent_builds from node where name = $1`, name).Scan(&raw)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, false, nil
+	}
+	if err != nil || raw == nil {
+		return nil, false, err
+	}
+	builds = map[string]string{}
+	if err := json.Unmarshal(raw, &builds); err != nil {
+		return nil, false, err
+	}
+	return builds, true, nil
+}
+
 // RecordSentBusUsers keeps a digest of the bus's user list a machine was just sent, by its name
 // (novox/hq issue 249): whether the machine holding the bus must go first is whether this differs
 // from the list composed now.
@@ -0,0 +1,81 @@
+package inventory
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// novox/hq issue 259: a send keeps which build of each module it carried. A machine never sent
+// anything, or sent with nothing recorded — before this was kept, or by hand — is not known, which
+// is not the same as having been sent nothing.
+func TestASendKeepsTheBuildsItCarried(t *testing.T) {
+	inv := ForTest(t)
+	ctx := t.Context()
+	node, err := inv.AddNode(ctx, "anchor")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if builds, known, err := inv.SentBuilds(ctx, "anchor"); err != nil || known || builds != nil {
+		t.Fatalf("a machine never sent anything has known builds %v (%v): %v", builds, known, err)
+	}
+
+	carried := map[string]string{"resolver": "abc123", "network": ""}
+	if err := inv.RecordSent(ctx, node.ID, "d1", carried); err != nil {
+		t.Fatal(err)
+	}
+	builds, known, err := inv.SentBuilds(ctx, "anchor")
+	if err != nil || !known || !reflect.DeepEqual(builds, carried) {
+		t.Fatalf("the builds sent were not kept: %v %v %v", builds, known, err)
+	}
+
+	// Sent with nothing carried: known, and empty.
+	if err := inv.RecordSent(ctx, node.ID, "d2", map[string]string{}); err != nil {
+		t.Fatal(err)
+	}
+	if builds, known, err := inv.SentBuilds(ctx, "anchor"); err != nil || !known || len(builds) != 0 {
+		t.Fatalf("an empty send: %v %v %v", builds, known, err)
+	}
+
+	// Sent by hand: not known, and the digest still recorded.
+	if err := inv.RecordSent(ctx, node.ID, "d3", nil); err != nil {
+		t.Fatal(err)
+	}
+	if builds, known, err := inv.SentBuilds(ctx, "anchor"); err != nil || known || builds != nil {
+		t.Fatalf("a send whose builds are not known read as %v %v: %v", builds, known, err)
+	}
+	if sent, err := inv.Outstanding(ctx, "anchor"); err != nil || sent != "d3" {
+		t.Fatalf("the digest was not recorded with it: %q %v", sent, err)
+	}
+
+	if _, known, err := inv.SentBuilds(ctx, "nobody"); err != nil || known {
+		t.Fatalf("a machine the mesh does not know: %v %v", known, err)
+	}
+}
+
+// A module's current build is the commit its manifest was read at, with its upgrade policy.
+func TestTheCurrentBuildsAreTheCatalogues(t *testing.T) {
+	inv := ForTest(t)
+	ctx := t.Context()
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "resolver", Version: "1"},
+		Source{Repository: "novox/mesh-catalog", BuiltFrom: "c1"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "by-hand", Version: "1"}, Source{}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetUpgradeOf(ctx, "by-hand", Upgrade{RollOut: true}); err != nil {
+		t.Fatal(err)
+	}
+	current, err := inv.CurrentBuilds(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := current["resolver"]; got != (CurrentBuild{Commit: "c1"}) {
+		t.Errorf("resolver is at %+v", got)
+	}
+	if got := current["by-hand"]; got != (CurrentBuild{RollOut: true}) {
+		t.Errorf("a module with no source is at %+v", got)
+	}
+}
@@ -100,7 +100,7 @@ func TestABareAliveDoesNotWipeTheDeclarationThatSaysANodeIsCurrent(t *testing.T)
 	}
 	// The mesh sent this node a declaration, and the node applied it and named which by digest.
 	const digest = "d640d1b6a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829304152"
-	if err := inv.RecordSent(ctx, node.ID, digest); err != nil {
+	if err := inv.RecordSent(ctx, node.ID, digest, nil); err != nil {
 		t.Fatal(err)
 	}
 	if _, err := (link.Enrolment{Inventory: inv}).Heard(ctx, link.Report{