configutil

package
v1.20210116.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2021 License: MIT Imports: 14 Imported by: 14

Documentation

Overview

Package configutil contains helpers for configuration.

The intent of this package is to allow you to compose configuration types found throughout `sdk/` and elsewhere into a single configuration type for a given program.

An example configuration type might be: 

type Config struct {
	DB db.Config `yaml:"db"`
	Logger logger.Config `yaml:"logger"`
	Web web.Config `yaml:"web"`
}

On start, you may want to read from a yaml configuration file into this type, deserializing the configuration. 

var cfg Config
paths, err := configutil.Read(&cfg)
// `err` is the first error returned from reading files
// `paths` are the paths read from to populate the config

If we want to also read from the environment, we can do so by adding a resolver, and using the `configutil.Resolve`, `configutil.SetXYZ` helpers. 

func (c *Config) Resolve(ctx context.Context) error {
	// NOTE: the pointer receiver is critical to modify the fields of the config
	return configutil.Resolve(ctx,
		(&c.DB).Resolve, // we use the (&foo) form here because we want to call the pointer receiver for `Resolve`
		(&c.Logger).Resolve,
		(&c.Web).Resolve,

		configutil.SetString(&c.Web.BindAddr, configutil.Env("BIND_ADDR"), configutil.String(c.Web.BindAddr)),
	)
}

In the above, the environment variable `BIND_ADDR` takes precedence over the string value found in any configuration file(s).

Note, we also "resolve" each of the attached configs first, in case they also have environment variables they read from etc.

Index

Constants

View Source 
const (
	// EnvVarConfigPath is the env var for configs.
	EnvVarConfigPath = "CONFIG_PATH"
	// ExtensionJSON is a file extension.
	ExtensionJSON = ".json"
	// ExtensionYAML is a file extension.
	ExtensionYAML = ".yaml"
	// ExtensionYML is a file extension.
	ExtensionYML = ".yml"
)
View Source 
const (
	// ErrConfigPathUnset is a common error.
	ErrConfigPathUnset = ex.Class("config path unset")

	// ErrInvalidConfigExtension is a common error.
	ErrInvalidConfigExtension = ex.Class("config extension invalid")
)

Variables

View Source 
var (
	// DefaultPaths are default path locations.
	// They are tested and read in order, so the later
	// paths will override data found in the earlier ones.
	DefaultPaths = []string{
		"/var/secrets/config.yml",
		"/var/secrets/config.yaml",
		"/var/secrets/config.json",
		"./_config/config.yml",
		"./_config/config.yaml",
		"./_config/config.json",
		"./config.yml",
		"./config.yaml",
		"./config.json",
	}
)

Functions

func GetConfigPaths added in v1.20210103.1 

func GetConfigPaths(ctx context.Context) []string

GetConfigPaths gets the config file paths from a context..

func IsConfigPathUnset 

func IsConfigPathUnset(err error) bool

IsConfigPathUnset returns if an error is an ErrConfigPathUnset.

func IsIgnored 

func IsIgnored(err error) bool

IsIgnored returns if we should ignore the config read error.

func IsInvalidConfigExtension 

func IsInvalidConfigExtension(err error) bool

IsInvalidConfigExtension returns if an error is an ErrInvalidConfigExtension.

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist returns if an error is an os.ErrNotExist.

Read will never return a not found error, instead it will simply skip over that file, `IsNotExist` should be used in other situations like in resolvers.

func MaybeDebugf added in v1.20201204.1 

func MaybeDebugf(log Logger, format string, args ...interface{})

MaybeDebugf writes a debug message if the logger is set.

func MaybeErrorf added in v1.20201204.1 

func MaybeErrorf(log Logger, format string, args ...interface{})

MaybeErrorf writes an error message if the logger is set.

func MaybeInfof added in v1.20201204.1 

func MaybeInfof(log Logger, format string, args ...interface{})

MaybeInfof writes an info message if the logger is set.

func MaybeWarningf added in v1.20201204.1 

