config

README

Config

Provides a high level pluggable abstraction for dynamic configuration.

Interface

There's a need for dynamic configuration with namespacing, deltas for rollback, watches for changes and an audit log. At a low level we may care about server addresses changing, routing information, etc. At a high level there may be a need to control business level logic; External API Urls, Pricing information, etc.

// Config is the top level config which aggregates a
// number of sources and provides a single merged
// interface.
type Config interface {
	// Config values
	Values
	// Config options
	Options() Options
	// Render unusable
	Close() error
	// String name of config
	String() string
}

// Values loaded within the config
type Values interface {
	// The path could be a nested structure so
	// make it a composable.
	// Returns internal cached value
	Get(path ...string) Value
	// Sets internal cached value
	Set(val interface{}, path ...string)
	// Deletes internal cached value
	Del(path ...string)
	// Returns vals as bytes
	Bytes() []byte
}

// Represent a value retrieved from the values loaded
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
}

func NewConfig(opts ...Option) Config {
	return newOS(opts...)
}

Supported Backends

• Config service
• Consul
• File

Usage

Config provides a way to use configuration that's dynamically loaded from a variety of backends and subscribe to changes. It also allows the ability to set default values where config might be missing.

	// Create a config instance
	config := config.NewConfig(
		// Poll every minute for changes
		config.PollInterval(time.Minute),
		// Use file as a config source
		// Multiple sources can be specified
		config.WithSource(file.NewSource(config.SourceName(configFile))),
	)

	defer config.Close()

	// Get config at path as string
	// Sets value 'default' if it does not exist
	val := config.Get("path", "to", "key").String("default")


	// Scan into some type
	var ival map[string]interface{}
	if err := config.Get("path", "to", "key").Scan(&ival); err != nil {
		fmt.Println(err)
		return
	}

	// Watch for changes. Optionally specify path to watch.
	w, err := c.Watch("path", "to", "key")
	if err != nil {
		fmt.Println(err)
		return
	}

	for {
		// Block waiting for changes from watcher.
		v, err := w.Next()
		if err != nil {
			fmt.Println(err)
			return
		}
		fmt.Println("Received value for key:", v.String("default"))
	}

Config Format

The config format expected for backend sources by default is JSON. This is handled by the Reader interface. Multiple sources will be read and merged down based on the order they were configured in options.

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

Documentation

Overview

Package config is an interface for dynamic configuration.

Index

• Variables
• func NewContext(ctx context.Context, c Config) context.Context
• type ChangeSet
• type Config
  • func FromContext(ctx context.Context) (Config, bool)
  • func NewConfig(opts ...Option) Config
• type Option
  • func PollInterval(i time.Duration) Option
  • func WithClient(c client.Client) Option
  • func WithReader(r Reader) Option
  • func WithSource(s Source) Option
• type Options
• type Reader
  • func NewReader() Reader
• type Source
  • func NewSource(opts ...SourceOption) Source
• type SourceOption
  • func SourceClient(c client.Client) SourceOption
  • func SourceHosts(hosts ...string) SourceOption
  • func SourceName(n string) SourceOption
• type SourceOptions
• type SourceWatcher
• type Value
• type Values
• type Watcher

Variables

var (
	DefaultPollInterval = time.Second * 30
	DefaultSourceName   = "MICRO:CONFIG"
)

Functions

func NewContext

func NewContext(ctx context.Context, c Config) context.Context

Types

type ChangeSet

type ChangeSet struct {
	// The time at which the last change occured
	Timestamp time.Time
	// The raw data set for the change
	Data []byte
	// Hash of the source data
	Checksum string
	// The source of this change; file, consul, etcd
	Source string
}

ChangeSet represents a set an actual source

type Config

type Config interface {
	// Config values
	Values
	// Config options
	Options() Options
	// Watch for changes
	Watch(path ...string) (Watcher, error)
	// Render config unusable
	Close() error
	// String name of config
	String() string
}

Config is the top level config which aggregates a number of sources and provides a single merged interface.

func FromContext

func FromContext(ctx context.Context) (Config, bool)

func NewConfig

func NewConfig(opts ...Option) Config

type Option

type Option func(o *Options)

func PollInterval

func PollInterval(i time.Duration) Option

PollInterval is the time interval at which the sources are polled to retrieve config.

func WithClient

func WithClient(c client.Client) Option

func WithReader

func WithReader(r Reader) Option

WithReader is the reader used by config to parse ChangeSets, merge them and provide values. We're not as elegant here in terms of encoding.

func WithSource

func WithSource(s Source) Option

WithSource appends a source to our list of sources. This forms a hierarchy whereby all the configs are merged down with the last specified as favoured.

type Options

type Options struct {
	PollInterval time.Duration
	Reader       Reader
	Sources      []Source
	Client       client.Client
}

type Reader

type Reader interface {
	// Parse ChangeSets
	Parse(...*ChangeSet) (*ChangeSet, error)
	// As values
	Values(*ChangeSet) (Values, error)
	// Name of parser; json
	String() string
}

Reader takes a ChangeSet from a source and returns a single merged ChangeSet e.g reads ChangeSet as JSON and can merge down

func NewReader

func NewReader() Reader

New json reader

type Source

type Source interface {
	// Loads ChangeSet from the source
	Read() (*ChangeSet, error)
	// Watch for source changes
	// Returns the entire changeset
	Watch() (SourceWatcher, error)
	// Name of source
	String() string
}

Source is the source from which config is loaded. This may be a file, a url, consul, etc.

func NewSource

func NewSource(opts ...SourceOption) Source

type SourceOption

type SourceOption func(o *SourceOptions)

func SourceClient

func SourceClient(c client.Client) SourceOption

func SourceHosts

func SourceHosts(hosts ...string) SourceOption

func SourceName

func SourceName(n string) SourceOption

SourceName is an option to provide name of a file, a url, key within etcd, consul, zookeeper, etc.

type SourceOptions

type SourceOptions struct {
	// Name, Url, etc
	Name string

	// Client
	Client client.Client
	Hosts  []string

	// Extra Options
	Context context.Context
}

type SourceWatcher

type SourceWatcher interface {
	Next() (*ChangeSet, error)
	Stop() error
}

SourceWatcher allows you to watch a source for changes Next is a blocking call which returns the next ChangeSet update. Stop Renders the watcher unusable.

type 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
}

Represent a value retrieved from the values loaded

type Values

type Values interface {
	// The path could be a nested structure so
	// make it a composable.
	// Returns internal cached value
	Get(path ...string) Value
	// Sets internal cached value
	Set(val interface{}, path ...string)
	// Deletes internal cached value
	Del(path ...string)
	// Returns vals as bytes
	Bytes() []byte
}

Values loaded within the config

type Watcher

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