[configoptional] Add a confmap.Marshaler implementation (#13196)

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

Adds a `confmap.Marshaler` implementation for `configoptional.Optional`

---------

Co-authored-by: Evan Bradley <[email protected]>

Author: mx-psi

.chloggen/mx-psi_marshaler-implementation copy.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: bug_fix
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: confmap
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Distinguish between empty and nil values when marshaling `confmap.Conf` structs."
+
+# One or more tracking issues or pull requests related to the change
+issues: [13196]
+
+# (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/mx-psi_marshaler-implementation.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: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: configoptional
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add a confmap.Marshaler implementation for configoptional.Optional"
+
+# One or more tracking issues or pull requests related to the change
+issues: [13196]
+
+# (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]

config/configoptional/optional.go

@@ -164,3 +164,28 @@ func (o *Optional[T]) Unmarshal(conf *confmap.Conf) error {
 	o.flavor = someFlavor
 	return nil
 }
+
+var _ confmap.Marshaler = (*Optional[any])(nil)
+
+// Marshal the Optional value into the configuration.
+// If the Optional is None or Default, it does not marshal anything.
+// If the Optional is Some, it marshals the value into the configuration.
+//
+// T must be derefenceable to a type with struct kind.
+// Scalar values are not supported.
+func (o Optional[T]) Marshal(conf *confmap.Conf) error {
+	if err := assertStructKind[T](); err != nil {
+		return err
+	}
+
+	if o.flavor == noneFlavor || o.flavor == defaultFlavor {
+		// Optional is None or Default, do not marshal anything.
+		return conf.Marshal(map[string]any(nil))
+	}
+
+	if err := conf.Marshal(o.value); err != nil {
+		return fmt.Errorf("configoptional: failed to marshal Optional value: %w", err)
+	}
+
+	return nil
+}

config/configoptional/optional_test.go

@@ -4,6 +4,7 @@
 package configoptional
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -339,10 +340,11 @@ func confFromYAML(t *testing.T, yaml string) *confmap.Conf {
 	return conf
 }
 
-func TestComparePointer(t *testing.T) {
+func TestComparePointerUnmarshal(t *testing.T) {
 	tests := []struct {
 		yaml string
 	}{
+		{yaml: ""},
 		{yaml: "sub: "},
 		{yaml: "sub: null"},
 		{yaml: "sub: {}"},
@@ -365,3 +367,96 @@ func TestComparePointer(t *testing.T) {
 		})
 	}
 }
+
+func TestOptionalMarshal(t *testing.T) {
+	tests := []struct {
+		name     string
+		value    Config[Sub]
+		expected map[string]any
+	}{
+		{
+			name:     "none (zero value)",
+			value:    Config[Sub]{},
+			expected: map[string]any{"sub": nil},
+		},
+		{
+			name:     "none",
+			value:    Config[Sub]{Sub1: None[Sub]()},
+			expected: map[string]any{"sub": nil},
+		},
+		{
+			name:     "default",
+			value:    Config[Sub]{Sub1: Default(subDefault)},
+			expected: map[string]any{"sub": nil},
+		},
+		{
+			name: "some",
+			value: Config[Sub]{Sub1: Some(Sub{
+				Foo: "bar",
+			})},
+			expected: map[string]any{
+				"sub": map[string]any{
+					"foo": "bar",
+				},
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			conf := confmap.New()
+			require.NoError(t, conf.Marshal(test.value))
+			assert.Equal(t, test.expected, conf.ToStringMap())
+		})
+	}
+}
+
+func TestComparePointerMarshal(t *testing.T) {
+	type Wrap[T any] struct {
+		// Note: passes without requiring "squash".
+		Sub1 T `mapstructure:"sub"`
+	}
+
+	type WrapOmitEmpty[T any] struct {
+		// Note: passes without requiring "squash", except with Default-flavored Optional values.
+		Sub1 T `mapstructure:"sub,omitempty"`
+	}
+
+	tests := []struct {
+		pointer       *Sub
+		optional      Optional[Sub]
+		skipOmitEmpty bool
+	}{
+		{pointer: nil, optional: None[Sub]()},
+		{pointer: nil, optional: Default(subDefault), skipOmitEmpty: true}, // does not work with omitempty
+		{pointer: &Sub{Foo: "bar"}, optional: Some(Sub{Foo: "bar"})},
+	}
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("%v vs %v", test.pointer, test.optional), func(t *testing.T) {
+			wrapPointer := Wrap[*Sub]{Sub1: test.pointer}
+			confPointer := confmap.NewFromStringMap(nil)
+			require.NoError(t, confPointer.Marshal(wrapPointer))
+
+			wrapOptional := Wrap[Optional[Sub]]{Sub1: test.optional}
+			confOptional := confmap.NewFromStringMap(nil)
+			require.NoError(t, confOptional.Marshal(wrapOptional))
+
+			assert.Equal(t, confPointer.ToStringMap(), confOptional.ToStringMap())
+		})
+
+		if test.skipOmitEmpty {
+			continue
+		}
+		t.Run(fmt.Sprintf("%v vs %v (omitempty)", test.pointer, test.optional), func(t *testing.T) {
+			wrapPointer := WrapOmitEmpty[*Sub]{Sub1: test.pointer}
+			confPointer := confmap.NewFromStringMap(nil)
+			require.NoError(t, confPointer.Marshal(wrapPointer))
+
+			wrapOptional := WrapOmitEmpty[Optional[Sub]]{Sub1: test.optional}
+			confOptional := confmap.NewFromStringMap(nil)
+			require.NoError(t, confOptional.Marshal(wrapOptional))
+
+			assert.Equal(t, confPointer.ToStringMap(), confOptional.ToStringMap())
+		})
+	}
+}

confmap/confmap.go

@@ -580,11 +580,22 @@ func marshalerHookFunc(orig any) mapstructure.DecodeHookFuncValue {
 		if !ok {
 			return from.Interface(), nil
 		}
-		conf := New()
+		conf := NewFromStringMap(nil)
 		if err := marshaler.Marshal(conf); err != nil {
 			return nil, err
 		}
-		return conf.ToStringMap(), nil
+
+		stringMap := conf.ToStringMap()
+		if stringMap == nil {
+			// If conf is still nil after marshaling, we want to encode it as an untyped nil
+			// instead of a map-typed nil. This ensures the value is a proper null value
+			// in the final marshaled output instead of an empty map. We hit this case
+			// when marshaling wrapper structs that have no direct representation
+			// in the marshaled output that aren't tagged with "squash" on the fields
+			// they're used on.
+			return nil, nil
+		}
+		return stringMap, nil
 	})
 }
 

confmap/internal/mapstructure/encoder.go

@@ -165,7 +165,12 @@ func (e *Encoder) encodeMap(value reflect.Value) (any, error) {
 			Kind:   value.Kind(),
 		}
 	}
-	result := make(map[string]any)
+
+	var result map[string]any
+	if value.Len() > 0 || !value.IsNil() {
+		result = make(map[string]any)
+	}
+
 	iterator := value.MapRange()
 	for iterator.Next() {
 		encoded, err := e.encode(iterator.Key())

service/config_test.go

@@ -87,7 +87,7 @@ func TestConfmapMarshalConfig(t *testing.T) {
 		Telemetry: defaultTelConfig,
 	}))
 	assert.Equal(t, map[string]any{
-		"pipelines": map[string]any{},
+		"pipelines": map[string]any(nil),
 		"telemetry": map[string]any{
 			"logs": map[string]any{
 				"encoding":           "console",