zerobounce-sdk 3.0.0 → 3.1.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.
@@ -1,19 +1,45 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require 'json'
4
+ require 'stringio'
4
5
  require 'zerobounce/api_urls'
5
6
  require 'zerobounce/response_error'
6
7
  require 'zerobounce/api_key'
8
+ require 'zerobounce/strict_json'
7
9
  require 'zerobounce/error'
10
+ require 'zerobounce/response_shape'
8
11
 
9
- # https://github.com/rest-client/rest-client
10
- require 'rest-client'
11
-
12
+ require 'zerobounce/http_transport'
12
13
 
13
14
  module Zerobounce
14
15
 
15
16
  # Sends the HTTP request.
16
17
  class BaseRequest
18
+ # A file part the SDK builds from the caller's IO or String (the
19
+ # *_send_stream methods). It is content, not a path, so the check that
20
+ # keeps caller-supplied paths under the current directory does not apply
21
+ # to it, and nothing is written to disk. It is sent as a file part named
22
+ # +original_filename+.
23
+ class Upload
24
+ attr_reader :original_filename
25
+
26
+ def initialize(content, file_name)
27
+ @io = StringIO.new(content.to_s.b)
28
+ @original_filename = File.basename(file_name.to_s)
29
+ end
30
+
31
+ def content
32
+ @io.string
33
+ end
34
+
35
+ def content_type
36
+ 'text/csv'
37
+ end
38
+
39
+ def close
40
+ @io.close
41
+ end
42
+ end
17
43
 
18
44
  protected
19
45
 
@@ -46,25 +72,15 @@ module Zerobounce
46
72
  end
47
73
 
48
74
  def self.__require_https__(url)
49
- unless url.to_s.downcase.start_with?('https://')
50
- raise ArgumentError, 'API URL must be an https:// URL'
51
- end
52
- url
75
+ ApiUrls.check!(url, 'API URL')
53
76
  end
54
77
 
55
78
  # Removes the API key from error text. The key the request actually used
56
79
  # (a Zerobounce::Client's or with_api_key's, which is thread-local) is
57
- # redacted as well as the global one, in its raw and URL-encoded forms.
80
+ # redacted as well as the global one, in its raw, URL-encoded and
81
+ # JSON-escaped forms.
58
82
  def self.__redact_api_key__(message)
59
- text = message.to_s
60
- [current_api_key, Zerobounce.config.apikey].uniq.each do |key|
61
- next if key.nil? || key.to_s.strip.empty?
62
-
63
- [key.to_s, URI.encode_www_form_component(key.to_s)].uniq.each do |form|
64
- text = text.gsub(form, '***')
65
- end
66
- end
67
- text
83
+ ApiKey.redact(message, [current_api_key, Zerobounce.config.apikey].uniq)
68
84
  end
69
85
 
70
86
  def self.current_api_key
@@ -84,37 +100,57 @@ module Zerobounce
84
100
  end
85
101
 
86
102
  # The message for an HTTP error status.
87
- def self.__http_error_message__(error)
88
- code = error.http_code.to_i
89
- # max_redirects is 0, so a 3xx is never followed; say so rather than
90
- # reporting its (usually empty) body as an "Empty response".
103
+ def self.__http_error_message__(response)
104
+ code = response.code.to_i
105
+ # Redirects are never followed; say so rather than reporting the (usually
106
+ # empty) body as an "Empty response".
91
107
  if code.between?(300, 399)
92
108
  return "ZeroBounce answered with a redirect (HTTP #{code}), which is not followed"
93
109
  end
94
110
 
95
- ResponseError.message_from(error.response)
111
+ ResponseError.message_from(response)
96
112
  end
97
113
 
