maxmind-db 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e8404a64573590d7a01fd9199ae1be5bb1892407
-  data.tar.gz: cfdec2ef12cae84fa914784b90c386d1006fdf47
+SHA256:
+  metadata.gz: d5705dca32ee40fdadd07a1f6abc8a0ff56e23b699ecb9ba159344a9325c8456
+  data.tar.gz: d71304945c1c09f3af09a85b03dbbcf8cbeb4652456441a7f6978b2cb9db6adc
 SHA512:
-  metadata.gz: 263eff4235eadc529e14266772c3db95bc17950ebc7d73fbb3f5d20ee76f3b2f50035c97ad2e39454e5dbd65dd6093fc56f3a6dd3b8d91a69037b8e396986366
-  data.tar.gz: 8fe05ac4631539293ee2d1485fe7c1908858ef952d76e60e75d9f601f356263bb47928bc8dd670c2989df4437cb0d2a876869c662b1f4aab36d0e8a81ce19552
+  metadata.gz: b8c1a541fcf270945c34254e2e5817ac52864f6cea427d223cb4b5c9c4036afdc61380954462fe063beeacd3407507a647eff776ab8913a561eef6eed71a6730
+  data.tar.gz: 70c1967f07e22885938b7fb1e9cbd0a73c9d4f3efab144a6aa4c2e40bac81ce8445d2702ad51d2b32e028a6eef053f132542d9d9c1086030d224575a4bb39e64

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.2.0 (2023-11-22)
+
+* Ruby 2.4 is no longer supported. If you're using Ruby 2.4, please use
+  version 1.1.1 of this gem.
+* `Object#respond_to?` is no longer called on every read. Pull request by
+  Jean byroot Boussier. GitHub #65.
+* The `get` and `get_prefix_length` methods now accept the IP addresses as
+  `IPAddr` objects. Strings are still accepted too. Pull request by Eddie
+  Lebow. GitHub #69.
+
+## 1.1.1 (2020-06-23)
+
+* Fixed the memory reader's inspect method to no longer attempt to modify a
+  frozen string. Pull request by Tietew. GitHub #35.
+
 ## 1.1.0 (2020-01-08)
 
 * The method `get_with_prefix_length` was added. This method returns both

data/Gemfile

@@ -2,7 +2,4 @@
 
 source 'https://rubygems.org'
 
-gem 'minitest', group: :development
-gem 'rake', group: :development
-gem 'rubocop', group: :development
-gem 'rubocop-performance', group: :development
+gemspec

data/README.dev.md

@@ -1,14 +1,22 @@
 # How to release
-* Update changelog and set release date
-* Bump version in `maxmind-db.gemspec`
+* Ensure tests pass: `rake`
+* Update changelog: Set version and release date
+* Set version in `maxmind-db.gemspec`
+* Add them: `git add -p`
+* Create a branch e.g. `horgh/release` and switch to it.
+  * `main` is protected.
 * Commit: `git commit -m v1.0.0`
 * Tag: `git tag -a v1.0.0 -m v1.0.0`
 * Clean up to be sure nothing stray gets into gem: `git clean -dxff`
 * Create `.gem` file: `gem build maxmind-db.gemspec`
 * Complete prerequisites (see below)
+  * You only need to do this once. You can tell if this is necessary if you
+    are lacking `:rubygems_api_key` in `~/.local/share/gem/credentials`
+    (previously `~/.gem/credentials`)
 * Upload to rubygems.org: `gem push maxmind-db-1.0.0.gem`
 * Push: `git push`
 * Push tag: `git push --tags`
+* Make a PR and get it merged.
 * Double check it looks okay at https://rubygems.org/gems/maxmind-db and
   https://www.rubydoc.info/gems/maxmind-db
 
@@ -18,7 +26,7 @@
 ## Step 1
 Sign up for an account at rubygems.org if you don't have one.
 
-Enable multi factor authentication.
+Enable multi factor authentication (for both UI and API).
 
 
 ## Step 2
@@ -29,5 +37,9 @@ They do this by using the `gem owner` command
 
 
 ## Step 3
-Go to your rubygems.org profile and find the curl command to run to
-download your API key.
+Run `gem signin`. This will prompt you for your username and password, and
+then create an API key for you. Select the scopes `index_rubygems` and
+`push_rubygem` (I'm not sure the former is required, but anyway).
+
+Note you may need an up to date version of rubygems to do this as I believe
+support for API keys like this is a newer addition.

data/README.md

@@ -6,20 +6,12 @@ This is the Ruby API for reading [MaxMind
 DB](https://maxmind.github.io/MaxMind-DB/) files. MaxMind DB is a binary
 file format that stores data indexed by IP address subnets (IPv4 or IPv6).
 
-
 ## Installation
 
 ```
 gem install maxmind-db
 ```
 
-Or from source:
-
-```
-gem build maxmind-db.spec
-gem install ./maxmind-db-xxx.gem
-```
-
 ## Usage
 
 ```ruby
@@ -43,8 +35,7 @@ For more information see the
 
 ## Requirements
 
-This code requires Ruby version 2.4 or higher. Older versions may work, but
-are not supported.
+This code requires Ruby version 2.5 or higher.
 
 ## Contributing
 
@@ -65,7 +56,7 @@ This library uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License
 
-This software is Copyright (c) 2018 - 2020 by MaxMind, Inc.
+This software is Copyright (c) 2018 - 2023 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/bin/mmdb-benchmark.rb

@@ -29,9 +29,9 @@ end
 
 def print_usage
   # rubocop:disable Style/StderrPuts
-  STDERR.puts "Usage: #{$PROGRAM_NAME} <MMDB file> <IP file>"
-  STDERR.puts
-  STDERR.puts 'Benchmark by reading IPs from the IP file and looking up each one in the MMDB file.'
+  $stderr.puts "Usage: #{$PROGRAM_NAME} <MMDB file> <IP file>"
+  $stderr.puts
+  $stderr.puts 'Benchmark by reading IPs from the IP file and looking up each one in the MMDB file.'
   # rubocop:enable Style/StderrPuts
 end
 

data/lib/maxmind/db/decoder.rb

@@ -2,14 +2,18 @@
 
 require 'maxmind/db/errors'
 
-module MaxMind # :nodoc:
+module MaxMind
   class DB
     # +Decoder+ decodes a {MaxMind DB}[https://maxmind.github.io/MaxMind-DB/]
     # data section.
     #
     # Typically you will interact with this class through a Reader rather than
     # directly.
-    class Decoder # :nodoc:
+    #
+    # @!visibility private
+    class Decoder
+      # rubocop:disable Style/OptionalBooleanParameter
+
       # Create a +Decoder+.
       #
       # +io+ is the DB. It must provide a +read+ method. It must be opened in
@@ -26,6 +30,7 @@ module MaxMind # :nodoc:
         @pointer_base = pointer_base
         @pointer_test = pointer_test
       end
+      # rubocop:enable Style/OptionalBooleanParameter
 
       private
 

data/lib/maxmind/db/errors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module MaxMind # :nodoc:
+module MaxMind
   class DB
     # An InvalidDatabaseError means the {MaxMind
     # DB}[https://maxmind.github.io/MaxMind-DB/] file is corrupt or invalid.

data/lib/maxmind/db/file_reader.rb

@@ -2,13 +2,40 @@
 
 require 'maxmind/db/errors'
 
-module MaxMind # :nodoc:
+module MaxMind
   class DB
-    class FileReader # :nodoc:
+    # @!visibility private
+    class FileReader
+      if ::File.method_defined?(:pread)
+        PReadFile = ::File
+      else
+        # For Windows support
+        class PReadFile
+          def initialize(filename, mode)
+            @mutex = Mutex.new
+            @file = File.new(filename, mode)
+          end
+
+          def size
+            @file.size
+          end
+
+          def close
+            @file.close
+          end
+
+          def pread(size, offset)
+            @mutex.synchronize do
+              @file.seek(offset, IO::SEEK_SET)
+              @file.read(size)
+            end
+          end
+        end
+      end
+
       def initialize(filename)
-        @fh = File.new(filename, 'rb')
+        @fh = PReadFile.new(filename, 'rb')
         @size = @fh.size
-        @mutex = Mutex.new
       end
 
       attr_reader :size
@@ -20,15 +47,7 @@ module MaxMind # :nodoc:
       def read(offset, size)
         return ''.b if size == 0
 
-        # When we support only Ruby 2.5+, remove this and require pread.
-        if @fh.respond_to?(:pread)
-          buf = @fh.pread(size, offset)
-        else
-          @mutex.synchronize do
-            @fh.seek(offset, IO::SEEK_SET)
-            buf = @fh.read(size)
-          end
-        end
+        buf = @fh.pread(size, offset)
 
         raise InvalidDatabaseError, 'The MaxMind DB file contains bad data' if buf.nil? || buf.length != size
 

data/lib/maxmind/db/memory_reader.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module MaxMind # :nodoc:
+module MaxMind
   class DB
-    class MemoryReader # :nodoc:
+    # @!visibility private
+    class MemoryReader
       def initialize(filename, options = {})
         if options[:is_buffer]
           @buf = filename
@@ -18,8 +19,7 @@ module MaxMind # :nodoc:
 
       # Override to not show @buf in inspect to avoid showing it in irb.
       def inspect
-        s = "#<#{self.class.name}:0x#{self.class.object_id.to_s(16)} "
-        s << '@size=' << @size.inspect << '>'
+        "#<#{self.class.name}:0x#{self.class.object_id.to_s(16)}, @size=#{@size.inspect}>"
       end
 
       def close; end

data/lib/maxmind/db/metadata.rb

@@ -1,42 +1,64 @@
 # frozen_string_literal: true
 
-module MaxMind # :nodoc:
+module MaxMind
   class DB
     # Metadata holds metadata about a {MaxMind
-    # DB}[https://maxmind.github.io/MaxMind-DB/] file.
+    # DB}[https://maxmind.github.io/MaxMind-DB/] file. See
+    # https://maxmind.github.io/MaxMind-DB/#database-metadata for the
+    # specification.
     class Metadata
       # The number of nodes in the database.
+      #
+      # @return [Integer]
       attr_reader :node_count
 
       # The bit size of a record in the search tree.
+      #
+      # @return [Integer]
       attr_reader :record_size
 
       # The IP version of the data in the database. A value of 4 means the
       # database only supports IPv4. A database with a value of 6 may support
       # both IPv4 and IPv6 lookups.
+      #
+      # @return [Integer]
       attr_reader :ip_version
 
       # A string identifying the database type. e.g., "GeoIP2-City".
+      #
+      # @return [String]
       attr_reader :database_type
 
       # An array of locale codes supported by the database.
+      #
+      # @return [Array<String>]
       attr_reader :languages
 
       # The major version number of the binary format used when creating the
       # database.
+      #
+      # @return [Integer]
       attr_reader :binary_format_major_version
 
       # The minor version number of the binary format used when creating the
       # database.
+      #
+      # @return [Integer]
       attr_reader :binary_format_minor_version
 
       # The Unix epoch for the build time of the database.
+      #
+      # @return [Integer]
       attr_reader :build_epoch
 
       # A hash from locales to text descriptions of the database.
+      #
+      # @return [Hash<String, String>]
       attr_reader :description
 
       # +m+ is a hash representing the metadata map.
+      #
+      # @!visibility private
       def initialize(map)
         @node_count                  = map['node_count']
         @record_size                 = map['record_size']
@@ -50,11 +72,15 @@ module MaxMind # :nodoc:
       end
 
       # The size of a node in bytes.
+      #
+      # @return [Integer]
       def node_byte_size
         @record_size / 4
       end
 
       # The size of the search tree in bytes.
+      #
+      # @return [Integer]
       def search_tree_size
         @node_count * node_byte_size
       end

data/lib/maxmind/db.rb

@@ -3,11 +3,11 @@
 require 'ipaddr'
 require 'maxmind/db/decoder'
 require 'maxmind/db/errors'
-require 'maxmind/db/file_reader.rb'
-require 'maxmind/db/memory_reader.rb'
-require 'maxmind/db/metadata.rb'
+require 'maxmind/db/file_reader'
+require 'maxmind/db/memory_reader'
+require 'maxmind/db/metadata'
 
-module MaxMind # :nodoc:
+module MaxMind
   # DB provides a way to read {MaxMind DB
   # files}[https://maxmind.github.io/MaxMind-DB/].
   #
@@ -31,11 +31,6 @@ module MaxMind # :nodoc:
   #   end
   #
   #   reader.close
-  #
-  # == Exceptions
-  #
-  # DB raises an InvalidDatabaseError if the database is corrupt or invalid. It
-  # can raise other exceptions, such as ArgumentError, if other errors occur.
   class DB
     # Choose the default method to open the database. Currently the default is
     # MODE_FILE.
@@ -47,7 +42,9 @@ module MaxMind # :nodoc:
     MODE_MEMORY = :MODE_MEMORY
     # Treat the database parameter as containing a database already read into
     # memory. It must be a binary string. This primarily exists for testing.
-    MODE_PARAM_IS_BUFFER = :MODE_PARAM_IS_BUFFER # :nodoc:
+    #
+    # @!visibility private
+    MODE_PARAM_IS_BUFFER = :MODE_PARAM_IS_BUFFER
 
     DATA_SECTION_SEPARATOR_SIZE = 16
     private_constant :DATA_SECTION_SEPARATOR_SIZE
@@ -59,7 +56,9 @@ module MaxMind # :nodoc:
     private_constant :METADATA_MAX_SIZE
 
     # Return the metadata associated with the {MaxMind
-    # DB}[https://maxmind.github.io/MaxMind-DB/] as a Metadata object.
+    # DB}[https://maxmind.github.io/MaxMind-DB/]
+    #
+    # @return [MaxMind::DB::Metadata]
     attr_reader :metadata
 
     # Create a DB. A DB provides a way to read {MaxMind DB
@@ -70,20 +69,20 @@ module MaxMind # :nodoc:
     # is safe to use after forking only if you use MODE_MEMORY or if your
     # version of Ruby supports IO#pread.
     #
-    # Creating the DB may raise an exception if initialization fails.
+    # @param database [String] a path to a {MaxMind
+    #   DB}[https://maxmind.github.io/MaxMind-DB/].
     #
-    # +database+ is a path to a {MaxMind
-    # DB}[https://maxmind.github.io/MaxMind-DB/].
+    # @param options [Hash<Symbol, Symbol>] options controlling the behavior of
+    #   the DB.
     #
-    # +options+ is an option hash where each key is a symbol. The options
-    # control the behaviour of the DB.
+    # @option options [Symbol] :mode Defines how to open the database. It may
+    #   be one of MODE_AUTO, MODE_FILE, or MODE_MEMORY. If you don't provide
+    #   one, DB uses MODE_AUTO. Refer to the definition of those constants for
+    #   an explanation of their meaning.
     #
-    # The available options are:
+    # @raise [InvalidDatabaseError] if the database is corrupt or invalid.
     #
-    # [+:mode+] defines how to open the database. It may be one of MODE_AUTO,
-    #           MODE_FILE, or MODE_MEMORY. If you don't provide one, DB uses
-    #           MODE_AUTO. Refer to the definition of those constants for an
-    #           explanation of their meaning.
+    # @raise [ArgumentError] if the mode is invalid.
     def initialize(database, options = {})
       options[:mode] = MODE_AUTO unless options.key?(:mode)
 
@@ -125,37 +124,45 @@ module MaxMind # :nodoc:
       end
     end
 
-    # Return the record for the +ip_address+ in the {MaxMind
+    # Return the record for the IP address in the {MaxMind
     # DB}[https://maxmind.github.io/MaxMind-DB/]. The record can be one of
     # several types and depends on the contents of the database.
     #
-    # If no record is found for +ip_address+, +get+ returns +nil+.
+    # If no record is found for the IP address, +get+ returns +nil+.
+    #
+    # @param ip_address [String, IPAddr] IPv4 or IPv6 address.
     #
-    # +get+ raises an exception if there is an error performing the lookup.
+    # @raise [ArgumentError] if you attempt to look up an IPv6 address in an
+    #   IPv4-only database.
     #
-    # +ip_address+ is a string in the standard notation. It may be IPv4 or
-    # IPv6.
+    # @raise [InvalidDatabaseError] if the database is corrupt or invalid.
+    #
+    # @return [Object, nil]
     def get(ip_address)
       record, = get_with_prefix_length(ip_address)
 
       record
     end
 
-    # Return an array containing the record for the +ip_address+ in the
+    # Return an array containing the record for the IP address in the
     # {MaxMind DB}[https://maxmind.github.io/MaxMind-DB/] and its associated
     # network prefix length. The record can be one of several types and
     # depends on the contents of the database.
     #
-    # If no record is found for +ip_address+, the record will be +nil+ and
+    # If no record is found for the IP address, the record will be +nil+ and
     # the prefix length will be the value for the missing network.
     #
-    # +get_with_prefix_length+ raises an exception if there is an error
-    # performing the lookup.
+    # @param ip_address [String, IPAddr] IPv4 or IPv6 address.
+    #
+    # @raise [ArgumentError] if you attempt to look up an IPv6 address in an
+    #   IPv4-only database.
+    #
+    # @raise [InvalidDatabaseError] if the database is corrupt or invalid.
     #
-    # +ip_address+ is a string in the standard notation. It may be IPv4 or
-    # IPv6.
+    # @return [Array<(Object, Integer)>]
     def get_with_prefix_length(ip_address)
-      ip = IPAddr.new(ip_address)
+      ip = ip_address.is_a?(IPAddr) ? ip_address : IPAddr.new(ip_address)
+
       # We could check the IP has the correct prefix (32 or 128) but I do not
       # for performance reasons.
 
@@ -192,7 +199,7 @@ module MaxMind # :nodoc:
         break if depth >= bit_count || node >= node_count
 
         c = packed[depth >> 3].ord
-        bit = 1 & (c >> 7 - (depth % 8))
+        bit = 1 & (c >> (7 - (depth % 8)))
         node = read_node(node, bit)
         depth += 1
       end
@@ -221,8 +228,6 @@ module MaxMind # :nodoc:
 
     # Read a record from the indicated node. Index indicates whether it's the
     # left (0) or right (1) record.
-    #
-    # rubocop:disable Metrics/CyclomaticComplexity
     def read_node(node_number, index)
       base_offset = node_number * @node_byte_size
 
@@ -253,7 +258,6 @@ module MaxMind # :nodoc:
 
       raise InvalidDatabaseError, "Unsupported record size: #{@record_size}"
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     def resolve_data_pointer(pointer)
       offset_in_file = pointer - @node_count + @search_tree_size
@@ -268,7 +272,7 @@ module MaxMind # :nodoc:
     end
 
     def find_metadata_start
-      metadata_max_size = @size < METADATA_MAX_SIZE ? @size : METADATA_MAX_SIZE
+      metadata_max_size = [@size, METADATA_MAX_SIZE].min
 
       stop_index = @size - metadata_max_size
       index = @size - METADATA_START_MARKER_LENGTH
@@ -290,8 +294,7 @@ module MaxMind # :nodoc:
 
     # Close the DB and return resources to the system.
     #
-    # There is no useful return value. #close raises an exception if there is
-    # an error.
+    # @return [void]
     def close
       @io.close
     end

data/maxmind-db.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |s|
   s.files       = Dir['**/*']
   s.name        = 'maxmind-db'
   s.summary     = 'A gem for reading MaxMind DB files.'
-  s.version     = '1.1.0'
+  s.version     = '1.2.0'
 
   s.description = 'A gem for reading MaxMind DB files. MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6).'
   s.email       = 'support@maxmind.com'
@@ -13,10 +13,16 @@ Gem::Specification.new do |s|
   s.licenses    = ['Apache-2.0', 'MIT']
   s.metadata = {
     'bug_tracker_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby/issues',
-    'changelog_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/master/CHANGELOG.md',
-    'documentation_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby',
+    'changelog_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/main/CHANGELOG.md',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/maxmind-db',
     'homepage_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby',
     'source_code_uri' => 'https://github.com/maxmind/MaxMind-DB-Reader-ruby',
+    'rubygems_mfa_required' => 'true',
   }
-  s.required_ruby_version = '>= 2.4.0'
+  s.required_ruby_version = '>= 2.5.0'
+
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'rubocop-performance'
 end

data/test/data/LICENSE

@@ -0,0 +1,4 @@
+This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
+Unported License. To view a copy of this license, visit
+http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
+Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.