maxmind-geoip2 0.1.0

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+RuboCop::RakeTask.new
+
+desc 'Run tests and RuboCop'
+task default: :test
+task default: :rubocop

data/lib/maxmind/geoip2.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/reader'

data/lib/maxmind/geoip2/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MaxMind::GeoIP2
+  # An AddressNotFoundError means the IP address was not found in the database.
+  class AddressNotFoundError < RuntimeError
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module MaxMind::GeoIP2::Model
+  # @!visibility private
+  class Abstract
+    def initialize(record)
+      @record = record
+
+      ip = IPAddr.new(record['ip_address']).mask(record['prefix_length'])
+      record['network'] = format('%s/%d', ip.to_s, record['prefix_length'])
+    end
+
+    protected
+
+    def get(key)
+      if @record.nil? || !@record.key?(key)
+        return false if key.start_with?('is_')
+
+        return nil
+      end
+
+      @record[key]
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/abstract'
+
+module MaxMind::GeoIP2::Model
+  # Model class for the Anonymous IP database.
+  class AnonymousIP < Abstract
+    # This is true if the IP address belongs to any sort of anonymous network.
+    #
+    # @return [Boolean]
+    def anonymous?
+      get('is_anonymous')
+    end
+
+    # This is true if the IP address is registered to an anonymous VPN
+    # provider. If a VPN provider does not register subnets under names
+    # associated with them, we will likely only flag their IP ranges using the
+    # is_hosting_provider attribute.
+    #
+    # @return [Boolean]
+    def anonymous_vpn?
+      get('is_anonymous_vpn')
+    end
+
+    # This is true if the IP address belongs to a hosting or VPN provider (see
+    # description of the is_anonymous_vpn attribute).
+    #
+    # @return [Boolean]
+    def hosting_provider?
+      get('is_hosting_provider')
+    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
+
+    # This is true if the IP address belongs to a public proxy.
+    #
+    # @return [Boolean]
+    def public_proxy?
+      get('is_public_proxy')
+    end
+
+    # This is true if the IP address is a Tor exit node.
+    #
+    # @return [Boolean]
+    def tor_exit_node?
+      get('is_tor_exit_node')
+    end
+  end
+end

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

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

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

@@ -0,0 +1,75 @@
+# 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::GeoIP2::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

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

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

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/continent'
+require 'maxmind/geoip2/record/country'
+require 'maxmind/geoip2/record/represented_country'
+require 'maxmind/geoip2/record/traits'
+
+module MaxMind::GeoIP2::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
+
+    # 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,
+      )
+      @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

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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
+
+    # 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

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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
+  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

@@ -0,0 +1,277 @@
+# 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::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