func MaybeWarningf(log Logger, format string, args ...interface{})

MaybeWarningf writes a debug message if the logger is set.

func MustRead added in v1.20210103.1 

func MustRead(ref Any, options ...Option) (filePaths []string)

MustRead reads a config from optional path(s) and panics on error.

It is functionally equivalent to `Read` outside error handling; see this function for more information.

func Read 

func Read(ref Any, options ...Option) (paths []string, err error)

Read reads a config from optional path(s), returning the paths read from (in the order visited), and an error if there were any issues.

If the ref type is a `Resolver` the `Resolve(context.Context) error` method will be called on the ref and passed a context configured from the given options.

By default, a well known set of paths will be read from (including a path read from the environment variable `CONFIG_PATH`).

You can override this by providing options to specify which paths will be read from: 

paths, err := configutil.Read(&cfg, configutil.OptPaths("foo.yml"))

The above will _only_ read from `foo.yml` to populate the `cfg` reference.

func Resolve added in v1.20201204.1 

func Resolve(ctx context.Context, steps ...ResolveAction) (err error)

Resolve returns the first non-nil error in a list.

func WithConfigPaths added in v1.20210103.1 

func WithConfigPaths(ctx context.Context, paths []string) context.Context

WithConfigPaths adds config file paths to the context.

Types

type Any 

type Any = interface{}

Any is a loose type alias to interface{}.

type BoolFunc added in v1.20201204.1 

type BoolFunc func(context.Context) (*bool, error)

BoolFunc is a bool value source. It can be used with configutil.SetBool

func (BoolFunc) Bool added in v1.20201204.1 

func (vf BoolFunc) Bool(ctx context.Context) (*bool, error)

Bool returns an invocation of the function.

type BoolSource added in v1.20201204.1 

type BoolSource interface {
	// Bool should return a bool if the source has a given value.
	// It should return nil if the value is not found.
	// It should return an error if there was a problem fetching the value.
	Bool(context.Context) (*bool, error)
}

BoolSource is a type that can return a value.

type BoolValue added in v1.20201204.1 

type BoolValue bool

BoolValue implements value provider.

func Bool added in v1.20201204.1 

func Bool(value *bool) *BoolValue

Bool returns a BoolValue for a given value.

func (*BoolValue) Bool added in v1.20201204.1 

func (b *BoolValue) Bool(_ context.Context) (*bool, error)

Bool returns the value for a constant.

type ConfigContents added in v1.20210103.1 

type ConfigContents struct {
	Ext      string
	Contents io.Reader
}

ConfigContents are literal contents to read from.

type ConfigOptions added in v1.20201204.1 

type ConfigOptions struct {
	Log       Logger
	Context   context.Context
	Contents  []ConfigContents
	FilePaths []string
	Env       env.Vars
}

ConfigOptions are options built for reading configs.

func (ConfigOptions) Background added in v1.20201204.1 

func (co ConfigOptions) Background() context.Context

Background yields a context for a config options set.

type Duration added in v1.20201204.1 

type Duration time.Duration

Duration implements value provider.

If the value is zero, a nil is returned by the implementation indicating the value was not present.

If you want 0 to be a valid value, you must use DurationPtr.

func (Duration) Duration added in v1.20201204.1 

func (dc Duration) Duration(_ context.Context) (*time.Duration, error)

Duration returns the value for a constant.

type DurationFunc added in v1.20201204.1 

type DurationFunc func(context.Context) (*time.Duration, error)

DurationFunc is a value source from a function.

func (DurationFunc) Duration added in v1.20201204.1 

func (vf DurationFunc) Duration(ctx context.Context) (*time.Duration, error)

Duration returns an invocation of the function.

type DurationPtrSource added in v1.20201204.1 

type DurationPtrSource struct {
	Value *time.Duration
}

DurationPtrSource is a DurationSource that wraps a duration pointer.

func (DurationPtrSource) Duration added in v1.20201204.1 

func (dps DurationPtrSource) Duration(_ context.Context) (*time.Duration, error)