98
- def self.__execute_request__(**kwargs)
99
- kwargs[:max_redirects] = 0
114
+ # The content of a stream the caller passed to a *_send_stream method.
115
+ # A read that fails is the SDK's error, and nothing is sent.
116
+ def self.read_stream(io)
117
+ return io.to_s unless io.respond_to?(:read)
118
+
119
+ io.read.to_s
120
+ rescue StandardError => e
121
+ raise ApiResponseError.new(
122
+ __redact_api_key__("Could not read the upload stream (#{e.class}): #{e.message}"), 0
123
+ ), cause: nil
124
+ end
125
+
126
+ # Sends one request. An HTTP error status (4xx, 5xx, and a 3xx, which is
127
+ # never followed) raises ApiResponseError with that status; a transport
128
+ # failure raises it with status 0. Messages are redacted of the API key.
129
+ def self.__execute_request__(method:, url:, query: nil, headers: {}, body: nil)
130
+ # Re-checked on every send, whichever entry point built the URL; outside
131
+ # the rescue below, so it is the caller's ArgumentError.
132
+ __require_https__(url)
133
+ __send_checked__(method: method, url: url, query: query, headers: headers, body: body)
134
+ end
135
+
136
+ def self.__send_checked__(method:, url:, query:, headers:, body:)
100
137
  user_agent = Zerobounce.config.headers && Zerobounce.config.headers[:user_agent]
101
- kwargs[:headers] = (kwargs[:headers] || {}).merge(user_agent: user_agent) if user_agent
102
- RestClient::Request.execute(**kwargs)
103
- rescue RestClient::ExceptionWithResponse => e
104
- # Re-raised as the same RestClient class (RestClient::NotFound and so
105
- # on), so `rescue RestClient::...` and #http_code keep working as they
106
- # did up to 2.1.8. Only the message changes: the API's short error text,
107
- # with the key redacted.
108
- e.message = __redact_api_key__(__http_error_message__(e))
109
- raise e
110
- rescue RestClient::Exception => e
111
- e.message = __redact_api_key__(e.message)
112
- raise e
138
+ headers = headers.merge(user_agent: user_agent) if user_agent
139
+ response = HttpTransport.execute(
140
+ method: method, url: url, query: query, headers: headers, body: body,
141
+ redact: ->(text) { __redact_api_key__(text) }
142
+ )
143
+ if response.code >= 300
144
+ raise ApiResponseError.new(__redact_api_key__(__http_error_message__(response)), response.code), cause: nil
145
+ end
146
+
147
+ response
148
+ rescue ApiResponseError
149
+ raise
113
150
  rescue StandardError => e
114
- # Same class and backtrace, redacted message. cause: nil, because the
115
- # original (unredacted) error would otherwise ride along as #cause and
116
- # be printed by #full_message.
117
- raise e.exception(__redact_api_key__(e.message)), cause: nil
151
+ # cause: nil, because the original (unredacted) error would otherwise
152
+ # ride along as #cause and be printed by #full_message.
153
+ raise HttpTransport.failure(e, ->(text) { __redact_api_key__(text) }), cause: nil
118
154
  end
119
155
 
120
156
  def self._get(root, path, params, content_type='application/json')
@@ -128,10 +164,30 @@ module Zerobounce
128
164
  url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
129
165
  Zerobounce::BaseRequest.__require_https__(url)
130
166
 
131
- response = __execute_request__(method: :get, url: url, timeout: 120, headers: { params: params })
167
+ response = __execute_request__(method: :get, url: url, query: params)
132
168
  return response
133
169
  end
134
170
 
171
+ # The file part of a multipart upload: the content is read up front, so a
172
+ # file that cannot be read is an error before anything is sent.
173
+ def self.__file_part__(filepath)
174
+ if filepath.is_a?(Upload)
175
+ return { name: 'file', filename: filepath.original_filename, content: filepath.content,
176
+ content_type: filepath.content_type }
177
+ end
178
+
179
+ path = __safe_file_path__(filepath)
180
+ begin
181
+ content = File.binread(path)
182
+ rescue SystemCallError, IOError => e
183
+ raise ApiResponseError.new(
184
+ __redact_api_key__("Could not read the upload file (#{e.class}): #{e.message}"), 0
185
+ ), cause: nil
186
+ end
187
+ type = File.extname(path).casecmp('.csv').zero? ? 'text/csv' : 'application/octet-stream'
188
+ { name: 'file', filename: File.basename(path), content: content, content_type: type }
189
+ end
190
+
135
191
  def self._post(root, path, params, content_type='application/json', filepath=nil)
