annotated.go

// Copyright (c) 2020-2021 Uber Technologies, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.

package fx

import (
	"context"
	"errors"
	"fmt"
	"reflect"
	"strings"

	"go.uber.org/dig"
	"go.uber.org/fx/internal/fxreflect"
)

// Annotated annotates a constructor provided to Fx with additional options.
//
// For example,
//
//	func NewReadOnlyConnection(...) (*Connection, error)
//
//	fx.Provide(fx.Annotated{
//	  Name: "ro",
//	  Target: NewReadOnlyConnection,
//	})
//
// Is equivalent to,
//
//	type result struct {
//	  fx.Out
//
//	  Connection *Connection `name:"ro"`
//	}
//
//	fx.Provide(func(...) (result, error) {
//	  conn, err := NewReadOnlyConnection(...)
//	  return result{Connection: conn}, err
//	})
//
// Annotated cannot be used with constructors which produce fx.Out objects.
//
// When used with fx.Supply, the target is a value rather than a constructor function.
type Annotated struct {
	// If specified, this will be used as the name for all non-error values returned
	// by the constructor. For more information on named values, see the documentation
	// for the fx.Out type.
	//
	// A name option may not be provided if a group option is provided.
	Name string

	// If specified, this will be used as the group name for all non-error values returned
	// by the constructor. For more information on value groups, see the package documentation.
	//
	// A group option may not be provided if a name option is provided.
	//
	// Similar to group tags, the group name may be followed by a `,flatten`
	// option to indicate that each element in the slice returned by the
	// constructor should be injected into the value group individually.
	Group string

	// Target is the constructor or value being annotated with fx.Annotated.
	Target interface{}
}

func (a Annotated) String() string {
	var fields []string
	if len(a.Name) > 0 {
		fields = append(fields, fmt.Sprintf("Name: %q", a.Name))
	}
	if len(a.Group) > 0 {
		fields = append(fields, fmt.Sprintf("Group: %q", a.Group))
	}
	if a.Target != nil {
		fields = append(fields, fmt.Sprintf("Target: %v", fxreflect.FuncName(a.Target)))
	}
	return fmt.Sprintf("fx.Annotated{%v}", strings.Join(fields, ", "))
}

// field used for embedding fx.Out type in generated struct.
var _outAnnotationField = reflect.StructField{
	Name:      "Out",
	Type:      reflect.TypeOf(Out{}),
	Anonymous: true,
}

// Annotation can be passed to Annotate(f interface{}, anns ...Annotation)
// for annotating the parameter and result types of a function.
type Annotation interface {
	apply(*annotated) error
}

var (
	_typeOfError reflect.Type = reflect.TypeOf((*error)(nil)).Elem()
	_nilError                 = reflect.Zero(_typeOfError)
)

// annotationError is a wrapper for an error that was encountered while
// applying annotation to a function. It contains the specific error
// that it encountered as well as the target interface that was attempted
// to be annotated.
type annotationError struct {
	target interface{}
	err    error
}

func (e *annotationError) Error() string {
	return e.err.Error()
}

type paramTagsAnnotation struct {
	tags []string
}

var _ Annotation = paramTagsAnnotation{}

// Given func(T1, T2, T3, ..., TN), this generates a type roughly
// equivalent to,
//
//   struct {
//     fx.In
//
//     Field1 T1 `$tags[0]`
//     Field2 T2 `$tags[1]`
//     ...
//     FieldN TN `$tags[N-1]`
//   }
//
// If there has already been a ParamTag that was applied, this
// will return an error.

func (pt paramTagsAnnotation) apply(ann *annotated) error {
	if len(ann.ParamTags) > 0 {
		return errors.New("cannot apply more than one line of ParamTags")
	}
	ann.ParamTags = pt.tags
	return nil
}

// ParamTags is an Annotation that annotates the parameter(s) of a function.
// When multiple tags are specified, each tag is mapped to the corresponding
// positional parameter.
func ParamTags(tags ...string) Annotation {
	return paramTagsAnnotation{tags}
}

type resultTagsAnnotation struct {
	tags []string
}

var _ Annotation = resultTagsAnnotation{}

