config

Documentation

Overview

Package config handles the configuration of a program. The configuration contains the set of initial parameter settings that are read at runtime by the program.

This package allows plugging a fully-fledged configuration system into an application, taking care of the boilerplate code, common settings, configuration loading, and validation.

Different configuration sources can be used during development, debugging, testing, or deployment. The configuration can be loaded from a local file, environment variables, or a remote configuration provider (e.g., Consul, etcd, etcd3, Firestore, NATS).

This is a Viper-based implementation of the configuration model described in the following article:

• Nicola Asuni, 2014-09-13, "Software Configuration", https://technick.net/guides/software/software_configuration/

Configuration Loading Strategy:

To achieve maximum flexibility, the different configuration entry points are coordinated in the following sequence (1 has the lowest priority and 5 has the highest):

1. In the "myprog" program, the configuration parameters are defined as a data structure that can be easily mapped to and from a JSON object (or any other format supported by Viper like TOML, YAML, and HCL). Each structure parameter is annotated with the "mapstructure" and "validate" tags to define the name mapping and the validation rules. The parameters are initialized with constant default values.

2. The program attempts to load the local "config.json" configuration file, and as soon as one is found, it overwrites the default values previously set.

   The configuration file is searched in the following ordered directories based on the Linux Filesystem Hierarchy Standard (FHS):

   - ./

   - ~/.myprog/

   - /etc/myprog/

3. The program attempts to load the environmental variables that define the remote configuration system. If found, it overwrites the corresponding configuration parameters:

   - [ENVIRONMENT VARIABLE NAME] → [CONFIGURATION PARAMETER NAME]

   - MYPROG_REMOTECONFIGPROVIDER → remoteConfigProvider

   - MYPROG_REMOTECONFIGENDPOINT → remoteConfigEndpoint

   - MYPROG_REMOTECONFIGPATH → remoteConfigPath

   - MYPROG_REMOTECONFIGSECRETKEYRING → remoteConfigSecretKeyring

   - MYPROG_REMOTECONFIGDATA → remoteConfigData

4. If the "remoteConfigProvider" parameter is not empty, the program attempts to load the configuration data from the specified source. This can be any remote source supported by the Viper library (e.g., Consul, etcd, etcd3, Firestore, NATS). The configuration source can also be the "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".

5. Any specified command-line argument overwrites the corresponding configuration parameter.

6. The configuration parameters are validated via the Validate() function.

Example:

• An implementation example of this configuration package can be found in examples/service/internal/cli/config.go Note that the "log", "shutdown_timeout", and "remoteConfig" parameters are defined in this package as they are common to all programs.

• The configuration file format of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.schema.json

• The default configuration file of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.json

Index

• func Load(cmdName, configDir, envPrefix string, cfg Configuration) error
• type BaseConfig
• type Configuration
• type LogConfig
• type Viper

Functions

func Load

func Load(cmdName, configDir, envPrefix string, cfg Configuration) error

Load populates the configuration parameters.

Types

type BaseConfig

type BaseConfig struct {
	// Log configuration.
	Log LogConfig `mapstructure:"log" validate:"required"`

	// ShutdownTimeout is the time in seconds to wait for graceful shutdown.
	ShutdownTimeout int64 `mapstructure:"shutdown_timeout" validate:"omitempty,min=1,max=3600"`
}

BaseConfig contains the default configuration options to be used in the application config struct.

type Configuration

type Configuration interface {
	SetDefaults(v Viper)
	Validate() error
}

Configuration is the interface we need the application config struct to implement.

type LogConfig

type LogConfig struct {
	// Level is the standard syslog level: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG.
	Level string `mapstructure:"level" validate:"required,oneof=EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFO DEBUG"`

	// Format is the log output format: CONSOLE, JSON.
	Format string `mapstructure:"format" validate:"required,oneof=CONSOLE JSON"`

	// Network is the optional network protocol used to send logs via syslog: udp, tcp.
	Network string `mapstructure:"network" validate:"omitempty,oneof=udp tcp"`

	// Address is the optional remote syslog network address: (ip:port) or just (:port).
	Address string `mapstructure:"address" validate:"omitempty,hostname_port"`
}

LogConfig contains the configuration for the application logger.

type Viper

type Viper interface {
	AddConfigPath(in string)
	AddRemoteProvider(provider, endpoint, path string) error
	AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error
	AllKeys() []string
	AutomaticEnv()
	BindEnv(input ...string) error
	BindPFlag(key string, flag *pflag.Flag) error
	Get(key string) any
	ReadConfig(in io.Reader) error
	ReadInConfig() error
	ReadRemoteConfig() error
	SetConfigName(in string)
	SetConfigType(in string)
	SetDefault(key string, value any)
	SetEnvPrefix(in string)
	Unmarshal(rawVal any, opts ...viper.DecoderConfigOption) error
}

Viper is the local interface to the actual viper to allow for mocking.