136
192
 
137
193
  api_key = __checked_api_key__
@@ -145,20 +201,21 @@ module Zerobounce
145
201
  params.each do |key, value|
146
202
  params[key] = value ? 'true' : 'false' if value == true || value == false
147
203
  end
148
- params[:file] = File.new(Zerobounce::BaseRequest.__safe_file_path__(filepath), 'rb')
149
- params[:multipart] = true
150
- response = __execute_request__(method: :post, url: url, payload: params, timeout: 120)
204
+ file = __file_part__(filepath)
205
+ multipart_type, body = HttpTransport.multipart(params, file)
206
+ response = __execute_request__(method: :post, url: url, body: body,
207
+ headers: { content_type: multipart_type })
151
208
 
152
209
  elsif content_type == 'application/json'
153
210
  response = __execute_request__(
154
211
  method: :post,
155
212
  url: url,
156
- payload: params.to_json,
157
- timeout: 120,
158
- headers: { content_type: :json, accept: :json }
213
+ body: params.to_json,
214
+ headers: { content_type: 'application/json', accept: 'application/json' }
159
215
  )
160
216
  elsif content_type == 'application/x-www-form-urlencoded'
161
- response = __execute_request__(method: :post, url: url, payload: params, timeout: 120)
217
+ response = __execute_request__(method: :post, url: url, body: HttpTransport.encode_query(params),
218
+ headers: { content_type: 'application/x-www-form-urlencoded' })
162
219
  else
163
220
  # this shouldn't happen
