configutil

Documentation

Index

• Constants
• Variables
• func Env[T any](key string) func(context.Context) (*T, error)
• func GetConfigPaths(ctx context.Context) []string
• func GetEnvVars(ctx context.Context) map[string]string
• func IsConfigPathUnset(err error) bool
• func IsIgnored(err error) bool
• func IsInvalidConfigExtension(err error) bool
• func IsNotExist(err error) bool
• func MustRead(ref any, options ...Option) (filePaths []string)
• func Read(ref any, options ...Option) (paths []string, err error)
• func Resolve(ctx context.Context, steps ...ResolveAction) (err error)
• func WithConfigPaths(ctx context.Context, paths []string) context.Context
• func WithEnvVars(ctx context.Context, vars map[string]string) context.Context
• type ConfigOptions
  • func (co ConfigOptions) Background() context.Context
• type Option
  • func OptAddContent(content io.Reader) Option
  • func OptAddContentString(contents string) Option
  • func OptAddFilePaths(paths ...string) Option
  • func OptAddPaths(paths ...string) Option
  • func OptAddPreferredPaths(paths ...string) Option
  • func OptContents(contents ...io.Reader) Option
  • func OptContext(ctx context.Context) Option
  • func OptDeserializer(fn func(io.Reader, any) error) Option
  • func OptEnv(vars map[string]string) Option
  • func OptPaths(paths ...string) Option
  • func OptUnsetPaths() Option
• type ResolveAction
  • func Set[T any](destination *T, sources ...Source[T]) ResolveAction
• type Resolver
• type Source
  • func Const[T comparable](v T) Source[T]
  • func Lazy[T comparable](value *T) Source[T]

Constants

const (
	// EnvVarConfigPath is the env var for configs.
	EnvVarConfigPath = "CONFIG_PATH"
)

Variables

var (
	// ErrConfigPathUnset is a common error.
	ErrConfigPathUnset = errors.New("config path unset")

	// ErrInvalidConfigExtension is a common error.
	ErrInvalidConfigExtension = errors.New("config extension invalid")
)

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 Env

func Env[T any](key string) func(context.Context) (*T, error)

Env returns an environment variable with a given key as a value source.

func GetConfigPaths

func GetConfigPaths(ctx context.Context) []string

GetConfigPaths gets the config file paths from a context.

func GetEnvVars

func GetEnvVars(ctx context.Context) map[string]string

GetEnvVars gets the env vars 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 MustRead

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

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

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

func WithConfigPaths

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

WithConfigPaths adds config file paths to the context.

func WithEnvVars

func WithEnvVars(ctx context.Context, vars map[string]string) context.Context

WithEnvVars adds the env vars to the context.

Types

type ConfigOptions

type ConfigOptions struct {
	Context      context.Context
	Contents     []io.Reader
	FilePaths    []string
	Deserializer func(r io.Reader, ref any) error
	Env          map[string]string
}

ConfigOptions are options built for reading configs.

func (ConfigOptions) Background

func (co ConfigOptions) Background() context.Context

Background yields a context for a config options set.

type Option

type Option func(*ConfigOptions) error

Option is a modification of config options.

func OptAddContent

func OptAddContent(content io.Reader) Option

OptAddContent adds contents to the options as a reader.

func OptAddContentString

func OptAddContentString(contents string) Option

OptAddContentString adds contents to the options as a string.

func OptAddFilePaths

func OptAddFilePaths(paths ...string) Option

OptAddFilePaths is deprecated; use `OptAddPaths`

func OptAddPaths

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

func OptAddPreferredPaths(paths ...string) Option

OptAddPreferredPaths adds paths to search first for the config file.

func OptContents

func OptContents(contents ...io.Reader) Option

OptContents sets config contents on the options.

func OptContext

func OptContext(ctx context.Context) Option

OptContext sets the context on the options.

func OptDeserializer

func OptDeserializer(fn func(io.Reader, any) error) Option

OptDeserializer sets the deserializer on the options.

func OptEnv

func OptEnv(vars map[string]string) Option

OptEnv sets the env vars on the options.

func OptPaths

func OptPaths(paths ...string) Option

OptPaths sets paths to search for the config file.

func OptUnsetPaths

func OptUnsetPaths() Option

OptUnsetPaths removes default paths from the paths set.

type ResolveAction

type ResolveAction func(context.Context) error

ResolveAction is a step in resolution.

func Set

func Set[T any](destination *T, sources ...Source[T]) ResolveAction

Set sets a field from a given list of sources.

type Resolver

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

Resolver is a type that can be resolved.

type Source

type Source[T any] func(context.Context) (*T, error)

Source is a function that provides a given value.

func Const

func Const[T comparable](v T) Source[T]

Const returns a constant configuration value.

Do not reference resolved fields with this function! They will always be zero!

func Lazy

func Lazy[T comparable](value *T) Source[T]

Lazy returns a Source for a given typed pointer.

Lazy differs from a typical Source[T] that it returns or evaluates the passed value when the resolve happens, potentially after the value of the pointer has been set from somewhere else.

Lazy also specifically treats the "zero" value of T as unset.