73 lines
3.5 KiB
Markdown
73 lines
3.5 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 initial loader accepts one strict YAML
|
|
source (or explicit defaults-only input), optionally traverses explicit path and glob
|
|
imports, strictly composes their disjoint definitions, applies typed defaults, and
|
|
can overlay one selected fixed overlay and check an application schema version. It
|
|
returns 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.
|
|
|
|
```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. Today, the main document
|
|
and its imports form the strictly composed base, with a selected overlay and
|
|
explicit CLI overrides above it and typed defaults below 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. The
|
|
[consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
|
|
Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
|
|
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.
|