config

Documentation

Overview

Package config supplies a simple workflow for initializing an uber/fx App instance with spf13/pflag, spf13/viper, and any other components that need to be initialized prior to any uber/fx providers running. Additionally, this package provides simpler providers for use by applications that do not need this more complex workflow.

Index

• func ProvideViper(builders ...ViperBuilder) func(ViperIn) (ViperOut, error)
• type ApplicationName
  • func DefaultApplicationName() ApplicationName
• type CommandLine
  • func (cl CommandLine) Provide(builders ...FlagSetBuilder) fx.Option
• type CommandLineOut
• type FlagSetBuilder
• type KeyUnmarshaller
• type MissingKeyError
  • func NewMissingKeyError(k string) MissingKeyError
• type Unmarshaller
• type ViperBuilder
  • func Json(data string) ViperBuilder
  • func ReadConfig(format string, data io.Reader) ViperBuilder
  • func Yaml(data string) ViperBuilder
• type ViperIn
• type ViperOut
• type ViperUnmarshaller
  • func (vu ViperUnmarshaller) IsSet(k string) bool
  • func (vu ViperUnmarshaller) Unmarshal(v interface{}) error
  • func (vu ViperUnmarshaller) UnmarshalKey(k string, v interface{}) error

Functions

func ProvideViper

func ProvideViper(builders ...ViperBuilder) func(ViperIn) (ViperOut, error)

ProvideViper produces components for the viper environment. Each builder is invoked in sequence, and any error will short-circuit construction. This provider function does not itself read any configuration or otherwise modify the viper instance it creates. At least one builder function must read configuration.

Types

type ApplicationName

type ApplicationName string

ApplicationName is the type of component that identifies the executable or application name.

func DefaultApplicationName

func DefaultApplicationName() ApplicationName

DefaultApplicationName simply returns os.Arg[0]

type CommandLine

type CommandLine struct {
	// Name is the executable or application name.  If unset, os.Args[0] is used.
	Name string

	// Arguments are the command-line arguments to parse.  If nil, os.Args[1:] is used.  Note that
	// if this slice is explicitly set to an empty slice, then an empty slice of arguments will be parsed.
	Arguments []string

	// ErrorHandling is the pflag error handling mode.  Defaults to ContinueOnError.
	ErrorHandling pflag.ErrorHandling

	// DisableParse controls whether Provide will parse the command line after building the flagset.
	// Setting this to true allows upstream providers or invoke functions to handle the parsing.
	DisableParse bool
}

CommandLine describes how to provide a *pflag.FlagSet to an uber/fx container. The zero value for this type is valid and will parse the executable's command line defined by os.Args. Examples include:

CommandLine{}.Provide(parseCommandLine)
CommandLine{Name: "custom"}.Provide(builder1, builder2)
CommandLine{DisableParse: true}.Provide(parseIt)

func (CommandLine) Provide

func (cl CommandLine) Provide(builders ...FlagSetBuilder) fx.Option

Provide is an uber/fx provide function that creates a *pflag.FlagSet. Zero or more builders may be passed to configure flagset, which includes adding command-line arguments. If none of the builders parse the command line, and if DisableParse is false, this function will parse the arguments prior to returning the flagset.

This provider will short-circuit application startup using fx.Error if any command-line parsing error occurs.

type CommandLineOut

type CommandLineOut struct {
	fx.Out

	// Name is the application (or, executable) name determined by CommandLine.Provide.
	// It defaults to os.Args[0].  This component will always be supplied regardless of
	// the CommandLine settings.
	Name ApplicationName

	// FlagSet is the command line flags and configuration.  This will be parsed by default.
	FlagSet *pflag.FlagSet
}

CommandLineOut defines the components provided by CommandLine.Provide

type FlagSetBuilder

type FlagSetBuilder func(*pflag.FlagSet) error

FlagSetBuilder is a builder strategy for tailoring a flagset. Most commonly, this involves setting up any command line flags.

