config

func Diff ¶

func Diff[T any](old, next *T) ([]Change, error)

Diff compares two configs of type T, a struct, and returns every key whose value differs, in walk order: fields as declared, map entries by sorted key, list elements by index. A nil config has no keys. It compares decoded values, never their text, and neither input is changed.

• Lists compare by index: removing the first of three elements changes the first two and removes the third. Map entries compare by key; an added or removed entry is a change of every key beneath it.
• A struct, map, list or interface that appears, disappears or turns nil, or a nil collection becoming empty, is a Structural change at its key, followed by the keys beneath it that changed. An interface whose value changes type, or turns nil, is compared whole: one change at its key, Structural when either value is a struct, map or list.
• Values decoded whole — scalars, self-decoding structs, maps keyed by non-strings — compare with reflect.DeepEqual: no Equal or String method decides, so two time.Time values for one instant in different locations differ, and NaN never equals itself.
• A value PrintRedacted would redact is redacted on both sides; a sensitive map, list or interface is compared whole, so the keys it holds, which may themselves be secrets, are never listed.
• A pointer, map or slice that leads back to one it lies within, on either side, is compared whole there, so a cycle ends.

A T that is not a struct, a struct whose keys cannot be told apart, an interface holding such a struct, and a non-nil func, channel or unsafe pointer anywhere in either config — inside a value compared whole included — are ErrSchema errors.

package main

import (
	"fmt"

	"github.com/ashtonian/pkg/config"
)

func main() {
	type Limits struct {
		Rate int `koanf:"rate"`
	}
	type AppConfig struct {
		Port     int               `koanf:"port"`
		Password string            `koanf:"password"`
		Tags     []string          `koanf:"tags"`
		Features map[string]Limits `koanf:"features"`
	}
	old := &AppConfig{Port: 8080, Password: "a", Tags: []string{"web"}, Features: map[string]Limits{"audit": {Rate: 10}}}
	next := &AppConfig{Port: 9090, Password: "b", Tags: []string{"web", "api"}, Features: map[string]Limits{"audit": {Rate: 20}, "export": {Rate: 1}}}

	changes, err := config.Diff(old, next)
	if err != nil {
		fmt.Println(err)
		return
	}
	for _, c := range changes {
		switch {
		case c.Structural:
			fmt.Printf("%s: added (%s)\n", c.Key, c.Field.Path)
		case !c.Old.Present:
			fmt.Printf("%s: + %s\n", c.Key, c.New.Text)
		default:
			fmt.Printf("%s: %s -> %s\n", c.Key, c.Old.Text, c.New.Text)
		}
	}

}

Output:
port: 8080 -> 9090
password: [REDACTED] -> [REDACTED]
tags[1]: + api
features["audit"].rate: 10 -> 20
features["export"]: added (features[*])
features["export"].rate: + 1

func RestartChanges ¶ added in v0.7.0

func RestartChanges(changes []Change) []Change

RestartChanges returns caller-owned changes whose resolved class is restart. It is an offline declaration check, independent of runtime applier ownership.

func NewMapProvider ¶

func NewMapProvider(read func(ctx context.Context) (map[string]any, error), delimiter string) (ContextProvider, error)

NewMapProvider returns a provider over the configuration read returns, read afresh on every load — a database table, a key-value store, a cluster's replicated settings — for WithBaseProvider or WithOverrideProvider with a nil parser:

settings, err := config.NewMapProvider(func(ctx context.Context) (map[string]any, error) {
    return loadSettings(ctx, db) // e.g. SELECT key, value FROM settings
}, ".")
reloader, err := config.NewReloader[AppConfig](ctx,
    []config.Option{config.WithBaseProvider(settings, nil)},
    config.WithPollInterval(30*time.Second))

read is called with the load's context, so a slow store stops when the load is cancelled; a nil map is an empty source, and an error fails the load with ErrSource. What read returns is copied, so the caller may keep and change it. With delimiter "." the keys are dotted paths (db.max_conns) and are unflattened into the key tree; a key with an empty segment, or one that is a prefix of another (db and db.host), is an error, since it would set a value and a section at once. With delimiter "" the map is already nested. Any other delimiter is an error. It is a source, not a watch: call Reloader.SourceChanged when the store says it changed, or use WithPollInterval.

func FieldFor ¶

func FieldFor[T any](key string) (Field, error)

FieldFor returns the declared field a key of T names. A struct field's key returns its Field, Index included. A key inside a map or list — items[0].port, limits["/upload"] — returns a Field synthesized for every element or entry: Path is the pattern (items[*].port), Tag and Type the element's, Sensitive inherited from what holds it, and Index nil. A key beneath an interface returns the interface's field, which owns whatever the value holds. The map keys and indexes in key need not exist in any config. Inspection does not decode default/example tags. A field T does not have, a selector of the wrong kind, an index past a fixed array's end, or a key that does not parse is an ErrKey error.