// Given func(T1, T2, T3, ..., TN), this generates a type roughly
// equivalent to,
//
//	struct {
//	  fx.Out
//
//	  Field1 T1 `$tags[0]`
//	  Field2 T2 `$tags[1]`
//	  ...
//	  FieldN TN `$tags[N-1]`
//	}
//
// If there has already been a ResultTag that was applied, this
// will return an error.
func (rt resultTagsAnnotation) apply(ann *annotated) error {
	if len(ann.ResultTags) > 0 {
		return errors.New("cannot apply more than one line of ResultTags")
	}
	ann.ResultTags = rt.tags
	return nil
}

// ResultTags is an Annotation that annotates the result(s) of a function.
// When multiple tags are specified, each tag is mapped to the corresponding
// positional result.
func ResultTags(tags ...string) Annotation {
	return resultTagsAnnotation{tags}
}

type _lifecycleHookAnnotationType int

const (
	_unknownHookType _lifecycleHookAnnotationType = iota
	_onStartHookType
	_onStopHookType
)

type lifecycleHookAnnotation struct {
	Type   _lifecycleHookAnnotationType
	Target interface{}
}

var _ Annotation = (*lifecycleHookAnnotation)(nil)

func (la *lifecycleHookAnnotation) String() string {
	name := "UnknownHookAnnotation"
	switch la.Type {
	case _onStartHookType:
		name = _onStartHook
	case _onStopHookType:
		name = _onStopHook
	}
	return name
}

func (la *lifecycleHookAnnotation) apply(ann *annotated) error {
	if la.Target == nil {
		return fmt.Errorf(
			"cannot use nil function for %q hook annotation",
			la,
		)
	}

	for _, h := range ann.Hooks {
		if la.Type == h.Type {
			return fmt.Errorf(
				"cannot apply more than one %q hook annotation",
				la,
			)
		}
	}

	ft := reflect.TypeOf(la.Target)

	if ft.Kind() != reflect.Func {
		return fmt.Errorf(
			"must provide function for %q hook, got %v (%T)",
			la,
			la.Target,
			la.Target,
		)
	}

	if ft.NumIn() < 1 || ft.In(0) != _typeOfContext {
		return fmt.Errorf(
			"first argument of hook must be context.Context, got %v (%T)",
			la.Target,
			la.Target,
		)
	}

	hasOut := ft.NumOut() == 1
	returnsErr := hasOut && ft.Out(0) == _typeOfError

	if !hasOut || !returnsErr {
		return fmt.Errorf(
			"hooks must return only an error type, got %v (%T)",
			la.Target,
			la.Target,
		)
	}

	if ft.IsVariadic() {
		return fmt.Errorf(
			"hooks must not accept variatic parameters, got %v (%T)",
			la.Target,
			la.Target,
		)
	}

	ann.Hooks = append(ann.Hooks, la)
	return nil
}

var (
	_typeOfLifecycle reflect.Type = reflect.TypeOf((*Lifecycle)(nil)).Elem()
	_typeOfContext   reflect.Type = reflect.TypeOf((*context.Context)(nil)).Elem()
)

type valueResolver func(reflect.Value, int) reflect.Value

func (la *lifecycleHookAnnotation) resolveMap(results []reflect.Type) (
	resultMap map[reflect.Type]valueResolver,
) {
	// index the constructor results by type and position to allow
	// for us to omit these from the in types that must be injected,
	// and to allow us to interleave constructor results
	// into our hook arguments.
	resultMap = make(map[reflect.Type]valueResolver, len(results))

	for _, r := range results {
		resultMap[r] = func(v reflect.Value, pos int) (value reflect.Value) {
			return v
		}
	}

	return
}

func (la *lifecycleHookAnnotation) resolveLifecycleParamField(
	param reflect.Value,
	n int,
) (
	value reflect.Value,
) {
	if param.Kind() == reflect.Struct {
		if n <= param.NumField() {
			value = param.FieldByName(fmt.Sprintf("Field%d", n))
		}
	}

	return value
}

