Settings: changing a module's config without editing its file

Managed files are generated and never edited, so somebody's intention about one
has to live where the generator can see it. It does now: the module ships
defaults, settings go over the top by key, and the file is produced from both.
Upstream can rewrite its half freely and the keys somebody chose survive.

Two layers, both from the start. The mesh's settings for a module, then one
machine's over those. A node that differs is expressed by differing, rather
than by restating everything the rest already say -- which would pin all of it
against future changes for no reason.

An override beats a default and there is nothing to resolve. A setting is a
statement about that key made deliberately; the default was only ever what to
do in the absence of one. So when upstream changes a key somebody has set,
there is no conflict, no merge markers, and nothing to ask.

Nested blocks merge and lists are replaced whole. Setting one field of a block
must not delete its siblings, or every setting would restate the whole block
and pin all of it. A list that merged element-wise could neither be shortened
nor reordered, and there is no correct guess about which element is "the same
one".

A module can keep specific keys for itself -- a socket path its own code
depends on -- and setting one is REFUSED rather than ignored. A setting quietly
dropped is somebody believing they changed something.

Settings that reach nothing are named at the moment they would be used, not
discovered later by the machine not behaving differently.

`plan --files` prints what a machine would be given before it is sent, because
"1 resource" does not tell you whether the merge landed.

One test kept with a note that it does not defend this code: output stability
comes from Go's encoder sorting map keys, so it passes with the merging
removed. Worth having as the thing that would catch a change of encoder, but it
is not evidence about anything written here, and it was checked.

internal/catalogue/resolve.go

@@ -272,15 +272,22 @@ func checkResources(modules []Manifest) []string {
 	return problems
 }
 
-// Declaration is everything the resolved modules put on the node, as the host reads it.
+// SettingsBy is the layers that apply to each module, keyed by module name.
+type SettingsBy map[string][]Layer
+
+// Declaration is everything the resolved modules put on the node, with settings applied.
 //
 // Resource identities are prefixed with the module they came from. Two modules may reasonably
 // both call something "config", and without this the second would silently replace the first —
 // the node applying one of them and reporting success.