164
221
  raise Error.new('Unknown content type specified in request.'\
@@ -187,15 +244,13 @@ module Zerobounce
187
244
  end
188
245
  Zerobounce::BaseRequest.__require_https__(url)
189
246
 
190
- options = { method: method, url: url, timeout: 120 }
247
+ options = { method: method, url: url, query: params, headers: extra }
191
248
  if form
192
- options[:payload] = form
193
- options[:headers] = extra.merge(params: params, content_type: 'application/x-www-form-urlencoded')
249
+ options[:body] = HttpTransport.encode_query(form)
250
+ options[:headers] = extra.merge(content_type: 'application/x-www-form-urlencoded')
194
251
  elsif json
195
- options[:payload] = json.to_json
196
- options[:headers] = extra.merge(params: params, content_type: :json, accept: :json)
197
- else
198
- options[:headers] = extra.merge(params: params)
252
+ options[:body] = json.to_json
253
+ options[:headers] = extra.merge(content_type: 'application/json', accept: 'application/json')
199
254
  end
200
255
 
201
256
  __execute_request__(**options)
@@ -205,7 +260,7 @@ module Zerobounce
205
260
  # evaluator, which has its own host.
206
261
  def self.root_request(method, root, path, params, form: nil)
207
262
  url = "#{__root_without_trailing_slashes__(root)}/#{path.to_s.sub(%r{\A/}, '')}"
208
- __parse_json_response__(__execute_with_method__(method, url, params, form: form))
263
+ __parse_json_response__(__execute_with_method__(method, url, params, form: form), nil, strict: false)
209
264
  end
210
265
 
211
266
  # One Inbox Placement Tester call.
@@ -215,9 +270,12 @@ module Zerobounce
215
270
  # LIVE: the Inbox Placement Tester authenticates with a Bearer header.
216
271
  # Sent as an api_key parameter the request is rejected as unauthorized.
217
272
  response = __execute_with_method__(method, url, params, json: json, bearer: true)
218
- return nil if response.body.to_s.strip.empty?
273
+ # Only a DELETE may answer with nothing (zero bytes) and succeed. On
274
+ # every other call an empty body is an "Empty response" error, with the
275
+ # HTTP status, from the parse below.
276
+ return nil if method == :delete && response.body.to_s.empty?
219
277
 
220
- __parse_json_response__(response)
278
+ __parse_json_response__(response, nil, strict: false)
221
279
  end
222
280
 
223
281
  # Whether a Content-Type names a JSON body.
@@ -242,17 +300,18 @@ module Zerobounce
242
300
  configured = Zerobounce.configuration.bulk_root_url.to_s.strip
243
301
  return __root_without_trailing_slashes__(configured) unless configured.empty?
244
302
 
245
- derived = Zerobounce.configuration.bulk_api_root_url.to_s.sub(%r{/v2/?$}, '')
303
+ # Trailing slashes first, so ".../v2//" loses its /v2 as well.
304
+ derived = __root_without_trailing_slashes__(Zerobounce.configuration.bulk_api_root_url).delete_suffix('/v2')
246
305
  derived = ApiUrls::BULK_ROOT_URL if derived.strip.empty?
247
306
  __root_without_trailing_slashes__(derived)
248
307
  end
249
308
 
250
- # Whether a "success" field means failure. The API sends it as a JSON
251
- # false, "false" or "False" depending on the endpoint.
309
+ # Whether a "success" field means failure: every value the strict boolean
310
+ # reads as false (false, 0, "false", "False", "0", whitespace ignored).
252
311
  def self.__success_means_failure__(value)
253
- return !value if value == true || value == false
312
+ return true if value == false || (value.is_a?(Integer) && value.zero?)
254
313
 
255
- value.is_a?(String) && value.strip.casecmp('false').zero?
314
+ value.is_a?(String) && %w[false 0].include?(value.strip.downcase)
256
315
  end
257
316
 
258
317
  # LIVE: {"success": false} on an HTTP 200 is a failure, not a result. The
@@ -267,11 +326,6 @@ module Zerobounce
267
326
  )
268
327
  end
269
328
 
270
- # A value that reads as an error: a non-blank String.
271
- def self.__error_text__(value)
272
- value.is_a?(String) && !value.strip.empty?
273
- end
274
-
275
329
  # An "error" value that means failure: anything but nil or a blank String.
276
330
  def self.__error_value__(value)
277
331
  !value.nil? && !(value.is_a?(String) && value.strip.empty?)
@@ -280,14 +334,37 @@ module Zerobounce
280
334
  # The keys a message-only body is made of.
281
335
  MESSAGE_KEYS = %w[error message error_message Message Error detail].freeze
282
336
 
283
- # A body made only of message keys (no "success"), for the calls whose
284
- # result is never a bare message.
285
- def self.__raise_if_message_only__(response, parsed)
286
- return if parsed.empty? || parsed.key?('success')
287
- return unless parsed.keys.all? { |key| MESSAGE_KEYS.include?(key) }
337
+ # The paths whose answer may be a bare message or an empty object: the
338
+ # filters calls, whose documented success is {"Message": "Filter has been
339
+ # added."}.
340
+ RAW_JSON_PATHS = %w[filters/add filters/list filters/delete].freeze
341
+
342
+ # A typed call never answers with an empty object or a body made only of
343
+ # message keys (no "success"): either is how the API reports a rejected
344
+ # request, so it is an error with the HTTP status. The exceptions are
345
+ # validate's greylist answer {"Message": "..."} (a result), the raw-JSON
346
+ # filters calls, and the list evaluator and Inbox Placement Tester calls
347
+ # (which never reach this check).
348
+ def self.__raise_if_untyped_answer__(response, parsed, path)
349
+ return if RAW_JSON_PATHS.include?(path)
350
+
351
+ if parsed.empty?
352
+ raise ApiResponseError.new('ZeroBounce returned JSON of an unexpected shape: an empty object.',
353
+ response.code)
354
+ end
355
+ return if parsed.key?('success') || !parsed.keys.all? { |key| MESSAGE_KEYS.include?(key) }
356
+ return if path == 'validate' && ResponseError.text_of(parsed['Message'])
357
+
358
+ text = MESSAGE_KEYS.filter_map { |key| __message_text__(parsed[key]) }.first
359
+ if text.nil? && MESSAGE_KEYS.any? { |key| ResponseError.non_text?(parsed[key]) }
360
+ text = ResponseError::NO_MESSAGE_TEXT
361
+ end
362
+ raise ApiResponseError.new(ResponseError.strip_prefix(text || 'Request failed'), response.code)
363
+ end
288
364
 
