Switch Networks methods to iterators

Author: oschwald

.github/workflows/go.yml

@@ -8,7 +8,7 @@ jobs:
     name: Build
     strategy:
       matrix:
-        go-version: [1.21.x, 1.22.x]
+        go-version: [1.23.0-rc.1]
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:

example_test.go

@@ -63,20 +63,16 @@ func ExampleReader_Networks() {
 	}
 	defer db.Close()
 
-	networks := db.Networks()
-	for networks.Next() {
+	for result := range db.Networks() {
 		record := struct {
 			Domain string `maxminddb:"connection_type"`
 		}{}
 
-		subnet, err := networks.Network(&record)
+		err := result.Decode(&record)
 		if err != nil {
 			log.Panic(err)
 		}
-		fmt.Printf("%s: %s\n", subnet.String(), record.Domain)
-	}
-	if networks.Err() != nil {
-		log.Panic(networks.Err())
+		fmt.Printf("%s: %s\n", result.Network(), record.Domain)
 	}
 	// Output:
 	// 1.0.0.0/24: Cable/DSL
@@ -119,20 +115,15 @@ func ExampleReader_NetworksWithin() {
 		log.Panic(err)
 	}
 
-	networks := db.NetworksWithin(prefix)
-	for networks.Next() {
+	for result := range db.NetworksWithin(prefix) {
 		record := struct {
 			Domain string `maxminddb:"connection_type"`
 		}{}
-
-		subnet, err := networks.Network(&record)
+		err := result.Decode(&record)
 		if err != nil {
 			log.Panic(err)
 		}
-		fmt.Printf("%s: %s\n", subnet.String(), record.Domain)
-	}
-	if networks.Err() != nil {
-		log.Panic(networks.Err())
+		fmt.Printf("%s: %s\n", result.Network(), record.Domain)
 	}
 
 	// Output:

go.mod

@@ -1,6 +1,6 @@
 module github.com/oschwald/maxminddb-golang/v2
 
-go 1.21
+go 1.23
 
 require (
 	github.com/stretchr/testify v1.9.0

reader.go

@@ -221,14 +221,6 @@ func (r *Reader) traverseTree(ip netip.Addr, node uint, stopBit int) (uint, int)
 	return node, i
 }
 
-func (r *Reader) retrieveData(pointer uint, result any) error {
-	offset, err := r.resolveDataPointer(pointer)
-	if err != nil {
-		return err
-	}
-	return Result{decoder: r.decoder, offset: uint(offset)}.Decode(result)
-}
-
 func (r *Reader) resolveDataPointer(pointer uint) (uintptr, error) {
 	resolved := uintptr(pointer - r.Metadata.NodeCount - dataSectionSeparatorSize)
 

traverse.go

@@ -3,6 +3,8 @@ package maxminddb
 import (
 	"fmt"
 	"net/netip"
+
+	"iter"
 )
 
 // Internal structure used to keep track of nodes we still need to visit.
@@ -12,8 +14,8 @@ type netNode struct {
 	pointer uint
 }
 
-// Networks represents a set of subnets that we are iterating over.
-type Networks struct {
+// networks represents a set of subnets that we are iterating over.
+type networks struct {
 	err                    error
 	reader                 *Reader
 	nodes                  []netNode
@@ -27,12 +29,12 @@ var (
 )
 
 // NetworksOption are options for Networks and NetworksWithin.
-type NetworksOption func(*Networks)
+type NetworksOption func(*networks)
 
 // IncludeAliasedNetworks is an option for Networks and NetworksWithin
 // that makes them iterate over aliases of the IPv4 subtree in an IPv6
 // database, e.g., ::ffff:0:0/96, 2001::/32, and 2002::/16.
-func IncludeAliasedNetworks(networks *Networks) {
+func IncludeAliasedNetworks(networks *networks) {
 	networks.includeAliasedNetworks = true
 }
 
@@ -43,15 +45,11 @@ func IncludeAliasedNetworks(networks *Networks) {
 // in an IPv6 database. This iterator will only iterate over these once by
 // default. To iterate over all the IPv4 network locations, use the
 // IncludeAliasedNetworks option.
-func (r *Reader) Networks(options ...NetworksOption) *Networks {
-	var networks *Networks
+func (r *Reader) Networks(options ...NetworksOption) iter.Seq[Result] {
 	if r.Metadata.IPVersion == 6 {
-		networks = r.NetworksWithin(allIPv6, options...)
-	} else {
-		networks = r.NetworksWithin(allIPv4, options...)
+		return r.NetworksWithin(allIPv6, options...)
 	}
-
-	return networks
+	return r.NetworksWithin(allIPv4, options...)
 }
 
 // NetworksWithin returns an iterator that can be used to traverse all networks
@@ -64,17 +62,49 @@ func (r *Reader) Networks(options ...NetworksOption) *Networks {
 //
 // If the provided prefix is contained within a network in the database, the
 // iterator will iterate over exactly one network, the containing network.
-func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption) *Networks {
+func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption) iter.Seq[Result] {
+	n := r.networksWithin(prefix, options...)
+	return func(yield func(Result) bool) {
+		for n.next() {
+			if n.err != nil {
+				yield(Result{err: n.err})
+				return
+			}
+
+			ip := n.lastNode.ip
+			if isInIPv4Subtree(ip) {
+				ip = v6ToV4(ip)
+			}
+
+			offset, err := r.resolveDataPointer(n.lastNode.pointer)
+			ok := yield(Result{
+				decoder:   r.decoder,
+				ip:        ip,
+				offset:    uint(offset),
+				prefixLen: uint8(n.lastNode.bit),
+				err:       err,
+			})
+			if !ok {
+				return
+			}
+		}
+		if n.err != nil {
+			yield(Result{err: n.err})
+		}
+	}
+}
+
+func (r *Reader) networksWithin(prefix netip.Prefix, options ...NetworksOption) *networks {
 	if r.Metadata.IPVersion == 4 && prefix.Addr().Is6() {
-		return &Networks{
+		return &networks{
 			err: fmt.Errorf(
 				"error getting networks with '%s': you attempted to use an IPv6 network in an IPv4-only database",
 				prefix,
 			),
 		}
 	}
 
-	networks := &Networks{reader: r}
+	networks := &networks{reader: r}
 	for _, option := range options {
 		option(networks)
 	}
@@ -105,10 +135,10 @@ func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption)
 	return networks
 }
 
-// Next prepares the next network for reading with the Network method. It
+// next prepares the next network for reading with the Network method. It
 // returns true if there is another network to be processed and false if there
 // are no more networks or if there is an error.
-func (n *Networks) Next() bool {
+func (n *networks) next() bool {
 	if n.err != nil {
 		return false
 	}
@@ -160,32 +190,6 @@ func (n *Networks) Next() bool {
 	return false
 }
 
-// Network returns the current network or an error if there is a problem
-// decoding the data for the network. It takes a pointer to a result value to
-// decode the network's data into.
-func (n *Networks) Network(result any) (netip.Prefix, error) {
-	if n.err != nil {
-		return netip.Prefix{}, n.err
-	}
-	if err := n.reader.retrieveData(n.lastNode.pointer, result); err != nil {
-		return netip.Prefix{}, err
-	}
-
-	ip := n.lastNode.ip
-	prefixLength := int(n.lastNode.bit)
-	if isInIPv4Subtree(ip) {
-		ip = v6ToV4(ip)
-		prefixLength -= 96
-	}
-
-	return netip.PrefixFrom(ip, prefixLength), nil
-}
-
-// Err returns an error, if any, that was encountered during iteration.
-func (n *Networks) Err() error {
-	return n.err
-}
-
 var ipv4SubtreeBoundary = netip.MustParseAddr("::255.255.255.255").Next()
 
 // isInIPv4Subtree returns true if the IP is in the database's IPv4 subtree.

traverse_test.go

@@ -20,18 +20,18 @@ func TestNetworks(t *testing.T) {
 			reader, err := Open(fileName)
 			require.NoError(t, err, "unexpected error while opening database: %v", err)
 
-			n := reader.Networks()
-			for n.Next() {
+			for result := range reader.Networks() {
 				record := struct {
 					IP string `maxminddb:"ip"`
 				}{}
-				network, err := n.Network(&record)
+				err := result.Decode(&record)
 				require.NoError(t, err)
+
+				network := result.Network()
 				assert.Equal(t, record.IP, network.Addr().String(),
 					"expected %s got %s", record.IP, network.Addr().String(),
 				)
 			}
-			require.NoError(t, n.Err())
 			require.NoError(t, reader.Close())
 		}
 	}
@@ -41,13 +41,14 @@ func TestNetworksWithInvalidSearchTree(t *testing.T) {
 	reader, err := Open(testFile("MaxMind-DB-test-broken-search-tree-24.mmdb"))
 	require.NoError(t, err, "unexpected error while opening database: %v", err)
 
-	n := reader.Networks()
-	for n.Next() {
+	for result := range reader.Networks() {
 		var record any
-		_, err := n.Network(&record)
-		require.NoError(t, err)
+		err = result.Decode(&record)
+		if err != nil {
+			break
+		}
 	}
-	require.EqualError(t, n.Err(), "invalid search tree at 128.128.128.128/32")
+	require.EqualError(t, err, "invalid search tree at 128.128.128.128/32")
 
 	require.NoError(t, reader.Close())
 }
@@ -285,20 +286,18 @@ func TestNetworksWithin(t *testing.T) {
 				require.NoError(t, err)
 
 				require.NoError(t, err)
-				n := reader.NetworksWithin(network, v.Options...)
 				var innerIPs []string
 
-				for n.Next() {
+				for result := range reader.NetworksWithin(network, v.Options...) {
 					record := struct {
 						IP string `maxminddb:"ip"`
 					}{}
-					network, err := n.Network(&record)
+					err := result.Decode(&record)
 					require.NoError(t, err)
-					innerIPs = append(innerIPs, network.String())
+					innerIPs = append(innerIPs, result.Network().String())
 				}
 
 				assert.Equal(t, v.Expected, innerIPs)
-				require.NoError(t, n.Err())
 
 				require.NoError(t, reader.Close())
 			})
@@ -326,20 +325,18 @@ func TestGeoIPNetworksWithin(t *testing.T) {
 
 		prefix, err := netip.ParsePrefix(v.Network)
 		require.NoError(t, err)
-		n := reader.NetworksWithin(prefix)
 		var innerIPs []string
 
-		for n.Next() {
+		for result := range reader.NetworksWithin(prefix) {
 			record := struct {
 				IP string `maxminddb:"ip"`
 			}{}
-			network, err := n.Network(&record)
+			err := result.Decode(&record)
 			require.NoError(t, err)
-			innerIPs = append(innerIPs, network.String())
+			innerIPs = append(innerIPs, result.Network().String())
 		}
 
 		assert.Equal(t, v.Expected, innerIPs)
-		require.NoError(t, n.Err())
 
 		require.NoError(t, reader.Close())
 	}

verifier.go

@@ -102,16 +102,11 @@ func (v *verifier) verifyDatabase() error {
 func (v *verifier) verifySearchTree() (map[uint]bool, error) {
 	offsets := make(map[uint]bool)
 
-	it := v.reader.Networks()
-	for it.Next() {
-		offset, err := v.reader.resolveDataPointer(it.lastNode.pointer)
-		if err != nil {
+	for result := range v.reader.Networks() {
+		if err := result.Err(); err != nil {
 			return nil, err
 		}
-		offsets[uint(offset)] = true
-	}
-	if err := it.Err(); err != nil {
-		return nil, err
+		offsets[result.offset] = true
 	}
 	return offsets, nil
 }