Documentation ¶
Overview ¶
Package envconfig populates struct fields based on environment variable values (or anything that responds to "Lookup"). Structs declare their environment dependencies using the "env" tag with the key being the name of the environment variable, case sensitive.
type MyStruct struct { A string `env:"A"` // resolves A to $A B string `env:"B,required"` // resolves B to $B, errors if $B is unset C string `env:"C,default=foo"` // resolves C to $C, defaults to "foo" D string `env:"D,required,default=foo"` // error, cannot be required and default E string `env:""` // error, must specify key }
All built-in types are supported except Func and Chan. If you need to define a custom decoder, implement Decoder:
type MyStruct struct { field string } func (v *MyStruct) EnvDecode(val string) error { v.field = fmt.Sprintf("PREFIX-%s", val) return nil }
In the environment, slices are specified as comma-separated values:
export MYVAR="a,b,c,d" // []string{"a", "b", "c", "d"}
In the environment, maps are specified as comma-separated key:value pairs:
export MYVAR="a:b,c:d" // map[string]string{"a":"b", "c":"d"}
If you need to modify environment variable values before processing, you can specify a custom mutator:
type Config struct { Password `env:"PASSWORD_SECRET"` } func resolveSecretFunc(ctx context.Context, key, value string) (string, error) { if strings.HasPrefix(value, "secret://") { return secretmanager.Resolve(ctx, value) // example } return value, nil } var config Config ProcessWith(&config, OsLookuper(), resolveSecretFunc)
Index ¶
- Constants
- func ExtractDefaults(ctx context.Context, i interface{}, fns ...MutatorFunc) error
- func Process(ctx context.Context, i interface{}) error
- func ProcessWith(ctx context.Context, i interface{}, l Lookuper, fns ...MutatorFunc) error
- type Base64Bytes
- type Decoder
- type Error
- type HexBytes
- type Lookuper
- type MutatorFunc
Constants ¶
const ( ErrInvalidEnvvarName = Error("invalid environment variable name") ErrInvalidMapItem = Error("invalid map item") ErrLookuperNil = Error("lookuper cannot be nil") ErrMissingKey = Error("missing key") ErrMissingRequired = Error("missing required value") ErrNoInitNotPtr = Error("field must be a pointer to have noinit") ErrNotPtr = Error("input must be a pointer") ErrNotStruct = Error("input must be a struct") ErrPrefixNotStruct = Error("prefix is only valid on struct types") ErrPrivateField = Error("cannot parse private fields") ErrRequiredAndDefault = Error("field cannot be required and have a default value") ErrUnknownOption = Error("unknown option") )
Variables ¶
This section is empty.
Functions ¶
func ExtractDefaults ¶
func ExtractDefaults(ctx context.Context, i interface{}, fns ...MutatorFunc) error
ExtractDefaults is a helper that returns a fully-populated struct with the default values resolved. This is helpful when you want to return a constant "default" configuration that is not affected by the user's environment.
type Config struct { Port string `env:"PORT,default=8080"` } func DefaultConfig() *Config { var cfg Config if err := envconfig.ExtractDefaults(ctx, &cfg); err != nil { panic("failed to extract default config: %s" + err.Error()) } return &cfg }
This is effectively the same as calling ProcessWith with an empty MapLookuper.
func Process ¶
Process processes the struct using the environment. See ProcessWith for a more customizable version.
func ProcessWith ¶
func ProcessWith(ctx context.Context, i interface{}, l Lookuper, fns ...MutatorFunc) error
ProcessWith processes the given interface with the given lookuper. See the package-level documentation for specific examples and behaviors.
Types ¶
type Base64Bytes ¶
type Base64Bytes []byte
Base64Bytes is a slice of bytes where the information is base64-encoded in the environment variable.
func (*Base64Bytes) EnvDecode ¶
func (b *Base64Bytes) EnvDecode(val string) error
EnvDecode implements env.Decoder.
type Decoder ¶
Decoder is an interface that custom types/fields can implement to control how decoding takes place. For example:
type MyType string func (mt MyType) EnvDecode(val string) error { return "CUSTOM-"+val }
type HexBytes ¶
type HexBytes []byte
HexBytes is a slice of bytes where the information is hex-encoded in the environment variable.
type Lookuper ¶
type Lookuper interface { // Lookup searches for the given key and returns the corresponding string // value. If a value is found, it returns the value and true. If a value is // not found, it returns the empty string and false. Lookup(key string) (string, bool) }
Lookuper is an interface that provides a lookup for a string-based key.
func MapLookuper ¶
MapLookuper looks up environment configuration from a provided map. This is useful for testing, especially in parallel, since it does not require you to mutate the parent environment (which is stateful).
func MultiLookuper ¶
MultiLookuper wraps a collection of lookupers. It does not combine them, and lookups appear in the order in which they are provided to the initializer.
func OsLookuper ¶
func OsLookuper() Lookuper
OsLookuper returns a lookuper that uses the environment (os.LookupEnv) to resolve values.
func PrefixLookuper ¶
PrefixLookuper looks up environment configuration using the specified prefix. This is useful if you want all your variables to start with a particular prefix like "MY_APP_".