uconfig

README

uConfig

Lightweight, zero-dependency, and extendable configuration management.

uConfig is extremely light and extendable configuration management library with zero dependencies. Every aspect of configuration is provided through a plugin, which means you can have any combination of flags, environment variables, defaults, Kubernetes Downward API, and what you want, through plugins.

uConfig takes the config schema as a struct decorated with tags, nesting is supported.

Supports all basic types, time.Duration, time.Time, and you any other type through encoding.TextUnmarshaler interface. See the flat view package for details.

Example Configuration:

package database
// Config holds the database configurations.
type Config struct {
  Address  string `default:"localhost" env:"DATABASE_HOST"`
  Port     string `default:"28015" env:"DATABASE_SERVICE_PORT"`
  Database string `default:"my-project"`
}

package redis
// Config describes the requirement for redis client.
type Config struct {
  Address  string `default:"redis-master" env:"REDIS_HOST"`
  Port     string `default:"6379" env:"REDIS_SERVICE_PORT"`
  Password string `default:""`
  DB       int    `default:"0"`
}

package main
// Config is our distribution configs as required for services and clients.
type Config struct {

  Redis   redis.Config
  Database database.Config
}

The following example uses uconfig.Classic to create a uConfig manager which processes defaults, optionally any config files, environment variables, and flags; in that order. In this example, we're using a single YAML config file, but you can specify multiple files (each with its own unmarshaller) in the uconfig.Files map if required.

# path/to/config.yaml
# YAML unmarshaller doesn't appear to handle flattened embedded structs,
# so 'version' needs to sit under 'anon' to map correctly
anon:
  version: '0.2'
gohard: true
redis:
  host: redis-host
  port: 6379
rethink:
  db: base
  host:
    address: rethink-cluster
    port: '28015'

// main.go
package main

import (
  "os"

  "gopkg.in/yaml.v2"

  "github.com/anggiaj/uconfig"
)

type Anon struct {
  Version string `default:"0.0.1" env:"APP_VERSION"`
}

type Host struct {
  Address string `default:"localhost" env:"RETHINKDB_HOST"`
  Port    string `default:"28015" env:"RETHINKDB_PORT"`
}

type RethinkConfig struct {
  Host Host
  Db   string `default:"my-project"`
}

type Redis struct {
  Host string `default:"redis-master" env:"REDIS_HOST"`
  Port int    `default:"6379" env:"REDIS_SERVICE_PORT"`
}

type YourConfig struct {
  Anon
  GoHard  bool
  Redis   Redis
  Rethink RethinkConfig
}

func main() {

  conf := &YourConfig{}

  // Simply
  c, err := uconfig.Classic(conf, uconfig.Files{
    "path/to/config.yaml": yaml.Unmarshal,
  })
  if err != nil {
    c.Usage()
    os.Exit(1)
  }
  // Use your config here as you please.
}

File Plugin

File plugin is a walker plugin that loads configuration files of different formats by way of accepting an Unmarshaler function that follows the standard unmarshal function of type func(src []byte, v interface{}) error; this allows you to use encoding/json and other encoders that follow the same interface.

Following is some common unmarshalers that follow the standard unmarshaler function:

• JSON: encoding/json
• TOML: github.com/BurntSushi/toml
• YAML: gopkg.in/yaml.v2
  • Note: YAML unmarshaller doesn't appear to handle embedded structs as cleanly as some unmarshallers; you may need to nest the embedded struct's options in your YAML file (see version in the example below)

Tests

For tests, you may consider the Must function to set the defaults, like so

package something 

import (
  "testing"

  "github.com/anggiaj/uconfig"
  "github.com/anggiaj/uconfig/defaults"
)

func TestSomething(t *testing.T) error {

  conf := &YourConfigStruct{}

  // It will panic on error
  uconfig.Must(conf, defaults.New())

  // Use your conf as you please.
}

See the Classic source for how to compose plugins.
For more details, see the godoc.

Extending uConfig:

uConfig provides a plugin mechanism for adding new sources of configuration. There are two kind of plugins, Walkers and Visitors.

Walkers

Walkers are used for configuration plugins that take the whole config struct and unmarshal the underlying content into the config struct. Plugins that load the configuration from files are good candidates for this.

// Walker is the interface for plugins that take the whole config, like file loaders.
type Walker interface {
  Plugin

  Walk(interface{}) error
}

Visitors

Visitors get a flat view of the configuration struct, which is a flat view of the structs regardless of nesting level, for more details see the flat package documentation.

Plugins that load the configurations from flat structures (e.g flags, environment variables, default tags) are good candidts for this type of plugin.

// Visitor is the interface for plugins that require a flat view of the config, like flags, env vars
type Visitor interface {
  Plugin

  Visit(flat.Fields) error
}

Documentation

Overview

Package uconfig provides advanced command line flags supporting defaults, env vars, and config structs.

Index

• func Must(conf interface{}, plugins ...Plugin)
• type Config
  • func Classic(conf interface{}, files Files) (Config, error)
  • func New(conf interface{}, plugins ...Plugin) (Config, error)
• type Files
• type Plugin
• type Visitor
• type Walker

Functions

func Must

func Must(conf interface{}, plugins ...Plugin)

Must is like New but also calls Parse and panics instead of returning errors. This is useful in tests.

Types

type Config

type Config interface {
	// Visitor adds a visitor plugin, Config invokes the plugins Visit method
	// right away with a flat view of the underlying config struct.
	Visitor(Visitor) error
	// Walker adds a walker plugin, Config invokes the plugins Walk method
	// right away with the underlying config struct.
	Walker(Walker) error

	// Must be called after Visitor and Walkers are added.
	// Parse will call the parse method of all the added plugins in the order
	// that the plugins were registered, it will return early as soon as any
	// plugin fails.
	Parse() error

	// Usage provides a simple usage message based on the meta data registered
	// by the plugins.
	Usage()
}

Config is the config manager.

func Classic

func Classic(conf interface{}, files Files) (Config, error)

Classic creates a uconfig manager with defaults,environment variables, and flags (in that order) and optionally file loaders based on the provided Files map and parses them right away.

func New

func New(conf interface{}, plugins ...Plugin) (Config, error)

New returns a new Config. The conf must be a pointer to a struct.

type Files

type Files map[string]file.Unmarshal

Files represents a set of file paths and the appropriate unmarshal function for the given file.

type Plugin

type Plugin interface {
	Parse() error
}

Plugin is the common interface for all plugins.

type Visitor

type Visitor interface {
	Plugin

	Visit(flat.Fields) error
}

Visitor is the interface for plugins that require a flat view of the config, like flags, env vars

type Walker

type Walker interface {
	Plugin

	Walk(interface{}) error
}

Walker is the interface for plugins that take the whole config, like file loaders.