-func (r Resolution) Declaration() []map[string]any {
+func (r Resolution) Declaration(settings SettingsBy) ([]map[string]any, error) {
 	var out []map[string]any
 	for _, m := range r.Modules {
-		for _, resource := range m.Resources {
+		for _, unsettled := range m.Resources {
+			resource, err := ApplySettings(unsettled, settings[m.Module])
+			if err != nil {
+				return nil, err
+			}
 			copied := map[string]any{}
 			for k, v := range resource {
 				copied[k] = v
@@ -298,5 +305,5 @@ func (r Resolution) Declaration() []map[string]any {
 			out = append(out, copied)
 		}
 	}
-	return out
+	return out, nil
 }

internal/catalogue/resolve_test.go

@@ -201,7 +201,7 @@ func TestResourceIdentitiesCarryTheirModule(t *testing.T) {
 		t.Fatal(err)
 	}
 	seen := map[string]bool{}
-	for _, r := range got.Declaration() {
+	for _, r := range mustDeclare(t, got) {
 		id := r["id"].(string)
 		if seen[id] {
 			t.Errorf("two resources share the identity %q", id)
@@ -226,7 +226,7 @@ func TestWhatAServiceReflectsIsQualifiedToo(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	for _, r := range got.Declaration() {
+	for _, r := range mustDeclare(t, got) {
 		if r["id"] == "thing.svc" {
 			if got := fmt.Sprint(r["restart-on"]); got != "[thing.conf]" {
 				t.Errorf("a service reflects %s, which is not a resource in the declaration", got)
@@ -317,3 +317,12 @@ func TestARequirementNamingAModuleMeansThatModule(t *testing.T) {
 		t.Errorf("unexpected refusal: %v", err)
 	}
 }
+
+func mustDeclare(t *testing.T, r Resolution) []map[string]any {
+	t.Helper()
+	out, err := r.Declaration(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}

internal/catalogue/settings.go

@@ -0,0 +1,166 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// Settings are how somebody changes a config file a module owns, without editing it.
+//
+// Managed files are generated and never edited (novox/hq ADR 0011), so a person's intention has
+// to be expressed somewhere the generator can see it. Then the file is produced from the module's
+// defaults and that intention together, and upstream can rewrite its half freely.
+//
+// **An override beats a default, so there is nothing to resolve.** When the module changes a key
+// somebody has set, the setting wins — it was a statement about that key, made deliberately, and
+// the default was only ever what to do in the absence of one. This is the same shape as the rest
+// of the mesh refusing to guess: there is no guess to make.
+
+// Merge is how a file's content is combined with settings. A module names one per resource.
+const (
+	// MergeJSON treats the content as a JSON document and merges settings into it by key.
+	MergeJSON = "json"
+)
+
+// Layer is one source of settings, in the order they are applied.
+type Layer struct {
+	// Where these came from, for saying which layer set a value.
+	From   string
+	Values map[string]any
+}
+
+// ApplySettings produces a resource's final content from the module's own and the layers over it.
+//
+// Layers are applied in order, so a later one beats an earlier one — the mesh's settings for a
+// module first, then this node's. A node that differs from the rest is expressed by differing,
+// rather than by repeating everything the rest already say.
+func ApplySettings(resource map[string]any, layers []Layer) (map[string]any, error) {
+	how, _ := resource["merge"].(string)
+	if how == "" {
+		// Not a mergeable file. Settings for it are ignored rather than silently doing nothing
+		// somewhere else — see UnusedSettings, which is what says so.
+		return resource, nil
+	}
+	if how != MergeJSON {
+		return nil, fmt.Errorf(
+			"%v says it merges as %q, and this control plane knows how to merge %q",
+			resource["id"], how, MergeJSON)
+	}
+
+	content, _ := resource["content"].(string)
+	var base map[string]any
+	if strings.TrimSpace(content) == "" {
+		base = map[string]any{}
+	} else if err := json.Unmarshal([]byte(content), &base); err != nil {
+		return nil, fmt.Errorf("%v says it merges as JSON and its content is not JSON: %w",
+			resource["id"], err)
+	}
+
+	protected := map[string]bool{}
+	for _, k := range stringsOf(resource["protected"]) {
+		protected[k] = true
+	}
+
+	merged := deepCopy(base)
+	for _, layer := range layers {
+		for key, value := range layer.Values {
+			if protected[key] {
+				// The module said it must own this one. Refused rather than ignored: a setting
+				// that is quietly dropped is somebody believing they changed something.
+				return nil, fmt.Errorf(
+					"%s sets %q on %v, and that module keeps %q for itself — it is not settable",
+					layer.From, key, resource["id"], key)
+			}
+			merged[key] = mergeValue(merged[key], value)
+		}
+	}
+
+	out := map[string]any{}
+	for k, v := range resource {
+		out[k] = v
+	}
+	// Keys sorted by the encoder, so the same settings always produce the same bytes. A file
+	// whose lines move for no reason makes every reconcile look like a change, and anything
+	// reflecting it would restart for ever.
+	rendered, err := json.MarshalIndent(merged, "", "  ")
+	if err != nil {
+		return nil, err
+	}
+	out["content"] = string(rendered) + "\n"
+	delete(out, "merge")
+	delete(out, "protected")
+	return out, nil
+}
+
+// mergeValue combines one value with the one over it.
+//
+// Two objects merge key by key, so setting one field of a nested block does not delete its
+// siblings. Anything else is replaced whole: a list that merged element-wise could neither be
+// shortened nor reordered, and there is no correct guess about which element is "the same one".
+func mergeValue(under, over any) any {
+	underMap, isUnderMap := under.(map[string]any)
+	overMap, isOverMap := over.(map[string]any)
+	if !isUnderMap || !isOverMap {
+		return over
+	}
+	merged := deepCopy(underMap)
+	for k, v := range overMap {
+		merged[k] = mergeValue(merged[k], v)
+	}
+	return merged
+}
+
+func deepCopy(in map[string]any) map[string]any {
+	out := map[string]any{}
+	for k, v := range in {
+		if nested, ok := v.(map[string]any); ok {
+			out[k] = deepCopy(nested)
+			continue
+		}
+		out[k] = v
+	}
+	return out
+}
+
+// UnusedSettings names settings that reached no file.
+//
+// Somebody who sets a key on a module with nothing mergeable, or misspells one, has changed
+// nothing — and would find out by the machine not behaving differently, which is the slowest
+// way there is. This is what makes that visible at the moment they set it.
+func UnusedSettings(m Manifest, layers []Layer) []string {
+	mergeable := false
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how != "" {
+			mergeable = true
+		}
+	}
+	if mergeable {
+		return nil
+	}
+
+	var unused []string
+	for _, layer := range layers {
+		for key := range layer.Values {
+			unused = append(unused, fmt.Sprintf("%s sets %q, and %s has no file to merge it into",
+				layer.From, key, m.Module))
+		}
+	}
+	sort.Strings(unused)
+	return unused
+}
+
+func stringsOf(v any) []string {
+	raw, ok := v.([]any)
+	if !ok {
+		return nil
+	}
+	var out []string
+	for _, item := range raw {
+		if s, ok := item.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}

internal/catalogue/settings_test.go

@@ -0,0 +1,181 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func file(content string, protected ...string) map[string]any {
+	r := map[string]any{"id": "conf", "type": "file", "path": "/etc/thing.json",
+		"merge": MergeJSON, "content": content}
+	if len(protected) > 0 {
+		var as []any
+		for _, p := range protected {
+			as = append(as, p)
+		}
+		r["protected"] = as
+	}
+	return r
+}
+
+func merged(t *testing.T, resource map[string]any, layers ...Layer) map[string]any {
+	t.Helper()
+	out, err := ApplySettings(resource, layers)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(out["content"].(string)), &parsed); err != nil {
+		t.Fatalf("the merged file is not JSON: %v", err)
+	}
+	return parsed
+}
+
+func TestASettingBeatsTheModulesDefault(t *testing.T) {
+	// The whole rule. A setting is a statement about that key made deliberately; the default was
+	// only ever what to do in the absence of one. So there is nothing to resolve.
+	got := merged(t, file(`{"port":8080,"log":"info"}`),
+		Layer{From: "node", Values: map[string]any{"port": 9090.0}})
+
+	if got["port"] != 9090.0 {
+		t.Errorf("port is %v; the setting should have won", got["port"])
+	}
+	if got["log"] != "info" {
+		t.Errorf("log is %v; a key nobody set should keep the module's value", got["log"])
+	}
+}
+
+func TestUpstreamKeepsTheKeysNobodySet(t *testing.T) {
+	// The point of merging rather than replacing: the module can change its half freely and only
+	// the keys somebody actually cares about are pinned.
+	got := merged(t, file(`{"port":8080,"log":"info","workers":4}`),
+		Layer{From: "node", Values: map[string]any{"log": "debug"}})
+
+	if got["port"] != 8080.0 || got["workers"] != 4.0 {
+		t.Errorf("the module's other keys did not survive: %v", got)
+	}
+}
+
+func TestTheNodeBeatsTheMesh(t *testing.T) {
+	// Two layers, in order. A node that differs is expressed by differing, rather than by
+	// repeating everything the rest of the mesh already says.
+	got := merged(t, file(`{"log":"info"}`),
+		Layer{From: "mesh", Values: map[string]any{"log": "warn", "workers": 8.0}},
+		Layer{From: "node", Values: map[string]any{"log": "debug"}})
+
+	if got["log"] != "debug" {
+		t.Errorf("log is %v; the node's setting should have won", got["log"])
+	}
+	if got["workers"] != 8.0 {
+		t.Errorf("workers is %v; a mesh-wide setting the node did not touch should stand", got["workers"])
+	}
+}
+
+func TestNestedBlocksMergeRatherThanReplace(t *testing.T) {
+	// Setting one field of a block must not delete its siblings, or every setting would have to
+	// restate the whole block and would then pin all of it against upstream.
+	got := merged(t, file(`{"http":{"gzip":"off","timeout":30,"port":80}}`),
+		Layer{From: "node", Values: map[string]any{
+			"http": map[string]any{"gzip": "on"}}})
+
+	block := got["http"].(map[string]any)
+	if block["gzip"] != "on" {
+		t.Errorf("gzip is %v", block["gzip"])
+	}
+	if block["timeout"] != 30.0 || block["port"] != 80.0 {
+		t.Errorf("the block's other fields were lost: %v", block)
+	}
+}
+
+func TestAListIsReplacedWholeNotMerged(t *testing.T) {
+	// A list that merged element-wise could neither be shortened nor reordered, and there is no
+	// correct guess about which element is "the same one".
+	got := merged(t, file(`{"hosts":["a","b","c"]}`),
+		Layer{From: "node", Values: map[string]any{"hosts": []any{"x"}}})
+
+	hosts := got["hosts"].([]any)
+	if len(hosts) != 1 || hosts[0] != "x" {
+		t.Errorf("hosts is %v; a list is replaced whole", hosts)
+	}
+}
+
+func TestAProtectedKeyIsRefusedNotIgnored(t *testing.T) {
+	// A setting quietly dropped is somebody believing they changed something. Refusing says so
+	// while they are looking at it.
+	_, err := ApplySettings(file(`{"socket":"/run/thing.sock","log":"info"}`, "socket"),
+		[]Layer{{From: "node", Values: map[string]any{"socket": "/tmp/mine.sock"}}})
+	if err == nil {
+		t.Fatal("a protected key was overridden")
+	}
+	if !strings.Contains(err.Error(), "socket") || !strings.Contains(err.Error(), "not settable") {
+		t.Errorf("the refusal does not say which key or why: %v", err)
+	}
+}
+
+func TestSettingsAroundAProtectedKeyStillApply(t *testing.T) {
+	got := merged(t, file(`{"socket":"/run/thing.sock","log":"info"}`, "socket"),
+		Layer{From: "node", Values: map[string]any{"log": "debug"}})
+	if got["log"] != "debug" {
+		t.Errorf("log is %v", got["log"])
+	}
+}
+
+func TestTheSameSettingsAlwaysProduceTheSameBytes(t *testing.T) {
+	// A file whose lines move for no reason makes every reconcile look like a change, and a
+	// service reflecting it would restart for ever.
+	//
+	// Note what this defends: Go's JSON encoder sorts map keys, so the stability comes from the
+	// standard library and this passes with the merging removed. It is worth keeping as the thing
+	// that would catch a move to an encoder that does not sort — but it is not evidence about the
+	// code below it, and it was checked.
+	resource := file(`{"b":2,"a":1,"c":3}`)
+	layer := Layer{From: "node", Values: map[string]any{"z": 26.0, "a": 100.0}}
+
+	first, err := ApplySettings(resource, []Layer{layer})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 5; i++ {
+		again, err := ApplySettings(resource, []Layer{layer})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if again["content"] != first["content"] {
+			t.Fatal("the same settings produced different bytes")
+		}
+	}
+}
+
+func TestAFileThatDoesNotMergeIsLeftAlone(t *testing.T) {
+	plain := map[string]any{"id": "conf", "type": "file", "path": "/etc/thing",
+		"content": "not structured at all\n"}
+	out, err := ApplySettings(plain, []Layer{{From: "node", Values: map[string]any{"x": 1}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out["content"] != "not structured at all\n" {
+		t.Errorf("a file with no merge rule was changed: %v", out["content"])
+	}
+}
+
+func TestSettingsThatReachNothingAreNamed(t *testing.T) {
+	// Somebody who misspells a module, or sets a key on one with nothing mergeable, has changed
+	// nothing — and would otherwise find out by the machine not behaving differently, which is
+	// the slowest way there is.
+	m := Manifest{Module: "thing", Resources: []map[string]any{
+		{"id": "conf", "type": "file", "path": "/etc/thing", "content": "plain"},
+	}}
+	unused := UnusedSettings(m, []Layer{{From: "node", Values: map[string]any{"port": 1}}})
+	if len(unused) != 1 || !strings.Contains(unused[0], "no file to merge it into") {
+		t.Errorf("settings that reached nothing were not named: %v", unused)
+	}
+}
+
+func TestContentThatIsNotJSONIsRefusedWhereSomebodyIsLooking(t *testing.T) {
+	// Rather than on the machine, at apply time, as a file the program cannot read.
+	_, err := ApplySettings(file(`this is not json`), nil)
+	if err == nil {
+		t.Fatal("a module claiming to merge as JSON shipped something else and was accepted")
+	}
+}