Change DecodePath to return (bool, error)

The bool indicates whether the path was found, making it possible
to distinguish between path-not-found and actual errors.

Author: oschwald

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 2.0.0-beta.9
 
+- **BREAKING CHANGE**: `DecodePath` now returns `(bool, error)` instead of
+  just `error`. The bool indicates whether the path was found, making it
+  possible to distinguish between path-not-found and actual errors.
 - **SECURITY**: Fixed integer overflow vulnerability in search tree size
   calculation that could potentially allow malformed databases to trigger
   security issues.

fuzz_test.go

@@ -42,7 +42,7 @@ func FuzzDatabase(f *testing.F) {
 			_ = result.Decode(&mapResult)
 			if mapResult != nil {
 				var output any
-				_ = result.DecodePath(&output, "country", "iso_code")
+				_, _ = result.DecodePath(&output, "country", "iso_code")
 			}
 		}
 	})
@@ -192,20 +192,20 @@ func FuzzDecodePath(f *testing.F) {
 
 		// Try to decode with the fuzzed path
 		var output any
-		_ = result.DecodePath(&output, path...)
+		_, _ = result.DecodePath(&output, path...)
 
 		// Also test with different output types to exercise different decoding paths
 		var stringOutput string
-		_ = result.DecodePath(&stringOutput, path...)
+		_, _ = result.DecodePath(&stringOutput, path...)
 
 		var intOutput int
-		_ = result.DecodePath(&intOutput, path...)
+		_, _ = result.DecodePath(&intOutput, path...)
 
 		var mapOutput map[string]any
-		_ = result.DecodePath(&mapOutput, path...)
+		_, _ = result.DecodePath(&mapOutput, path...)
 
 		var sliceOutput []any
-		_ = result.DecodePath(&sliceOutput, path...)
+		_, _ = result.DecodePath(&sliceOutput, path...)
 	})
 }
 

internal/decoder/reflection.go

@@ -93,10 +93,10 @@ func (d *ReflectionDecoder) DecodePath(
 	offset uint,
 	path []any,
 	v any,
-) error {
+) (bool, error) {
 	result := reflect.ValueOf(v)
 	if result.Kind() != reflect.Ptr || result.IsNil() {
-		return errors.New("result param must be a pointer")
+		return false, errors.New("result param must be a pointer")
 	}
 
 PATH:
@@ -108,23 +108,23 @@ PATH:
 		)
 		typeNum, size, offset, err = d.decodeCtrlData(offset)
 		if err != nil {
-			return err
+			return false, err
 		}
 
 		if typeNum == KindPointer {
 			pointer, _, err := d.decodePointer(size, offset)
 			if err != nil {
-				return err
+				return false, err
 			}
 
 			typeNum, size, offset, err = d.decodeCtrlData(pointer)
 			if err != nil {
-				return err
+				return false, err
 			}
 
 			// Check for pointer-to-pointer after we've already read the data
 			if typeNum == KindPointer {
-				return mmdberrors.NewInvalidDatabaseError(
+				return false, mmdberrors.NewInvalidDatabaseError(
 					"invalid pointer to pointer at offset %d",
 					pointer,
 				)
@@ -135,53 +135,53 @@ PATH:
 		case string:
 			// We are expecting a map
 			if typeNum != KindMap {
-				return fmt.Errorf("expected a map for %s but found %s", v, typeNum.String())
+				return false, fmt.Errorf("expected a map for %s but found %s", v, typeNum.String())
 			}
 			for range size {
 				var key []byte
 				key, offset, err = d.decodeKey(offset)
 				if err != nil {
-					return err
+					return false, err
 				}
 				if string(key) == v {
 					continue PATH
 				}
 				offset, err = d.nextValueOffset(offset, 1)
 				if err != nil {
-					return err
+					return false, err
 				}
 			}
-			// Not found. Maybe return a boolean?
-			return nil
+			// Not found
+			return false, nil
 		case int:
 			// We are expecting an array
 			if typeNum != KindSlice {
-				return fmt.Errorf("expected a slice for %d but found %s", v, typeNum.String())
+				return false, fmt.Errorf("expected a slice for %d but found %s", v, typeNum.String())
 			}
 			var i uint
 			if v < 0 {
 				if size < uint(-v) {
 					// Slice is smaller than negative index, not found
-					return nil
+					return false, nil
 				}
 				i = size - uint(-v)
 			} else {
 				if size <= uint(v) {
 					// Slice is smaller than index, not found
-					return nil
+					return false, nil
 				}
 				i = uint(v)
 			}
 			offset, err = d.nextValueOffset(offset, i)
 			if err != nil {
-				return err
+				return false, err
 			}
 		default:
-			return fmt.Errorf("unexpected type for %d value in path, %v: %T", i, v, v)
+			return false, fmt.Errorf("unexpected type for %d value in path, %v: %T", i, v, v)
 		}
 	}
 	_, err := d.decode(offset, result, len(path))
-	return d.wrapError(err, offset)
+	return true, d.wrapError(err, offset)
 }
 
 // wrapError wraps an error with context information when an error occurs.

reader_test.go

@@ -332,40 +332,55 @@ func TestDecodePath(t *testing.T) {
 
 	var u16 uint16
 
-	require.NoError(t, result.DecodePath(&u16, "uint16"))
-
+	found, err := result.DecodePath(&u16, "uint16")
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint16(100), u16)
 
 	var u uint
-	require.NoError(t, result.DecodePath(&u, "array", 0))
+	found, err = result.DecodePath(&u, "array", 0)
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint(1), u)
 
 	var u2 uint
-	require.NoError(t, result.DecodePath(&u2, "array", 2))
+	found, err = result.DecodePath(&u2, "array", 2)
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint(3), u2)
 
 	// This is past the end of the array
 	var u3 uint
-	require.NoError(t, result.DecodePath(&u3, "array", 3))
+	found, err = result.DecodePath(&u3, "array", 3)
+	require.NoError(t, err)
+	assert.False(t, found)
 	assert.Equal(t, uint(0), u3)
 
 	// Negative offsets
 
 	var n1 uint
-	require.NoError(t, result.DecodePath(&n1, "array", -1))
+	found, err = result.DecodePath(&n1, "array", -1)
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint(3), n1)
 
 	var n2 uint
-	require.NoError(t, result.DecodePath(&n2, "array", -3))
+	found, err = result.DecodePath(&n2, "array", -3)
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint(1), n2)
 
 	var u4 uint
-	require.NoError(t, result.DecodePath(&u4, "map", "mapX", "arrayX", 1))
+	found, err = result.DecodePath(&u4, "map", "mapX", "arrayX", 1)
+	require.NoError(t, err)
+	assert.True(t, found)
 	assert.Equal(t, uint(8), u4)
 
 	// Does key not exist
 	var ne uint
-	require.NoError(t, result.DecodePath(&ne, "does-not-exist", 1))
+	found, err = result.DecodePath(&ne, "does-not-exist", 1)
+	require.NoError(t, err)
+	assert.False(t, found)
 	assert.Equal(t, uint(0), ne)
 }
 
@@ -1000,7 +1015,7 @@ func BenchmarkDecodePathCountryCode(b *testing.B) {
 	s := make(net.IP, 4)
 	for range b.N {
 		ip := randomIPv4Address(r, s)
-		err = db.Lookup(ip).DecodePath(&result, path...)
+		_, err = db.Lookup(ip).DecodePath(&result, path...)
 		if err != nil {
 			b.Error(err)
 		}

result.go

@@ -59,26 +59,31 @@ func (r Result) Decode(v any) error {
 //
 // If the path is empty, the entire data structure is decoded into v.
 //
-// Returns an error if:
-//   - the path is invalid
-//   - the data cannot be decoded into the type of v
-//   - v is not a pointer or the database record cannot be stored in v due to
-//     type mismatch
-//   - the Result does not contain valid data
+// Returns (found, error):
+//   - found is true if the path was found and decoded successfully
+//   - found is false if the path was not found (but no error occurred)
+//   - error is returned for actual errors (invalid path, type mismatch, etc.)
 //
 // Example usage:
 //
 //	var city string
-//	err := result.DecodePath(&city, "location", "city", "names", "en")
+//	found, err := result.DecodePath(&city, "location", "city", "names", "en")
+//	if err != nil {
+//	    // Handle error
+//	} else if found {
+//	    // city contains the decoded value
+//	} else {
+//	    // path was not found
+//	}
 //
 //	var geonameID int
-//	err := result.DecodePath(&geonameID, "subdivisions", 0, "geoname_id")
-func (r Result) DecodePath(v any, path ...any) error {
+//	found, err := result.DecodePath(&geonameID, "subdivisions", 0, "geoname_id")
+func (r Result) DecodePath(v any, path ...any) (bool, error) {
 	if r.err != nil {
-		return r.err
+		return false, r.err
 	}
 	if r.offset == notFound {
-		return nil
+		return false, nil
 	}
 	return r.decoder.DecodePath(r.offset, path, v)
 }