callbacks.go

package kong

import (
	"fmt"
	"reflect"
	"runtime"
	"strings"
)

// binding is a single binding registered with Kong.
type binding struct {
	// fn is a function that returns a value of the target type.
	fn reflect.Value

	// val is a value of the target type.
	// Must be set if done and singleton are true.
	val reflect.Value

	// singleton indicates whether the binding is a singleton.
	// If true, the binding will be resolved once and cached.
	singleton bool

	// done indicates whether a singleton binding has been resolved.
	// If singleton is false, this field is ignored.
	done bool
}

// newValueBinding builds a binding with an already resolved value.
func newValueBinding(v reflect.Value) *binding {
	return &binding{val: v, done: true, singleton: true}
}

// newFunctionBinding builds a binding with a function
// that will return a value of the target type.
//
// The function signature must be func(...) (T, error) or func(...) T
// where parameters are recursively resolved.
func newFunctionBinding(f reflect.Value, singleton bool) *binding {
	return &binding{fn: f, singleton: singleton}
}

// Get returns the pre-resolved value for the binding,
// or false if the binding is not resolved.
func (b *binding) Get() (v reflect.Value, ok bool) {
	return b.val, b.done
}

// Set sets the value of the binding to the given value,
// marking it as resolved.
//
// If the binding is not a singleton, this method does nothing.
func (b *binding) Set(v reflect.Value) {
	if b.singleton {
		b.val = v
		b.done = true
	}
}

// A map of type to function that returns a value of that type.
//
// The function should have the signature func(...) (T, error). Arguments are recursively resolved.
type bindings map[reflect.Type]*binding

func (b bindings) String() string {
	out := []string{}
	for k := range b {
		out = append(out, k.String())
	}
	return "bindings{" + strings.Join(out, ", ") + "}"
}

func (b bindings) add(values ...any) bindings {
	for _, v := range values {
		val := reflect.ValueOf(v)
		b[val.Type()] = newValueBinding(val)
	}
	return b
}

func (b bindings) addTo(impl, iface any) {
	val := reflect.ValueOf(impl)
	b[reflect.TypeOf(iface).Elem()] = newValueBinding(val)
}

func (b bindings) addProvider(provider any, singleton bool) error {
	pv := reflect.ValueOf(provider)
	t := pv.Type()
	if t.Kind() != reflect.Func {
		return fmt.Errorf("%T must be a function", provider)
	}

	if t.NumOut() == 0 {
		return fmt.Errorf("%T must be a function with the signature func(...)(T, error) or func(...) T", provider)
	}
	if t.NumOut() == 2 {
		if t.Out(1) != reflect.TypeOf((*error)(nil)).Elem() {
			return fmt.Errorf("missing error; %T must be a function with the signature func(...)(T, error) or func(...) T", provider)
		}
	}
	rt := pv.Type().Out(0)
	b[rt] = newFunctionBinding(pv, singleton)
	return nil
}

// Clone and add values.
func (b bindings) clone() bindings {
	out := make(bindings, len(b))
	for k, v := range b {
		out[k] = v
	}
	return out
}

func (b bindings) merge(other bindings) bindings {
	for k, v := range other {
		b[k] = v
	}
	return b
}

func getMethod(value reflect.Value, name string) reflect.Value {
	method := value.MethodByName(name)
	if !method.IsValid() {
		if value.CanAddr() {
			method = value.Addr().MethodByName(name)
		}
	}
	return method
}

func getExplicitMethod(value reflect.Value, name string) reflect.Value {
	if isExplicitMethod(value.Type(), name) {
		return value.MethodByName(name)
	}
	if value.CanAddr() && isExplicitMethod(value.Addr().Type(), name) {
		return value.Addr().MethodByName(name)
	}
	return reflect.Value{}
}

func isExplicitMethod(t reflect.Type, name string) bool {
	method, ok := t.MethodByName(name)
	if !ok {
		return false
	}
	// Promoted embedded methods are compiler-generated wrappers. The embedded
	// value itself is visited separately, so skip those wrappers here.
	fn := runtime.FuncForPC(method.Func.Pointer())
	if fn == nil {
		return true
	}
	file, _ := fn.FileLine(method.Func.Pointer())
	return file != "<autogenerated>"
}

