inject

inject

inject generates fx modules from comment annotations. You annotate constructors with @Provide and entry points with @Invoke; the generator reads them with the annotation package, builds the dependency graph, checks it and writes one fx module per function plus a root Module() that wires the whole application.

Annotations

index is the zero-based position of the result or parameter and is always required. A parameter without @Inject is linked to a default provider of the same type when one is annotated; otherwise the application must provide it (for example with fx.Supply or another fx module).

package greeting

// NewGreeter greets informally.
// @Provide(index=0)
func NewGreeter() *Greeter { return &Greeter{Prefix: "Hello"} }

// NewFormalGreeter greets formally.
// @Provide(name=formal, index=0)
func NewFormalGreeter() (*Greeter, error) { return &Greeter{Prefix: "Good morning"}, nil }

package app

// Announce runs on start.
// @Inject(name=formal, index=0)
// @Inject(group=names, index=2)
// @Invoke
func Announce(formal, casual *greeting.Greeter, names []string, board *Board) { ... }

Generating

Add a go:generate line to the application and run go generate:

//go:generate go run github.com/xgodev/boost/inject/cmd/inject --boost.inject.output=gen

go generate ./...

The command starts with boost.Start(), so its settings are boost config keys (flags, env vars or config files):

The output mirrors the project, the directory that holds it: each annotated function's module sits at the path of its package in the project. A package of another module mirrors its whole import path.

gen/
  module.go                                   # package gen: func Module() fx.Option
  greeting/newgreeter_module.go               # source in github.com/acme/app/greeting
  greeting/options_module.go                  # @Config struct Options
  internal/stock/new_module.go                # source in github.com/acme/app/internal/stock
  github.com/acme/lib/clock/new_module.go     # source in another module

Two renames keep the generated packages importable and apart (GenPath):

• an internal element below the first is written internal_. The generated packages import each other across gen/, and Go lets only the tree above an internal/ directory import what is in it; a leading internal/ sits right under gen/, so it stays. Under gen/implementation/ and gen/builder/middleware/ the leading one is written internal_ too (GenPathUnder).
• the first element of a package of the project gets a trailing _ when it is a directory the generators own (builder, client, implementation) or has a dot, as the first element of an import path has.

