flags

README

Flags library for microservice

This package provides enhanced flags utilities for microservice. Features including:

• Support more types then built-in flag library: Duration(), Slice()
• Support multiple formats of config by filename ext: YAML, JSON, TOML.
• Support reading config from consul KV store by specifying --service flag.
• Support reading encrypted GPG keyring config by specifying --secret flag.
• Support binding struct as flags by Struct()
• Support required flags with XXXRequired() series binding functions.

Example snippet

type Config struct {
    Number int `json:"number" desc:"Hint shown in --help"`
    Range struct {
        LessThan float64 `flag:"lt"`
        GreaterThan float64 `flag:"gt"`
    } `flag:"range"`
}

var (
    name     = flags.String("name", "default", "Name")
    subjects = flags.Slice("subjects", []string{"math", "chinese"}, "List of subjects separated by comma")
    config   = flags.Struct("config", Config{}, "Nested flags")
)

func main() {
    flags.Parse()

    data := Config{}
    config(&data) // Output the config flag to an object.
    fmt.Println(name(), subjects(), data)
}

The above demo accepts all below flags:

• $ ./bin --name=abc --subjects english,xxx --config.number 100
• $ ./bin --service=example

It will try to parse example.yaml or example.json or example.toml in current directory, /usr/local/etc/ or /app/.

Config encyption

Sometimes, we have private keys for the services, and demand a way to control access to the secrets. In such case, user can put their secrets to config file, and use gpg keyring to protect the configs.

Encrypt config file

1. Create gpg keyring manually, or with the helper script in mms2/devtool/gpg/gen.sh. You should then have two files: public keyring(pubring.gpg) and private keyring(secring.gpg).
2. Compose the config file in yaml, and put it to consul KV store with key etc/yourservice. yourservice is the name of your service.
3. Execute mms2/utils/flags/secret with --targetService=yourservice --lock and the pubring.gpg file. It should then encrypt the service config file.
4. To retrieve the config file, you have to specify --service=yourservice and also --secret=secring.gpg to execute your program. The config data will be automatically decrypted and be accessable through flags.

Remove encryption

1. Prepare the companion private keyring secring.gpg. The correspond pubkey should be used to encrypt the config file.
2. Execute mms2/utils/flags/secret with --targetService=yourservice --unlock and the secring.gog file.

Lost private keyrings??

Congratulation. You lose access to your config file FOREVER.

Documentation

Index

• func Bool(key string, defaultValue bool, usage string) func() bool
• func BoolRequired(key, usage string) func() bool
• func Duration(key string, defaultValue time.Duration, usage string) func() time.Duration
• func DurationRequired(key, usage string) func() time.Duration
• func FetchLocalServiceConfig(path string) (interface{}, error)
• func FetchRemoteServiceConfig(watchRemoteConfig bool) (interface{}, error)
• func File(key, defaultValue, usage string) func() ([]byte, error)
• func FileRequired(key, usage string) func() ([]byte, error)
• func Float64(key string, defaultValue float64, usage string) func() float64
• func Float64Required(key, usage string) func() float64
• func GetConsulAddress() string
• func GetRemoteWatchPath() string
• func GetServiceName() string
• func GetWatchRemoteConfig() bool
• func ImportHookFunc() mapstructure.DecodeHookFunc
• func InitFlags()
• func Int(key string, defaultValue int, usage string) func() int
• func IntRequired(key, usage string) func() int
• func ListDegradedTags(tag string) []string
• func OnRemoteChange(cb func([]byte))
• func OverrideDefaultConfigFile(configFile string)
• func Parse()
• func SetAutoloadRemote(enabled bool)
• func SetForbidUnknownKeys(forbid bool)
• func SetForbiddenKeys(keys []string)
• func Slice(key string, defaultValue []string, usage string) func() []string
• func SliceRequired(key, usage string) func() []string
• func String(key, defaultValue, usage string) func() string
• func StringMapString(key string, defaultValue map[string]string, usage string) func() map[string]string
• func StringRequired(key, usage string) func() string
• func StringToProtoEnumHookFunc() mapstructure.DecodeHookFunc
• func Struct(key string, defaultValue interface{}, usage string) func(out interface{}) error
• func UnmarshalByStruct(input interface{}, rawVal interface{}, opts ...viper.DecoderConfigOption) error
• type EnumProto
• type HasDefault
• type HasValidator
• type ImportStore