func (la *lifecycleHookAnnotation) parameters(results ...reflect.Type) (
	in reflect.Type,
	argmap func(
		args []reflect.Value,
	) (Lifecycle, []reflect.Value),
) {
	resultMap := la.resolveMap(results)

	// hook functions require a lifecycle, and it should be injected
	params := []reflect.StructField{
		{
			Name:      "In",
			Type:      _typeOfIn,
			Anonymous: true,
		},
		{
			Name: "Lifecycle",
			Type: _typeOfLifecycle,
		},
	}

	type argSource struct {
		pos     int
		result  bool
		resolve valueResolver
	}

	ft := reflect.TypeOf(la.Target)
	resolverIdx := make([]argSource, 1)

	for i := 1; i < ft.NumIn(); i++ {
		t := ft.In(i)
		result, isProvidedByResults := resultMap[t]

		if isProvidedByResults {
			resolverIdx = append(resolverIdx, argSource{
				pos:     i,
				result:  true,
				resolve: result,
			})
			continue
		}

		field := reflect.StructField{
			Name: fmt.Sprintf("Field%d", i),
			Type: t,
		}
		params = append(params, field)

		resolverIdx = append(resolverIdx, argSource{
			pos:     i,
			resolve: la.resolveLifecycleParamField,
		})
	}

	in = reflect.StructOf(params)

	argmap = func(
		args []reflect.Value,
	) (lc Lifecycle, remapped []reflect.Value) {
		remapped = make([]reflect.Value, ft.NumIn())

		if len(args) != 0 {
			var (
				results reflect.Value
				p       = args[0]
			)

			if len(args) > 1 {
				results = args[1]
			}

			lc, _ = p.FieldByName("Lifecycle").Interface().(Lifecycle)
			for i := 1; i < ft.NumIn(); i++ {
				resolver := resolverIdx[i]
				source := p
				if resolver.result {
					source = results
				}
				remapped[i] = resolver.resolve(source, i)
			}
		}
		return
	}
	return
}

func (la *lifecycleHookAnnotation) buildHook(fn func(context.Context) error) (hook Hook) {
	switch la.Type {
	case _onStartHookType:
		hook.OnStart = fn
	case _onStopHookType:
		hook.OnStop = fn
	}

	return
}

func (la *lifecycleHookAnnotation) Build(results ...reflect.Type) reflect.Value {
	in, paramMap := la.parameters(results...)
	params := []reflect.Type{in}
	for _, r := range results {
		if r != _typeOfError {
			params = append(params, r)
		}
	}

	origFn := reflect.ValueOf(la.Target)
	newFnType := reflect.FuncOf(params, nil, false)
	newFn := reflect.MakeFunc(newFnType, func(args []reflect.Value) []reflect.Value {
		var lc Lifecycle
		lc, args = paramMap(args)
		hookFn := func(ctx context.Context) (err error) {
			args[0] = reflect.ValueOf(ctx)

			results := origFn.Call(args)
			if len(results) > 0 && results[0].Type() == _typeOfError {
				err, _ = results[0].Interface().(error)
			}

			return
		}

		lc.Append(la.buildHook(hookFn))
		return []reflect.Value{}
	})

	return newFn
}

// OnStart is an Annotation that appends an OnStart Hook to the application
// Lifecycle when that function is called. This provides a way to create
// Lifecycle OnStart (see Lifecycle type documentation) hooks without building a
// function that takes a dependency on the Lifecycle type.
//
//	fx.Annotate(
//	  NewServer,
//	  fx.OnStart(func(ctx context.Context, server Server) error {
//	      return server.Listen(ctx)
//	  }),
//	)
//
// Which is functionally the same as:
//
//	 fx.Provide(
//	   func(lifecycle fx.Lifecycle, p Params) Server {
//	     server := NewServer(p)
//	     lifecycle.Append(fx.Hook{
//		      OnStart: func(ctx context.Context) error {
//			    return server.Listen(ctx)
//		      },
//	     })
//	   }
//	 )
//
// Only one OnStart annotation may be applied to a given function at a time,
// however functions may be annotated with other types of lifecylce Hooks, such
// as OnStop.
func OnStart(onStart interface{}) Annotation {
	return &lifecycleHookAnnotation{
		Type:   _onStartHookType,
		Target: onStart,
	}
}