Each <func>_module.go declares <Func>Module(), an fx.Module with the modules it depends on and fx.Provide/fx.Invoke of the function, wrapped in fx.Annotate with fx.ParamTags/fx.ResultTags when names or groups are used. Every run rewrites the output and removes generated files (those starting with // Code generated by inject; DO NOT EDIT.) that are no longer produced; other files in the output directory are kept.

The application uses the root module:

func main() {
	boost.Start()

	fx.New(gen.Module()).Run()
}

Default implementation

Two or more constructors may provide the same value (same type and name, no group) when one of them is marked @Default: they form an implementation set and config chooses which one is wired. The implementation is named after its package.

package memory // example.com/app/stock/memory

// @Provide(index=0)
// @Default
func New() stock.Service { ... }

package unlimited // example.com/app/stock/unlimited

// @Provide(index=0)
func New(c *Client) stock.Service { ... }

The generator writes the switch in gen/implementation/<type import path>/<type>_implementation.go:

gen/implementation/example.com/app/stock/service_implementation.go
  ServiceImplementationModule()  // includes only the chosen implementation's module
  ServiceImplementation()        // name of the chosen implementation

• The key is the package path of the type, relative to the Go module, plus the value name, plus implementation: stock.implementation (env STOCK_IMPLEMENTATION), stock.formal.implementation for @Provide(name=formal). _ splits segments and a-b becomes aB, so the key is always reachable from an environment variable. A type outside the module uses its full import path.
• Unset, the key holds the @Default package name.
• Only the chosen implementation's module is included: the others, and what only they depend on, are never built.
• An unknown name fails the boot with an error naming the key, the value and the valid names; it never falls back to the default.
• Every consumer and the root Module() include the switch instead of the implementations. The graph still links consumers to every implementation, so cycles are found whatever the config says.

"Default implementation" (@Default) is not "default provider" (a @Provide without name): a set of named values has a default implementation too.

Config

A package that needs settings declares a struct marked @Config; the generator writes the config.Add registration and provides *Struct to the constructors that receive it. The package never imports wrapper/config.

package resty // example.com/app/internal/pkg/client/quote/resty

// @Config
type Options struct {
	BaseURL string        `default:"http://localhost" desc:"quote API base URL"`
	Timeout time.Duration `default:"2s" desc:"call timeout"`
	Token   string        `hide:"true" desc:"API token"`
}

// @Provide(index=0)
func New(o *Options) quote.Service { ... }

The generator writes gen/<import path>/options_module.go:

const optionsRoot = "internal.pkg.client.quote.resty"

func init() {
	// env INTERNAL_PKG_CLIENT_QUOTE_RESTY_BASE__URL
	config.Add(optionsRoot+".baseUrl", "http://localhost", "quote API base URL")
	// env INTERNAL_PKG_CLIENT_QUOTE_RESTY_TIMEOUT
	config.Add(optionsRoot+".timeout", 2*time.Second, "call timeout")
	// env INTERNAL_PKG_CLIENT_QUOTE_RESTY_TOKEN
	config.Add(optionsRoot+".token", "", "API token", config.WithHide())
}

func OptionsModule() fx.Option // provides *resty.Options from config.NewOptionsWithPath

• @Config takes no arguments and goes on an exported struct outside package main; at most one per package.
• Every exported field is a key, unless tagged config:"-". Supported types: string, bool, int, int8..int64, uint, uint8..uint64, float32, float64, time.Duration and []string.
• desc is required. default is optional (the zero value without it) and is parsed when generating: strconv rules for bool and numbers, time.ParseDuration for durations, a comma list for []string. hide:"true" registers a secret (config.WithHide()). config:"name" renames the key segment; it must be lowerCamel (^[a-z][a-zA-Z0-9]*$).
• The root key is the package path relative to the Go module, with the segment rules of the implementation key (its full import path outside the module). The field segment is the field's words in lowerCamel (BaseURL -> baseUrl, HTTPTimeout -> httpTimeout), which is what the env loader builds from BASE__URL: the env var of each key is written next to its config.Add.
• Values are read when the module is built, after boost.Start() loaded flags, env vars and config files; a []string env value is split by commas.

Factory clients

A parameter whose type is a client a boost factory builds, with @Inject, is built by the generator: one client per name, each with its own config and the plugins its @Inject lists. The app writes no factory module.

package resty // example.com/app/internal/pkg/client/quote/resty

// @Provide(index=0)
// @Inject(index=0, name=quote, plugins=[otel, prometheus])
func New(c *resty.Client) quote.Repository { ... }

The generator writes gen/client/<client type import path>/<name>_<type>.go (default_client.go for an @Inject without name):

const quoteClientRoot = "boost.factory.resty.clients.quote"

func init() {
	factory.ConfigAdd(quoteClientRoot)
	otelplugin.ConfigAdd(quoteClientRoot + ".plugins.otel")
	prometheusplugin.ConfigAdd(quoteClientRoot + ".plugins.prometheus")
}

func QuoteClientModule() fx.Option // provides *resty.Client `name:"quote"`

func newQuoteClient(ctx context.Context) (*resty.Client, error) {
	otel, err := otelplugin.NewOtelrestyWithConfigPath(quoteClientRoot + ".plugins.otel")
	...
	return factory.NewClientWithConfigPath(ctx, quoteClientRoot, otel.Register, prometheus.Register)
}

NATS, Pub/Sub, Bigtable, gocql and kafka clients hold connections, so their constructor also takes fx.Lifecycle and closes the client when the app stops:

func newEventsConn(ctx context.Context, lc fx.Lifecycle) (*nats.Conn, error) {
	...
	c, err := factory.NewConnWithConfigPath(ctx, eventsConnRoot, health.Plugin, log.Register)
	if err != nil {
		return nil, err
	}
	lc.Append(fx.StopHook(c.Close))
	return c, nil
}

• Name. name=x is the client x; without name it is the default client of the factory. A name is lowerCamel (^[a-z][a-zA-Z0-9]*$) so an env var reaches its keys.
• Config. The default client keeps the factory's root (boost.factory.resty.*); a named one lives under <factory root>.clients.<name> (boost.factory.resty.clients.quote.host, env BOOST_FACTORY_RESTY_CLIENTS_QUOTE_HOST) with the factory's defaults. Each plugin sits under the client (boost.factory.resty.clients.quote.plugins.otel.enabled, default true): the annotation chooses the plugins, config only turns one off.
• Shared. Consumers with the same type and name share one client. Each may list plugins only if the lists are equal; a consumer without plugins takes the client as the others declare it; no list anywhere is a client without plugins.
• The app wins. When a @Provide of the app provides the value (same type and name), it is used and nothing is generated. A client parameter without @Inject is left to the app.
• Every consumer's module and the root Module() include <Name>ClientModule(). fx builds the client only when a consumer is built, so a client of an implementation that config did not choose is never built.

Publisher

A *publisher.Publisher (github.com/xgodev/boost/wrapper/publisher) parameter with @Inject is built by the generator, with the driver one config key names. The app writes no driver module.

package boost // example.com/app/publisher/ordercreated/boost

// @Provide(index=0)
// @Inject(index=0)
func New(p *publisher.Publisher) ordercreated.Publisher { ... }

The generator writes gen/client/github.com/xgodev/boost/wrapper/publisher/publisher.go with PublisherModule(), which wires the publisher and only the chosen driver and its client:

• Choice. Env BOOST_WRAPPER_PUBLISHER_DRIVER_NAME=nats. An unknown value fails the boot with NotValid, naming the key, the value and the valid names. The key is .driver.name, not .driver: .driver holds the drivers' options.
• Clients. Each driver takes the default client of its factory, the same one an @Inject without name gets (see Factory clients): the app and the publisher share it, with the plugins the app lists. The adapter of a builder @Function shares it too (GeneratorOptions.DefaultClients).
• cgo. The kafka client binds librdkafka through cgo, so its files build only with cgo (//go:build cgo). An app built with CGO_ENABLED=0 still builds; choosing kafka there fails the boot with NotSupported.
• The app wins. When a @Provide of the app provides *publisher.Publisher, it is used and nothing is generated. A named publisher (name=x) is not built: provide it. plugins do not apply.
• The hand-written driver fx modules (fx/modules/wrapper/publisher/...) and their .enabled keys are unchanged; use them or PublisherModule(), not both.

Validation

The generator fails, without touching the output directory, when:

• index is missing, out of range or declared twice;
• a function has both @Provide and @Invoke, or @Inject without either;
• @Provide points to an error result, or uses both name and group;
• @Inject(group=...) is on a parameter that is not a slice;
• two functions provide the same value (same type and name; groups may have many providers) and none is @Default;
• @Default takes arguments, is not on a function with exactly one @Provide, is on a group, or its value has no other provider;
• an implementation set has two @Default, a member with more than one @Provide, two members in packages with the same name, members providing different types, or a type that is not named (T, *T, pkg.T, *pkg.T);
• a consumer of an implementation set lives in a member's package (the switch would import itself);
• two generated config keys (of @Config fields or implementation switches) are equal, or one is the parent of another (a.b and a.b.c);
• @Config takes arguments, is on a function, an unexported struct or in package main, is combined with another inject annotation, or appears twice in a package;
• a @Config field is embedded, has an unsupported type, lacks desc, has a default that does not parse for its type or a config name that is not lowerCamel, or is unexported and tagged;
• an @Inject parameter has no provider and is not a factory client;
• plugins is on a @Provide, on a parameter that is not a factory client or that the app provides, or with group; lists an unknown or repeated plugin; or differs between two consumers of one client;
• a client name is not lowerCamel, or two clients would be written to the same file (name=default and the unnamed client);
• the dependencies have a cycle, or a function depends on what it provides;
• an annotated function is unexported or in package main (the generated code must import it);
• the output directory is not inside the Go module.

Annotations other than @Config on structs, and annotations on methods, are ignored with a warning.

Library

The command is a thin wrapper over the package API, which can be used to build other generators or to check that the generated code is up to date:

modulePath, moduleDir, _ := inject.FindModule(".")
entries, _ := inject.CollectEntries(".")
g, _ := inject.NewGraphFromEntries(ctx, entries)
files, _ := inject.NewGenerator(g, inject.GeneratorOptions{
	ModulePath: modulePath,
	ModuleDir:  moduleDir,
	OutputDir:  outputDir, // absolute
}).Render(ctx) // or Generate(ctx) to write them

WriteGraphviz/ExportInjectGraphToGraphviz export the graph in DOT format.

Generators built on top of inject (such as builder) reuse:

See examples/simple and examples/publisher: their tests run the generated application and fail when gen/ is stale. examples/clients injects a NATS conn, a Pub/Sub client, gocql v1 and v2 sessions and a Bigtable client; its test starts the app against an embedded NATS server, the Pub/Sub emulator, a fake Cassandra node and the in-process Bigtable emulator (bttest), and checks every client is closed when the app stops.

Limitations

• Types are matched by package name and type expression, not by import path: two packages with the same name and type name are seen as the same type.
• Each generated <Func>Module() returns its options only on the first call (sync.Once), so a constructor reached by several modules is registered once. Build the fx application once per process.
• fx provides every non-error result of a constructor, whatever @Provide declares; @Provide only tells the generator which results to track.
• The scan also loads the packages imported by the scanned code, which makes a run take a few seconds on large dependency trees.