maxmind-geoip2 0.0.1 → 0.1.0

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

@@ -9,7 +9,7 @@ module MaxMind::GeoIP2::Model
   # fields in each record may be populated. See
   # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
   #
-  # See City for inherited methods.
+  # See {MaxMind::GeoIP2::Model::City} for inherited methods.
   class Enterprise < City
   end
 end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+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
+
+    # 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 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 name of the organization associated with the IP address.
+    #
+    # @return [String, nil]
+    def organization
+      get('organization')
+    end
+  end
+end

data/lib/maxmind/geoip2/reader.rb

@@ -2,9 +2,14 @@
 
 require 'maxmind/db'
 require 'maxmind/geoip2/errors'
+require 'maxmind/geoip2/model/anonymous_ip'
+require 'maxmind/geoip2/model/asn'
 require 'maxmind/geoip2/model/city'
+require 'maxmind/geoip2/model/connection_type'
 require 'maxmind/geoip2/model/country'
+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
@@ -31,29 +36,24 @@ module MaxMind::GeoIP2
     # 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.
     #
-    # Creating the Reader may raise an exception if initialization fails.
+    # @param database [String] a path to a GeoIP2/GeoLite2 database file.
     #
-    # +database+ is 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.
     #
-    # +locales+ is 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.
     #
-    # +options+ is an option hash where each key is a symbol. The options
-    # control 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.
     #
-    # The available options are:
+    # @raise [MaxMind::DB::InvalidDatabaseError] if the database is corrupt or
+    #   invalid.
     #
-    # [+: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.
-    #
-    # === Exceptions
-    #
-    # Raises a MaxMind::DB::InvalidDatabaseError if the database is corrupt or
-    # invalid. It can raise other exceptions, such as ArgumentError, if other
-    # errors occur.
+    # @raise [ArgumentError] if the mode is invalid.
     def initialize(database, locales = ['en'], options = {})
       @reader = MaxMind::DB.new(database, options)
       @type = @reader.metadata.database_type
@@ -61,76 +61,178 @@ module MaxMind::GeoIP2
       @locales = locales
     end
 
-    # Look up the +ip_address+ in the database and returns a
-    # MaxMind::GeoIP2::Model::City object.
+    # 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 an ASN database.
+    #
+    # @param ip_address [String] a string in the standard notation. It may be
+    #   IPv4 or IPv6.
+    #
+    # @return [MaxMind::GeoIP2::Model::ASN]
     #
-    # +ip_address+ is a string in the standard notation. It may be IPv4 or
-    # IPv6.
+    # @raise [ArgumentError] if used against a non-ASN database or if you
+    #   attempt to look up an IPv6 address in an IPv4 only database.
     #
-    # === Exceptions
+    # @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 City database.
     #
-    # Raises an ArgumentError if used against a non-City database or if you
-    # attempt to look up an IPv6 address in an IPv4 only database.
+    # @param ip_address [String] a string in the standard notation. It may be
+    #   IPv4 or IPv6.
     #
-    # Raises an AddressNotFoundError if +ip_address+ is not found in the
-    # database.
+    # @return [MaxMind::GeoIP2::Model::City]
     #
-    # Raises a MaxMind::DB::InvalidDatabaseError if the database appears
-    # corrupt.
+    # @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 the database and returns a
-    # MaxMind::GeoIP2::Model::Country object.
+    # 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]
     #
-    # +ip_address+ is a string in the standard notation. It may be IPv4 or
-    # IPv6.
+    # @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.
     #
-    # === Exceptions
+    # @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 Country database.
     #
-    # Raises an ArgumentError if used against a non-Country database or if you
-    # attempt to look up an IPv6 address in an IPv4 only database.
+    # @param ip_address [String] a string in the standard notation. It may be
+    #   IPv4 or IPv6.
     #
-    # Raises an AddressNotFoundError if +ip_address+ is not found in the
-    # database.
+    # @return [MaxMind::GeoIP2::Model::Country]
     #
-    # Raises a MaxMind::DB::InvalidDatabaseError if the database appears
-    # corrupt.
+    # @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 the database and returns a
-    # MaxMind::GeoIP2::Model::Enterprise object.
+    # 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.
     #
-    # +ip_address+ is a string in the standard notation. It may be IPv4 or
-    # IPv6.
+    # @return [MaxMind::GeoIP2::Model::Domain]
     #
