maxmind-geoip2 0.2.0 → 0.3.0

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

@@ -2,31 +2,35 @@
 
 require 'maxmind/geoip2/model/abstract'
 
-module MaxMind::GeoIP2::Model
-  # Model class for the GeoIP2 Domain database.
-  class Domain < Abstract
-    # The second level domain associated with the IP address. This will be
-    # something like "example.com" or "example.co.uk", not "foo.example.com".
-    #
-    # @return [String, nil]
-    def domain
-      get('domain')
-    end
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the GeoIP2 Domain database.
+      class Domain < Abstract
+        # The second level domain associated with the IP address. This will be
+        # something like "example.com" or "example.co.uk", not "foo.example.com".
+        #
+        # @return [String, nil]
+        def domain
+          get('domain')
+        end
 
-    # The IP address that the data in the model is for.
-    #
-    # @return [String]
-    def ip_address
-      get('ip_address')
-    end
+        # The IP address that the data in the model is for.
+        #
+        # @return [String]
+        def ip_address
+          get('ip_address')
+        end
 
-    # The network in CIDR notation associated with the record. In particular,
-    # this is the largest network where all of the fields besides ip_address
-    # have the same value.
-    #
-    # @return [String]
-    def network
-      get('network')
+        # The network in CIDR notation associated with the record. In particular,
+        # this is the largest network where all of the fields besides ip_address
+        # have the same value.
+        #
+        # @return [String]
+        def network
+          get('network')
+        end
+      end
     end
   end
 end

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

@@ -2,14 +2,18 @@
 
 require 'maxmind/geoip2/model/city'
 
-module MaxMind::GeoIP2::Model
-  # Model class for the data returned by GeoIP2 Enterprise database lookups.
-  #
-  # The only difference between the City and Insights model classes is which
-  # fields in each record may be populated. See
-  # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
-  #
-  # See {MaxMind::GeoIP2::Model::City} for inherited methods.
-  class Enterprise < City
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by GeoIP2 Enterprise database lookups.
+      #
+      # The only difference between the City and Insights model classes is which
+      # fields in each record may be populated. See
+      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      #
+      # See {MaxMind::GeoIP2::Model::City} for inherited methods.
+      class Enterprise < City
+      end
+    end
   end
 end

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

@@ -2,13 +2,17 @@
 
 require 'maxmind/geoip2/model/city'
 
-module MaxMind::GeoIP2::Model
-  # Model class for the data returned by the GeoIP2 Precision Insights web
-  # service.
-  #
-  # The only difference between the City and Insights model classes is which
-  # fields in each record may be populated. See
-  # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
-  class Insights < City
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 Precision Insights web
+      # service.
+      #
+      # The only difference between the City and Insights model classes is which
+      # fields in each record may be populated. See
+      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      class Insights < City
+      end
+    end
   end
 end

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

@@ -2,52 +2,56 @@
 
 require 'maxmind/geoip2/model/abstract'
 
-module MaxMind::GeoIP2::Model
-  # Model class for the GeoIP2 ISP database.
-  class ISP < Abstract
-    # The autonomous system number associated with the IP address.
-    #
-    # @return [Integer, nil]
-    def autonomous_system_number
-      get('autonomous_system_number')
-    end
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the GeoIP2 ISP database.
+      class ISP < Abstract
+        # The autonomous system number associated with the IP address.
+        #
+        # @return [Integer, nil]
+        def autonomous_system_number
+          get('autonomous_system_number')
+        end
 
-    # The organization associated with the registered autonomous system number
-    # for the IP address.
-    #
-    # @return [String, nil]
-    def autonomous_system_organization
-      get('autonomous_system_organization')
-    end
+        # The organization associated with the registered autonomous system number
+        # for the IP address.
+        #
+        # @return [String, nil]
+        def autonomous_system_organization
+          get('autonomous_system_organization')
+        end
 
-    # The IP address that the data in the model is for.
-    #
-    # @return [String]
-    def ip_address
-      get('ip_address')
-    end
+        # The IP address that the data in the model is for.
+        #
+        # @return [String]
+        def ip_address
+          get('ip_address')
+        end
 
-    # The name of the ISP associated with the IP address.
-    #
-    # @return [String, nil]
-    def isp
-      get('isp')
-    end
+        # The name of the ISP associated with the IP address.
+        #
+        # @return [String, nil]
+        def isp
+          get('isp')
+        end
 
