wire

README

Wire: Automated Initialization in Go

Wire is a code generation tool that automates connecting components using dependency injection. Dependencies between components are represented in Wire as function parameters, encouraging explicit initialization instead of global variables. Because Wire operates without runtime state or reflection, code written to be used with Wire is useful even for hand-written initialization.

Installing

Install Wire by running:

go get github.com/google/go-cloud/wire/cmd/wire

Basics

Wire has two core concepts: providers and injectors.

Defining Providers

The primary mechanism in Wire is the provider: a function that can produce a value. These functions are ordinary Go code.

package foobarbaz

type Foo struct {
	X int
}

// ProvideFoo returns a Foo.
func ProvideFoo() Foo {
	return Foo{X: 42}
}

Provider functions must be exported in order to be used from other packages, just like ordinary functions.

Providers can specify dependencies with parameters:

package foobarbaz

// ...

type Bar struct {
	X int
}

// ProvideBar returns a Bar: a negative Foo.
func ProvideBar(foo Foo) Bar {
	return Bar{X: -foo.X}
}

Providers can also return errors:

package foobarbaz

import (
	"context"
	"errors"
)

// ...

type Baz struct {
	X int
}

// ProvideBaz returns a value if Bar is not zero.
func ProvideBaz(ctx context.Context, bar Bar) (Baz, error) {
	if bar.X == 0 {
		return Baz{}, errors.New("cannot provide baz when bar is zero")
	}
	return Baz{X: bar.X}, nil
}

Providers can be grouped into provider sets. This is useful if several providers will frequently be used together. To add these providers to a new set called SuperSet, use the wire.NewSet function:

package foobarbaz

import (
	// ...
	"github.com/google/go-cloud/wire"
)

// ...

var SuperSet = wire.NewSet(ProvideFoo, ProvideBar, ProvideBaz)

You can also add other provider sets into a provider set.

package foobarbaz

import (
	// ...
	"example.com/some/other/pkg"
)

// ...

var MegaSet = wire.NewSet(SuperSet, pkg.OtherSet)

Injectors

An application wires up these providers with an injector: a function that calls providers in dependency order. With Wire, you write the injector's signature, then Wire generates the function's body.

An injector is declared by writing a function declaration whose body is a call to wire.Build. The return values don't matter as long as they are of the correct type. The values themselves will be ignored in the generated code. Let's say that the above providers were defined in a package called example.com/foobarbaz. The following would declare an injector to obtain a Baz:

// +build wireinject
// The build tag makes sure the stub is not built in the final build.

package main

import (
	"context"

	"github.com/google/go-cloud/wire"
	"example.com/foobarbaz"
)

func initializeBaz(ctx context.Context) (foobarbaz.Baz, error) {
	wire.Build(foobarbaz.MegaSet)
	return foobarbaz.Baz{}, nil
}

Like providers, injectors can be parameterized on inputs (which then get sent to providers) and can return errors. Arguments to wire.Build are the same as wire.NewSet: they form a provider set. This is the provider set that gets used during code generation for that injector.

Any non-injector declarations found in a file with injectors will be copied into the generated file.

You can generate the injector by invoking Wire in the package directory:

wire

Wire will produce an implementation of the injector in a file called wire_gen.go that looks something like this:

// Code generated by Wire. DO NOT EDIT.

//go:generate wire
//+build !wireinject

package main

import (
	"example.com/foobarbaz"
)

func initializeBaz(ctx context.Context) (foobarbaz.Baz, error) {
	foo := foobarbaz.ProvideFoo()
	bar := foobarbaz.ProvideBar(foo)
	baz, err := foobarbaz.ProvideBaz(ctx, bar)
	if err != nil {
		return 0, err
	}
	return baz, nil
}

As you can see, the output is very close to what a developer would write themselves. Further, there is little dependency on Wire at runtime: all of the written code is just normal Go code, and can be used without Wire.

Once wire_gen.go is created, you can regenerate it by running go generate.

Advanced Features

The following features all build on top of the concepts of providers and injectors.

