Replace LookupOffset/Decode with RecordKey

Author: oschwald

reader.go

@@ -156,48 +156,8 @@ 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
-// data or an empty any value.
-//
-// If result is a pointer to a struct, the struct need not include a field
-// for every value that may be in the database. If a field is not present in
-// the structure, the decoder will not decode that field, reducing the time
-// required to decode the record.
-//
-// As a special case, a struct field of type uintptr will be used to capture
-// the offset of the value. Decode may later be used to extract the stored
-// value from the offset. MaxMind DBs are highly normalized: for example in
-// the City database, all records of the same country will reference a
-// single representative record for that country. This uintptr behavior allows
-// clients to leverage this normalization in their own sub-record caching.
-func (r *Reader) Decode(offset uintptr, result any) error {
-	if r.buffer == nil {
-		return errors.New("cannot call Decode on a closed database")
-	}
-
-	return Result{decoder: r.decoder, offset: uint(offset)}.Decode(result)
-}
-
 func (r *Reader) lookupPointer(ip netip.Addr) (uint, int, error) {
 	if r.Metadata.IPVersion == 4 && ip.Is6() {
 		return 0, 0, fmt.Errorf(

result.go

@@ -107,6 +107,16 @@ func (r Result) Found() bool {
 	return r.err == nil && r.offset != notFound
 }
 
+// RecordKey returns a unique identifier for the data record in the particular
+// database. This can be used to cache the data record across lookups. Note
+// that while the key uniquely identifies the data record, other data in Result
+// may differ between lookups. The key 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) RecordKey() uint {
+	return r.offset
+}
+
 // Network returns the netip.Prefix representing the network associated with
 // the data record in the database.
 func (r Result) Network() netip.Prefix {