♻️ [config] Improve validation error formatting (#585)

<!--
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
### Description

Improve validation errors returned by configuration validation


### Test Coverage

<!--
Please put an `x` in the correct box e.g. `[x]` to indicate the testing
coverage of this change.
-->

- [x]  This change is covered by existing or additional automated tests.
- [ ] Manual testing has been performed (and evidence provided) as
automated testing was not feasible.
- [ ] Additional tests are not required for this change (e.g.
documentation update).

Author: acabarbaye

.secrets.baseline

@@ -130,21 +130,21 @@
         "filename": "utils/config/service_configuration_test.go",
         "hashed_secret": "7ca1cc114e7e5f955880bb96a5bf391b4dc20ab6",
         "is_verified": false,
-        "line_number": 481
+        "line_number": 497
       },
       {
         "type": "Secret Keyword",
         "filename": "utils/config/service_configuration_test.go",
         "hashed_secret": "11519c144be4850d95b34220a40030cbd5a36b57",
         "is_verified": false,
-        "line_number": 576
+        "line_number": 592
       },
       {
         "type": "Secret Keyword",
         "filename": "utils/config/service_configuration_test.go",
         "hashed_secret": "15fae91d8fa7f2c531c1cf3ddc745e1f4473c02d",
         "is_verified": false,
-        "line_number": 583
+        "line_number": 599
       }
     ],
     "utils/filesystem/filehash_test.go": [
@@ -265,5 +265,5 @@
       }
     ]
   },
-  "generated_at": "2025-03-17T21:06:33Z"
+  "generated_at": "2025-03-28T10:35:43Z"
 }

changes/20250328102314.bugfix

@@ -0,0 +1 @@
+:recycle: [config] Improve error formatting to ease understanding configuration validation errors

utils/commonerrors/serialisation.go

@@ -19,13 +19,23 @@ type iMarshallingError interface {
 	error
 	ConvertToError() error
 	SetWrappedError(err error)
+	GetReason() string
+	GetErrorType() error
 }
 
 type marshallingError struct {
 	Reason    string
 	ErrorType error
 }
 