289
- text = MESSAGE_KEYS.map { |key| parsed[key] }.find { |value| __error_text__(value) }
290
- raise ApiResponseError.new(ResponseError.strip_prefix(text), response.code) if text
365
+ # The text of a message value: a non-blank String, or the non-blank Strings of an Array joined with "\n".
366
+ def self.__message_text__(value)
367
+ ResponseError.text_of(value)
291
368
  end
292
369
 
293
370
  # A dead or invalid key on an HTTP 200: no "success" field and a non-empty
@@ -296,13 +373,15 @@ module Zerobounce
296
373
  return if parsed.key?('success')
297
374
 
298
375
  %w[Error error_message].each do |key|
299
- next unless __error_text__(parsed[key])
376
+ next unless __message_text__(parsed[key])
300
377
 
301
378
  raise ApiResponseError.new(ResponseError.strip_prefix(parsed[key]), response.code)
302
379
  end
303
380
  end
304
381
 
305
- def self.__parse_json_response__(response)
382
+ # The parsed JSON body. An HTML page, an empty body or one that is not
383
+ # valid JSON raises ApiResponseError with the HTTP status.
384
+ def self.__parse_json_body__(response)
306
385
  body = response.body.to_s
307
386
  content_type = (response.headers[:content_type] || '').to_s
308
387
  code = response.code
@@ -310,11 +389,48 @@ module Zerobounce
310
389
  raise ApiResponseError.new(ResponseError.message_from_parts(code, content_type, body), code)
311
390
  end
312
391
  begin
313
- parsed = JSON.parse(body)
392
+ StrictJson.parse(body)
314
393
  rescue JSON::ParserError
315
- raise ApiResponseError.new('ZeroBounce returned a response that is not valid JSON.', code)
394
+ # cause: nil, or the parser's error, which quotes the body, would ride
395
+ # along as #cause.
396
+ raise ApiResponseError.new('ZeroBounce returned a response that is not valid JSON.', code), cause: nil
316
397
  end
317
- return parsed unless parsed.is_a?(Hash)
398
+ end
399
+
400
+ # The calls whose documented answer is a JSON array: list_filters, and
401
+ # listS3files, which may also answer {"success": true, "files": [...]}.
402
+ # Every other call answers a JSON object.
403
+ ARRAY_PATHS = %w[filters/list listS3files].freeze
404
+
405
+ # E7: strict JSON of the wrong shape for the call (0, "x", null, true, an
406
+ # array where an object is expected, an object where an array is) is an
407
+ # API error with the HTTP status, never a result.
408
+ def self.__require_shape__(response, parsed, path)
409
+ return parsed if parsed.is_a?(Array) && ARRAY_PATHS.include?(path)
410
+ # The documented field types of the answer (ResponseShape), for the calls that have a shape.
411
+ return ResponseShape.check!(parsed, path, response.code) if parsed.is_a?(Hash) && !ARRAY_PATHS.include?(path)
412
+ return parsed if parsed.is_a?(Hash) && path == 'listS3files' && parsed['files'].is_a?(Array)
413
+
414
+ expected = { 'filters/list' => 'an array', 'listS3files' => 'an object with files, or an array' }
415
+ .fetch(path, 'an object')
416
+ raise ApiResponseError.new("ZeroBounce returned JSON of an unexpected shape: expected #{expected}.",
417
+ response.code)
418
+ end
419
+
420
+ # The "error" of the first entry of an "errors" array; an entry that is
421
+ # not an object is the wrong shape (E7), not a TypeError.
422
+ def self.__first_error__(response, errors)
423
+ first = errors[0]
424
+ return first['error'] if first.is_a?(Hash)
425
+
426
+ raise ApiResponseError.new('ZeroBounce returned JSON of an unexpected shape: an errors entry is not an object.',
427
+ response.code)
428
+ end
429
+
430
+ def self.__parse_json_response__(response, path = nil, strict: true)
431
+ parsed = __parse_json_body__(response)
432
+ code = response.code
433
+ return __require_shape__(response, parsed, path) unless parsed.is_a?(Hash)
318
434
 