// OnStop is an Annotation that appends an OnStop Hook to the application
// Lifecycle when that function is called. This provides a way to create
// Lifecycle OnStop (see Lifecycle type documentation) hooks without building a
// function that takes a dependency on the Lifecycle type.
//
//	fx.Annotate(
//	  NewServer,
//	  fx.OnStop(func(ctx context.Context, server Server) error {
//	      return server.Shutdown(ctx)
//	  }),
//	)
//
// Which is functionally the same as:
//
//	 fx.Provide(
//	   func(lifecycle fx.Lifecycle, p Params) Server {
//	     server := NewServer(p)
//	     lifecycle.Append(fx.Hook{
//		      OnStart: func(ctx context.Context) error {
//			    return server.Shutdown(ctx)
//		      },
//	     })
//	   }
//	 )
//
// Only one OnStop annotation may be applied to a given function at a time,
// however functions may be annotated with other types of lifecylce Hooks, such
// as OnStart.
func OnStop(onStop interface{}) Annotation {
	return &lifecycleHookAnnotation{
		Type:   _onStopHookType,
		Target: onStop,
	}
}

type asAnnotation struct {
	targets []interface{}
}

var _ Annotation = asAnnotation{}

// As is an Annotation that annotates the result of a function (i.e. a
// constructor) to be provided as another interface.
//
// For example, the following code specifies that the return type of
// bytes.NewBuffer (bytes.Buffer) should be provided as io.Writer type:
//
//	fx.Provide(
//	  fx.Annotate(bytes.NewBuffer(...), fx.As(new(io.Writer)))
//	)
//
// In other words, the code above is equivalent to:
//
//	fx.Provide(func() io.Writer {
//	  return bytes.NewBuffer()
//	  // provides io.Writer instead of *bytes.Buffer
//	})
//
// Note that the bytes.Buffer type is provided as an io.Writer type, so this
// constructor does NOT provide both bytes.Buffer and io.Writer type; it just
// provides io.Writer type.
//
// When multiple values are returned by the annotated function, each type
// gets mapped to corresponding positional result of the annotated function.
//
// For example,
//
//	func a() (bytes.Buffer, bytes.Buffer) {
//	  ...
//	}
//	fx.Provide(
//	  fx.Annotate(a, fx.As(new(io.Writer), new(io.Reader)))
//	)
//
// Is equivalent to,
//
//	fx.Provide(func() (io.Writer, io.Reader) {
//	  w, r := a()
//	  return w, r
//	}
func As(interfaces ...interface{}) Annotation {
	return asAnnotation{interfaces}
}

func (at asAnnotation) apply(ann *annotated) error {
	types := make([]reflect.Type, len(at.targets))
	for i, typ := range at.targets {
		t := reflect.TypeOf(typ)
		if t.Kind() != reflect.Ptr || t.Elem().Kind() != reflect.Interface {
			return fmt.Errorf("fx.As: argument must be a pointer to an interface: got %v", t)
		}
		t = t.Elem()
		types[i] = t
	}

	ann.As = append(ann.As, types)
	return nil
}

type annotated struct {
	Target     interface{}
	ParamTags  []string
	ResultTags []string
	As         [][]reflect.Type
	FuncPtr    uintptr
	Hooks      []*lifecycleHookAnnotation
}

func (ann annotated) String() string {
	var sb strings.Builder
	sb.WriteString("fx.Annotate(")
	sb.WriteString(fxreflect.FuncName(ann.Target))
	if tags := ann.ParamTags; len(tags) > 0 {
		fmt.Fprintf(&sb, ", fx.ParamTags(%q)", tags)
	}
	if tags := ann.ResultTags; len(tags) > 0 {
		fmt.Fprintf(&sb, ", fx.ResultTags(%q)", tags)
	}
	if as := ann.As; len(as) > 0 {
		fmt.Fprintf(&sb, ", fx.As(%v)", as)
	}
	return sb.String()
}

