maxmind-geoip2 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59a52bbdfb71c9b0ebe0104616db7425e90f166940aa14a04aef3baa60adce7e
-  data.tar.gz: 51a5b6921967659ac3ee2a874b7625065b71102ce8fc5ee05b0ea7b94f34f233
+  metadata.gz: 2825710c836cdc4f085ac2e89f88753aa972124ac307af9669866bb355c61f10
+  data.tar.gz: c420943be58fd25b84afe0a51264333c4ef268259da7946b58cd7ef77dd8a46b
 SHA512:
-  metadata.gz: 3a75b0ac6a4da68a4c79b9a8b3a61d45c458279189edb5dc98a5366c4dbac567d6834528c6060ad3dbb759316614649b0d8d9bdf571516ca5d33d639dbf7f76c
-  data.tar.gz: dfa9fb9b9d1f0a10194ee80b4860cd2b83398fbdc86f042a3e9bcf0c90bd4d7621323524167f19467d46faf94bd790283d5ffdb14d8ba66841615dea4d64c37e
+  metadata.gz: 30d7e6caeaeded96d60fb981bcc2c4ce518620e973f3dae47433cd1582265fa315706a826c1bc62d29dfce013d5cee78ab1fefff54f51ef858589a54075b24f0
+  data.tar.gz: ca89534bc5f0572ad5b69c7c7b92be70089d6e7e600f962d71a38c8c073299d01ed141c6b1b5089cbca9694c6f49b5b8bcb77a45fb1d2ab668cf3f698c40abdb

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.0 (2021-03-23)
+
+* Updated the `MaxMind::GeoIP2::Reader` constructor to support being called
+  using keyword arguments. For example, you may now create a `Reader` using
+  `MaxMind::GeoIP2::Reader.new(database: 'GeoIP2-Country.mmdb')` instead of
+  using positional arguments. This is intended to make it easier to pass in
+  optional arguments. Positional argument calling is still supported.
+* Proxy support was fixed. Pull request by Manoj Dayaram. GitHub #30.
+
+## 0.5.0 (2020-09-25)
+
+* Added the `residential_proxy?` method to
+  `MaxMind::GeoIP2::Model::AnonymousIP` and
+  `MaxMind::GeoIP2::Record::Traits` for use with the Anonymous IP database
+  and GeoIP2 Precision Insights.
+
+## 0.4.0 (2020-03-06)
+
+* HTTP connections are now persistent. There is a new parameter that
+  controls the maximum number of connections the client will use.
+
+## 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
+  Insights.
+
 ## 0.1.0 (2020-02-20)
 
 * Added support for the Anonymous IP, ASN, Connection Type, Domain, and ISP

data/Gemfile

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

data/README.dev.md

@@ -1,4 +1,4 @@
 # How to release
 
 See
-[here](https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/master/README.dev.md).
+[here](https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/main/README.dev.md).

data/README.md

@@ -47,7 +47,9 @@ for more details.
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-City.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-City.mmdb',
+)
 
 record = reader.city('128.101.101.101')
 
@@ -74,7 +76,9 @@ puts record.traits.network # 128.101.101.101/32
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-Country.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-Country.mmdb',
+)
 
 record = reader.country('128.101.101.101')
 
@@ -89,7 +93,9 @@ puts record.country.names['zh-CN'] # '美国'
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-Enterprise.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-Enterprise.mmdb',
+)
 
 record = reader.enterprise('128.101.101.101')
 
@@ -120,7 +126,9 @@ puts record.traits.network # 128.101.101.101/32
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-Anonymous-IP.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-Anonymous-IP.mmdb',
+)
 
 record = reader.anonymous_ip('128.101.101.101')
 
@@ -133,7 +141,9 @@ puts "Anonymous" if record.is_anonymous
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoLite2-ASN.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoLite2-ASN.mmdb',
+)
 
 record = reader.asn('128.101.101.101')
 
@@ -147,7 +157,9 @@ puts record.autonomous_system_organization # Example Ltd
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-Connection-Type.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-Connection-Type.mmdb',
+)
 
 record = reader.connection_type('128.101.101.101')
 
@@ -160,7 +172,9 @@ puts record.connection_type # Cable/DSL
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-Domain.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-Domain.mmdb',
+)
 
 record = reader.domain('128.101.101.101')
 
@@ -173,7 +187,9 @@ puts record.domain # example.com
 require 'maxmind/geoip2'
 
 # This creates the Reader object which should be reused across lookups.
-reader = MaxMind::GeoIP2::Reader.new('/usr/share/GeoIP/GeoIP2-ISP.mmdb')
+reader = MaxMind::GeoIP2::Reader.new(
+  database: '/usr/share/GeoIP/GeoIP2-ISP.mmdb',
+)
 
 record = reader.isp('128.101.101.101')
 
@@ -183,6 +199,64 @@ 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. To use the GeoLite2 web service, you
+may also set the `host` parameter to `geolite.info`. You may 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',
+
+  # To use the GeoLite2 web service instead of GeoIP2 Precision, set
+  # the host parameter to "geolite.info":
+  # host: 'geolite.info',
+)
+
+# Replace "city" with the method corresponding to the web service that
+# you are using, e.g., "country", "insights". Please note that Insights
+# is only supported by GeoIP2 Precision and not the GeoLite2 web service.
+record = client.city('128.101.101.101')
+
+puts record.country.iso_code # 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,333 @@
+# frozen_string_literal: true
+
+require 'connection_pool'
+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
+  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.
+    #
+    # 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. Set
+      #   this to "geolite.info" to use the GeoLite2 web service instead of
+      #   GeoIP2 Precision.
+      #
+      # @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.
+      #
+      # @param pool_size [Integer] HTTP connection pool size
+      def initialize(
+        account_id:,
+        license_key:,
+        locales: ['en'],
+        host: 'geoip.maxmind.com',
+        timeout: 0,
+        proxy_address: '',
+        proxy_port: 0,
+        proxy_username: '',
+        proxy_password: '',
+        pool_size: 5
+      )
+        @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
+        @pool_size = pool_size
+
+        @connection_pool = ConnectionPool.new(size: @pool_size) do
+          make_http_client.persistent("https://#{@host}")
+        end
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # This method calls the 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 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 Insights web service.
+      #
+      # Insights is only supported by the GeoIP2 Precision web service. The
+      # GeoLite2 web service does not support it.
+      #
+      # @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
+
+      def make_http_client
+        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 != ''
+          proxy_params = [@proxy_address]
+          proxy_params << (@proxy_port == 0 ? nil : @proxy_port)
+          proxy_params << (@proxy_username == '' ? nil : @proxy_username)
+          proxy_params << (@proxy_password == '' ? nil : @proxy_password)
+          proxy = timeout.via(*proxy_params)
+        end
+
+        proxy
+      end
+
+      def get(endpoint, ip_address)
+        url = "/geoip/v2.1/#{endpoint}/#{ip_address}"
+
+        response = nil
+        body = nil
+        @connection_pool.with do |client|
+          response = client.get(url)
+          body = response.to_s
+        end
+
+        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: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
+end