maxmind-geoip2 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +28 -0
  3. data/Gemfile +12 -0
  4. data/Gemfile.lock +72 -0
  5. data/LICENSE-APACHE +202 -0
  6. data/LICENSE-MIT +17 -0
  7. data/README.dev.md +4 -0
  8. data/README.md +326 -0
  9. data/Rakefile +14 -0
  10. data/lib/maxmind/geoip2.rb +4 -0
  11. data/lib/maxmind/geoip2/client.rb +328 -0
  12. data/lib/maxmind/geoip2/errors.rb +41 -0
  13. data/lib/maxmind/geoip2/model/abstract.rb +31 -0
  14. data/lib/maxmind/geoip2/model/anonymous_ip.rb +67 -0
  15. data/lib/maxmind/geoip2/model/asn.rb +43 -0
  16. data/lib/maxmind/geoip2/model/city.rb +79 -0
  17. data/lib/maxmind/geoip2/model/connection_type.rb +36 -0
  18. data/lib/maxmind/geoip2/model/country.rb +74 -0
  19. data/lib/maxmind/geoip2/model/domain.rb +36 -0
  20. data/lib/maxmind/geoip2/model/enterprise.rb +19 -0
  21. data/lib/maxmind/geoip2/model/insights.rb +18 -0
  22. data/lib/maxmind/geoip2/model/isp.rb +57 -0
  23. data/lib/maxmind/geoip2/reader.rb +279 -0
  24. data/lib/maxmind/geoip2/record/abstract.rb +26 -0
  25. data/lib/maxmind/geoip2/record/city.rb +42 -0
  26. data/lib/maxmind/geoip2/record/continent.rb +41 -0
  27. data/lib/maxmind/geoip2/record/country.rb +58 -0
  28. data/lib/maxmind/geoip2/record/location.rb +77 -0
  29. data/lib/maxmind/geoip2/record/maxmind.rb +21 -0
  30. data/lib/maxmind/geoip2/record/place.rb +32 -0
  31. data/lib/maxmind/geoip2/record/postal.rb +34 -0
  32. data/lib/maxmind/geoip2/record/represented_country.rb +27 -0
  33. data/lib/maxmind/geoip2/record/subdivision.rb +52 -0
  34. data/lib/maxmind/geoip2/record/traits.rb +204 -0
  35. data/maxmind-geoip2.gemspec +26 -0
  36. data/test/test_client.rb +424 -0
  37. data/test/test_model_country.rb +80 -0
  38. data/test/test_model_names.rb +47 -0
  39. data/test/test_reader.rb +459 -0
  40. metadata +130 -0
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'rake/testtask'
4
+ require 'rubocop/rake_task'
5
+
6
+ Rake::TestTask.new do |t|
7
+ t.libs << 'test'
8
+ end
9
+
10
+ RuboCop::RakeTask.new
11
+
12
+ desc 'Run tests and RuboCop'
13
+ task default: :test
14
+ task default: :rubocop
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/client'
4
+ require 'maxmind/geoip2/reader'
@@ -0,0 +1,328 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'connection_pool'
4
+ require 'http'
5
+ require 'json'
6
+ require 'maxmind/geoip2/errors'
7
+ require 'maxmind/geoip2/model/city'
8
+ require 'maxmind/geoip2/model/country'
9
+ require 'maxmind/geoip2/model/insights'
10
+
11
+ module MaxMind
12
+ module GeoIP2
13
+ # This class provides a client API for all the
14
+ # {https://dev.maxmind.com/geoip/geoip2/web-services/ GeoIP2 Precision web
15
+ # services}. The services are Country, City, and Insights. Each service
16
+ # returns a different set of data about an IP address, with Country returning
17
+ # the least data and Insights the most.
18
+ #
19
+ # Each web service is represented by a different model class, and these model
20
+ # classes in turn contain multiple record classes. The record classes have
21
+ # attributes which contain data about the IP address.
22
+ #
23
+ # If the web service does not return a particular piece of data for an IP
24
+ # address, the associated attribute is not populated.
25
+ #
26
+ # The web service may not return any information for an entire record, in
27
+ # which case all of the attributes for that record class will be empty.
28
+ #
29
+ # == Usage
30
+ #
31
+ # The basic API for this class is the same for all of the web service end
32
+ # points. First you create a web service client object with your MaxMind
33
+ # account ID and license key, then you call the method corresponding to a
34
+ # specific end point, passing it the IP address you want to look up.
35
+ #
36
+ # If the request succeeds, the method call will return a model class for the
37
+ # service you called. This model in turn contains multiple record classes,
38
+ # each of which represents part of the data returned by the web service.
39
+ #
40
+ # If the request fails, the client class throws an exception.
41
+ #
42
+ # == Example
43
+ #
44
+ # require 'maxmind/geoip2'
45
+ #
46
+ # client = MaxMind::GeoIP2::Client.new(
47
+ # account_id: 42,
48
+ # license_key: 'abcdef123456',
49
+ # )
50
+ #
51
+ # # Replace 'city' with the method corresponding to the web service you
52
+ # # are using, e.g., 'country', 'insights'.
53
+ # record = client.city('128.101.101.101')
54
+ #
55
+ # puts record.country.iso_code
56
+ class Client
57
+ # rubocop:disable Metrics/ParameterLists
58
+
59
+ # Create a Client that may be used to query a GeoIP2 Precision web service.
60
+ #
61
+ # Once created, the Client is safe to use for lookups from multiple
62
+ # threads.
63
+ #
64
+ # @param account_id [Integer] your MaxMind account ID.
65
+ #
66
+ # @param license_key [String] your MaxMind license key.
67
+ #
68
+ # @param locales [Array<String>] a list of locale codes to use in the name
69
+ # property from most preferred to least preferred.
70
+ #
71
+ # @param host [String] the host to use when querying the web service.
72
+ #
73
+ # @param timeout [Integer] the number of seconds to wait for a request
74
+ # before timing out. If 0, no timeout is set.
75
+ #
76
+ # @param proxy_address [String] proxy address to use, if any.
77
+ #
78
+ # @param proxy_port [Integer] proxy port to use, if any.
79
+ #
80
+ # @param proxy_username [String] proxy username to use, if any.
81
+ #
82
+ # @param proxy_password [String] proxy password to use, if any.
83
+ #
84
+ # @param pool_size [Integer] HTTP connection pool size
85
+ def initialize(
86
+ account_id:,
87
+ license_key:,
88
+ locales: ['en'],
89
+ host: 'geoip.maxmind.com',
90
+ timeout: 0,
91
+ proxy_address: '',
92
+ proxy_port: 0,
93
+ proxy_username: '',
94
+ proxy_password: '',
95
+ pool_size: 5
96
+ )
97
+ @account_id = account_id
98
+ @license_key = license_key
99
+ @locales = locales
100
+ @host = host
101
+ @timeout = timeout
102
+ @proxy_address = proxy_address
103
+ @proxy_port = proxy_port
104
+ @proxy_username = proxy_username
105
+ @proxy_password = proxy_password
106
+ @pool_size = pool_size
107
+
108
+ @connection_pool = ConnectionPool.new(size: @pool_size) do
109
+ make_http_client.persistent("https://#{@host}")
110
+ end
111
+ end
112
+ # rubocop:enable Metrics/ParameterLists
113
+
114
+ # This method calls the GeoIP2 Precision City web service.
115
+ #
116
+ # @param ip_address [String] IPv4 or IPv6 address as a string. If no
117
+ # address is provided, the address that the web service is called from is
118
+ # used.
119
+ #
120
+ # @raise [HTTP::Error] if there was an error performing the HTTP request,
121
+ # such as an error connecting.
122
+ #
123
+ # @raise [JSON::ParserError] if there was invalid JSON in the response.
124
+ #
125
+ # @raise [HTTPError] if there was a problem with the HTTP response, such as
126
+ # an unexpected HTTP status code.
127
+ #
128
+ # @raise [AddressInvalidError] if the web service believes the IP address
129
+ # to be invalid or missing.
130
+ #
131
+ # @raise [AddressNotFoundError] if the IP address was not found.
132
+ #
133
+ # @raise [AddressReservedError] if the IP address is reserved.
134
+ #
135
+ # @raise [AuthenticationError] if there was a problem authenticating to the
136
+ # web service, such as an invalid or missing license key.
137
+ #
138
+ # @raise [InsufficientFundsError] if your account is out of credit.
139
+ #
140
+ # @raise [PermissionRequiredError] if your account does not have permission
141
+ # to use the web service.
142
+ #
143
+ # @raise [InvalidRequestError] if the web service responded with an error
144
+ # and there is no more specific error to raise.
145
+ #
146
+ # @return [MaxMind::GeoIP2::Model::City]
147
+ def city(ip_address = 'me')
148
+ response_for('city', MaxMind::GeoIP2::Model::City, ip_address)
149
+ end
150
+
151
+ # This method calls the GeoIP2 Precision Country web service.
152
+ #
153
+ # @param ip_address [String] IPv4 or IPv6 address as a string. If no
154
+ # address is provided, the address that the web service is called from is
155
+ # used.
156
+ #
157
+ # @raise [HTTP::Error] if there was an error performing the HTTP request,
158
+ # such as an error connecting.
159
+ #
160
+ # @raise [JSON::ParserError] if there was invalid JSON in the response.
161
+ #
162
+ # @raise [HTTPError] if there was a problem with the HTTP response, such as
163
+ # an unexpected HTTP status code.
164
+ #
165
+ # @raise [AddressInvalidError] if the web service believes the IP address
166
+ # to be invalid or missing.
167
+ #
168
+ # @raise [AddressNotFoundError] if the IP address was not found.
169
+ #
170
+ # @raise [AddressReservedError] if the IP address is reserved.
171
+ #
172
+ # @raise [AuthenticationError] if there was a problem authenticating to the
173
+ # web service, such as an invalid or missing license key.
174
+ #
175
+ # @raise [InsufficientFundsError] if your account is out of credit.
176
+ #
177
+ # @raise [PermissionRequiredError] if your account does not have permission
178
+ # to use the web service.
179
+ #
180
+ # @raise [InvalidRequestError] if the web service responded with an error
181
+ # and there is no more specific error to raise.
182
+ #
183
+ # @return [MaxMind::GeoIP2::Model::Country]
184
+ def country(ip_address = 'me')
185
+ response_for('country', MaxMind::GeoIP2::Model::Country, ip_address)
186
+ end
187
+
188
+ # This method calls the GeoIP2 Precision Insights web service.
189
+ #
190
+ # @param ip_address [String] IPv4 or IPv6 address as a string. If no
191
+ # address is provided, the address that the web service is called from is
192
+ # used.
193
+ #
194
+ # @raise [HTTP::Error] if there was an error performing the HTTP request,
195
+ # such as an error connecting.
196
+ #
197
+ # @raise [JSON::ParserError] if there was invalid JSON in the response.
198
+ #
199
+ # @raise [HTTPError] if there was a problem with the HTTP response, such as
200
+ # an unexpected HTTP status code.
201
+ #
202
+ # @raise [AddressInvalidError] if the web service believes the IP address
203
+ # to be invalid or missing.
204
+ #
205
+ # @raise [AddressNotFoundError] if the IP address was not found.
206
+ #
207
+ # @raise [AddressReservedError] if the IP address is reserved.
208
+ #
209
+ # @raise [AuthenticationError] if there was a problem authenticating to the
210
+ # web service, such as an invalid or missing license key.
211
+ #
212
+ # @raise [InsufficientFundsError] if your account is out of credit.
213
+ #
214
+ # @raise [PermissionRequiredError] if your account does not have permission
215
+ # to use the web service.
216
+ #
217
+ # @raise [InvalidRequestError] if the web service responded with an error
218
+ # and there is no more specific error to raise.
219
+ #
220
+ # @return [MaxMind::GeoIP2::Model::Insights]
221
+ def insights(ip_address = 'me')
222
+ response_for('insights', MaxMind::GeoIP2::Model::Insights, ip_address)
223
+ end
224
+
225
+ private
226
+
227
+ def response_for(endpoint, model_class, ip_address)
228
+ record = get(endpoint, ip_address)
229
+
230
+ model_class.new(record, @locales)
231
+ end
232
+
233
+ def make_http_client
234
+ headers = HTTP.basic_auth(user: @account_id, pass: @license_key)
235
+ .headers(
236
+ accept: 'application/json',
237
+ user_agent: 'MaxMind-GeoIP2-ruby',
238
+ )
239
+ timeout = @timeout > 0 ? headers.timeout(@timeout) : headers
240
+
241
+ proxy = timeout
242
+ if @proxy_address != ''
243
+ opts = {}
244
+ opts[:proxy_port] = @proxy_port if @proxy_port != 0
245
+ opts[:proxy_username] = @proxy_username if @proxy_username != ''
246
+ opts[:proxy_password] = @proxy_password if @proxy_password != ''
247
+ proxy = timeout.via(@proxy_address, opts)
248
+ end
249
+
250
+ proxy
251
+ end
252
+
253
+ def get(endpoint, ip_address)
254
+ url = '/geoip/v2.1/' + endpoint + '/' + ip_address
255
+
256
+ response = nil
257
+ body = nil
258
+ @connection_pool.with do |client|
259
+ response = client.get(url)
260
+ body = response.to_s
261
+ end
262
+
263
+ is_json = response.headers[:content_type]&.include?('json')
264
+
265
+ if response.status.client_error?
266
+ return handle_client_error(endpoint, response.code, body, is_json)
267
+ end
268
+
269
+ if response.status.server_error?
270
+ raise HTTPError,
271
+ "Received server error response (#{response.code}) for #{endpoint} with body #{body}"
272
+ end
273
+
274
+ if response.code != 200
275
+ raise HTTPError,
276
+ "Received unexpected response (#{response.code}) for #{endpoint} with body #{body}"
277
+ end
278
+
279
+ handle_success(endpoint, body, is_json)
280
+ end
281
+
282
+ # rubocop:disable Metrics/CyclomaticComplexity
283
+ def handle_client_error(endpoint, status, body, is_json)
284
+ if !is_json
285
+ raise HTTPError,
286
+ "Received client error response (#{status}) for #{endpoint} but it is not JSON: #{body}"
287
+ end
288
+
289
+ error = JSON.parse(body)
290
+
291
+ if !error.key?('code') || !error.key?('error')
292
+ raise HTTPError,
293
+ "Received client error response (#{status}) that is JSON but does not specify code or error keys: #{body}"
294
+ end
295
+
296
+ case error['code']
297
+ when 'IP_ADDRESS_INVALID', 'IP_ADDRESS_REQUIRED'
298
+ raise AddressInvalidError, error['error']
299
+ when 'IP_ADDRESS_NOT_FOUND'
300
+ raise AddressNotFoundError, error['error']
301
+ when 'IP_ADDRESS_RESERVED'
302
+ raise AddressReservedError, error['error']
303
+ when 'ACCOUNT_ID_REQUIRED',
304
+ 'ACCOUNT_ID_UNKNOWN',
305
+ 'AUTHORIZATION_INVALID',
306
+ 'LICENSE_KEY_REQUIRED'
307
+ raise AuthenticationError, error['error']
308
+ when 'INSUFFICIENT_FUNDS'
309
+ raise InsufficientFundsError, error['error']
310
+ when 'PERMISSION_REQUIRED'
311
+ raise PermissionRequiredError, error['error']
312
+ else
313
+ raise InvalidRequestError, error['error']
314
+ end
315
+ end
316
+ # rubocop:enable Metrics/CyclomaticComplexity
317
+
318
+ def handle_success(endpoint, body, is_json)
319
+ if !is_json
320
+ raise HTTPError,
321
+ "Received a success response for #{endpoint} but it is not JSON: #{body}"
322
+ end
323
+
324
+ JSON.parse(body)
325
+ end
326
+ end
327
+ end
328
+ end
@@ -0,0 +1,41 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MaxMind
4
+ module GeoIP2
5
+ # An AddressNotFoundError means the IP address was not found in the
6
+ # database or the web service said the IP address was not found.
7
+ class AddressNotFoundError < RuntimeError
8
+ end
9
+
10
+ # An HTTPError means there was an unexpected HTTP status or response.
11
+ class HTTPError < RuntimeError
12
+ end
13
+
14
+ # An AddressInvalidError means the IP address was invalid.
15
+ class AddressInvalidError < RuntimeError
16
+ end
17
+
18
+ # An AddressReservedError means the IP address is reserved.
19
+ class AddressReservedError < RuntimeError
20
+ end
21
+
22
+ # An AuthenticationError means there was a problem authenticating to the
23
+ # web service.
24
+ class AuthenticationError < RuntimeError
25
+ end
26
+
27
+ # An InsufficientFundsError means the account is out of credits.
28
+ class InsufficientFundsError < RuntimeError
29
+ end
30
+
31
+ # A PermissionRequiredError means the account does not have permission to
32
+ # use the requested service.
33
+ class PermissionRequiredError < RuntimeError
34
+ end
35
+
36
+ # An InvalidRequestError means the web service returned an error and there
37
+ # is no more specific error class.
38
+ class InvalidRequestError < RuntimeError
39
+ end
40
+ end
41
+ end
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'ipaddr'
4
+
5
+ module MaxMind
6
+ module GeoIP2
7
+ module Model
8
+ # @!visibility private
9
+ class Abstract
10
+ def initialize(record)
11
+ @record = record
12
+
13
+ ip = IPAddr.new(record['ip_address']).mask(record['prefix_length'])
14
+ record['network'] = format('%s/%d', ip.to_s, record['prefix_length'])
15
+ end
16
+
17
+ protected
18
+
19
+ def get(key)
20
+ if @record.nil? || !@record.key?(key)
21
+ return false if key.start_with?('is_')
22
+
23
+ return nil
24
+ end
25
+
26
+ @record[key]
27
+ end
28
+ end
29
+ end
30
+ end
31
+ end
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/model/abstract'
4
+
5
+ module MaxMind
6
+ module GeoIP2
7
+ module Model
8
+ # Model class for the Anonymous IP database.
9
+ class AnonymousIP < Abstract
10
+ # This is true if the IP address belongs to any sort of anonymous network.
11
+ #
12
+ # @return [Boolean]
13
+ def anonymous?
14
+ get('is_anonymous')
15
+ end
16
+
17
+ # This is true if the IP address is registered to an anonymous VPN
18
+ # provider. If a VPN provider does not register subnets under names
19
+ # associated with them, we will likely only flag their IP ranges using the
20
+ # hosting_provider? method.
21
+ #
22
+ # @return [Boolean]
23
+ def anonymous_vpn?
24
+ get('is_anonymous_vpn')
25
+ end
26
+
27
+ # This is true if the IP address belongs to a hosting or VPN provider (see
28
+ # description of the anonymous_vpn? method).
29
+ #
30
+ # @return [Boolean]
31
+ def hosting_provider?
32
+ get('is_hosting_provider')
33
+ end
34
+
35
+ # The IP address that the data in the model is for.
36
+ #
37
+ # @return [String]
38
+ def ip_address
39
+ get('ip_address')
40
+ end
41
+
42
+ # The network in CIDR notation associated with the record. In particular,
43
+ # this is the largest network where all of the fields besides ip_address
44
+ # have the same value.
45
+ #
46
+ # @return [String]
47
+ def network
48
+ get('network')
49
+ end
50
+
51
+ # This is true if the IP address belongs to a public proxy.
52
+ #
53
+ # @return [Boolean]
54
+ def public_proxy?
55
+ get('is_public_proxy')
56
+ end
57
+
58
+ # This is true if the IP address is a Tor exit node.
59
+ #
60
+ # @return [Boolean]
61
+ def tor_exit_node?
62
+ get('is_tor_exit_node')
63
+ end
64
+ end
65
+ end
66
+ end
67
+ end