go-config-reader

Simple configuration reader and validator that accepts a variety of sources.

How to use

1. Import the library

import (
        cf "github.com/randlabs/go-config-reader"
)

2. Create a struct that defines your configuration settings and add the required JSON tags to it.

type ConfigurationSettings struct {
        Name         string  `json:"name"`
        IntegerValue int     `json:"integerValue"`
        FloatValue   float64 `json:"floatValue"`
}

3. Define the variable that will hold your settings

settings := ConfigurationSettings{}

4. Setup the configuration load options

opts := cf.Options{
        Source: "/tmp/settings.json"",
}

5. And execute load

err := cf.Load(opts, &settings)
if err != nil {
        return err
}

Loader options

The Options struct accept several modifiers that affects the load operation:

Field	Meaning
Source	Specifies the configuration source. Optional. Used mostly for testing or templating.
EnvironmentVariable	The environment variable used to lookup for the source. If specified, the source is the value of the environment variable. For example, this code: opts.EnvironmentVariable = "MYSETTINGS" expects you define an environment variable like this: MYSETTINGS=/tmp/settings.json so the source will be: /tmp/settings.json NOTE: Source has priority over this field.
CmdLineParameter CmdLineParameterShort	Long and short command-line parameters that contains source. Set to an empty string to disable. For example, this code: s := "settings" opts.CmdLineParameter = &s expects you run your app like this: yourapp --settings /tmp/settings.json NOTE: EnvironmentVariable has priority over this field.
Callback	Use a custom loader for the configuration settings. For example: func (ctx context.Context, source string) (string, error) { dat, err := os.ReadFile(source) if err != nil { return "", err } return string(dat), nil }
Schema	Specifies an optional JSON schema to use to validate the loaded configuration. See this page for details about the schema format.
ExtendedValidator	Specifies a custom validator function. For example: func (settings interface{}) error { s := settings.(*ConfigurationSettings) if s.IntegerValue < 0 { return errors.New("invalid integer value") } s.IntegerValue *= 2 // You can also modify them at this stage return nil }
Context	Optional context.Context object to use while loading the configuration.

The source

The library contains several predefined loaders to load configuration settings from different locations. They are:

• A file path like /tmp/settings.json or in URL format file:///tmp/settings.json used to load the configuration settings from the specified file.
  
  
• An http or https URL like https://configurations.company/network/myapp/settings.json.
  
  
• An embedded data URL like data://{ "integerValue": 10, .... }. A JSON object like { "integerValue": 10, .... } will be also taken as a data URL.
  
  
• A Hashicorp Vault URL using a custom scheme: vault://server-domain?token={access-token}&path={vault-path}
  In this case, the loader will try to reach the vault-path secret located at http://server-domain using the provided access-token.
  
  By default, all the keys are read and returned as a JSON object but you can additionally add the &key={key} query parameter in order to read the specified value.
  
  NOTES:
  1. {vault-path} usually starts with /secret or /secret/data for KV engines v1 and v2 respectively.
  2. Use vaults:// to access a server using the https protocol.

Variable expansion

When data is loaded from the provided source, a macro expansion routine is executed. The following macros are processed:

• ${SRC:some-source}: The loader will attempt to load the data located at some-source and replace the macro with it. some-source must be in any of the supported source formats.
  
  
• ${ENV:some-environment-variable}: The loader will replace the macro with the content of the environment variable named some-environment-variable.

You can also embed macros inside other macros, for example:

${SRC:vault://my-vault-server.network?token=${ENV:VAULT_ACCESS_TOKEN}&path=/secret/data/mysecret}

LICENSE

See LICENSE file for details.