maxmind-geoip2 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 59a52bbdfb71c9b0ebe0104616db7425e90f166940aa14a04aef3baa60adce7e
-  data.tar.gz: 51a5b6921967659ac3ee2a874b7625065b71102ce8fc5ee05b0ea7b94f34f233
+SHA1:
+  metadata.gz: 107c7822a5a2de18a3339637547ca8fd8eef5163
+  data.tar.gz: 8d730256e5f036178cf13cbd69ed5be2b86afc10
 SHA512:
-  metadata.gz: 3a75b0ac6a4da68a4c79b9a8b3a61d45c458279189edb5dc98a5366c4dbac567d6834528c6060ad3dbb759316614649b0d8d9bdf571516ca5d33d639dbf7f76c
-  data.tar.gz: dfa9fb9b9d1f0a10194ee80b4860cd2b83398fbdc86f042a3e9bcf0c90bd4d7621323524167f19467d46faf94bd790283d5ffdb14d8ba66841615dea4d64c37e
+  metadata.gz: 1c9dc8f9b3a115494fa9f20c603f772721568a3759b9e2619fde20751ba71a50109d911effeb7d702d286a2011e56d71049ff6a2b854b177f012bbf6bd904291
+  data.tar.gz: a895b54353186ad7fdffec41d9fcf0efa03f093f2dd44a7bbe31e417e13e726a971bb4b88a8a7357c424b16d864061aa563aa150b87160a087d025e852be9a60

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0 (2020-02-26)
+
+* Added support for the GeoIP2 Precision web services: Country, City, and
+  Insights.
+
 ## 0.1.0 (2020-02-20)
 
 * Added support for the Anonymous IP, ASN, Connection Type, Domain, and ISP

data/Gemfile

@@ -2,8 +2,10 @@
 
 source 'https://rubygems.org'
 
+gem 'http'
 gem 'maxmind-db'
 gem 'minitest', group: :development
 gem 'rake', group: :development
 gem 'rubocop', group: :development
 gem 'rubocop-performance', group: :development
+gem 'webmock', group: :development

data/Gemfile.lock

@@ -1,13 +1,35 @@
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    domain_name (0.5.20190701)
+      unf (>= 0.0.5, < 1.0.0)
+    ffi (1.12.2)
+    ffi-compiler (1.0.1)
+      ffi (>= 1.0.0)
+      rake
+    hashdiff (1.0.0)
+    http (4.3.0)
+      addressable (~> 2.3)
+      http-cookie (~> 1.0)
+      http-form_data (~> 2.2)
+      http-parser (~> 1.2.0)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    http-form_data (2.2.0)
+    http-parser (1.2.1)
+      ffi-compiler (>= 1.0, < 2.0)
     jaro_winkler (1.5.4)
     maxmind-db (1.1.0)
     minitest (5.14.0)
     parallel (1.19.1)
     parser (2.7.0.2)
       ast (~> 2.4.0)
+    public_suffix (4.0.3)
     rainbow (3.0.0)
     rake (13.0.1)
     rexml (3.2.4)
@@ -22,17 +44,27 @@ GEM
     rubocop-performance (1.5.2)
       rubocop (>= 0.71.0)
     ruby-progressbar (1.10.1)
+    safe_yaml (1.0.5)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.6)
     unicode-display_width (1.6.1)
+    webmock (3.8.2)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  http
   maxmind-db
   minitest
   rake
   rubocop
   rubocop-performance
