maxmind-geoip2 0.4.0

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the GeoLite2 ASN database.
+      class ASN < 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 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/city.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/country'
+require 'maxmind/geoip2/record/city'
+require 'maxmind/geoip2/record/location'
+require 'maxmind/geoip2/record/postal'
+require 'maxmind/geoip2/record/subdivision'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 City web service and
+      # database. It is also used for GeoLite2 City 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::Country} for inherited methods.
+      class City < Country
+        # City data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::City]
+        attr_reader :city
+
+        # Location data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Location]
+        attr_reader :location
+
+        # Postal data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Postal]
+        attr_reader :postal
+
+        # The country subdivisions for the IP address.
+        #
+        # The number and type of subdivisions varies by country, but a subdivision
+        # is typically a state, province, country, etc. Subdivisions are ordered
+        # from most general (largest) to most specific (smallest).
+        #
+        # If the response did not contain any subdivisions, this attribute will be
+        # an empty array.
+        #
+        # @return [Array<MaxMind::GeoIP2::Record::Subdivision>]
+        attr_reader :subdivisions
+
+        # @!visibility private
+        def initialize(record, locales)
+          super(record, locales)
+          @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
+
+        # The most specific subdivision returned.
+        #
+        # If the response did not contain any subdivisions, this method returns
+        # nil.
+        #
+        # @return [MaxMind::GeoIP2::Record::Subdivision, nil]
+        def most_specific_subdivision
+          @subdivisions.last
+        end
+
+        private
+
+        def create_subdivisions(subdivisions, locales)
+          return [] if subdivisions.nil?
+
+          subdivisions.map do |s|
+            MaxMind::GeoIP2::Record::Subdivision.new(s, locales)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the GeoIP2 Connection Type database.
+      class ConnectionType < Abstract
+        # The connection type may take the following values: "Dialup", "Cable/DSL",
+        # "Corporate", "Cellular". Additional values may be added in the future.
+        #
+        # @return [String, nil]
+        def connection_type
+          get('connection_type')
+        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')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/continent'
+require 'maxmind/geoip2/record/country'
+require 'maxmind/geoip2/record/maxmind'
+require 'maxmind/geoip2/record/represented_country'
+require 'maxmind/geoip2/record/traits'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 Country web service and
+      # database. It is also used for GeoLite2 Country lookups.
+      class Country
+        # Continent data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Continent]
+        attr_reader :continent
+
+        # Country data for the IP address. This object represents the country where
+        # MaxMind believes the end user is located.
+        #
+        # @return [MaxMind::GeoIP2::Record::Country]
+        attr_reader :country
+
+        # Data related to your MaxMind account.
+        #
+        # @return [MaxMind::GeoIP2::Record::MaxMind]
+        attr_reader :maxmind
+
+        # Registered country data for the IP address. This record represents the
+        # country where the ISP has registered a given IP block and may differ from
+        # the user's country.
+        #
+        # @return [MaxMind::GeoIP2::Record::Country]
+        attr_reader :registered_country
+
+        # Represented country data for the IP address. The represented country is
+        # used for things like military bases. It is only present when the
+        # represented country differs from the country.
+        #
+        # @return [MaxMind::GeoIP2::Record::RepresentedCountry]
+        attr_reader :represented_country
+
+        # Data for the traits of the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Traits]
+        attr_reader :traits
+
+        # @!visibility private
+        def initialize(record, locales)
+          @continent = MaxMind::GeoIP2::Record::Continent.new(
+            record['continent'],
+            locales,
+          )
+          @country = MaxMind::GeoIP2::Record::Country.new(
+            record['country'],
+            locales,
+          )
+          @maxmind = MaxMind::GeoIP2::Record::MaxMind.new(record['maxmind'])
+          @registered_country = MaxMind::GeoIP2::Record::Country.new(
+            record['registered_country'],
+            locales,
+          )
+          @represented_country = MaxMind::GeoIP2::Record::RepresentedCountry.new(
+            record['represented_country'],
+            locales,
+          )
+          @traits = MaxMind::GeoIP2::Record::Traits.new(record['traits'])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/abstract'
+
+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 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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/abstract'
+
+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 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
+  end
+end

data/lib/maxmind/geoip2/reader.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+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
+  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 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]
+      #
+      # @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 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 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 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 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 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 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.
+      #
+      # @return [void]
+      def close
+        @reader.close
+      end
+
+      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."
+        end
+
+        record, prefix_length = @reader.get_with_prefix_length(ip_address)
+
+        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)
+
+        record['ip_address'] = ip_address
+        record['prefix_length'] = prefix_length
+
+        model_class.new(record)
+      end
+    end
+  end
+end