func Fields ¶

func Fields[T any]() []Field

Fields reports every leaf key of T in declaration order. It is the single definition of how a config struct maps to keys, shared by struct-tag defaults, environment-variable mapping, redacted printing and the kongprovider flag bridge:

• A key segment is the koanf tag's name, or the lowercased field name when the tag has none. Options after a comma are not part of the name.
• Unexported fields, koanf:"-" and koanf:",remain" are skipped. koanf:",squash" merges a struct's keys into its parent, as mapstructure decodes it — an unexported embedded struct's exported fields too, as encoding/json promotes them. An embedded pointer to an unexported struct cannot be allocated, and a schema squashing one is refused with ErrSchema.
• Pointers are followed. A struct is descended into unless it decodes itself — encoding.TextUnmarshaler (time.Time, netip.Addr, ...) or mapstructure's Unmarshaler: such a struct is one leaf decoded whole, exactly as decoding treats it.
• Maps, slices, arrays and interfaces are leaves.
• A struct type is never re-entered while it is being walked, so a recursive type yields the keys above the recursion rather than recursing forever. Values for the recursive part still decode from files; they just have no default, environment or flag key.

A T that is not a struct (or pointer to one), or whose keys are invalid or ambiguous, has no fields. Use FieldsChecked to distinguish an empty catalog from an invalid schema.

func FieldsChecked ¶ added in v0.5.0

func FieldsChecked[T any]() ([]Field, error)

FieldsChecked returns the same catalog as Fields, or ErrSchema for a non-struct root, invalid key or ambiguous name. It reads tags as metadata; it does not decode defaults or examples. Load validates those separately. The returned slice and field indexes are caller-owned copies of cached metadata.

func MatchFields ¶ added in v0.6.0

func MatchFields[T any](cfg *T, targets []reflect.Value) ([]Field, error)

MatchFields associates reflected targets, such as CLI flag destinations, with fields in cfg in one traversal. Results correspond to targets in the same order. A result with an empty Path means the target is not a config field: invalid/unaddressable values, cfg itself, skipped fields, collection elements and values outside cfg do not match. A field behind a nil pointer has no address.

Matching reads addresses, not contents, and does not decode tags. It returns ErrSchema for invalid config metadata and ErrKey for nil cfg or ambiguous addresses (including shared zero-sized fields). Results and their indexes are caller-owned. They describe this call's cfg; call again after replacing pointers or targets. No instance addresses are retained in the metadata cache.

package main

import (
	"fmt"
	"reflect"

	"github.com/ashtonian/pkg/config"
)

func main() {
	type Settings struct {
		Port int `koanf:"port" desc:"HTTP port"`
	}
	cfg := Settings{Port: 8080}
	verbose := false
	fields, err := config.MatchFields(&cfg, []reflect.Value{
		reflect.ValueOf(&cfg.Port).Elem(),
		reflect.ValueOf(&verbose).Elem(),
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(fields[0].Path, fields[0].Tag.Get("desc"))
	fmt.Println(fields[1].Path == "")
}

Output:
port HTTP port
true

func ParseKey ¶ added in v0.7.0

func ParseKey(text string) (Key, error)

ParseKey parses fields, quoted map keys, decimal list indexes and [*] patterns. Malformed and empty keys return an error wrapping ErrKey.

func WithAllowUnknownKeys ¶

func WithAllowUnknownKeys() Option

WithAllowUnknownKeys lets a load succeed when a source sets a key no field decodes — for a file shared with another program — by accepting every one silently. Use WithUnknownKeys to accept them and still report them.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/ashtonian/pkg/config"
)

// tempFile writes content to a file in a new temporary directory and
// returns its path and a cleanup function.
func tempFile(name, content string) (string, func()) {
	dir, err := os.MkdirTemp("", "config-example")
	if err != nil {
		log.Fatal(err)
	}
	path := filepath.Join(dir, name)
	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
		log.Fatal(err)
	}
	return path, func() { _ = os.RemoveAll(dir) }
}

func main() {
	type AppConfig struct {
		Server struct {
			Port int `koanf:"port" default:"8080"`
		} `koanf:"server"`
	}
	file, cleanup := tempFile("config.yaml", "server:\n  prot: 9000\n")
	defer cleanup()

	_, err := config.Load[AppConfig](context.Background(), config.WithFile(file))
	fmt.Println(errors.Is(err, config.ErrValidation), err)

	cfg, err := config.Load[AppConfig](context.Background(), config.WithFile(file), config.WithAllowUnknownKeys())
	fmt.Println(cfg.Server.Port, err)

}

Output:
true unmarshaling config: configuration validation failed: keys no field of config_test.AppConfig decodes: server.prot (did you mean server.port?)
8080 <nil>