// getMethods gets all methods with the given name from the given value
// and any embedded fields.
//
// Returns a slice of bound methods that can be called directly.
func getMethods(value reflect.Value, name string) (methods []reflect.Value) {
	walkEmbedded(value, func(v reflect.Value) {
		if method := getExplicitMethod(v, name); method.IsValid() {
			methods = append(methods, method)
		}
	})
	if len(methods) == 0 {
		// No explicit method was found on the value
		// or its exported embedded fields.
		// An unexported anonymous field may still provide a promoted method:
		//
		//     type options struct{}
		//     func (*options) AfterApply() error { return nil }
		//     type CLI struct{ options }
		//
		// Reflection cannot safely visit the options field,
		// but Go exposes CLI.AfterApply through a compiler-generated wrapper.
		// Calling that wrapper here cannot duplicate a method found above.
		if method := getMethod(value, name); method.IsValid() {
			methods = append(methods, method)
		}
	}
	return
}

// walkEmbedded calls visit on v and recursively on every exported field
// of v that is either a standard Go anonymous field or tagged `embed:""`.
// Pointer values are dereferenced before traversal; nil/invalid pointers
// are skipped. [Plugins] are descended into element-by-element, matching how
// [flattenedFields] treats them at build time.
func walkEmbedded(value reflect.Value, visit func(reflect.Value)) {
	if value.Kind() == reflect.Pointer {
		value = value.Elem()
	}
	if !value.IsValid() {
		return
	}
	visit(value)
	if value.Type() == reflect.TypeOf(Plugins{}) {
		for i := 0; i < value.Len(); i++ {
			walkEmbedded(value.Index(i).Elem(), visit)
		}
		return
	}
	if value.Kind() != reflect.Struct {
		return
	}
	t := value.Type()
	for i := 0; i < value.NumField(); i++ {
		field := t.Field(i)
		if !field.IsExported() {
			continue
		}
		_, isEmbedded := field.Tag.Lookup("embed")
		if !isEmbedded && !field.Anonymous {
			continue
		}
		walkEmbedded(value.Field(i), visit)
	}
}

func callFunction(f reflect.Value, bindings bindings) error {
	if f.Kind() != reflect.Func {
		return fmt.Errorf("expected function, got %s", f.Type())
	}
	t := f.Type()
	if t.NumOut() != 1 || !t.Out(0).Implements(callbackReturnSignature) {
		return fmt.Errorf("return value of %s must implement \"error\"", t)
	}
	out, err := callAnyFunction(f, bindings)
	if err != nil {
		return err
	}
	ferr := out[0]
	if ferrv := reflect.ValueOf(ferr); !ferrv.IsValid() || ((ferrv.Kind() == reflect.Interface || ferrv.Kind() == reflect.Pointer) && ferrv.IsNil()) {
		return nil
	}
	return ferr.(error) //nolint:forcetypeassert
}

func isNil(v reflect.Value) bool {
	switch v.Kind() {
	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
		return v.IsNil()
	default:
		return false
	}
}

func callAnyFunction(f reflect.Value, bindings bindings) (out []any, err error) {
	if f.Kind() != reflect.Func {
		return nil, fmt.Errorf("expected function, got %s", f.Type())
	}
	in := []reflect.Value{}
	t := f.Type()
	for i := 0; i < t.NumIn(); i++ {
		pt := t.In(i)
		binding, ok := bindings[pt]
		if !ok {
			return nil, fmt.Errorf("couldn't find binding of type %s for parameter %d of %s(), use kong.Bind(%s)", pt, i, t, pt)
		}

		// Don't need to call the function if the value is already resolved.
		if val, ok := binding.Get(); ok {
			in = append(in, val)
			continue
		}

		// Recursively resolve binding functions.
		argv, err := callAnyFunction(binding.fn, bindings)
		if err != nil {
			return nil, fmt.Errorf("%s: %w", pt, err)
		}
		if ferrv := reflect.ValueOf(argv[len(argv)-1]); ferrv.IsValid() && ferrv.Type().Implements(callbackReturnSignature) && !isNil(ferrv) {
			return nil, ferrv.Interface().(error) //nolint:forcetypeassert
		}

		val := reflect.ValueOf(argv[0])
		binding.Set(val)
		in = append(in, val)
	}
	outv := f.Call(in)
	out = make([]any, len(outv))
	for i, v := range outv {
		out[i] = v.Interface()
	}
	return out, nil
}