container

README

Cosmos SDK Dependency Injection container Module

Overview

TODO

Usage

TODO

Debugging

Issues with resolving dependencies in the container can be done with logs and Graphviz renderings of the container tree. By default, whenever there is an error, logs will be printed to stderr and a rendering of the dependency graph in Graphviz DOT format will be saved to debug_container.dot.

Here is an example Graphviz rendering of a successful build of a dependency graph:

Rectangles represent functions, ovals represent types, rounded rectangles represent modules and the single hexagon represents the function which called Build. Black-colored shapes mark functions and types that were called/resolved without an error. Gray-colored nodes mark functions and types that could have been called/resolved in the container but were left unused.

Here is an example Graphviz rendering of a dependency graph build which failed:

Graphviz DOT files can be converted into SVG's for viewing in a web browser using the dot command-line tool, ex:

> dot -Tsvg debug_container.dot > debug_container.svg

Many other tools including some IDEs support working with DOT files.

Documentation

Index

• func Build(containerConfig Config, outputs ...interface{}) error
• func BuildDebug(debugOpt DebugOption, config Config, outputs ...interface{}) error
• type Config
  • func Configs(opts ...Config) Config
  • func Error(err error) Config
  • func Provide(providers ...interface{}) Config
  • func ProvideInModule(moduleName string, providers ...interface{}) Config
  • func Supply(values ...interface{}) Config
• type DebugOption
  • func AutoDebug() DebugOption
  • func Debug() DebugOption
  • func DebugCleanup(cleanup func()) DebugOption
  • func DebugOptions(options ...DebugOption) DebugOption
  • func FileVisualizer(filename string) DebugOption
  • func LogVisualizer() DebugOption
  • func Logger(logger func(string)) DebugOption
  • func OnError(option DebugOption) DebugOption
  • func OnSuccess(option DebugOption) DebugOption
  • func StderrLogger() DebugOption
  • func StdoutLogger() DebugOption
  • func Visualizer(visualizer func(dotGraph string)) DebugOption
• type In
• type Location
  • func LocationFromCaller(skip int) Location
  • func LocationFromPC(pc uintptr) Location
• type ManyPerContainerType
• type ModuleKey
  • func (k ModuleKey) Name() string
• type OnePerModuleType
• type Out
• type OwnModuleKey
• type ProviderDescriptor
  • func ExtractProviderDescriptor(provider interface{}) (ProviderDescriptor, error)
• type ProviderInput
• type ProviderOutput

Functions

func Build

func Build(containerConfig Config, outputs ...interface{}) error

Build builds the container specified by containerConfig and extracts the requested outputs from the container or returns an error. It is the single entry point for building and running a dependency injection container. Each of the values specified as outputs must be pointers to types that can be provided by the container.

Ex:

var x int
Build(Provide(func() int { return 1 }), &x)

Build uses the debug mode provided by AutoDebug which means there will be verbose debugging information if there is an error and nothing upon success. Use BuildDebug to configure debug behavior.

func BuildDebug

func BuildDebug(debugOpt DebugOption, config Config, outputs ...interface{}) error

BuildDebug is a version of Build which takes an optional DebugOption for logging and visualization.

Types

type Config

type Config interface {
	// contains filtered or unexported methods
}

Config is a functional configuration of a container.

func Configs

func Configs(opts ...Config) Config

Configs defines a configuration which bundles together multiple Config definitions.

func Error

func Error(err error) Config

Error defines configuration which causes the dependency injection container to fail immediately.

func Provide

func Provide(providers ...interface{}) Config

Provide defines a container configuration which registers the provided dependency injection providers. Each provider will be called at most once with the exception of module-scoped providers which are called at most once per module (see ModuleKey).

func ProvideInModule

func ProvideInModule(moduleName string, providers ...interface{}) Config

ProvideInModule defines container configuration which registers the provided dependency injection providers that are to be run in the named module. Each provider will be called at most once.

func Supply

func Supply(values ...interface{}) Config

type DebugOption

type DebugOption interface {
	// contains filtered or unexported methods
}

DebugOption is a functional option for running a container that controls debug logging and visualization output.

func AutoDebug

func AutoDebug() DebugOption

AutoDebug does the same thing as Debug when there is an error and deletes the debug_container.dot if it exists when there is no error. This is the default debug mode of Run.

func Debug

func Debug() DebugOption

Debug is a default debug option which sends log output to stderr, dumps the container in the graphviz DOT and SVG formats to debug_container.dot and debug_container.svg respectively.

func DebugCleanup

func DebugCleanup(cleanup func()) DebugOption

DebugCleanup specifies a clean-up function to be called at the end of processing to clean up any resources that may be used during debugging.

func DebugOptions

func DebugOptions(options ...DebugOption) DebugOption

DebugOptions creates a debug option which bundles together other debug options.