-    # The network in CIDR notation associated with the record. In particular,
-    # this is the largest network where all of the fields besides ip_address
-    # have the same value.
-    #
-    # @return [String]
-    def network
-      get('network')
-    end
+        # The network in CIDR notation associated with the record. In particular,
+        # this is the largest network where all of the fields besides ip_address
+        # have the same value.
+        #
+        # @return [String]
+        def network
+          get('network')
+        end
 
-    # The name of the organization associated with the IP address.
-    #
-    # @return [String, nil]
-    def organization
-      get('organization')
+        # The name of the organization associated with the IP address.
+        #
+        # @return [String, nil]
+        def organization
+          get('organization')
+        end
+      end
     end
   end
 end

data/lib/maxmind/geoip2/reader.rb

@@ -11,267 +11,269 @@ require 'maxmind/geoip2/model/domain'
 require 'maxmind/geoip2/model/enterprise'
 require 'maxmind/geoip2/model/isp'
 
-module MaxMind::GeoIP2
-  # Reader is a reader for the GeoIP2/GeoLite2 database format. IP addresses
-  # can be looked up using the database specific methods.
-  #
-  # == Example
-  #
-  #   require 'maxmind/geoip2'
-  #
-  #   reader = MaxMind::GeoIP2::Reader.new('GeoIP2-Country.mmdb')
-  #
-  #   record = reader.country('1.2.3.4')
-  #   puts record.country.iso_code
-  #
-  #   reader.close
-  class Reader
-    # Create a Reader for looking up IP addresses in a GeoIP2/GeoLite2 database
-    # file.
-    #
-    # If you're performing multiple lookups, it's most efficient to create one
-    # Reader and reuse it.
-    #
-    # Once created, the Reader is safe to use for lookups from multiple
-    # threads. It is safe to use after forking only if you use
-    # MaxMind::DB::MODE_MEMORY or if your version of Ruby supports IO#pread.
-    #
-    # @param database [String] a path to a GeoIP2/GeoLite2 database file.
-    #
-    # @param locales [Array<String>] a list of locale codes to use in the name
-    #   property from most preferred to least preferred.
-    #
-    # @param options [Hash<Symbol, Symbol>] options controlling the behavior of
-    #   the Reader.
-    #
-    # @option options [Symbol] :mode Defines how to open the database. It may
-    #   be one of MaxMind::DB::MODE_AUTO, MaxMind::DB::MODE_FILE, or
-    #   MaxMind::DB::MODE_MEMORY. If you don't provide one, the Reader uses
-    #   MaxMind::DB::MODE_AUTO. Refer to the definition of those constants in
-    #   MaxMind::DB for an explanation of their meaning.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database is corrupt or
-    #   invalid.
-    #
-    # @raise [ArgumentError] if the mode is invalid.
-    def initialize(database, locales = ['en'], options = {})
-      @reader = MaxMind::DB.new(database, options)
-      @type = @reader.metadata.database_type
-      locales = ['en'] if locales.empty?
-      @locales = locales
-    end
-
-    # Look up the IP address in the database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::AnonymousIP]
-    #
-    # @raise [ArgumentError] if used against a non-Anonymous IP database or if
-    #   you attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def anonymous_ip(ip_address)
-      flat_model_for(
-        Model::AnonymousIP,
-        'anonymous_ip',
-        'GeoIP2-Anonymous-IP',
-        ip_address,
-      )
-    end
+module MaxMind
+  module GeoIP2
+    # Reader is a reader for the GeoIP2/GeoLite2 database format. IP addresses
+    # can be looked up using the database specific methods.
+    #
+    # == Example
+    #
+    #   require 'maxmind/geoip2'
+    #
+    #   reader = MaxMind::GeoIP2::Reader.new('GeoIP2-Country.mmdb')
+    #
+    #   record = reader.country('1.2.3.4')
+    #   puts record.country.iso_code
+    #
+    #   reader.close
+    class Reader
+      # Create a Reader for looking up IP addresses in a GeoIP2/GeoLite2 database
+      # file.
+      #
+      # If you're performing multiple lookups, it's most efficient to create one
+      # Reader and reuse it.
+      #
+      # Once created, the Reader is safe to use for lookups from multiple
+      # threads. It is safe to use after forking only if you use
+      # MaxMind::DB::MODE_MEMORY or if your version of Ruby supports IO#pread.
+      #
+      # @param database [String] a path to a GeoIP2/GeoLite2 database file.
+      #
+      # @param locales [Array<String>] a list of locale codes to use in the name
+      #   property from most preferred to least preferred.
+      #
+      # @param options [Hash<Symbol, Symbol>] options controlling the behavior of
+      #   the Reader.
+      #
+      # @option options [Symbol] :mode Defines how to open the database. It may
+      #   be one of MaxMind::DB::MODE_AUTO, MaxMind::DB::MODE_FILE, or
+      #   MaxMind::DB::MODE_MEMORY. If you don't provide one, the Reader uses
+      #   MaxMind::DB::MODE_AUTO. Refer to the definition of those constants in
+      #   MaxMind::DB for an explanation of their meaning.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database is corrupt or
+      #   invalid.
+      #
+      # @raise [ArgumentError] if the mode is invalid.
+      def initialize(database, locales = ['en'], options = {})
+        @reader = MaxMind::DB.new(database, options)
+        @type = @reader.metadata.database_type
+        locales = ['en'] if locales.empty?
+        @locales = locales
+      end
 
