config

Documentation

Overview

Package config provides functionality for working with configuration files and command line arguments to a Granitic application.

Grantic uses JSON files to store component definitions (declarations of, and relationships between, components to run in the IoC container) and configuration (variables used by IoC components that may vary between environments and settings for Grantic's built-in facilities). A defintion of the use and syntax of these files are outside of the scope of a GoDoc page, but are described in detail at http://granitic.io/1.0/ref/components and http://granitic.io/1.0/ref/config

This package defines functionality for loading a JSON file (from a filesystem or via HTTP) and merging multiple files into a single view. This is a key concept in Granitic.

Given a folder of configuration files called conf:

conf/x.json
conf/sub/a.json
conf/sub/b.json

starting a Grantic application with:

-c http://example.com/base.json,conf,http://example.com/myinstance.json

The following will take place. Firstly the files would be expanded into a flat list of paths/URIs

http://example.com/base.json
conf/sub/a.json
conf/sub/b.json
conf/x.json
http://example.com/myinstance.json

The the files will be merged together from left, using the the first file as a base. In this example, http://example.com/base.json and conf/sub/a.json will be merged together, then result of that merge will be merged with conf/sub/b.json and so on.

For named fields (in a JSON object/map), the process of merging is fairly obvious. When merging files A and B, a field that is defined in both files will have the value of the field used in file B in the merged output. For example,

a.json

{
	"database": {
		"host": "localhost",
		"port": 3306,
		"flags": ["a", "b", "c"]
	}
}

and

b.json

{
	"database": {
		"host": "remotehost",
		"flags": ["d"]
	}
}

woud merge to:

{
	"database": {
		"host": "remotehost",
		"port": 3306,
		"flags": ["d"]
	}
}

The merging of configuration files occurs exactly above, but when component definition files are merged, arrays are joined, not overwritten. For example:

{ "methods": ["GET"] }

merged with;

{ "methods": ["POST"] }

would result in:

{ "methods": ["GET", "POST"] }

Another core concept used by the types in this package is a config path. This is the absolute path to field in the eventual merged configuration file with a dot-delimited notation. E.g "database.host".

Index

• Constants
• func ExpandToFilesAndURLs(paths []string) ([]string, error)
• func FileListFromPath(path string) ([]string, error)
• func FindConfigFilesInDir(dirPath string) ([]string, error)
• func GraniticHome() string
• func JsonType(value interface{}) int
• type ConfigAccessor
  • func (c *ConfigAccessor) Array(path string) ([]interface{}, error)
  • func (c *ConfigAccessor) BoolVal(path string) (bool, error)
  • func (c *ConfigAccessor) Float64Val(path string) (float64, error)
  • func (c *ConfigAccessor) Flush()
  • func (c *ConfigAccessor) IntVal(path string) (int, error)
  • func (c *ConfigAccessor) ObjectVal(path string) (map[string]interface{}, error)
  • func (c *ConfigAccessor) PathExists(path string) bool
  • func (ca *ConfigAccessor) Populate(path string, target interface{}) error
  • func (ca *ConfigAccessor) SetField(fieldName string, path string, target interface{}) error
  • func (c *ConfigAccessor) StringVal(path string) (string, error)
  • func (c *ConfigAccessor) Value(path string) interface{}
• type ContentParser
• type InitialSettings
  • func InitialSettingsFromEnvironment() *InitialSettings
• type JsonContentParser
  • func (jcp *JsonContentParser) ContentTypes() []string
  • func (jcp *JsonContentParser) Extensions() []string
  • func (jcp *JsonContentParser) ParseInto(data []byte, target interface{}) error
• type JsonMerger
  • func NewJsonMergerWithDirectLogging(l logging.Logger, cp ContentParser) *JsonMerger
  • func NewJsonMergerWithManagedLogging(flm *logging.ComponentLoggerManager, cp ContentParser) *JsonMerger
  • func (jm *JsonMerger) LoadAndMergeConfig(files []string) (map[string]interface{}, error)
  • func (jm *JsonMerger) LoadAndMergeConfigWithBase(config map[string]interface{}, files []string) (map[string]interface{}, error)
  • func (jm *JsonMerger) RegisterContentParser(cp ContentParser)

Constants

const (
	Unset       = -2
	JsonUnknown = -1
	JsonString  = 1
	JsonArray   = 2
	JsonMap     = 3
	JsonBool    = 4
)

Used by code that needs to know what type of JSON data structure resides at a particular path before operating on it.

const JsonPathSeparator string = "."

The character used to delimit paths to config values.

Functions

func ExpandToFilesAndURLs

func ExpandToFilesAndURLs(paths []string) ([]string, error)

ExpandToFilesAndURLs takes a slice that may be a mixture of URLs, file paths and directory paths and returns a list of URLs and file paths, recursively expanding any non-empty directories into a list of files. Returns an error if there is a problem traversing directories of if any of the supplied file paths does not exist.

func FileListFromPath

func FileListFromPath(path string) ([]string, error)

FileListFromPath takes a string that could represent a path to a directory or a path to a file and returns a list of file paths. If the path is to directory, any files in that directory are included in the result. Any sub-directories are recursively entered.

func FindConfigFilesInDir

func FindConfigFilesInDir(dirPath string) ([]string, error)

FindConfigFilesInDir finds all files with a .json extension in the supplied directory path, recursively checking sub-directories. Note that each directory's contents are examined and added to the list of files lexicographically, so any files in a sub-directory 'b' would appear in the resulting list of files before 'c.json'

func GraniticHome

func GraniticHome() string

Returns the value of the OS environment variable GRANITIC_HOME. This is expected to be the path (without a trailing /) where Grantic has been installed (e.g. /home/youruser/go/src/github.com/graniticio/granitic). This is required so that configuration files for built-in facilities can be loaded from the resource sub-directory of the Granitic installation.

func JsonType

func JsonType(value interface{}) int

Determines the apparent JSON type of the supplied Go interface.

Types

type ConfigAccessor

type ConfigAccessor struct {
	// The merged JSON configuration in object form.
	JsonData map[string]interface{}

	// Logger used by Granitic framework components. Automatically injected.
	FrameworkLogger logging.Logger
}

A ConfigAccessor provides access to a merged view of configuration files during the initialisation and configuration of the Granitic IoC container.

func (*ConfigAccessor) Array

func (c *ConfigAccessor) Array(path string) ([]interface{}, error)

Array returns the value of an array of JSON obects at the supplied path. Caution should be used when calling this method as behaviour is undefined for JSON arrays of JSON types other than object.

func (*ConfigAccessor) BoolVal

func (c *ConfigAccessor) BoolVal(path string) (bool, error)

BoolVal returns the bool value of the JSON bool at the supplied path. An error will be returned if the value is not a JSON bool. Note this method only suports the JSON definition of bools (true, false) not the Go definition (true, false, 1, 0 etc).

func (*ConfigAccessor) Float64Val

func (c *ConfigAccessor) Float64Val(path string) (float64, error)

IntVal returns the float64 value of the JSON number at the supplied path. An error will be returned if the value is not a JSON number.

func (*ConfigAccessor) Flush

func (c *ConfigAccessor) Flush()

Flush removes internal references to the (potentially very large) merged JSON data so the associated memory can be recovered during the next garbage collection.

func (*ConfigAccessor) IntVal

func (c *ConfigAccessor) IntVal(path string) (int, error)

IntVal returns the int value of the JSON number at the supplied path. JSON numbers are internally represented by Go as a float64, so no error will be returned, but data might be lost if the JSON number does not actually represent an int. An error will be returned if the value is not a JSON number or cannot be converted to an int.

func (*ConfigAccessor) ObjectVal

func (c *ConfigAccessor) ObjectVal(path string) (map[string]interface{}, error)

ObjectVal returns a map representing a JSON object or nil if the path does not exist of points to a null JSON value. An error is returned if the value cannot be interpreted as a JSON object.

func (*ConfigAccessor) PathExists

func (c *ConfigAccessor) PathExists(path string) bool

PathExists check to see whether the supplied dot-delimited path exists in the configuration and points to a non-null JSON value.

func (*ConfigAccessor) Populate

func (ca *ConfigAccessor) Populate(path string, target interface{}) error

Populate sets the fields on the supplied target object using the JSON data at the supplied path. This is acheived using Go's json.Marshal to convert the data back into text JSON and then json.Unmarshal to unmarshal back into the target.

func (*ConfigAccessor) SetField

func (ca *ConfigAccessor) SetField(fieldName string, path string, target interface{}) error

SetField takes a target Go interface and uses the data a the supplied path to populated the named field on the target. The target must be a pointer to a struct. The field must be a string, bool, int, float63, string[interface{}] map or a slice of one of those types. An eror will be returned if the target field, is missing, not settable or incompatiable with the JSON value at the supplied path.

func (*ConfigAccessor) StringVal

func (c *ConfigAccessor) StringVal(path string) (string, error)

ObjectVal returns the string value of the JSON string at the supplied path. Does not convert other types to a string, so will return an error if the value is not a JSON string.

func (*ConfigAccessor) Value

func (c *ConfigAccessor) Value(path string) interface{}

Value returns the JSON value at the supplied path or nil if the path does not exist of points to a null JSON value.

type ContentParser

type ContentParser interface {
	ParseInto(data []byte, target interface{}) error
	Extensions() []string
	ContentTypes() []string
}

A ContentParser can take a []byte of some structured file type (e.g. YAML, JSON() and convert into a map[string]interface{} representation

type InitialSettings

type InitialSettings struct {

	// The level at which messages from Granitic components used before configuration files can be loaded (the initiator,
	// logger, IoC container, JSON merger etc.) will be logged. As soon as configuration has been loaded, this value will
	// be discarded in favour of LogLevels defined in that configuration.
	FrameworkLogLevel logging.LogLevel

	// Files, directories and URLs from which JSON configuration should be loaded and merged.
	Configuration []string

	// The time at which the application was started (to allow accurate timing of the IoC container start process).
	StartTime time.Time

	// An (optional) unique identifier for this instance of a Granitic application.
	InstanceId string

	// A base 64 serialised version of Granitic's built-in configuration files
	BuiltInConfig *string

	// Additional parsers to support config files in a format other than JSON
	ConfigParsers []ContentParser

	// Exit immediately after container has successfully started
	DryRun bool
}

InitialSettings contains settings that are needed by Granitic before configuration files can be loaded and parsed. See package granitic for more information on how this is used when starting a Granitic application with command line arguments or supplying an instance of this struct programmatically.

func InitialSettingsFromEnvironment

func InitialSettingsFromEnvironment() *InitialSettings

InitialSettingsFromEnvironment builds an InitialSettings and populates it with defaults or the values of command line arguments if available.

type JsonContentParser

type JsonContentParser struct {
}

func (*JsonContentParser) ContentTypes

func (jcp *JsonContentParser) ContentTypes() []string

func (*JsonContentParser) Extensions

func (jcp *JsonContentParser) Extensions() []string

func (*JsonContentParser) ParseInto

func (jcp *JsonContentParser) ParseInto(data []byte, target interface{}) error

type JsonMerger

type JsonMerger struct {
	// Logger used by Granitic framework components. Automatically injected.
	Logger logging.Logger

	// True if arrays should be joined when merging; false if the entire conetnts of the array should be overwritten.
	MergeArrays bool

	DefaultParser ContentParser
	// contains filtered or unexported fields
}

A JsonMerger can merge a sequence of JSON configuration files (from a filesystem or HTTP URL) into a single view of configuration that will be used to configure Grantic's facilities and the user's IoC components. See the top of this page for a brief explanation of how merging works.

func NewJsonMergerWithDirectLogging

func NewJsonMergerWithDirectLogging(l logging.Logger, cp ContentParser) *JsonMerger

func NewJsonMergerWithManagedLogging

func NewJsonMergerWithManagedLogging(flm *logging.ComponentLoggerManager, cp ContentParser) *JsonMerger

NewJsonMerger creates a JsonMerger with a Logger

func (*JsonMerger) LoadAndMergeConfig

func (jm *JsonMerger) LoadAndMergeConfig(files []string) (map[string]interface{}, error)

LoadAndMergeConfig takes a list of file paths or URIs to JSON files and merges them into a single in-memory object representation. See the top of this page for a brief explanation of how merging works. Returns an error if a remote URI returned a 4xx or 5xx response code, a file or folder could not be accessed or if two files could not be merged dued to JSON parsing errors.

func (*JsonMerger) LoadAndMergeConfigWithBase

func (jm *JsonMerger) LoadAndMergeConfigWithBase(config map[string]interface{}, files []string) (map[string]interface{}, error)

func (*JsonMerger) RegisterContentParser

func (jm *JsonMerger) RegisterContentParser(cp ContentParser)