319
435
  __raise_if_success_false__(response, parsed)
320
436
 
@@ -326,9 +442,10 @@ module Zerobounce
326
442
  end
327
443
  __raise_if_bare_error__(response, parsed)
328
444
  if parsed.key?('errors') && parsed['errors'].is_a?(Array) && !parsed['errors'].empty?
329
- raise ApiResponseError.new(ResponseError.strip_prefix(parsed['errors'][0]['error']), code)
445
+ raise ApiResponseError.new(ResponseError.strip_prefix(__first_error__(response, parsed['errors'])), code)
330
446
  end
331
- parsed
447
+ __raise_if_untyped_answer__(response, parsed, path) if strict
448
+ __require_shape__(response, parsed, path)
332
449
  end
333
450
 
334
451
  end
@@ -5,9 +5,11 @@ require 'zerobounce/api_key'
5
5
  module Zerobounce
6
6
  # One API key. Package methods share Zerobounce.config; a Client does not.
7
7
  class Client
8
+ include ApiKey::RefusesDump
9
+
8
10
  def initialize(apikey)
9
11
  ApiKey.check!(apikey) unless apikey.nil? || apikey.to_s.strip.empty?
10
- @apikey = apikey
12
+ @apikey = apikey.nil? ? nil : ApiKey::Secret.new(apikey)
11
13
  end
12
14
 
13
15
  # Keeps the API key out of logs and consoles.
@@ -16,15 +18,21 @@ module Zerobounce
16
18
  end
17
19
 
18
20
  def validate(email, ip_address = nil, **options)
19
- Zerobounce.with_api_key(@apikey) { Zerobounce.validate(email, ip_address, **options) }
21
+ Zerobounce.with_api_key(key) { Zerobounce.validate(email, ip_address, **options) }
20
22
  end
21
23
 
22
24
  def credits
23
- Zerobounce.with_api_key(@apikey) { Zerobounce.credits }
25
+ Zerobounce.with_api_key(key) { Zerobounce.credits }
24
26
  end
25
27
 
26
28
  def validate_batch(emails, ip_addresses = [], **options)
27
- Zerobounce.with_api_key(@apikey) { Zerobounce.validate_batch(emails, ip_addresses, **options) }
29
+ Zerobounce.with_api_key(key) { Zerobounce.validate_batch(emails, ip_addresses, **options) }
30
+ end
31
+
32
+ private
33
+
34
+ def key
35
+ @apikey&.value
28
36
  end
29
37
  end
30
38
  end
@@ -1,7 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'rest-client'
4
3
  require_relative 'api_urls'
4
+ require_relative 'api_key'
5
5
 
6
6
  module Zerobounce
7
7
  # Configuration object for Zerobounce.
@@ -30,8 +30,24 @@ module Zerobounce
30
30
  # @attr [Array<Symbol>] valid_statues
