maxmind-geoip2 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c1d04d352a8344e1e8d9c232ab7713bc0b74ddaa1e4a82aec61dbbf37bfd925
-  data.tar.gz: 20bcee370b35a4e098b48b36146eb7da9674f6c271ba94744a435addbd9c5e05
+  metadata.gz: f26229b50b6ba4760df9389e76c5e705dc2b5b53e7fc50eb6be25d2af74f6985
+  data.tar.gz: bfcb0fef72edaf05cdfcb1cc55be5ce2d12afbc650912e062ae263649a279736
 SHA512:
-  metadata.gz: 0331f1fe319379d035bd4f8675f775bbe31f0d3747d2f9a65754523cb6718160237d5a232d54cad7cd00cdcfe5243ff0f8a39276d749948116fc974221eb3d8a
-  data.tar.gz: 1d3e2f6c9a5847671b4b86004c7407bacf25cb271674d7dd49c5217b15d20a307ba416ec19a5f04d2050925ee689a97f01ca899f2edcb611bb44c5ee1a13ba35
+  metadata.gz: 4d3de90ee7df88d6acbef1af76202af2130e9670ad726bea5f9753581bd5e3ae962f859720458f833731f0822cc08345171ac90cde7b446c784ca7c6ca21215c
+  data.tar.gz: 34b7484739814ecd6de33435310c8cb29840534c4beed8d063c2ed00f2e0eee46338cec95bef1be5acb2ac2947be937842a2edc1f646b46460d70fa656213f6d

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.4.0 (2025-11-20)
+
+* Ruby 3.2+ is now required. If you're using Ruby 3.0 or 3.1, please use
+  version 1.3.0 of this gem.
+* A new `anonymizer` object has been added to the `MaxMind::GeoIP2::Model::Insights`
+  model. This object indicates whether the IP address is part of an anonymizing
+  network, including VPN confidence scoring, provider name detection, and network
+  last seen date. This is only available from the GeoIP2 Insights web service.
+* A new `ip_risk_snapshot` method has been added to `MaxMind::GeoIP2::Record::Traits`.
+  This field contains the risk associated with the IP address, ranging from 0.01 to
+  99 (a higher score indicates a higher risk). This is only available from the GeoIP2
+  Insights web service.
+* The `anonymous?`, `anonymous_vpn?`, `hosting_provider?`, `public_proxy?`,
+  `residential_proxy?`, and `tor_exit_node?` methods in
+  `MaxMind::GeoIP2::Record::Traits` have been deprecated. Please use the
+  corresponding methods in the `anonymizer` object from the GeoIP2 Insights
+  response instead.
+
+
+## 1.3.0 (2025-05-06)
+
+* Support for the GeoIP Anonymous Plus database has been added. To do a
+  lookup in this database, use the `anonymous_plus` method on
+  `MaxMind::GeoIP2::Reader`.
+* Ruby 3.0+ is now required. If you're using Ruby 2.5, 2.6, or 2.7, please
+  use version 1.2.0 of this gem.
+* Deprecated `metro_code` on `MaxMind::GeoIP2::Record::Location`. The code
+  values are no longer being maintained.
+
 ## 1.2.0 (2023-12-04)
 
 * `MaxMind::GeoIP2::Client` now validates the IP address before making a

data/CLAUDE.md

@@ -0,0 +1,390 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**GeoIP2-ruby** is MaxMind's official Ruby client library for:
+- **GeoIP2/GeoLite2 Web Services**: Country, City, and Insights endpoints
+- **GeoIP2/GeoLite2 Databases**: Local MMDB file reading for various database types (City, Country, ASN, Anonymous IP, Anonymous Plus, ISP, etc.)
+
+The library provides both web service clients and database readers that return strongly-typed model objects containing geographic, ISP, anonymizer, and other IP-related data.
+
+**Key Technologies:**
+- Ruby 3.2+ (uses frozen string literals and modern Ruby features)
+- MaxMind DB Reader for binary database files
+- HTTP gem for web service client functionality
+- Minitest for testing
+- RuboCop with multiple plugins for code quality
+
+## Code Architecture
+
+### Package Structure
+
+```
+lib/maxmind/geoip2/
+├── model/              # Response models (City, Insights, AnonymousIP, etc.)
+├── record/             # Data records (City, Location, Traits, etc.)
+├── client.rb           # HTTP client for MaxMind web services
+├── reader.rb           # Local MMDB file reader
+├── errors.rb           # Custom exceptions for error handling
+└── version.rb          # Version constant
+```
+
+### Key Design Patterns
+
+#### 1. **Attr Reader Pattern for Immutable Data**
+
+Models expose data through `attr_reader` attributes that are initialized in the constructor. Unlike PHP's readonly properties, Ruby uses instance variables with attr_reader:
+
+```ruby
+class City < Country
+  attr_reader :city
+  attr_reader :location
+  attr_reader :postal
+  attr_reader :subdivisions
+
+  def initialize(record, locales)
+    super
+    @city = MaxMind::GeoIP2::Record::City.new(record['city'], locales)
+    @location = MaxMind::GeoIP2::Record::Location.new(record['location'])
+    @postal = MaxMind::GeoIP2::Record::Postal.new(record['postal'])
+    @subdivisions = create_subdivisions(record['subdivisions'], locales)
+  end
+end
+```
+
+**Key Points:**
+- Instance variables are set in the constructor
+- Use `attr_reader` to expose them
+- Models and records are initialized from hash data (from JSON/DB)
+- Records are composed objects (City contains City record, Location record, etc.)
+
+#### 2. **Inheritance Hierarchies**
+
+Models follow clear inheritance patterns:
+- `Country` → base model with country/continent data
+- `City` extends `Country` → adds city, location, postal, subdivisions
+- `Insights` extends `City` → adds additional web service fields (web service only)
+- `Enterprise` extends `City` → adds enterprise-specific fields
+
+Records have similar patterns:
+- `Abstract` → base with `get` method for accessing hash data
+- `Place` extends `Abstract` → adds names/locales handling
+- Specific records (`City`, `Country`, etc.) extend `Place` or `Abstract`
+
+#### 3. **Get Method Pattern for Data Access**
+
+Both models and records use a protected `get` method to safely access hash data:
+
+```ruby
+def get(key)
+  if @record.nil? || !@record.key?(key)
+    return false if key.start_with?('is_')
+    return nil
+  end
+
+  @record[key]
+end
+```
+
+- Returns `false` for missing boolean fields (starting with `is_`)
+- Returns `nil` for missing optional fields
+- Records store the raw hash in `@record` instance variable
+
+Public methods expose data through the `get` method:
+
+```ruby
+def anonymizer_confidence
+  get('anonymizer_confidence')
+end
+
+def provider_name
+  get('provider_name')
+end
+```
+
+#### 4. **Lazy Parsing for Special Types**
+
+Some fields require parsing and are computed lazily:
+
+```ruby
+def network_last_seen
+  return @network_last_seen if defined?(@network_last_seen)
+
+  date_string = get('network_last_seen')
+
+  if !date_string
+    return nil
+  end
+
+  @network_last_seen = Date.parse(date_string)
+end
+```
+
+- Use `defined?(@variable)` to check if already parsed
+- Parse only once and cache in instance variable
+- Handle nil cases before parsing
+
+#### 5. **Web Service Only vs Database Models**
+
+Some models are only used by web services and do **not** need MaxMind DB support:
+
+**Web Service Only Models**:
+- Models that are exclusive to web service responses
+- Simpler implementation, just inherit and define in model hierarchy
+- Example: `Insights` (extends City but used only for web service)
+
+**Database-Supported Models**:
+- Models used by both web services and database files
+- Reader has specific methods (e.g., `anonymous_ip`, `anonymous_plus`, `city`)
+- Must handle MaxMind DB format data structures
+- Example: `City`, `Country`, `AnonymousIP`, `AnonymousPlus`
+
+## Testing Conventions
+
+### Running Tests
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake test
+
+# Run tests and RuboCop
+bundle exec rake  # default task
+
+# Run RuboCop only
+bundle exec rake rubocop
+
+# Run specific test file
+ruby -Ilib:test test/test_reader.rb
+```
+
+### Test Structure
+
+Tests are organized by functionality:
+- `test/test_reader.rb` - Database reader tests
+- `test/test_client.rb` - Web service client tests
+- `test/test_model_*.rb` - Model-specific tests
+- `test/data/` - Test fixtures and sample database files
+
+### Test Patterns
+
+Tests use Minitest with a constant for test data:
+
+```ruby
+class CountryModelTest < Minitest::Test
+  RAW = {
+    'continent' => {
+      'code' => 'NA',
+      'geoname_id' => 42,
+      'names' => { 'en' => 'North America' },
+    },
+    'country' => {
+      'geoname_id' => 1,
+      'iso_code' => 'US',
+      'names' => { 'en' => 'United States of America' },
+    },
+    'traits' => {
+      'ip_address' => '1.2.3.4',
+      'prefix_length' => 24,
+    },
+  }.freeze
+
+  def test_values
+    model = MaxMind::GeoIP2::Model::Country.new(RAW, ['en'])
+
+    assert_equal(42, model.continent.geoname_id)
+    assert_equal('NA', model.continent.code)
+    assert_equal('United States of America', model.country.name)
+  end
+end
+```
+
+When adding new fields to models:
+1. Update the `RAW` constant to include the new field
+2. Add assertions to verify the field is properly populated
+3. Test both presence and absence of the field (nil handling)
+4. Test with different values if applicable
+
+## Working with This Codebase
+
+### Adding New Fields to Existing Models
+
+For database models (like AnonymousPlus):
+
+1. **Add a public method** that calls `get`:
+   ```ruby
+   # A description of the field.
+   #
+   # @return [Type, nil]
+   def field_name
+     get('field_name')
+   end
+   ```
+
+2. **For fields requiring parsing** (dates, complex types), use lazy loading:
+   ```ruby
+   def network_last_seen
+     return @network_last_seen if defined?(@network_last_seen)
+
+     date_string = get('network_last_seen')
+
+     if !date_string
+       return nil
+     end
+
+     @network_last_seen = Date.parse(date_string)
+   end
+   ```
+
+For composed models (like City, Country):
+
+1. **Add `attr_reader`** for the new record/field:
+   ```ruby
+   attr_reader :new_field
+   ```
+
+2. **Initialize in constructor**:
+   ```ruby
+   def initialize(record, locales)
+     super
+     @new_field = record['new_field']
+   end
+   ```
+
+3. **Provide comprehensive YARD documentation** (`@return` tags)
+4. **Update tests** to include the new field in test data and assertions
+5. **Update CHANGELOG.md** with the change
+
+### Adding New Models
+
+When creating a new model class:
+
+1. **Determine if web service only or database-supported**
+2. **Follow the pattern** from existing similar models
+3. **Extend the appropriate base class** (e.g., `Country`, `City`, or standalone)
+4. **Use `attr_reader`** for composed record objects
+5. **Provide comprehensive YARD documentation** for all public methods
+6. **Add corresponding tests** with full coverage
+7. **If database-supported**, add a method to `Reader` class
+
+### Deprecation Guidelines
+
+When deprecating fields:
+
+1. **Use `@deprecated` in YARD doc** with version and alternative:
+   ```ruby
+   # This field is deprecated as of version 2.0.0.
+   # Use the anonymizer object from the Insights response instead.
+   #
+   # @return [Boolean]
+   # @deprecated since 2.0.0
+   def is_anonymous
+     get('is_anonymous')
+   end
+   ```
+
+2. **Keep deprecated fields functional** - don't break existing code
+3. **Update CHANGELOG.md** with deprecation notices
+4. **Document alternatives** in the deprecation message
+
+### CHANGELOG.md Format
+
+Always update `CHANGELOG.md` for user-facing changes.
+
+**Important**: Do not add a date to changelog entries until release time.
+
+- If there's an existing version entry without a date (e.g., `1.5.0`), add your changes there
+- If creating a new version entry, don't include a date - it will be added at release time
+- Use past tense for descriptions
+
+```markdown
+## 1.5.0
+
+* A new `field_name` method has been added to `MaxMind::GeoIP2::Model::ModelName`.
+  This method provides information about...
+* The `old_field` method in `MaxMind::GeoIP2::Model::ModelName` has been deprecated.
+  Please use `new_field` instead.
+```
+
+## Common Pitfalls and Solutions
+
+### Problem: Incorrect Nil Handling
+
+Using the wrong nil check can cause unexpected behavior.
+
+**Solution**: Follow these patterns:
+- Use `if !variable` or `if variable.nil?` to check for nil
+- The `get` method returns `nil` for missing keys (except `is_*` keys which return `false`)
+- Use `defined?(@variable)` to check if an instance variable has been set (for lazy loading)
+
+### Problem: Missing YARD Documentation
+
+New methods without documentation make the API harder to use.
+
+**Solution**: Always add YARD documentation:
+- Use `@return [Type, nil]` for the return type
+- Add a description of what the method returns
+- Use `@deprecated since X.Y.Z` for deprecated methods
+- Include examples in model class documentation if helpful
+
+### Problem: Test Failures After Adding Fields
+
+Tests fail because fixtures don't include new fields.
+
+**Solution**: Update all related tests:
+1. Add field to test `RAW` constant or test data hash
+2. Add assertions for the new field
+3. Test nil case if field is optional
+4. Test different data types if applicable
+
+## Code Style Requirements
+
+- **RuboCop enforced** with multiple plugins (minitest, performance, rake, thread_safety)
+- **Frozen string literals** (`# frozen_string_literal: true`) in all files
+- **Target Ruby 3.2+**
+- **No metrics cops** - AbcSize, ClassLength, MethodLength disabled
+- **Trailing commas allowed** in arrays, hashes, and arguments
+- **Use `if !condition`** instead of `unless condition` (NegatedIf disabled)
+
+Key RuboCop configurations:
+- Line length not enforced
+- Format string token checks disabled
+- Numeric predicates allowed in any style
+- Multiple assertions allowed in tests
+
+## Development Workflow
+
+### Setup
+```bash
+bundle install
+```
+
+### Before Committing
+```bash
+# Run tests and linting
+bundle exec rake
+
+# Or run separately
+bundle exec rake test
+bundle exec rake rubocop
+```
+
+### Running Single Test
+```bash
+ruby -Ilib:test test/test_reader.rb
+```
+
+### Version Requirements
+- **Ruby 3.2+** required
+- Target compatibility should match current supported Ruby versions (3.2-3.4)
+
+## Additional Resources
+
+- [API Documentation](https://www.rubydoc.info/gems/maxmind-geoip2)
+- [GeoIP2 Web Services Docs](https://dev.maxmind.com/geoip/docs/web-services)
+- [MaxMind DB Format](https://maxmind.github.io/MaxMind-DB/)
+- GitHub Issues: https://github.com/maxmind/GeoIP2-ruby/issues

data/Gemfile.lock

@@ -0,0 +1,126 @@
+PATH
+  remote: .
+  specs:
+    maxmind-geoip2 (1.4.0)
+      connection_pool (~> 2.2)
+      http (>= 4.3, < 6.0)
+      maxmind-db (~> 1.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    bigdecimal (3.3.1)
+    connection_pool (2.5.4)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    domain_name (0.6.20240107)
+    ffi (1.17.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    ffi-compiler (1.3.2)
+      ffi (>= 1.15.5)
+      rake
+    hashdiff (1.2.1)
+    http (5.3.1)
+      addressable (~> 2.8)
+      http-cookie (~> 1.0)
+      http-form_data (~> 2.2)
+      llhttp-ffi (~> 0.5.0)
+    http-cookie (1.1.0)
+      domain_name (~> 0.5)
+    http-form_data (2.3.0)
+    json (2.16.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    llhttp-ffi (0.5.1)
+      ffi-compiler (~> 1.0)
+      rake (~> 13.0)
+    maxmind-db (1.4.0)
+    minitest (5.26.2)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.6.0)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.81.7)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-minitest (0.38.2)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-thread_safety (0.7.3)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  maxmind-geoip2!
+  minitest
+  rake
+  rubocop
+  rubocop-minitest
+  rubocop-performance
+  rubocop-rake
+  rubocop-thread_safety
+  webmock
+
+BUNDLED WITH
+   2.6.9

data/README.dev.md

@@ -1,4 +1,4 @@
 # How to release
 
 See
-[here](https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/main/README.dev.md).
+[here](https://github.com/maxmind/minfraud-api-ruby/blob/main/README.dev.md).

data/README.md

@@ -133,6 +133,21 @@ record = reader.anonymous_ip('128.101.101.101')
 puts "Anonymous" if record.is_anonymous
 ```
 
+### Anonymous Plus Example
+
+```ruby
+require 'maxmind/geoip2'
+
+# This creates the Reader object which should be reused across lookups.
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP-Anonymous-Plus.mmdb',
+)
+
+record = reader.anonymous_plus('128.101.101.101')
+
+puts record.anonymizer_confidence # 30
+```
+
 ### ASN Example
 
 ```ruby
@@ -332,7 +347,7 @@ client API, please see [our support page](https://www.maxmind.com/en/support).
 
 ## Requirements
 
-This code requires Ruby version 2.5 or higher.
+This code requires Ruby version 3.2 or higher.
 
 ## Contributing
 
@@ -345,7 +360,7 @@ This library uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License
 
-This software is Copyright (c) 2020-2023 by MaxMind, Inc.
+This software is Copyright (c) 2020-2025 by MaxMind, Inc.
 
 This is free software, licensed under the [Apache License, Version
 2.0](LICENSE-APACHE) or the [MIT License](LICENSE-MIT), at your option.

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
 
@@ -10,5 +11,4 @@ end
 RuboCop::RakeTask.new
 
 desc 'Run tests and RuboCop'
-task default: :test
-task default: :rubocop
+task default: %i[test rubocop]

data/lib/maxmind/geoip2/model/anonymous_plus.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'maxmind/geoip2/model/anonymous_ip'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the Anonymous Plus database.
+      class AnonymousPlus < AnonymousIP
+        # A score ranging from 1 to 99 that is our percent confidence that the
+        # network is currently part of an actively used VPN service.
+        #
+        # @return [Integer, nil]
+        def anonymizer_confidence
+          get('anonymizer_confidence')
+        end
+
+        # The last day that the network was sighted in our analysis of
+        # anonymized networks. This value is parsed lazily.
+        #
+        # @return [Date, nil] A Date object representing the last seen date,
+        #   or nil if the date is not available.
+        def network_last_seen
+          return @network_last_seen if defined?(@network_last_seen)
+
+          date_string = get('network_last_seen')
+
+          if !date_string
+            return nil
+          end
+
+          @network_last_seen = Date.parse(date_string)
+        end
+
+        # The name of the VPN provider (e.g., NordVPN, SurfShark, etc.)
+        # associated with the network.
+        #
+        # @return [String, nil]
+        def provider_name
+          get('provider_name')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/model/city.rb

@@ -46,7 +46,7 @@ module MaxMind
 
         # @!visibility private
         def initialize(record, locales)
-          super(record, locales)
+          super
           @city = MaxMind::GeoIP2::Record::City.new(record['city'], locales)
           @location = MaxMind::GeoIP2::Record::Location.new(record['location'])
           @postal = MaxMind::GeoIP2::Record::Postal.new(record['postal'])