Duration implements DurationSource.

type DurationSource added in v1.20201204.1 

type DurationSource interface {
	// Duration should return a time.Duration if the source has a given value.
	// It should return nil if the value is not present.
	// It should return an error if there was a problem fetching the value.
	Duration(context.Context) (*time.Duration, error)
}

DurationSource is a type that can return a time.Duration value.

func DurationPtr added in v1.20201204.1 

func DurationPtr(value *time.Duration) DurationSource

DurationPtr returns a DurationSource for a given duration pointer.

type EnvVars added in v1.20201204.1 

type EnvVars struct {
	Key string
}

EnvVars is a value provider where the string represents the environment variable name. It can be used with *any* config.Set___ type.

func Env added in v1.20201204.1 

func Env(key string) EnvVars

Env returns a new environment value provider.

func (EnvVars) Bool added in v1.20201204.1 

func (e EnvVars) Bool(ctx context.Context) (*bool, error)

Bool returns a given environment variable as a bool.

func (EnvVars) Duration added in v1.20201204.1 

func (e EnvVars) Duration(ctx context.Context) (*time.Duration, error)

Duration returns a given environment variable as a time.Duration.

func (EnvVars) Float64 added in v1.20201204.1 

func (e EnvVars) Float64(ctx context.Context) (*float64, error)

Float64 returns a given environment variable as a float64.

func (EnvVars) Int added in v1.20201204.1 

func (e EnvVars) Int(ctx context.Context) (*int, error)

Int returns a given environment variable as an int.

func (EnvVars) Int32 added in v1.20201204.1 

func (e EnvVars) Int32(ctx context.Context) (*int32, error)

Int32 returns a given environment variable as an int32.

func (EnvVars) Int64 added in v1.20201204.1 

func (e EnvVars) Int64(ctx context.Context) (*int64, error)

Int64 returns a given environment variable as an int64.

func (EnvVars) String added in v1.20201204.1 

func (e EnvVars) String(ctx context.Context) (*string, error)

String returns a given environment variable as a string.

func (EnvVars) Strings added in v1.20201204.1 

func (e EnvVars) Strings(ctx context.Context) ([]string, error)

Strings returns a given environment variable as strings.

type File added in v1.20201204.1 

type File string

File reads the string contents of a file as a literal config value.

func (File) String added in v1.20201204.1 

func (f File) String(ctx context.Context) (*string, error)

String returns the string contents of a file.

type Float64 added in v1.20201204.1 

type Float64 float64

Float64 implements value provider.

Note: this will treat 0 as unset, if 0 is a valid value you must use configutil.FloatPtr.

func (Float64) Float64 added in v1.20201204.1 

func (f Float64) Float64(_ context.Context) (*float64, error)

Float64 returns the value for a constant.

type Float64Func added in v1.20201204.1 

type Float64Func func(context.Context) (*float64, error)

Float64Func is a float value source from a commandline flag.

func (Float64Func) Float64 added in v1.20201204.1 

func (vf Float64Func) Float64(ctx context.Context) (*float64, error)

Float64 returns an invocation of the function.

type Float64PtrSource added in v1.20201204.1 

type Float64PtrSource struct {
	Value *float64
}

Float64PtrSource is a Float64Source that wraps a float64 pointer.

func (Float64PtrSource) Float64 added in v1.20201204.1 

func (fps Float64PtrSource) Float64(_ context.Context) (*float64, error)

Float64 implements Float64Source.

type Float64Source added in v1.20201204.1 

type Float64Source interface {
	// Float should return a float64 if the source has a given value.
	// It should return nil if the value is not found.
	// It should return an error if there was a problem fetching the value.
	Float64(context.Context) (*float64, error)
}

Float64Source is a type that can return a value.

func Float64Ptr added in v1.20201204.1 

func Float64Ptr(value *float64) Float64Source

Float64Ptr returns an Float64Source for a given float64 pointer.

type Int added in v1.20201204.1 

type Int int

Int implements value provider.

