config

README

Config

Go Config is a pluggable dynamic config library

Most config in applications are statically configured or include complex logic to load from multiple sources. Go-config makes this easy, pluggable and mergeable. You'll never have to deal with config in the same way again.

Features

• Dynamic - load config on the fly as you need it
• Pluggable - choose which source to load from; file, envvar, consul
• Mergeable - merge and override multiple config sources
• Fallback - specify fallback values where keys don't exist
• Watch - Watch the config for changes

Getting Started

• Sources
• Formats
• Config
• Usage
• FAQ

Sources

Sources are backends from which config is loaded. The following sources for config are supported.

• configmap - read from k8s configmap
• consul - read from consul
• etcd - read from etcd v3
• envvar - read from environment variables
• file - read from file
• flag - read from flags
• grpc - read from grpc server
• memory - read from memory
• microcli - read from micro cli flags

TODO:

• vault
• git url

Formats

Encoders handle source encoding formats. The following encoding formats are supported:

• json
• yaml
• toml
• xml
• hcl

Default encoder is json with format:

{
	"path": {
		"to": {
			"key": ["foo", "bar"]
		}
	}
}

Config

Top level config is an interface. It supports multiple sources, watching and fallback values.

Interface

type Config interface {
        Close() error
        Bytes() []byte
        Get(path ...string) reader.Value
        Load(source ...source.Source) error
        Watch(path ...string) (Watcher, error)
}

Value

The config.Get method returns a reader.Value which can cast to any type with a fallback value

type Value interface {
	Bool(def bool) bool
	Int(def int) int
	String(def string) string
	Float64(def float64) float64
	Duration(def time.Duration) time.Duration
	StringSlice(def []string) []string
	StringMap(def map[string]string) map[string]string
	Scan(val interface{}) error
	Bytes() []byte
}

Usage

• Sample Config
• Load File
• Scan Value
• Cast Value
• Watch Path
• Merge Sources
• Set Source Encoder
• Add Reader Encoder

Sample Config

{
    "hosts": {
        "database": {
            "address": "10.0.0.1",
            "port": 3306
        },
        "cache": {
            "address": "10.0.0.2",
            "port": 6379
        }
    }
}

Load File

import "github.com/micro/go-config/source/file"

// Create new config
conf := config.NewConfig()

// Load file source
conf.Load(file.NewSource(
	file.WithPath("/tmp/config.json"),
))

Scan Value

type Host struct {
	Address string `json:"address"`
	Port int `json:"port"`
}

var host Host

conf.Get("hosts", "database").Scan(&host)

// 10.0.0.1 3306
fmt.Println(host.Address, host.Port)

Cast Value

// Get address. Set default to localhost as fallback
address := conf.Get("hosts", "database", "address").String("localhost")

// Get port. Set default to 3000 as fallback
port := conf.Get("hosts", "database", "port").Int(3000)

Watch Path

Watch a path for changes. When the file changes the new value will be made available.

w, err := conf.Watch("hosts", "database")
if err != nil {
	// do something
}

// wait for next value
v, err := w.Next()
if err != nil {
	// do something
}

var host Host

v.Scan(&host)

Merge Sources

Multiple sources can be loaded and merged. Merging priority is in reverse order.

conf := config.NewConfig()


conf.Load(
	// base config from env
	envvar.NewSource(),
	// override env with flags
	flag.NewSource(),
	// override flags with file
	file.NewSource(
		file.WithPath("/tmp/config.json"),
	),
)

Set Source Encoder

The default encoder is json.

e := yaml.NewEncoder()

s := consul.NewSource(
	source.WithEncoder(e),
)

Add Reader Encoder

The reader supports multiple encoders.

Add a new encoder to a reader like so:

e := yaml.NewEncoder()

r := json.NewReader(
	reader.WithEncoder(e),
)

FAQ

How is this different from Viper?

Viper and go-config are solving the same problem. Go-config provides a different interface and is part of the larger micro ecosystem of tooling.

Documentation

Overview

Package config is an interface for dynamic configuration.

Index

• type Config
  • func NewConfig(opts ...Option) Config
• type Option
  • func WithReader(r reader.Reader) Option
  • func WithSource(s source.Source) Option
• type Options
• type Watcher

Types

type Config

type Config interface {
	Close() error
	Bytes() []byte
	Get(path ...string) reader.Value
	Load(source ...source.Source) error
	Watch(path ...string) (Watcher, error)
}

Config is an interface abstraction for dynamic configuration

func NewConfig

func NewConfig(opts ...Option) Config

NewConfig returns new config

type Option

type Option func(o *Options)

func WithReader

func WithReader(r reader.Reader) Option

WithReader sets the config reader

func WithSource

func WithSource(s source.Source) Option

WithSource appends a source to list of sources

type Options

type Options struct {
	Reader reader.Reader
	Source []source.Source

	// for alternative data
	Context context.Context
}

type Watcher

type Watcher interface {
	Next() (reader.Value, error)
	Stop() error
}

Watcher is the config watcher