+  webmock
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -183,6 +183,58 @@ puts record.isp # University of Minnesota
 puts record.organization # University of Minnesota
 ```
 
+## Web Service Client
+
+### Usage
+
+To use this API, you must create a new `MaxMind::GeoIP2::Client` object
+with your account ID and license key, then you call the method
+corresponding to a specific end point, passing it the IP address you want
+to look up.
+
+If the request succeeds, the method call will return a model class for the end
+point you called. This model in turn contains multiple record classes, each of
+which represents part of the data returned by the web service.
+
+If there is an error, a structured exception is thrown.
+
+See the [API documentation](https://www.rubydoc.info/gems/maxmind-geoip2)
+for more details.
+
+### Example
+
+```ruby
+require 'maxmind/geoip2'
+
+# This creates a Client object that can be reused across requests.
+# Replace "42" with your account ID and "license_key" with your license
+# key.
+client = MaxMind::GeoIP2::Client.new(
+  account_id: 42,
+  license_key: 'license_key',
+)
+
+# Replace "city" with the method corresponding to the web service that
+# you are using, e.g., "country", "insights".
+record = client.city('128.101.101.101')
+
+puts record.country.isoCode # US
+puts record.country.name # United States
+puts record.country.names['zh-CN'] # 美国
+
+puts record.most_specific_subdivision.name # Minnesota
+puts record.most_specific_subdivision.iso_code # MN
+
+puts record.city.name # Minneapolis
+
+puts record.postal.code # 55455
+
+puts record.location.latitude # 44.9733
+puts record.location.longitude # -93.2323
+
+puts record.traits.network # 128.101.101.101/32
+```
+
 ## Values to use for Database or Array Keys
 
 **We strongly discourage you from using a value from any `names` property

data/lib/maxmind/geoip2.rb

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

data/lib/maxmind/geoip2/client.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'http'
+require 'json'
+require 'maxmind/geoip2/errors'
+require 'maxmind/geoip2/model/city'
+require 'maxmind/geoip2/model/country'
+require 'maxmind/geoip2/model/insights'
+
+module MaxMind::GeoIP2
+  # This class provides a client API for all the
+  # {https://dev.maxmind.com/geoip/geoip2/web-services/ GeoIP2 Precision web
+  # services}. The services are Country, City, and Insights. Each service
+  # returns a different set of data about an IP address, with Country returning
+  # the least data and Insights the most.
+  #
+  # Each web service is represented by a different model class, and these model
+  # classes in turn contain multiple record classes. The record classes have
+  # attributes which contain data about the IP address.
+  #
+  # If the web service does not return a particular piece of data for an IP
+  # address, the associated attribute is not populated.
+  #
+  # The web service may not return any information for an entire record, in
+  # which case all of the attributes for that record class will be empty.
+  #
+  # == Usage
+  #
+  # The basic API for this class is the same for all of the web service end
+  # points. First you create a web service client object with your MaxMind
+  # account ID and license key, then you call the method corresponding to a
+  # specific end point, passing it the IP address you want to look up.
+  #
+  # If the request succeeds, the method call will return a model class for the
+  # service you called. This model in turn contains multiple record classes,
+  # each of which represents part of the data returned by the web service.
+  #
+  # If the request fails, the client class throws an exception.
+  #
+  # == Example
+  #
+  #   require 'maxmind/geoip2'
+  #
+  #   client = MaxMind::GeoIP2::Client.new(
+  #     account_id: 42,
+  #     license_key: 'abcdef123456',
+  #   )
+  #
+  #   # Replace 'city' with the method corresponding to the web service you
+  #   # are using, e.g., 'country', 'insights'.
+  #   record = client.city('128.101.101.101')
+  #
+  #   puts record.country.iso_code
+  class Client
+    # rubocop:disable Metrics/ParameterLists
+
+    # Create a Client that may be used to query a GeoIP2 Precision web service.
+    #
+    # Once created, the Client is safe to use for lookups from multiple
+    # threads.
+    #
+    # @param account_id [Integer] your MaxMind account ID.
+    #
+    # @param license_key [String] your MaxMind license key.
+    #
+    # @param locales [Array<String>] a list of locale codes to use in the name
+    #   property from most preferred to least preferred.
+    #
+    # @param host [String] the host to use when querying the web service.
+    #
+    # @param timeout [Integer] the number of seconds to wait for a request
+    #   before timing out. If 0, no timeout is set.
+    #
+    # @param proxy_address [String] proxy address to use, if any.
+    #
+    # @param proxy_port [Integer] proxy port to use, if any.
+    #
+    # @param proxy_username [String] proxy username to use, if any.
+    #
+    # @param proxy_password [String] proxy password to use, if any.
+    def initialize(
+      account_id:,
+      license_key:,
+      locales: ['en'],
+      host: 'geoip.maxmind.com',
+      timeout: 0,
+      proxy_address: '',
+      proxy_port: 0,
+      proxy_username: '',
+      proxy_password: ''
+    )
+      @account_id = account_id
+      @license_key = license_key
+      @locales = locales
+      @host = host
+      @timeout = timeout
+      @proxy_address = proxy_address
+      @proxy_port = proxy_port
+      @proxy_username = proxy_username
+      @proxy_password = proxy_password
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # This method calls the GeoIP2 Precision City web service.
+    #
+    # @param ip_address [String] IPv4 or IPv6 address as a string. If no
+    #   address is provided, the address that the web service is called from is
+    #   used.
+    #
+    # @raise [HTTP::Error] if there was an error performing the HTTP request,
+    #   such as an error connecting.
+    #
+    # @raise [JSON::ParserError] if there was invalid JSON in the response.
+    #
+    # @raise [HTTPError] if there was a problem with the HTTP response, such as
+    #   an unexpected HTTP status code.
+    #
+    # @raise [AddressInvalidError] if the web service believes the IP address
+    #   to be invalid or missing.
+    #
+    # @raise [AddressNotFoundError] if the IP address was not found.
+    #
+    # @raise [AddressReservedError] if the IP address is reserved.
+    #
+    # @raise [AuthenticationError] if there was a problem authenticating to the
+    #   web service, such as an invalid or missing license key.
+    #
+    # @raise [InsufficientFundsError] if your account is out of credit.
+    #
+    # @raise [PermissionRequiredError] if your account does not have permission
+    #   to use the web service.
+    #
+    # @raise [InvalidRequestError] if the web service responded with an error
+    #   and there is no more specific error to raise.
+    #
+    # @return [MaxMind::GeoIP2::Model::City]
+    def city(ip_address = 'me')
+      response_for('city', MaxMind::GeoIP2::Model::City, ip_address)
+    end
+
+    # This method calls the GeoIP2 Precision Country web service.
+    #
+    # @param ip_address [String] IPv4 or IPv6 address as a string. If no
+    #   address is provided, the address that the web service is called from is
+    #   used.
+    #
+    # @raise [HTTP::Error] if there was an error performing the HTTP request,
+    #   such as an error connecting.
+    #
+    # @raise [JSON::ParserError] if there was invalid JSON in the response.
+    #
+    # @raise [HTTPError] if there was a problem with the HTTP response, such as
+    #   an unexpected HTTP status code.
+    #
+    # @raise [AddressInvalidError] if the web service believes the IP address
+    #   to be invalid or missing.
+    #
+    # @raise [AddressNotFoundError] if the IP address was not found.
+    #
+    # @raise [AddressReservedError] if the IP address is reserved.
+    #
+    # @raise [AuthenticationError] if there was a problem authenticating to the
+    #   web service, such as an invalid or missing license key.
+    #
+    # @raise [InsufficientFundsError] if your account is out of credit.
+    #
+    # @raise [PermissionRequiredError] if your account does not have permission
+    #   to use the web service.
+    #
+    # @raise [InvalidRequestError] if the web service responded with an error
+    #   and there is no more specific error to raise.
+    #
+    # @return [MaxMind::GeoIP2::Model::Country]
+    def country(ip_address = 'me')
+      response_for('country', MaxMind::GeoIP2::Model::Country, ip_address)
+    end
+
+    # This method calls the GeoIP2 Precision Insights web service.
+    #
+    # @param ip_address [String] IPv4 or IPv6 address as a string. If no
+    #   address is provided, the address that the web service is called from is
+    #   used.
+    #
+    # @raise [HTTP::Error] if there was an error performing the HTTP request,
+    #   such as an error connecting.
+    #
+    # @raise [JSON::ParserError] if there was invalid JSON in the response.
+    #
+    # @raise [HTTPError] if there was a problem with the HTTP response, such as
+    #   an unexpected HTTP status code.
+    #
+    # @raise [AddressInvalidError] if the web service believes the IP address
+    #   to be invalid or missing.
+    #
+    # @raise [AddressNotFoundError] if the IP address was not found.
+    #
+    # @raise [AddressReservedError] if the IP address is reserved.
+    #
+    # @raise [AuthenticationError] if there was a problem authenticating to the
+    #   web service, such as an invalid or missing license key.
+    #
+    # @raise [InsufficientFundsError] if your account is out of credit.
+    #
+    # @raise [PermissionRequiredError] if your account does not have permission
+    #   to use the web service.
+    #
+    # @raise [InvalidRequestError] if the web service responded with an error
+    #   and there is no more specific error to raise.
+    #
+    # @return [MaxMind::GeoIP2::Model::Insights]
+    def insights(ip_address = 'me')
+      response_for('insights', MaxMind::GeoIP2::Model::Insights, ip_address)
+    end
+
+    private
+
+    def response_for(endpoint, model_class, ip_address)
+      record = get(endpoint, ip_address)
+
+      model_class.new(record, @locales)
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def get(endpoint, ip_address)
+      url = 'https://' + @host + '/geoip/v2.1/' + endpoint + '/' + ip_address
+
+      headers = HTTP.basic_auth(user: @account_id, pass: @license_key)
+                    .headers(
+                      accept: 'application/json',
+                      user_agent: 'MaxMind-GeoIP2-ruby',
+                    )
+      timeout = @timeout > 0 ? headers.timeout(@timeout) : headers
+
+      proxy = timeout
+      if @proxy_address != ''
+        opts = {}
+        opts[:proxy_port] = @proxy_port if @proxy_port != 0
+        opts[:proxy_username] = @proxy_username if @proxy_username != ''
+        opts[:proxy_password] = @proxy_password if @proxy_password != ''
+        proxy = timeout.via(@proxy_address, opts)
+      end
+
+      response = proxy.get(url)
+
+      body = response.to_s
+      is_json = response.headers[:content_type]&.include?('json')
+
+      if response.status.client_error?
+        return handle_client_error(endpoint, response.code, body, is_json)
+      end
+
+      if response.status.server_error?
+        raise HTTPError,
+              "Received server error response (#{response.code}) for #{endpoint} with body #{body}"
+      end
+
+      if response.code != 200
+        raise HTTPError,
+              "Received unexpected response (#{response.code}) for #{endpoint} with body #{body}"
+      end
+
+      handle_success(endpoint, body, is_json)
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def handle_client_error(endpoint, status, body, is_json)
+      if !is_json
+        raise HTTPError,
+              "Received client error response (#{status}) for #{endpoint} but it is not JSON: #{body}"
+      end
+
+      error = JSON.parse(body)
+
+      if !error.key?('code') || !error.key?('error')
+        raise HTTPError,
+              "Received client error response (#{status}) that is JSON but does not specify code or error keys: #{body}"
+      end
+
+      case error['code']
+      when 'IP_ADDRESS_INVALID', 'IP_ADDRESS_REQUIRED'
+        raise AddressInvalidError, error['error']
+      when 'IP_ADDRESS_NOT_FOUND'
+        raise AddressNotFoundError, error['error']
+      when 'IP_ADDRESS_RESERVED'
+        raise AddressReservedError, error['error']
+      when 'ACCOUNT_ID_REQUIRED',
+            'ACCOUNT_ID_UNKNOWN',
+            'AUTHORIZATION_INVALID',
+            'LICENSE_KEY_REQUIRED'
+        raise AuthenticationError, error['error']
+      when 'INSUFFICIENT_FUNDS'
+        raise InsufficientFundsError, error['error']
+      when 'PERMISSION_REQUIRED'
+        raise PermissionRequiredError, error['error']
+      else
+        raise InvalidRequestError, error['error']
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def handle_success(endpoint, body, is_json)
+      if !is_json
+        raise HTTPError,
+              "Received a success response for #{endpoint} but it is not JSON: #{body}"
+      end
+
+      JSON.parse(body)
+    end
+  end
+end