Note: Int treats 0 as unset, if 0 is a valid value you must use configutil.IntPtr.

func (Int) Int added in v1.20201204.1 

func (i Int) Int(_ context.Context) (*int, error)

Int returns the value for a constant.

type Int32 added in v1.20201204.1 

type Int32 int32

Int32 implements value provider.

Note: Int32 treats 0 as unset, if 0 is a valid value you must use configutil.Int32Ptr.

func (Int32) Int32 added in v1.20201204.1 

func (i Int32) Int32(_ context.Context) (*int32, error)

Int32 returns the value for a constant.

type Int32PtrSource added in v1.20201204.1 

type Int32PtrSource struct {
	Value *int32
}

Int32PtrSource is a Int32Source that wraps an int32 pointer.

func (Int32PtrSource) Int32 added in v1.20201204.1 

func (ips Int32PtrSource) Int32(_ context.Context) (*int32, error)

Int32 implements Int32Source.

type Int32Source added in v1.20201204.1 

type Int32Source interface {
	// Int32 should return an int32 if the source has a given value.
	// It should return nil if the value is not found.
	// It should return an error if there was a problem fetching the value.
	Int32(ctx context.Context) (*int32, error)
}

Int32Source is a type that can return a value.

func Int32Ptr added in v1.20201204.1 

func Int32Ptr(value *int32) Int32Source

Int32Ptr returns an Int32Source for a given int32 pointer.

type Int64 added in v1.20201204.1 

type Int64 int64

Int64 implements value provider.

Note: Int64 treats 0 as unset, if 0 is a valid value you must use configutil.Int64Ptr.

func (Int64) Int64 added in v1.20201204.1 

func (i Int64) Int64(_ context.Context) (*int64, error)

Int64 returns the value for a constant.

type Int64Func added in v1.20201204.1 

type Int64Func func(context.Context) (*int64, error)

Int64Func is an int64 value source from a commandline flag.

func (Int64Func) Int64 added in v1.20201204.1 

func (vf Int64Func) Int64(ctx context.Context) (*int64, error)

Int64 returns an invocation of the function.

type Int64PtrSource added in v1.20201204.1 

type Int64PtrSource struct {
	Value *int64
}

Int64PtrSource is a Int64Source that wraps an Int64 poInt64er.

func (Int64PtrSource) Int64 added in v1.20201204.1 

func (ips Int64PtrSource) Int64(_ context.Context) (*int64, error)

Int64 implements Int64Source.

type Int64Source added in v1.20201204.1 

type Int64Source interface {
	// Int should return a int if the source has a given value.
	// It should return nil if the value is not found.
	// It should return an error if there was a problem fetching the value.
	Int64(ctx context.Context) (*int64, error)
}

Int64Source is a type that can return a value.

func Int64Ptr added in v1.20201204.1 

func Int64Ptr(value *int64) Int64Source

Int64Ptr returns an Int64Source for a given Int64 poInt64er.

type IntFunc added in v1.20201204.1 

type IntFunc func(context.Context) (*int, error)

IntFunc is an int value source from a commandline flag.

func (IntFunc) Int added in v1.20201204.1 

func (vf IntFunc) Int(ctx context.Context) (*int, error)

Int returns an invocation of the function.

type IntPtrSource added in v1.20201204.1 

type IntPtrSource struct {
	Value *int
}

IntPtrSource is a IntSource that wraps an int pointer.

func (IntPtrSource) Int added in v1.20201204.1 

func (ips IntPtrSource) Int(_ context.Context) (*int, error)

Int implements IntSource.

type IntSource added in v1.20201204.1 

type IntSource interface {
	// Int should return a int if the source has a given value.
	// It should return nil if the value is not found.
	// It should return an error if there was a problem fetching the value.
	Int(ctx context.Context) (*int, error)
}

IntSource is a type that can return a value.

func IntPtr added in v1.20201204.1 

func IntPtr(value *int) IntSource

IntPtr returns an IntSource for a given int pointer.

type Labels 

type Labels = map[string]string

Labels is a loose type alias to map[string]string

