83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
# ConfigKit
|
|
|
|
An opinionated Go library for applications that use YAML configuration files.
|
|
|
|
Linux is release-validated; macOS support is best-effort. See the
|
|
[platform support policy](docs/policy/release.md#platform-support) for details.
|
|
|
|
ConfigKit's simple `Load` accepts one strict YAML source (or explicit
|
|
defaults-only input). `LoadLayered` additionally combines explicit lower-priority
|
|
source groups with an independently selected main input. Sources can be host
|
|
files, native `fs.FS` files, labeled bytes or readers, or snapshotted mappings.
|
|
Enabled path and glob imports compose strictly within their group; precedence
|
|
between groups combines mappings recursively. Both entry points return a complete,
|
|
validated configuration with detached metadata and safe diagnostics.
|
|
Applications may perform audited defaulting and normalization through a resolver,
|
|
then report domain errors and warnings through read-only semantic validation. Secret
|
|
tags and a path predicate drive deterministic redacted effective YAML. Typed secret
|
|
references resolve environment names before validation, and explicit
|
|
secrets-directory bootstrap is available as a separate startup operation. Explicit
|
|
CLI override records apply above overlays. Value explanation is available through
|
|
detached structured records and deterministic redacted output. Built-in
|
|
`extends` relationships let a mapping inherit from a named sibling during the
|
|
same load, retaining explicit presence and source/derivation history. The root
|
|
`Diff` API compares frozen effective values from two successful same-type loads;
|
|
the [configuration contract](docs/config.md#effective-configuration-diffs) and
|
|
[consumer guide](docs/consumers/README.md#effective-configuration-diffs) describe
|
|
its safe changed-region records and maintained workflows.
|
|
|
|
```go
|
|
type Config struct {
|
|
Enabled bool `yaml:"enabled"`
|
|
Workers int `yaml:"workers"`
|
|
}
|
|
|
|
func ReadConfig(path string) (Config, error) {
|
|
result, err := configkit.Load[Config](configkit.File(path))
|
|
if err != nil {
|
|
return Config{}, err
|
|
}
|
|
return result.Config, nil
|
|
}
|
|
```
|
|
|
|
## Design philosophy
|
|
|
|
ConfigKit favors one coherent, predictable configuration model over flexibility
|
|
for reproducing each consumer's conventions. Its goal is to let applications
|
|
load once, inspect where final values came from, and distinguish explicit values
|
|
from omissions with minimal configuration bookkeeping. Applications retain their
|
|
domain rules and execution responsibilities.
|
|
|
|
Loading is synchronous and complete on return. Applications normally load once
|
|
near startup and then use the final configuration and metadata; ConfigKit stays
|
|
inactive until explicitly called again. Applications may initiate additional
|
|
loads as needed. See the [loading lifecycle](docs/config.md#completion-and-resource-lifetime)
|
|
for completion and ownership details.
|
|
|
|
Within a configuration tier, independent contributions compose strictly: shared
|
|
mappings combine, while overlapping non-mapping definitions are errors. Between
|
|
precedence tiers, mappings combine recursively, retaining omitted lower-priority
|
|
children; other values replace lower-priority values. The main document and its
|
|
imports form one strictly composed tier. Explicit underlay groups sit below it
|
|
and above typed defaults; a selected overlay and explicit CLI overrides sit
|
|
above it. The [configuration contract](docs/config.md#strict-document-composition)
|
|
owns the detailed combination rules and input-specific constraints.
|
|
|
|
The [architecture goals](docs/policy/architecture.md#success-criteria) explain
|
|
these priorities and how genuine new needs can justify extending the shared
|
|
model. The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions.
|
|
|
|
The [configuration contract](docs/config.md) describes implemented behavior,
|
|
including [input destinations](docs/config.md#input-destinations). The
|
|
[consumer adoption guide](docs/consumers/README.md) provides maintained simple,
|
|
layered, and mounted-collection examples alongside the migration shapes. The
|
|
accepted placement decision is recorded in [ADR 0011](docs/adr/0011-input-destinations.md).
|
|
See the [development guide](docs/development.md) for repository orientation and
|
|
the [release procedure](docs/release.md) for maintainer-only candidate and
|
|
publication steps.
|
|
|
|
ConfigKit code is licensed under the [LGPL v3.0 or later](COPYRIGHT).
|
|
|
|
[Open Source attribution notices](docs/oss/attribution.md) are available.
|