envconfig

package module
v0.0.0-...-b10d79e Latest Latest
Warning

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

Go to latest
Published: Jan 12, 2023 License: Apache-2.0 Imports: 14 Imported by: 0

README

Envconfig

GoDoc GitHub Actions

Envconfig populates struct field values based on environment variables or arbitrary lookup functions. It supports pre-setting mutations, which is useful for things like converting values to uppercase, trimming whitespace, or looking up secrets.

Note: Versions prior to v0.2 used a different import path. This README and examples are for v0.2+.

Usage

Define a struct with fields using the env tag:

type MyConfig struct {
  Port     int    `env:"PORT"`
  Username string `env:"USERNAME"`
}

Set some environment variables:

export PORT=5555
export USERNAME=yoyo

Process it using envconfig:

package main

import (
  "context"
  "log"

  "github.com/sethvargo/go-envconfig"
)

func main() {
  ctx := context.Background()

  var c MyConfig
  if err := envconfig.Process(ctx, &c); err != nil {
    log.Fatal(err)
  }

  // c.Port = 5555
  // c.Username = "yoyo"
}

You can also use nested structs, just remember that any fields you want to process must be public:

type MyConfig struct {
  Database *DatabaseConfig
}

type DatabaseConfig struct {
  Port     int    `env:"PORT"`
  Username string `env:"USERNAME"`
}

Configuration

Use the env struct tag to define configuration.

Required

If a field is required, processing will error if the environment variable is unset.

type MyStruct struct {
  Port int `env:"PORT,required"`
}

It is invalid to have a field as both required and default.

Default

If an environment variable is not set, the field will be set to the default value. Note that the environment variable must not be set (e.g. unset PORT). If the environment variable is the empty string, that counts as a "value" and the default will not be used.

type MyStruct struct {
  Port int `env:"PORT,default=5555"`
}

You can also set the default value to another field or value from the environment, for example:

type MyStruct struct {
  DefaultPort int `env:"DEFAULT_PORT,default=5555"`
  Port        int `env:"OVERRIDE_PORT,default=$DEFAULT_PORT"`
}

The value for Port will default to the value of DEFAULT_PORT.

It is invalid to have a field as both required and default.

Prefix

For shared, embedded structs, you can define a prefix to use when processing struct values for that embed.

type SharedConfig struct {
  Port int `env:"PORT,default=5555"`
}

type Server1 struct {
  // This processes Port from $FOO_PORT.
  *SharedConfig `env:",prefix=FOO_"`
}

type Server2 struct {
  // This processes Port from $BAR_PORT.
  *SharedConfig `env:",prefix=BAR_"`
}

It is invalid to specify a prefix on non-struct fields.

Overwrite

If overwrite is set, the value will be overwritten if there is an environment variable match regardless if the value is non-zero.

type MyStruct struct {
  Port int `env:"PORT,overwrite"`
}

The rules for overwrite + default are:

  • If the struct field has the zero value and a default is set:

    • If no environment variable is specified, the struct field will be populated with the default value.

    • If an environment variable is specified, the struct field will be populate with the environment variable value.

  • If the struct field has a non-zero value and a default is set:

    • If no environment variable is specified, the struct field's existing value will be used (the default is ignored).

    • If an environment variable is specified, the struct field's existing value will be overwritten with the environment variable value.

Complex Types

Note: Complex types are only decoded or unmarshalled when the environment variable is defined or a default is specified. The decoding/unmarshalling functions are not invoked when a value is not defined.

Durations

In the environment, time.Duration values are specified as a parsable Go duration:

type MyStruct struct {
  MyVar time.Duration `env:"MYVAR"`
}
export MYVAR="10m" # 10 * time.Minute
TextUnmarshaler / BinaryUnmarshaler

Types that implement TextUnmarshaler or BinaryUnmarshaler are processed as such.

json.Unmarshaler

Types that implement json.Unmarshaler are processed as such.

gob.Decoder

Types that implement gob.Decoder are processed as such.

Slices

Slices are specified as comma-separated values:

type MyStruct struct {
  MyVar []string `env:"MYVAR"`
}
export MYVAR="a,b,c,d" # []string{"a", "b", "c", "d"}

Define a custom delimiter with delimiter:

type MyStruct struct {
  MyVar []string `env:"MYVAR,delimiter=;"`
export MYVAR="a;b;c;d" # []string{"a", "b", "c", "d"}

Note that byte slices are special cased and interpreted as strings from the environment.

Maps

Maps are specified as comma-separated key:value pairs:

type MyStruct struct {
  MyVar map[string]string `env:"MYVAR"`
}
export MYVAR="a:b,c:d" # map[string]string{"a":"b", "c":"d"}

Define a custom delimiter with delimiter:

type MyStruct struct {
  MyVar map[string]string `env:"MYVAR,delimiter=;"`
export MYVAR="a:b;c:d" # map[string]string{"a":"b", "c":"d"}

Define a separator with separator:

type MyStruct struct {
  MyVar map[string]string `env:"MYVAR,separator=|"`
}
export MYVAR="a|b,c|d" # map[string]string{"a":"b", "c":"d"}
Structs

Envconfig walks the entire struct, including nested structs, so deeply-nested fields are also supported.

If a nested struct is a pointer type, it will automatically be instantianted to the non-nil value. To change this behavior, see Initialization.

Custom

You can also define your own decoder.

Prefixing

You can define a custom prefix using the PrefixLookuper. This will lookup values in the environment by prefixing the keys with the provided value:

type MyStruct struct {
  MyVar string `env:"MYVAR"`
}
// Process variables, but look for the "APP_" prefix.
l := envconfig.PrefixLookuper("APP_", envconfig.OsLookuper())
if err := envconfig.ProcessWith(ctx, &c, l); err != nil {
  panic(err)
}
export APP_MYVAR="foo"

Initialization

By default, all pointer fields are initialized (allocated) so they are not nil. To disable this behavior, use the tag the field as noinit:

type MyStruct struct {
  // Without `noinit`, DeleteUser would be initialized to the default boolean
  // value. With `noinit`, if the environment variable is not given, the value
  // is kept as uninitialized (nil).
  DeleteUser *bool `env:"DELETE_USER, noinit"`
}

This also applies to nested fields in a struct:

type ParentConfig struct {
  // Without `noinit` tag, `Child` would be set to `&ChildConfig{}` whether
  // or not `FIELD` is set in the env var.
  // With `noinit`, `Child` would stay nil if `FIELD` is not set in the env var.
  Child *ChildConfig `env:",noinit"`
}

type ChildConfig struct {
  Field string `env:"FIELD"`
}

The noinit tag is only applicable for pointer fields. Putting the tag on a non-struct-pointer will return an error.

Extension

All built-in types are supported except Func and Chan. If you need to define a custom decoder, implement the Decoder interface:

type MyStruct struct {
  field string
}

func (v *MyStruct) EnvDecode(val string) error {
  v.field = fmt.Sprintf("PREFIX-%s", val)
  return nil
}

If you need to modify environment variable values before processing, you can specify a custom Mutator:

type Config struct {
  Password `env:"PASSWORD"`
}

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
envconfig.ProcessWith(ctx, &config, envconfig.OsLookuper(), resolveSecretFunc)

Testing

Relying on the environment in tests can be troublesome because environment variables are global, which makes it difficult to parallelize the tests. Envconfig supports extracting data from anything that returns a value:

lookuper := envconfig.MapLookuper(map[string]string{
  "FOO": "bar",
  "ZIP": "zap",
})

var config Config
envconfig.ProcessWith(ctx, &config, lookuper)

Now you can parallelize all your tests by providing a map for the lookup function. In fact, that's how the tests in this repo work, so check there for an example.

You can also combine multiple lookupers with MultiLookuper. See the GoDoc for more information and examples.

Inspiration

This library is conceptually similar to kelseyhightower/envconfig, with the following major behavioral differences:

  • Adds support for specifying a custom lookup function (such as a map), which is useful for testing.

  • Only populates fields if they contain zero or nil values if overwrite is unset. This means you can pre-initialize a struct and any pre-populated fields will not be overwritten during processing.

  • Support for interpolation. The default value for a field can be the value of another field.

  • Support for arbitrary mutators that change/resolve data before type conversion.

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

View Source
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

func Process(ctx context.Context, i interface{}) error

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) Bytes

func (b Base64Bytes) Bytes() []byte

Bytes returns the underlying bytes.

func (*Base64Bytes) EnvDecode

func (b *Base64Bytes) EnvDecode(val string) error

EnvDecode implements env.Decoder.

type Decoder

type Decoder interface {
	EnvDecode(val string) error
}

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 Error

type Error string

Error is a custom error type for errors returned by envconfig.

func (Error) Error

func (e Error) Error() string

Error implements error.

type HexBytes

type HexBytes []byte

HexBytes is a slice of bytes where the information is hex-encoded in the environment variable.

func (HexBytes) Bytes

func (b HexBytes) Bytes() []byte

Bytes returns the underlying bytes.

func (*HexBytes) EnvDecode

func (b *HexBytes) EnvDecode(val string) error

EnvDecode implements env.Decoder.

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

func MapLookuper(m map[string]string) Lookuper

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

func MultiLookuper(lookupers ...Lookuper) Lookuper

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

func PrefixLookuper(prefix string, l Lookuper) Lookuper

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_".

type MutatorFunc

type MutatorFunc func(ctx context.Context, k, v string) (string, error)

MutatorFunc is a function that mutates a given value before it is passed along for processing. This is useful if you want to mutate the environment variable value before it's converted to the proper type.

Jump to

Keyboard shortcuts

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