func WithBaseProvider ¶

func WithBaseProvider(p koanf.Provider, parser koanf.Parser, opts ...SourceOption) Option

WithBaseProvider adds a koanf provider loaded above the defaults and below the config files — the place for a remote store (Consul, etcd, S3) that local files and the environment refine. parser is nil for a provider that returns a map (Read), or the parser for one that returns bytes (ReadBytes): a file, an HTTP body. Base providers load in the order added.

A provider that implements ContextProvider is read with the load's context. A provider failing to load fails the load with ErrSource. Source options such as WithInvalidEntries apply only to this provider.

func WithDecodeHook ¶

func WithDecodeHook(hook mapstructure.DecodeHookFunc) Option

WithDecodeHook adds a mapstructure decode hook. Hooks run in the order added, before the built-in ones (string → time.Duration, comma-separated string → slice, encoding.TextUnmarshaler), so a hook can take over a conversion the built-ins would otherwise make — splitting a slice on ";", say, or decoding a custom type from a map.

func WithDefaults ¶

func WithDefaults(defaults map[string]any) Option

WithDefaults adds programmatic default values keyed by koanf dot-path (e.g. "server.port"); they override the code defaults (Defaulter) and tags. Repeated calls merge, a later call winning on a shared key. The values are deep-copied when WithDefaults is called — every map key and value, slice, array and pointer target reachable through exported fields — so changing the caller's data afterwards changes nothing, including what a Reloader built from the option reads later. Unexported struct fields, channels and functions are copied by value.

func WithEnvPrefix ¶

func WithEnvPrefix(prefix string) Option

WithEnvPrefix enables environment variables named PREFIX_<KEY>, the key path upper-cased with "." → "_" (APP_DB_MAX_CONNS sets db.max_conns). The environment is not read without a prefix. WithEnvPrefix(p) is WithEnvPrefixes(p).

func WithEnvPrefixes ¶ added in v0.9.0

func WithEnvPrefixes(prefixes ...string) Option

WithEnvPrefixes enables environment variables under each prefix, most specific first: for every key, the first prefix whose variable is set wins, then the names the field's env tag lists. A binary that runs several services reads a shared layer beneath each service's own:

config.WithEnvPrefixes("APP_WORKER", "APP") // APP_WORKER_DB_HOST, then APP_DB_HOST

The environment stays one source, between the config files and the override providers. A prefix's trailing "_" is optional; empty and repeated prefixes are left out, and with none left the environment is not read. The last call wins.

A variable two keys could read, under one prefix or across two (APP_WORKER_DB_HOST is db.host under APP_WORKER and worker.db.host under APP), fails the load naming every reading. So does setting a whole map or format:"json" section and a key beneath it, under one prefix or two. A variable under a prefix that no key reads under any prefix is unknown (see WithUnknownKeys); claim the shared prefix's variables only other services read with WithVariableFilter or WithKnownVariables.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/ashtonian/pkg/config"
)

func main() {
	type DBConfig struct {
		Host     string `koanf:"host" default:"localhost" desc:"Database host"`
		MaxConns int    `koanf:"max_conns" default:"10" desc:"Pool size"`
	}
	type WorkerConfig struct {
		DB          DBConfig `koanf:"db"`
		Concurrency int      `koanf:"concurrency" default:"4" desc:"Jobs run at once"`
	}
	environ := []string{
		"APP_DB_HOST=db.internal", // every service
		"APP_DB_MAX_CONNS=20",
		"APP_WORKER_DB_MAX_CONNS=50", // the worker only
		"APP_WORKER_CONCURRENCY=16",
	}

	cfg, err := config.Load[WorkerConfig](context.Background(),
		config.WithEnvPrefixes("APP_WORKER", "APP"),
		config.WithEnviron(func() []string { return environ }),
	)
	if err != nil {
		fmt.Println("load:", err)
		return
	}
	fmt.Printf("host=%s max_conns=%d concurrency=%d\n\n", cfg.DB.Host, cfg.DB.MaxConns, cfg.Concurrency)

	if err := config.PrintUsage[WorkerConfig]("APP_WORKER", config.WithFallbackEnvPrefixes("APP"), config.WithWriter(os.Stdout)); err != nil {
		fmt.Println(err)
	}

}

Output:
host=db.internal max_conns=50 concurrency=16

KEY           ENV                                        TYPE    DEFAULT    RELOAD   DESCRIPTION
db.host       APP_WORKER_DB_HOST, APP_DB_HOST            string  localhost  restart  Database host
db.max_conns  APP_WORKER_DB_MAX_CONNS, APP_DB_MAX_CONNS  int     10         restart  Pool size
concurrency   APP_WORKER_CONCURRENCY, APP_CONCURRENCY    int     4          restart  Jobs run at once

