config

Documentation

Overview

Package config provides an unified pattern for configuration structs.

Usage

Every configuration struct should implement the Config interface. There are three parts to a configuration: Initialization, validation and sample generation.

Initialization

A config struct is initialized by calling InitDefaults. This recursively initializes all uninitialized fields. Fields that should not be initialized to default must be set before calling InitDefaults.

Validation

A config struct is validated by calling Validate. This recursively validates all fields.

Sample Generation

A config struct can be used to generate a commented sample toml config by calling Sample. Unit tests guarantee the consistency between implementation and the generated sample. To this end, each config struct has to provide a composable unit test to check that the sample is parsable and consistent with the default values. See lib/envtest for an example.

Warning: The method Sample is allowed to panic if an error occurs during sample generation.

Index

• Constants
• func Decode(raw []byte, cfg interface{}) error
• func Digest(cfg Config) ([]byte, error)
• func InitAll(defaulters ...Defaulter)
• func LoadFile(file string, cfg interface{}) error
• func LoadResource(location string) (io.ReadCloser, error)
• func ValidateAll(validators ...Validator) error
• func WriteSample(dst io.Writer, path Path, ctx CtxMap, samplers ...Sampler)
• func WriteString(dst io.Writer, s string)
• type Config
• type CtxMap
• type Defaulter
• type NoDefaulter
  • func (NoDefaulter) InitDefaults()
• type NoValidator
  • func (NoValidator) Validate() error
• type Path
  • func (p Path) Extend(s string) Path
• type Sampler
  • func FormatData(s Sampler, a ...interface{}) Sampler
  • func OverrideName(s Sampler, name string) Sampler
• type StringSampler
  • func (s StringSampler) ConfigName() string
  • func (s StringSampler) Sample(dst io.Writer, _ Path, _ CtxMap)
• type TableSampler
• type Validator

Constants

const ID = "id"

Functions

func Decode

func Decode(raw []byte, cfg interface{}) error

Decode decodes a raw config.

func Digest

func Digest(cfg Config) ([]byte, error)

Digest calculates a digest of the configuration by attempting to encode the configuration as JSON object and then calculate the SHA256 sum on the resulting encoding.

func InitAll

func InitAll(defaulters ...Defaulter)

InitAll initializes all defaulters.

func LoadFile

func LoadFile(file string, cfg interface{}) error

LoadFile loads the config from file.

func LoadResource

func LoadResource(location string) (io.ReadCloser, error)

LoadResource returns an object suitable for reading based on the resource specified by location.

If location starts with "http://" or "https://", LoadResource will issue an HTTP GET to retrieve the resource. Only the Body of the reply can be read from the returned reader.

If the location does not start with "http://" or "https://, LoadResource interprets location as a file path and loads the resource from disk.

It is the caller's responsibility to close the returned reader.

func ValidateAll

func ValidateAll(validators ...Validator) error

ValidateAll validates all validators. The first error encountered is returned.

func WriteSample

func WriteSample(dst io.Writer, path Path, ctx CtxMap, samplers ...Sampler)

WriteSample writes all sample config blocks in order of appearance with indentation and header to dst. It panics if an error occurs.

func WriteString

func WriteString(dst io.Writer, s string)

WriteString writes the string to dst. It panics if an error occurs.

Types

type Config

type Config interface {
	Sampler
	Validator
	Defaulter
}

Config is the interface that config structs should implement to allow for streamlined initialization, validation and sample generation.

type CtxMap

type CtxMap map[string]string

CtxMap contains the context for sample generation.

type Defaulter

type Defaulter interface {
	// InitDefaults recursively initializes the default values of all
	// uninitialized fields.
	InitDefaults()
}

Defaulter defines the initialization part of Config.

type NoDefaulter

type NoDefaulter struct{}

NoDefaulter implements a Defaulter that does a no-op on InitDefaults. It can be embedded in config structs that do not have any defaults.

func (NoDefaulter) InitDefaults

func (NoDefaulter) InitDefaults()

InitDefaults is a no-op.

type NoValidator

type NoValidator struct{}

NoValidator implements a Validator that never fails to validate. It can be embedded in config structs that do not need to validate.

func (NoValidator) Validate

func (NoValidator) Validate() error

Validate always returns nil.

type Path

type Path []string

Path is the header of a config block possibly consisting of multiple parts.

func (Path) Extend

func (p Path) Extend(s string) Path

Extend creates a copy of the path with string s appended.

type Sampler

type Sampler interface {
	// Sample creates a sample config and writes it to dst. Ctx provides
	// additional information. Sample is allowed to panic if an error
	// occurs.
	Sample(dst io.Writer, path Path, ctx CtxMap)
}

Sampler defines the sample generation part of Config.

func FormatData

func FormatData(s Sampler, a ...interface{}) Sampler

FormatData creates a sampler that will call fmt.Sprintf on the string returned by s.Sample using the supplied argument information.

func OverrideName

func OverrideName(s Sampler, name string) Sampler

OverrideName creates a sampler that is identical to the one in the argument, except it will use the desired config name instead of the original one.

type StringSampler

type StringSampler struct {
	// Text the sample string.
	Text string
	// Name the config name.
	Name string
}

StringSampler implements a Sampler that writes string Text and provides Name as ConfigName.

func (StringSampler) ConfigName

func (s StringSampler) ConfigName() string

ConfigName returns the name.

func (StringSampler) Sample

func (s StringSampler) Sample(dst io.Writer, _ Path, _ CtxMap)

Sample writes the text to dst.

type TableSampler

type TableSampler interface {
	Sampler
	// ConfigName returns the name of the config block. This forces
	// consistency between samples for different services for the same
	// config block.
	ConfigName() string
}

TableSampler is used to write a table to the sample.

type Validator

type Validator interface {
	// Validate recursively checks that all fields contain valid values.
	Validate() error
}

Validator defines the validation part of Config.