31
31
  # The statuses that are considered valid by {Response#valid?}.
32
32
  class Configuration
33
- attr_accessor :headers, :apikey, :api_root_url, :bulk_api_root_url, :bulk_root_url,
34
- :list_evaluator_root_url, :inbox_placement_root_url, :valid_statuses, :mock
33
+ include ApiKey::RefusesDump
34
+
35
+ attr_accessor :headers, :apikey, :valid_statuses, :mock
36
+ attr_reader :api_root_url, :bulk_api_root_url, :bulk_root_url, :list_evaluator_root_url, :inbox_placement_root_url
37
+
38
+ # The base URLs are refused at configuration unless they are a valid
39
+ # https:// URL (ApiUrls.check!): every request carries the API key.
40
+ # bulk_root_url may also be nil or blank, which derives it from
41
+ # bulk_api_root_url.
42
+ %i[api_root_url bulk_api_root_url list_evaluator_root_url inbox_placement_root_url].each do |name|
43
+ define_method(:"#{name}=") do |url|
44
+ instance_variable_set(:"@#{name}", ApiUrls.check!(url, name.to_s))
45
+ end
46
+ end
47
+
48
+ def bulk_root_url=(url)
49
+ @bulk_root_url = url.to_s.strip.empty? ? url : ApiUrls.check!(url, 'bulk_root_url')
50
+ end
35
51
 
36
52
  def initialize(mock = false)
37
53
  self.apikey = ENV['ZEROBOUNCE_API_KEY']
@@ -58,20 +58,32 @@ module Zerobounce
58
58
  #
59
59
  # Carries the HTTP status so callers can tell a 403 (Cloudflare) from a
60
60
  # 400/404 (API) or a 429 (the Warmup rate limit). The Warmup client raises
61
- # it. The validation client raises the RestClient exception for an HTTP
62
- # error status (status in #http_code), as it did up to 2.1.8, and this
63
- # class, with the 2xx status (usually 200), for an error reported on a
64
- # successful HTTP response; both carry the same short message. It is a
65
- # RuntimeError, which those errors were before, so `rescue RuntimeError`
66
- # still catches them.
61
+ # it, for every HTTP error status (4xx, 5xx, and a 3xx, which is never
62
+ # followed), for an error reported on a successful HTTP response (status
63
+ # usually 200) and for a transport failure (refused, reset, timeout, TLS, a
64
+ # body cut short), whose status is 0. It is a RuntimeError, which the
65
+ # validation client's errors were before, so `rescue RuntimeError` still
66
+ # catches them.
67
+ #
68
+ # Its message is often built from a response body, which can quote the
69
+ # API key (an "Invalid API key <key>" message, a proxy echoing the request
70
+ # URL, an HTML title). Every message is therefore redacted here, once, so
71
+ # each path that raises this error inherits it.
67
72
  class ApiResponseError < RuntimeError
68
73
  # @return [Integer] the HTTP status of the failed response, or 0
69
74
  attr_reader :status_code
70
75
 
71
76
  def initialize(message, status_code = 0)
72
- super(message)
77
+ super(ApiResponseError.redact(message))
73
78
  @status_code = status_code.to_i
74
79
  end
80
+
81
+ # The message with the request's API key replaced by ***.
82
+ def self.redact(message)
83
+ return message unless defined?(Zerobounce::BaseRequest)
84
+
85
+ Zerobounce::BaseRequest.__redact_api_key__(message)
86
+ end
75
87
  end
76
88
 
77
89
  # Server returned a 500 error.
@@ -10,37 +10,53 @@ module Zerobounce
10
10
  module GetFileHelper
11
11
  module_function
12
12
 
13
- # @param [String] body
14
- # @return [Boolean]
15
- def json_indicates_error?(body)
16
- t = body.to_s.lstrip
17
- return false if t.empty? || t[0] != '{'
13
+ BOM = "\uFEFF"
18
14
 