func WithEnviron ¶

func WithEnviron(environ func() []string) Option

WithEnviron sets where environment variables are read from: a function returning "NAME=value" entries, as os.Environ does, called on every load and reload. The default is os.Environ. Tests and examples pass a fixed list; a deployment adapter can pass variables gathered elsewhere.

func WithFile ¶

func WithFile(path string) Option

WithFile adds an optional config file. A missing file is skipped; one that exists but cannot be read fails the load with ErrFileRead, and one the file parser rejects fails it with ErrFileParse. Files merge in the order added, a later file winning on a shared key.

Under a Reloader, a file that loaded once is required from then on: a reload that finds it gone fails and keeps the previous config rather than quietly reverting its keys to lower-precedence values.

func WithFileParser ¶

func WithFileParser(suffix string, p koanf.Parser) Option

WithFileParser parses the config files whose names end in suffix with p, any koanf parser: WithFileParser(".toml", toml.Parser()). Each file takes the parser of the longest suffix its name ends in, ignoring case, so files of different formats load together. Built in, .yaml and .yml parse as YAML, .json as JSON, and any other file as YAML; the suffix "" names every file no longer suffix matches, so WithFileParser("", p) changes that default. A suffix without its leading dot gets one. A nil p removes suffix's parser, leaving its files to a shorter suffix.

The JSON parser reads one object. Integers decode as integers, a key set twice in one object fails the load, and a parse error names its line.

func WithFiles ¶

func WithFiles(paths ...string) Option

WithFiles adds several optional config files, merged in order. Each follows the WithFile rules.

func WithKnownVariables ¶ added in v0.7.0

func WithKnownVariables(names ...string) Option

WithKnownVariables claims exact, case-sensitive environment variable names read by the caller. They are omitted from unknown-variable reports; normal configuration decoding and unknown-key checks are unchanged. Calls accumulate.

func WithLogger ¶

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger for load diagnostics (the sources loaded, and environment variables that fit no key, at debug level) and, for a Reloader built by NewReloader, its reload events. Without it, or with a nil logger, every line goes to slog.Default() as it is when the line is written, so a logger configured after construction — from the config just loaded, say — takes effect.

func WithOverrideProvider ¶

func WithOverrideProvider(p koanf.Provider, parser koanf.Parser, opts ...SourceOption) Option

WithOverrideProvider adds a koanf provider loaded above the environment, at the highest precedence — the place for explicit CLI flags (see the kongprovider package) and other operator overrides. Override providers load in the order added, a later one winning on a shared key. parser, ContextProvider and failures follow WithBaseProvider.

func WithPostLoad ¶

func WithPostLoad[T any](fn func(ctx context.Context, cfg *T) error) Option

WithPostLoad registers a hook that runs after decoding and secret resolution, and before validation: the place for derivation and normalization decode hooks cannot express — collapsing a shorthand into its canonical form, expanding a profile into the knobs it stands for, deriving a default from the host.

Because the hook runs inside the load, a Reloader applies it on every reload before deciding whether to swap, so normalization is covered by validate-before-swap. The same work done after Load returns is not: under a Reloader the new config is already live by the time it fails.

The hook mutates *cfg in place. Its error fails the load with ErrPostLoad and, under a Reloader, keeps the previous config. Hooks run in registration order; the first error stops the chain. A hook written for a type other than the one loaded fails the load before any source is read.

func WithRequiredFile ¶

func WithRequiredFile(path string) Option

WithRequiredFile adds a config file that must exist: a missing or unreadable file fails the load with ErrFileRead, one the file parser rejects with ErrFileParse.

func WithRequiredFiles ¶

func WithRequiredFiles(paths ...string) Option

WithRequiredFiles adds several required config files, merged in order.

func WithSecretPopulator ¶

func WithSecretPopulator(p SecretPopulator) Option

WithSecretPopulator sets the secret resolver. It runs after decoding with the load's context and a pointer to the decoded config; its error fails the load with ErrSecretProvider.

func WithShadowedInputs ¶ added in v0.10.0

func WithShadowedInputs(handle func(ctx context.Context, shadowed *ShadowedInputsError) error) Option

WithShadowedInputs decides what a load does with shadowed inputs: values a source sets for a key that a higher-precedence source also sets, so the lower value cannot take effect — a config file's key that a leftover environment variable or a typed flag also sets. handle is called with them whenever there are any, at every Load and every reload. A nil return lets the load go on; an error fails it with ErrValidation, the error kept as its cause. Return shadowed to require that every key have one source:

config.WithShadowedInputs(func(_ context.Context, shadowed *config.ShadowedInputsError) error {
    return shadowed
})

