maxmind-geoip2 0.0.1

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,16 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/reader'
+
+# rubocop:disable Style/ClassAndModuleChildren
+# :nodoc: all
+module MaxMind
+  module GeoIP2
+    module Record # :nodoc:
+    end
+
+    module Model # :nodoc:
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

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/city.rb

@@ -0,0 +1,60 @@
+# 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 Country for inherited methods.
+  class City < Country
+    # City data for the IP address. See MaxMind::GeoIP2::Record::City.
+    attr_reader :city
+
+    # Location data for the IP address. See MaxMind::GeoIP2::Record::Location.
+    attr_reader :location
+
+    # Postal data for the IP address. See MaxMind::GeoIP2::Record::Postal.
+    attr_reader :postal
+
+    # An array of MaxMind::GeoIP2::Record::Subdivision objects representing 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.
+    attr_reader :subdivisions
+
+    def initialize(record, locales) # :nodoc:
+      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
+
+    # Return an object representing the most specific subdivision returned. If
+    # the response did not contain any subdivisions, this method returns 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/country.rb

@@ -0,0 +1,55 @@
+# 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. See 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. See
+    # 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. See 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. See
+    # MaxMind::GeoIP2::Record::RepresentedCountry.
+    attr_reader :represented_country
+
+    # Data for the traits of the IP address. See
+    # MaxMind::GeoIP2::Record::Traits.
+    attr_reader :traits
+
+    def initialize(record, locales) # :nodoc:
+      @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/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 City for inherited methods.
+  class Enterprise < City
+  end
+end

data/lib/maxmind/geoip2/reader.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'maxmind/db'
+require 'maxmind/geoip2/errors'
+require 'maxmind/geoip2/model/city'
+require 'maxmind/geoip2/model/country'
+require 'maxmind/geoip2/model/enterprise'
+
+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.
+    #
+    # Creating the Reader may raise an exception if initialization fails.
+    #
+    # +database+ is a path to a GeoIP2/GeoLite2 database file.
+    #
+    # +locales+ is a list of locale codes to use in the name property from most
+    # preferred to least preferred.
+    #
+    # +options+ is an option hash where each key is a symbol. The options
+    # control the behavior of the Reader.
+    #
+    # The available options are:
+    #
+    # [+: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.
+    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 and returns a
+    # MaxMind::GeoIP2::Model::City object.
+    #
+    # +ip_address+ is a string in the standard notation. It may be IPv4 or
+    # IPv6.
+    #
+    # === Exceptions
+    #
+    # 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.
+    #
+    # Raises an AddressNotFoundError if +ip_address+ is not found in the
+    # database.
+    #
+    # Raises a 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.
+    #
+    # +ip_address+ is a string in the standard notation. It may be IPv4 or
+    # IPv6.
+    #
+    # === Exceptions
+    #
+    # 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.
+    #
+    # Raises an AddressNotFoundError if +ip_address+ is not found in the
+    # database.
+    #
+    # Raises a 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.
+    #
+    # +ip_address+ is a string in the standard notation. It may be IPv4 or
+    # IPv6.
+    #
+    # === Exceptions
+    #
+    # 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.
+    #
+    # Raises an AddressNotFoundError if +ip_address+ is not found in the
+    # database.
+    #
+    # Raises a 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.
+    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.
+    def close
+      @reader.close
+    end
+
+    private
+
+    def model_for(model_class, 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['traits'] = {} if !record.key?('traits')
+      record['traits']['ip_address'] = ip_address
+      record['traits']['prefix_length'] = prefix_length
+
+      model_class.new(record, @locales)
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MaxMind::GeoIP2::Record
+  class Abstract # :nodoc:
+    def initialize(record)
+      @record = record
+    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/record/city.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind::GeoIP2::Record
+  # City-level data associated with an IP address.
+  #
+  # This record is returned by all location services and databases besides
+  # Country.
+  #
+  # See 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.
+    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.
+    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.
+    def names
+      get('names')
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind::GeoIP2::Record
+  # Contains data for the continent record associated with an IP address.
+  #
+  # This record is returned by all location services and databases.
+  #
+  # See 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.
+    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.
+    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.
+    def names
+      get('names')
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind::GeoIP2::Record
+  # Contains data for the country record associated with an IP address.
+  #
+  # This record is returned by all location services and databases.
+  #
+  # See Place for inherited methods.
+  class Country < Place
+    # A value from 0-100 indicating MaxMind's confidence that the country is
+    # correct. This attribute is only available from the Insights service and
+    # the GeoIP2 Enterprise database. Integer but may be nil.
+    def confidence
+      get('confidence')
+    end
+
+    # The GeoName ID for the country. This attribute is returned by all
+    # location services and databases. Integer but may be nil.
+    def geoname_id
+      get('geoname_id')
+    end
+
+    # This is true if the country is a member state of the European Union. This
+    # attribute is returned by all location services and databases. Boolean.
+    def in_european_union?
+      get('is_in_european_union')
+    end
+
+    # The two-character ISO 3166-1 alpha code for the country. See
+    # https://en.wikipedia.org/wiki/ISO_3166-1. This attribute is returned by
+    # all location services and databases. String but may be nil.
+    def iso_code
+      get('iso_code')
+    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.
+    def names
+      get('names')
+    end
+  end
+end