configs

README

Overview

This library helps applications work with configs through environment variables. It's a more opinionated and much smaller version of Viper. It assumes you're following the 12 factor app recommendations for configs and logging.

Goals

Applications generally want to do the following:

1. Define some default config values which work in development.
2. Let apps overwrite defaults with environment variables.
3. Validate the config values.
4. Log values of any config variables except for credentials.

This library's goal is to make these steps as painless as possible.

Usage

Define structs and tag them with the names of environment variables:

type struct Config {
  Main Server `environment:"MAIN"`
  Admin Server `environment:"ADMIN"`
  Password string `environment:"PASSWORD"`
}

type struct Server {
  Port int `environment:"PORT"`
}

Set some environment variables in your shell.

export MYAPP_MAIN_PORT=80
export MYAPP_ADMIN_PORT=81
export MYAPP_PASSWORD=boo

Reference them in the code like so:

import (
  "github.com/wikisophia/go-environment-configs"
)

func Parse() Config {
  // Define defaults by setting the initial struct values.
  cfg := Config{
    Main: Server{
      Port: 80
    },
    Admin: Server{
      Port: 81
    }
  }

  // Overwrite the defaults with environment variables.
  // Panic with a descriptive error message if the values don't match the types.
  configs.MustLoadWithPrefix(&cfg, "MYAPP")

  // Print the config values.
  // Anything named "password" will be logged as "<redacted>"
  configs.LogWithPrefix(&cfg, "MYAPP")
}

The "Prefix" is intended as a namespace to help separate your app's environment variables from others running on the same system.

This library only handles type-based valiation. The Load() functions will return errors or panic if an environment variable has a value which can't fit into the Config struct, but any extra validation is on the caller. For example:

  cfg := Config{
    // Set defaults like above
  }

  err := configs.LoadWithPrefix(&cfg, "MYAPP")

  // Add app-specific validation errors. The library will collect these
  // alongside errors generated by LoadWithPrefix for pretty printing.
  err = configs.Ensure(err, "MYAPP_MAIN_PORT", cfg.Main.Port > 0, "must be a positive integer")

Contributing

This library doesn't yet support all the struct property types... just the ones that I've needed for projects so far. This covers the common ones, but certainly not all of them. Feel free to contribute support for any new types you need.

Documentation

Index

• func Ensure(err error, key string, predicate bool, msgFormat string, ...) error
• func LoadWithPrefix(container interface{}, prefix string) error
• func LogWithPrefix(container interface{}, prefix string)
• func MustLoadWithPrefix(container interface{}, prefix string)

Functions

func Ensure

func Ensure(err error, key string, predicate bool, msgFormat string, msgArgs ...interface{}) error

Ensure adds custom error messagse to the error returned by LoadWithPrefix().

Normal usage looks like this:

err := configs.LoadWithPrefix(&cfg, "MYAPP")
err = configs.Ensure(err, "MYAPP_PORT", cfg.Port > 0, "must be a positive integer")
err = configs.Ensure(err, "MYAPP_ENV", isValid(cfg.ENV), "must be one of: %v", validEnvs)

If predicate is true, err is returned unchanged. If predicate is false and err is nil, a new error will be returned.

In all cases the returned error will "pretty print" your validation error alongside any errors generated by the LoadWithPrefix() call.

func LoadWithPrefix

func LoadWithPrefix(container interface{}, prefix string) error

LoadWithPrefix loads the values of environment variables into a struct. It returns an error if any of the environment variable values don't match the type defined on the struct.

func LogWithPrefix

func LogWithPrefix(container interface{}, prefix string)

LogWithPrefix prints all the environment variables and their values on container to stdout, excluding any which include the name "password" (for security)

func MustLoadWithPrefix

func MustLoadWithPrefix(container interface{}, prefix string)

MustLoadWithPrefix loads the environment variables into a struct. It panics if any of the environment variables' values can't be coerced into the type defined on the struct.