type Logger added in v1.20201204.1 

type Logger interface {
	Infof(string, ...interface{})
	Debugf(string, ...interface{})
	Warningf(string, ...interface{})
	Errorf(string, ...interface{})
}

Logger is a type that can satisfy the configutil logger interface.

type Option added in v1.20201204.1 

type Option func(*ConfigOptions) error

Option is a modification of config options.

func OptAddContent added in v1.20210103.1 

func OptAddContent(ext string, content io.Reader) Option

OptAddContent adds contents to the options as a reader.

func OptAddContentString added in v1.20210103.1 

func OptAddContentString(ext string, contents string) Option

OptAddContentString adds contents to the options as a string.

func OptAddFilePaths added in v1.20201204.1 

func OptAddFilePaths(paths ...string) Option

OptAddFilePaths is deprecated; use `OptAddPaths`

func OptAddPaths added in v1.20210103.1 

func OptAddPaths(paths ...string) Option

OptAddPaths adds paths to search for the config file.

These paths will be added after the default paths.

func OptAddPreferredPaths added in v1.20210103.1 

func OptAddPreferredPaths(paths ...string) Option

OptAddPreferredPaths adds paths to search first for the config file.

func OptContents added in v1.20201204.1 

func OptContents(contents []ConfigContents) Option

OptContents sets config contents on the options.

func OptContext added in v1.20201204.1 

func OptContext(ctx context.Context) Option

OptContext sets the context on the options.

func OptEnv added in v1.20201204.1 

func OptEnv(vars env.Vars) Option

OptEnv sets the config options environment variables. If unset, will default to the current global environment variables.

func OptLog added in v1.20201204.1 

func OptLog(log Logger) Option

OptLog sets the configutil logger.

func OptPaths added in v1.20210103.1 

func OptPaths(paths ...string) Option

OptPaths sets paths to search for the config file.

func OptUnsetPaths added in v1.20210103.1 

func OptUnsetPaths() Option

OptUnsetPaths removes default paths from the paths set.

type Parser added in v1.20201204.1 

type Parser struct {
	Source StringSource
}

Parser parses an int.

func Parse added in v1.20201204.1 

func Parse(source StringSource) Parser

Parse returns an int parser.

func (Parser) Bool added in v1.20201204.1 

func (p Parser) Bool(ctx context.Context) (*bool, error)

Bool returns the bool value.

func (Parser) Duration added in v1.20201204.1 

func (p Parser) Duration(ctx context.Context) (*time.Duration, error)

Duration returns a parsed duration value.

func (Parser) Float64 added in v1.20201204.1 

func (p Parser) Float64(ctx context.Context) (*float64, error)

Float64 returns the float64 value.

func (Parser) Int added in v1.20201204.1 

func (p Parser) Int(ctx context.Context) (*int, error)

Int returns the int value.

type ResolveAction added in v1.20201204.1 

type ResolveAction func(context.Context) error

ResolveAction is a step in resolution.

func ResolveIf added in v1.20201204.1 

func ResolveIf(branch bool, resolver ResolveAction) ResolveAction

ResolveIf wraps a resolver in a branch.

func ResolveIfFunc added in v1.20201204.1 

func ResolveIfFunc(branchFunc func(context.Context) bool, resolver ResolveAction) ResolveAction

ResolveIfFunc wraps a resolver in a branch returned from a function.

func SetBool added in v1.20201204.1 

func SetBool(destination **bool, sources ...BoolSource) ResolveAction

SetBool coalesces a given list of sources into a variable.

func SetDuration added in v1.20201204.1 

func SetDuration(destination *time.Duration, sources ...DurationSource) ResolveAction

SetDuration coalesces a given list of sources into a variable.

func SetDurationPtr added in v1.20201204.1 

func SetDurationPtr(destination **time.Duration, sources ...DurationSource) ResolveAction

SetDurationPtr coalesces a given list of sources into a variable.

func SetFloat64 added in v1.20201204.1 

func SetFloat64(destination *float64, sources ...Float64Source) ResolveAction

