gofigure

README

GoFigure

GoFigure is a small utility library for reading configuration files. It's usefuly especially if you want to load many files recursively (think /etc/apache2/mods-enabled/*.conf on Ubuntu).

It can support multiple formats, as long as you take a file and unmarshal it into a struct containing your configurations.

Right now the only implemented formats are YAML and JSON files, but feel free to add more :)

Example usage:

import (
	"fmt"
	"github.com/EverythingMe/gofigure"
	"github.com/EverythingMe/gofigure/yaml"
)

// this is our configuration container
var conf = &struct {
	Redis struct {
		Server  string
		Monitor int
		Timeout int
	}
}{}

func main() {
	
	//if we set some default, the loader will override it
	conf.Redis.Server = "localhost:6377"

	// init a loader with a YAML decoder in strict mode
	loader := gofigure.NewLoader(yaml.Decoder{}, true)

	// run recursively on some directory
	err := loader.LoadRecursive(conf, "/etc/myservice/conf.d")
	if err != nil {
		panic(err)
	}

	fmt.Println(conf.Redis.Server)
	//Output: localhost:6379
}

Automatic -conf and -confdir flags

GoFigure can automatically add the optional -conf and -confdir flags to your program's command line flags, and then automatically read config files specified by them.

To do that, simply add an import to "github.com/EverythingMe/gofigure/autoflag".

You can then use autoflag.Load to load either a single file or all files in the directory specified by these flags.

Modifying the above example to do this:

import (
    // ... other imports ... 
    
	"github.com/EverythingMe/gofigure"
    "github.com/EverythingMe/gofigure/autoflag"
)

func main() {
	
	// in this example we also use the default loader which loads yaml files,
    // but any loader can work here
    err := autoflag.Load(gofigure.DefaultLoader, &conf)
    if err != nil {
		panic(err)
	}
    
}

Reloading configurations on the fly

GoFigure provides a primitive utility for waiting on config reloads. Right now the only implemented method is to send a SIGHUP to the process, and have the process using GoFigure use a ReloadMonitor, with a Reloader that gets called when that signal is sent.

We do not deal with the actual loading, as each program has its own sensitivites to what parts can be reconfigured in runtime and which can't.

Example:

import (
    // ... other imports ... 
    
	"github.com/EverythingMe/gofigure"
    "github.com/EverythingMe/gofigure/autoflag"
)


// loadConfigs is used both to initially load the configs, and to refresh them
func loadConfigs() {
	if err := autoflag.Load(gofigure.DefaultLoader, &conf); err != nil {
        log.Println(err)
    }
}


func main() {
	
	loadConfigs()
    
    // Create a SignalMonitor that calls a reloader when SIGHUP is sent to our process
    m := gofigure.NewSignalMonitor()
    
    // make the monitor wait for siguhup and call configReload when it needs to
	m.Monitor(gofigure.ReloadFunc(loadConfigs))
    
}

Documentation

Overview

GoFigure is a small utility library for reading configuration files. It's usefuly especially if you want to load many files recursively (think /etc/apache2/mods-enabled/*.conf).

It can support multiple formats, as long as you take a file and unmarshal it into a struct containing your configurations. Right now the only implemented formats are YAML and JSON files, but feel free to add more :)

Index

• Variables
• type Decoder
• type Loader
  • func NewLoader(d Decoder, strict bool) *Loader
  • func (l Loader) LoadFile(config interface{}, path string) error
  • func (l Loader) LoadRecursive(config interface{}, paths ...string) error
• type ReloadFunc
  • func (f ReloadFunc) Reload()
• type ReloadMonitor
• type Reloader
• type SignalMonitor
  • func NewSignalMonitor() *SignalMonitor
  • func (m *SignalMonitor) Monitor(r Reloader)
  • func (m *SignalMonitor) Stop()

Examples

• Loader

Variables

var DefaultLoader = NewLoader(yaml.Decoder{}, true)

DefaultDecoder is a yaml based decoder that can be used for convenience

Types

type Decoder

type Decoder interface {

	// Decode reads data from the io stream, and unmarshals it to the config struct.
	Decode(r io.Reader, config interface{}) error

	// CanDecode should return true if a file is decode-able by the decoder,
	// based on extension or similar mechanisms
	CanDecode(path string) bool
}

Decoder is the interface for config decoders (right now we've just implemented a YAML one)

type Loader

type Loader struct {

	// StrictMode determines whether the loader will completely fail on any IO or decoding error,
	// or whether it will continue traversing all files even if one of them is invalid.
	StrictMode bool
	// contains filtered or unexported fields
}

Loader traverses directories recursively and lets the decoder decode relevant files.

It can also explicitly decode single files

Example

// create our configuration container
var conf = &struct {
	Redis struct {
		Server  string
		Monitor int
		Timeout int
	}
}{}

//if we set some default, the loader will override it
conf.Redis.Server = "localhost:6377"

// init a loader with a YAML decoder in strict mode
loader := NewLoader(yaml.Decoder{}, true)

// run recursively on the testdata directory
err := loader.LoadRecursive(conf, "./testdata")
if err != nil {
	panic(err)
}

fmt.Println(conf.Redis.Server)

Output:

localhost:6379

func NewLoader

func NewLoader(d Decoder, strict bool) *Loader

NewLoader creates and returns a new Loader wrapping a decoder, using strict mode if specified

func (Loader) LoadFile

func (l Loader) LoadFile(config interface{}, path string) error

LoadFile takes a pointer to a struct containing configurations, and a path to a file, and uses the decoder to read the file's contents into the struct. It returns an error if the file could not be opened or properly decoded

func (Loader) LoadRecursive

func (l Loader) LoadRecursive(config interface{}, paths ...string) error

LoadRecursive takes a pointer to a struct containing configurations, and a series of paths. It then traverses the paths recursively in their respective order, and lets the decoder decode every relevant file.

type ReloadFunc

type ReloadFunc func()

ReloadFunc can be used to make a simple func conform to the Reloader interface

func (ReloadFunc) Reload

func (f ReloadFunc) Reload()

type ReloadMonitor

type ReloadMonitor interface {
	Watch(Reloader)
	Stop()
}

ReloadMonitor is an interface for waiting for external notifications that we need to reload our configs. The only implementation right now is a SIGHUP listener

type Reloader

type Reloader interface {
	Reload()
}

Reloader is an interface to be implemented by the calling program, that gets called when we need to reload our configs

type SignalMonitor

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

SignalMonitor is a monitor that waits for SIGHUP and calls its Reloader

func NewSignalMonitor

func NewSignalMonitor() *SignalMonitor

NewSignalMonitor creates a new signal monitor

func (*SignalMonitor) Monitor

func (m *SignalMonitor) Monitor(r Reloader)

Monitor waits for SIGHUP and calls the reloader's Reload method

func (*SignalMonitor) Stop

func (m *SignalMonitor) Stop()

Stop stops the signal monitor