config

README

Config

Manage your application config as a typesafe struct in as little as two function calls.

package main

import (
	"context"
	"fmt"
	
	"github.com/hookactions/config"
)

type MyConfig struct {
	DatabaseUrl string `config:"DATABASE_URL"`
	FeatureFlag bool   `config:"FEATURE_FLAG"`
	Port        int // tags are optional. PORT is assumed
	...
}

var c MyConfig
config.FromEnv().To(&c)

fmt.Printf("%v\n", c)

// Supports AWS Secret Manager and Parameter store
// sm://my_value
// ssm://my_value

p, _ := config.NewAWSSecretManagerValuePreProcessor(context.Background(), true)
config.WithValuePreProcessor(p).FromEnv().To(&c)

fmt.Printf("%v\n", c)

How It Works

Its just simple, pure stdlib with optional AWS support.

• A field's type determines what strconv function is called.

• All string conversion rules are as defined in the strconv package

• If chaining multiple data sources, data sets are merged. Later values override previous values.

  config.From("dev.config").FromEnv().To(&c)
  

• Unset values remain as their native zero value

• Nested structs/subconfigs are delimited with double underscore

  • e.g. PARENT__CHILD

• Env vars map to struct fields case insensitively

  • NOTE: Also true when using struct tags.

Why you should use this

• Its the cloud-native way to manage config. See 12 Factor Apps
• Simple:
  • only 2 lines to configure.
• Composeable:
  • Merge local files and environment variables for effortless local development.

Design Philosophy

Opinionated and narrow in scope. This library is only meant to do config binding. Feel free to use it on its own, or alongside other libraries.

• Only structs at the entry point. This keeps the API surface small.

• Slices are space delimited. This matches how environment variables and commandline args are handled by the go cmd.

• No slices of structs. The extra complexity isn't warranted for such a niche usecase.

• No maps. The only feature of maps not handled by structs for this usecase is dynamic keys.

• No pointer members. If you really need one, just take the address of parts of your struct.

Documentation

Overview

Package config provides typesafe, cloud native configuration binding from environment variables or files to structs.

Configuration can be done in as little as two lines:

var c MyConfig
config.FromEnv().To(&c)

A field's type determines what https://golang.org/pkg/strconv/ function is called.

All string conversion rules are as defined in the https://golang.org/pkg/strconv/ package.

If chaining multiple data sources, data sets are merged.

Later values override previous values.

config.From("dev.config").FromEnv().To(&c)

Unset values remain as their native zero value: https://tour.golang.org/basics/12.

Nested structs/subconfigs are delimited with double underscore.

PARENT__CHILD

Env vars map to struct fields case insensitively. NOTE: Also true when using struct tags.

Example

package main

import (
	"fmt"
	"os"

	"github.com/hookactions/config"
)

type MySubConfig struct {
	IPWhitelist []string
}

type MyConfig struct {
	DatabaseURL string `config:"DATABASE_URL"`
	Port        int
	FeatureFlag bool `config:"FEATURE_FLAG"`
	SubConfig   MySubConfig
}

func main() {
	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")
	os.Setenv("PORT", "1234")
	os.Setenv("FEATURE_FLAG", "true") // also accepts t, f, 0, 1 etc. see strconv package.
	// Double underscore for sub structs. Space separation for slices.
	os.Setenv("SUBCONFIG__IPWHITELIST", "0.0.0.0 1.1.1.1 2.2.2.2")

	var c MyConfig
	config.FromEnv().To(&c)

	fmt.Println(c.DatabaseURL)
	fmt.Println(c.Port)
	fmt.Println(c.FeatureFlag)
	fmt.Println(c.SubConfig.IPWhitelist, len(c.SubConfig.IPWhitelist))

}

Output:

db://
1234
true
[0.0.0.0 1.1.1.1 2.2.2.2] 3

Example (FromFileWithOverride)

package main

import (
	"fmt"
	"io/ioutil"
	"os"
	"strings"

	"github.com/hookactions/config"
)

type MySubConfig struct {
	IPWhitelist []string
}

type MyConfig struct {
	DatabaseURL string `config:"DATABASE_URL"`
	Port        int
	FeatureFlag bool `config:"FEATURE_FLAG"`
	SubConfig   MySubConfig
}

func main() {
	tempFile, _ := ioutil.TempFile("", "temp")
	tempFile.Write([]byte(strings.Join([]string{"PORT=1234", "FEATURE_FLAG=true"}, "\n")))
	tempFile.Close()

	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")
	os.Setenv("PORT", "5678")

	var c MyConfig
	config.From(tempFile.Name()).FromEnv().To(&c)

	// db:// was only set in ENV
	fmt.Println(c.DatabaseURL)
	// 1234 was overridden by 5678
	fmt.Println(c.Port)
	// FeatureFlag was was only set in file
	fmt.Println(c.FeatureFlag)

}