SetFloat64 coalesces a given list of sources into a variable.

func SetFloat64Ptr added in v1.20201204.1 

func SetFloat64Ptr(destination **float64, sources ...Float64Source) ResolveAction

SetFloat64Ptr coalesces a given list of sources into a variable.

func SetInt added in v1.20201204.1 

func SetInt(destination *int, sources ...IntSource) ResolveAction

SetInt coalesces a given list of sources into a variable.

func SetInt32 added in v1.20201204.1 

func SetInt32(destination *int32, sources ...Int32Source) ResolveAction

SetInt32 coalesces a given list of sources into a variable.

func SetInt32Ptr added in v1.20201204.1 

func SetInt32Ptr(destination **int32, sources ...Int32Source) ResolveAction

SetInt32Ptr coalesces a given list of sources into a variable.

func SetInt64 added in v1.20201204.1 

func SetInt64(destination *int64, sources ...Int64Source) ResolveAction

SetInt64 coalesces a given list of sources into a variable.

func SetInt64Ptr added in v1.20201204.1 

func SetInt64Ptr(destination **int64, sources ...Int64Source) ResolveAction

SetInt64Ptr coalesces a given list of sources into a variable.

func SetIntPtr added in v1.20201204.1 

func SetIntPtr(destination **int, sources ...IntSource) ResolveAction

SetIntPtr coalesces a given list of sources into a variable.

func SetString added in v1.20201204.1 

func SetString(destination *string, sources ...StringSource) ResolveAction

SetString coalesces a given list of sources into a variable.

func SetStringPtr added in v1.20201204.1 

func SetStringPtr(destination **string, sources ...StringSource) ResolveAction

SetStringPtr coalesces a given list of sources into a variable.

func SetStrings added in v1.20201204.1 

func SetStrings(destination *[]string, sources ...StringsSource) ResolveAction

SetStrings coalesces a given list of sources into a variable.

type Resolver added in v1.20201204.1 

type Resolver interface {
	Resolve(context.Context) error
}

Resolver is a type that can be resolved.

type String added in v1.20201204.1 

type String string

String implements value provider. An empty string is treated as unset, and will cause `String(context.Context) (*string, error)` to return nil for the string.

func (String) String added in v1.20201204.1 

func (s String) String(_ context.Context) (*string, error)

StringValue returns the value for a constant.

type StringFunc added in v1.20201204.1 

type StringFunc func(context.Context) (*string, error)

StringFunc is a value source from a function.

func (StringFunc) String added in v1.20201204.1 

func (svf StringFunc) String(ctx context.Context) (*string, error)

String returns an invocation of the function.

type StringSource added in v1.20201204.1 

type StringSource interface {
	// String should return a string if the source has a given value.
	// It should return nil if the value is not present.
	// It should return an error if there was a problem fetching the value.
	String(context.Context) (*string, error)
}

StringSource is a type that can return a value.

func StringPtr added in v1.20201204.1 

func StringPtr(value *string) StringSource

StringPtr returns a StringSource for a given string pointer.

type Strings added in v1.20201204.1 

type Strings []string

Strings implements a value provider.

func (Strings) Strings added in v1.20201204.1 

func (s Strings) Strings(_ context.Context) ([]string, error)

Strings returns the value for a constant.

type StringsFunc added in v1.20201204.1 

type StringsFunc func(context.Context) ([]string, error)

StringsFunc is a value source from a function.

func (StringsFunc) Strings added in v1.20201204.1 

func (svf StringsFunc) Strings(ctx context.Context) ([]string, error)

Strings returns an invocation of the function.

type StringsSource added in v1.20201204.1 

type StringsSource interface {
	// Strings should return a string array if the source has a given value.
	// It should return nil if the value is not present.
	// It should return an error if there was a problem fetching the value.
	Strings(context.Context) ([]string, error)
}

StringsSource is a type that can return a value.

type Vars 

type Vars = map[string]interface{}

Vars is a loose type alias to map[string]string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.