-    # === Exceptions
+    # @raise [ArgumentError] if used against a non-Domain database or if you
+    #   attempt to look up an IPv6 address in an IPv4 only database.
     #
-    # Raises an 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 domain(ip_address)
+      flat_model_for(Model::Domain, 'domain', 'GeoIP2-Domain', ip_address)
+    end
+
+    # Look up the IP address in an Enterprise database.
     #
-    # Raises an AddressNotFoundError if +ip_address+ is not found in the
-    # database.
+    # @param ip_address [String] a string in the standard notation. It may be
+    #   IPv4 or IPv6.
     #
-    # Raises a MaxMind::DB::InvalidDatabaseError if the database appears
-    # corrupt.
+    # @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 as a
-    # MaxMind::DB::Metadata object.
+    # 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
+
+    # Return the metadata associated with the database.
+    #
+    # @return [MaxMind::DB::Metadata]
     def metadata
       @reader.metadata
     end
 
     # Close the Reader 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
       @reader.close
     end
@@ -138,6 +240,16 @@ module MaxMind::GeoIP2
     private
 
     def model_for(model_class, method, type, ip_address)
+      record, prefix_length = get_record(method, type, ip_address)
+
+      record['traits'] = {} if !record.key?('traits')
+      record['traits']['ip_address'] = ip_address
+      record['traits']['prefix_length'] = prefix_length
+
+      model_class.new(record, @locales)
+    end
+
+    def get_record(method, type, ip_address)
       if !@type.include?(type)
         raise ArgumentError,
               "The #{method} method cannot be used with the #{@type} database."
@@ -150,11 +262,16 @@ module MaxMind::GeoIP2
               "The address #{ip_address} is not in the database."
       end
 
-      record['traits'] = {} if !record.key?('traits')
-      record['traits']['ip_address'] = ip_address
-      record['traits']['prefix_length'] = prefix_length
+      [record, prefix_length]
+    end
 
-      model_class.new(record, @locales)
+    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
+
+      model_class.new(record)
     end
   end
 end

data/lib/maxmind/geoip2/record/abstract.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module MaxMind::GeoIP2::Record
-  class Abstract # :nodoc:
+  # @!visibility private
+  class Abstract
     def initialize(record)
       @record = record
     end

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

@@ -8,24 +8,29 @@ module MaxMind::GeoIP2::Record
   # This record is returned by all location services and databases besides
   # Country.
   #
-  # See Place for inherited methods.
+  # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
   class City < Place
     # A value from 0-100 indicating MaxMind's confidence that the city is
     # correct. This attribute is only available from the Insights service and
-    # the GeoIP2 Enterprise database. Integer but may be nil.
+    # the GeoIP2 Enterprise database.
+    #
+    # @return [Integer, nil]
     def confidence
       get('confidence')
     end
 
     # The GeoName ID for the city. This attribute is returned by all location
-    # services and databases. Integer but may be nil.
+    # services and databases.
+    #
+    # @return [Integer, nil]
     def geoname_id
       get('geoname_id')
     end
 
-    # A Hash where the keys are locale codes (Strings) and the values are names
-    # (Strings). This attribute is returned by all location services and
-    # databases. Hash but may be nil.
+    # A Hash where the keys are locale codes and the values are names. This
+    # attribute is returned by all location services and databases.
+    #
+    # @return [Hash<String, String>, nil]
     def names
       get('names')
     end

data/lib/maxmind/geoip2/record/continent.rb

@@ -7,24 +7,29 @@ module MaxMind::GeoIP2::Record
   #
   # This record is returned by all location services and databases.
   #
-  # See Place for inherited methods.
+  # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
   class Continent < Place
     # A two character continent code like "NA" (North America) or "OC"
     # (Oceania). This attribute is returned by all location services and
-    # databases. String but may be nil.
+    # databases.
+    #
+    # @return [String, nil]
     def code
       get('code')
     end
 
     # The GeoName ID for the continent. This attribute is returned by all
-    # location services and databases. String but may be nil.
+    # location services and databases.
+    #
+    # @return [String, nil]
     def geoname_id
       get('geoname_id')
     end
 
-    # A Hash where the keys are locale codes (Strings) and the values are names
-    # (Strings). This attribute is returned by all location services and
-    # databases. Hash but may be nil.
+    # A Hash where the keys are locale codes and the values are names. This
+    # attribute is returned by all location services and databases.
+    #
+    # @return [Hash<String, String>, nil]
     def names
       get('names')
     end