19
- o = JSON.parse(t)
20
- return false unless o.is_a?(Hash)
21
-
22
- if o.key?('success')
23
- s = o['success']
24
- return true if s == false || s == 'False' || s == 'false'
25
- end
15
+ # The text without a leading byte-order mark (a UTF-8 BOM, however the
16
+ # body was decoded).
17
+ # @param [String] body
18
+ # @return [String]
19
+ def strip_bom(body)
20
+ text = body.to_s.dup
21
+ text.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
22
+ text = text.scrub('') unless text.valid_encoding?
23
+ text.delete_prefix(BOM)
24
+ end
26
25
 
27
- %w[message error error_message].each do |k|
28
- v = o[k]
29
- next if v.nil?
26
+ # Whether the Content-Type is JSON: application/json, any */*+json
27
+ # (application/problem+json), or application/json anywhere in the value.
28
+ # @param [String] content_type
29
+ # @return [Boolean]
30
+ def json_type?(content_type)
31
+ value = content_type.to_s.downcase
32
+ media = value.split(';').first.to_s.strip
33
+ media == 'application/json' || media.end_with?('+json') || value.include?('application/json')
34
+ end
30
35
 
31
- return true if v.is_a?(String) && !v.strip.empty?
32
- return true if v.is_a?(Array) && !v.empty?
33
- end
36
+ # Whether the body (after a BOM and white space) is a JSON object or array.
37
+ # No result file is one, so it is an API answer, not file content.
38
+ # @param [String] body
39
+ # @return [Boolean]
40
+ def json_container?(body)
41
+ text = strip_bom(body).lstrip
42
+ return false unless text.start_with?('{', '[')
34
43
 
35
- o.key?('success')
44
+ JSON.parse(text)
45
+ true
36
46
  rescue JSON::ParserError
37
47
  false
38
48
  end
39
49
 
50
+ # @param [String] body
51
+ # @return [Boolean]
52
+ def json_indicates_error?(body)
53
+ json_container?(body)
54
+ end
55
+
40
56
  # @param [String] body
41
57
  # @return [String]
42
58
  def format_error_message(body)
43
- o = JSON.parse(body.to_s)
59
+ o = JSON.parse(strip_bom(body))
44
60
  return body.to_s unless o.is_a?(Hash)
45
61
 
46
62
  %w[message error error_message].each do |k|
@@ -58,13 +74,10 @@ module Zerobounce
58
74
  # @param [String] content_type
59
75
  # @return [Boolean]
60
76
  def should_treat_as_error?(body, content_type)
61
- ct = content_type.to_s.downcase
62
- return true if ct.include?('application/json')
63
-
64
- json_indicates_error?(body)
77
+ json_type?(content_type) || json_container?(body)
65
78
  end
66
79
 
67
- # @param [RestClient::Response] response
80
+ # @param [Zerobounce::HttpTransport::Response] response
68
81
  # @return [String] CSV/text body on success
69
82
  def process_getfile_response(response)
70
83
  code = response.code.to_i
@@ -72,12 +85,12 @@ module Zerobounce
72
85
  ct = (response.headers[:content_type] || response.headers['Content-Type'] || '').to_s
73
86
 
74
87
  # An empty body is no result file: an error, as in the other SDKs.
75
- if code > 299 || body_str.strip.empty? || ResponseError.html?(body_str, ct)
88
+ if code > 299 || strip_bom(body_str).strip.empty? || ResponseError.html?(body_str, ct)
76
89
  raise ApiResponseError.new(ResponseError.message_from_parts(code, ct, body_str), code)
77
90
  end
78
91
 
79
92
  if should_treat_as_error?(body_str, ct)
80
- raise ApiResponseError.new(format_error_message(body_str), code)
93
+ raise ApiResponseError.new(ResponseError.message_from_parts(code, ct, strip_bom(body_str)), code)
81
94
  end
82
95
 
83
96
  io = StringIO.new(response.body)