Overriding a file from the environment or the command line is a legitimate pattern, so without a handler shadowed inputs never fail a load: LoadSnapshot and every NewReloader load list them in Snapshot.Shadowed and log them at debug level, and Load does not look for them. A nil handle restores that default.

Two kinds of layering are designed overrides and never reported: defaults (default tags, Defaulter and WithDefaults) beneath any source, and the precedence inside the environment layer — WithEnvPrefixes' narrower prefixes over broader ones, prefixed names over env tag names — which is one source. Inputs are named by key and source, never value; an input at a key no field reads is left to WithUnknownKeys.

func WithSkipValidation ¶

func WithSkipValidation() Option

WithSkipValidation disables validation — the validator, validate:"required" included, and a root Validate method (see Validatable). Unknown keys still fail the load; WithUnknownKeys decides those separately.

func WithUnknownKeys ¶ added in v0.2.0

func WithUnknownKeys(handle func(ctx context.Context, unknown *UnknownKeysError) error) Option

WithUnknownKeys decides what a load does with input no field reads: keys a config file, provider or WithDefaults sets that no field decodes, and environment variables under a WithEnvPrefixes prefix that name no key under any of them. handle is called with them whenever there are any, at every Load and every reload, each with the key or variable it most likely misspells. A nil return lets the load go on without them; an error fails it with ErrValidation, the error kept as its cause. Return unknown to fail as the default does, or a copy holding only the keys that matter:

config.WithUnknownKeys(func(ctx context.Context, unknown *config.UnknownKeysError) error {
    logger.WarnContext(ctx, "config input no field reads", "error", unknown)
    return nil
})

Without it, a load fails on unknown keys, naming each one (server.prot, items[0].prot, named["primary"].prot), so a misspelled key cannot leave a service running on the default it was meant to override; unknown variables are logged at debug level and never fail it, since other programs may share the prefix. A nil handle restores that default.

The decoder reports the keys it did not use while it decodes the merged sources, so the check follows decoding exactly: into slice elements and map entries of structs, through squashed structs, and past input a decode hook or a self-decoding type consumes. A map's own keys, anything beneath an interface, and keys a koanf:",remain" field collects are accepted. A section no field holds is one key (legacy, not legacy.old). The merged tree does not record which source set a key, so keys are named, not their sources; values are never reported.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/ashtonian/pkg/config"
)

// tempFile writes content to a file in a new temporary directory and
// returns its path and a cleanup function.
func tempFile(name, content string) (string, func()) {
	dir, err := os.MkdirTemp("", "config-example")
	if err != nil {
		log.Fatal(err)
	}
	path := filepath.Join(dir, name)
	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
		log.Fatal(err)
	}
	return path, func() { _ = os.RemoveAll(dir) }
}

func main() {
	type AppConfig struct {
		Server struct {
			Port int `koanf:"port" default:"8080"`
		} `koanf:"server"`
	}
	file, cleanup := tempFile("config.yaml", "server:\n  prot: 9000\n")
	defer cleanup()

	cfg, err := config.Load[AppConfig](context.Background(),
		config.WithFile(file),
		config.WithEnvPrefix("APP"),
		config.WithEnviron(func() []string { return []string{"APP_SERVER_PROT=9000"} }),
		config.WithUnknownKeys(func(_ context.Context, unknown *config.UnknownKeysError) error {
			for _, k := range unknown.Keys {
				fmt.Printf("warning: unknown key %s, did you mean %s?\n", k.Key, k.Suggestion)
			}
			for _, v := range unknown.Variables {
				fmt.Printf("warning: unknown variable %s, did you mean %s?\n", v.Key, v.Suggestion)
			}
			return nil
		}))
	fmt.Println(cfg.Server.Port, err)

}

Output:
warning: unknown key server.prot, did you mean server.port?
warning: unknown variable APP_SERVER_PROT, did you mean APP_SERVER_PORT?
8080 <nil>

func WithValidator ¶

func WithValidator(v Validator) Option

WithValidator sets the validator. nil restores the default: a go-playground validator that names fields by config key. Register FieldName on a custom go-playground validator to get the same naming.

func WithVariableFilter ¶ added in v0.7.0

func WithVariableFilter(claimed func(name string) bool) Option

WithVariableFilter claims otherwise unmatched environment variable names for which claimed returns true. It sees names only, never values. A nil predicate clears the filter. The last call wins.

func WithFallbackEnvPrefixes ¶ added in v0.9.0

func WithFallbackEnvPrefixes(prefixes ...string) PrintOption

WithFallbackEnvPrefixes names the prefixes a WithEnvPrefixes load reads beneath the one PrintUsage, PrintTemplate and PrintEnv are given, in precedence order, so their output follows that load: a load with WithEnvPrefixes("APP_WORKER", "APP") is described by

config.PrintUsage[Config]("APP_WORKER", config.WithFallbackEnvPrefixes("APP"))

