insconfig

README

Insolar configurations

Insolar configurations unify configuring for all Insolar applications: Assured Ledger, Insolar Observer, Insolar MainNet, Insolar Explorer and more.

Configurations are consolidated into a single configuration library that is a wrapper for Viper.

Configurations are used by Insolar applications as a dependency.

Insolar is extensively documented. If you need more information on what is Insolar, visit Insolar Docs.

Key features

• .yaml format of configuration files.
• No default configuration paths. A path should be explicitly set by the "--config/-c" flag. Optionally, you can override this by implementing ConfigPathGetter (look at configurator_test.go for details).
• Environment values override file values.
• Option to use only ENV, without a configuration file at all.
• Option to write the config file content to the log file at an app launch.
• Hiding sensitive data via the insconfigsecret tag.
• No default values in a configuration file. All values should be set explicitly, otherwise the library returns an error.
• No unnecessary field or parameters both in a configuration file and ENV, otherwise the library returns an error. Consider as unecessary: fields in a config struct unused in a configuration file, old or obsolete parameters in a configuration file that are not currently used, unused parameters in ENV.
• Support of custom flags, go flags and pflags.
• No overriding configutation files by flags.
• Option to generate an empty .yaml file with field descriptions.
• Automatic adding of the --config flag.
• [work in progress] Automatic of the --gen-config flag.
• No overriding app configuration on the fly.
• Support of custom Viper decode hooks.

Usage

Consider the example in ./example/example.go.

Run the example:

run ./example/example.go --config="./example/example_config.yaml"

In addition:

• Test the code snippets below by replacing the contents of func main() in example.go with them.

• Modify the snippets appropriately to include them directly into your code. Pay attention to variable and configuration field contents.

Tip: Don't forget to add github.com/insolar/insconfig to the import section.

Note: EnvPrefix value shouldn't have any delimiters: EnvPrefix: "incorrect example" has incorrect syntax, while EnvPrefix: "correctexample" has correct syntax.

No flags

If you don't use any flags and DefaultPathGetter, which adds the --config flag so you can start right away, consider this example for func main():

mconf := &Config{}	
	params := insconfig.Params{
		EnvPrefix:        "example",
		ConfigPathGetter: &insconfig.DefaultPathGetter{},
	}
	insConfigurator := insconfig.New(params)
	if err := insConfigurator.Load(mconf); err != nil {
		panic(err)
	}
	insConfigurator.ToYaml(mconf)
	fmt.Println(insConfigurator.ToYaml(mconf))

Custom flags

Custom Go flags (from example.go)

    var flag_example_1 = flag.String("flag_example_1", "example_value", "flag_example_1_desc")
    mconf := Config{}
    params := insconfig.Params{
	EnvPrefix:    "example",
	ConfigPathGetter: &insconfig.FlagPathGetter{
		GoFlags: flag.CommandLine,
	},
    }
    insConfigurator := insconfig.New(params)
    _ = insConfigurator.Load(&mconf)
    fmt.Println(*flag_example_1)
    fmt.Println(insConfigurator.ToYaml(mconf))

Custom spf13/pflags

    var flag_example_1 = pflag.String("flag_example_1", "", "flag_example_1_desc")
    mconf := Config{}
    params := insconfig.Params{
        EnvPrefix:    "example",
        ConfigPathGetter: &insconfig.PFlagPathGetter{
            PFlags: pflag.CommandLine,
        },
    }
    insConfigurator := insconfig.New(params)
    _ = insConfigurator.Load(&mconf)
    fmt.Println(flag_example_1)
    fmt.Println(insConfigurator.ToYaml(mconf))

Custom spf13/cobra flags.

Note: Cobra doesn't provide tools that manage flags parsing, so you need to add the --config flag yourself.

// To set your path from flag to insconfig you need to implement simple ConfigPathGetter interface and return path
type stringPathGetter struct {
	Path string
}
func (g *stringPathGetter) GetConfigPath() string {
	return g.Path
}
func main() {
	var configPath string
	rootCmd := &cobra.Command{
		Use: "your_command_name",
	}
	rootCmd.PersistentFlags().StringVarP(&configPath, "config", "c", "", "path to config file")
	_ = rootCmd.MarkPersistentFlagRequired("config")
	err := rootCmd.Execute()
	if err != nil {
		panic(err)
	}
	cfg := Config{}
	params := insconfig.Params{
		EnvPrefix:        "example",
		ConfigPathGetter: &stringPathGetter{Path: configPath},
		FileNotRequired:     true,
	}
	insConfigurator := insconfig.New(params)
	err = insConfigurator.Load(&cfg)
	if err != nil {
		panic(err)
	}
	println(insConfigurator.ToYaml(cfg))
}

Generating a configuration template

Tip: You can use tags to enrich a field with a comment, and it will end up in your template.

If you want to create a config file example and you have a ready config structure, consider this example:

    type Config struct {
    ... 
        Field Type `insonfig:"Commentary for this field"`
    }
    ...
    cfg := Config{
        ...
        Field: "default_value",
    }
    insconfig.NewYamlTemplaterStruct(cfg).TemplateTo(os.StdOut)

As you see, default value for a field can be provided via instance of config structure.

Generating a configuration template with hidden fields

If you have some sensitive data, you may want to hide it in a config. You can use the insconfigsecret tag to hide such data.

    type Config struct {
    ...
	    Pass string `insconfigsecret:""`
    }
    ...
    insconfig.NewYamlDumper(Config).DumpTo(os.StdOut)

