maxmind-db-rust 0.4.0-x86_64-linux-musl → 0.5.0-x86_64-linux-musl

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a828a17a7c839a34c1bc2a56faefbff229387754ba5c9f9ed918681dac08370f
-  data.tar.gz: 9be96cbcad356a3ed0dd63b3a894da11c33fd3cbbf0315eec48e584481f7a99c
+  metadata.gz: 5e802338b0926b0b3569390005ff7bc4230143173bc1ea4dbf5ce3f9a5e9dd04
+  data.tar.gz: d6b93a5eff956d47daf4ca687ea479430c8f522b191cfff6ae4937318d962b78
 SHA512:
-  metadata.gz: 5229ef74a197ee6ac61344960dbab9470071e24dbe1fc911fc32b544ad5c104465af2fd079f989e693e1bf20555c7d9ef3451aa5c486c21e909e063159906ebd
-  data.tar.gz: 7bb775535b3a825276dca19e98f0e2cd5d883cf2eeaa6ea2de82079f9ca55d7347d69eccbf99e9121b3c707772d5903e02ffd96a6546e5a9fdfe3dd328cfbd75
+  metadata.gz: f9a77f7cff6be16ee203b9e8311c22fa842c11280a29949120e229e021d69c417622f3c178ad27a4430797cf1bb9fae62e013ad868dd43e1faec539d4c3d8de8
+  data.tar.gz: d4d8b3ad41716483176aeccedbfc8e398dfd124b09eecc5583a1806a607f812e3b9de73cbac35d6118c278665aaca1cfe8dd992c5cdbf66c0cdf97989a443618

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/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/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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: maxmind-db-rust
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: x86_64-linux-musl
 authors:
 - Gregory Oschwald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest