cfg

README

cfg: Reloadable config package for golang

Features

1. Use golang struct instead of map for config.
2. Versioned and Atomic reloadable configuration
3. Customizable decoders(json out of box)
4. Customizable config source(reloadable file source out of box)
5. Hooks in config lifecycle, and can be used to customize behavior of cfg package:
   1. PreDecoder: called before new config decoding from source. It can be used to set default value.
   2. PostDecoder: called after new config decoding from source. It can be used to validate new config.
   3. PostSwap: called after new config taked effect(implemented by atomic swap pointers). It can be used to notify that new config is reloaded.
6. Simple logger interface to log events.

How to use

import (
    validator "github.com/go-playground/validator/v10"
    "github.com/gokits/cfg"
    "github.com/gokits/cfg/source/file"
)
//...

// 1. define config struct
// 2. define validator(optional)
type Config struct {
    MaxRetry               int  `validate:"min=0,max=10"`
    LogPath                string
}

var (
    gvalidator *validator.Validate
    filesource *file.File
    meta       *cfg.ConfigMeta
)
//...

// define PostDecode hook to validate new config. New config reload will be canceled if `error != nil`.
// `oldptr` will hold pointer to current version config struct
// `c` will hold pointer to new config struct
func (c *Config) PostDecode(oldptr interface{}) error {
    return gvalidator.Struct(c)
}

//...

func main() { 
    gvalidator = validator.New()
    if filesource, err = file.NewFileSource("./tmp.json"); err != nil {
        return
    }
    defer filesource.Close()
    meta = cfg.NewConfigMeta(Config{}, filesource)
    go meta.Run()
    if err = meta.WaitSynced(); err != nil {
        return
    }
    fmt.Printf("%+v\n", meta.Get().(*Config))
}

Roadmap

1. [done] reloadable file source
2. [done] custimizable hooks
3. [todo] export config version
4. [todo] frozen package api and release v1
5. [todo] implement other config source(etcd, consul...)

Status

This package has been used in production environment running on our kubernetes clusters. It works well with configmap of kubernetes and files.

Documentation

Index

• func Final()
• func MustGet(configptr interface{}) interface{}
• func MustRegisterFile(configptr interface{}, file string, conf *RegisterConfiguration)
• func WaitSynced(configptr interface{}) error
• func WaitSyncedAll() (err error)
• type ConfigMeta
  • func NewConfigMeta(c interface{}, source Source, opts ...Option) *ConfigMeta
  • func (cm *ConfigMeta) Get() interface{}
  • func (cm *ConfigMeta) Run()
  • func (cm *ConfigMeta) Stop()
  • func (cm *ConfigMeta) WaitSynced() error
  • func (cm *ConfigMeta) WaitSynced2(ctx context.Context) error
• type Decoder
• type Option
  • func WithDecoder(d Decoder) Option
  • func WithLogger(logger logger.LeveledLogger) Option
  • func WithValidator(v *validator.Validate) Option
• type PostDecoder
• type PostSwapper
• type PreDecoder
• type RegisterConfiguration
  • func WithDefaultConfiguration() *RegisterConfiguration
  • func (c *RegisterConfiguration) WithDecoder(d Decoder) *RegisterConfiguration
  • func (c *RegisterConfiguration) WithLogger(l logger.LeveledLogger) *RegisterConfiguration
  • func (c *RegisterConfiguration) WithValidator(v *validator.Validate) *RegisterConfiguration
• type Source

Functions

func Final

func Final()

func MustGet

func MustGet(configptr interface{}) interface{}

func MustRegisterFile

func MustRegisterFile(configptr interface{}, file string, conf *RegisterConfiguration)

func WaitSynced

func WaitSynced(configptr interface{}) error

func WaitSyncedAll

func WaitSyncedAll() (err error)

Types

type ConfigMeta

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

func NewConfigMeta

func NewConfigMeta(c interface{}, source Source, opts ...Option) *ConfigMeta

func (*ConfigMeta) Get

func (cm *ConfigMeta) Get() interface{}

func (*ConfigMeta) Run

func (cm *ConfigMeta) Run()

func (*ConfigMeta) Stop

func (cm *ConfigMeta) Stop()

func (*ConfigMeta) WaitSynced

func (cm *ConfigMeta) WaitSynced() error

func (*ConfigMeta) WaitSynced2

func (cm *ConfigMeta) WaitSynced2(ctx context.Context) error

type Decoder

type Decoder interface {
	Unmarshal(data []byte, v interface{}) error
}

type Option

type Option func(cm *ConfigMeta)

func WithDecoder

func WithDecoder(d Decoder) Option

func WithLogger

func WithLogger(logger logger.LeveledLogger) Option

func WithValidator

func WithValidator(v *validator.Validate) Option

type PostDecoder

type PostDecoder interface {
	PostDecode(oldptr interface{}) error
}

type PostSwapper

type PostSwapper interface {
	PostSwap(oldptr interface{})
}

type PreDecoder

type PreDecoder interface {
	PreDecode(oldptr interface{}) error
}

type RegisterConfiguration

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

func WithDefaultConfiguration

func WithDefaultConfiguration() *RegisterConfiguration

func (*RegisterConfiguration) WithDecoder

func (c *RegisterConfiguration) WithDecoder(d Decoder) *RegisterConfiguration

func (*RegisterConfiguration) WithLogger

func (c *RegisterConfiguration) WithLogger(l logger.LeveledLogger) *RegisterConfiguration

func (*RegisterConfiguration) WithValidator

func (c *RegisterConfiguration) WithValidator(v *validator.Validate) *RegisterConfiguration

type Source

type Source interface {
	Next(ctx context.Context, oldversion int64) (content []byte, version int64, ok bool)
	Close()
}