Optionally propagate context to Decoder

This introduces a new way to define `EnvDecode` to optionally pass in a context. The old way still works, but the context method is preferred. Since it's actually impossible to define the same function with different arguments on the same receiver, there's no possibility of conflict.

Author: sethvargo

README.md

@@ -290,8 +290,21 @@ the non-nil value. To change this behavior, see
 
 ### Custom Decoders
 
-You can also define your own decoders. See the [godoc][godoc] for more
-information.
+You can also define your own decoders.
+
+```go
+type MyCustomType struct {
+  value string
+}
+
+func (t *MyCustomType) EnvDecode(ctx context.Context, val string) error {
+  resolved := someComplexFunction(val)
+  t.value = resolved
+  return nil
+}
+```
+
+See the [godoc][godoc] for more information.
 
 
 ## Testing

envconfig.go

@@ -214,16 +214,23 @@ type keyedLookuper interface {
 	Key(key string) string
 }
 
-// Decoder is an interface that custom types/fields can implement to control how
-// decoding takes place. For example:
+// Decoder is the legacy implementation of [DecoderCtx], but it does not accept
+// a context as the first parameter to `EnvDecode`. Please use [DecoderCtx]
+// instead, as this will be removed in a future release.
+type Decoder interface {
+	EnvDecode(val string) error
+}
+
+// DecoderCtx is an interface that custom types/fields can implement to control
+// how decoding takes place. For example:
 //
 //	type MyType string
 //
-//	func (mt MyType) EnvDecode(val string) error {
+//	func (mt MyType) EnvDecode(ctx context.Context, val string) error {
 //	    return "CUSTOM-"+val
 //	}