Binding Interfaces

Frequently, dependency injection is used to bind a concrete implementation for an interface. Wire matches inputs to outputs via type identity, so the inclination might be to create a provider that returns an interface type. However, this would not be idiomatic, since the Go best practice is to return concrete types. Instead, you can declare an interface binding in a provider set:

type Fooer interface {
	Foo() string
}

type Bar string

func (b *Bar) Foo() string {
	return string(*b)
}

func ProvideBar() *Bar {
	b := new(Bar)
	*b = "Hello, World!"
	return b
}

var BarFooer = wire.NewSet(
	ProvideBar,
	wire.Bind(new(Fooer), new(Bar)))

The first argument to wire.Bind is a pointer to a value of the desired interface type and the second argument is a zero value of the concrete type. Any set that includes an interface binding must also have a provider in the same set that provides the concrete type.

Struct Providers

Structs can also be marked as providers. Instead of calling a function, an injector will fill in each field using the corresponding provider. For a given struct type S, this would provide both S and *S. For example, given the following providers:

type Foo int
type Bar int

func ProvideFoo() Foo {
	// ...
}

func ProvideBar() Bar {
	// ...
}

type FooBar struct {
	Foo Foo
	Bar Bar
}

var Set = wire.NewSet(
	ProvideFoo,
	ProvideBar,
	FooBar{})

A generated injector for FooBar would look like this:

func injectFooBar() FooBar {
	foo := ProvideFoo()
	bar := ProvideBar()
	fooBar := FooBar{
		Foo: foo,
		Bar: bar,
	}
	return fooBar
}

And similarly if the injector needed a *FooBar.

Binding Values

Occasionally, it is useful to bind a basic value (usually nil) to a type. Instead of having injectors depend on a throwaway provider function, you can add a value expression to a provider set.

type Foo struct {
	X int
}

func injectFoo() Foo {
	wire.Build(wire.Value(Foo{X: 42}))
	return Foo{}
}

The generated injector would look like this:

func injectFoo() Foo {
	foo := Foo{X: 42}
	return foo
}

It's important to note that the expression will be copied to the injector's package; references to variables will be evaluated during the injector package's initialization. Wire will emit an error if the expression calls any functions or receives from any channels.

For interface values, use InterfaceValue:

func injectReader() io.Reader {
	wire.Build(wire.InterfaceValue(new(io.Reader), os.Stdin))
	return Foo{}
}

Cleanup functions

If a provider creates a value that needs to be cleaned up (e.g. closing a file), then it can return a closure to clean up the resource. The injector will use this to either return an aggregated cleanup function to the caller or to clean up the resource if a provider called later in the injector's implementation returns an error.

func provideFile(log Logger, path Path) (*os.File, func(), error) {
	f, err := os.Open(string(path))
	if err != nil {
		return nil, nil, err
	}
	cleanup := func() {
		if err := f.Close(); err != nil {
			log.Log(err)
		}
	}
	return f, cleanup, nil
}

A cleanup function is guaranteed to be called before the cleanup function of any of the provider's inputs and must have the signature func().

Alternate Injector Syntax

If you grow weary of writing return foobarbaz.Foo{}, nil at the end of your injector function declaration, you can instead write it more concisely with a panic:

func injectFoo() Foo {
	panic(wire.Build(/* ... */))
}

Best Practices

The following are practices we recommend for using Wire. This list will grow over time.

Distinguishing Types

If you need to inject a common type like string, create a new string type to avoid conflicts with other providers. For example:

type MySQLConnectionString string

Options Structs

A provider function that includes many dependencies can pair the function with an options struct.

type Options struct {
	// Messages is the set of recommended greetings.
	Messages []Message
	// Writer is the location to send greetings. nil goes to stdout.
	Writer io.Writer
}

func NewGreeter(ctx context.Context, opts *Options) (*Greeter, error) {
	// ...
}

var GreeterSet = wire.NewSet(Options{}, NewGreeter)

Evolving Provider Sets

