[xconfmap] Create module and add validation facilities

.chloggen/create-confmap-validate.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: xconfmap
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Create the xconfmap module and add the `Validator` interface and `Validate` function to facilitate config validation
+
+# One or more tracking issues or pull requests related to the change
+issues: [11524]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

.chloggen/deprecate-component-validate.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: component
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Deprecate `ConfigValidator` and `ValidateConfig`
+
+# One or more tracking issues or pull requests related to the change
+issues: [11524]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: Please use `Validator` and `Validate` respectively from `xconfmap`. 
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

cmd/builder/internal/builder/main_test.go

@@ -53,6 +53,7 @@ var replaceModules = []string{
 	"/config/configtelemetry",
 	"/config/configtls",
 	"/confmap",
+	"/confmap/xconfmap",
 	"/confmap/provider/envprovider",
 	"/confmap/provider/fileprovider",
 	"/confmap/provider/httpprovider",

cmd/otelcorecol/builder-config.yaml

@@ -52,6 +52,7 @@ replaces:
   - go.opentelemetry.io/collector/config/configtelemetry => ../../config/configtelemetry
   - go.opentelemetry.io/collector/config/configtls => ../../config/configtls
   - go.opentelemetry.io/collector/confmap => ../../confmap
+  - go.opentelemetry.io/collector/confmap/xconfmap => ../../confmap/xconfmap
   - go.opentelemetry.io/collector/confmap/provider/envprovider => ../../confmap/provider/envprovider
   - go.opentelemetry.io/collector/confmap/provider/fileprovider => ../../confmap/provider/fileprovider
   - go.opentelemetry.io/collector/confmap/provider/httpprovider => ../../confmap/provider/httpprovider

cmd/otelcorecol/go.mod

@@ -93,6 +93,7 @@ require (
 	go.opentelemetry.io/collector/config/configretry v1.25.0 // indirect
 	go.opentelemetry.io/collector/config/configtelemetry v0.119.0 // indirect
 	go.opentelemetry.io/collector/config/configtls v1.25.0 // indirect
+	go.opentelemetry.io/collector/confmap/xconfmap v0.0.0-00010101000000-000000000000 // indirect
 	go.opentelemetry.io/collector/connector/connectortest v0.119.0 // indirect
 	go.opentelemetry.io/collector/connector/xconnector v0.119.0 // indirect
 	go.opentelemetry.io/collector/consumer v1.25.0 // indirect
@@ -190,6 +191,8 @@ replace go.opentelemetry.io/collector/config/configtls => ../../config/configtls
 
 replace go.opentelemetry.io/collector/confmap => ../../confmap
 
+replace go.opentelemetry.io/collector/confmap/xconfmap => ../../confmap/xconfmap
+
 replace go.opentelemetry.io/collector/confmap/provider/envprovider => ../../confmap/provider/envprovider
 
 replace go.opentelemetry.io/collector/confmap/provider/fileprovider => ../../confmap/provider/fileprovider

component/config.go

@@ -14,7 +14,7 @@ import (
 // Config defines the configuration for a component.Component.
 //
 // Implementations and/or any sub-configs (other types embedded or included in the Config implementation)
-// MUST implement the ConfigValidator if any validation is required for that part of the configuration
+// MUST implement xconfmap.Validator if any validation is required for that part of the configuration
 // (e.g. check if a required field is present).
 //
 // A valid implementation MUST pass the check componenttest.CheckConfigStruct (return nil error).
@@ -25,13 +25,17 @@ type Config any
 var configValidatorType = reflect.TypeOf((*ConfigValidator)(nil)).Elem()
 
 // ConfigValidator defines an optional interface for configurations to implement to do validation.
+//
+// Deprecated: [v0.120.0] use xconfmap.Validator.
 type ConfigValidator interface {
 	// Validate the configuration and returns an error if invalid.
 	Validate() error
 }
 
 // ValidateConfig validates a config, by doing this:
 //   - Call Validate on the config itself if the config implements ConfigValidator.
+//
+// Deprecated: [v0.120.0] use xconfmap.Validate.
 func ValidateConfig(cfg Config) error {
 	var err error
 

confmap/confmap.go

@@ -24,6 +24,12 @@ const (
 	KeyDelimiter = "::"
 )
 
+const (
+	// MapstructureTag is the struct field tag used to record marshaling/unmarshaling settings.
+	// See https://pkg.go.dev/github.com/go-viper/mapstructure/v2 for supported values.
+	MapstructureTag = "mapstructure"
+)
+
 // New creates a new empty confmap.Conf instance.
 func New() *Conf {
 	return &Conf{k: koanf.New(KeyDelimiter)}
@@ -205,7 +211,7 @@ func decodeConfig(m *Conf, result any, errorUnused bool, skipTopLevelUnmarshaler
 	dc := &mapstructure.DecoderConfig{
 		ErrorUnused:      errorUnused,
 		Result:           result,
-		TagName:          "mapstructure",
+		TagName:          MapstructureTag,
 		WeaklyTypedInput: false,
 		MatchName:        caseSensitiveMatchName,
 		DecodeHook: mapstructure.ComposeDecodeHookFunc(
@@ -407,7 +413,7 @@ func unmarshalerEmbeddedStructsHookFunc() mapstructure.DecodeHookFuncValue {
 		for i := 0; i < to.Type().NumField(); i++ {
 			// embedded structs passed in via `squash` cannot be pointers. We just check if they are structs:
 			f := to.Type().Field(i)
-			if f.IsExported() && slices.Contains(strings.Split(f.Tag.Get("mapstructure"), ","), "squash") {
+			if f.IsExported() && slices.Contains(strings.Split(f.Tag.Get(MapstructureTag), ","), "squash") {
 				if unmarshaler, ok := to.Field(i).Addr().Interface().(Unmarshaler); ok {
 					c := NewFromStringMap(fromAsMap)
 					c.skipTopLevelUnmarshaler = true

confmap/xconfmap/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

confmap/xconfmap/config.go

@@ -0,0 +1,199 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package xconfmap // import "go.opentelemetry.io/collector/confmap/xconfmap"
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+
+	"go.opentelemetry.io/collector/confmap"
+)
+
+// As interface types are only used for static typing, a common idiom to find the reflection Type
+// for an interface type Foo is to use a *Foo value.
+var configValidatorType = reflect.TypeOf((*Validator)(nil)).Elem()
+
+// Validator defines an optional interface for configurations to implement to do validation.
+type Validator interface {
+	// Validate the configuration and returns an error if invalid.
+	Validate() error
+}
+
+// Validate validates a config, by doing this:
+//   - Call Validate on the config itself if the config implements ConfigValidator.
+func Validate(cfg any) error {
+	var err error
+
+	for _, validationErr := range validate(reflect.ValueOf(cfg)) {
+		err = errors.Join(err, validationErr)
+	}
+
+	return err
+}
+
+type pathError struct {
+	err  error
+	path []string
+}
+
+func (pe pathError) Error() string {
+	if len(pe.path) > 0 {
+		var path string
+		sb := strings.Builder{}
+
+		_, _ = sb.WriteString(pe.path[len(pe.path)-1])
+		for i := len(pe.path) - 2; i >= 0; i-- {
+			_, _ = sb.WriteString(confmap.KeyDelimiter)
+			_, _ = sb.WriteString(pe.path[i])
+		}
+		path = sb.String()
+
+		return fmt.Sprintf("%s: %s", path, pe.err)
+	}
+
+	return pe.err.Error()
+}
+
+func (pe pathError) Unwrap() error {
+	return pe.err
+}
+
+func validate(v reflect.Value) []pathError {
+	errs := []pathError{}
+	// Validate the value itself.
+	switch v.Kind() {
+	case reflect.Invalid:
+		return nil
+	case reflect.Ptr, reflect.Interface:
+		return validate(v.Elem())
+	case reflect.Struct:
+		err := callValidateIfPossible(v)
+		if err != nil {
+			errs = append(errs, pathError{err: err})
+		}
+
+		// Reflect on the pointed data and check each of its fields.
+		for i := 0; i < v.NumField(); i++ {
+			if !v.Type().Field(i).IsExported() {
+				continue
+			}
+			field := v.Type().Field(i)
+			path := fieldName(field)
+
+			subpathErrs := validate(v.Field(i))
+			for _, err := range subpathErrs {
+				errs = append(errs, pathError{
+					err:  err.err,
+					path: append(err.path, path),
+				})
+			}
+		}
+		return errs
+	case reflect.Slice, reflect.Array:
+		err := callValidateIfPossible(v)
+		if err != nil {
+			errs = append(errs, pathError{err: err})
+		}
+
+		// Reflect on the pointed data and check each of its fields.
+		for i := 0; i < v.Len(); i++ {
+			subPathErrs := validate(v.Index(i))
+
+			for _, err := range subPathErrs {
+				errs = append(errs, pathError{
+					err:  err.err,
+					path: append(err.path, strconv.Itoa(i)),
+				})
+			}
+		}
+		return errs
+	case reflect.Map:
+		err := callValidateIfPossible(v)
+		if err != nil {
+			errs = append(errs, pathError{err: err})
+		}
+
+		iter := v.MapRange()
+		for iter.Next() {
+			keyErrs := validate(iter.Key())
+			valueErrs := validate(iter.Value())
+			key := stringifyMapKey(iter.Key())
+
+			for _, err := range keyErrs {
+				errs = append(errs, pathError{err: err.err, path: append(err.path, key)})
+			}
+
+			for _, err := range valueErrs {
+				errs = append(errs, pathError{err: err.err, path: append(err.path, key)})
+			}
+		}
+		return errs
+	default:
+		err := callValidateIfPossible(v)
+		if err != nil {
+			return []pathError{{err: err}}
+		}
+
+		return nil
+	}
+}
+
+func callValidateIfPossible(v reflect.Value) error {
+	// If the value type implements ConfigValidator just call Validate
+	if v.Type().Implements(configValidatorType) {
+		return v.Interface().(Validator).Validate()
+	}
+
+	// If the pointer type implements ConfigValidator call Validate on the pointer to the current value.
+	if reflect.PointerTo(v.Type()).Implements(configValidatorType) {
+		// If not addressable, then create a new *V pointer and set the value to current v.
+		if !v.CanAddr() {
+			pv := reflect.New(reflect.PointerTo(v.Type()).Elem())
+			pv.Elem().Set(v)
+			v = pv.Elem()
+		}
+		return v.Addr().Interface().(Validator).Validate()
+	}
+
+	return nil
+}
+
+func fieldName(field reflect.StructField) string {
+	var fieldName string
+	if tag, ok := field.Tag.Lookup(confmap.MapstructureTag); ok {
+		tags := strings.Split(tag, ",")
+		if len(tags) > 0 {
+			fieldName = tags[0]
+		}
+	}
+	// Even if the mapstructure tag exists, the field name may not
+	// be available, so set it if it is still blank.
+	if len(fieldName) == 0 {
+		fieldName = strings.ToLower(field.Name)
+	}
+
+	return fieldName
+}
+
+func stringifyMapKey(val reflect.Value) string {
+	var key string
+
+	if str, ok := val.Interface().(string); ok {
+		key = str
+	} else if stringer, ok := val.Interface().(fmt.Stringer); ok {
+		key = stringer.String()
+	} else {
+		switch val.Kind() {
+		case reflect.Ptr, reflect.Interface, reflect.Struct, reflect.Slice, reflect.Array, reflect.Map:
+			key = fmt.Sprintf("[%T key]", val.Interface())
+		default:
+			key = fmt.Sprintf("%v", val.Interface())
+		}
+	}
+
+	return key
+}