Add support for UnmarshalMaxMinDB

Author: oschwald

CHANGELOG.md

@@ -6,6 +6,13 @@
 - `IncludeNetworksWithoutData` and `IncludeAliasedNetworks` now return a
   `NetworksOption` rather than being one themselves. This was done to improve
   the documentation organization.
+- Added `Unmarshaler` interface to allow custom decoding implementations for
+  performance-critical applications. Types implementing
+  `UnmarshalMaxMindDB(d *Decoder) error` will automatically use custom
+  decoding logic instead of reflection, following the same pattern as
+  `json.Unmarshaler`.
+- Added public `Decoder` type with methods for manual decoding including
+  `DecodeMap()`, `DecodeSlice()`, `DecodeString()`, `DecodeUInt32()`, etc.
 
 ## 2.0.0-beta.3 - 2025-02-16
 

decoder.go

@@ -0,0 +1,47 @@
+package maxminddb
+
+import "github.com/oschwald/maxminddb-golang/v2/internal/decoder"
+
+// Decoder provides methods for decoding MaxMind DB data values.
+// This interface is passed to UnmarshalMaxMindDB methods to allow
+// custom decoding logic that avoids reflection for performance-critical applications.
+//
+// Types implementing Unmarshaler will automatically use custom decoding logic
+// instead of reflection when used with Reader.Lookup, providing better performance
+// for performance-critical applications.
+//
+// Example:
+//
+//	type City struct {
+//		Names     map[string]string `maxminddb:"names"`
+//		GeoNameID uint              `maxminddb:"geoname_id"`
+//	}
+//
+//	func (c *City) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
+//		for key, err := range d.DecodeMap() {
+//			if err != nil { return err }
+//			switch string(key) {
+//			case "names":
+//				names := make(map[string]string)
+//				for nameKey, nameErr := range d.DecodeMap() {
+//					if nameErr != nil { return nameErr }
+//					value, valueErr := d.DecodeString()
+//					if valueErr != nil { return valueErr }
+//					names[string(nameKey)] = value
+//				}
+//				c.Names = names
+//			case "geoname_id":
+//				geoID, err := d.DecodeUInt32()
+//				if err != nil { return err }
+//				c.GeoNameID = uint(geoID)
+//			default:
+//				if err := d.SkipValue(); err != nil { return err }
+//			}
+//		}
+//		return nil
+//	}
+type Decoder = decoder.Decoder
+
+// Unmarshaler is implemented by types that can unmarshal MaxMind DB data.
+// This follows the same pattern as json.Unmarshaler and other Go standard library interfaces.
+type Unmarshaler = decoder.Unmarshaler

internal/decoder/decoder.go

@@ -17,52 +17,6 @@ type Decoder struct {
 	nextOffset    uint
 }
 
-func (d *Decoder) reset(offset uint) {
-	d.offset = offset
-	d.hasNextOffset = false
-	d.nextOffset = 0
-}
-
-func (d *Decoder) setNextOffset(offset uint) {
-	if !d.hasNextOffset {
-		d.hasNextOffset = true
-		d.nextOffset = offset
-	}
-}
-
-func unexpectedTypeErr(expectedType, actualType Type) error {
-	return fmt.Errorf("unexpected type %d, expected %d", actualType, expectedType)
-}
-
-func (d *Decoder) decodeCtrlDataAndFollow(expectedType Type) (uint, uint, error) {
-	dataOffset := d.offset
-	for {
-		var typeNum Type
-		var size uint
-		var err error
-		typeNum, size, dataOffset, err = d.d.decodeCtrlData(dataOffset)
-		if err != nil {
-			return 0, 0, err
-		}
-
-		if typeNum == TypePointer {
-			var nextOffset uint
-			dataOffset, nextOffset, err = d.d.decodePointer(size, dataOffset)
-			if err != nil {
-				return 0, 0, err
-			}
-			d.setNextOffset(nextOffset)
-			continue
-		}
-
-		if typeNum != expectedType {
-			return 0, 0, unexpectedTypeErr(expectedType, typeNum)
-		}
-
-		return size, dataOffset, nil
-	}
-}
-
 // DecodeBool decodes the value pointed by the decoder as a bool.
 //
 // Returns an error if the database is malformed or if the pointed value is not a bool.
@@ -85,15 +39,6 @@ func (d *Decoder) DecodeBool() (bool, error) {
 	return value, nil
 }
 
-func (d *Decoder) decodeBytes(typ Type) ([]byte, error) {
-	size, offset, err := d.decodeCtrlDataAndFollow(typ)
-	if err != nil {
-		return nil, err
-	}
-	d.setNextOffset(offset + size)
-	return d.d.buffer[offset : offset+size], nil
-}
-
 // DecodeString decodes the value pointed by the decoder as a string.
 //
 // Returns an error if the database is malformed or if the pointed value is not a string.
@@ -382,3 +327,71 @@ func (d *Decoder) DecodeSlice() iter.Seq[error] {
 		d.reset(currentOffset)
 	}
 }
+
+// SkipValue skips over the current value without decoding it.
+// This is useful in custom decoders when encountering unknown fields.
+// The decoder will be positioned after the skipped value.
+func (d *Decoder) SkipValue() error {
+	// We can reuse the existing nextValueOffset logic by jumping to the next value
+	nextOffset, err := d.d.nextValueOffset(d.offset, 1)
+	if err != nil {
+		return err
+	}
+	d.reset(nextOffset)
+	return nil
+}
+
+func (d *Decoder) reset(offset uint) {
+	d.offset = offset
+	d.hasNextOffset = false
+	d.nextOffset = 0
+}
+
+func (d *Decoder) setNextOffset(offset uint) {
+	if !d.hasNextOffset {
+		d.hasNextOffset = true
+		d.nextOffset = offset
+	}
+}
+
+func unexpectedTypeErr(expectedType, actualType Type) error {
+	return fmt.Errorf("unexpected type %d, expected %d", actualType, expectedType)
+}
+
+func (d *Decoder) decodeCtrlDataAndFollow(expectedType Type) (uint, uint, error) {
+	dataOffset := d.offset
+	for {
+		var typeNum Type
+		var size uint
+		var err error
+		typeNum, size, dataOffset, err = d.d.decodeCtrlData(dataOffset)
+		if err != nil {
+			return 0, 0, err
+		}
+
+		if typeNum == TypePointer {
+			var nextOffset uint
+			dataOffset, nextOffset, err = d.d.decodePointer(size, dataOffset)
+			if err != nil {
+				return 0, 0, err
+			}
+			d.setNextOffset(nextOffset)
+			continue
+		}
+
+		if typeNum != expectedType {
+			return 0, 0, unexpectedTypeErr(expectedType, typeNum)
+		}
+
+		return size, dataOffset, nil
+	}
+}
+
+func (d *Decoder) decodeBytes(typ Type) ([]byte, error) {
+	size, offset, err := d.decodeCtrlDataAndFollow(typ)
+	if err != nil {
+		return nil, err
+	}
+	d.setNextOffset(offset + size)
+	return d.d.buffer[offset : offset+size], nil
+}