config

Documentation

Overview

Package config does 3 things:

1. provide an interface for component objects to get and process their own config
2. provide an interface for config providers to hook into the load mechanism
3. provide a load mechanism with sensible defaults and config lifecycle

The load mechanism defines the basic semantics and lifecycle of configuration:

1. configuration is loaded from one or more files via Load
2. the config format(s) are up to the config provider
3. top level keys map to registered object names matched via Lookup
4. a special "disabled" top level key is used to disable registered objects
5. files are loaded from paths that the app specifies in call to Load
6. more filepaths can be specified via user environment variable
7. config can be set or overridden by user environment variables
8. resulting config for each object is passed via extension point
9. objects use this to specify defaults, process, and store values
10. "config" fields of an object are assigned by lookup using the key by that field name
11. registry is reloaded

The default, preferred, and builtin configuration provider is Viper. Viper can be used directly for more control, or replaced with a custom provider.

The Settings and Initializer interfaces are the only parts needed for object compatibility in the component ecosystem. Apps can define their own config Provider, or ignore the Load mechanism entirely.

Index

• func Load(registry *objects.Registry, provider Provider, name string, paths []string) error
• type Initializer
• type Provider
• type Settings

Functions

func Load

func Load(registry *objects.Registry, provider Provider, name string, paths []string) error

Load uses a Provider to read in configuration from various files and the environment for the objects in a particular Registry. It passes Settings for each object to any object that implements the Initializer interface. Then it will lookup any struct fields with `com:"config"` and use the settings for that object to get the name of an object from the registry to assign to that field. It also disables any objects in the Registry referenced in the top-level config section called "disabled".

Types

type Initializer

type Initializer interface {
	// InitializeConfig is called on a registered object with Settings for that
	// object when configuration has been loaded.
	InitializeConfig(config Settings) error
}

Initializer is an extension point interface with a hook allowing objects to handle their configuration when configuration is loaded by the provider.

type Provider

type Provider interface {
	// Load returns Settings for named configuration loaded from provided paths.
	// Leave the file extension off of name as supported format extensions will
	// automatically be added.
	Load(name string, paths []string) (Settings, error)

	// New returns an empty Settings instance.
	New() Settings

	Settings
}

Provider is an interface for configuration providers, which includes the the interface to loaded configuration from that provider.

type Settings

type Settings interface {
	// Get returns the value associated with the key as an empty interface.
	Get(key string) interface{}

	// IsSet checks to see if the key has been set in configuration.
	IsSet(key string) bool

	// Unmarshal unmarshals the config into a Struct. Make sure that the tags on the fields of the structure are properly set.
	Unmarshal(rawVal interface{}) error

	// UnmarshalKey takes a single key and unmarshals it into a Struct.
	// BUG: Currently with Viper, UnmarshalKey will ignore environment values.
	UnmarshalKey(key string, rawVal interface{}) error

	// SetDefault sets the default value for this key.
	SetDefault(key string, value interface{})

	// Sub returns new Settings instance representing a sub tree of this instance.
	Sub(key string) Settings
}

Settings is an interface representing a collection of key-values from a configuration or subset of a configuration. 90% of the time you'll just use Unmarshal into a struct, but sometimes you'll want to grab a specific key. To encourage using structs, there are no typed getters.