Refuse config keys that no setting has (closes #419)

A misspelled or unknown config key was accepted silently, so a typo in exclude backed up everything it meant to leave out. Loading now refuses a key that no setting has, at any depth, naming its dotted path and, when it is in the file, its line; keys brought in by ${...} references are checked too. config set refuses an unknown key. A top-level env: section stays accepted, since the config library uses it. Anchors that contain themselves fail with an error.

Model: opus-5-5

internal/config/keys.go

@@ -0,0 +1,214 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// yamlMergeTag is the tag YAML gives a merge key (<<), which adds the keys
+// of the map it names to the map it sits in.
+const yamlMergeTag = "!!merge"
+
+// EnvSection is the top-level key of a map of environment variables that
+// smartconfig sets while it loads the config. It is not a vaultik setting,
+// so its keys are not checked.
+const EnvSection = "env"
+
+var (
+	errUnknownKey           = errors.New("unknown config key")
+	errAnchorContainsItself = errors.New("anchor contains itself")
+)
+
+// nodeAndType is a node of a parsed config and the setting type it is
+// checked against.
+type nodeAndType struct {
+	node *yaml.Node
+	typ  reflect.Type
+}
+
+// SettingType returns the type of the setting that the dotted key names in
+// Config, following the fields' yaml tags, as for s3.bucket or
+// snapshots.home.exclude.0. A snapshot name or a list index may be any
+// word. It returns an unknown key error when no setting has that key.
+func SettingType(keys []string) (reflect.Type, error) {
+	typ := reflect.TypeFor[Config]()
+
+	for _, key := range keys {
+		switch {
+		case typ.Kind() == reflect.Map || typ.Kind() == reflect.Slice:
+			typ = typ.Elem()
+		case typ.Kind() == reflect.Struct:
+			field, ok := yamlField(typ, key)
+			if !ok {
+				return nil, fmt.Errorf("%w %q", errUnknownKey, strings.Join(keys, "."))
+			}
+
+			typ = field.Type
+		default:
+			return nil, fmt.Errorf("%w %q", errUnknownKey, strings.Join(keys, "."))
+		}
+	}
+
+	return typ, nil
+}
+
+// yamlField returns the field of struct type typ whose yaml tag names key.
+func yamlField(typ reflect.Type, key string) (reflect.StructField, bool) {
+	for field := range typ.Fields() {
+		name, _, _ := strings.Cut(field.Tag.Get("yaml"), ",")
+		if name == key && name != "-" {
+			return field, true
+		}
+	}
+
+	return reflect.StructField{}, false
+}
+
+// checkKeys returns an error naming the first key in node, a parsed config
+// or part of one at the dotted path, that no setting in typ has. The error
+// gives the key's line in the file, when it has one. A value of the wrong
+// type is left for the YAML decoder to report. following holds the aliases
+// the walk is inside. Meeting one of them again means its anchor contains
+// itself, which is an error. checked holds each anchored node the walk has
+// checked completely, with the type it was checked against. An alias to
+// that node is not followed again for that type.
+func checkKeys(node *yaml.Node, typ reflect.Type, path string,
+	following map[*yaml.Node]bool, checked map[nodeAndType]bool,
+) error {
+	switch node.Kind {
+	case yaml.DocumentNode:
+		for _, child := range node.Content {
+			err := checkKeys(child, typ, path, following, checked)
+			if err != nil {
+				return err
+			}
+		}
+	case yaml.AliasNode:
+		if following[node] {
+			return fmt.Errorf("%w: %q on line %d",
+				errAnchorContainsItself, node.Value, node.Line)
+		}
+
+		target := nodeAndType{node.Alias, typ}
+		if checked[target] {
+			return nil
+		}
+
+		following[node] = true
+		defer delete(following, node)
+
+		err := checkKeys(node.Alias, typ, path, following, checked)
+		if err != nil {
+			return err
+		}
+
+		checked[target] = true
+	case yaml.SequenceNode:
+		if typ.Kind() != reflect.Slice {
+			return nil
+		}
+
+		for i, child := range node.Content {
+			err := checkKeys(child, typ.Elem(), joinKey(path, strconv.Itoa(i)),
+				following, checked)
+			if err != nil {
+				return err
+			}
+		}
+	case yaml.MappingNode:
+		return checkMappingKeys(node, typ, path, following, checked)
+	case yaml.ScalarNode:
+		// A scalar has no keys.
+	}
+
+	return nil
+}
+
+// checkFilledKeys is checkKeys for data, the config after smartconfig has
+// filled in its ${...} references. A key that a reference brings in is not
+// in the file, and the copy that Encode makes has no line numbers.
+func checkFilledKeys(data map[string]any) error {
+	var filled yaml.Node
+
+	err := filled.Encode(data)
+	if err != nil {
+		return fmt.Errorf("failed to marshal config data: %w", err)
+	}
+
+	return checkKeys(&filled, reflect.TypeFor[Config](), "",
+		map[*yaml.Node]bool{}, map[nodeAndType]bool{})
+}
+
+// checkMappingKeys is checkKeys for a map.
+func checkMappingKeys(node *yaml.Node, typ reflect.Type, path string,
+	following map[*yaml.Node]bool, checked map[nodeAndType]bool,
+) error {
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		key, value := node.Content[i], node.Content[i+1]
+
+		if key.Tag == yamlMergeTag {
+			// The value is one map or a list of maps.
+			merged := []*yaml.Node{value}
+			if value.Kind == yaml.SequenceNode {
+				merged = value.Content
+			}
+
+			for _, m := range merged {
+				err := checkKeys(m, typ, path, following, checked)
+				if err != nil {
+					return err
+				}
+			}
+
+			continue
+		}
+
+		keyPath := joinKey(path, key.Value)
+		if keyPath == EnvSection {
+			continue
+		}
+
+		var valueType reflect.Type
+
+		switch {
+		case typ.Kind() == reflect.Map:
+			valueType = typ.Elem()
+		case typ.Kind() == reflect.Struct:
+			field, ok := yamlField(typ, key.Value)
+			if !ok && key.Line == 0 {
+				// A key that a ${...} reference brought in has no line.
+				return fmt.Errorf("%w %q", errUnknownKey, keyPath)
+			}
+
+			if !ok {
+				return fmt.Errorf("%w %q on line %d",
+					errUnknownKey, keyPath, key.Line)
+			}
+
+			valueType = field.Type
+		default:
+			return nil
+		}
+
+		err := checkKeys(value, valueType, keyPath, following, checked)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// joinKey appends key to the dotted path.
+func joinKey(path, key string) string {
+	if path == "" {
+		return key
+	}
+
+	return path + "." + key
+}