When creating a provider set for use in a library, the only changes you can make without breaking compatibility are:

• Change which provider a provider set uses to provide a specific output, as long as it does not introduce a new input to the provider set. It may remove inputs. However, note that existing injectors will use the old provider until they are regenerated.
• Introduce a new output type into the provider set, but only if the type itself is newly added. If the type is not new, it is possible that some injector already has the output type included, which would cause a conflict.

All other changes are not safe. This includes:

• Requiring a new input in the provider set.
• Removing an output type from a provider set.
• Adding an existing output type into the provider set.

Instead of making one of these breaking changes, consider adding a new provider set.

As an example, if you have a provider set like this:

var GreeterSet = wire.NewSet(NewStdoutGreeter)

func DefaultGreeter(ctx context.Context) *Greeter {
	// ...
}

func NewStdoutGreeter(ctx context.Context, msgs []Message) *Greeter {
	// ...
}

func NewGreeter(ctx context.Context, w io.Writer, msgs []Message) (*Greeter, error) {
	// ...
}

You may:

• Use DefaultGreeter instead of NewStdoutGreeter in GreeterSet.
• Create a new type T and add a provider for T to GreeterSet, as long as T is introduced in the same commit/release as the provider is added.

You may not:

• Use NewGreeter instead of NewStdoutGreeter in GreeterSet. This both adds an input type (io.Writer) and requires injectors to return an error where the provider of *Greeter did not require this before.
• Remove NewStdoutGreeter from GreeterSet. Injectors depending on *Greeter will be broken.
• Add a provider for io.Writer to GreeterSet. Injectors might already have a provider for io.Writer which might conflict with this one.

Documentation

Overview

Package wire contains directives for Wire code generation.

Index

• func Build(...interface{}) string
• type Binding
  • func Bind(iface, to interface{}) Binding
• type ProvidedValue
  • func InterfaceValue(typ interface{}, x interface{}) ProvidedValue
  • func Value(interface{}) ProvidedValue
• type ProviderSet
  • func NewSet(...interface{}) ProviderSet

Functions

func Build

func Build(...interface{}) string

Build is placed in the body of an injector function to declare the providers to use. Its arguments are the same as NewSet. Its return value is an error message that can be sent to panic.

Examples:

func injector(ctx context.Context) (*sql.DB, error) {
	wire.Build(otherpkg.FooSet, myProviderFunc)
	return nil, nil
}

func injector(ctx context.Context) (*sql.DB, error) {
	panic(wire.Build(otherpkg.FooSet, myProviderFunc))
}

Types

type Binding

type Binding struct{}

A Binding maps an interface to a concrete type.

func Bind

func Bind(iface, to interface{}) Binding

Bind declares that a concrete type should be used to satisfy a dependency on the type of iface, which must be a pointer to an interface type.

Example:

type Fooer interface {
	Foo()
}

type MyFoo struct{}

func (MyFoo) Foo() {}

var MySet = wire.NewSet(
	MyFoo{},
	wire.Bind(new(Fooer), new(MyFoo)))

type ProvidedValue

type ProvidedValue struct{}

A ProvidedValue is an expression that is copied to the generated injector.

func InterfaceValue

func InterfaceValue(typ interface{}, x interface{}) ProvidedValue

InterfaceValue binds an expression to provide a specific interface type.

Example:

var MySet = wire.NewSet(wire.InterfaceValue(new(io.Reader), os.Stdin))

func Value

func Value(interface{}) ProvidedValue

Value binds an expression to provide the type of the expression. The expression may not be an interface value; use InterfaceValue for that.

Example:

var MySet = wire.NewSet(wire.Value([]string(nil)))

type ProviderSet

type ProviderSet struct{}

ProviderSet is a marker type that collects a group of providers.

func NewSet

func NewSet(...interface{}) ProviderSet

NewSet creates a new provider set that includes the providers in its arguments. Each argument is either an exported function value, an exported struct (zero) value, a provider set, a call to Bind, a a call to Value, or a call to InterfaceValue.