config

package module
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2021 License: MIT Imports: 10 Imported by: 18

README

Config

PkgGoDev Mentioned in Awesome Go Build Status Go Report Card Coverage Status GitHub issues license Release

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

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

var c MyConfig
err := config.FromEnv().To(&c)

How It Works

It's just simple, pure stdlib.

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

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

  • time.Duration follows the same parsing rules as time.ParseDuration

  • *net.URL follows the same parsing rules as url.Parse

    • NOTE: *net.URL fields on the struct must be a pointer

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

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

  • Unset values remain intact or 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.

  • Any errors encountered are aggregated into a single error value

    • the entirety of the struct is always attempted
    • failed conversions (i.e. converting "x" to an int) and file i/o are the only sources of errors
      • missing values are not errors

Why you should use this

  • It's 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.
  • small:
    • only stdlib
    • < 180 LoC

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.

    • One exception is *url.URL, which is explicitly a pointer for ease of use, matching the url package conventions

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://pkg.go.dev/strconv function is called.

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

time.Duration follows the same parsing rules as https://pkg.go.dev/time#ParseDuration

*net.URL follows the same parsing rules as https://pkg.go.dev/net/url#URL.Parse NOTE: `*net.URL` fields on the struct **must** be a pointer

If chaining multiple data sources, data sets are merged.

Later values override previous values. 

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

Unset values remain intact or 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/JeremyLoy/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 (Defaults) 
package main

import (
	"fmt"
	"os"

	"github.com/JeremyLoy/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", "production://")

	// existing values on the struct are maintained if unset in the env
	c := MyConfig{
		DatabaseURL: "development://",
		Port:        1234,
	}
	config.FromEnv().To(&c)

	fmt.Println(c.DatabaseURL)
	fmt.Println(c.Port)

}

Output:

production://
1234
Example (ErrorHandling) 
package main

import (
	"fmt"
	"os"

	"github.com/JeremyLoy/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("PORT", "X")

	var c MyConfig
	err := config.FromEnv().To(&c)
	fmt.Println(err)

}

Output:

config: the following fields had errors: [port]
Example (FromFileWithOverride) 
package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/JeremyLoy/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, _ := os.CreateTemp("", "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/JeremyLoy/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://
Example (Subconfig) 
package main

import (
	"fmt"
	"os"

	"github.com/JeremyLoy/config"
)

type MySubConfig struct {
	IPWhitelist []string
}

func main() {
	os.Clearenv()
	os.Setenv("SUBCONFIG__IPWHITELIST", "0.0.0.0 1.1.1.1 2.2.2.2")

	var c MySubConfig
	config.FromEnv().Sub(&c, "SUBCONFIG")

	fmt.Println(c.IPWhitelist, len(c.IPWhitelist))

}

Output:

[0.0.0.0 1.1.1.1 2.2.2.2] 3

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

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.

func FromEnv 

func FromEnv() *Builder

FromEnv returns a new Builder, populated with environment variables

func FromOptional added in v1.5.0 

func FromOptional(file string) *Builder

FromOptional returns a new Builder, populated with the values from file if it exists.

func (*Builder) From 

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

From merges new values from file into the current config state, returning the Builder.

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) FromOptional added in v1.5.0 

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

FromOptional merges new values from file (if it exists) into the current config state, returning the Builder.

func (*Builder) Sub added in v1.4.0 

func (c *Builder) Sub(target interface{}, prefix string) error

Sub behaves the same as To, however it maps configuration to the struct starting at the given prefix.

func (*Builder) To 

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

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

  • all int, uint, float variants
  • bool, struct, string
  • time.Duration
  • \*url.URL
  • slice of any of the above, except for []struct{}

It returns an error if:

  • struct contains unsupported fields (pointers, maps, slice of structs, channels, arrays, funcs, interfaces, complex)
  • there were errors doing file i/o

It panics if:

  • target is not a struct pointer

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.