maxmind-db-rust 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 854691c99c81b7d9574c780a7e10f80eea69788bb4dc95cce41361e5163d6f28
-  data.tar.gz: '086f7efa6e3620e3fd15d66b87964076647e7510551d58d98e4f484c69400173'
+  metadata.gz: 477024cc8d20f8e13fa22fa0e6d8a94554c91f16812e81ef2154ae5cc821739c
+  data.tar.gz: 4a5b94f8b821af36bed45f0b164ea1c5061c734a3827afc8f0ed059ec986c4b0
 SHA512:
-  metadata.gz: f20905fca81e3742ff75da2e5758fbd198d61dd5c7c82b23dd8ed9a731bf7a46dc707c6660590adb895e2c022b6f6d07edb7916eab774d4461faccd2de66ec2e
-  data.tar.gz: 888d4623247bf07a0c8058c669230032ebcef98b0efcc03920f1196cb1695361f2a868250ffeafb6fe3ed7913038b38f4b419d9ef5e3a1d5f3caecd0b1ec1bb0
+  metadata.gz: ad9547ef7bf1d3371325d7fd519f78f0d01f302e5fecc4e5181d9a88e57aa1ebed4c51b1f6ae08491133aab05a63ad31516bae33051a78362308ec77ece1e204
+  data.tar.gz: f5be53fe4952c00ad82c3824a0b17aa7ae420a9580261686847f684ab8834fbbaa6d5b316405f6a70ee14fc9fd25717fcb367d49af6c5e9d29fb10ed33e2736b

data/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-14
+
+### Added
+
+- Added `MODE_FILE` as an official-gem compatibility alias for path-backed
+  memory-mapped readers.
+- Added `MODE_PARAM_IS_BUFFER` for constructing readers from Ruby strings
+  containing database bytes.
+- Added `Reader#get_path` and `Reader#get_many_path` for selective path lookups.
+- Added `Reader#get_many` for batch lookups over arrays and enumerables.
+- Added Enumerator return support for `Reader#each` when called without a block.
+- Added `Reader#inspect` with closed state and database IP version.
+- Added benchmark tooling for comparing git refs and measuring Ruby object
+  allocations.
+- Added official gem parity tests, compatibility audit tests, bad data corpus
+  tests, and reader concurrency stress tests.
+
+### Changed
+
+- Upgraded the `maxminddb` crate to 0.28.1.
+- Improved IPv4 string lookup performance with a strict fast-path parser.
+- Streamed non-array `get_many` and `get_many_path` inputs instead of
+  materializing enumerables.
+- Cached parsed lookup paths per reader to reduce repeated path parsing.
+- Simplified reader open mode parsing and centralized lookup error handling.
+- Documented Rust extension safety invariants and `Send` requirements.
+
+### Fixed
+
+- Fixed source gem native extension installation so `require "maxmind/db/rust"`
+  works after installing the source gem.
+- Removed an unsafe reader iterator transmute.
+- Improved invalid database error construction consistency across reader open
+  and iteration paths.
+- Fixed dead test assertions and made adapted MaxMind tests independent of the
+  current working directory.
+
+### Security
+
+- Pinned GitHub Actions to commit SHAs.
+- Restricted workflow permissions and disabled persisted checkout credentials.
+- Added a zizmor workflow and source-gem install smoke test to release checks.
+
 ## [0.4.0] - 2026-04-25
 
 ### Performance

data/README.md

@@ -13,9 +13,10 @@ It keeps the API close to the official `maxmind-db` gem while adding Rust-backed
 - Rust implementation focused on fast lookups
 - API modeled after the official `maxmind-db` gem
 - Thread-safe lookups
-- Supports MMAP and in-memory modes
+- Supports file-backed, MMAP, in-memory, and buffer-backed modes
 - Includes network iteration support
 - Accepts both `String` and `IPAddr` inputs
+- Includes selective path lookup and batch lookup extensions
 
 ## Installation
 
@@ -81,6 +82,26 @@ puts "Prefix length: #{prefix_length}"
 reader.close
 ```
 
+### Selective and Batch Lookups
+
+```ruby
+require 'maxmind/db/rust'
+
+reader = MaxMind::DB::Rust::Reader.new('GeoIP2-City.mmdb')
+
+# Decode one field without materializing the full record.
+iso_code = reader.get_path('8.8.8.8', ['country', 'iso_code'])
+
+# Batch full-record lookups.
+ips = ['8.8.8.8', '1.1.1.1', '208.67.222.222']
+records = reader.get_many(ips)
+
+# Batch one-field lookups.
+iso_codes = reader.get_many_path(ips, ['country', 'iso_code'])
+
+reader.close
+```
+
 ### Using IPAddr Objects
 
 ```ruby
@@ -112,11 +133,24 @@ reader = MaxMind::DB::Rust::Reader.new(
   mode: MaxMind::DB::Rust::MODE_MMAP
 )
 