Output:

db://
5678
true

Example (StructTags)

package main

import (
	"fmt"
	"os"

	"github.com/hookactions/config"
)

func main() {
	type MyConfig struct {
		// NOTE: even when using tags, lookup is still case insensitive.
		// dAtABase_urL would still work.
		DatabaseURL string `config:"DATABASE_URL"`
	}

	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")

	var c MyConfig
	config.FromEnv().To(&c)

	fmt.Println(c.DatabaseURL)

}

Output:

db://

Index

• type AWSSecretManagerValuePreProcessor
  • func NewAWSSecretManagerValuePreProcessor(ctx context.Context, decryptParameterStoreValues bool) (*AWSSecretManagerValuePreProcessor, error)
  • func (p *AWSSecretManagerValuePreProcessor) PreProcessValue(key, value string) string
• type Builder
  • func From(file string) *Builder
  • func FromEnv() *Builder
  • func WithValuePreProcessor(p ValuePreProcessor) *Builder
  • func (c *Builder) From(file string) *Builder
  • func (c *Builder) FromEnv() *Builder
  • func (c *Builder) To(target interface{})
  • func (c *Builder) WithValuePreProcessor(p ValuePreProcessor) *Builder
• type ValuePreProcessor

Examples

• Package
• Package (FromFileWithOverride)
• Package (StructTags)
• WithValuePreProcessor

Types

type AWSSecretManagerValuePreProcessor

type AWSSecretManagerValuePreProcessor struct {
	// contains filtered or unexported fields
}

AWSSecretManagerValuePreProcessor is a ValuePreProcessor for AWS. Supports Secrets Manager and Parameter Store.

func NewAWSSecretManagerValuePreProcessor

func NewAWSSecretManagerValuePreProcessor(ctx context.Context, decryptParameterStoreValues bool) (*AWSSecretManagerValuePreProcessor, error)

NewAWSSecretManagerValuePreProcessor creates a new AWSSecretManagerValuePreProcessor with the given context and whether to decrypt parameter store values or not. This will load the aws config from external.LoadDefaultAWSConfig()

func (*AWSSecretManagerValuePreProcessor) PreProcessValue

func (p *AWSSecretManagerValuePreProcessor) PreProcessValue(key, value string) string

PreProcessValue pre-processes a config key/value pair.

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder contains the current configuration state.

func From

func From(file string) *Builder

From returns a new Builder, populated with the values from file. It panics if unable to open the file.

func FromEnv

func FromEnv() *Builder

FromEnv returns a new Builder, populated with environment variables

func WithValuePreProcessor

func WithValuePreProcessor(p ValuePreProcessor) *Builder

WithValuePreProcessor creates a new builder with a ValuePreProcessor. This will be called when adding values to the builder's configMap. An example use would be retrieving values from AWS secret manager.

Example

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/hookactions/config"
)

type MyPreProcessor struct{}

func (p *MyPreProcessor) PreProcessValue(key, value string) string {
	return strings.ToUpper(value)
}

func main() {
	type MyConfig struct {
		Foo string
	}

	os.Clearenv()
	os.Setenv("FOO", "bar")

	var c MyConfig
	config.WithValuePreProcessor(&MyPreProcessor{}).FromEnv().To(&c)

	fmt.Println(c.Foo)

}

Output:

BAR

func (*Builder) From

func (c *Builder) From(file string) *Builder

From merges new values from file into the current config state, returning the Builder. It panics if unable to open the file.

func (*Builder) FromEnv

func (c *Builder) FromEnv() *Builder

FromEnv merges new values from the environment into the current config state, returning the Builder.

func (*Builder) To

func (c *Builder) To(target interface{})

To accepts a struct pointer, and populates it with the current config state. Supported fields:

• all int, uint, float variants
• bool, struct, string
• slice of any of the above, except for []struct{}

It panics under the following circumstances:

• target is not a struct pointer
• struct contains unsupported fields (pointers, maps, slice of structs, channels, arrays, funcs, interfaces, complex)

func (*Builder) WithValuePreProcessor

func (c *Builder) WithValuePreProcessor(p ValuePreProcessor) *Builder

WithValuePreProcessor adds a ValuePreProcessor to the builder. This will be called when adding values to the builder's configMap. An example use would be retrieving values from AWS secret manager.

type ValuePreProcessor

type ValuePreProcessor interface {
	// PreProcessValue pre-processes a key/value pair for the config.
	PreProcessValue(key, value string) string
}

ValuePreProcessor is an interface for pre-processing values