config

package
v0.83.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package config loads service configuration from defaults, files, environment variables, and command-line flags. Values are applied in that order, so an explicitly changed flag has the highest precedence.

Configuration keys come from the struct tag selected by Options.TagName, which defaults to "mapstructure". Environment variable names are inferred from those keys with the NB prefix. For example, server.listen-address maps to NB_SERVER_LISTEN_ADDRESS. The env and flag tags can provide explicit names, comma-separated compatibility aliases, or "-" to disable a source.

A typical service configuration can be loaded as follows:

type Config struct {
	Address string        `yaml:"address" env:"NB_ADDRESS" flag:"address"`
	Timeout time.Duration `yaml:"timeout"`
}

flags := pflag.NewFlagSet("service", pflag.ContinueOnError)
flags.String("address", ":443", "service listen address")

cfg, err := config.Load("config.yaml", &Config{
	Address: ":443",
	Timeout: 30 * time.Second,
}, config.Options{
	TagName: "yaml",
	FlagSet: flags,
	Strict:  true,
})

Set Options.AllowMissing when the service must start without a configuration file. Options.Transform can preprocess file contents before decoding.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Load

func Load[T any](configPath string, cfg *T, options Options) (*T, error)

Load reads configuration into a default-initialized value. Explicitly tagged environment values and changed flags override file values.

Types

type InvalidEnvironmentAction

type InvalidEnvironmentAction uint8

InvalidEnvironmentAction controls how invalid environment values are handled.

const (
	// InvalidEnvironmentFatal returns the parsing error.
	InvalidEnvironmentFatal InvalidEnvironmentAction = iota
	// InvalidEnvironmentIgnore keeps the file or default value.
	InvalidEnvironmentIgnore
	// InvalidEnvironmentUsePartial keeps scalar values returned with parsing errors.
	InvalidEnvironmentUsePartial
)

type Options

type Options struct {
	// TagName selects the struct tag and decoder used for configuration keys.
	TagName string
	// AllowMissing permits an empty path or a file that does not exist.
	AllowMissing bool
	// FlagSet provides command-line flags referenced by `flag` struct tags.
	FlagSet *pflag.FlagSet
	// Transform rewrites configuration file contents before decoding.
	Transform func([]byte) ([]byte, error)
	// Strict rejects configuration keys that are not represented by the target type.
	Strict bool
	// InvalidEnvironment controls how parsing failures affect the loaded value.
	InvalidEnvironment InvalidEnvironmentAction
	// DecodeErrorPrefix preserves service-specific context for file decoding errors.
	DecodeErrorPrefix string
}

Options controls how Load resolves files and fields.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL