Replace LookupOffset with RecordOffset

Author: oschwald

reader.go

@@ -9,13 +9,7 @@ import (
 	"reflect"
 )
 
-const (
-	// NotFound is returned by LookupOffset when a matched root record offset
-	// cannot be found.
-	NotFound = ^uintptr(0)
-
-	dataSectionSeparatorSize = 16
-)
+const dataSectionSeparatorSize = 16
 
 var metadataStartMarker = []byte("\xAB\xCD\xEFMaxMind.com")
 
@@ -156,24 +150,6 @@ func (r *Reader) Lookup(ip netip.Addr) Result {
 	}
 }
 
-// LookupOffset maps an argument net.IP to a corresponding record offset in the
-// database. NotFound is returned if no such record is found, and a record may
-// otherwise be extracted by passing the returned offset to Decode. LookupOffset
-// is an advanced API, which exists to provide clients with a means to cache
-// previously-decoded records.
-func (r *Reader) LookupOffset(ip netip.Addr) (uintptr, error) {
-	if r.buffer == nil {
-		return 0, errors.New("cannot call LookupOffset on a closed database")
-	}
-	pointer, _, err := r.lookupPointer(ip)
-	if pointer == 0 || err != nil {
-		return NotFound, err
-	}
-	return r.resolveDataPointer(pointer)
-}
-
-var zeroIP = netip.MustParseAddr("::")
-
 // Decode the record at |offset| into |result|. The result value pointed to
 // must be a data value that corresponds to a record in the database. This may
 // include a struct representation of the data, a map capable of holding the
@@ -198,6 +174,8 @@ func (r *Reader) Decode(offset uintptr, result any) error {
 	return Result{decoder: r.decoder, offset: uint(offset)}.Decode(result)
 }
 
+var zeroIP = netip.MustParseAddr("::")
+
 func (r *Reader) lookupPointer(ip netip.Addr) (uint, int, error) {
 	if r.Metadata.IPVersion == 4 && ip.Is6() {
 		return 0, 0, fmt.Errorf(

reader_test.go

@@ -300,19 +300,19 @@ func TestDecoder(t *testing.T) {
 
 	{
 		// Directly lookup and decode.
-		var result TestType
-		require.NoError(t, reader.Lookup(netip.MustParseAddr("::1.1.1.0")).Decode(&result))
-		verify(result)
+		var testV TestType
+		require.NoError(t, reader.Lookup(netip.MustParseAddr("::1.1.1.0")).Decode(&testV))
+		verify(testV)
 	}
 	{
 		// Lookup record offset, then Decode.
-		var result TestType
-		offset, err := reader.LookupOffset(netip.MustParseAddr("::1.1.1.0"))
-		require.NoError(t, err)
-		assert.NotEqual(t, NotFound, offset)
+		var testV TestType
+		result := reader.Lookup(netip.MustParseAddr("::1.1.1.0"))
+		require.NoError(t, result.Err())
+		require.True(t, result.Found())
 
-		require.NoError(t, reader.Decode(offset, &result))
-		verify(result)
+		require.NoError(t, reader.Decode(result.RecordOffset(), &testV))
+		verify(testV)
 	}
 
 	require.NoError(t, reader.Close())
@@ -548,9 +548,9 @@ func TestNestedOffsetDecode(t *testing.T) {
 	db, err := Open(testFile("GeoIP2-City-Test.mmdb"))
 	require.NoError(t, err)
 
-	off, err := db.LookupOffset(netip.MustParseAddr("81.2.69.142"))
-	assert.NotEqual(t, NotFound, off)
-	require.NoError(t, err)
+	result := db.Lookup(netip.MustParseAddr("81.2.69.142"))
+	require.NoError(t, result.Err())
+	require.True(t, result.Found())
 
 	var root struct {
 		CountryOffset uintptr `maxminddb:"country"`
@@ -563,7 +563,7 @@ func TestNestedOffsetDecode(t *testing.T) {
 			TimeZoneOffset uintptr `maxminddb:"time_zone"`
 		} `maxminddb:"location"`
 	}
-	require.NoError(t, db.Decode(off, &root))
+	require.NoError(t, db.Decode(result.RecordOffset(), &root))
 	assert.InEpsilon(t, 51.5142, root.Location.Latitude, 1e-10)
 
 	var longitude float64
@@ -671,14 +671,15 @@ func TestUsingClosedDatabase(t *testing.T) {
 	require.NoError(t, err)
 	require.NoError(t, reader.Close())
 
-	var recordInterface any
 	addr := netip.MustParseAddr("::")
+
+	result := reader.Lookup(addr)
+	assert.Equal(t, "cannot call Lookup on a closed database", result.Err().Error())
+
+	var recordInterface any
 	err = reader.Lookup(addr).Decode(recordInterface)
 	assert.Equal(t, "cannot call Lookup on a closed database", err.Error())
 
-	_, err = reader.LookupOffset(addr)
-	assert.Equal(t, "cannot call LookupOffset on a closed database", err.Error())
-
 	err = reader.Decode(0, recordInterface)
 	assert.Equal(t, "cannot call Decode on a closed database", err.Error())
 }

result.go

@@ -95,7 +95,7 @@ func (r Result) DecodePath(v any, path ...any) error {
 }
 
 // Err provides a way to check whether there was an error during the lookup
-// without clling Result.Decode. If there was an error, it will also be
+// without calling Result.Decode. If there was an error, it will also be
 // returned from Result.Decode.
 func (r Result) Err() error {
 	return r.err
@@ -107,6 +107,17 @@ func (r Result) Found() bool {
 	return r.err == nil && r.offset != notFound
 }
 
+// RecordOffset returns the offset of the record in the database. This can be
+// passed to ReaderDecode. It can also be used as a unique identifier for the
+// data record in the particular database to cache the data record across
+// lookups. Note that while the offset uniquely identifies the data record,
+// other data in Result  may differ between lookups. The offset is only valid
+// for the current database version. If you update the database file, you must
+// invalidate any cache associated with the previous version.
+func (r Result) RecordOffset() uintptr {
+	return uintptr(r.offset)
+}
+
 // Network returns the netip.Prefix representing the network associated with
 // the data record in the database.
 func (r Result) Network() netip.Prefix {