+# MODE_FILE: Official-gem compatibility alias for path-backed MMAP
+reader = MaxMind::DB::Rust::Reader.new(
+  'GeoIP2-City.mmdb',
+  mode: MaxMind::DB::Rust::MODE_FILE
+)
+
 # MODE_MEMORY: Load entire database into memory
 reader = MaxMind::DB::Rust::Reader.new(
   'GeoIP2-City.mmdb',
   mode: MaxMind::DB::Rust::MODE_MEMORY
 )
+
+# MODE_PARAM_IS_BUFFER: Read from a String containing database bytes
+buffer = File.binread('GeoIP2-City.mmdb')
+reader = MaxMind::DB::Rust::Reader.new(
+  buffer,
+  mode: MaxMind::DB::Rust::MODE_PARAM_IS_BUFFER
+)
 ```
 
 ### Accessing Metadata
@@ -176,15 +210,15 @@ reader.close
 
 ### `MaxMind::DB::Rust::Reader`
 
-#### `new(database_path, options = {})`
+#### `new(database, options = {})`
 
 Create a new Reader instance.
 
 **Parameters:**
 
-- `database_path` (String): Path to the MaxMind DB file
+- `database` (String): Path to the MaxMind DB file, or database bytes when using `:MODE_PARAM_IS_BUFFER`
 - `options` (Hash): Optional configuration
-  - `:mode` (Symbol): One of `:MODE_AUTO`, `:MODE_MEMORY`, or `:MODE_MMAP`
+  - `:mode` (Symbol): One of `:MODE_AUTO`, `:MODE_FILE`, `:MODE_MEMORY`, `:MODE_MMAP`, or `:MODE_PARAM_IS_BUFFER`
 
 **Returns:** Reader instance
 
@@ -208,6 +242,17 @@ Look up an IP address in the database.
 - `ArgumentError`: If looking up IPv6 in an IPv4-only database
 - `MaxMind::DB::Rust::InvalidDatabaseError`: If the database is corrupt
 
+#### `get_path(ip_address, path)`
+
+Look up an IP address and return only the value at `path`.
+
+**Parameters:**
+
+- `ip_address` (String or IPAddr): The IP address to look up
+- `path` (Array): String map keys and Integer array indexes. Negative indexes count from the end.
+
+**Returns:** The value at the path, or `nil` if the record or path is not found
+
 #### `get_with_prefix_length(ip_address)`
 
 Look up an IP address and return the prefix length.
@@ -218,6 +263,27 @@ Look up an IP address and return the prefix length.
 
 **Returns:** Array `[record, prefix_length]` where record is a Hash or `nil`
 
+#### `get_many(ip_addresses)`
+
+Look up multiple IP addresses.
+
+**Parameters:**
+
+- `ip_addresses` (Array or Enumerable): IP address strings or IPAddr objects
+
+**Returns:** Array of record values in input order
+
+#### `get_many_path(ip_addresses, path)`
+
+Look up one path for multiple IP addresses.
+
+**Parameters:**
+
+- `ip_addresses` (Array or Enumerable): IP address strings or IPAddr objects
+- `path` (Array): String map keys and Integer array indexes
+
+**Returns:** Array of path values in input order
+
 #### `metadata()`
 
 Get metadata about the database.
@@ -269,8 +335,10 @@ Metadata attributes:
 ### Constants
 
 - `MaxMind::DB::Rust::MODE_AUTO` - Automatically choose the best mode (uses MMAP)
+- `MaxMind::DB::Rust::MODE_FILE` - Official-gem compatibility alias for path-backed MMAP
 - `MaxMind::DB::Rust::MODE_MEMORY` - Load entire database into memory
 - `MaxMind::DB::Rust::MODE_MMAP` - Use memory-mapped file I/O (recommended)
+- `MaxMind::DB::Rust::MODE_PARAM_IS_BUFFER` - Read database bytes from a Ruby String
 
 ### Exceptions
 
@@ -278,26 +346,26 @@ Metadata attributes:
 
 ## Comparison with Official Gem
 
-| Feature          | maxmind-db (official) | maxmind-db-rust (this gem)                 |
-| ---------------- | --------------------- | ------------------------------------------ |
-| Implementation   | Pure Ruby             | Rust with Ruby bindings                    |
-| Performance      | Baseline              | Faster lookup throughput in our benchmarks |
-| API              | MaxMind::DB           | MaxMind::DB::Rust                          |
-| MODE_FILE        | ✓                     | ✗                                          |
-| MODE_MEMORY      | ✓                     | ✓                                          |
-| MODE_AUTO        | ✓                     | ✓                                          |
-| MODE_MMAP        | ✗                     | ✓                                          |
-| Iterator support | ✗                     | ✓                                          |
-| Thread-safe      | ✓                     | ✓                                          |
+| Feature              | maxmind-db (official) | maxmind-db-rust (this gem)                 |
+| -------------------- | --------------------- | ------------------------------------------ |
+| Implementation       | Pure Ruby             | Rust with Ruby bindings                    |
+| Performance          | Baseline              | Faster lookup throughput in our benchmarks |
+| API                  | MaxMind::DB           | MaxMind::DB::Rust                          |
+| MODE_FILE            | ✓                     | ✓                                          |
+| MODE_MEMORY          | ✓                     | ✓                                          |
+| MODE_AUTO            | ✓                     | ✓                                          |
+| MODE_PARAM_IS_BUFFER | ✓                     | ✓                                          |
+| MODE_MMAP            | ✗                     | ✓                                          |
+| Iterator support     | ✗                     | ✓                                          |
+| Thread-safe          | ✓                     | ✓                                          |
 
 ## Performance
 
 Lookup performance depends on hardware, Ruby version, database, and workload.
 
 - In this project’s random-lookup benchmarks, this gem is consistently faster than the official Ruby implementation.
-- On `/var/lib/GeoIP/GeoIP2-City.mmdb` in this environment, random lookup throughput was about `47x` higher than the official gem.
 - `MODE_MMAP` and `MODE_MEMORY` both perform well; which is faster can vary by environment.
-- For reproducible numbers on your own data, run `benchmark/compare_lookups.rb` against your database.
+- For current, reproducible numbers on your own data and Ruby version, run `benchmark/compare_lookups.rb` against your database.
 - Safe for concurrent lookups across threads.
 
 ## Development

data/ext/maxmind_db_rust/Cargo.toml

@@ -15,7 +15,7 @@ crate-type = ["cdylib"]
 arc-swap = "1.9"
 ipnetwork = "0.21"
 magnus = "0.8"
-maxminddb = { version = "0.28", features = ["unsafe-str-decode"] }
+maxminddb = { version = "0.28.1", features = ["unsafe-str-decode"] }
 memmap2 = "0.9"
 rustc-hash = "2.1"
 serde = "1.0"

data/ext/maxmind_db_rust/extconf.rb

@@ -3,4 +3,4 @@
 require 'mkmf'
 require 'rb_sys/mkmf'
 
-create_rust_makefile('maxmind_db_rust')
+create_rust_makefile('maxmind/db/maxmind_db_rust')

data/ext/maxmind_db_rust/lib/maxmind/db/rust.rb

@@ -10,7 +10,7 @@ module MaxMind
       # - Reader class
       # - Metadata class
       # - InvalidDatabaseError exception
-      # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+      # - MODE_AUTO, MODE_FILE, MODE_MEMORY, MODE_MMAP, MODE_PARAM_IS_BUFFER constants
     end
   end
 end

data/ext/maxmind_db_rust/src/lib.rs

@@ -5,26 +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::FxHasher;
 use serde::de::{self, Deserialize, DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
 use std::{
     cell::{OnceCell, RefCell},
-    collections::BTreeMap,
+    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,
     },
 };
 
@@ -37,6 +37,7 @@ 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 {
@@ -319,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(
@@ -351,6 +388,18 @@ impl ReaderSource {
         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) => reader.lookup(ip)?.decode_path(path_elements),
+            ReaderSource::Memory(reader) => reader.lookup(ip)?.decode_path(path_elements),
+        }
+    }
+
     #[inline]
     fn metadata(&self) -> &maxminddb_crate::Metadata {
         match self {
@@ -360,31 +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())?;
-                Ok(ReaderWithin::Mmap(unsafe {
-                    std::mem::transmute::<Within<'_, Mmap>, Within<'static, Mmap>>(iter)
-                }))
-            }
-            ReaderSource::Memory(reader) => {
-                let iter = reader.within(network, Default::default())?;
-                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),
@@ -407,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() {
@@ -501,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
@@ -509,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,
 }
 
@@ -516,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;
@@ -524,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)?),
         }
     }
 
@@ -558,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]
@@ -594,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> {
@@ -664,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;
@@ -747,13 +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")?;
 
@@ -769,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(
@@ -796,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
@@ -807,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> {
@@ -825,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
@@ -861,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(
@@ -878,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");
@@ -898,14 +1296,10 @@ fn open_database_mmap(path: &str) -> Result<Reader, Error> {
         )
     })?;
     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)))
@@ -924,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)))
 }
@@ -971,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()
@@ -1055,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
@@ -1096,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);
+        }
+    }
+}

data/lib/maxmind/db/rust.rb

@@ -66,7 +66,7 @@ module MaxMind
       # - Reader class
       # - Metadata class
       # - InvalidDatabaseError exception
-      # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+      # - MODE_AUTO, MODE_FILE, MODE_MEMORY, MODE_MMAP, MODE_PARAM_IS_BUFFER constants
     end
   else
     # Official gem not loaded - define DB as a module
@@ -128,7 +128,7 @@ module MaxMind
         # - Reader class
         # - Metadata class
         # - InvalidDatabaseError exception
-        # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+        # - MODE_AUTO, MODE_FILE, MODE_MEMORY, MODE_MMAP, MODE_PARAM_IS_BUFFER constants
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: maxmind-db-rust
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gregory Oschwald
@@ -191,7 +191,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Unofficial high-performance Rust-based MaxMind DB reader for Ruby
 test_files: []