maxmind-geoip2 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 107c7822a5a2de18a3339637547ca8fd8eef5163
-  data.tar.gz: 8d730256e5f036178cf13cbd69ed5be2b86afc10
+SHA256:
+  metadata.gz: 42699226c0ab8ec1152f4c56929c830916d7c226097082ae95959199d8796aa8
+  data.tar.gz: 97d399a1c58fb932171cfb4aa5c6b19cfb64af382771e2cdfc693e72bba2abd1
 SHA512:
-  metadata.gz: 1c9dc8f9b3a115494fa9f20c603f772721568a3759b9e2619fde20751ba71a50109d911effeb7d702d286a2011e56d71049ff6a2b854b177f012bbf6bd904291
-  data.tar.gz: a895b54353186ad7fdffec41d9fcf0efa03f093f2dd44a7bbe31e417e13e726a971bb4b88a8a7357c424b16d864061aa563aa150b87160a087d025e852be9a60
+  metadata.gz: cd7fac3bc1738b562586e23722eb62919a3d157a32619511ca2246b0b23c91eabcf9a3565e9f33ff080680bdb9e42a6cfaf984689de9231e8cc2b4edab5b5fa9
+  data.tar.gz: 05ce00df88e5de2ecfc7fceacc868fdf5d0b371091d7da5aae63089f9699c72195aaf70175fcdd8e16c3af4d251cd2cf8b78f06e462c2936ea66cc82a4ed622d

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 (2020-03-04)
+
+* Modules are now always be defined. Previously we used a shorthand syntax
+  which meant including individual classes could leave module constants
+  undefined.
+
 ## 0.2.0 (2020-02-26)
 
 * Added support for the GeoIP2 Precision web services: Country, City, and

data/Gemfile.lock

@@ -12,7 +12,7 @@ GEM
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
-    hashdiff (1.0.0)
+    hashdiff (1.0.1)
     http (4.3.0)
       addressable (~> 2.3)
       http-cookie (~> 1.0)
@@ -27,13 +27,13 @@ GEM
     maxmind-db (1.1.0)
     minitest (5.14.0)
     parallel (1.19.1)
-    parser (2.7.0.2)
+    parser (2.7.0.4)
       ast (~> 2.4.0)
     public_suffix (4.0.3)
     rainbow (3.0.0)
     rake (13.0.1)
     rexml (3.2.4)
-    rubocop (0.80.0)
+    rubocop (0.80.1)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.7.0.1)

data/lib/maxmind/geoip2/client.rb

@@ -7,307 +7,309 @@ 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.
+module MaxMind
+  module 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.
     #
-    # @param locales [Array<String>] a list of locale codes to use in the name
-    #   property from most preferred to least preferred.
+    # 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.
     #
-    # @param host [String] the host to use when querying the web service.
+    # If the web service does not return a particular piece of data for an IP
+    # address, the associated attribute is not populated.
     #
-    # @param timeout [Integer] the number of seconds to wait for a request
-    #   before timing out. If 0, no timeout is set.
+    # 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.
     #
-    # @param proxy_address [String] proxy address to use, if any.
+    # == Usage
     #
-    # @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.
+    # 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.
     #
-    # @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.
+    # 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.
     #
-    # @raise [HTTP::Error] if there was an error performing the HTTP request,
-    #   such as an error connecting.
+    # If the request fails, the client class throws an exception.
     #
-    # @raise [JSON::ParserError] if there was invalid JSON in the response.
+    # == Example
     #
-    # @raise [HTTPError] if there was a problem with the HTTP response, such as
-    #   an unexpected HTTP status code.
+    #   require 'maxmind/geoip2'
     #
-    # @raise [AddressInvalidError] if the web service believes the IP address
-    #   to be invalid or missing.
+    #   client = MaxMind::GeoIP2::Client.new(
+    #     account_id: 42,
+    #     license_key: 'abcdef123456',
+    #   )
     #
-    # @raise [AddressNotFoundError] if the IP address was not found.
+    #   # Replace 'city' with the method corresponding to the web service you
+    #   # are using, e.g., 'country', 'insights'.
+    #   record = client.city('128.101.101.101')
     #
-    # @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
+    #   puts record.country.iso_code
+    class Client
+      # rubocop:disable Metrics/ParameterLists
 
-    # 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
+      # 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
 
-    private
+      # 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
 
-    def response_for(endpoint, model_class, ip_address)
-      record = get(endpoint, ip_address)
+      # 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
 
-      model_class.new(record, @locales)
-    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
 
-    # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/PerceivedComplexity
-    def get(endpoint, ip_address)
-      url = 'https://' + @host + '/geoip/v2.1/' + endpoint + '/' + ip_address
+      private
 
-      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
+      def response_for(endpoint, model_class, ip_address)
+        record = get(endpoint, ip_address)
 
-      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)
+        model_class.new(record, @locales)
       end
 
-      response = proxy.get(url)
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      def get(endpoint, ip_address)
+        url = 'https://' + @host + '/geoip/v2.1/' + endpoint + '/' + ip_address
 
-      body = response.to_s
-      is_json = response.headers[:content_type]&.include?('json')
+        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
 
-      if response.status.client_error?
-        return handle_client_error(endpoint, response.code, body, is_json)
-      end
+        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
 
-      if response.status.server_error?
-        raise HTTPError,
-              "Received server error response (#{response.code}) for #{endpoint} with body #{body}"
-      end
+        response = proxy.get(url)
 
-      if response.code != 200
-        raise HTTPError,
-              "Received unexpected response (#{response.code}) for #{endpoint} with body #{body}"
-      end
+        body = response.to_s
+        is_json = response.headers[:content_type]&.include?('json')
 
-      handle_success(endpoint, body, is_json)
-    end
-    # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/PerceivedComplexity
+        if response.status.client_error?
+          return handle_client_error(endpoint, response.code, body, is_json)
+        end
 
-    # 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
+        if response.status.server_error?
+          raise HTTPError,
+                "Received server error response (#{response.code}) for #{endpoint} with body #{body}"
+        end
 
-      error = JSON.parse(body)
+        if response.code != 200
+          raise HTTPError,
+                "Received unexpected response (#{response.code}) for #{endpoint} with body #{body}"
+        end
 
-      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}"
+        handle_success(endpoint, body, is_json)
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
 
-      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
+      # 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)
 
-    def handle_success(endpoint, body, is_json)
-      if !is_json
-        raise HTTPError,
-              "Received a success response for #{endpoint} but it is not JSON: #{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)
+        JSON.parse(body)
+      end
     end
   end
 end