[xconfmap] Create module and add validation facilities (#12226)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

Builds on
#12224 and
starts the move of config validation from component to confmap. We can
keep this in `xconfmap` while we determine whether to add the ability to
validate using struct field tags.

I think this has the following advantages:
1. Everything configuration-related is now in confmap instead of split
between confmap and component.
2. We can share things like the mapstructure tag and config key
separator as constants between unmarshaling and validation without
creating dependencies between confmap and component.

~The one uncertainty this creates is what to do with `component.Config`,
which would now be used as a thin alias for `any` without any meaningful
usage in component.~

<!-- Issue number if applicable -->
#### Link to tracking issue
Fixes
#11524

.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
+}