Files
archie/internal/infrastructure/configuration/doc.go
T
sam c66c0a2a38 refactor(config): move loading into infrastructure/configuration
internal/config both defined the types every package imports and performed
the file I/O to produce them. Importing a settings struct therefore pulled
in a TOML decoder and a YAML decoder, and the shared model owned discovery,
decoding, overlays, defaulting and validation all at once. See
docs/architecture/configuration.md, which requires loading to move out and
internal/config to be dissolved.

internal/config is now types only -- no os, no filepath, no toml. The new
package owns loading, one concern per file:

  features.go    the closed set of recognised feature files
  discovery.go   directory scan and classification
  decode.go      TOML/YAML decoding, format dispatch
  defaults.go    filling absent values, no errors
  validate.go    judging supplied values, no mutation
  provenance.go  which file contributed what
  loader.go      Loader wiring the above; File/Overlay/Dir

Beyond relocating, this fixes what the old code conflated:

  - Defaulting and validation were interleaved. applyAgentDefaults and
    applyDispatchDefaults returned validation errors; validateContainers and
    validateSingleIdentity quietly mutated the config. There was no point at
    which you could see what the operator actually supplied. They are now
    separate passes: applyDefaults never fails, validate never writes.
  - Errors were fmt.Errorf strings prefixed "config: ", so a caller could not
    distinguish operator-fixable input from an unreadable file without
    matching message text. Five sentinels now carry that distinction.
  - dataHome() read XDG_DATA_HOME directly and discarded the error from
    os.UserHomeDir, so defaulting could not be tested without the
    environment. It is injectable on Loader and no longer swallows the error.
  - Nothing recorded where a value came from. With overlays, feature files
    and conf.d/ all able to set the same field, "which file set this?" was
    answerable only by re-deriving precedence by hand. Provenance records it.
  - Feature files were applied in map iteration order, making load order and
    any resulting error arbitrary. Discovery now returns them sorted.
  - loadMainConfig reported "no config.yaml or config.toml found in %s" with
    an empty string: the directory was lost when it was extracted from
    loadDirInto, so the error named no directory.
  - Unreadable or malformed conf.d/ extras were skipped silently, which
    presents as a setting the operator wrote simply not taking effect.
  - Decode errors from the main config were returned bare, without naming
    the file that failed to parse.

The 40 loader tests moved with the code and their assertions are unchanged,
so the defaulting and validation rewrite is behaviour-preserving.

Document.Config is the temporary seam: still internal/config.Config, named
as a field so the compromise is visible at each use site, with its deletion
condition recorded in doc.go. Building typed per-domain sections now, while
every consumer still reads config.Config, would mean two shapes kept in sync
by hand with no consumer for the new one; that belongs with the dissolution
work, not ahead of it.

No consumer outside cmd/archied changed.

Verified: go build, go vet, gofmt clean; go test ./internal/config/... and
./internal/infrastructure/configuration/... pass. Pre-existing gateway and
telegram failures are unchanged.
2026-07-29 11:07:41 +10:00

36 lines
1.8 KiB
Go

// Package configuration is the external configuration input boundary.
//
// It owns everything about how configuration arrives: locating files,
// decoding TOML and YAML, applying base/overlay precedence, resolving
// environment and secret references, defaulting absent input, validating
// what was supplied, and recording where each value came from.
//
// It owns none of the behaviour those values describe. Deciding what a
// dispatch trigger or a retry budget *means* belongs to the domain that
// acts on it; this package only decides whether the operator supplied
// something usable, and says so clearly when they did not.
//
// # Why this package exists
//
// Loading used to live inside internal/config, alongside the runtime types
// every package imports. That made the shared model responsible for file
// I/O, so a package that merely wanted a settings struct also pulled in a
// TOML decoder, and defaulting, validation and decoding were interleaved in
// one function. See docs/architecture/configuration.md.
//
// # The temporary seam
//
// docs/architecture/configuration.md requires a private input document that
// is translated into per-domain settings and never returned as the
// application's runtime model. [Document.Config] is not that yet: it is the
// existing internal/config.Config, exposed here so this package can take
// over loading without every consumer changing at once.
//
// It is deliberately a named field rather than a bare return value so the
// compromise is visible at each use site. It should be replaced by typed
// per-domain sections once those domains own their settings; the condition
// for deleting it is that internal/config no longer exists. Until then, do
// not add behaviour to it, and do not treat its presence as licence to pass
// whole-application configuration into a domain.
package configuration