Documentation
¶
Overview ¶
Package provider abstracts external configuration sources (env, CLI, KV, Vault, ...). Providers are second-class citizens of the reload pipeline: their output is merged into the same map[string]any that file discovery produces, after which the merged document is decoded into the user's strongly-typed *T.
The Provider/Event interface itself lives in fastconf/contracts; this package re-exports it (see aliases.go) and ships the built-in Env/CLI/ File implementations.
Index ¶
- func AutoDotEnvPaths(configDir string) []string
- type CLIProvider
- type DotEnvProvider
- type EnvKeyReplacer
- type EnvKeyReplacerFunc
- type EnvProvider
- type LabelOptions
- type LabelProvider
- type ReplacerProvider
- func (p *ReplacerProvider) Load(_ context.Context) (map[string]any, error)
- func (p *ReplacerProvider) Name() string
- func (p *ReplacerProvider) Priority() int
- func (p *ReplacerProvider) Watch(_ context.Context) (<-chan contracts.Event, error)
- func (p *ReplacerProvider) WithPriority(prio int) *ReplacerProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AutoDotEnvPaths ¶
AutoDotEnvPaths returns the default .env file search paths for WithDotEnvAuto: [configDir + "/.env", ".env"]. Missing files are skipped by DotEnvProvider.Load, so callers do not need to pre-check existence.
Types ¶
type CLIProvider ¶
type CLIProvider struct {
// contains filtered or unexported fields
}
CLIProvider exposes a pre-parsed map (typically built by the user from command-line flags) as the highest-priority static provider. Users wire it up in main() after their flag parsing completes — fastconf does not own the flag set.
func (*CLIProvider) Watch ¶
Watch implements Provider. CLI is fundamentally static for the process lifetime.
func (*CLIProvider) WithPriority ¶
func (p *CLIProvider) WithPriority(prio int) *CLIProvider
WithPriority overrides the default priority.
type DotEnvProvider ¶
type DotEnvProvider struct {
// contains filtered or unexported fields
}
DotEnvProvider reads one or more .env files and emits a nested map using the same key convention as EnvProvider: an optional prefix is stripped and "__" (double underscore) introduces a nesting level. Actual process environment variables take precedence over .env values for the same key, matching the classic dotenv contract.
Priority defaults to PriorityDotEnv (5), so all other built-in providers override dotenv values.
Supported .env syntax:
- KEY=VALUE (unquoted; trailing spaces trimmed)
- KEY="double quoted" (supports \n \t \" \\ escapes)
- KEY='single quoted' (no escapes; literal content)
- export KEY=VALUE (leading "export" keyword stripped)
- # comment lines
- Blank lines are ignored.
func NewDotEnv ¶
func NewDotEnv(prefix string, paths ...string) *DotEnvProvider
NewDotEnv builds a DotEnvProvider that reads the given .env file paths. prefix follows the same convention as NewEnv: e.g. "APP_" so that APP_DATABASE__HOST=db yields {"database":{"host":"db"}}.
func (*DotEnvProvider) Priority ¶
func (p *DotEnvProvider) Priority() int
Priority implements Provider.
func (*DotEnvProvider) WithPriority ¶
func (p *DotEnvProvider) WithPriority(prio int) *DotEnvProvider
WithPriority overrides the default priority.
type EnvKeyReplacer ¶
EnvKeyReplacer transforms the post-prefix portion of an env var name into a dotted-path string. Empty result means "skip this key".
var DotReplacer EnvKeyReplacer = EnvKeyReplacerFunc(func(s string) string { return strings.ToLower(strings.ReplaceAll(s, "_", ".")) })
DotReplacer is the canonical "single underscore → dot" replacer matching Viper's SetEnvKeyReplacer(strings.NewReplacer(".", "_")).
APP_DATABASE_DSN, prefix="APP_" → "database.dsn"
type EnvKeyReplacerFunc ¶
EnvKeyReplacerFunc is an EnvKeyReplacer adapter for plain funcs.
func (EnvKeyReplacerFunc) Replace ¶
func (f EnvKeyReplacerFunc) Replace(s string) string
Replace implements EnvKeyReplacer.
type EnvProvider ¶
type EnvProvider struct {
// contains filtered or unexported fields
}
EnvProvider reads process environment variables matching a prefix and translates them into a nested map. Conventions:
- Prefix is stripped.
- "__" (double underscore) introduces a nesting level. Single underscore is preserved as part of the key (handles names like APP_FEATURE_FLAGS).
- Keys are lower-cased.
- Values are coerced to bool / int64 / float64 / string in that order.
Example: APP_DATABASE__POOL=20 with prefix "APP_" produces {"database":{"pool":int64(20)}}.
func NewEnv ¶
func NewEnv(prefix string) *EnvProvider
NewEnv builds an EnvProvider with the given prefix (e.g. "APP_") and the default Env priority.
func (*EnvProvider) WithPriority ¶
func (p *EnvProvider) WithPriority(prio int) *EnvProvider
WithPriority overrides the default priority.
type LabelOptions ¶
type LabelOptions struct {
// Name overrides the default Provider name (otherwise "labels:<prefix>"
// or "labels:" when prefix is empty).
Name string
// Priority sets the merge priority. Defaults to PriorityCLI so labels
// from a controller / docker engine override file layers.
Priority int
// Prefix, when non-empty, restricts expansion to labels whose key starts
// with this prefix (e.g. "traefik.").
Prefix string
// StripPrefix removes Prefix from each key before expansion.
StripPrefix bool
// Separator splits a flat key into nested segments. Default ".".
Separator string
// Coerce, when true, converts "true"/"false"/int/float strings into typed
// values. Default false: values are kept verbatim (matches Traefik /
// Compose label semantics).
Coerce bool
}
LabelOptions configures a LabelProvider. Mirrors mappath.LabelOptions so callers do not need to import two packages.
type LabelProvider ¶
type LabelProvider struct {
// contains filtered or unexported fields
}
LabelProvider injects a flat list (or map) of Traefik / Docker / K8s style dotted labels as a single configuration layer. Use it when labels arrive from outside the configuration file — e.g. a Docker engine query, a K8s controller scanning service annotations, or a CLI flag with --label.
LabelProvider is read-only and does not implement Watch; pair it with a fastconf.Reload(ctx) call when the upstream label set changes.
func NewLabelMap ¶
func NewLabelMap(labels map[string]string, opts LabelOptions) *LabelProvider
NewLabelMap constructs a LabelProvider from a key→value map, matching the Docker engine API / K8s annotation form.
func NewLabels ¶
func NewLabels(labels []string, opts LabelOptions) *LabelProvider
NewLabels constructs a LabelProvider from a list of "key=value" strings, matching the Compose / docker CLI --label form.
func (*LabelProvider) Priority ¶
func (p *LabelProvider) Priority() int
Priority implements Provider.
type ReplacerProvider ¶
type ReplacerProvider struct {
// contains filtered or unexported fields
}
ReplacerProvider is an EnvProvider variant that routes the post-prefix portion of each env name through Replacer before building the nested map. Value coercion (bool / int / float / string) is identical to EnvProvider.
func NewEnvReplacer ¶
func NewEnvReplacer(prefix string, replacer EnvKeyReplacer) *ReplacerProvider
NewEnvReplacer builds a ReplacerProvider with the given prefix and replacer. If replacer is nil, DotReplacer is used.
func (*ReplacerProvider) Name ¶
func (p *ReplacerProvider) Name() string
Name implements contracts.Provider.
func (*ReplacerProvider) Priority ¶
func (p *ReplacerProvider) Priority() int
Priority implements contracts.Provider.
func (*ReplacerProvider) WithPriority ¶
func (p *ReplacerProvider) WithPriority(prio int) *ReplacerProvider
WithPriority overrides the default priority.
Source Files