Every variable is listed in the order the load reads them. Where one variable is written for a key, as PrintEnv and FormatEnv write one, it is the one under the first prefix, and a name another key reads under any of the prefixes is not written. The last call wins.

func WithFormat ¶

func WithFormat(format string) PrintOption

WithFormat sets the output format. Each printer documents the formats it writes and its default; any other value makes it return an error.

func WithIncludeDescriptions ¶

func WithIncludeDescriptions() PrintOption

WithIncludeDescriptions includes desc:"" tag values in the printed output. When set, the table, JSON, and env output includes the desc:"description" tag value alongside each field.

func WithSortByName ¶

func WithSortByName() PrintOption

WithSortByName sorts output fields alphabetically by name.

func WithWriter ¶

func WithWriter(w io.Writer) PrintOption

WithWriter sets the output destination. Defaults to os.Stdout.

func Diagnose ¶

func Diagnose(err error) *Problem

Diagnose returns err as a Problem: the category of the sentinel it wraps and its message. A reload's error is categorized by what failed beneath ErrReload; an ApplyError is KindApply whatever its causes wrap. A nil error has no problem.

func WithApplier ¶

func WithApplier[T any](a Applier[T]) ReloadOption

WithApplier registers a; appliers run in registration order. An applier with no name or a repeated one, no Apply, or no prefix fails construction, as does a prefix that names no key of the config, reaches beneath an interface or a value compared whole, or is as specific as another applier's and could name the same key. See Applier.

With appliers registered, the reloader accounts for every key: a change no applier owns, or one an applier returned as a restart key, is reported in Snapshot.PendingRestart until it is applied or reverted. Register an applier for keys your code reads from Reloader.Config on every use, so they do not read as waiting for a restart.

func WithFileWatch ¶

func WithFileWatch(debounce time.Duration) ReloadOption

WithFileWatch reloads when a watched file changes: the config files of a NewReloader, and any given to WithWatchedFiles. debounce coalesces a burst of filesystem events (editors that rename and write, atomic-write tools) into one reload; zero or negative selects DefaultFileWatchDebounce. A continuous stream of events delays a reload by at most ten debounce windows. A reloader with nothing to watch fails construction.

Detected: direct writes, write-temp-then-rename saves, symlink swaps of the file or of any directory on its path, and a directory removed and recreated — including Kubernetes ConfigMap and Secret volume updates, where the watched path is a symlink into `..data` and the leaf file is never written. Paths resolve as the kernel resolves them, ".." after a symlink included, so the watch follows the file the loader opens. Every four debounce windows, and no more often than once a second (every 2s at the default debounce), the watch also resolves its paths again with no event to prompt it. That catches what sends the watch no event: an ancestor directory renamed away and recreated, whose event goes to the old tree; and, on kqueue platforms (macOS, *BSD), a relink whose only trace is a temporary name renamed over the link (`ln -s new link.tmp && mv -Tf link.tmp link`), which fsnotify there does not report because the directory's set of names is unchanged.

NOT detected:

• ConfigMap/Secret volumes mounted with subPath. kubelet cannot swap a symlink through a bind mount, so these never update in the container at all — neither a watch nor polling can see a change. Mount the volume without subPath.
• Sources that are not files: environment variables and providers. Use WithPollInterval, or Reloader.SourceChanged from whatever learns of the change.
• A symlink directly under the filesystem root, such as /var or /tmp on macOS, being re-pointed. Those belong to the OS; watching / would hold a descriptor per entry on kqueue and can block on automount points.

func WithOnReloadError ¶

func WithOnReloadError(fn func(trigger string, err error)) ReloadOption

WithOnReloadError registers a callback invoked after every failed reload, whatever triggered it — including the watchers Reloader.Run serves, whose errors would otherwise reach only the log. It fires in addition to the error Reloader.Reload returns. trigger is one of the Trigger* constants. Callbacks follow the WithOnReloadSuccess rules.

Reloads that reach no verdict — ErrReloadInProgress, ErrReloaderStopped, or a reload abandoned because its context ended — do not invoke it.

func WithOnReloadSuccess ¶

func WithOnReloadSuccess[T any](fn func(ctx context.Context, ev ReloadEvent[T])) ReloadOption

WithOnReloadSuccess registers a callback invoked after every successful reload with the reload's context and a ReloadEvent: the trigger, the config replaced and the one published, and the keys that changed. It runs after the swap, so it reacts to a config already live and cannot veto it. Every successful reload publishes and calls it, a poll that changed nothing included — its event's Changes is then empty. Callbacks run in registration order, panics are recovered, and they run while the reload holds the single-flight slot: hand long work off, and never call Reloader.Stop or Reloader.Arm from one. A callback written for a type other than the reloader's fails construction.

func WithPollInterval ¶