// Build builds and returns a constructor based on fx.In/fx.Out params and
// results wrapping the original constructor passed to fx.Annotate.
func (ann *annotated) Build() (interface{}, error) {
	ft := reflect.TypeOf(ann.Target)
	if ft.Kind() != reflect.Func {
		return nil, fmt.Errorf("must provide constructor function, got %v (%T)", ann.Target, ann.Target)
	}

	if err := ann.typeCheckOrigFn(); err != nil {
		return nil, fmt.Errorf("invalid annotation function %T: %w", ann.Target, err)
	}

	resultTypes, remapResults, err := ann.results()
	if err != nil {
		return nil, err
	}
	paramTypes, remapParams, hookParams := ann.parameters(resultTypes...)

	hookFns := make([]reflect.Value, len(ann.Hooks))
	for i, builder := range ann.Hooks {
		if hookFn := builder.Build(resultTypes...); !hookFn.IsZero() {
			hookFns[i] = hookFn
		}
	}

	newFnType := reflect.FuncOf(paramTypes, resultTypes, false)
	origFn := reflect.ValueOf(ann.Target)
	ann.FuncPtr = origFn.Pointer()

	newFn := reflect.MakeFunc(newFnType, func(args []reflect.Value) []reflect.Value {
		origArgs := make([]reflect.Value, len(args))
		copy(origArgs, args)
		args = remapParams(args)
		var results []reflect.Value
		if ft.IsVariadic() {
			results = origFn.CallSlice(args)
		} else {
			results = origFn.Call(args)
		}
		results = remapResults(results)

		// if the number of results is greater than zero and the final result
		// is a non-nil error, do not execute hook installers
		hasErrorResult := len(results) > 0 && results[len(results)-1].Type() == _typeOfError
		if hasErrorResult {
			if err, ok := results[len(results)-1].Interface().(error); ok && err != nil {
				return results
			}
		}

		for i, hookFn := range hookFns {
			hookArgs := hookParams(i, origArgs, results)
			hookFn.Call(hookArgs)
		}

		return results
	})

	return newFn.Interface(), nil
}

// checks whether the target function is either
// returning an fx.Out struct or an taking in a
// fx.In struct as a parameter.
func (ann *annotated) typeCheckOrigFn() error {
	ft := reflect.TypeOf(ann.Target)
	for i := 0; i < ft.NumOut(); i++ {
		ot := ft.Out(i)
		if ot.Kind() != reflect.Struct {
			continue
		}
		if dig.IsOut(reflect.New(ft.Out(i)).Elem().Interface()) {
			return errors.New("fx.Out structs cannot be annotated")
		}
	}

	for i := 0; i < ft.NumIn(); i++ {
		it := ft.In(i)
		if it.Kind() != reflect.Struct {
			continue
		}
		if dig.IsIn(reflect.New(ft.In(i)).Elem().Interface()) {
			return errors.New("fx.In structs cannot be annotated")
		}
	}
	return nil
}