Functions

func Bool

func Bool(key string, defaultValue bool, usage string) func() bool

func BoolRequired

func BoolRequired(key, usage string) func() bool

func Duration

func Duration(key string, defaultValue time.Duration, usage string) func() time.Duration

func DurationRequired

func DurationRequired(key, usage string) func() time.Duration

func FetchLocalServiceConfig

func FetchLocalServiceConfig(path string) (interface{}, error)

func FetchRemoteServiceConfig

func FetchRemoteServiceConfig(watchRemoteConfig bool) (interface{}, error)

func File

func File(key, defaultValue, usage string) func() ([]byte, error)

func FileRequired

func FileRequired(key, usage string) func() ([]byte, error)

func Float64

func Float64(key string, defaultValue float64, usage string) func() float64

func Float64Required

func Float64Required(key, usage string) func() float64

func GetConsulAddress

func GetConsulAddress() string

func GetRemoteWatchPath

func GetRemoteWatchPath() string

func GetServiceName

func GetServiceName() string

GetServiceName returns special `service` flag always included in this library.

func GetWatchRemoteConfig

func GetWatchRemoteConfig() bool

func ImportHookFunc

func ImportHookFunc() mapstructure.DecodeHookFunc

func InitFlags

func InitFlags()

func Int

func Int(key string, defaultValue int, usage string) func() int

func IntRequired

func IntRequired(key, usage string) func() int

func ListDegradedTags

func ListDegradedTags(tag string) []string

func OnRemoteChange

func OnRemoteChange(cb func([]byte))

func OverrideDefaultConfigFile

func OverrideDefaultConfigFile(configFile string)

OverrideDefaultConfigFile . Internal use only.

func Parse

func Parse()

Parse has to called after main() before any application code.

func SetAutoloadRemote

func SetAutoloadRemote(enabled bool)

SetAutoloadRemote let user disable populating remote service config by default. User can use FetchRemoteServiceConfig to obtain the remote service config on demand.

func SetForbidUnknownKeys

func SetForbidUnknownKeys(forbid bool)

SetForbidUnknownKeys controls whether an unknown key is allowed in arguments. Usually required when cooperating with other flags library.

func SetForbiddenKeys

func SetForbiddenKeys(keys []string)

SetForbiddenKeys opts out certain keys from declaring.

func Slice

func Slice(key string, defaultValue []string, usage string) func() []string

func SliceRequired

func SliceRequired(key, usage string) func() []string

func String

func String(key, defaultValue, usage string) func() string

func StringMapString

func StringMapString(key string, defaultValue map[string]string, usage string) func() map[string]string

func StringRequired

func StringRequired(key, usage string) func() string

func StringToProtoEnumHookFunc

func StringToProtoEnumHookFunc() mapstructure.DecodeHookFunc

func Struct

func Struct(key string, defaultValue interface{}, usage string) func(out interface{}) error

func UnmarshalByStruct

func UnmarshalByStruct(input interface{}, rawVal interface{}, opts ...viper.DecoderConfigOption) error

Types

type EnumProto

type EnumProto interface {
	EnumDescriptor() ([]byte, []int)
}

type HasDefault

type HasDefault interface {
	SetDefault()
}

HasDefault indicates a flag struct which has default values.

type HasValidator

type HasValidator interface {
	Validate() error
}

type ImportStore

type ImportStore interface {
	LoadValue(path string) ([]byte, error)
}