maxmind-db-rust 0.3.0 → 0.5.0

data/ext/maxmind_db_rust/src/lib.rs

@@ -5,25 +5,26 @@ use ::maxminddb as maxminddb_crate;
 use arc_swap::{ArcSwapOption, Guard};
 use ipnetwork::IpNetwork;
 use magnus::{
-    error::Error, prelude::*, scan_args::get_kwargs, scan_args::scan_args, ExceptionClass,
-    IntoValue, RArray, RClass, RHash, RModule, RString, Symbol, Value,
+    error::Error, prelude::*, scan_args::get_kwargs, scan_args::scan_args, typed_data::Obj,
+    ExceptionClass, IntoValue, RArray, RClass, RHash, RModule, RString, Symbol, Value,
 };
-use maxminddb_crate::{MaxMindDbError, Reader as MaxMindReader, Within};
+use maxminddb_crate::{MaxMindDbError, PathElement, Reader as MaxMindReader, Within};
 use memmap2::Mmap;
-use rustc_hash::FxHashMap;
+use rustc_hash::FxHasher;
 use serde::de::{self, Deserialize, DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
 use std::{
-    cell::RefCell,
-    collections::BTreeMap,
+    cell::{OnceCell, RefCell},
+    collections::{BTreeMap, VecDeque},
     fmt,
     fs::File,
+    hash::{Hash, Hasher},
     io::Read as IoRead,
-    net::IpAddr,
+    net::{IpAddr, Ipv4Addr},
     path::Path,
     str::FromStr,
     sync::{
         atomic::{AtomicBool, Ordering},
-        Arc,
+        Arc, Mutex,
     },
 };
 
@@ -31,57 +32,95 @@ use std::{
 const ERR_CLOSED_DB: &str = "Attempt to read from a closed MaxMind DB.";
 const ERR_BAD_DATA: &str =
     "The MaxMind DB file's data section contains bad data (unknown data type or corrupt data)";
+const STRING_CACHE_ROOTS_CONST: &str = "__STRING_CACHE_ROOTS__";
+const MAP_KEY_ROOTS_CONST: &str = "__MAP_KEY_ROOTS__";
+const STRING_CACHE_MAX: usize = 4096;
+const STRING_CACHE_MIN_LEN: usize = 2;
+const STRING_CACHE_MAX_LEN: usize = 64;
+const PATH_CACHE_MAX_ENTRIES: usize = 64;
+
+#[derive(Default)]
+struct StringCacheEntry {
+    hash: u64,
+    value: String,
+}
 
-thread_local! {
-    static MAP_KEY_CACHE: RefCell<MapKeyCache> = RefCell::new(MapKeyCache::new());
+struct StringCache {
+    entries: Box<[StringCacheEntry]>,
 }
 
-const MAP_KEY_CACHE_MAX: usize = 256;
-const MAP_KEY_ROOTS_CONST: &str = "__MAP_KEY_ROOTS__";
+impl StringCache {
+    fn new() -> Self {
+        let entries = (0..STRING_CACHE_MAX)
+            .map(|_| StringCacheEntry::default())
+            .collect::<Vec<_>>()
+            .into_boxed_slice();
+        Self { entries }
+    }
+}
 
-struct MapKeyCache {
-    key_to_index: FxHashMap<String, usize>,
+thread_local! {
+    static STRING_CACHE: RefCell<StringCache> = RefCell::new(StringCache::new());
+    static STRING_CACHE_ROOTS: OnceCell<RArray> = const { OnceCell::new() };
 }
 
-impl MapKeyCache {
-    #[inline]
-    fn new() -> Self {
-        Self {
-            key_to_index: FxHashMap::default(),
-        }
+#[inline]
+fn string_cache_roots_owner(ruby: &magnus::Ruby) -> RArray {
+    let value = rust_module(ruby)
+        .const_get::<_, Value>(STRING_CACHE_ROOTS_CONST)
+        .expect("string cache roots constant should exist");
+    RArray::from_value(value).expect("string cache roots constant should be an array")
+}
+
+#[inline]
+fn init_thread_string_cache_roots(ruby: &magnus::Ruby) -> RArray {
+    let roots = ruby.ary_new_capa(STRING_CACHE_MAX);
+    for _ in 0..STRING_CACHE_MAX {
+        roots
+            .push(ruby.qnil().as_value())
+            .expect("string cache roots initialization should succeed");
     }
+    string_cache_roots_owner(ruby)
+        .push(roots.as_value())
+        .expect("string cache roots owner should retain per-thread roots");
+    roots
 }
 
 #[inline]
-fn map_key_roots_array(ruby: &magnus::Ruby) -> RArray {
-    let rust = rust_module(ruby);
-    let roots = rust
-        .const_get::<_, Value>(MAP_KEY_ROOTS_CONST)
-        .expect("map key roots constant should exist");
-    RArray::from_value(roots).expect("map key roots constant should be an array")
+fn string_cache_roots(ruby: &magnus::Ruby) -> RArray {
+    STRING_CACHE_ROOTS.with(|roots| *roots.get_or_init(|| init_thread_string_cache_roots(ruby)))
 }
 
 #[inline]
-fn cached_map_key(ruby: &magnus::Ruby, key: &str) -> Value {
-    MAP_KEY_CACHE.with(|cache| {
-        let mut cache = cache.borrow_mut();
-        let roots = map_key_roots_array(ruby);
-        if let Some(index) = cache.key_to_index.get(key) {
-            return roots
-                .entry::<Value>(*index as isize)
-                .expect("cached map key index should be valid");
-        }
+fn cached_string(ruby: &magnus::Ruby, value: &str) -> Value {
+    if !(STRING_CACHE_MIN_LEN..=STRING_CACHE_MAX_LEN).contains(&value.len()) {
+        return ruby.str_new(value).into_value_with(ruby);
+    }
 
-        let interned = ruby.str_new(key).to_interned_str();
-        let value = interned.as_value();
-        if cache.key_to_index.len() < MAP_KEY_CACHE_MAX {
-            let index = roots.len();
-            roots
-                .push(value)
-                .expect("map key roots array push should succeed");
-            cache.key_to_index.insert(key.to_owned(), index);
+    let mut hasher = FxHasher::default();
+    value.hash(&mut hasher);
+    let hash = hasher.finish();
+    let slot = (hash as usize) & (STRING_CACHE_MAX - 1);
+
+    STRING_CACHE.with(|cache_cell| {
+        let mut cache = cache_cell.borrow_mut();
+        let entry = &mut cache.entries[slot];
+        if entry.hash == hash && entry.value == value {
+            return string_cache_roots(ruby)
+                .entry::<Value>(slot as isize)
+                .expect("string cache roots lookup should succeed");
         }
-        value
+
+        let string = ruby.str_new(value);
+        string.freeze();
+        let cached = string.as_value();
+        string_cache_roots(ruby)
+            .store(slot as isize, cached)
+            .expect("string cache roots update should succeed");
+        entry.hash = hash;
+        entry.value.clear();
+        entry.value.push_str(value);
+        cached
     })
 }
 
@@ -214,18 +253,14 @@ impl<'de, 'ruby> Visitor<'de> for RubyValueVisitor<'ruby> {
     where
         E: de::Error,
     {
-        Ok(RubyDecodedValue::new(
-            self.ruby.str_new(value).into_value_with(self.ruby),
-        ))
+        Ok(RubyDecodedValue::new(cached_string(self.ruby, value)))
     }
 
     fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
     where
         E: de::Error,
     {
-        Ok(RubyDecodedValue::new(
-            self.ruby.str_new(&value).into_value_with(self.ruby),
-        ))
+        Ok(RubyDecodedValue::new(cached_string(self.ruby, &value)))
     }
 
     fn visit_bytes<E>(self, value: &[u8]) -> Result<Self::Value, E>
@@ -270,8 +305,8 @@ impl<'de, 'ruby> Visitor<'de> for RubyValueVisitor<'ruby> {
             None => self.ruby.hash_new(),
         };
         while let Some(key) = map.next_key::<&'de str>()? {
-            let key_val = cached_map_key(self.ruby, key);
             let value = map.next_value_seed(RubyValueSeed { ruby: self.ruby })?;
+            let key_val = cached_string(self.ruby, key);
             hash.aset(key_val, value.into_value())
                 .map_err(|e| de::Error::custom(e.to_string()))?;
         }
@@ -285,6 +320,42 @@ enum ReaderSource {
     Memory(MaxMindReader<Vec<u8>>),
 }
 
+#[derive(Copy, Clone)]
+enum OpenMode {
+    Mmap,
+    Memory,
+    Buffer,
+}
+
+impl OpenMode {
+    fn from_symbol(mode: Symbol, ruby: &magnus::Ruby) -> Result<Self, Error> {
+        let mode_name = mode.name()?;
+        match mode_name.as_ref() {
+            // MODE_FILE is the official gem's file-backed mode; use the
+            // existing mmap reader for the same path-backed behavior.
+            "MODE_AUTO" | "MODE_FILE" | "MODE_MMAP" => Ok(Self::Mmap),
+            "MODE_MEMORY" => Ok(Self::Memory),
+            "MODE_PARAM_IS_BUFFER" => Ok(Self::Buffer),
+            _ => Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("Unsupported mode: {}", mode_name),
+            )),
+        }
+    }
+}
+
+#[derive(PartialEq, Eq)]
+enum OwnedPathElement {
+    Key(String),
+    Index(usize),
+    IndexFromEnd(usize),
+}
+
+struct CachedPath {
+    hash: u64,
+    elements: Arc<[OwnedPathElement]>,
+}
+
 impl ReaderSource {
     #[inline]
     fn lookup(
@@ -302,9 +373,30 @@ impl ReaderSource {
         &self,
         ip: IpAddr,
     ) -> Result<(Option<RubyDecodedValue>, usize), maxminddb_crate::MaxMindDbError> {
+        let (result, prefix_len) = match self {
+            ReaderSource::Mmap(reader) => {
+                let result = reader.lookup(ip)?;
+                let network = result.network()?;
+                (result.decode()?, prefix_len_for_ip_network(ip, network))
+            }
+            ReaderSource::Memory(reader) => {
+                let result = reader.lookup(ip)?;
+                let network = result.network()?;
+                (result.decode()?, prefix_len_for_ip_network(ip, network))
+            }
+        };
+        Ok((result, prefix_len))
+    }
+
+    #[inline]
+    fn lookup_path(
+        &self,
+        ip: IpAddr,
+        path_elements: &[PathElement<'_>],
+    ) -> Result<Option<RubyDecodedValue>, maxminddb_crate::MaxMindDbError> {
         match self {
-            ReaderSource::Mmap(reader) => lookup_prefix_for_reader(reader, ip),
-            ReaderSource::Memory(reader) => lookup_prefix_for_reader(reader, ip),
+            ReaderSource::Mmap(reader) => reader.lookup(ip)?.decode_path(path_elements),
+            ReaderSource::Memory(reader) => reader.lookup(ip)?.decode_path(path_elements),
         }
     }
 
@@ -317,34 +409,25 @@ impl ReaderSource {
     }
 
     #[inline]
-    fn within(&self, network: IpNetwork) -> Result<ReaderWithin, MaxMindDbError> {
+    fn within(&self, network: IpNetwork) -> Result<ReaderWithin<'_>, MaxMindDbError> {
         match self {
-            ReaderSource::Mmap(reader) => {
-                let iter = reader.within(network, Default::default())?;
-                // SAFETY: the iterator holds a reference into `reader`. We'll store an Arc guard
-                // alongside it so the reader outlives the transmuted iterator.
-                Ok(ReaderWithin::Mmap(unsafe {
-                    std::mem::transmute::<Within<'_, Mmap>, Within<'static, Mmap>>(iter)
-                }))
-            }
-            ReaderSource::Memory(reader) => {
-                let iter = reader.within(network, Default::default())?;
-                // SAFETY: same as above, the Arc guard keeps the reader alive.
-                Ok(ReaderWithin::Memory(unsafe {
-                    std::mem::transmute::<Within<'_, Vec<u8>>, Within<'static, Vec<u8>>>(iter)
-                }))
-            }
+            ReaderSource::Mmap(reader) => Ok(ReaderWithin::Mmap(
+                reader.within(network, Default::default())?,
+            )),
+            ReaderSource::Memory(reader) => Ok(ReaderWithin::Memory(
+                reader.within(network, Default::default())?,
+            )),
         }
     }
 }
 
 /// Wrapper enum for Within iterators
-enum ReaderWithin {
-    Mmap(Within<'static, Mmap>),
-    Memory(Within<'static, Vec<u8>>),
+enum ReaderWithin<'reader> {
+    Mmap(Within<'reader, Mmap>),
+    Memory(Within<'reader, Vec<u8>>),
 }
 
-impl ReaderWithin {
+impl ReaderWithin<'_> {
     fn next(&mut self) -> Option<Result<(IpNetwork, RubyDecodedValue), MaxMindDbError>> {
         match self {
             ReaderWithin::Mmap(iter) => next_within_result(iter),
@@ -353,17 +436,6 @@ impl ReaderWithin {
     }
 }
 
-#[inline]
-fn lookup_prefix_for_reader<S: AsRef<[u8]>>(
-    reader: &MaxMindReader<S>,
-    ip: IpAddr,
-) -> Result<(Option<RubyDecodedValue>, usize), maxminddb_crate::MaxMindDbError> {
-    let result = reader.lookup(ip)?;
-    let network = result.network()?;
-    let prefix_len = prefix_len_for_ip_network(ip, network);
-    Ok((result.decode()?, prefix_len))
-}
-
 #[inline]
 // prefix_len_for_ip_network uses 0 as a sentinel for ip.is_ipv4() && network.is_ipv6().
 // In this case, 0 is not a real prefix length; it signals an IPv4-in-IPv6 mapping path,
@@ -378,7 +450,7 @@ fn prefix_len_for_ip_network(ip: IpAddr, network: IpNetwork) -> usize {
 
 #[inline]
 fn next_within_result<S: AsRef<[u8]>>(
-    iter: &mut Within<'static, S>,
+    iter: &mut Within<'_, S>,
 ) -> Option<Result<(IpNetwork, RubyDecodedValue), MaxMindDbError>> {
     loop {
         match iter.next() {
@@ -472,6 +544,10 @@ impl Metadata {
     }
 }
 
+// SAFETY: Metadata stores only owned Rust values copied out of the database
+// metadata. It contains no Ruby VALUE handles or borrowed database/source data,
+// so moving it between Ruby-managed threads cannot invalidate GC or lifetime
+// assumptions.
 unsafe impl Send for Metadata {}
 
 /// A Ruby wrapper around the MaxMind DB reader
@@ -480,6 +556,7 @@ unsafe impl Send for Metadata {}
 struct Reader {
     reader: Arc<ArcSwapOption<ReaderSource>>,
     closed: Arc<AtomicBool>,
+    path_cache: Arc<Mutex<VecDeque<CachedPath>>>,
     ip_version: u16,
 }
 
@@ -487,7 +564,7 @@ impl Reader {
     fn new(args: &[Value]) -> Result<Self, Error> {
         let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby method");
 
-        let args = scan_args::<(String,), (), (), (), _, ()>(args)?;
+        let args = scan_args::<(Value,), (), (), (), _, ()>(args)?;
         let (database,) = args.required;
         let kw = get_kwargs::<_, (), (Option<Symbol>,), ()>(args.keywords, &[], &["mode"])?;
         let (mode,) = kw.optional;
@@ -495,29 +572,13 @@ impl Reader {
         // Parse mode from options hash
         let mode: Symbol = mode.unwrap_or_else(|| ruby.to_symbol("MODE_AUTO"));
 
-        let mode_str = mode.name()?;
-        let mode_str: &str = &mode_str;
-
-        // Determine actual mode to use
-        let actual_mode = match mode_str {
-            "MODE_AUTO" | "MODE_MMAP" => "MMAP",
-            "MODE_MEMORY" => "MEMORY",
-            _ => {
-                return Err(Error::new(
-                    ruby.exception_arg_error(),
-                    format!("Unsupported mode: {}", mode_str),
-                ))
-            }
-        };
+        let open_mode = OpenMode::from_symbol(mode, &ruby)?;
 
         // Open database with appropriate mode
-        match actual_mode {
-            "MMAP" => open_database_mmap(&database),
-            "MEMORY" => open_database_memory(&database),
-            _ => Err(Error::new(
-                ruby.exception_arg_error(),
-                format!("Invalid mode: {}", actual_mode),
-            )),
+        match open_mode {
+            OpenMode::Mmap => open_database_mmap(&database_path(database)?),
+            OpenMode::Memory => open_database_memory(&database_path(database)?),
+            OpenMode::Buffer => open_database_buffer(database_buffer(database)?),
         }
     }
 
@@ -529,32 +590,28 @@ impl Reader {
         let reader_option = guard.as_ref();
         let reader = reader_option.as_ref().unwrap();
 
-        // Parse IP address
-        let parsed_ip = parse_ip_address_fast(ip_address, &ruby)?;
+        let parsed_ip = self.parse_lookup_ip(ip_address, &ruby)?;
 
-        if self.ip_version == 4 && matches!(parsed_ip, IpAddr::V6(_)) {
-            return Err(Error::new(
-                ruby.exception_arg_error(),
-                ipv6_in_ipv4_error(&parsed_ip),
-            ));
-        }
+        lookup_result_to_value(&ruby, reader.lookup(parsed_ip), "Database lookup failed")
+    }
 
-        // Perform lookup
-        match reader.lookup(parsed_ip) {
-            Ok(Some(data)) => Ok(data.into_value()),
-            Ok(None) => Ok(ruby.qnil().as_value()),
-            Err(MaxMindDbError::InvalidDatabase { .. }) | Err(MaxMindDbError::Io(_)) => {
-                Err(Error::new(
-                    ExceptionClass::from_value(invalid_database_error().as_value())
-                        .expect("InvalidDatabaseError should convert to ExceptionClass"),
-                    ERR_BAD_DATA,
-                ))
-            }
-            Err(e) => Err(Error::new(
-                ruby.exception_runtime_error(),
-                format!("Database lookup failed: {}", e),
-            )),
-        }
+    #[inline]
+    fn get_path(&self, ip_address: Value, path: Value) -> Result<Value, Error> {
+        let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby method");
+
+        let guard = self.get_reader(&ruby)?;
+        let reader_option = guard.as_ref();
+        let reader = reader_option.as_ref().unwrap();
+
+        let parsed_ip = self.parse_lookup_ip(ip_address, &ruby)?;
+        let owned_path = self.parse_path(path, &ruby)?;
+        let path_elements = path_elements_from_owned_path(owned_path.as_ref());
+
+        lookup_result_to_value(
+            &ruby,
+            reader.lookup_path(parsed_ip, &path_elements),
+            "Database lookup failed",
+        )
     }
 
     #[inline]
@@ -565,42 +622,65 @@ impl Reader {
         let reader_option = guard.as_ref();
         let reader = reader_option.as_ref().unwrap();
 
-        // Parse IP address
-        let parsed_ip = parse_ip_address_fast(ip_address, &ruby)?;
-
-        if self.ip_version == 4 && matches!(parsed_ip, IpAddr::V6(_)) {
-            return Err(Error::new(
-                ruby.exception_arg_error(),
-                ipv6_in_ipv4_error(&parsed_ip),
-            ));
-        }
+        let parsed_ip = self.parse_lookup_ip(ip_address, &ruby)?;
 
         // Perform lookup with prefix
-        match reader.lookup_prefix(parsed_ip) {
-            Ok((Some(data), prefix)) => {
-                let arr = ruby.ary_new();
-                arr.push(data.into_value())?;
-                arr.push(prefix.into_value_with(&ruby))?;
-                Ok(arr)
-            }
-            Ok((None, prefix)) => {
-                let arr = ruby.ary_new();
-                arr.push(ruby.qnil().as_value())?;
-                arr.push(prefix.into_value_with(&ruby))?;
-                Ok(arr)
+        lookup_prefix_result_to_array(
+            &ruby,
+            reader.lookup_prefix(parsed_ip),
+            "Database lookup failed",
+        )
+    }
+
+    fn get_many(&self, ips: Value) -> Result<RArray, Error> {
+        let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby method");
+
+        let guard = self.get_reader(&ruby)?;
+        let reader_option = guard.as_ref();
+        let reader = reader_option.as_ref().unwrap();
+
+        if let Ok(ip_array) = RArray::try_convert(ips) {
+            let results = ruby.ary_new_capa(ip_array.len());
+            for index in 0..ip_array.len() {
+                let ip = ip_array.entry::<Value>(index as isize)?;
+                results.push(self.lookup_ip_value(&ruby, reader, ip)?)?;
             }
-            Err(MaxMindDbError::InvalidDatabase { .. }) | Err(MaxMindDbError::Io(_)) => {
-                Err(Error::new(
-                    ExceptionClass::from_value(invalid_database_error().as_value())
-                        .expect("InvalidDatabaseError should convert to ExceptionClass"),
-                    ERR_BAD_DATA,
-                ))
+            return Ok(results);
+        }
+
+        ensure_enumerable(ips, &ruby, "ips must be an Array or Enumerable")?;
+        let results = ruby.ary_new();
+        for ip in ips.enumeratorize("each", ()) {
+            results.push(self.lookup_ip_value(&ruby, reader, ip?)?)?;
+        }
+        Ok(results)
+    }
+
+    fn get_many_path(&self, ips: Value, path: Value) -> Result<RArray, Error> {
+        let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby method");
+
+        let guard = self.get_reader(&ruby)?;
+        let reader_option = guard.as_ref();
+        let reader = reader_option.as_ref().unwrap();
+
+        let owned_path = self.parse_path(path, &ruby)?;
+        let path_elements = path_elements_from_owned_path(owned_path.as_ref());
+
+        if let Ok(ip_array) = RArray::try_convert(ips) {
+            let results = ruby.ary_new_capa(ip_array.len());
+            for index in 0..ip_array.len() {
+                let ip = ip_array.entry::<Value>(index as isize)?;
+                results.push(self.lookup_ip_path_value(&ruby, reader, ip, &path_elements)?)?;
             }
-            Err(e) => Err(Error::new(
-                ruby.exception_runtime_error(),
-                format!("Database lookup failed: {}", e),
-            )),
+            return Ok(results);
         }
+
+        ensure_enumerable(ips, &ruby, "ips must be an Array or Enumerable")?;
+        let results = ruby.ary_new();
+        for ip in ips.enumeratorize("each", ()) {
+            results.push(self.lookup_ip_path_value(&ruby, reader, ip?, &path_elements)?)?;
+        }
+        Ok(results)
     }
 
     fn metadata(&self) -> Result<Metadata, Error> {
@@ -635,19 +715,25 @@ impl Reader {
         self.closed.load(Ordering::Acquire)
     }
 
-    fn each(&self, args: &[Value]) -> Result<Value, Error> {
-        let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby method");
+    fn inspect(&self) -> String {
+        format!(
+            "#<MaxMind::DB::Rust::Reader:0x{:x} @closed={} @ip_version={}>",
+            self as *const Self as usize,
+            self.closed(),
+            self.ip_version,
+        )
+    }
 
-        let guard = self.get_reader(&ruby)?;
+    fn each(ruby: &magnus::Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Value, Error> {
+        let reader_self = &*rb_self;
+
+        let guard = reader_self.get_reader(ruby)?;
         let reader_option = guard.as_ref();
         let reader = reader_option.as_ref().unwrap();
 
         // If no block given, return enumerator
         if !ruby.block_given() {
-            return Err(Error::new(
-                ruby.exception_runtime_error(),
-                "Enumerator support not yet implemented, please provide a block",
-            ));
+            return Ok(rb_self.enumeratorize("each", args).as_value());
         }
 
         let ip_version = reader.metadata().ip_version;
@@ -718,14 +804,9 @@ impl Reader {
             ));
         }
 
-        let mut iter = reader.within(network).map_err(|e| {
-            Error::new(
-                ExceptionClass::from_value(invalid_database_error().as_value())
-                    .expect("InvalidDatabaseError should convert to ExceptionClass"),
-                format!("Failed to iterate: {}", e),
-            )
-        })?;
-
+        let mut iter = reader
+            .within(network)
+            .map_err(|e| invalid_database_exception(&format!("Failed to iterate: {}", e)))?;
         // Get IPAddr class
         let ipaddr_class = ruby.class_object().const_get::<_, RClass>("IPAddr")?;
 
@@ -741,12 +822,10 @@ impl Reader {
                     let values = (ipaddr, data.into_value());
                     ruby.yield_values::<(Value, Value), Value>(values)?;
                 }
-                Err(MaxMindDbError::InvalidDatabase { .. }) | Err(MaxMindDbError::Io(_)) => {
-                    return Err(Error::new(
-                        ExceptionClass::from_value(invalid_database_error().as_value())
-                            .expect("InvalidDatabaseError should convert to ExceptionClass"),
-                        ERR_BAD_DATA,
-                    ));
+                Err(MaxMindDbError::InvalidDatabase { .. })
+                | Err(MaxMindDbError::Decoding { .. })
+                | Err(MaxMindDbError::Io(_)) => {
+                    return Err(invalid_database_exception(ERR_BAD_DATA));
                 }
                 Err(e) => {
                     return Err(Error::new(
@@ -768,8 +847,114 @@ impl Reader {
         }
         Ok(guard)
     }
+
+    #[inline]
+    fn parse_lookup_ip(&self, ip_address: Value, ruby: &magnus::Ruby) -> Result<IpAddr, Error> {
+        let parsed_ip = parse_ip_address_fast(ip_address, ruby)?;
+        self.validate_lookup_ip(parsed_ip, ruby)
+    }
+
+    #[inline]
+    fn validate_lookup_ip(&self, parsed_ip: IpAddr, ruby: &magnus::Ruby) -> Result<IpAddr, Error> {
+        if self.ip_version == 4 && matches!(parsed_ip, IpAddr::V6(_)) {
+            Err(Error::new(
+                ruby.exception_arg_error(),
+                ipv6_in_ipv4_error(&parsed_ip),
+            ))
+        } else {
+            Ok(parsed_ip)
+        }
+    }
+
+    #[inline]
+    fn lookup_ip_value(
+        &self,
+        ruby: &magnus::Ruby,
+        reader: &ReaderSource,
+        ip: Value,
+    ) -> Result<Value, Error> {
+        let parsed_ip = self.parse_lookup_ip(ip, ruby)?;
+        lookup_result_to_value(ruby, reader.lookup(parsed_ip), "Database lookup failed")
+    }
+
+    #[inline]
+    fn lookup_ip_path_value(
+        &self,
+        ruby: &magnus::Ruby,
+        reader: &ReaderSource,
+        ip: Value,
+        path_elements: &[PathElement<'_>],
+    ) -> Result<Value, Error> {
+        let parsed_ip = self.parse_lookup_ip(ip, ruby)?;
+        lookup_result_to_value(
+            ruby,
+            reader.lookup_path(parsed_ip, path_elements),
+            "Database lookup failed",
+        )
+    }
+
+    fn parse_path(
+        &self,
+        path: Value,
+        ruby: &magnus::Ruby,
+    ) -> Result<Arc<[OwnedPathElement]>, Error> {
+        let path = path_array(path, ruby)?;
+        let hash = path_cache_hash(path, ruby)?;
+
+        if let Some(cached) = self.cached_path(path, hash)? {
+            return Ok(cached);
+        }
+
+        let parsed_path: Arc<[OwnedPathElement]> = parse_path_array(path, ruby)?.into();
+        self.store_cached_path(hash, parsed_path.clone());
+        Ok(parsed_path)
+    }
+
+    fn cached_path(
+        &self,
+        path: RArray,
+        hash: u64,
+    ) -> Result<Option<Arc<[OwnedPathElement]>>, Error> {
+        let candidates = match self.path_cache.lock() {
+            Ok(cache) => cache
+                .iter()
+                .filter(|entry| entry.hash == hash && entry.elements.len() == path.len())
+                .map(|entry| entry.elements.clone())
+                .collect::<Vec<_>>(),
+            Err(_) => return Ok(None),
+        };
+
+        for candidate in candidates {
+            if path_matches_cached(path, candidate.as_ref())? {
+                return Ok(Some(candidate));
+            }
+        }
+
+        Ok(None)
+    }
+
+    fn store_cached_path(&self, hash: u64, elements: Arc<[OwnedPathElement]>) {
+        if let Ok(mut cache) = self.path_cache.lock() {
+            if cache
+                .iter()
+                .any(|entry| entry.hash == hash && entry.elements.as_ref() == elements.as_ref())
+            {
+                return;
+            }
+
+            cache.push_back(CachedPath { hash, elements });
+            while cache.len() > PATH_CACHE_MAX_ENTRIES {
+                cache.pop_front();
+            }
+        }
+    }
 }
 
+// SAFETY: Reader does not store Ruby VALUE handles. The database source is
+// owned by ReaderSource and is read-only after construction; close atomically
+// swaps the shared source to None. The path cache contains only Rust-owned path
+// elements behind a Mutex. All Ruby object access happens inside method calls
+// while the Ruby VM is active.
 unsafe impl Send for Reader {}
 
 /// Helper function to create a Reader from a ReaderSource
@@ -779,10 +964,152 @@ fn create_reader(source: ReaderSource) -> Reader {
     Reader {
         reader: Arc::new(ArcSwapOption::from(Some(source))),
         closed: Arc::new(AtomicBool::new(false)),
+        path_cache: Arc::new(Mutex::new(VecDeque::with_capacity(PATH_CACHE_MAX_ENTRIES))),
         ip_version,
     }
 }
 
+fn path_array(path: Value, ruby: &magnus::Ruby) -> Result<RArray, Error> {
+    RArray::try_convert(path).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "Path must be an Array of String and Integer elements",
+        )
+    })
+}
+
+fn parse_path_array(path: RArray, ruby: &magnus::Ruby) -> Result<Vec<OwnedPathElement>, Error> {
+    let mut elements = Vec::with_capacity(path.len());
+    for index in 0..path.len() {
+        let item = path.entry::<Value>(index as isize)?;
+        if let Ok(key) = RString::try_convert(item) {
+            elements.push(OwnedPathElement::Key(key.to_string()?));
+            continue;
+        }
+        if let Ok(index) = isize::try_convert(item) {
+            elements.push(signed_index_to_owned_path_element(index));
+            continue;
+        }
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Path elements must be Strings or Integers",
+        ));
+    }
+
+    Ok(elements)
+}
+
+#[inline]
+fn signed_index_to_owned_path_element(index: isize) -> OwnedPathElement {
+    if index >= 0 {
+        OwnedPathElement::Index(index as usize)
+    } else {
+        let index_from_end = index
+            .checked_neg()
+            .and_then(|index| index.checked_sub(1))
+            .map(|index| index as usize)
+            .unwrap_or(usize::MAX);
+        OwnedPathElement::IndexFromEnd(index_from_end)
+    }
+}
+
+fn path_cache_hash(path: RArray, ruby: &magnus::Ruby) -> Result<u64, Error> {
+    let mut hasher = FxHasher::default();
+    path.len().hash(&mut hasher);
+
+    for index in 0..path.len() {
+        let item = path.entry::<Value>(index as isize)?;
+        if let Ok(key) = RString::try_convert(item) {
+            0_u8.hash(&mut hasher);
+            hash_path_key(key, &mut hasher)?;
+            continue;
+        }
+        if let Ok(index) = isize::try_convert(item) {
+            1_u8.hash(&mut hasher);
+            index.hash(&mut hasher);
+            continue;
+        }
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Path elements must be Strings or Integers",
+        ));
+    }
+
+    Ok(hasher.finish())
+}
+
+fn hash_path_key(key: RString, hasher: &mut FxHasher) -> Result<(), Error> {
+    // SAFETY: the borrowed str is used only for immediate hashing and is not
+    // stored across any call that could mutate or free the Ruby string.
+    if let Some(key_str) = unsafe { key.test_as_str() } {
+        key_str.hash(hasher);
+    } else {
+        key.to_string()?.hash(hasher);
+    }
+    Ok(())
+}
+
+fn path_matches_cached(path: RArray, cached: &[OwnedPathElement]) -> Result<bool, Error> {
+    if path.len() != cached.len() {
+        return Ok(false);
+    }
+
+    for (index, cached_element) in cached.iter().enumerate() {
+        let item = path.entry::<Value>(index as isize)?;
+        match cached_element {
+            OwnedPathElement::Key(expected) => {
+                let Ok(key) = RString::try_convert(item) else {
+                    return Ok(false);
+                };
+                if !path_key_matches(key, expected)? {
+                    return Ok(false);
+                }
+            }
+            OwnedPathElement::Index(_) | OwnedPathElement::IndexFromEnd(_) => {
+                let Ok(index) = isize::try_convert(item) else {
+                    return Ok(false);
+                };
+                if signed_index_to_owned_path_element(index) != *cached_element {
+                    return Ok(false);
+                }
+            }
+        }
+    }
+
+    Ok(true)
+}
+
+fn path_key_matches(key: RString, expected: &str) -> Result<bool, Error> {
+    // SAFETY: the borrowed str is used only for immediate comparison and is not
+    // stored across any call that could mutate or free the Ruby string.
+    if let Some(key_str) = unsafe { key.test_as_str() } {
+        Ok(key_str == expected)
+    } else {
+        Ok(key.to_string()? == expected)
+    }
+}
+
+fn path_elements_from_owned_path(path: &[OwnedPathElement]) -> Vec<PathElement<'_>> {
+    path.iter()
+        .map(|element| match element {
+            OwnedPathElement::Key(key) => PathElement::Key(key.as_str()),
+            OwnedPathElement::Index(index) => PathElement::Index(*index),
+            OwnedPathElement::IndexFromEnd(index) => PathElement::IndexFromEnd(*index),
+        })
+        .collect()
+}
+
+fn ensure_enumerable(value: Value, ruby: &magnus::Ruby, error_message: &str) -> Result<(), Error> {
+    if value.respond_to("each", false)? {
+        Ok(())
+    } else {
+        Err(Error::new(
+            ruby.exception_arg_error(),
+            error_message.to_owned(),
+        ))
+    }
+}
+
 /// Parse IP address from Ruby value (String or IPAddr) - optimized version
 #[inline(always)]
 fn parse_ip_address_fast(value: Value, ruby: &magnus::Ruby) -> Result<IpAddr, Error> {
@@ -797,12 +1124,7 @@ fn parse_ip_address_fast(value: Value, ruby: &magnus::Ruby) -> Result<IpAddr, Er
             )
         })?;
 
-        return IpAddr::from_str(ip_str).map_err(|_| {
-            Error::new(
-                ruby.exception_arg_error(),
-                format!("'{}' does not appear to be an IPv4 or IPv6 address", ip_str),
-            )
-        });
+        return parse_ip_string(ip_str, ruby);
     }
 
     // Slow path: Try as IPAddr object
@@ -833,15 +1155,7 @@ fn parse_ip_address_fast(value: Value, ruby: &magnus::Ruby) -> Result<IpAddr, Er
     }
 
     if let Ok(ipaddr_obj) = value.funcall::<_, _, String>("to_s", ()) {
-        return IpAddr::from_str(&ipaddr_obj).map_err(|_| {
-            Error::new(
-                ruby.exception_arg_error(),
-                format!(
-                    "'{}' does not appear to be an IPv4 or IPv6 address",
-                    ipaddr_obj
-                ),
-            )
-        });
+        return parse_ip_string(&ipaddr_obj, ruby);
     }
 
     Err(Error::new(
@@ -850,14 +1164,126 @@ fn parse_ip_address_fast(value: Value, ruby: &magnus::Ruby) -> Result<IpAddr, Er
     ))
 }
 
+#[inline(always)]
+fn parse_ip_string(s: &str, ruby: &magnus::Ruby) -> Result<IpAddr, Error> {
+    if let Some(ip) = parse_ipv4_string(s.as_bytes()) {
+        return Ok(IpAddr::V4(ip));
+    }
+
+    IpAddr::from_str(s).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("'{}' does not appear to be an IPv4 or IPv6 address", s),
+        )
+    })
+}
+
+#[inline(always)]
+fn parse_ipv4_string(bytes: &[u8]) -> Option<Ipv4Addr> {
+    let mut octets = [0u8; 4];
+    let mut octet_index = 0;
+    let mut value: u16 = 0;
+    let mut digits = 0;
+
+    for &byte in bytes {
+        if byte == b'.' {
+            if digits == 0 || octet_index == 3 {
+                return None;
+            }
+            octets[octet_index] = value as u8;
+            octet_index += 1;
+            value = 0;
+            digits = 0;
+            continue;
+        }
+
+        if !byte.is_ascii_digit() {
+            return None;
+        }
+        if digits == 1 && value == 0 {
+            return None;
+        }
+
+        digits += 1;
+        if digits > 3 {
+            return None;
+        }
+        value = value * 10 + u16::from(byte - b'0');
+        if value > u16::from(u8::MAX) {
+            return None;
+        }
+    }
+
+    if octet_index != 3 || digits == 0 {
+        return None;
+    }
+    octets[octet_index] = value as u8;
+
+    Some(Ipv4Addr::from(octets))
+}
+
+#[inline]
+fn lookup_result_to_value(
+    ruby: &magnus::Ruby,
+    result: Result<Option<RubyDecodedValue>, MaxMindDbError>,
+    error_context: &str,
+) -> Result<Value, Error> {
+    match result {
+        Ok(Some(data)) => Ok(data.into_value()),
+        Ok(None) => Ok(ruby.qnil().as_value()),
+        Err(err) => Err(lookup_error(ruby, err, error_context)),
+    }
+}
+
+#[inline]
+fn lookup_prefix_result_to_array(
+    ruby: &magnus::Ruby,
+    result: Result<(Option<RubyDecodedValue>, usize), MaxMindDbError>,
+    error_context: &str,
+) -> Result<RArray, Error> {
+    match result {
+        Ok((data, prefix)) => {
+            let arr = ruby.ary_new();
+            arr.push(data.map_or_else(|| ruby.qnil().as_value(), RubyDecodedValue::into_value))?;
+            arr.push(prefix.into_value_with(ruby))?;
+            Ok(arr)
+        }
+        Err(err) => Err(lookup_error(ruby, err, error_context)),
+    }
+}
+
+#[inline]
+fn lookup_error(ruby: &magnus::Ruby, err: MaxMindDbError, context: &str) -> Error {
+    match err {
+        MaxMindDbError::InvalidDatabase { .. }
+        | MaxMindDbError::Decoding { .. }
+        | MaxMindDbError::Io(_) => invalid_database_exception(ERR_BAD_DATA),
+        other => Error::new(
+            ruby.exception_runtime_error(),
+            format!("{}: {}", context, other),
+        ),
+    }
+}
+
 /// Generate error message for IPv6 in IPv4-only database
 fn ipv6_in_ipv4_error(ip: &IpAddr) -> String {
     format!(
-        "Error looking up {}. You attempted to look up an IPv6 address in an IPv4-only database",
+        "Error looking up {}. You attempted to look up an IPv6 address in an IPv4-only database.",
         ip
     )
 }
 
+fn database_path(database: Value) -> Result<String, Error> {
+    RString::try_convert(database)?.to_string()
+}
+
+fn database_buffer(database: Value) -> Result<Vec<u8>, Error> {
+    let string = RString::try_convert(database)?;
+    // SAFETY: the slice is copied into an owned Vec before Ruby can mutate or
+    // free the string, and the reader only ever sees the owned bytes.
+    Ok(unsafe { string.as_slice() }.to_vec())
+}
+
 /// Open a MaxMind DB using memory-mapped I/O (MODE_MMAP)
 fn open_database_mmap(path: &str) -> Result<Reader, Error> {
     let ruby = magnus::Ruby::get().expect("Ruby VM should be available in Ruby context");
@@ -869,16 +1295,11 @@ fn open_database_mmap(path: &str) -> Result<Reader, Error> {
             format!("Failed to memory-map database file: {}", e),
         )
     })?;
-
     let reader = MaxMindReader::from_source(mmap).map_err(|_| {
-        Error::new(
-            ExceptionClass::from_value(invalid_database_error().as_value())
-                .expect("InvalidDatabaseError should convert to ExceptionClass"),
-            format!(
-                "Error opening database file ({}). Is this a valid MaxMind DB file?",
-                path
-            ),
-        )
+        invalid_database_exception(&format!(
+            "Error opening database file ({}). Is this a valid MaxMind DB file?",
+            path
+        ))
     })?;
 
     Ok(create_reader(ReaderSource::Mmap(reader)))
@@ -897,16 +1318,25 @@ fn open_database_memory(path: &str) -> Result<Reader, Error> {
         )
     })?;
 
-    let reader = MaxMindReader::from_source(buffer).map_err(|_| {
-        Error::new(
-            ExceptionClass::from_value(invalid_database_error().as_value())
-                .expect("InvalidDatabaseError should convert to ExceptionClass"),
-            format!(
-                "Error opening database file ({}). Is this a valid MaxMind DB file?",
-                path
-            ),
-        )
-    })?;
+    reader_from_buffer(
+        buffer,
+        format!(
+            "Error opening database file ({}). Is this a valid MaxMind DB file?",
+            path
+        ),
+    )
+}
+
+fn open_database_buffer(buffer: Vec<u8>) -> Result<Reader, Error> {
+    reader_from_buffer(
+        buffer,
+        "Error opening database from buffer. Is this a valid MaxMind DB file?".to_owned(),
+    )
+}
+
+fn reader_from_buffer(buffer: Vec<u8>, invalid_message: String) -> Result<Reader, Error> {
+    let reader = MaxMindReader::from_source(buffer)
+        .map_err(|_| invalid_database_exception(invalid_message.as_str()))?;
 
     Ok(create_reader(ReaderSource::Memory(reader)))
 }
@@ -944,6 +1374,14 @@ fn invalid_database_error() -> RClass {
         .expect("InvalidDatabaseError class should exist")
 }
 
+fn invalid_database_exception(message: &str) -> Error {
+    Error::new(
+        ExceptionClass::from_value(invalid_database_error().as_value())
+            .expect("InvalidDatabaseError should convert to ExceptionClass"),
+        message.to_owned(),
+    )
+}
+
 fn rust_module(ruby: &magnus::Ruby) -> RModule {
     let maxmind = ruby
         .class_object()
@@ -1004,8 +1442,15 @@ fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
         }
     };
 
-    if rust.const_get::<_, Value>(MAP_KEY_ROOTS_CONST).is_err() {
-        rust.const_set(MAP_KEY_ROOTS_CONST, ruby.ary_new_capa(MAP_KEY_CACHE_MAX))?;
+    if rust
+        .const_get::<_, Value>(STRING_CACHE_ROOTS_CONST)
+        .is_err()
+    {
+        rust.const_set(STRING_CACHE_ROOTS_CONST, ruby.ary_new())?;
+    }
+
+    if rust.const_get::<_, Value>(MAP_KEY_ROOTS_CONST).is_ok() {
+        let _ = rust.funcall::<_, _, Value>("send", ("remove_const", MAP_KEY_ROOTS_CONST))?;
     }
 
     // The extension can be loaded more than once from different paths.
@@ -1021,13 +1466,17 @@ fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
     let reader_class = rust.define_class("Reader", ruby.class_object())?;
     reader_class.define_singleton_method("new", magnus::function!(Reader::new, -1))?;
     reader_class.define_method("get", magnus::method!(Reader::get, 1))?;
+    reader_class.define_method("get_path", magnus::method!(Reader::get_path, 2))?;
     reader_class.define_method(
         "get_with_prefix_length",
         magnus::method!(Reader::get_with_prefix_length, 1),
     )?;
+    reader_class.define_method("get_many", magnus::method!(Reader::get_many, 1))?;
+    reader_class.define_method("get_many_path", magnus::method!(Reader::get_many_path, 2))?;
     reader_class.define_method("metadata", magnus::method!(Reader::metadata, 0))?;
     reader_class.define_method("close", magnus::method!(Reader::close, 0))?;
     reader_class.define_method("closed", magnus::method!(Reader::closed, 0))?;
+    reader_class.define_method("inspect", magnus::method!(Reader::inspect, 0))?;
     reader_class.define_method("each", magnus::method!(Reader::each, -1))?;
 
     // Include Enumerable module
@@ -1062,8 +1511,49 @@ fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
 
     // Define MODE constants
     rust.const_set("MODE_AUTO", ruby.to_symbol("MODE_AUTO"))?;
+    rust.const_set("MODE_FILE", ruby.to_symbol("MODE_FILE"))?;
     rust.const_set("MODE_MEMORY", ruby.to_symbol("MODE_MEMORY"))?;
     rust.const_set("MODE_MMAP", ruby.to_symbol("MODE_MMAP"))?;
+    rust.const_set(
+        "MODE_PARAM_IS_BUFFER",
+        ruby.to_symbol("MODE_PARAM_IS_BUFFER"),
+    )?;
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::parse_ipv4_string;
+    use std::net::Ipv4Addr;
+
+    #[test]
+    fn parses_strict_ipv4_strings() {
+        assert_eq!(
+            parse_ipv4_string(b"0.1.2.255"),
+            Some(Ipv4Addr::new(0, 1, 2, 255))
+        );
+        assert_eq!(
+            parse_ipv4_string(b"192.0.2.1"),
+            Some(Ipv4Addr::new(192, 0, 2, 1))
+        );
+    }
+
+    #[test]
+    fn rejects_ipv4_strings_that_std_parser_rejects() {
+        for value in [
+            b"01.2.3.4".as_slice(),
+            b"1.02.3.4".as_slice(),
+            b"1.2.3.04".as_slice(),
+            b"1.2.3".as_slice(),
+            b"1.2.3.4.5".as_slice(),
+            b"1..2.3".as_slice(),
+            b"256.1.1.1".as_slice(),
+            b"1.2.3.4 ".as_slice(),
+            b" 1.2.3.4".as_slice(),
+            b"2001:db8::1".as_slice(),
+        ] {
+            assert_eq!(parse_ipv4_string(value), None);
+        }
+    }
+}