// parameters returns the type for the parameters of the annotated function,
// and a function that maps the arguments of the annotated function
// back to the arguments of the target function and a function that maps
// values to any lifecycle hook annotations. It accepts a variactic set
// of reflect.Type which allows for omitting any resulting constructor types
// from required parameters for annotation hooks.
func (ann *annotated) parameters(results ...reflect.Type) (
	types []reflect.Type,
	remap func([]reflect.Value) []reflect.Value,
	hookValueMap func(int, []reflect.Value, []reflect.Value) []reflect.Value,
) {
	ft := reflect.TypeOf(ann.Target)

	types = make([]reflect.Type, ft.NumIn())
	for i := 0; i < ft.NumIn(); i++ {
		types[i] = ft.In(i)
	}

	// No parameter annotations. Return the original types
	// and an identity function.
	if len(ann.ParamTags) == 0 && !ft.IsVariadic() && len(ann.Hooks) == 0 {
		return types, func(args []reflect.Value) []reflect.Value {
			return args
		}, nil
	}

	// Turn parameters into an fx.In struct.
	inFields := []reflect.StructField{
		{
			Name:      "In",
			Type:      reflect.TypeOf(In{}),
			Anonymous: true,
		},
	}

	for i, t := range types {
		field := reflect.StructField{
			Name: fmt.Sprintf("Field%d", i),
			Type: t,
		}

		if i < len(ann.ParamTags) {
			field.Tag = reflect.StructTag(ann.ParamTags[i])
		} else if i == ft.NumIn()-1 && ft.IsVariadic() {
			// If a variadic argument is unannotated, mark it optional,
			// so that just wrapping a function in fx.Annotate does not
			// suddenly introduce a required []arg dependency.
			field.Tag = reflect.StructTag(`optional:"true"`)
		}

		inFields = append(inFields, field)
	}

	// append required types for hooks to types field, but do not
	// include them as params in constructor call
	for i, t := range ann.Hooks {
		params, _ := t.parameters(results...)
		field := reflect.StructField{
			Name: fmt.Sprintf("Hook%d", i),
			Type: params,
		}
		inFields = append(inFields, field)
	}

	types = []reflect.Type{reflect.StructOf(inFields)}
	remap = func(args []reflect.Value) []reflect.Value {
		params := args[0]
		args = args[:0]
		for i := 0; i < ft.NumIn(); i++ {
			args = append(args, params.Field(i+1))
		}
		return args
	}

	hookValueMap = func(hook int, args []reflect.Value, results []reflect.Value) (out []reflect.Value) {
		params := args[0]
		if params.Kind() == reflect.Struct {
			var zero reflect.Value
			value := params.FieldByName(fmt.Sprintf("Hook%d", hook))

			if value != zero {
				out = append(out, value)
			}
		}
		for _, r := range results {
			if r.Type() != _typeOfError {
				out = append(out, r)
			}
		}
		return
	}
	return
}

// results returns the types of the results of the annotated function,
// and a function that maps the results of the target function,
// into a result compatible with the annotated function.
func (ann *annotated) results() (
	types []reflect.Type,
	remap func([]reflect.Value) []reflect.Value,
	err error,
) {
	ft := reflect.TypeOf(ann.Target)
	types = make([]reflect.Type, ft.NumOut())

	for i := 0; i < ft.NumOut(); i++ {
		types[i] = ft.Out(i)
	}

	// No result annotations. Return the original types
	// and an identity function.
	if len(ann.ResultTags) == 0 && len(ann.As) == 0 {
		return types, func(results []reflect.Value) []reflect.Value {
			return results
		}, nil
	}

	numStructs := 1
	if len(ann.As) > 0 {
		numStructs = len(ann.As)
	}

	type outStructInfo struct {
		Fields  []reflect.StructField // fields of the struct
		Offsets []int                 // Offsets[i] is the index of result i in Fields
	}

	outs := make([]outStructInfo, numStructs)

	for i := 0; i < numStructs; i++ {
		outs[i].Fields = []reflect.StructField{
			{
				Name:      "Out",
				Type:      reflect.TypeOf(Out{}),
				Anonymous: true,
			},
		}
		outs[i].Offsets = make([]int, len(types))
	}

	var hasError bool

	for i, t := range types {
		if t == _typeOfError {
			// Guarantee that:
			// - only the last result is an error
			// - there is at most one error result
			if i != len(types)-1 {
				return nil, nil, fmt.Errorf(
					"only the last result can be an error: "+
						"%v (%v) returns error as result %d",
					fxreflect.FuncName(ann.Target), ft, i)
			}
			hasError = true
			continue
		}

		for j := 0; j < numStructs; j++ {
			field := reflect.StructField{
				Name: fmt.Sprintf("Field%d", i),
				Type: t,
			}

			if len(ann.As) > 0 && i < len(ann.As[j]) {
				if !t.Implements(ann.As[j][i]) {
					return nil, nil, fmt.Errorf("invalid fx.As: %v does not implement %v", t, ann.As[i])
				}
				field.Type = ann.As[j][i]
			}
			if i < len(ann.ResultTags) {
				field.Tag = reflect.StructTag(ann.ResultTags[i])
			}
			outs[j].Offsets[i] = len(outs[j].Fields)
			outs[j].Fields = append(outs[j].Fields, field)
		}
	}

	var resTypes []reflect.Type
	for _, out := range outs {
		resTypes = append(resTypes, reflect.StructOf(out.Fields))
	}

	outTypes := resTypes
	if hasError {
		outTypes = append(resTypes, _typeOfError)
	}

	return outTypes, func(results []reflect.Value) []reflect.Value {
		var (
			outErr     error
			outResults []reflect.Value
		)

		for _, resType := range resTypes {
			outResults = append(outResults, reflect.New(resType).Elem())
		}

		for i, r := range results {
			if i == len(results)-1 && hasError {
				// If hasError and this is the last item,
				// we are guaranteed that this is an error
				// object.
				if err, _ := r.Interface().(error); err != nil {
					outErr = err
				}
				continue
			}
			for j := range resTypes {
				if fieldIdx := outs[j].Offsets[i]; fieldIdx > 0 {
					// fieldIdx 0 is an invalid index
					// because it refers to uninitialized
					// outs and would point to fx.Out in the
					// struct definition. We need to check this
					// to prevent panic from setting fx.Out to
					// a value.
					outResults[j].Field(fieldIdx).Set(r)
				}
			}
		}

		if hasError {
			if outErr != nil {
				outResults = append(outResults, reflect.ValueOf(outErr))
			} else {
				outResults = append(outResults, _nilError)
			}
		}

		return outResults
	}, nil
}

