auconfigenv

README

go-autumn-config-env

About go-autumn-config-env

A library that handles configuration for enterprise microservices.

This is a lightweight alternative to go-autumn-config that is tailored specifically towards 15 factor microservices, especially when run in a container.

In order of precedence, configuration values come from

• environment variables
• an optional flat configuration file (intended for use in local development only)
• hardcoded defaults

There is no support for structured configuration values. Just like environment variables, configuration values are strings only.

There is no support for command line switches.

There is no support for application profiles.

There is no support for a separate file for secrets.

On the plus side, this guides developers on the right path towards a 15 factor app, and there is a minimal dependency and runtime footprint.

How to use

We recommend collecting all configuration related code in a package internal/repository/configuration.

You configure the configuration subsystem by a call to auconfigenv.Setup(...). This function takes 2 arguments:

• a list of auconfigapi.ConfigItem to specify what configuration items exist
• a warning message handler of type auconfigapi.ConfigWarnFunc, which should probably log a warning using your preferred logging framework. log.Print satisfies the type requirements, but again we hope this is not what you'll use in production...

See go-autumn-config-api for the precise type definitions.

When you request your configuration to be loaded, which you must do yourself with a call to auconfigenv.Read(), every key is assigned its value by going through the following precedence list:

• environment variable
• configuration read from local-config.yaml
• default value specified in ConfigItems

Once loaded, validate the values by calling auconfigenv.Validate() to validate each configuration entry. It will use the warning message callback to notify you about individual errors, and if any validation errors were found, return an error at the end.

Once loaded (even before validation), access configuration values by calling auconfigenv.Get(key), which returns the cached string value.

We also export auconfigenv.Set(key, value), which allows injecting configuration values at runtime, for example after querying a secrets management solution such as OpenBAO, or during tests.

Structured data under a key

... is not directly supported, but you can parse JSON from configuration values, and the validation function can check validity and correctness.

Examples:

Using this can be as simple as:

package configuration

import (
	"fmt"
	"github.com/StephanHCB/go-autumn-config-api"
	"github.com/StephanHCB/go-autumn-config-env"
	"log"
    "strconv"
)

// custom validation function example
func checkValidPortNumber(key string) error {
    portStr := auconfigenv.Get(key)
    port, err := strconv.Atoi(portStr)
    if err != nil {
        return fmt.Errorf("fatal error: configuration value for key %s is not a valid number: %s", key, err.Error())
    }
    if port < 1024 || port > 65535 {
        return fmt.Errorf("fatal error: configuration value for key %s is not in range 1024..65535", key)
    }
    return nil
}

// define what configuration items you want
var configItems = []auconfigapi.ConfigItem{
	{
		Key:         "server.address",
		Default:     "",
		Description: "ip address or hostname to listen on, can be left blank for localhost",
		Validate:    auconfigapi.ConfigNeedsNoValidation,
	}, {
		Key:         "server.port",
		Default:     "8080",
		Description: "port to listen on, defaults to 8080 if not set",
		Validate:    checkValidPortNumber,
	},
}

// initialize the library.
func Setup() {
    _ = auconfigenv.Setup(configItems, log.Print)
	_ = auconfigenv.Read()
	_ = auconfigenv.Validate()
}

// provide accessor functions

func ServerAddress() string {
	return fmt.Sprintf("%s:%s", auconfigenv.Get("server.address"), auconfigenv.Get("server.port"))
}

Documentation

Index

• Variables
• func AToInt(s string) (int, error)
• func AToUint(s string) (uint, error)
• func Get(key string) string
• func ObtainIntRangeValidator(min int, max int) auconfigapi.ConfigValidationFunc
• func ObtainIsBooleanValidator() auconfigapi.ConfigValidationFunc
• func ObtainIsRegexValidator() auconfigapi.ConfigValidationFunc
• func ObtainNotEmptyValidator() auconfigapi.ConfigValidationFunc
• func ObtainPatternValidator(pattern string) auconfigapi.ConfigValidationFunc
• func ObtainSingleCharacterValidator() auconfigapi.ConfigValidationFunc
• func ObtainUintRangeValidator(min uint, max uint) auconfigapi.ConfigValidationFunc
• func Read() error
• func ReadYaml(filename string) error
• func Set(key string, value string)
• func Setup(items []auconfigapi.ConfigItem, warnFunc auconfigapi.ConfigWarnFunc) error
• func Validate() error

Variables

var LocalConfigFileName = "local-config.yaml"

Functions

func AToInt

func AToInt(s string) (int, error)

func AToUint

func AToUint(s string) (uint, error)

func Get

func Get(key string) string

func ObtainIntRangeValidator

func ObtainIntRangeValidator(min int, max int) auconfigapi.ConfigValidationFunc

func ObtainIsBooleanValidator

func ObtainIsBooleanValidator() auconfigapi.ConfigValidationFunc

func ObtainIsRegexValidator

func ObtainIsRegexValidator() auconfigapi.ConfigValidationFunc

func ObtainNotEmptyValidator

func ObtainNotEmptyValidator() auconfigapi.ConfigValidationFunc

func ObtainPatternValidator

func ObtainPatternValidator(pattern string) auconfigapi.ConfigValidationFunc

func ObtainSingleCharacterValidator

func ObtainSingleCharacterValidator() auconfigapi.ConfigValidationFunc

func ObtainUintRangeValidator

func ObtainUintRangeValidator(min uint, max uint) auconfigapi.ConfigValidationFunc

func Read

func Read() error

Read should be called in your code after Setup().

func ReadYaml

func ReadYaml(filename string) error

ReadYaml is exposed for direct use in testing code, allows you to ignore environment variables.

func Set

func Set(key string, value string)

func Setup

func Setup(items []auconfigapi.ConfigItem, warnFunc auconfigapi.ConfigWarnFunc) error

Setup initializes configuration with the default values - you need to call this from your code before calling Read() and Validate().

func Validate

func Validate() error