Files
archie/internal/infrastructure/configuration/loader.go
T
sam 3c6772bd2e fix(configuration): resolve the default config path in one place
Four binaries derived the default with os.UserConfigDir while the daemon
resolved it from its own config home. The two agree on Linux with an
absolute XDG_CONFIG_HOME and diverge everywhere else, so one deployment
booted from a different config file depending on which binary started.

Move the rule into the package that owns configuration resolution
(internal/infrastructure/configuration, which already owns xdgDataHome and
DefaultWorkDir) as DefaultConfigDir/DefaultConfigPath, and have every
-config default take it from there: archie-gateway, archie-messaging,
archie-state-store (serve and recovery) and archie-ui, plus the daemon's
own parseArgs, setup generator and drain-marker path.

Fence the claim at the source, since the resolved value is only observable
by starting a process: no source under cmd/ or internal/app/archied may
call os.UserConfigDir, and every -config registration must default to the
helper.
2026-09-22 01:57:49 +10:00

456 lines
16 KiB
Go

package configuration
import (
"fmt"
"log/slog"
"os"
"path/filepath"
"reflect"
"sort"
"github.com/samcharles93/archie-core/internal/config"
)
// Document is the decoded external configuration together with a record of
// where it came from.
type Document struct {
// Config is the translated settings.
//
// TEMPORARY. docs/architecture/configuration.md requires this to become
// typed per-domain sections that never expose a whole-application model.
// It stays for now so this package can own loading without every
// consumer changing at once. Delete when internal/config is dissolved.
Config config.Config
// Scheduling is the decoded [scheduling] input. Application composition
// translates it into domain-owned scheduling.EngineConfig.
Scheduling SchedulingInput
// 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
// [New].
type Loader struct {
log *slog.Logger
// dataHomeFn resolves the base directory for derived paths. Injected so
// tests can exercise defaulting without depending on the environment --
// the previous package-level dataHome() read XDG_DATA_HOME directly and
// discarded the error from os.UserHomeDir.
dataHomeFn func() string
}
// New returns a Loader. A nil logger discards output.
func New(log *slog.Logger) *Loader {
if log == nil {
log = slog.New(slog.DiscardHandler)
}
return &Loader{log: log, dataHomeFn: xdgDataHome}
}
// dataHome resolves the base directory for derived paths.
func (l *Loader) dataHome() string {
if l.dataHomeFn == nil {
return xdgDataHome()
}
return l.dataHomeFn()
}
// xdgDataHome returns $XDG_DATA_HOME, falling back to ~/.local/share, and
// finally to a relative path when the home directory is unknowable.
func xdgDataHome() string {
if dir := os.Getenv("XDG_DATA_HOME"); dir != "" {
return dir
}
home, err := os.UserHomeDir()
if err != nil {
return filepath.Join(".local", "share")
}
return filepath.Join(home, ".local", "share")
}
// xdgConfigHome returns $XDG_CONFIG_HOME, falling back to ~/.config, and
// finally to a relative path when the home directory is unknowable.
//
// os.UserConfigDir is the XDG-spec-shaped function and is deliberately not
// used: it resolves to ~/Library/Application Support on darwin and returns an
// error rather than a relative path for a relative $XDG_CONFIG_HOME, so two
// archie processes would read two different configuration files.
func xdgConfigHome() string {
if dir := os.Getenv("XDG_CONFIG_HOME"); dir != "" {
return dir
}
home, err := os.UserHomeDir()
if err != nil {
return ".config"
}
return filepath.Join(home, ".config")
}
// File loads a single configuration file. TOML remains supported for existing
// deployments; YAML files use the same defaults and validation path.
func (l *Loader) File(path string) (*Document, error) {
return l.Resolve(path, "")
}
// Resolve selects the configuration source from its filesystem type: a TOML
// or YAML file, or a feature-config directory. This is the production entry
// point. Keeping selection here ensures command-line loading and operator
// tooling share the exact same precedence and validation rules.
func (l *Loader) Resolve(basePath, overlayPath string) (*Document, error) {
info, err := os.Stat(basePath)
if err != nil {
return nil, fmt.Errorf("%w: config source %s: %w", ErrUnreadable, basePath, err)
}
if err := validateOverlayPath(overlayPath, basePath, info.IsDir()); err != nil {
return nil, err
}
if info.IsDir() {
return l.Dir(basePath, overlayPath)
}
return l.overlayFile(basePath, overlayPath)
}
// validateOverlayPath checks that overlayPath, when non-empty, exists and has
// the same filesystem kind as basePath: a directory overlay for a directory
// source and a file overlay for a file source.
func validateOverlayPath(overlayPath, basePath string, baseIsDir bool) error {
if overlayPath == "" {
return nil
}
overlayInfo, err := os.Stat(overlayPath)
if err != nil {
return fmt.Errorf("%w: config overlay %s: %w", ErrUnreadable, overlayPath, err)
}
if overlayInfo.IsDir() != baseIsDir {
if baseIsDir {
return fmt.Errorf("config overlay %s must be a directory when config source %s is a directory", overlayPath, basePath)
}
return fmt.Errorf("config overlay %s must be a file when config source %s is a file", overlayPath, basePath)
}
return nil
}
// Overlay loads basePath, then decodes overlayPath into the same value so
// only the fields the overlay sets are replaced -- every field it omits keeps
// the base value. This lets a deployment-specific file (config.docker.toml)
// declare only what differs instead of restating the whole schema. An empty
// overlayPath is equivalent to [Loader.File].
func (l *Loader) Overlay(basePath, overlayPath string) (*Document, error) {
return l.overlayFile(basePath, overlayPath)
}
// ApplyOverlay decodes the runtime config overlay (a nested map of
// dotted-path values from the overlay store) into a copy of doc with the
// same field-level precedence as a file overlay, records the overlay
// origin, then applies defaults and validates. It is used at boot and on
// reload to layer dashboard-edited overrides over the file config.
//
// ApplyOverlay never mutates its input: the returned Document owns fresh
// copies of the Config and the provenance chain, so a decode or
// validation failure leaves the caller's document (and whatever it was
// published from) exactly as it was.
func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Document, error) {
next := *doc
next.Config = doc.Config.Clone()
next.Provenance.Origins = append([]Origin(nil), doc.Provenance.Origins...)
if len(overrides) == 0 {
return l.finalize(&next, Validate)
}
if err := ApplyOverlayValues(&next.Config, overrides); err != nil {
return nil, err
}
if err := applySchedulingOverlay(&next.Scheduling, overrides); err != nil {
return nil, err
}
next.Provenance.record(Origin{Path: "config_overlay (runtime)", Role: RoleMain, Layer: LayerOverlay})
return l.finalize(&next, Validate)
}
func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) {
doc := &Document{}
cfgKeys, err := decodeConfigFileKeys(basePath, &doc.Config)
if err != nil {
return nil, err
}
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 != "" {
// The overlay is folded over the base config rather than decoded into
// it: a decode replaces a map-valued entry wholesale, clearing the
// fields of that entry the overlay does not name (applyOverlayFile).
cfgKeys, err = applyOverlayFile(overlayPath, &doc.Config)
if err != nil {
return nil, err
}
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, validateBootstrap)
}
// overlayFileKeys reports the keys of an overlay file that nothing consumes. It
// has two sources, because the file's own decode and the fold's apply decode do
// not match keys the same way: TOML accepts a key that differs only in case,
// while the yaml decode the fold uses does not. A key only the file's decode
// matches would therefore be consumed by the report below and dropped in
// silence by the apply, so the apply's own view of the mapping is unioned in.
//
// The second decode here is deliberate: it is what carries TOML's Undecoded()
// view of the file, which the raw mapping cannot report (it consumes every key).
func overlayFileKeys(path string, mapping map[string]any, target reflect.Type) ([]string, error) {
decoded, err := decodeConfigFileKeys(path, reflect.New(target).Interface())
if err != nil {
return nil, err
}
return append(decoded, unmatchableKeys(mapping, target)...), nil
}
// unmatchableKeys returns the dotted paths of the keys in mapping that the fold's
// yaml decode cannot match to a field of target. It descends the way foldOverrides
// does -- through structs and through string-keyed maps of structs -- so it sees
// the same keys the apply does. A slice of tables is not descended: the yaml
// decode replaces it wholesale, so anything inside it is a value, not a key.
func unmatchableKeys(mapping map[string]any, target reflect.Type) []string {
var out []string
for key, value := range mapping {
field, ok := yamlFieldOf(target, key)
if !ok {
out = append(out, key)
continue
}
sub, ok := value.(map[string]any)
if !ok {
continue
}
switch field.Type.Kind() {
case reflect.Struct:
out = append(out, prefixed(key, unmatchableKeys(sub, field.Type))...)
case reflect.Map:
entry := field.Type.Elem()
for entry.Kind() == reflect.Pointer {
entry = entry.Elem()
}
if entry.Kind() != reflect.Struct || field.Type.Key().Kind() != reflect.String {
continue
}
for entryName, entryValue := range sub {
entryMapping, ok := entryValue.(map[string]any)
if !ok {
continue
}
out = append(out, prefixed(key+"."+entryName, unmatchableKeys(entryMapping, entry))...)
}
}
}
return out
}
// prefixed qualifies a nested key report with the path that reached it.
func prefixed(prefix string, keys []string) []string {
for i, key := range keys {
keys[i] = prefix + "." + key
}
return keys
}
// 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
}
// unregisteredServiceKeys reports [services.<name>] sections naming a service
// nobody registered.
//
// Undecoded() cannot see these. Services is a map, so TOML decodes any section
// under [services] into it successfully, and a typo'd [services.gatway] would
// load clean where the previous struct form reported it. The registry is the
// authority on which names exist, so ask it.
func unregisteredServiceKeys(services config.Services) []string {
var out []string
for name := range services {
if _, ok := config.LookupService(name); !ok {
out = append(out, "services."+name)
}
}
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
// config.gateway.yaml chat channels and platforms
// config.tools.yaml MCP servers and tool policy
// config.memory.yaml memory provider settings
// config.models.yaml LLM providers and models
// config.identities.yaml identity settings
// conf.d/*.yaml additional feature files
//
// A missing feature file means the feature is absent, not an error. Legacy
// config.toml is the fallback when config.yaml is absent; YAML wins when
// both exist.
//
// When overlayDir is non-empty its files are applied on top of baseDir, with
// the same field-level precedence as [Loader.Overlay]. The overlay directory
// need not contain a main config.
func (l *Loader) Dir(baseDir, overlayDir string) (*Document, error) {
doc := &Document{}
if err := l.loadDir(doc, baseDir, LayerBase); err != nil {
return nil, err
}
if overlayDir != "" {
if err := l.loadDir(doc, overlayDir, LayerOverlay); err != nil {
return nil, err
}
}
return l.finalize(doc, validateBootstrap)
}
// loadDir discovers and decodes one directory into doc. The base layer must
// supply a main config; an overlay may contribute feature files alone.
func (l *Loader) loadDir(doc *Document, dir string, layer Layer) error {
files, err := discover(dir)
if err != nil {
return err
}
switch path, isYAMLFile, ok := files.main(); {
case ok:
if err := l.decodeMain(doc, path, isYAMLFile, layer); err != nil {
return err
}
doc.Provenance.record(Origin{Path: path, Role: RoleMain, Layer: layer})
case layer == LayerBase:
return fmt.Errorf("%w: no config.yaml or config.toml in %s", ErrNoConfigFile, dir)
}
for _, feature := range files.sortedFeatures() {
path := files.features[feature]
if err := decodeFeature(&doc.Config, feature, path, layer); err != nil {
return err
}
doc.Provenance.record(Origin{Path: path, Role: RoleFeature, Layer: layer, Feature: feature})
}
for _, name := range files.sortedExtras() {
path := files.extras[name]
if err := decodeExtra(&doc.Config, name, path); err != nil {
return err
}
doc.Provenance.record(Origin{Path: path, Role: RoleExtra, Layer: layer, Feature: Feature(name)})
}
return nil
}
// decodeMain decodes the daemon-level file in whichever format it uses. An
// overlay layer's file is FOLDED over what the base layer decoded, the same way
// a single overlay file folds over its base -- otherwise a map-valued entry it
// only partly addresses would clear the fields it does not name, which is the
// archie-core-e2e2 failure on the directory form of the same flag.
func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool, layer Layer) error {
if layer == LayerOverlay {
cfgKeys, err := applyOverlayFile(path, &doc.Config)
if err != nil {
return err
}
doc.UnknownKeys = append(doc.UnknownKeys, cfgKeys...)
return decodeSchedulingFile(path, &doc.Scheduling)
}
if isYAMLFile {
if err := decodeYAML(path, &doc.Config); err != nil {
return err
}
return decodeSchedulingFile(path, &doc.Scheduling)
}
cfgKeys, err := decodeTOMLKeys(path, &doc.Config)
if err != nil {
return err
}
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 defaulted configuration, including values the operator never
// wrote.
//
// validate is a parameter because the two kinds of caller produce different
// documents. Every file source ([Loader.File], [Loader.Overlay], [Loader.Dir])
// produces a BOOTSTRAP document and passes validateBootstrap: the settings the
// control plane owns are layered over it later, so a stale value in one of them
// must not fail the load. [Loader.ApplyOverlay] layers overrides onto a
// document that is already effective, so it passes [Validate].
func (l *Loader) finalize(doc *Document, validate func(*config.Config) error) (*Document, error) {
doc.UnknownKeys = sortedUnique(append(doc.UnknownKeys, unregisteredServiceKeys(doc.Config.Services)...))
l.applyDefaults(&doc.Config)
if err := validate(&doc.Config); err != nil {
return nil, err
}
l.log.Debug("configuration loaded", "sources", doc.Provenance.String())
return doc, nil
}