distconf

distconf

distconf is a distributed configuration framework for Go.

All applications need to load configuration somehow. Configuration can be loaded in many different ways

• Environment variables
• Command line parameters
• ZooKeeper or consul

How configuration is loaded should ideally be abstracted from the need for configuration.

An additional complication is that configuration can change while an application is live. It is sometimes useful to allow applications to update their configuration without having to restart. Unfortunately, systems like zookeeper can be slow so your application also needs to atomically cache configuration, while also monitoring for changes.

Distconf does all that

• Abstract the need for configuration from the source of configuration
• Fast, atomic loading of configuration
• Monitoring of configuration updates

Usage

The correct way to use distconf is to get a configuration value once from it, then either pass that value into your application code or register a watch to update your application when the value changes. For example, for type Float call distconf.Float once, then call Get on that value while your application is live.

Normal example with for loop

    func ExampleFloat_Get_inloop() {
        ctx := context.Background()
        m := distconf.Mem{}
        if err := m.Write(ctx, "value", []byte("2.0")); err != nil {
            panic("never happens")
        }
        d := distconf.Distconf{
            Readers: []distconf.Reader{&m},
        }
        x := d.Float(ctx, "value", 1.0)
        sum := 0.0
        for i := 0 ;i < 1000; i++ {
            sum += x.Get()
        }
        fmt.Println(sum)
        // Output: 2000
    }

Getting a float value from distconf

    func ExampleDistconf_Float() {
        ctx := context.Background()
        m := distconf.Mem{}
        if err := m.Write(ctx, "value", []byte("3.2")); err != nil {
            panic("never happens")
        }
        d := distconf.Distconf{
            Readers: []distconf.Reader{&m},
        }
        x := d.Float(ctx, "value", 1.0)
        fmt.Println(x.Get())
        // Output: 3.2
    }

Getting the default value from distconf

    func ExampleDistconf_defaults() {
        ctx := context.Background()
        d := distconf.Distconf{}
        x := d.Float(ctx, "value", 1.1)
        fmt.Println(x.Get())
        // Output: 1.1
    }

Watching for updates for values

    func ExampleFloat_Watch() {
        ctx := context.Background()
        m := distconf.Mem{}
        d := distconf.Distconf{
            Readers: []distconf.Reader{&m},
        }
        x := d.Float(ctx, "value", 1.0)
        x.Watch(func(f *distconf.Float, oldValue float64) {
            fmt.Println("Change from", oldValue, "to", f.Get())
        })
        fmt.Println("first", x.Get())
        if err := m.Write(ctx, "value", []byte("2.1")); err != nil {
            panic("never happens")
        }
        fmt.Println("second", x.Get())
        // Output: first 1
        // Change from 1 to 2.1
        // second 2.1
    }

Design Rational

The primary design goals of distconf are:

• Obey best practices around lack of globals or reflection
• Have small core interfaces with very few functions
• Allow fast, atomic fetches of values, allowing them to be used in tight loops
• Allow registered updates of values as they change
• Minimal external dependencies

The core component of distconf is an interface with only one method.

    // Reader can get a []byte value for a config key
    type Reader interface {
        // Read should lookup a key inside the configuration source.  This function should
        // be thread safe, but is allowed to be slow or block.  That block will only happen
        // on application startup.  An error will skip this source and fall back to another
        // source in the chain.
        Read(ctx context.Context, key string) ([]byte, error)
    }

From this simple interface, we can derive the rest of distconf. Readers are used by Distconf to fetch configuration information. Some readers, such as zookeeper, allow you to watch for specific keys and get notifications live when they change. To support this, readers can also optionally implement the Watcher interface.

    // A Watcher config can change what it thinks a value is over time.
    type Watcher interface {
        // Watch a key for a change in value.  When the value for that key changes,
        // execute 'callback'.  It is ok to execute callback more times than needed.
        // Each call to callback will probably trigger future calls to Get().
        // Watch may be called multiple times for a single key.  Only the latest callback needs to be executed.
        // It is possible callback may itself call watch.  Be careful with locking.
        // If callback is nil, then we are trying to remove a previously registered callback.
        Watch(ctx context.Context, key string, callback func()) error
    }

Any Reader that implements Watcher will get a Watch() function call whenever a key should be watched for changes. That Watcher should then forever notify Distconf whenever that key's value changes by executing callback. When you're done with distconf, call Shutdown to deregister watches. It will try to exit early if context is terminated.

Contributing

Contributions welcome! Submit a pull request on github and make sure your code passes make lint test. For large changes, I strongly recommend creating an issue on GitHub first to confirm your change will be accepted before writing a lot of code. GitHub issues are also recommended, at your discretion, for smaller changes or questions.

License

This library is licensed under the Apache 2.0 License, forked from https://github.com/signalfx/golib under the Apache 2.0 License.