func WithPollInterval(interval time.Duration) ReloadOption

WithPollInterval reloads every interval: the fallback for sources without filesystem events (environment variables, providers) and for filesystems whose events are unreliable (NFS, some container runtimes). Every tick runs the whole pipeline, secrets included.

func WithProvenance ¶

func WithProvenance() ReloadOption

WithProvenance records where every key's value came from on each load, as LoadSnapshot does: Reloader.Snapshot carries the origins of the config it publishes, and a refused reload keeps the previous ones. It costs a copy and a comparison of the decoded config around the secret populator and each post-load hook, per load. It needs NewReloader's pipeline: NewReloaderFunc refuses it.

func WithReloadLogger ¶

func WithReloadLogger(logger *slog.Logger) ReloadOption

WithReloadLogger sets the logger for reload events. Without it, a NewReloader logs through its load options' WithLogger logger. A nil logger here, or no logger anywhere, means slog.Default() as it is when each line is written, so a reloader built before the process logger is configured logs through the configured one.

func WithReloadTagChecks ¶ added in v0.7.0

func WithReloadTagChecks() ReloadOption

WithReloadTagChecks enables WithReloadTags and rejects live keys with no applier, and appliers that own no live keys, with ErrSchema. It checks the whole schema, including collection patterns, before reading any sources.

func WithReloadTags ¶ added in v0.7.0

func WithReloadTags() ReloadOption

WithReloadTags enables the schema's reload classes for change routing. Restart keys are withheld from appliers and reported in PendingRestart. Other classes, including caller-defined labels, are live. A schema with no reload tags retains prefix-based routing. Metadata is available without this option; opting in separates declarations from existing caller-owned policy.

func WithSignalReload ¶

func WithSignalReload(signals ...os.Signal) ReloadOption

WithSignalReload reloads when the process receives one of signals, typically syscall.SIGHUP.

func WithWatchedFiles ¶

func WithWatchedFiles(paths ...string) ReloadOption

WithWatchedFiles adds files the file watch covers, and that Run compares with the last load once the watch is armed, beyond a NewReloader's config files: a file a secret populator or base provider reads, or, for NewReloaderFunc, the files the caller's loader reads.

func NewReloader ¶

func NewReloader[T any](ctx context.Context, loadOpts []Option, opts ...ReloadOption) (*Reloader[T], error)

NewReloader loads the initial config with Load's pipeline and loadOpts, and returns a Reloader that re-runs that pipeline, with the same options, on every reload. Each reload uses the ctx passed to Reload, or Run's for automatic triggers. The WithLogger logger in loadOpts also receives reload events unless WithReloadLogger sets another. The file watch covers the config files loadOpts name, and any WithWatchedFiles adds.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/ashtonian/pkg/config"
)

// tempFile writes content to a file in a new temporary directory and
// returns its path and a cleanup function.
func tempFile(name, content string) (string, func()) {
	dir, err := os.MkdirTemp("", "config-example")
	if err != nil {
		log.Fatal(err)
	}
	path := filepath.Join(dir, name)
	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
		log.Fatal(err)
	}
	return path, func() { _ = os.RemoveAll(dir) }
}

func main() {
	type AppConfig struct {
		Rate int `koanf:"rate" validate:"min=1"`
	}
	file, cleanup := tempFile("config.yaml", "rate: 10\n")
	defer cleanup()
	ctx := context.Background()

	reloader, err := config.NewReloader[AppConfig](ctx,
		[]config.Option{config.WithFile(file)},
		config.WithOnReloadSuccess(func(_ context.Context, ev config.ReloadEvent[AppConfig]) {
			old, new := ev.Old, ev.New
			fmt.Printf("rate %d -> %d\n", old.Rate, new.Rate)
		}),
	)
	if err != nil {
		fmt.Println("load:", err)
		return
	}
	defer func() { _ = reloader.Stop(ctx) }()

	_ = os.WriteFile(file, []byte("rate: 20\n"), 0o600)
	if _, err := reloader.Reload(ctx); err != nil {
		fmt.Println("reload:", err)
	}

	_ = os.WriteFile(file, []byte("rate: 0\n"), 0o600)
	_, err = reloader.Reload(ctx)
	fmt.Println(errors.Is(err, config.ErrReload), errors.Is(err, config.ErrValidation))
	fmt.Println("live rate:", reloader.Config().Rate)

}

Output:
rate 10 -> 20
true true
live rate: 20

func NewReloaderFunc ¶

func NewReloaderFunc[T any](ctx context.Context, load func(ctx context.Context) (*T, error), opts ...ReloadOption) (*Reloader[T], error)

NewReloaderFunc returns a Reloader whose loader is the caller's: load builds a complete, validated config, and its error keeps the previous one live. Use it to give an existing loading path the reload lifecycle. The file watch covers the files given to WithWatchedFiles; each reload compares them with what they held just before the previous load.

