perf: dual-child read + traversal tweaks

Author: oschwald

reader.go

@@ -515,6 +515,67 @@ func readNodeBySize(buffer []byte, offset, bit, recordSize uint) (uint, error) {
 	}
 }
 
+// readNodePairBySize reads both left (bit=0) and right (bit=1) child pointers
+// for a node at the given base offset according to the record size. This reduces
+// duplicate bound checks and byte fetches when both children are needed.
+func readNodePairBySize(buffer []byte, baseOffset, recordSize uint) (left, right uint, err error) {
+	bufferLen := uint(len(buffer))
+	switch recordSize {
+	case 24:
+		// Each child is 3 bytes; total 6 bytes starting at baseOffset
+		if baseOffset > bufferLen-6 {
+			return 0, 0, mmdberrors.NewInvalidDatabaseError(
+				"bounds check failed: insufficient buffer for 24-bit node pair read",
+			)
+		}
+		o := baseOffset
+		left = (uint(buffer[o]) << 16) | (uint(buffer[o+1]) << 8) | uint(buffer[o+2])
+		o += 3
+		right = (uint(buffer[o]) << 16) | (uint(buffer[o+1]) << 8) | uint(buffer[o+2])
+		return left, right, nil
+	case 28:
+		// Left uses high nibble of shared byte, right uses low nibble.
+		// Layout: [A B C S][D E F] where S provides 4 shared bits for each child
+		if baseOffset > bufferLen-7 {
+			return 0, 0, mmdberrors.NewInvalidDatabaseError(
+				"bounds check failed: insufficient buffer for 28-bit node pair read",
+			)
+		}
+		// Left child (bit=0): uses high nibble of shared byte
+		shared := uint(buffer[baseOffset+3])
+		left = ((shared & 0xF0) << 20) |
+			(uint(buffer[baseOffset]) << 16) |
+			(uint(buffer[baseOffset+1]) << 8) |
+			uint(buffer[baseOffset+2])
+		// Right child (bit=1): uses low nibble of shared byte, next 3 bytes
+		right = ((shared & 0x0F) << 24) |
+			(uint(buffer[baseOffset+4]) << 16) |
+			(uint(buffer[baseOffset+5]) << 8) |
+			uint(buffer[baseOffset+6])
+		return left, right, nil
+	case 32:
+		// Each child is 4 bytes; total 8 bytes
+		if baseOffset > bufferLen-8 {
+			return 0, 0, mmdberrors.NewInvalidDatabaseError(
+				"bounds check failed: insufficient buffer for 32-bit node pair read",
+			)
+		}
+		o := baseOffset
+		left = (uint(buffer[o]) << 24) |
+			(uint(buffer[o+1]) << 16) |
+			(uint(buffer[o+2]) << 8) |
+			uint(buffer[o+3])
+		o += 4
+		right = (uint(buffer[o]) << 24) |
+			(uint(buffer[o+1]) << 16) |
+			(uint(buffer[o+2]) << 8) |
+			uint(buffer[o+3])
+		return left, right, nil
+	default:
+		return 0, 0, mmdberrors.NewInvalidDatabaseError("unsupported record size")
+	}
+}
+
 func (r *Reader) traverseTree(ip netip.Addr, node uint, stopBit int) (uint, int, error) {
 	switch r.Metadata.RecordSize {
 	case 24:

traverse.go

@@ -223,8 +223,12 @@ func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption)
 				}
 				ipRight[node.bit>>3] |= 1 << (7 - (node.bit % 8))
 
-				offset := node.pointer * r.nodeOffsetMult
-				rightPointer, err := readNodeBySize(r.buffer, offset, 1, r.Metadata.RecordSize)
+				baseOffset := node.pointer * r.nodeOffsetMult
+				leftPointer, rightPointer, err := readNodePairBySize(
+					r.buffer,
+					baseOffset,
+					r.Metadata.RecordSize,
+				)
 				if err != nil {
 					yield(Result{
 						ip:        mappedIP(node.ip),
@@ -241,15 +245,6 @@ func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption)
 					bit:     node.bit,
 				})
 
-				leftPointer, err := readNodeBySize(r.buffer, offset, 0, r.Metadata.RecordSize)
-				if err != nil {
-					yield(Result{
-						ip:        mappedIP(node.ip),
-						prefixLen: uint8(node.bit),
-						err:       err,
-					})
-					return
-				}
 				node.pointer = leftPointer
 			}
 		}