feat(configuration): report config keys no decode target consumed
decodeTOML discarded toml.DecodeFile's metadata, so a misspelled or renamed key parsed, validated and silently did nothing. Document.UnknownKeys now carries the dotted key paths a loaded file's decode targets left undecoded. One file feeds two decode targets (&doc.Config and &doc.Scheduling), so a key legitimately owned by one shows up as undecoded in the other -- a key is only reported when both leave it undecoded (unknownKeys intersects the two sets), which is what keeps a valid [scheduling] block from being misreported as unknown on every config that uses it. YAML config sources are unchanged for now (no equivalent metadata hook in the yaml decoder); this covers the TOML path, which is what config.example.toml, every shipped deployments/*.toml profile, and install.sh's generated config.toml all use.
This commit is contained in:
1 parent
9942ac4487
commit
9b2fb4a82c
4 files changed
+237
-18
No files matched your search
@@ -11,23 +11,43 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
)
|
||||
|
||||
func decodeConfigFile(path string, target any) error {
|
||||
// decodeConfigFileKeys decodes path into target, dispatching on extension,
|
||||
// additionally returning target's undecoded top-level keys for a TOML
|
||||
// source (see decodeTOMLKeys). A YAML source has no equivalent hook yet
|
||||
// (plan-config-drift.md step 1 note) and always reports none -- unchanged
|
||||
// behaviour, not a claim of completeness.
|
||||
func decodeConfigFileKeys(path string, target any) ([]string, error) {
|
||||
switch filepath.Ext(path) {
|
||||
case ".yaml", ".yml":
|
||||
return decodeYAML(path, target)
|
||||
return nil, decodeYAML(path, target)
|
||||
case ".toml":
|
||||
return decodeTOML(path, target)
|
||||
return decodeTOMLKeys(path, target)
|
||||
default:
|
||||
return fmt.Errorf("%w: config file %s must end in .toml, .yaml, or .yml", ErrUnreadable, path)
|
||||
return nil, fmt.Errorf("%w: config file %s must end in .toml, .yaml, or .yml", ErrUnreadable, path)
|
||||
}
|
||||
}
|
||||
|
||||
// decodeTOML decodes a TOML file into target.
|
||||
func decodeTOML(path string, target any) error {
|
||||
if _, err := toml.DecodeFile(path, target); err != nil {
|
||||
return fmt.Errorf("%w: parsing %s: %w", ErrUnreadable, path, err)
|
||||
// decodeTOMLKeys decodes a TOML file into target, additionally
|
||||
// returning the top-level dotted key paths present in the file that
|
||||
// target did not consume (toml.MetaData.Undecoded()). A single decode
|
||||
// target's undecoded set is not by itself "unknown" -- see Hazard 1 in
|
||||
// .local/issue-tracker/plan-config-drift.md, one file can legitimately
|
||||
// feed more than one target -- callers combine this with the other
|
||||
// target's undecoded set before treating anything as a real unknown key.
|
||||
func decodeTOMLKeys(path string, target any) ([]string, error) {
|
||||
meta, err := toml.DecodeFile(path, target)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%w: parsing %s: %w", ErrUnreadable, path, err)
|
||||
}
|
||||
return nil
|
||||
undecoded := meta.Undecoded()
|
||||
if len(undecoded) == 0 {
|
||||
return nil, nil
|
||||
}
|
||||
keys := make([]string, len(undecoded))
|
||||
for i, k := range undecoded {
|
||||
keys[i] = k.String()
|
||||
}
|
||||
return keys, nil
|
||||
}
|
||||
|
||||
// decodeYAML decodes a YAML file into target.
|
||||
|
||||
@@ -5,6 +5,7 @@ import (
|
||||
"log/slog"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
)
|
||||
@@ -25,6 +26,15 @@ type Document struct {
|
||||
|
||||
// Provenance lists the files that produced Config, in precedence order.
|
||||
Provenance Provenance
|
||||
|
||||
// UnknownKeys lists dotted TOML key paths present in a loaded file that
|
||||
// no decode target consumed (e.g. "containers.max_concurrancy" for a
|
||||
// misspelled max_concurrency) -- present so a typo'd key is visible
|
||||
// instead of silently parsing, validating and doing nothing. Sorted
|
||||
// and de-duplicated. A missing key that a YAML config source carries
|
||||
// is not yet detected here (plan-config-drift.md step 1 note); this
|
||||
// is TOML-only for now.
|
||||
UnknownKeys []string
|
||||
}
|
||||
|
||||
// Loader reads configuration from files. The zero value is not usable; call
|
||||
@@ -151,27 +161,74 @@ func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Documen
|
||||
func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) {
|
||||
doc := &Document{}
|
||||
|
||||
if err := decodeConfigFile(basePath, &doc.Config); err != nil {
|
||||
cfgKeys, err := decodeConfigFileKeys(basePath, &doc.Config)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := decodeSchedulingFile(basePath, &doc.Scheduling); err != nil {
|
||||
schedKeys, err := decodeSchedulingFileKeys(basePath, &doc.Scheduling)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...)
|
||||
doc.Provenance.record(Origin{Path: basePath, Role: RoleMain, Layer: LayerBase})
|
||||
|
||||
if overlayPath != "" {
|
||||
if err := decodeConfigFile(overlayPath, &doc.Config); err != nil {
|
||||
cfgKeys, err = decodeConfigFileKeys(overlayPath, &doc.Config)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := decodeSchedulingFile(overlayPath, &doc.Scheduling); err != nil {
|
||||
schedKeys, err = decodeSchedulingFileKeys(overlayPath, &doc.Scheduling)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...)
|
||||
doc.Provenance.record(Origin{Path: overlayPath, Role: RoleMain, Layer: LayerOverlay})
|
||||
}
|
||||
|
||||
return l.finalize(doc)
|
||||
}
|
||||
|
||||
// unknownKeys returns the keys present in both a and b: one config file
|
||||
// feeds more than one decode target (&doc.Config and &doc.Scheduling), so
|
||||
// a key legitimately owned by one target decodes cleanly there and only
|
||||
// shows up in the other target's undecoded set. Only a key neither target
|
||||
// consumed is a real unknown key (Hazard 1, plan-config-drift.md).
|
||||
func unknownKeys(a, b []string) []string {
|
||||
if len(a) == 0 || len(b) == 0 {
|
||||
return nil
|
||||
}
|
||||
inB := make(map[string]bool, len(b))
|
||||
for _, k := range b {
|
||||
inB[k] = true
|
||||
}
|
||||
var out []string
|
||||
for _, k := range a {
|
||||
if inB[k] {
|
||||
out = append(out, k)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// sortedUnique returns keys sorted and de-duplicated, so Document.UnknownKeys
|
||||
// is deterministic across a base+overlay load that happens to name the same
|
||||
// stray key in both files.
|
||||
func sortedUnique(keys []string) []string {
|
||||
if len(keys) == 0 {
|
||||
return nil
|
||||
}
|
||||
seen := make(map[string]bool, len(keys))
|
||||
out := make([]string, 0, len(keys))
|
||||
for _, k := range keys {
|
||||
if !seen[k] {
|
||||
seen[k] = true
|
||||
out = append(out, k)
|
||||
}
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// Dir loads configuration from a directory tree:
|
||||
//
|
||||
// config.yaml daemon-level settings
|
||||
@@ -249,16 +306,23 @@ func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool) error {
|
||||
}
|
||||
return decodeSchedulingFile(path, &doc.Scheduling)
|
||||
}
|
||||
if err := decodeTOML(path, &doc.Config); err != nil {
|
||||
cfgKeys, err := decodeTOMLKeys(path, &doc.Config)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return decodeSchedulingFile(path, &doc.Scheduling)
|
||||
schedKeys, err := decodeSchedulingFileKeys(path, &doc.Scheduling)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...)
|
||||
return nil
|
||||
}
|
||||
|
||||
// finalize applies defaults, then validates. The order matters: validation
|
||||
// judges the effective configuration, including values the operator never
|
||||
// wrote.
|
||||
func (l *Loader) finalize(doc *Document) (*Document, error) {
|
||||
doc.UnknownKeys = sortedUnique(doc.UnknownKeys)
|
||||
l.applyDefaults(&doc.Config)
|
||||
if err := Validate(&doc.Config); err != nil {
|
||||
return nil, err
|
||||
|
||||
@@ -41,12 +41,20 @@ type schedulingDocument struct {
|
||||
}
|
||||
|
||||
func decodeSchedulingFile(path string, target *SchedulingInput) error {
|
||||
_, err := decodeSchedulingFileKeys(path, target)
|
||||
return err
|
||||
}
|
||||
|
||||
// decodeSchedulingFileKeys is decodeSchedulingFile plus the file's
|
||||
// undecoded top-level keys under this target (see decodeConfigFileKeys).
|
||||
func decodeSchedulingFileKeys(path string, target *SchedulingInput) ([]string, error) {
|
||||
doc := schedulingDocument{Scheduling: *target}
|
||||
if err := decodeConfigFile(path, &doc); err != nil {
|
||||
return err
|
||||
keys, err := decodeConfigFileKeys(path, &doc)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
*target = doc.Scheduling
|
||||
return nil
|
||||
return keys, nil
|
||||
}
|
||||
|
||||
func applySchedulingOverlay(target *SchedulingInput, overrides map[string]any) error {
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
package configuration
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// minimalValidConfigTOML is enough to pass Validate on its own, so these tests
|
||||
// isolate the unknown-key behaviour from unrelated validation failures.
|
||||
const minimalValidConfigTOML = "bot_user = \"widget\"\nwork_dir = \"/base/work\"\n" +
|
||||
"[agent]\nmode = \"inprocess\"\n"
|
||||
|
||||
// TestUnknownKeysAreReported pins plan-config-drift.md step 1: a
|
||||
// misspelled key must not parse, validate and silently do nothing. Today
|
||||
// (before the fix) it loads with zero indication anything was ignored.
|
||||
func TestUnknownKeysAreReported(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "config.toml")
|
||||
src := minimalValidConfigTOML + "[containers]\nmax_concurrancy = 4\n" // typo: concurrancy
|
||||
if err := os.WriteFile(path, []byte(src), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
doc, err := New(nil).File(path)
|
||||
if err != nil {
|
||||
t.Fatalf("File: %v (an unknown key must not fail the load)", err)
|
||||
}
|
||||
if len(doc.UnknownKeys) == 0 {
|
||||
t.Fatal("UnknownKeys is empty, want the typo'd key reported")
|
||||
}
|
||||
found := false
|
||||
for _, k := range doc.UnknownKeys {
|
||||
if k == "containers.max_concurrancy" {
|
||||
found = true
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Errorf("UnknownKeys = %v, want it to contain %q", doc.UnknownKeys, "containers.max_concurrancy")
|
||||
}
|
||||
}
|
||||
|
||||
// TestValidSchedulingBlockIsNotReportedAsUnknown pins Hazard 1 from
|
||||
// plan-config-drift.md: one file feeds both &doc.Config and
|
||||
// &doc.Scheduling. Reporting either target's Undecoded() verbatim would
|
||||
// flag every config carrying a real [scheduling] block, since Config has
|
||||
// no "scheduling" field and SchedulingInput has nothing else.
|
||||
func TestValidSchedulingBlockIsNotReportedAsUnknown(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "config.toml")
|
||||
src := minimalValidConfigTOML + "[scheduling]\ninterval = \"60s\"\nmax_parallel = 4\n"
|
||||
if err := os.WriteFile(path, []byte(src), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
doc, err := New(nil).File(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(doc.UnknownKeys) != 0 {
|
||||
t.Errorf("UnknownKeys = %v, want none: a valid [scheduling] block is not an unknown key", doc.UnknownKeys)
|
||||
}
|
||||
if doc.Scheduling.MaxParallel != 4 {
|
||||
t.Errorf("Scheduling.MaxParallel = %d, want 4 (scheduling must still decode correctly)", doc.Scheduling.MaxParallel)
|
||||
}
|
||||
}
|
||||
|
||||
// TestUnknownSchedulingKeyIsStillReported is the mirror of the Hazard 1
|
||||
// test: a typo inside [scheduling] must not be masked by the intersection
|
||||
// logic that protects legitimate cross-target keys.
|
||||
func TestUnknownSchedulingKeyIsStillReported(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "config.toml")
|
||||
src := minimalValidConfigTOML + "[scheduling]\nmax_parallell = 4\n" // typo: extra "l"
|
||||
if err := os.WriteFile(path, []byte(src), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
doc, err := New(nil).File(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
found := false
|
||||
for _, k := range doc.UnknownKeys {
|
||||
if k == "scheduling.max_parallell" {
|
||||
found = true
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Errorf("UnknownKeys = %v, want it to contain %q", doc.UnknownKeys, "scheduling.max_parallell")
|
||||
}
|
||||
}
|
||||
|
||||
// TestExampleConfigHasNoUnknownKeys is the contract test the design
|
||||
// promised: the checked-in template must never itself trip the detector.
|
||||
func TestExampleConfigHasNoUnknownKeys(t *testing.T) {
|
||||
doc, err := New(nil).File(filepath.Join("..", "..", "..", "config.example.toml"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(doc.UnknownKeys) != 0 {
|
||||
t.Errorf("config.example.toml has unknown keys: %v", doc.UnknownKeys)
|
||||
}
|
||||
}
|
||||
|
||||
// TestDeploymentOverlaysHaveNoUnknownKeys covers every shipped overlay
|
||||
// profile the same way, loaded as they are in production: layered over
|
||||
// config.example.toml via -config-overlay.
|
||||
func TestDeploymentOverlaysHaveNoUnknownKeys(t *testing.T) {
|
||||
base := filepath.Join("..", "..", "..", "config.example.toml")
|
||||
dir := filepath.Join("..", "..", "..", "deployments")
|
||||
entries, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if filepath.Ext(e.Name()) != ".toml" {
|
||||
continue
|
||||
}
|
||||
t.Run(e.Name(), func(t *testing.T) {
|
||||
doc, err := New(nil).Overlay(base, filepath.Join(dir, e.Name()))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(doc.UnknownKeys) != 0 {
|
||||
t.Errorf("%s has unknown keys: %v", e.Name(), doc.UnknownKeys)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user