+func (e *marshallingError) GetReason() string {
+	return e.Reason
+}
+
+func (e *marshallingError) GetErrorType() error {
+	return e.ErrorType
+}
+
 func (e *marshallingError) MarshalText() (text []byte, err error) {
 	str := e.String()
 	return []byte(str), nil
@@ -73,6 +83,22 @@ type multiplemarshallingError struct {
 	subErrs []iMarshallingError
 }
 
+func (m *multiplemarshallingError) GetReason() string {
+	reasons := make([]string, 0, len(m.subErrs))
+	for i := range m.subErrs {
+		reasons = append(reasons, m.subErrs[i].GetReason())
+	}
+	return strings.Join(reasons, string(MultipleErrorSeparator))
+}
+
+func (m *multiplemarshallingError) GetErrorType() error {
+	errs := make([]error, 0, len(m.subErrs))
+	for i := range m.subErrs {
+		errs = append(errs, m.subErrs[i].GetErrorType())
+	}
+	return errors.Join(errs...)
+}
+
 func (m *multiplemarshallingError) MarshalText() (text []byte, err error) {
 	for i := range m.subErrs {
 		subtext, suberr := m.subErrs[i].MarshalText()
@@ -112,7 +138,7 @@ func (m *multiplemarshallingError) UnmarshalText(text []byte) error {
 }
 
 func (m *multiplemarshallingError) ConvertToError() error {
-	var errs []error
+	errs := make([]error, 0, len(m.subErrs))
 	for i := range m.subErrs {
 		errs = append(errs, m.subErrs[i].ConvertToError())
 	}
@@ -227,20 +253,62 @@ func SerialiseError(err error) ([]byte, error) {
 
 // DeserialiseError unmarshals text into an error. It tries to determine the error type.
 func DeserialiseError(text []byte) (deserialisedError, err error) {
-	if len(text) == 0 {
+	mErr, err := deserialiseError(text)
+	if err != nil || mErr == nil {
 		return
 	}
-	var mErr iMarshallingError
+	deserialisedError = mErr.ConvertToError()
+	return
+}
 
+func deserialiseError(text []byte) (deserialisedError iMarshallingError, err error) {
+	if len(text) == 0 {
+		return
+	}
 	if strings.Contains(string(text), string(MultipleErrorSeparator)) {
-		mErr = &multiplemarshallingError{}
+		deserialisedError = &multiplemarshallingError{}
 	} else {
-		mErr = &marshallingError{}
+		deserialisedError = &marshallingError{}
 	}
-	err = mErr.UnmarshalText(text)
-	if err != nil {
+	err = deserialisedError.UnmarshalText(text)
+	return
+}
+
+func GetErrorReason(srcErr error) (reason string, err error) {
+	if srcErr == nil {
+		err = UndefinedVariable("source error")
 		return
 	}
-	deserialisedError = mErr.ConvertToError()
+	mErr, err := deserialiseError([]byte(srcErr.Error()))
+	if err != nil || mErr == nil {
+		return
+	}
+	reason = mErr.GetReason()
+	return
+}
+
+func GetCommonErrorReason(srcErr error) (reason string, err error) {
+	if srcErr == nil {
+		err = UndefinedVariable("source error")
+		return
+	}
+	if !IsCommonError(srcErr) {
+		reason = srcErr.Error()
+		return
+	}
+	reason, err = GetErrorReason(srcErr)
+	return
+}
+
+func GetUnderlyingErrorType(srcErr error) (commonerrorType, err error) {
+	if srcErr == nil {
+		err = UndefinedVariable("source error")
+		return
+	}
+	mErr, err := deserialiseError([]byte(srcErr.Error()))
+	if err != nil || mErr == nil {
+		return
+	}
+	commonerrorType = mErr.GetErrorType()
 	return
 }

utils/commonerrors/serialisation_test.go

@@ -42,7 +42,7 @@ func TestDeserialise(t *testing.T) {
 			expectedError:  errors.New(errStr),
 		},
 		{
-			text:           fmt.Errorf("%w: %v", errors.New(errStr), sentence).Error(),
+			text:           New(errors.New(errStr), sentence).Error(),
 			expectedReason: sentence,
 			expectedError:  errors.New(errStr),
 		},
@@ -144,7 +144,7 @@ func (m multiErr) Error() string   { return errors.Join(m...).Error() }
 func (m multiErr) Unwrap() []error { return []error(m) }
 
 func TestMultipleError(t *testing.T) {
-	expectedErr := multiErr([]error{fmt.Errorf("%w: %v", ErrInvalid, strings.ReplaceAll(faker.Sentence(), string(MultipleErrorSeparator), "sep")), errors.New(""), fmt.Errorf("%w: %v", ErrUnexpected, strings.ReplaceAll(faker.Sentence(), string(MultipleErrorSeparator), ";"))})
+	expectedErr := multiErr([]error{New(ErrInvalid, strings.ReplaceAll(faker.Sentence(), string(MultipleErrorSeparator), "sep")), errors.New(""), New(ErrUnexpected, strings.ReplaceAll(faker.Sentence(), string(MultipleErrorSeparator), ";"))})
 	text, err := SerialiseError(expectedErr)
 	require.NoError(t, err)
 	assert.NotEmpty(t, text)
@@ -191,6 +191,31 @@ func TestGenericSerialisation(t *testing.T) {
 		assert.NoError(t, deserialisedErr)
 	})
 
+	t.Run("error Reason", func(t *testing.T) {
+		reason := faker.Sentence()
+		dErr := New(errors.New(faker.Word()), reason)
+		dReason, err := GetCommonErrorReason(dErr)
+		require.NoError(t, err)
+		assert.Equal(t, dErr.Error(), dReason)
+		dReason, err = GetErrorReason(dErr)
+		require.NoError(t, err)
+		assert.Equal(t, reason, dReason)
+		reason = faker.Sentence()
+		dErr = New(ErrNotFound, reason)
+		dReason, err = GetCommonErrorReason(dErr)
+		require.NoError(t, err)
+		assert.Equal(t, reason, dReason)
+		dReason, err = GetErrorReason(dErr)
+		require.NoError(t, err)
+		assert.Equal(t, reason, dReason)
+		dReason, err = GetCommonErrorReason(nil)
+		assert.True(t, Any(err, ErrUndefined))
+		assert.Empty(t, dReason)
+		dReason, err = GetErrorReason(nil)
+		assert.True(t, Any(err, ErrUndefined))
+		assert.Empty(t, dReason)
+	})
+
 	tests := []struct {
 		commonError error
 	}{
@@ -227,12 +252,21 @@ func TestGenericSerialisation(t *testing.T) {
 		test := tests[i]
 		t.Run(test.commonError.Error(), func(t *testing.T) {
 			reason := strings.ReplaceAll(faker.Sentence(), "\n", ";")
-			text, err := SerialiseError(fmt.Errorf("%w : %v", test.commonError, reason))
+			text, err := SerialiseError(New(test.commonError, reason))
 			require.NoError(t, err)
 			dErr, err := DeserialiseError(text)
 			require.NoError(t, err)
 			assert.True(t, Any(dErr, test.commonError))
 			assert.True(t, strings.Contains(dErr.Error(), reason))
+			underlyingErr, err := GetUnderlyingErrorType(dErr)
+			require.NoError(t, err)
+			assert.True(t, Any(underlyingErr, test.commonError))
+			dReason, err := GetErrorReason(dErr)
+			require.NoError(t, err)
+			assert.Equal(t, reason, dReason)
+			dReason, err = GetCommonErrorReason(dErr)
+			require.NoError(t, err)
+			assert.Equal(t, reason, dReason)
 		})
 	}
 }