Feature 57 (config and provisioning): modules declare config and provisions, their files rendered from templates; synced with main (issues of feature 57, 874)

2026-10-16 07:37:43 +00:00
parent 1a2c917abf
commit 9652b2d5ce
771 changed files with 52063 additions and 1774 deletions
@@ -0,0 +1,64 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The module's directory, where its manifest and its files/ are.
+const moduleDir = "../.."
+
+// templateText is the text a file resource places on the machine: its template's, in the module's files/
+// (novox/hq ADR 0349 §2). A resource that names no template, or a template that is not there, fails the test.
+func templateText(t *testing.T, r map[string]any) string {
+	t.Helper()
+	name, _ := r["template"].(string)
+	if name == "" {
+		t.Fatalf("resource %v names no template", r["id"])
+	}
+	raw, err := os.ReadFile(filepath.Join(moduleDir, filepath.FromSlash(name)))
+	if err != nil {
+		t.Fatalf("resource %v names %s: %v", r["id"], name, err)
+	}
+	return string(raw)
+}
+
+// No file resource carries its text inline: each names its template in files/, and the build packs files/
+// into the one archive the controller reads the templates back from (novox/hq ADR 0349 §2).
+func TestEveryFileTakesItsTextFromATemplate(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join(moduleDir, "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Resources []map[string]any `json:"resources"`
+		Build     struct {
+			Artifacts []map[string]any `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in files/ and name it as the template", r["id"])
+		}
+		if r["type"] == "file" {
+			templateText(t, r)
+		}
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "files" {
+			packs++
+			if a["name"] != "files" {
+				t.Errorf("the templates archive is named %v, not files", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Errorf("the build packs files/ into %d archives, not one", packs)
+	}
+}
@@ -0,0 +1,63 @@
+# Managed by the mesh (module networkmanager). Replaced on every push; edit the
+# catalogue instead.
+#
+# This machine's uplink is NetworkManager's, and this file is the whole of what
+# the mesh asks of it (novox/hq ADR 0117): leave the resolver file to the mesh,
+# and leave the private network's interface alone. Nothing more. The mesh never
+# declares a connection profile, an address, a route, a wireless network or its
+# credentials — those are joined at the machine, by the person using it, and
+# the link they make is the only channel the mesh reaches this machine over. A
+# push that got a link wrong could not be undone by the next one.
+#
+# A drop-in of the mesh's own, beside NetworkManager.conf and whatever else the
+# operator keeps in this directory. NetworkManager reads the files here sorted by
+# name and a later one wins a key it sets again — so a file of the operator's
+# that sorts after this one (any name starting with a letter does) and sets dns=
+# or unmanaged-devices= overrides it. That is the operator's to decide, and the
+# reason this file sets nothing but the two keys it must.
+#
+# NetworkManager itself is the machine's: the mesh never starts, stops, enables
+# or disables it (its service is declared with no state), because stopping it
+# takes every link down, this machine's channel to the mesh included — and a
+# module unassigned by mistake must not be able to do that. When this file
+# changes, a running NetworkManager is reloaded (its D-Bus Reload call, which
+# re-reads its configuration — NetworkManager(8)), never restarted.
+
+[main]
+# The resolver file is the mesh's: this module writes /etc/resolv.conf itself,
+# listing the mesh's resolvers (novox/hq ADR 0223). Without this line
+# NetworkManager rewrites that file on
+# every connectivity change — every network joined, every lease renewed —
+# and the mesh's resolver is silently replaced while every surface of the mesh
+# still reads green. none: "NetworkManager will not modify resolv.conf. This
+# implies rc-manager unmanaged" (NetworkManager.conf(5), 1.58). On an adopted
+# machine the predecessor wrote the same line in a file of its own; both say one
+# thing, and the predecessor's is retired by hand after the take.
+#
+# Not NetworkManager's own global DNS ([global-dns-domain-*] with rc-manager=file):
+# it writes its own header and composes the options line itself, so it cannot
+# write the mesh's file byte for byte, and the three uplink modules would write
+# three different files for one fact. dns=none, and the file declared beside it.
+dns=none
+
+[keyfile]
+# mesh0 is the private network's interface: the mesh brings it up and the mesh
+# alone configures it. A manager that considers every interface its own could
+# try to configure it, or tear it down on a profile change.
+#
+# unmanaged-devices rather than a [device-mesh0] section with managed=0, because
+# NetworkManager.conf(5) says a device unmanaged by this key "is strictly
+# unmanaged and cannot be overruled by using the API like nmcli device set
+# $IFNAME managed yes", while device*.managed "can be overruled at runtime via
+# D-Bus". The same page adds that device*.managed "may be a better choice" for
+# exactly those reasons — for an interface the operator might want to hand back
+# at runtime. For the mesh's own interface, strict is the point.
+#
+# += rather than =: the same page documents appending to a list-valued key set
+# earlier ("plugins+=another-plugin") as an extension of its key file format,
+# and unmanaged-devices is a device list. = would replace whatever devices the
+# operator already keeps NetworkManager away from; += adds this one to them
+# (novox/hq ADR 0102: a list is added to, never replaced). A file of the
+# operator's read after this one that sets the key with = replaces it again;
+# that is the operator's to decide.
+unmanaged-devices+=interface-name:mesh0
@@ -32,6 +32,11 @@
        "loads": [
          "uplink-tools"
        ]
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
      }
    ]
  },
@@ -52,7 +57,7 @@
      "type": "file",
      "path": "/etc/NetworkManager/conf.d/50-mesh.conf",
      "mode": "0644",
-      "content": "# Managed by the mesh (module networkmanager). Replaced on every push; edit the\n# catalogue instead.\n#\n# This machine's uplink is NetworkManager's, and this file is the whole of what\n# the mesh asks of it (novox/hq ADR 0117): leave the resolver file to the mesh,\n# and leave the private network's interface alone. Nothing more. The mesh never\n# declares a connection profile, an address, a route, a wireless network or its\n# credentials \u2014 those are joined at the machine, by the person using it, and\n# the link they make is the only channel the mesh reaches this machine over. A\n# push that got a link wrong could not be undone by the next one.\n#\n# A drop-in of the mesh's own, beside NetworkManager.conf and whatever else the\n# operator keeps in this directory. NetworkManager reads the files here sorted by\n# name and a later one wins a key it sets again \u2014 so a file of the operator's\n# that sorts after this one (any name starting with a letter does) and sets dns=\n# or unmanaged-devices= overrides it. That is the operator's to decide, and the\n# reason this file sets nothing but the two keys it must.\n#\n# NetworkManager itself is the machine's: the mesh never starts, stops, enables\n# or disables it (its service is declared with no state), because stopping it\n# takes every link down, this machine's channel to the mesh included \u2014 and a\n# module unassigned by mistake must not be able to do that. When this file\n# changes, a running NetworkManager is reloaded (its D-Bus Reload call, which\n# re-reads its configuration \u2014 NetworkManager(8)), never restarted.\n\n[main]\n# The resolver file is the mesh's: this module writes /etc/resolv.conf itself,\n# listing the mesh's resolvers (novox/hq ADR 0223). Without this line\n# NetworkManager rewrites that file on\n# every connectivity change \u2014 every network joined, every lease renewed \u2014\n# and the mesh's resolver is silently replaced while every surface of the mesh\n# still reads green. none: \"NetworkManager will not modify resolv.conf. This\n# implies rc-manager unmanaged\" (NetworkManager.conf(5), 1.58). On an adopted\n# machine the predecessor wrote the same line in a file of its own; both say one\n# thing, and the predecessor's is retired by hand after the take.\n#\n# Not NetworkManager's own global DNS ([global-dns-domain-*] with rc-manager=file):\n# it writes its own header and composes the options line itself, so it cannot\n# write the mesh's file byte for byte, and the three uplink modules would write\n# three different files for one fact. dns=none, and the file declared beside it.\ndns=none\n\n[keyfile]\n# mesh0 is the private network's interface: the mesh brings it up and the mesh\n# alone configures it. A manager that considers every interface its own could\n# try to configure it, or tear it down on a profile change.\n#\n# unmanaged-devices rather than a [device-mesh0] section with managed=0, because\n# NetworkManager.conf(5) says a device unmanaged by this key \"is strictly\n# unmanaged and cannot be overruled by using the API like nmcli device set\n# $IFNAME managed yes\", while device*.managed \"can be overruled at runtime via\n# D-Bus\". The same page adds that device*.managed \"may be a better choice\" for\n# exactly those reasons \u2014 for an interface the operator might want to hand back\n# at runtime. For the mesh's own interface, strict is the point.\n#\n# += rather than =: the same page documents appending to a list-valued key set\n# earlier (\"plugins+=another-plugin\") as an extension of its key file format,\n# and unmanaged-devices is a device list. = would replace whatever devices the\n# operator already keeps NetworkManager away from; += adds this one to them\n# (novox/hq ADR 0102: a list is added to, never replaced). A file of the\n# operator's read after this one that sets the key with = replaces it again;\n# that is the operator's to decide.\nunmanaged-devices+=interface-name:mesh0\n"
+      "template": "files/50-mesh.conf"
    },
    {
      "id": "service",