Add thread-safe bounded string cache

Replaces unbounded cache with fixed 512-entry array using offset-based
indexing. Provides 15% performance improvement while preventing memory
growth and ensuring thread safety for concurrent reader usage.

Author: oschwald

CHANGELOG.md

@@ -27,6 +27,10 @@
   Pointer format. For example, errors may now show "at offset 1234, path
   /city/names/en" or "at offset 1234, path /list/0/name" instead of just the
   underlying error message.
+- **PERFORMANCE**: Added bounded string interning optimization that provides
+  ~15% performance improvement for City lookups while maintaining thread safety
+  for concurrent reader usage. Uses a fixed 512-entry cache with offset-based
+  indexing to prevent unbounded memory growth.
 
 ## 2.0.0-beta.3 - 2025-02-16
 

internal/decoder/data_decoder.go

@@ -108,7 +108,8 @@ func (k Kind) IsScalar() bool {
 // DataDecoder is a decoder for the MMDB data section.
 // This is exported so mmdbdata package can use it, but still internal.
 type DataDecoder struct {
-	buffer []byte
+	stringCache *StringCache
+	buffer      []byte
 }
 
 const (
@@ -118,7 +119,10 @@ const (
 
 // NewDataDecoder creates a [DataDecoder].
 func NewDataDecoder(buffer []byte) DataDecoder {
-	return DataDecoder{buffer: buffer}
+	return DataDecoder{
+		buffer:      buffer,
+		stringCache: NewStringCache(),
+	}
 }
 
 // Buffer returns the underlying buffer for direct access.
@@ -239,7 +243,8 @@ func (d *DataDecoder) DecodeString(size, offset uint) (string, uint, error) {
 	}
 
 	newOffset := offset + size
-	return string(d.buffer[offset:newOffset]), newOffset, nil
+	value := d.stringCache.InternAt(offset, size, d.buffer)
+	return value, newOffset, nil
 }
 
 // DecodeUint16 decodes a 16-bit unsigned integer from the given offset.

internal/decoder/reflection.go

@@ -672,9 +672,9 @@ func (d *ReflectionDecoder) decodeMap(
 	elemType := mapType.Elem()
 	var elemValue reflect.Value
 	for range size {
-		var key []byte
 		var err error
-		key, offset, err = d.DecodeKey(offset)
+
+		offset, err = d.decode(offset, keyValue, depth)
 		if err != nil {
 			return 0, err
 		}
@@ -687,10 +687,9 @@ func (d *ReflectionDecoder) decodeMap(
 
 		offset, err = d.decode(offset, elemValue, depth)
 		if err != nil {
-			return 0, d.wrapErrorWithMapKey(err, string(key))
+			return 0, d.wrapErrorWithMapKey(err, keyValue.String())
 		}
 
-		keyValue.SetString(string(key)) // This uses the compiler optimization
 		result.SetMapIndex(keyValue, elemValue)
 	}
 	return offset, nil

internal/decoder/string_cache.go

@@ -0,0 +1,66 @@
+package decoder
+
+import "sync"
+
+// StringCache provides bounded string interning using offset-based indexing.
+// Similar to encoding/json/v2's intern.go but uses offsets instead of hashing.
+// Thread-safe for concurrent use.
+type StringCache struct {
+	// Fixed-size cache to prevent unbounded memory growth
+	// Using 512 entries for 8KiB total memory footprint (512 * 16 bytes per string)
+	cache [512]cacheEntry
+	// RWMutex for thread safety - allows concurrent reads, exclusive writes
+	mu sync.RWMutex
+}
+
+type cacheEntry struct {
+	str    string
+	offset uint
+}
+
+// NewStringCache creates a new bounded string cache.
+func NewStringCache() *StringCache {
+	return &StringCache{}
+}
+
+// InternAt returns a canonical string for the data at the given offset and size.
+// Uses the offset modulo cache size as the index, similar to json/v2's approach.
+// Thread-safe for concurrent use.
+func (sc *StringCache) InternAt(offset, size uint, data []byte) string {
+	const (
+		minCachedLen = 2   // single byte strings not worth caching
+		maxCachedLen = 100 // reasonable upper bound for geographic strings
+	)
+
+	// Skip caching for very short or very long strings
+	if size < minCachedLen || size > maxCachedLen {
+		return string(data[offset : offset+size])
+	}
+
+	// Use offset as cache index (modulo cache size)
+	i := offset % uint(len(sc.cache))
+
+	// Fast path: check for cache hit with read lock
+	sc.mu.RLock()
+	entry := sc.cache[i]
+	if entry.offset == offset && len(entry.str) == int(size) {
+		str := entry.str
+		sc.mu.RUnlock()
+		return str
+	}
+	sc.mu.RUnlock()
+
+	// Cache miss - create new string and store with write lock
+	str := string(data[offset : offset+size])
+
+	sc.mu.Lock()
+	// Double-check in case another goroutine added it while we were waiting
+	if sc.cache[i].offset == offset && len(sc.cache[i].str) == int(size) {
+		str = sc.cache[i].str
+	} else {
+		sc.cache[i] = cacheEntry{offset: offset, str: str}
+	}
+	sc.mu.Unlock()
+
+	return str
+}