package main

import (
	"context"
	"fmt"

	"github.com/ashtonian/pkg/config"
)

func main() {
	type AppConfig struct{ Version int }
	version := 0
	load := func(context.Context) (*AppConfig, error) {
		version++
		return &AppConfig{Version: version}, nil
	}
	ctx := context.Background()
	reloader, err := config.NewReloaderFunc(ctx, load)
	if err != nil {
		fmt.Println("load:", err)
		return
	}
	defer func() { _ = reloader.Stop(ctx) }()

	fmt.Println(reloader.Config().Version)
	if _, err := reloader.Reload(ctx); err != nil {
		fmt.Println("reload:", err)
	}
	fmt.Println(reloader.Config().Version, reloader.Stats().Successes)

}

Output:
1
2 1

func SecretsFrom ¶

func SecretsFrom(fetch func(ctx context.Context, ref string) (string, error)) SecretPopulator

SecretsFrom returns a SecretPopulator that sets every field tagged secret:"<ref>" to what fetch returns for ref, decoded into the field's type as a source value is decoded — a string, an int, a duration:

type DBConfig struct {
    Host     string `koanf:"host" default:"localhost"`
    Password string `koanf:"password" secret:"prod/db#password"`
    User     string `koanf:"user" secret:"prod/db#username"`
    APIKey   string `koanf:"api_key" secret:"prod/api-key,optional"`
}

sm := secretsmanager.NewFromConfig(awsCfg)
cfg, err := config.Load[AppConfig](ctx, config.WithSecretPopulator(config.SecretsFrom(
    func(ctx context.Context, ref string) (string, error) {
        out, err := sm.GetSecretValue(ctx, &secretsmanager.GetSecretValueInput{SecretId: &ref})
        var missing *types.ResourceNotFoundException
        if errors.As(err, &missing) {
            return "", fmt.Errorf("%w: %s", config.ErrSecretNotFound, ref)
        }
        if err != nil {
            return "", err
        }
        return aws.ToString(out.SecretString), nil
    })))

A tag is ref[#field][,optional]. With #field the secret is a JSON object and the field takes that member — a store that keeps a database's username and password in one secret is fetched once for both. With ,optional a fetch error wrapping ErrSecretNotFound, or a missing member, leaves the field as the sources set it, so a development file can supply what production keeps in the store. A tag of "-" names no secret.

The fetched value replaces whatever the sources set. fetch runs once per ref per load, with the load's context, in declaration order. Any other failure fails the load with ErrSecretProvider, naming the key and the ref and wrapping fetch's error; a value that does not decode into its field is reported by type, never quoted. A field tagged secret is sensitive in every output, like sensitive:"true". A field behind a nil pointer — a section no source configured — is left alone. A secret tag inside a map or list cannot name one ref for every entry, and fails the load.

func LoadSnapshot ¶

func LoadSnapshot[T any](ctx context.Context, opts ...Option) (Snapshot[T], error)

LoadSnapshot runs Load and records where every key's value came from: the snapshot's Provenance holds an Origin for each key, and its Generation is 0. Recording costs a tree of the merged sources, a copy and a comparison of the decoded config around the secret populator and each post-load hook, and one walk for the rows. The snapshot's Shadowed lists the inputs a higher-precedence source outranks. Load records nothing, unless WithShadowedInputs asks it to find shadowed inputs.

func WithInvalidEntries ¶ added in v0.8.0

func WithInvalidEntries(report func(context.Context, []KeyError) error) SourceOption

WithInvalidEntries withholds known entries that fail CheckKey, preserving lower-precedence values. report receives the sorted rejected keys after each read, including an empty slice when none were rejected; nil discards the report. Its error fails the load with ErrSource. Report errors omit values; their wrapped causes are intended only for trusted diagnostics.

Struct sections are checked field by field; collections and self-decoding values are atomic entries. Defaults must validate before any provider is read, so a broken baseline cannot be mistaken for bad stored entries. Unknown entries remain available to the normal unknown-input handler, including declared unknown children of a withheld collection. Read/parser errors and cancellation still fail the load. The final merged configuration must validate: cross-field failures are never resolved by choosing entries to discard.

func Usage ¶ added in v0.7.0

func Usage[T any](envPrefixes ...string) ([]UsageEntry, error)

Usage returns the catalog rendered by PrintUsage, in declaration order, naming each key's variables under envPrefixes as WithEnvPrefixes takes them: Env is the one under the first prefix, AlsoEnv the rest in precedence order, and EnvVars all of them. Defaults that are sensitive or could contain secrets are empty and Withheld is true. Allowed follows JSONSchema's enum and withholding rules. Collection entries use [*] patterns and environment placeholders where supported.