-type Decoder interface {
-	EnvDecode(val string) error
+type DecoderCtx interface {
+	EnvDecode(ctx context.Context, val string) error
 }
 
 // options are internal options for decoding.
@@ -471,7 +478,7 @@ func processWith(ctx context.Context, c *Config) error {
 			}
 
 			if found || usedDefault || decodeUnset {
-				if ok, err := processAsDecoder(val, ef); ok {
+				if ok, err := processAsDecoder(ctx, val, ef); ok {
 					if err != nil {
 						return err
 					}
@@ -556,7 +563,7 @@ func processWith(ctx context.Context, c *Config) error {
 		}
 
 		// Set value.
-		if err := processField(val, ef, delimiter, separator, noInit); err != nil {
+		if err := processField(ctx, val, ef, delimiter, separator, noInit); err != nil {
 			return fmt.Errorf("%s: %w", tf.Name, err)
 		}
 	}
@@ -692,7 +699,7 @@ func lookup(key string, required bool, defaultValue string, l Lookuper) (string,
 
 // processAsDecoder processes the given value as a decoder or custom
 // unmarshaller.
-func processAsDecoder(v string, ef reflect.Value) (bool, error) {
+func processAsDecoder(ctx context.Context, v string, ef reflect.Value) (bool, error) {
 	// Keep a running error. It's possible that a property might implement
 	// multiple decoders, and we don't know *which* decoder will succeed. If we
 	// get through all of them, we'll return the most recent error.
@@ -711,6 +718,13 @@ func processAsDecoder(v string, ef reflect.Value) (bool, error) {
 		// never attempt to use other decoders in case of failure. EnvDecode's
 		// decoding logic is "the right one", and the error returned (if any)
 		// is the most specific we can get.
+		if dec, ok := iface.(DecoderCtx); ok {
+			imp = true
+			err = dec.EnvDecode(ctx, v)
+			return imp, err
+		}
+
+		// Check legacy decoder implementation
 		if dec, ok := iface.(Decoder); ok {
 			imp = true
 			err = dec.EnvDecode(v)
@@ -749,7 +763,7 @@ func processAsDecoder(v string, ef reflect.Value) (bool, error) {
 	return imp, err
 }
 
-func processField(v string, ef reflect.Value, delimiter, separator string, noInit bool) error {
+func processField(ctx context.Context, v string, ef reflect.Value, delimiter, separator string, noInit bool) error {
 	// If the input value is empty and initialization is skipped, do nothing.
 	if v == "" && noInit {
 		return nil
@@ -767,7 +781,7 @@ func processField(v string, ef reflect.Value, delimiter, separator string, noIni
 	tk := tf.Kind()
 
 	// Handle existing decoders.
-	if ok, err := processAsDecoder(v, ef); ok {
+	if ok, err := processAsDecoder(ctx, v, ef); ok {
 		return err
 	}
 
@@ -837,12 +851,12 @@ func processField(v string, ef reflect.Value, delimiter, separator string, noIni
 			mKey, mVal := strings.TrimSpace(pair[0]), strings.TrimSpace(pair[1])
 
 			k := reflect.New(tf.Key()).Elem()
-			if err := processField(mKey, k, delimiter, separator, noInit); err != nil {
+			if err := processField(ctx, mKey, k, delimiter, separator, noInit); err != nil {
 				return fmt.Errorf("%s: %w", mKey, err)
 			}
 
 			v := reflect.New(tf.Elem()).Elem()
-			if err := processField(mVal, v, delimiter, separator, noInit); err != nil {
+			if err := processField(ctx, mVal, v, delimiter, separator, noInit); err != nil {
 				return fmt.Errorf("%s: %w", mVal, err)
 			}
 
@@ -860,7 +874,7 @@ func processField(v string, ef reflect.Value, delimiter, separator string, noIni
 			s := reflect.MakeSlice(tf, len(vals), len(vals))
 			for i, val := range vals {
 				val = strings.TrimSpace(val)
-				if err := processField(val, s.Index(i), delimiter, separator, noInit); err != nil {
+				if err := processField(ctx, val, s.Index(i), delimiter, separator, noInit); err != nil {
 					return fmt.Errorf("%s: %w", val, err)
 				}
 			}

envconfig_test.go

@@ -31,14 +31,26 @@ import (
 	"github.com/google/go-cmp/cmp"
 )
 
-var _ Decoder = (*CustomDecoderType)(nil)
+var _ DecoderCtx = (*CustomDecoderType)(nil)
 
 // CustomDecoderType is used to test custom decoding using Decoder.
 type CustomDecoderType struct {
 	value string
 }
 
-func (c *CustomDecoderType) EnvDecode(val string) error {
+func (c *CustomDecoderType) EnvDecode(ctx context.Context, val string) error {
+	c.value = "CUSTOM-" + val
+	return nil
+}
+
+var _ Decoder = (*CustomDecoderTypeLegacy)(nil)
+
+// CustomDecoderTypeLegacy is used to test custom decoding using Decoder.
+type CustomDecoderTypeLegacy struct {
+	value string
+}
+
+func (c *CustomDecoderTypeLegacy) EnvDecode(val string) error {
 	c.value = "CUSTOM-" + val
 	return nil
 }
@@ -1428,6 +1440,14 @@ func TestProcessWith(t *testing.T) {
 		},
 
 		// Syntax
+		{
+			name: "syntax/=key",
+			target: &struct {
+				Field CustomDecoderTypeLegacy `env:"FIELD=foo"`
+			}{},
+			lookuper: MapLookuper(nil),
+			err:      ErrInvalidEnvvarName,
+		},
 		{
 			name: "syntax/=key",
 			target: &struct {
@@ -1619,6 +1639,98 @@ func TestProcessWith(t *testing.T) {
 			lookuper: MapLookuper(nil),
 		},
 
+		// Custom decoder - legacy
+		{
+			name: "custom_decoder/struct",
+			target: &struct {
+				Field CustomDecoderTypeLegacy `env:"FIELD"`
+			}{},
+			exp: &struct {
+				Field CustomDecoderTypeLegacy `env:"FIELD"`
+			}{
+				Field: CustomDecoderTypeLegacy{
+					value: "CUSTOM-foo",
+				},
+			},
+			lookuper: MapLookuper(map[string]string{
+				"FIELD": "foo",
+			}),
+		},
+		{
+			name: "custom_decoder/pointer",
+			target: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD"`
+			}{},
+			exp: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD"`
+			}{
+				Field: &CustomDecoderTypeLegacy{
+					value: "CUSTOM-foo",
+				},
+			},
+			lookuper: MapLookuper(map[string]string{
+				"FIELD": "foo",
+			}),
+		},
+		{
+			name: "custom_decoder/private",
+			target: &struct {
+				field *CustomDecoderTypeLegacy `env:"FIELD"`
+			}{},
+			lookuper: MapLookuper(map[string]string{
+				"FIELD": "foo",
+			}),
+			err: ErrPrivateField,
+		},
+		{
+			name: "custom_decoder/error",
+			target: &struct {
+				Field CustomTypeError `env:"FIELD"`
+			}{},
+			lookuper: MapLookuper(map[string]string{
+				"FIELD": "foo",
+			}),
+			errMsg: "broken",
+		},
+		{
+			name: "custom_decoder/called_for_empty_string",
+			target: &struct {
+				Field CustomTypeError `env:"FIELD"`
+			}{},
+			lookuper: MapLookuper(map[string]string{
+				"FIELD": "",
+			}),
+			errMsg: "broken",
+		},
+		{
+			name: "custom_decoder/called_when_default",
+			target: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD, default=foo"`
+			}{},
+			exp: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD, default=foo"`
+			}{
+				Field: &CustomDecoderTypeLegacy{
+					value: "CUSTOM-foo",
+				},
+			},
+			lookuper: MapLookuper(nil),
+		},
+		{
+			name: "custom_decoder/called_on_decodeunset",
+			target: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD, decodeunset"`
+			}{},
+			exp: &struct {
+				Field *CustomDecoderTypeLegacy `env:"FIELD, decodeunset"`
+			}{
+				Field: &CustomDecoderTypeLegacy{
+					value: "CUSTOM-",
+				},
+			},
+			lookuper: MapLookuper(nil),
+		},
+
 		// Expand
 		{
 			name: "expand/not_default",
@@ -3034,6 +3146,9 @@ func TestProcessWith(t *testing.T) {
 				// Custom decoder type
 				CustomDecoderType{},
 
+				// Custom decoder type - legacy
+				CustomDecoderTypeLegacy{},
+
 				// Custom standard library interfaces decoder type
 				CustomStdLibDecodingType{},