// Annotate lets you annotate a function's parameters and returns
// without you having to declare separate struct definitions for them.
//
// For example,
//
//	func NewGateway(ro, rw *db.Conn) *Gateway { ... }
//	fx.Provide(
//	  fx.Annotate(
//	    NewGateway,
//	    fx.ParamTags(`name:"ro" optional:"true"`, `name:"rw"`),
//	    fx.ResultTags(`name:"foo"`),
//	  ),
//	)
//
// Is equivalent to,
//
//	type params struct {
//	  fx.In
//
//	  RO *db.Conn `name:"ro" optional:"true"`
//	  RW *db.Conn `name:"rw"`
//	}
//
//	type result struct {
//	  fx.Out
//
//	  GW *Gateway `name:"foo"`
//	}
//
//	fx.Provide(func(p params) result {
//	   return result{GW: NewGateway(p.RO, p.RW)}
//	})
//
// Annotate cannot be used on functions that takes in or returns
// [In] or [Out] structs.
//
// Using the same annotation multiple times is invalid.
// For example, the following will fail with an error:
//
//	fx.Provide(
//	  fx.Annotate(
//	    NewGateWay,
//	    fx.ParamTags(`name:"ro" optional:"true"`),
//	    fx.ParamTags(`name:"rw"), // ERROR: ParamTags was already used above
//	    fx.ResultTags(`name:"foo"`)
//	  )
//	)
//
// is considered an invalid usage and will not apply any of the
// Annotations to NewGateway.
//
// If more tags are given than the number of parameters/results, only
// the ones up to the number of parameters/results will be applied.
//
// # Variadic functions
//
// If the provided function is variadic, Annotate treats its parameter as a
// slice. For example,
//
//	fx.Annotate(func(w io.Writer, rs ...io.Reader) {
//	  // ...
//	}, ...)
//
// Is equivalent to,
//
//	fx.Annotate(func(w io.Writer, rs []io.Reader) {
//	  // ...
//	}, ...)
//
// You can use variadic parameters with Fx's value groups.
// For example,
//
//	fx.Annotate(func(mux *http.ServeMux, handlers ...http.Handler) {
//	  // ...
//	}, fx.ParamTags(``, `group:"server"`))
//
// If we provide the above to the application,
// any constructor in the Fx application can inject its HTTP handlers
// by using fx.Annotate, fx.Annotated, or fx.Out.
//
//	fx.Annotate(
//	  func(..) http.Handler { ... },
//	  fx.ResultTags(`group:"server"`),
//	)
//
//	fx.Annotated{
//	  Target: func(..) http.Handler { ... },
//	  Group:  "server",
//	}
func Annotate(t interface{}, anns ...Annotation) interface{} {
	result := annotated{Target: t}
	for _, ann := range anns {
		if err := ann.apply(&result); err != nil {
			return annotationError{
				target: t,
				err:    err,
			}
		}
	}
	return result
}