Using maps in a configuration file

You can use maps in a configuration file, althought with some limitations:

• Only String type keys are allowed
• A map cannot be nested and has to be used on the first level
• Nested maps (directly or in a struct) are not allowed

Contribute!

Feel free to submit issues, fork the repository and send pull requests!

To make the process smooth for both reviewers and contributors, familiarize yourself with the following guidelines:

1. Open source contributor guide.
2. Style guide: Effective Go.
3. List of shorthands for Go code review comments.

When submitting an issue, include a complete test function that reproduces it.

Thank you for your intention to contribute to the Insolar Mainnet project. As a company developing open-source code, we highly appreciate external contributions to our project.

Contacts

If you have any additional questions, join our developers chat on Telegram.

Our social media:

License

This project is licensed under the terms of the MIT License.

Documentation

Index

• func New(params Params) insConfigurator
• type ConfigPathGetter
• type DefaultPathGetter
  • func (g *DefaultPathGetter) GetConfigPath() string
• type FlagPathGetter
  • func (g *FlagPathGetter) GetConfigPath() string
• type PFlagPathGetter
  • func (g *PFlagPathGetter) GetConfigPath() string
• type Params
• type YamlDumpable
• type YamlDumper
  • func NewYamlDumper(obj interface{}) *YamlDumper
  • func (d *YamlDumper) DumpTo(w io.Writer) error
• type YamlTemplatable
• type YamlTemplatableStruct
• type YamlTemplater
  • func NewYamlTemplater(obj interface{}) *YamlTemplater
  • func (m *YamlTemplater) TemplateTo(w io.Writer) error
• type YamlTemplaterStruct
  • func NewYamlTemplaterStruct(obj interface{}) YamlTemplaterStruct
  • func (m YamlTemplaterStruct) TemplateTo(w io.Writer) (err error)

Functions

func New

func New(params Params) insConfigurator

New creates new insConfigurator with params

Types

type ConfigPathGetter

type ConfigPathGetter interface {
	GetConfigPath() string
}

ConfigPathGetter - implement this if you don't want to use config path from --config flag

type DefaultPathGetter

type DefaultPathGetter struct {
	GoFlags *goflag.FlagSet
}

DefaultPathGetter adds "--config" flag and read path from it

func (*DefaultPathGetter) GetConfigPath

func (g *DefaultPathGetter) GetConfigPath() string

type FlagPathGetter

type FlagPathGetter struct {
	GoFlags *goflag.FlagSet
}

FlagPathGetter made for go flags compatibility Adds "--config" flag and read path from it, custom go flags should be created before and set to GoFlags

func (*FlagPathGetter) GetConfigPath

func (g *FlagPathGetter) GetConfigPath() string

type PFlagPathGetter

type PFlagPathGetter struct {
	PFlags *flag.FlagSet
}

PFlagPathGetter made for spf13/pflags compatibility. Adds "--config" flag and read path from it, custom pflags should be created before and set to PFlags

func (*PFlagPathGetter) GetConfigPath

func (g *PFlagPathGetter) GetConfigPath() string

type Params

type Params struct {
	// EnvPrefix is a prefix for environment variables
	EnvPrefix string
	// ViperHooks is custom viper decoding hooks
	ViperHooks []mapstructure.DecodeHookFunc
	// ConfigPathGetter should return config path
	ConfigPathGetter ConfigPathGetter
	// FileNotRequired - do not return error on file not found
	FileNotRequired bool
}

Params for config parsing

type YamlDumpable

type YamlDumpable interface {
	DumpTo(w io.Writer, m *YamlDumper) error
}

type YamlDumper

type YamlDumper struct {
	Obj   interface{}       // what are we marshaling right now
	Level int               // Level of recursion
	Tag   reflect.StructTag // Tag for current field
	FName string            // current field name
}

func NewYamlDumper

func NewYamlDumper(obj interface{}) *YamlDumper

func (*YamlDumper) DumpTo

func (d *YamlDumper) DumpTo(w io.Writer) error

type YamlTemplatable

type YamlTemplatable interface {
	TemplateTo(w io.Writer, m *YamlTemplater) error
}

Deprecated. Use YamlTemplatableStruct instead.

type YamlTemplatableStruct

type YamlTemplatableStruct interface {
	TemplateTo(w io.Writer, m YamlTemplaterStruct) error
}

type YamlTemplater

type YamlTemplater struct {
	Obj   interface{}       // what are we marshaling right now
	Level int               // Level of recursion
	Tag   reflect.StructTag // Tag for current field
	FName string            // current field name
}

Deprecated. Use YamlTemplaterStruct instead.

func NewYamlTemplater

func NewYamlTemplater(obj interface{}) *YamlTemplater

Deprecated. Use NewYamlTemplaterStruct instead.

func (*YamlTemplater) TemplateTo

func (m *YamlTemplater) TemplateTo(w io.Writer) error

type YamlTemplaterStruct

type YamlTemplaterStruct struct {
	Obj   interface{}       // what are we marshaling right now
	Level int               // Level of recursion
	Tag   reflect.StructTag // Tag for current field
	FName string            // current field name
	// contains filtered or unexported fields
}

func NewYamlTemplaterStruct

func NewYamlTemplaterStruct(obj interface{}) YamlTemplaterStruct

func (YamlTemplaterStruct) TemplateTo

func (m YamlTemplaterStruct) TemplateTo(w io.Writer) (err error)