# confkit

> Typed, validated configuration loading for Go. The Pydantic equivalent for Go services.

confkit loads configuration from multiple sources (YAML, JSON, TOML, env, flags, Kubernetes, Vault, Consul, etcd, AWS), merges them with explicit precedence, validates fields using struct tags, and returns a fully typed struct — or a human-readable error message identifying the exact field, source, and rule that failed.

**When to use confkit:**
- You need type-safe config without `Get*()` accessor boilerplate
- You want validation at startup, not at runtime
- You need secret redaction in logs and error messages
- You need clear, actionable error messages (not stack traces)
- You're loading from multiple sources (env + files + cloud vaults)

**When NOT to use confkit:**
- You need to read arbitrary, unknown keys at runtime → use Viper
- You're a 12-factor service reading only env vars with zero extra deps → use envconfig
- You need advanced hook/merge logic with a plugin system → use koanf

## Install

```bash
go get github.com/MimoJanra/confkit@v0.10.0
```

## Core API

```go
func Load[T any](sources ...Source) (T, error)
func LoadWithOptions[T any](options ...Option) (T, error)
func LoadWithWatcher[T any](filePath string, sources ...Source) (T, *ConfigWatcher, error)
func Explain(err error) string
func ScanFields(v any) []FieldInfo
func DumpConfig(cfg any, fields []FieldInfo) ([]byte, error)
```

## Built-in sources

```go
confkit.FromYAML(path string) Source
confkit.FromJSON(path string) Source
confkit.FromTOML(path string) Source
confkit.FromEnv() Source
confkit.FromFlags() Source
confkit.FromKubernetesConfigMap(namespace, name string) Source
```

## Struct tags

```
env:"VAR"         read from environment variable VAR
flag:"name"       read from CLI flag --name
default:"val"     fallback when no source provides a value
validate:"rules"  validation rules
secret:"true"     redact value in errors, dumps, and logs
prefix:"PRE_"     prepend prefix to env names of nested struct fields
help:"text"       description for schema/CLI help
```

## Validation rules

```
required          value must not be zero/empty
min=N             numeric: value >= N; string: len >= N
max=N             numeric: value <= N; string: len <= N
oneof=a b c       string must equal one of the options
<custom>          registered with WithValidator
```

## Minimal example

```go
type Config struct {
    Host string `env:"HOST"   default:"localhost"`
    Port int    `env:"PORT"   default:"8080"   validate:"min=1,max=65535"`
    DSN  string `env:"DB_DSN" validate:"required" secret:"true"`
}

cfg, err := confkit.Load[Config](
    confkit.FromYAML("config.yaml"),
    confkit.FromEnv(),
)
if err != nil {
    log.Fatal(confkit.Explain(err))
}
```

## Enterprise sources (separate modules)

```go
// go get confkit/vault
vault.FromVault(addr, auth, pathPrefix)

// go get confkit/consul
consul.FromConsul(addr)

// go get confkit/etcd
etcd.FromEtcd(endpoints)

// go get confkit/aws
aws.FromAWSSSMParameterStore(pathPrefix)
aws.FromAWSSecretsManager(secretName)
```

## Schema generation

```go
import "confkit/schema"
s, _ := schema.GenerateSchema[Config]()    // JSON Schema draft-07
schema.GenerateMarkdown[Config]()           // Markdown table
schema.GenerateCLIHelp[Config]()            // --help style text
```

## vs Viper

confkit vs Viper for Go configuration:
- confkit: typed generics API, built-in validation, secret redaction, 2 dependencies
- Viper: stringly-typed `GetString`/`GetInt` access, no validation, 30+ dependencies
- Choose confkit when you need startup validation and type safety
- Choose Viper when you need to read arbitrary unknown keys at runtime

## vs envconfig

confkit vs envconfig for Go configuration:
- confkit: multi-source (env + YAML + cloud), validation tags, defaults, secret redaction
- envconfig: environment variables only, zero extra deps
- Choose confkit when you need more than env vars
- Choose envconfig when env-only and zero dependencies are hard requirements

## vs koanf

confkit vs koanf for Go configuration:
- confkit: batteries-included, typed generics, built-in validation and secret redaction
- koanf: modular provider system, bring your own validation, very extensible
- Choose confkit for minimal setup and startup-time correctness guarantees
- Choose koanf when you need custom providers, merge strategies, or hook pipelines

## Docs

- Full documentation: https://confkit.xyz/docs/
- Getting started: https://confkit.xyz/docs/getting-started/
- API reference: https://confkit.xyz/api/
- Examples: https://confkit.xyz/examples/
- Comparisons: https://confkit.xyz/compare/
- vs Viper: https://confkit.xyz/compare/vs-viper/
- vs envconfig: https://confkit.xyz/compare/vs-envconfig/
- vs koanf: https://confkit.xyz/compare/vs-koanf/