-    # Look up the IP address in an ASN database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::ASN]
-    #
-    # @raise [ArgumentError] if used against a non-ASN database or if you
-    #   attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def asn(ip_address)
-      flat_model_for(Model::ASN, 'asn', 'GeoLite2-ASN', ip_address)
-    end
+      # Look up the IP address in the database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::AnonymousIP]
+      #
+      # @raise [ArgumentError] if used against a non-Anonymous IP database or if
+      #   you attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def anonymous_ip(ip_address)
+        flat_model_for(
+          Model::AnonymousIP,
+          'anonymous_ip',
+          'GeoIP2-Anonymous-IP',
+          ip_address,
+        )
+      end
 
-    # Look up the IP address in a City database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::City]
-    #
-    # @raise [ArgumentError] if used against a non-City database or if you
-    #   attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def city(ip_address)
-      model_for(Model::City, 'city', 'City', ip_address)
-    end
+      # Look up the IP address in an ASN database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::ASN]
+      #
+      # @raise [ArgumentError] if used against a non-ASN database or if you
+      #   attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def asn(ip_address)
+        flat_model_for(Model::ASN, 'asn', 'GeoLite2-ASN', ip_address)
+      end
 
-    # Look up the IP address in a Connection Type database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::ConnectionType]
-    #
-    # @raise [ArgumentError] if used against a non-Connection Type database or if
-    #   you attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def connection_type(ip_address)
-      flat_model_for(
-        Model::ConnectionType,
-        'connection_type',
-        'GeoIP2-Connection-Type',
-        ip_address,
-      )
-    end
+      # Look up the IP address in a City database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::City]
+      #
+      # @raise [ArgumentError] if used against a non-City database or if you
+      #   attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def city(ip_address)
+        model_for(Model::City, 'city', 'City', ip_address)
+      end
 
-    # Look up the IP address in a Country database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::Country]
-    #
-    # @raise [ArgumentError] if used against a non-Country database or if you
-    #   attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def country(ip_address)
-      model_for(Model::Country, 'country', 'Country', ip_address)
-    end
+      # Look up the IP address in a Connection Type database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::ConnectionType]
+      #
+      # @raise [ArgumentError] if used against a non-Connection Type database or if
+      #   you attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def connection_type(ip_address)
+        flat_model_for(
+          Model::ConnectionType,
+          'connection_type',
+          'GeoIP2-Connection-Type',
+          ip_address,
+        )
+      end
 
-    # Look up the IP address in a Domain database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::Domain]
-    #
-    # @raise [ArgumentError] if used against a non-Domain database or if you
-    #   attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def domain(ip_address)
-      flat_model_for(Model::Domain, 'domain', 'GeoIP2-Domain', ip_address)
-    end
+      # Look up the IP address in a Country database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::Country]
+      #
+      # @raise [ArgumentError] if used against a non-Country database or if you
+      #   attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def country(ip_address)
+        model_for(Model::Country, 'country', 'Country', ip_address)
+      end
 
-    # Look up the IP address in an Enterprise database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::Enterprise]
-    #
-    # @raise [ArgumentError] if used against a non-Enterprise database or if
-    #   you attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def enterprise(ip_address)
-      model_for(Model::Enterprise, 'enterprise', 'Enterprise', ip_address)
-    end
+      # Look up the IP address in a Domain database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::Domain]
+      #
+      # @raise [ArgumentError] if used against a non-Domain database or if you
+      #   attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def domain(ip_address)
+        flat_model_for(Model::Domain, 'domain', 'GeoIP2-Domain', ip_address)
+      end
 
