maxmind-db-rust 0.4.0-x86_64-linux → 0.6.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a96d9fc813a0f748b38ac9cb59d063863176f5f0981917675a3cc0b292ba16ca
-  data.tar.gz: 7dfbeab46f5323f4fc3a6c55331d047a2b2138fe7c2e84a2bfe81b2832589bcc
+  metadata.gz: 9a5acfd1e34141f95708f52bc8ded3d7c7a66f3e265de27f5f6622cc54937dfd
+  data.tar.gz: 57eed3dd6edfc9ecfc9fa460ec6bcc9de1d84d74cf9a40e02539bc37a24548bd
 SHA512:
-  metadata.gz: aeb73ff6afb0872cb895c2af4a876ad89df58b6f8222b083921afd88c0dd6bc26d17558e06ebac45a18201100cf4c47ca78c0cd4ef4cd6a31aaaa52f72756cd5
-  data.tar.gz: 1eb7d959c5ca910c61a72f03a4f024119f692c2da2c1078486c6da8a3aa3e8b9a06475fb99f2b398a2f89f4e7a719723059782687c62466570a4fe81b8ad1c26
+  metadata.gz: e9081ef975be35d614db2ba467ace5729f2c0467bc5bac354d2e50d64526f7cfb48c87f152f1dbeea3eb4c816cfc97b5b5dedd5b0cbd7882b41367690df62611
+  data.tar.gz: fbf97ed0b4805005989354dcb972df5ffb59bb14f455273eec2e491746a4b074a0eebff7a00a456ffc67a7c11957e9ed5cecdca4fd5d5a10d7c7339f228d0300

data/CHANGELOG.md

@@ -5,6 +5,107 @@ 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.6.0] - 2026-07-19
+
+### Added
+
+- Added `Reader#verify` for opt-in comprehensive database integrity checks
+  using the verifier introduced by `maxminddb` 0.30.0.
+- Added iteration and shared-reader thread-scaling benchmarks, including a
+  cache-root retention check across thread churn.
+
+### Performance
+
+- Batched Ruby array and hash insertion while decoding MMDB records to reduce
+  protected Ruby C API calls during full-record lookups.
+- Replaced per-thread string caches with one fixed-size process cache that uses
+  its Ruby root array directly, improving reuse while bounding retained memory.
+- Batched `get_many` and `get_many_path` result construction to reduce Ruby
+  array insertion overhead for large input collections.
+- Improved `IPAddr` lookup performance by converting its public integer
+  representation directly instead of allocating packed address strings.
+- Avoided allocating a temporary candidate vector on parsed-path cache hits.
+
+### Changed
+
+- Upgraded the `maxminddb` crate to 0.30.0, improving selective path decoding
+  and hardening iteration and verification of corrupt databases.
+- Documented selective lookup and input-type performance guidance, and
+  clarified that thread-safe lookups remain serialized by MRI's global VM lock.
+- Documented the file-lifecycle safety contract for memory-mapped readers and
+  the requirement to atomically replace database paths during updates.
+- Simplified reader ownership by removing redundant outer `Arc` wrappers and a
+  duplicate closed flag while preserving atomic close semantics.
+- Removed the redundant extension-level Cargo lockfile; workspace builds use
+  the root lockfile as the single dependency lock.
+- Moved MMDB-to-Ruby decoding and string-cache logic into a focused Rust module.
+- Moved metadata storage and Ruby method registration into a focused Rust
+  module.
+- Moved parsed-path ownership, hashing, matching, and conversion into a focused
+  Rust module.
+- Moved reader behavior and Ruby method registration into a focused Rust module,
+  leaving the crate root responsible only for extension initialization.
+- Moved extension namespace and cache-root setup into a focused initialization
+  module.
+- Alternated baseline and candidate subprocesses between benchmark samples to
+  reduce order and thermal bias in git-ref comparisons.
+- Added fixed-record and prebuilt-`IPAddr` benchmark cases for cache-hot and
+  input-conversion performance comparisons.
+- Extended allocation benchmarking to cover selective batch lookups.
+
+### Fixed
+
+- Made decoded MMDB strings consistently frozen regardless of whether their
+  length qualifies for the bounded string cache.
+- Decoded MMDB UTF-8 strings and map keys directly into Ruby strings from raw
+  bytes, avoiding unchecked Rust strings while preserving Ruby's behavior for
+  invalid UTF-8 in corrupt databases.
+- Propagated Ruby hash insertion errors from `Metadata#description` instead of
+  silently returning a partial description.
+
+## [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
@@ -113,3 +214,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - MODE_FILE support (use MODE_MMAP instead)
 - File descriptor support in constructor
+
+[0.6.0]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.1.4...v0.2.0
+[0.1.4]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/oschwald/maxmind-db-rust-ruby/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/oschwald/maxmind-db-rust-ruby/releases/tag/v0.1.0

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,29 @@ 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
+```
+
+Decoded MMDB strings, including hash keys, are frozen. Call `dup` before
+modifying a decoded string.
+
 ### Using IPAddr Objects
 
 ```ruby
@@ -112,13 +136,31 @@ 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
+)
 ```
 
+`MODE_AUTO`, `MODE_FILE`, and `MODE_MMAP` require the underlying file not to be
+modified or truncated while the reader is alive. To refresh a database, write
+the replacement to a new file and atomically rename it over the old path. Use
+`MODE_MEMORY` if the file lifecycle cannot be controlled this way.
+
 ### Accessing Metadata
 
 ```ruby
@@ -176,15 +218,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 +250,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,12 +271,45 @@ 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.
 
 **Returns:** `MaxMind::DB::Rust::Metadata` instance
 
+#### `verify()`
+
+Perform a comprehensive validation of the database metadata, search tree, data
+section separator, and referenced data records. Verification traverses the
+entire database and may use memory proportional to the number of distinct
+referenced values, so it is intended for explicit integrity checks rather than
+the lookup hot path.
+
+**Returns:** `true` when the database passes verification
+
+**Raises:** `MaxMind::DB::Rust::InvalidDatabaseError` when verification fails
+
 #### `close()`
 
 Close the database and release resources.
@@ -269,8 +355,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,27 +366,35 @@ 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.
-- Safe for concurrent lookups across threads.
+- Prefer `get_path` or `get_many_path` when only a small part of a record is
+  needed. Selective decoding avoids constructing the rest of the Ruby object
+  graph and can be substantially faster than a full-record lookup.
+- Textual IP address strings use the fastest input path. `IPAddr` objects are
+  supported but require Ruby method calls to extract their address family and
+  integer value.
+- For current, reproducible numbers on your own data and Ruby version, run `benchmark/compare_lookups.rb` against your database.
+- Readers are safe to share across Ruby threads. Ruby-facing lookup and decode
+  work currently runs under MRI's global VM lock, so additional Ruby threads do
+  not make one process perform lookups in parallel.
 
 ## 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.6.0
 platform: x86_64-linux
 authors:
 - Gregory Oschwald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement