maxmind-db-rust 0.1.4-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e09c312b29ebe97522fcd0ac7bfb3d2f8839ae21e441eaa307172c8dac0e9d6a
+  data.tar.gz: 74a5bdc6ae7da6f09784cb05c36a46f4f6cf5a01d60c7fdb8ee3035b2168567b
+SHA512:
+  metadata.gz: 36fb733556e32833ce2afe1bad3a503c7094439f5ab0b08f8b4163e5a286c0ab3d18fefa4481758718c6307378cd5123453674c1d9741a40ed85b15d335823db
+  data.tar.gz: 0ba0534b27d5a74ec28f2e178564be1a93d79f82dd88eaab3a2658bd5a8f9cf04eb02b0ae5df843aa54f3c7d751a9dc08805b53c7a85abb56a35613de8040ce4

data/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.4] - 2025-11-16
+
+### Fixed
+
+- Release workflow for publishing multiple platform-specific gems
+
+## [0.1.3] - 2025-11-16
+
+### Added
+
+- Pre-compiled native gems for multiple platforms, eliminating the need to compile Rust during installation:
+  - `x86_64-linux` (Linux x86_64)
+  - `aarch64-linux` (Linux ARM64)
+  - `x86_64-darwin` (macOS Intel)
+  - `arm64-darwin` (macOS Apple Silicon)
+  - `x64-mingw-ucrt` (Windows)
+  - `x86_64-linux-musl` (Alpine Linux)
+- Source gem as fallback for platforms without pre-compiled binaries
+
+## [0.1.2] - 2025-11-15
+
+### Added
+
+- Automated release script (`dev-bin/release.sh`) that validates changelog dates, updates gemspec version, runs tests, and creates GitHub releases
+
+### Changed
+
+- Updated actions/checkout from v4 to v5 in GitHub workflows
+
+### Fixed
+
+- Release workflow no longer runs twice (removed redundant triggers)
+
+### Removed
+
+- Unused test/maxmind-db-reader-ruby git submodule (documentation now references upstream repository by URL)
+
+## [0.1.1] - 2025-11-15
+
+### Fixed
+
+- Release workflow now has environment set.
+
+## [0.1.0] - 2025-11-15
+
+### Added
+
+- Initial release
+- Reader class with `get()`, `get_with_prefix_length()`, `metadata()`, `close()`, and `closed()` methods
+- Metadata class with all standard MaxMind DB metadata attributes
+- Support for MODE_AUTO, MODE_MEMORY, and MODE_MMAP modes
+- Iterator support via `each` method (Enumerable interface)
+  - Iterate over all networks in database
+  - Network-scoped iteration with optional CIDR parameter (String or IPAddr)
+- InvalidDatabaseError exception for corrupt databases
+- Thread-safe implementation using Rust Arc and RwLock
+- Support for both String and IPAddr IP address inputs
+- High-performance Rust implementation using maxminddb crate
+- Comprehensive API documentation
+
+### Not Implemented
+
+- MODE_FILE support (use MODE_MMAP instead)
+- File descriptor support in constructor

data/CONTRIBUTING.md

@@ -0,0 +1,509 @@
+# Contributing to maxmind-db-rust
+
+Thank you for your interest in contributing to maxmind-db-rust! This document provides guidelines and instructions for developers.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Building the Extension](#building-the-extension)
+- [Running Tests](#running-tests)
+- [Code Quality](#code-quality)
+- [Project Structure](#project-structure)
+- [Making Changes](#making-changes)
+- [Testing Guidelines](#testing-guidelines)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.2 or higher
+- Rust toolchain (stable)
+- Bundler
+- Git
+
+### Installing Rust
+
+If you don't have Rust installed:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+```
+
+### Clone and Setup
+
+```bash
+git clone https://github.com/oschwald/maxmind-db-rust-ruby.git
+cd maxmind-db-rust-ruby
+
+# Initialize git submodules (for test data)
+git submodule update --init --recursive
+
+# Install dependencies
+bundle install
+
+# Configure git to use the .githooks directory
+git config core.hooksPath .githooks
+```
+
+This will enable the pre-commit hook that runs `precious lint` on staged files before each commit.
+
+## Building the Extension
+
+### First Time Build
+
+```bash
+# Compile the Rust extension
+bundle exec rake compile
+```
+
+This will:
+
+1. Run `extconf.rb` to generate the Makefile
+2. Compile the Rust code using rb-sys
+3. Place the compiled extension in `lib/maxmind/db/`
+
+### Clean Build
+
+```bash
+# Clean build artifacts
+bundle exec rake clean
+
+# Clean and rebuild
+bundle exec rake clobber compile
+```
+
+### Development Build (Debug)
+
+The default rake task builds in release mode. For faster compile times during development:
+
+```bash
+# Set environment variable for debug builds
+CARGO_PROFILE=dev bundle exec rake compile
+```
+
+Note: Debug builds are significantly slower at runtime but compile faster.
+
+## Running Tests
+
+### Test Organization
+
+Tests are organized into two categories:
+
+1. **Our Own Tests** (`test/*_test.rb`)
+   - Tests specific to this implementation
+   - License: ISC (same as project)
+
+2. **MaxMind Upstream Tests** (`test/maxmind/test_*.rb`)
+   - Adapted from official MaxMind-DB-Reader-ruby
+   - License: Apache-2.0 or MIT (MaxMind, Inc.)
+   - See `test/maxmind/README.md` for details
+
+### Running Tests
+
+```bash
+# Run all tests (recommended before submitting PR)
+bundle exec rake test
+
+# Run only our own tests
+bundle exec rake test_own
+
+# Run only MaxMind upstream compatibility tests
+bundle exec rake test_maxmind
+
+# Run with verbose output
+bundle exec rake test_verbose
+
+# Run specific test file
+bundle exec ruby test/reader_test.rb
+
+# Run specific test method
+bundle exec ruby test/reader_test.rb -n test_get_ipv4_address
+```
+
+### Test Data
+
+Test databases are stored in `test/data/MaxMind-DB/` as a git submodule. If tests are failing with "file not found" errors:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Code Quality
+
+### Precious (Recommended)
+
+The easiest way to run all linters and formatters is using [precious](https://github.com/houseabsolute/precious):
+
+```bash
+# Install precious (once)
+cargo install precious
+
+# Check all linters
+precious lint --all
+
+# Auto-fix all issues
+precious tidy --all
+
+# Check only staged files (useful before committing)
+precious lint --staged
+
+# Run specific linter
+precious lint -c rubocop
+```
+
+The pre-commit hook automatically runs `precious lint --staged` before each commit.
+
+### RuboCop (Ruby)
+
+```bash
+# Check Ruby code style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+
+# Check specific files
+bundle exec rubocop lib/maxmind/db/rust.rb
+```
+
+### Clippy (Rust)
+
+```bash
+# Run Rust linter
+cd ext/maxmind_db_rust
+cargo clippy -- -D warnings
+```
+
+### Formatting
+
+```bash
+# Format Rust code
+cd ext/maxmind_db_rust
+cargo fmt
+
+# Check formatting without changing files
+cargo fmt -- --check
+```
+
+## Project Structure
+
+```
+maxmind-db-rust-ruby/
+├── ext/maxmind_db_rust/          # Rust extension code
+│   ├── Cargo.toml                # Rust dependencies
+│   ├── extconf.rb                # Ruby build configuration
+│   └── src/
+│       └── lib.rs                # Main Rust implementation
+├── lib/                          # Ruby integration layer
+│   └── maxmind/
+│       └── db/
+│           └── rust.rb           # Ruby API wrapper
+├── test/                         # Test suite
+│   ├── *_test.rb                 # Our own tests
+│   ├── maxmind/                  # Upstream tests (MaxMind copyright)
+│   │   ├── README.md             # Licensing info
+│   │   └── test_*.rb             # Adapted tests
+│   └── data/
+│       └── MaxMind-DB/           # Test databases (submodule)
+├── Rakefile                      # Build and test tasks
+├── maxmind-db-rust.gemspec       # Gem specification
+├── README.md                     # User documentation
+├── CONTRIBUTING.md               # This file
+├── CHANGELOG.md                  # Version history
+└── LICENSE                       # ISC License
+```
+
+## Making Changes
+
+### Workflow
+
+1. **Create a branch** for your changes:
+
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make your changes**:
+   - Rust code: `ext/maxmind_db_rust/src/lib.rs`
+   - Ruby wrapper: `lib/maxmind/db/rust.rb`
+   - Tests: Add tests in `test/` directory
+
+3. **Compile and test**:
+
+   ```bash
+   bundle exec rake compile
+   bundle exec rake test
+   ```
+
+4. **Check code quality**:
+
+   ```bash
+   bundle exec rubocop
+   cd ext/maxmind_db_rust && cargo clippy && cargo fmt
+   ```
+
+5. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "Add feature: description"
+   ```
+
+### Commit Message Guidelines
+
+- Use present tense ("Add feature" not "Added feature")
+- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
+- First line should be 50 characters or less
+- Reference issues and pull requests when relevant
+
+Example:
+
+```
+Add support for custom metadata attributes
+
+- Implement metadata attribute getter
+- Add tests for custom attributes
+- Update documentation
+
+Fixes #123
+```
+
+## Testing Guidelines
+
+### Writing Tests
+
+When adding new features or fixing bugs:
+
+1. **Add tests to our own test suite** (`test/*_test.rb`):
+
+   ```ruby
+   def test_new_feature
+     reader = MaxMind::DB::Rust::Reader.new('path/to/test.mmdb')
+     result = reader.new_method
+     assert_equal expected_value, result
+     reader.close
+   end
+   ```
+
+2. **Ensure existing tests pass**:
+
+   ```bash
+   bundle exec rake test
+   ```
+
+3. **Test both modes** (MMAP and MEMORY) when relevant:
+   ```ruby
+   [MaxMind::DB::Rust::MODE_MMAP, MaxMind::DB::Rust::MODE_MEMORY].each do |mode|
+     reader = MaxMind::DB::Rust::Reader.new(path, mode: mode)
+     # Test logic here
+     reader.close
+   end
+   ```
+
+### Test Coverage
+
+- Test normal operation (happy path)
+- Test edge cases (empty results, boundary conditions)
+- Test error conditions (invalid input, closed readers, etc.)
+- Test thread safety for concurrent operations
+- Test both IPv4 and IPv6 addresses
+
+### Upstream Test Synchronization
+
+When the official MaxMind-DB-Reader-ruby gem is updated:
+
+1. Clone or update a local copy of the upstream repository:
+
+   ```bash
+   # Clone to a temporary location
+   git clone https://github.com/maxmind/MaxMind-DB-Reader-ruby.git /tmp/maxmind-db-reader-ruby
+   cd /tmp/maxmind-db-reader-ruby
+
+   # Or update existing clone
+   git pull origin main
+   ```
+
+2. Review changes:
+
+   ```bash
+   cd /tmp/maxmind-db-reader-ruby
+   git log --oneline --since="3 months ago" -- test/
+   git diff HEAD~10..HEAD -- test/test_reader.rb
+   ```
+
+3. Apply relevant changes to `test/maxmind/test_reader.rb`:
+   - Maintain our namespace changes (MaxMind::DB::Rust)
+   - Keep MODE_MMAP instead of MODE_FILE
+   - Preserve our path adjustments
+   - Update expected error messages if needed
+
+4. Document changes in `test/maxmind/README.md`
+
+## Submitting Changes
+
+### Before Submitting a Pull Request
+
+1. **Ensure all tests pass**:
+
+   ```bash
+   bundle exec rake test
+   ```
+
+2. **Run code quality checks**:
+
+   ```bash
+   bundle exec rubocop
+   cd ext/maxmind_db_rust && cargo clippy && cargo fmt --check
+   ```
+
+3. **Update documentation** if needed:
+   - README.md for user-facing changes
+   - CHANGELOG.md for notable changes
+   - Code comments for complex logic
+
+4. **Rebase on main**:
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   ```
+
+### Pull Request Process
+
+1. **Push your branch**:
+
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+2. **Create a pull request** on GitHub with:
+   - Clear description of changes
+   - Reference to related issues
+   - Screenshots/examples if applicable
+   - Test results
+
+3. **Address review feedback**:
+   - Make requested changes
+   - Push updates to the same branch
+   - Respond to comments
+
+4. **Wait for approval** and merge
+
+## Release Process
+
+### Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Backward-compatible functionality additions
+- **PATCH**: Backward-compatible bug fixes
+
+### Creating a Release
+
+1. **Update version** in `maxmind-db-rust.gemspec`:
+
+   ```ruby
+   s.version = '0.2.0'
+   ```
+
+2. **Update CHANGELOG.md**:
+
+   ```markdown
+   ## [0.2.0] - 2025-01-15
+
+   ### Added
+
+   - New feature X
+
+   ### Fixed
+
+   - Bug fix Y
+   ```
+
+3. **Commit version bump**:
+
+   ```bash
+   git add maxmind-db-rust.gemspec CHANGELOG.md
+   git commit -m "Bump version to 0.2.0"
+   ```
+
+4. **Create and push tag**:
+
+   ```bash
+   git tag -a v0.2.0 -m "Release version 0.2.0"
+   git push origin main
+   git push origin v0.2.0
+   ```
+
+5. **Create GitHub Release**:
+
+   Go to https://github.com/oschwald/maxmind-db-rust-ruby/releases/new and create a new release with tag `v0.2.0`.
+
+   The GitHub Actions workflow will automatically:
+   - Build native gems for all supported platforms:
+     - `x86_64-linux` (Linux x86_64)
+     - `aarch64-linux` (Linux ARM64)
+     - `x86_64-darwin` (macOS Intel)
+     - `arm64-darwin` (macOS Apple Silicon)
+     - `x64-mingw-ucrt` (Windows)
+     - `x86_64-linux-musl` (Alpine Linux)
+   - Build a source gem (fallback for unsupported platforms)
+   - Push all gems to RubyGems.org
+
+### Building Native Gems
+
+Native gems for multiple platforms are built automatically by the CI/CD pipeline using the `oxidize-rb/actions/cross-gem` GitHub Action. The workflow handles cross-compilation for all supported platforms without requiring local Docker setup.
+
+## Performance Considerations
+
+### Benchmarking
+
+When making performance-related changes:
+
+1. **Create benchmark script**:
+
+   ```ruby
+   require 'benchmark'
+   require 'maxmind/db/rust'
+
+   reader = MaxMind::DB::Rust::Reader.new('path/to/db.mmdb')
+   ips = File.readlines('test_ips.txt').map(&:strip)
+
+   Benchmark.bm do |x|
+     x.report("lookups:") do
+       100_000.times { reader.get(ips.sample) }
+     end
+   end
+   ```
+
+2. **Compare before and after** your changes
+
+3. **Document results** in PR description
+
+### Optimization Tips
+
+- Use MODE_MMAP for best performance (default)
+- Release GIL during I/O operations (already implemented)
+- Minimize Ruby object allocations in hot paths
+- Use Arc for thread-safe sharing instead of cloning
+
+## Getting Help
+
+- **Issues**: https://github.com/oschwald/maxmind-db-rust-ruby/issues
+- **Discussions**: Use GitHub Discussions for questions
+- **MaxMind Docs**: https://maxmind.github.io/MaxMind-DB/
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Provide constructive feedback
+- Focus on the code, not the person
+- Help others learn and grow
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the ISC License.
+
+Thank you for contributing! 🎉

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, Gregory Oschwald
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,343 @@
+# maxmind-db-rust
+
+[![Test](https://github.com/oschwald/maxmind-db-rust-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/oschwald/maxmind-db-rust-ruby/actions/workflows/test.yml)
+[![Lint](https://github.com/oschwald/maxmind-db-rust-ruby/actions/workflows/lint.yml/badge.svg)](https://github.com/oschwald/maxmind-db-rust-ruby/actions/workflows/lint.yml)
+
+A high-performance Rust-based Ruby gem for reading MaxMind DB files. Provides API compatibility with the official `maxmind-db` gem while leveraging Rust for superior performance.
+
+> **Note:** This is an unofficial library and is not endorsed by MaxMind. For the official Ruby library, see [maxmind-db](https://github.com/maxmind/MaxMind-DB-Reader-ruby).
+
+## Features
+
+- **High Performance**: Rust-based implementation provides significantly faster lookups than pure Ruby
+- **API Compatible**: Familiar API similar to the official MaxMind::DB gem
+- **Thread-Safe**: Safe to use from multiple threads
+- **Memory Modes**: Support for both memory-mapped (MMAP) and in-memory modes
+- **Iterator Support**: Iterate over all networks in the database (extension feature)
+- **Type Support**: Works with both String and IPAddr objects
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'maxmind-db-rust'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install maxmind-db-rust
+```
+
+## Requirements
+
+- Ruby 3.2 or higher
+- Rust toolchain (for building from source)
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'maxmind/db/rust'
+
+# Open database
+reader = MaxMind::DB::Rust::Reader.new(
+  'GeoIP2-City.mmdb',
+  mode: MaxMind::DB::Rust::MODE_MEMORY
+)
+
+# Lookup an IP address
+record = reader.get('8.8.8.8')
+if record
+  puts record['country']['iso_code']
+  puts record['country']['names']['en']
+  puts record['city']['names']['en']
+end
+
+# Close the database
+reader.close
+```
+
+### Get with Prefix Length
+
+```ruby
+require 'maxmind/db/rust'
+
+reader = MaxMind::DB::Rust::Reader.new('GeoIP2-City.mmdb')
+
+record, prefix_length = reader.get_with_prefix_length('8.8.8.8')
+puts "Record: #{record}"
+puts "Prefix length: #{prefix_length}"
+
+reader.close
+```
+
+### Using IPAddr Objects
+
+```ruby
+require 'maxmind/db/rust'
+require 'ipaddr'
+
+reader = MaxMind::DB::Rust::Reader.new('GeoIP2-City.mmdb')
+
+ip = IPAddr.new('8.8.8.8')
+record = reader.get(ip)
+
+reader.close
+```
+
+### Database Modes
+
+```ruby
+require 'maxmind/db/rust'
+
+# MODE_AUTO: Uses memory-mapped files (default, best performance)
+reader = MaxMind::DB::Rust::Reader.new(
+  'GeoIP2-City.mmdb',
+  mode: MaxMind::DB::Rust::MODE_AUTO
+)
+
+# MODE_MMAP: Explicitly use memory-mapped files (recommended)
+reader = MaxMind::DB::Rust::Reader.new(
+  'GeoIP2-City.mmdb',
+  mode: MaxMind::DB::Rust::MODE_MMAP
+)
+
+# MODE_MEMORY: Load entire database into memory
+reader = MaxMind::DB::Rust::Reader.new(
+  'GeoIP2-City.mmdb',
+  mode: MaxMind::DB::Rust::MODE_MEMORY
+)
+```
+
+### Accessing Metadata
+
+```ruby
+require 'maxmind/db/rust'
+
+reader = MaxMind::DB::Rust::Reader.new('GeoIP2-City.mmdb')
+
+metadata = reader.metadata
+puts "Database type: #{metadata.database_type}"
+puts "Node count: #{metadata.node_count}"
+puts "Record size: #{metadata.record_size}"
+puts "IP version: #{metadata.ip_version}"
+puts "Build epoch: #{metadata.build_epoch}"
+puts "Languages: #{metadata.languages.join(', ')}"
+puts "Description: #{metadata.description}"
+
+reader.close
+```
+
+### Iterator Support (Extension Feature)
+
+Iterate over all networks in the database:
+
+```ruby
+require 'maxmind/db/rust'
+
+reader = MaxMind::DB::Rust::Reader.new('GeoLite2-Country.mmdb')
+
+# Iterate over all networks
+reader.each do |network, data|
+  puts "#{network}: #{data['country']['iso_code']}"
+  break # Remove this to see all networks
+end
+
+# Iterate over networks within a specific subnet (String CIDR notation)
+reader.each('192.168.0.0/16') do |network, data|
+  puts "#{network}: #{data['city']['names']['en']}"
+end
+
+# Iterate over networks within a specific subnet (IPAddr object)
+require 'ipaddr'
+subnet = IPAddr.new('10.0.0.0/8')
+reader.each(subnet) do |network, data|
+  puts "#{network}: #{data['country']['iso_code']}"
+end
+
+# Use Enumerable methods
+countries = reader.map { |network, data| data['country']['iso_code'] }.uniq
+puts "Unique countries: #{countries.size}"
+
+reader.close
+```
+
+## API Documentation
+
+### `MaxMind::DB::Rust::Reader`
+
+#### `new(database_path, options = {})`
+
+Create a new Reader instance.
+
+**Parameters:**
+
+- `database_path` (String): Path to the MaxMind DB file
+- `options` (Hash): Optional configuration
+  - `:mode` (Symbol): One of `:MODE_AUTO`, `:MODE_MEMORY`, or `:MODE_MMAP`
+
+**Returns:** Reader instance
+
+**Raises:**
+
+- `Errno::ENOENT`: If the database file does not exist
+- `MaxMind::DB::Rust::InvalidDatabaseError`: If the file is not a valid MaxMind DB
+
+#### `get(ip_address)`
+
+Look up an IP address in the database.
+
+**Parameters:**
+
+- `ip_address` (String or IPAddr): The IP address to look up
+
+**Returns:** Hash with the record data, or `nil` if not found
+
+**Raises:**
+
+- `ArgumentError`: If looking up IPv6 in an IPv4-only database
+- `MaxMind::DB::Rust::InvalidDatabaseError`: If the database is corrupt
+
+#### `get_with_prefix_length(ip_address)`
+
+Look up an IP address and return the prefix length.
+
+**Parameters:**
+
+- `ip_address` (String or IPAddr): The IP address to look up
+
+**Returns:** Array `[record, prefix_length]` where record is a Hash or `nil`
+
+#### `metadata()`
+
+Get metadata about the database.
+
+**Returns:** `MaxMind::DB::Rust::Metadata` instance
+
+#### `close()`
+
+Close the database and release resources.
+
+#### `closed()`
+
+Check if the database has been closed.
+
+**Returns:** Boolean
+
+#### `each(network = nil) { |network, data| ... }`
+
+Iterate over networks in the database.
+
+**Parameters:**
+
+- `network` (String or IPAddr, optional): Network CIDR to iterate within (e.g., "192.168.0.0/16"). If omitted, iterates over all networks in the database.
+
+**Yields:** IPAddr network and Hash data for each entry
+
+**Returns:** Enumerator if no block given
+
+**Raises:**
+
+- `ArgumentError`: If network CIDR is invalid or IPv6 network specified for IPv4-only database
+
+### `MaxMind::DB::Rust::Metadata`
+
+Metadata attributes:
+
+- `binary_format_major_version` - Major version of the binary format
+- `binary_format_minor_version` - Minor version of the binary format
+- `build_epoch` - Unix timestamp when the database was built
+- `database_type` - Type of database (e.g., "GeoIP2-City")
+- `description` - Hash of locale codes to descriptions
+- `ip_version` - 4 for IPv4-only, 6 for IPv4/IPv6 support
+- `languages` - Array of supported locale codes
+- `node_count` - Number of nodes in the search tree
+- `record_size` - Record size in bits (24, 28, or 32)
+- `node_byte_size` - Size of a node in bytes
+- `search_tree_size` - Size of the search tree in bytes
+
+### Constants
+
+- `MaxMind::DB::Rust::MODE_AUTO` - Automatically choose the best mode (uses MMAP)
+- `MaxMind::DB::Rust::MODE_MEMORY` - Load entire database into memory
+- `MaxMind::DB::Rust::MODE_MMAP` - Use memory-mapped file I/O (recommended)
+
+### Exceptions
+
+- `MaxMind::DB::Rust::InvalidDatabaseError` - Raised when the database file is corrupt or invalid
+
+## Comparison with Official Gem
+
+| Feature          | maxmind-db (official) | maxmind-db-rust (this gem) |
+| ---------------- | --------------------- | -------------------------- |
+| Implementation   | Pure Ruby             | Rust with Ruby bindings    |
+| Performance      | Baseline              | 10-50x faster              |
+| API              | MaxMind::DB           | MaxMind::DB::Rust          |
+| MODE_FILE        | ✓                     | ✗                          |
+| MODE_MEMORY      | ✓                     | ✓                          |
+| MODE_AUTO        | ✓                     | ✓                          |
+| MODE_MMAP        | ✗                     | ✓                          |
+| Iterator support | ✗                     | ✓                          |
+| Thread-safe      | ✓                     | ✓                          |
+
+## Performance
+
+Expected performance characteristics (will vary based on hardware):
+
+- Single-threaded lookups: 300,000 - 500,000 lookups/second
+- Significantly faster than pure Ruby implementations
+- Memory-mapped mode (MMAP) provides best performance
+- Fully thread-safe for concurrent lookups
+
+## Development
+
+Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed developer documentation, including:
+
+- Development setup and prerequisites
+- Building and testing the extension
+- Code quality guidelines
+- Project structure
+- Submitting changes
+
+### Quick Start
+
+```bash
+git clone https://github.com/oschwald/maxmind-db-rust-ruby.git
+cd maxmind-db-rust-ruby
+git submodule update --init --recursive
+bundle install
+bundle exec rake compile
+bundle exec rake test
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+This software is licensed under the ISC License. See the LICENSE file for details.
+
+## Support
+
+- **Issues**: https://github.com/oschwald/maxmind-db-rust-ruby/issues
+- **Documentation**: https://www.rubydoc.info/gems/maxmind-db-rust
+
+## Credits
+
+This gem uses the [maxminddb](https://github.com/oschwald/maxminddb-rust) Rust crate for the core MaxMind DB reading functionality.
+
+Built with [magnus](https://github.com/matsadler/magnus) and [rb-sys](https://github.com/oxidize-rb/rb-sys).

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'maxmind/db/maxmind_db_rust'
+
+module MaxMind
+  module DB
+    module Rust
+      # The native extension defines:
+      # - Reader class
+      # - Metadata class
+      # - InvalidDatabaseError exception
+      # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+    end
+  end
+end

data/lib/maxmind/db/rust.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'maxmind/db/maxmind_db_rust'
+
+module MaxMind
+  # Check if DB is already defined as a Class (official gem)
+  if const_defined?(:DB) && DB.is_a?(Class)
+    # Official gem loaded - Rust module is already attached to the class by native extension
+    # Just add documentation here
+    class << DB
+      # The Rust module provides a high-performance Rust-based implementation for reading
+      # {MaxMind DB files}[https://maxmind.github.io/MaxMind-DB/].
+      #
+      # MaxMind DB is a binary file format that stores data indexed by IP address
+      # subnets (IPv4 or IPv6).
+      #
+      # This is a Rust-based implementation that provides significant performance
+      # improvements over pure Ruby implementations while maintaining API compatibility
+      # with the official MaxMind::DB gem.
+      #
+      # == Example
+      #
+      #   require 'maxmind/db/rust'
+      #
+      #   reader = MaxMind::DB::Rust::Reader.new(
+      #     'GeoIP2-City.mmdb',
+      #     mode: MaxMind::DB::Rust::MODE_MEMORY
+      #   )
+      #
+      #   record = reader.get('1.1.1.1')
+      #   if record.nil?
+      #     puts '1.1.1.1 was not found in the database'
+      #   else
+      #     puts record['country']['iso_code']
+      #     puts record['country']['names']['en']
+      #   end
+      #
+      #   reader.close
+      #
+      # == Using the Iterator
+      #
+      #   require 'maxmind/db/rust'
+      #
+      #   reader = MaxMind::DB::Rust::Reader.new('GeoLite2-Country.mmdb')
+      #
+      #   # Iterate over all networks in the database
+      #   reader.each do |network, data|
+      #     puts "#{network}: #{data['country']['iso_code']}"
+      #   end
+      #
+      #   # Iterate over networks within a specific subnet
+      #   reader.each('192.168.0.0/16') do |network, data|
+      #     puts "#{network}: #{data['city']['names']['en']}"
+      #   end
+      #
+      #   # Also accepts IPAddr objects
+      #   subnet = IPAddr.new('10.0.0.0/8')
+      #   reader.each(subnet) do |network, data|
+      #     puts "#{network}: #{data['country']['iso_code']}"
+      #   end
+      #
+      #   reader.close
+      #
+      # The Rust module (MaxMind::DB::Rust) defines:
+      # - Reader class
+      # - Metadata class
+      # - InvalidDatabaseError exception
+      # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+    end
+  else
+    # Official gem not loaded - define DB as a module
+    module DB
+      # Rust provides a high-performance Rust-based implementation for reading
+      # {MaxMind DB files}[https://maxmind.github.io/MaxMind-DB/].
+      #
+      # MaxMind DB is a binary file format that stores data indexed by IP address
+      # subnets (IPv4 or IPv6).
+      #
+      # This is a Rust-based implementation that provides significant performance
+      # improvements over pure Ruby implementations while maintaining API compatibility
+      # with the official MaxMind::DB gem.
+      #
+      # == Example
+      #
+      #   require 'maxmind/db/rust'
+      #
+      #   reader = MaxMind::DB::Rust::Reader.new(
+      #     'GeoIP2-City.mmdb',
+      #     mode: MaxMind::DB::Rust::MODE_MEMORY
+      #   )
+      #
+      #   record = reader.get('1.1.1.1')
+      #   if record.nil?
+      #     puts '1.1.1.1 was not found in the database'
+      #   else
+      #     puts record['country']['iso_code']
+      #     puts record['country']['names']['en']
+      #   end
+      #
+      #   reader.close
+      #
+      # == Using the Iterator
+      #
+      #   require 'maxmind/db/rust'
+      #
+      #   reader = MaxMind::DB::Rust::Reader.new('GeoLite2-Country.mmdb')
+      #
+      #   # Iterate over all networks in the database
+      #   reader.each do |network, data|
+      #     puts "#{network}: #{data['country']['iso_code']}"
+      #   end
+      #
+      #   # Iterate over networks within a specific subnet
+      #   reader.each('192.168.0.0/16') do |network, data|
+      #     puts "#{network}: #{data['city']['names']['en']}"
+      #   end
+      #
+      #   # Also accepts IPAddr objects
+      #   subnet = IPAddr.new('10.0.0.0/8')
+      #   reader.each(subnet) do |network, data|
+      #     puts "#{network}: #{data['country']['iso_code']}"
+      #   end
+      #
+      #   reader.close
+      module Rust
+        # The native extension defines:
+        # - Reader class
+        # - Metadata class
+        # - InvalidDatabaseError exception
+        # - MODE_AUTO, MODE_MEMORY, MODE_MMAP constants
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,188 @@
+--- !ruby/object:Gem::Specification
+name: maxmind-db-rust
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: x86_64-linux
+authors:
+- Gregory Oschwald
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler-dock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.36'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.36'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-thread_safety
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: An unofficial high-performance Rust-based gem for reading MaxMind DB
+  files. Provides API compatibility with the official maxmind-db gem while leveraging
+  Rust for superior performance. This library is not endorsed by MaxMind.
+email: oschwald@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- ext/maxmind_db_rust/lib/maxmind/db/rust.rb
+- lib/maxmind/db/3.2/maxmind_db_rust.so
+- lib/maxmind/db/3.3/maxmind_db_rust.so
+- lib/maxmind/db/3.4/maxmind_db_rust.so
+- lib/maxmind/db/rust.rb
+homepage: https://github.com/oschwald/maxmind-db-rust-ruby
+licenses:
+- ISC
+metadata:
+  bug_tracker_uri: https://github.com/oschwald/maxmind-db-rust-ruby/issues
+  changelog_uri: https://github.com/oschwald/maxmind-db-rust-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/maxmind-db-rust
+  homepage_uri: https://github.com/oschwald/maxmind-db-rust-ruby
+  source_code_uri: https://github.com/oschwald/maxmind-db-rust-ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Unofficial high-performance Rust-based MaxMind DB reader for Ruby
+test_files: []