-    # Look up the IP address in an ISP database.
-    #
-    # @param ip_address [String] a string in the standard notation. It may be
-    #   IPv4 or IPv6.
-    #
-    # @return [MaxMind::GeoIP2::Model::ISP]
-    #
-    # @raise [ArgumentError] if used against a non-ISP database or if you
-    #   attempt to look up an IPv6 address in an IPv4 only database.
-    #
-    # @raise [AddressNotFoundError] if the IP address is not found in the
-    #   database.
-    #
-    # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
-    #   corrupt.
-    def isp(ip_address)
-      flat_model_for(Model::ISP, 'isp', 'GeoIP2-ISP', ip_address)
-    end
+      # Look up the IP address in an Enterprise database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::Enterprise]
+      #
+      # @raise [ArgumentError] if used against a non-Enterprise database or if
+      #   you attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def enterprise(ip_address)
+        model_for(Model::Enterprise, 'enterprise', 'Enterprise', ip_address)
+      end
 
-    # Return the metadata associated with the database.
-    #
-    # @return [MaxMind::DB::Metadata]
-    def metadata
-      @reader.metadata
-    end
+      # Look up the IP address in an ISP database.
+      #
+      # @param ip_address [String] a string in the standard notation. It may be
+      #   IPv4 or IPv6.
+      #
+      # @return [MaxMind::GeoIP2::Model::ISP]
+      #
+      # @raise [ArgumentError] if used against a non-ISP database or if you
+      #   attempt to look up an IPv6 address in an IPv4 only database.
+      #
+      # @raise [AddressNotFoundError] if the IP address is not found in the
+      #   database.
+      #
+      # @raise [MaxMind::DB::InvalidDatabaseError] if the database appears
+      #   corrupt.
+      def isp(ip_address)
+        flat_model_for(Model::ISP, 'isp', 'GeoIP2-ISP', ip_address)
+      end
 
-    # Close the Reader and return resources to the system.
-    #
-    # @return [void]
-    def close
-      @reader.close
-    end
+      # Return the metadata associated with the database.
+      #
+      # @return [MaxMind::DB::Metadata]
+      def metadata
+        @reader.metadata
+      end
 
-    private
+      # Close the Reader and return resources to the system.
+      #
+      # @return [void]
+      def close
+        @reader.close
+      end
 
-    def model_for(model_class, method, type, ip_address)
-      record, prefix_length = get_record(method, type, ip_address)
+      private
 
-      record['traits'] = {} if !record.key?('traits')
-      record['traits']['ip_address'] = ip_address
-      record['traits']['prefix_length'] = prefix_length
+      def model_for(model_class, method, type, ip_address)
+        record, prefix_length = get_record(method, type, ip_address)
 
-      model_class.new(record, @locales)
-    end
+        record['traits'] = {} if !record.key?('traits')
+        record['traits']['ip_address'] = ip_address
+        record['traits']['prefix_length'] = prefix_length
 
-    def get_record(method, type, ip_address)
-      if !@type.include?(type)
-        raise ArgumentError,
-              "The #{method} method cannot be used with the #{@type} database."
+        model_class.new(record, @locales)
       end
 
-      record, prefix_length = @reader.get_with_prefix_length(ip_address)
+      def get_record(method, type, ip_address)
+        if !@type.include?(type)
+          raise ArgumentError,
+                "The #{method} method cannot be used with the #{@type} database."
+        end
 
-      if record.nil?
-        raise AddressNotFoundError,
-              "The address #{ip_address} is not in the database."
-      end
+        record, prefix_length = @reader.get_with_prefix_length(ip_address)
 
-      [record, prefix_length]
-    end
+        if record.nil?
+          raise AddressNotFoundError,
+                "The address #{ip_address} is not in the database."
+        end
+
+        [record, prefix_length]
+      end
 
-    def flat_model_for(model_class, method, type, ip_address)
-      record, prefix_length = get_record(method, type, ip_address)
+      def flat_model_for(model_class, method, type, ip_address)
+        record, prefix_length = get_record(method, type, ip_address)
 
-      record['ip_address'] = ip_address
-      record['prefix_length'] = prefix_length
+        record['ip_address'] = ip_address
+        record['prefix_length'] = prefix_length
 
-      model_class.new(record)
+        model_class.new(record)
+      end
     end
   end
 end