type KeyUnmarshaller

type KeyUnmarshaller interface {
	// IsSet checks if a configuration key is present, either in the source or as a default.
	// See https://godoc.org/github.com/spf13/viper#IsSet
	IsSet(string) bool

	// UnmarshalKey unmarshals an object, normally a pointer to struct, from a given configuration key.
	// No attempt is made to verify the existence of the configuration key.  If no such key exists,
	// unmarshalling will still happen against a default set of options.
	// See https://godoc.org/github.com/spf13/viper#UnmarshalKey
	UnmarshalKey(string, interface{}) error
}

KeyUnmarshaller is a strategy for unmarshalling objects from hierarchial configuration sources.

type MissingKeyError

type MissingKeyError interface {
	error
	Key() string
}

MissingKeyError is returned when a required key was not found in the configuration

func NewMissingKeyError

func NewMissingKeyError(k string) MissingKeyError

NewMissingKeyError creates an error that indicates the given configuration key is not present in the underlying configuration source

type Unmarshaller

type Unmarshaller interface {
	KeyUnmarshaller
	Unmarshal(interface{}) error
}

Unmarshaller is a strategy for unmarshalling configuration, mostly in the form of structs.

type ViperBuilder

type ViperBuilder func(ViperIn, *viper.Viper) error

ViperBuilder is a builder strategy for tailoring a viper instance. The ViperIn set of dependencies will always have the Name field set, either as a component or by defaulting to DefaultApplicationName.

func Json

func Json(data string) ViperBuilder

Json uses ReadConfig to read configuration from an in-memory JSON string.

func ReadConfig

func ReadConfig(format string, data io.Reader) ViperBuilder

ReadConfig returns a ViperBuilder that reads in a configuration file from an arbitrary io.Reader.

func Yaml

func Yaml(data string) ViperBuilder

Yaml uses ReadConfig to read configuration from an in-memory YAML string.

type ViperIn

type ViperIn struct {
	fx.In

	// Name is the application (or, executable) name.  This component will be supplied if using
	// CommandLine.Provide.  If unset, DefaultApplicationName is used.  The instance of this struct
	// passed to builders will always have this field set.
	//
	// This name is frequently used to determine names of or paths to configuration files.  It is
	// passed to each builder function in Viper.Provide.
	Name ApplicationName `optional:"true"`

	// FlagSet is the optional spf13 FlagSet component.  It is passed to each builder function.
	// If supplied, this component can be used to tailor the viper instance using command-line arguments.
	FlagSet *pflag.FlagSet `optional:"true"`

	// DecoderOptions is an optional component that is a slice of spf13/viper decoder options for unmarshalling.
	// If supplied, this slice is used to create the Unmarshaller component.
	//
	// Note that spf13/viper provides a default set of options.  See https://godoc.org/github.com/spf13/viper#DecoderConfigOption
	DecoderOptions []viper.DecoderConfigOption `optional:"true"`
}

ViperIn describes the dependencies for creating an spf13 Viper instance

type ViperOut

type ViperOut struct {
	fx.Out

	Viper        *viper.Viper
	Unmarshaller Unmarshaller
}

ViperOut lists the components emitted for a Viper instance

type ViperUnmarshaller

type ViperUnmarshaller struct {
	// Viper is the required viper instance
	Viper *viper.Viper

	// Options are passed to viper for each unmarshal operation.  This field is optional.
	Options []viper.DecoderConfigOption
}

ViperUnmarshaller is an Unmarshaller backed by Viper.

func (ViperUnmarshaller) IsSet

func (vu ViperUnmarshaller) IsSet(k string) bool

func (ViperUnmarshaller) Unmarshal

func (vu ViperUnmarshaller) Unmarshal(v interface{}) error

func (ViperUnmarshaller) UnmarshalKey

func (vu ViperUnmarshaller) UnmarshalKey(k string, v interface{}) error