func FileVisualizer

func FileVisualizer(filename string) DebugOption

FileVisualizer is a debug option which dumps a graphviz DOT rendering of the container to the specified file.

func LogVisualizer

func LogVisualizer() DebugOption

LogVisualizer is a debug option which dumps a graphviz DOT rendering of the container to the log.

func Logger

func Logger(logger func(string)) DebugOption

Logger creates an option which provides a logger function which will receive all log messages from the container.

func OnError

func OnError(option DebugOption) DebugOption

OnError is a debug option that allows setting debug options that are conditional on an error happening. Any loggers added error will receive the full dump of logs since the start of container processing.

func OnSuccess

func OnSuccess(option DebugOption) DebugOption

OnSuccess is a debug option that allows setting debug options that are conditional on successful container resolution. Any loggers added on success will receive the full dump of logs since the start of container processing.

func StderrLogger

func StderrLogger() DebugOption

StderrLogger is a debug option which routes logging output to stderr.

func StdoutLogger

func StdoutLogger() DebugOption

StdoutLogger is a debug option which routes logging output to stdout.

func Visualizer

func Visualizer(visualizer func(dotGraph string)) DebugOption

Visualizer creates an option which provides a visualizer function which will receive a rendering of the container in the Graphiz DOT format whenever the container finishes building or fails due to an error. The graph is color-coded to aid debugging with black representing success, red representing an error, and gray representing unused types or functions. Graph rendering should be deterministic for a given version of the container module and container options so that graphs can be used in tests.

type In

type In struct{}

In can be embedded in another struct to inform the container that the fields of the struct should be treated as dependency inputs. This allows a struct to be used to specify dependencies rather than positional parameters.

Fields of the struct may support the following tags:

optional	if set to true, the dependency is optional and will
			be set to its default value if not found, rather than causing
			an error

type Location

type Location interface {
	Name() string
	fmt.Stringer
	fmt.Formatter
	// contains filtered or unexported methods
}

func LocationFromCaller

func LocationFromCaller(skip int) Location

func LocationFromPC

func LocationFromPC(pc uintptr) Location

type ManyPerContainerType

type ManyPerContainerType interface {
	// IsManyPerContainerType is a marker function which just indicates that this is a many-per-container type.
	IsManyPerContainerType()
}

ManyPerContainerType marks a type which automatically gets grouped together. For an ManyPerContainerType T, T and []T can be declared as output parameters for providers as many times within the container as desired. All of the provided values for T can be retrieved by declaring an []T input parameter.

type ModuleKey

type ModuleKey struct {
	// contains filtered or unexported fields
}

ModuleKey is a special type used to scope a provider to a "module".

Special module-scoped providers can be used with Provide and ProvideInModule by declaring a provider with an input parameter of type ModuleKey. These providers may construct a unique value of a dependency for each module and will be called at most once per module.

When being used with ProvideInModule, the provider will not receive its own ModuleKey but rather the key of the module requesting the dependency so that modules can provide module-scoped dependencies to other modules.

In order for a module to retrieve their own module key they can define a provider which requires the OwnModuleKey type and DOES NOT require ModuleKey.

func (ModuleKey) Name

func (k ModuleKey) Name() string

type OnePerModuleType

type OnePerModuleType interface {
	// IsOnePerModuleType is a marker function just indicates that this is a one-per-module type.
	IsOnePerModuleType()
}

OnePerModuleType marks a type which can have up to one value per module. All of the values for a one-per-module type T and their respective modules, can be retrieved by declaring an input parameter map[string]T.

type Out

type Out struct{}

Out can be embedded in another struct to inform the container that the fields of the struct should be treated as dependency outputs. This allows a struct to be used to specify outputs rather than positional return values.

type OwnModuleKey

type OwnModuleKey ModuleKey

OwnModuleKey is a type which can be used in a module to retrieve its own ModuleKey. It MUST NOT be used together with a ModuleKey dependency.

type ProviderDescriptor

type ProviderDescriptor struct {
	// Inputs defines the in parameter types to Fn.
	Inputs []ProviderInput

	// Outputs defines the out parameter types to Fn.
	Outputs []ProviderOutput

	// Fn defines the provider function.
	Fn func([]reflect.Value) ([]reflect.Value, error)

	// Location defines the source code location to be used for this provider
	// in error messages.
	Location Location
}

ProviderDescriptor defines a special provider type that is defined by reflection. It should be passed as a value to the Provide function. Ex:

option.Provide(ProviderDescriptor{ ... })

func ExtractProviderDescriptor

func ExtractProviderDescriptor(provider interface{}) (ProviderDescriptor, error)

type ProviderInput

type ProviderInput struct {
	Type     reflect.Type
	Optional bool
}

type ProviderOutput

type ProviderOutput struct {
	Type reflect.Type
}