49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# Configuration Internals
|
|
|
|
User-visible fields, defaults, and selection behavior belong in the
|
|
[Configuration Reference](../config.md). This document describes the internal
|
|
pipeline-loading boundary implemented by `internal/config`.
|
|
|
|
## Pipeline Loading
|
|
|
|
`LoadPipeline` assembles and validates a pipeline in this order:
|
|
|
|
1. Parse the root YAML into a presence-aware composition tree. The tree retains
|
|
source names, full field paths, node kinds, declaration order, and explicit
|
|
zero, false, empty-map, and empty-list values.
|
|
2. Remove the root-only `composition` envelope and validate its explicit
|
|
`imports` list.
|
|
3. Open each import relative to the root pipeline directory through the
|
|
confined regular-file boundary. Imports must use a `.yml` or `.yaml`
|
|
extension and cannot traverse, use symlinks, repeat a file, import the root,
|
|
or contain another composition envelope.
|
|
4. Additively merge the root body and imports. Distinct map leaves compose;
|
|
repeated scalar or list paths and node-kind disagreements are conflicts.
|
|
5. Emit deterministic canonical YAML and strictly decode it into
|
|
`PipelineConfig`.
|
|
6. Apply pipeline defaults once, then resolve ordinary relative pipeline paths
|
|
from the root pipeline file.
|
|
|
|
This ordering preserves monolithic configuration behavior. Moving a field to
|
|
an imported fragment changes its source ownership, not its path base, default,
|
|
or schema semantics.
|
|
|
|
## Diagnostics And Runtime Metadata
|
|
|
|
Syntax, duplicate-key, composition, conflict, and schema failures include the
|
|
relevant source name and full field path. Additive conflicts report every
|
|
claiming source so operators can repair the split without repeatedly
|
|
rediscovering additional conflicts.
|
|
|
|
The loaded pipeline retains private runtime metadata for the absolute root
|
|
path, ordered imports, contributing sources, and field ownership. This metadata
|
|
does not participate in YAML decoding or alter the public configuration model.
|
|
|
|
## Test Surfaces
|
|
|
|
`composition_test.go` protects the presence and merge algebra independently of
|
|
the public schema. `pipeline_composition_test.go` exercises explicit imports,
|
|
confinement, conflicts, strict decoding, metadata, and root-relative path
|
|
behavior through `LoadPipeline`. Other configuration tests continue to protect
|
|
defaults and validation after assembly.
|