85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# ConfigKit
|
|
|
|
ConfigKit loads YAML into your application's Go configuration type, combines the
|
|
inputs you choose, and lets you inspect where the final values came from. You
|
|
supply the types, defaults, and application rules; ConfigKit handles loading,
|
|
combination, strict decoding, and inspection.
|
|
|
|
Linux is release-validated; macOS support is best-effort. See the
|
|
[platform support policy](docs/policy/release.md#platform-support).
|
|
|
|
## Load a configuration file
|
|
|
|
```go
|
|
import "go.maximumdirect.net/configkit"
|
|
|
|
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
|
|
}
|
|
```
|
|
|
|
Existing consumers should follow the
|
|
[module-path migration guidance](docs/consumers/README.md#vanity-module-path-migration).
|
|
|
|
## Add the features you need
|
|
|
|
Start with one file. Optional features use the same loading and inspection model:
|
|
|
|
- [Choose inputs](docs/consumers/README.md#choosing-a-loading-entry-point): read
|
|
files, an application-owned `fs.FS`, bytes, a reader, or a Go mapping. Use
|
|
explicit search descriptions when the application should look in several places.
|
|
- [Supply lower-priority settings](docs/consumers/README.md#native-filesystem-and-layered-input):
|
|
use `LoadLayered` for bundled defaults that application configuration can override.
|
|
- [Combine configuration](docs/config.md#explicit-imports): add declared imports,
|
|
select one overlay, or pass values explicitly set by your CLI parser.
|
|
- [Reuse settings](docs/config.md#sibling-inheritance): let one named entry inherit
|
|
from a sibling. [Identified lists](docs/config.md#strict-document-composition)
|
|
also support record inheritance and replace, append, or upsert operations.
|
|
- [Apply application rules](docs/config.md#recorded-application-resolution): derive
|
|
or normalize values in a resolver, then check the final configuration in a validator.
|
|
- [Handle credentials](docs/config.md#typed-secret-references): use environment-name
|
|
references and choose which configuration fields to hide in inspection output.
|
|
- [Inspect a load](docs/config.md#layered-metadata): examine sources, presence,
|
|
history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs).
|
|
|
|
The [consumer guide](docs/consumers/README.md) walks through these tasks and links
|
|
to maintained examples. The [configuration reference](docs/config.md) defines the
|
|
exact YAML, combination, and lifecycle rules.
|
|
|
|
## Design philosophy
|
|
|
|
ConfigKit favors consistent, predictable rules across applications. A load returns
|
|
the final configuration and metadata that distinguish supplied values such as
|
|
`false` and `0` from omissions. Applications keep their domain rules and runtime
|
|
initialization.
|
|
|
|
Within one layer, independent contributions combine strictly: conflicting
|
|
values are errors. Across layers, higher-priority settings can replace
|
|
lower-priority settings, while mappings combine by key. Identified lists have
|
|
their declared combination rules. See the [worked combination
|
|
examples](docs/config.md#strict-document-composition) for the details and
|
|
exceptions.
|
|
|
|
Loading finishes before the call returns. ConfigKit then stays inactive until you
|
|
call it again; inspection uses the saved result. See
|
|
[completion and resource lifetime](docs/config.md#completion-and-resource-lifetime).
|
|
|
|
The [architecture goals](docs/policy/architecture.md#success-criteria) and
|
|
[ADRs](docs/adr) explain design decisions, including shared import and inheritance
|
|
ordering. [Future work](docs/roadmap/future.md) lists possible extensions.
|
|
Contributors can start with the [development guide](docs/development.md);
|
|
release maintainers use the [release procedure](docs/release.md).
|
|
|
|
ConfigKit code is licensed under the [LGPL v3.0 or later](COPYRIGHT).
|
|
|
|
[Open Source attribution notices](docs/oss/attribution.md) are available.
|