The controller answers each node's placement from its own store, read-only, for the seed of the catalogue's placement files: the one verb of its exit (issue 1126, ADR 0555 §6; the operator 2026-10-26 19:06:40)

2026-10-26 19:16:09 +01:00
parent 2ecfbb3a29
commit fb2f5a2962
8 changed files with 135 additions and 4 deletions
@@ -133,9 +133,14 @@ func nodeCommand(ctx context.Context, args []string) error {
 		// refuse (novox/hq issue 358). Read-only on the node and here, so a verb may run it too.
 		return nodeJudgeDirectories(ctx, open, args[1:])

+	case "placement-export":
+		// Each node's placement as the catalogue's placement file says it (novox/hq ADR 0555 §6): read-only, so a verb
+		// may run it.
+		return placementExport(ctx, open, args[1:])
+
 	default:
 		return fmt.Errorf("node has no %q; it has add, list, show, public-domain, account, agent-account, hand-over, "+
-			"setuid-search and judge-directories", args[0])
+			"setuid-search, judge-directories and placement-export", args[0])
 	}
 }

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"sort"
+
+	"git.novox.be/novox/mesh-sdk/go/compose/frombus"
+	"git.novox.be/novox/mesh-sdk/go/delivery"
+)
+
+// placementExport prints each node's placement as the catalogue's placement file says it (novox/hq ADR 0555 §6, issue
+// 1126): what a person decided of the node and where its modules run, read by this controller's own code from its own
+// store, as JSON keyed by node. The one verb the controller gains for its exit (the operator, 2026-10-26 19:06:40, ADR
+// 0547 §1's one exception besides §5's grant): read once by the seed of the placement files, whose pull request merges
+// only when its composition check composes every node equal to what it runs. It reads the same Input every composition
+// of this controller reads (readMeshAndNodes, readSettings) and writes nothing.
+//
+// It moves a piece of the research "The controller, NATS-native": the controller's last node data (node rows, placement,
+// ports, pins, bindings, config placement) leaves it for the catalogue, before its exit at ADR 0547's third milestone.
+func placementExport(ctx context.Context, open *stores, args []string) error {
+	if len(args) > 1 {
+		return errors.New("node placement-export [<name>]")
+	}
+	in, _, err := readMeshAndNodes(ctx, open)
+	if err != nil {
+		return err
+	}
+	if _, err := readSettings(ctx, open, &in); err != nil {
+		return err
+	}
+	var names []string
+	if len(args) == 1 {
+		names = []string{args[0]}
+	} else {
+		for _, n := range in.Nodes {
+			names = append(names, n.Name)
+		}
+		sort.Strings(names)
+	}
+	out := make(map[string]delivery.Placement, len(names))
+	for _, name := range names {
+		p, err := frombus.Export(in, name)
+		if err != nil {
+			return err
+		}
+		out[name] = p
+	}
+	return printJSON(out)
+}
@@ -0,0 +1,64 @@
+//go:build integration
+
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/compose/frombus"
+	sdkdelivery "git.novox.be/novox/mesh-sdk/go/delivery"
+	"git.novox.be/novox/mesh-sdk/go/overlay"
+)
+
+// Issue 1126 (novox/hq ADR 0555 §6, the operator's one export verb of 2026-10-26 19:06:40): `node placement-export`
+// answers, from the real store, each node's placement as the catalogue's placement file says it: what a person decided
+// of the node (its endpoint, site, hub and address on the private network) and its modules in the order the composition
+// reads them, exactly frombus.Export of the input this controller composes from; one node when named; a node the store
+// lacks is refused.
+func TestThePlacementExportIsEachNodesPlacementFromTheStore(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	in, _, err := readMeshAndNodes(ctx, open)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readSettings(ctx, open, &in); err != nil {
+		t.Fatal(err)
+	}
+	var all map[string]sdkdelivery.Placement
+	if err := json.Unmarshal([]byte(stdoutOf(t, func() error { return placementExport(ctx, open, nil) })), &all); err != nil {
+		t.Fatal(err)
+	}
+	if len(all) != 2 {
+		t.Fatalf("exported %d nodes, want anchor and laptop", len(all))
+	}
+	for i, name := range []string{"anchor", "laptop"} {
+		got := all[name]
+		d := got.Decided
+		if d.Endpoint != name+".example:51820" || d.Site != "here" || d.Hub != (name == "anchor") || d.Address != []string{"10.77.0.1", "10.77.0.2"}[i] {
+			t.Errorf("%s's decided facts are %+v", name, d)
+		}
+		if a := got.Assigned(); len(a) == 0 || !strings.Contains(strings.Join(a, ","), overlay.Name) {
+			t.Errorf("%s's modules are %v, want the private network among them", name, a)
+		}
+		want, err := frombus.Export(in, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !sdkdelivery.SamePlacement(got, want) {
+			t.Errorf("%s's export differs from frombus.Export of the controller's own input:\n%+v\n%+v", name, got, want)
+		}
+	}
+	var one map[string]sdkdelivery.Placement
+	if err := json.Unmarshal([]byte(stdoutOf(t, func() error { return placementExport(ctx, open, []string{"laptop"}) })), &one); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := one["laptop"]; !ok || len(one) != 1 {
+		t.Errorf("one node named exported %v", one)
+	}
+	if err := placementExport(ctx, open, []string{"stranger"}); err == nil {
+		t.Error("a node the store lacks was exported")
+	}
+}
@@ -349,6 +349,11 @@ func (a *verbArguments) commandLine() ([]string, error) {
 			return nil, err
 		}
 		return []string{"node", "judge-directories", str("node")}, nil
+	case "placement-export":
+		if node := str("node"); node != "" {
+			return []string{"node", "placement-export", node}, nil
+		}
+		return []string{"node", "placement-export"}, nil
 	case "modules":
 		return []string{"module", "list", "--json"}, nil
 	case "seats":
@@ -1400,7 +1405,9 @@ func seatAnnouncement(handlers map[string]link.ToolHandler) micro.Info {
 // nodeReads are the `node` subcommands a verb may run: the ones that only read.
 var nodeReads = map[string]bool{"list": true, "show": true,
 	// Read-only on the node too: the engine judges its directories and changes nothing (novox/hq issue 358).
-	"judge-directories": true}
+	"judge-directories": true,
+	// Each node's placement as the catalogue's placement file says it, read from the store (novox/hq ADR 0555 §6).
+	"placement-export": true}

 // flagsOnly says a command line's rest names no subcommand: empty, or beginning with a flag. For a command
 // with no subcommands every word is a flag, its value or a name it reads.