internetdata 2.3.1 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2733fa2507c4610501c4941ee66bd085f4eecee78491803742d7c796de693df2
-  data.tar.gz: af87a305689fbdba6d7c409944c6b7eeb8f7682ce9e1209829186b7b89a3faf7
+  metadata.gz: 75d59c125ee280d0f8d9fe9522fa6003ac9a1e6fc764839f93f2907f3ee7d13f
+  data.tar.gz: 9ee66403a693539439df78eb8cb65306f84093fd6480a92361650b7cd6bc987f
 SHA512:
-  metadata.gz: 6c4e6ac56b6baad950705defb63fad84e7f85f623cbbff479fc7702d4be222dc9c425e842d4344dbbe40e3e08dbad020c9b7b78b52565459be226b78742b0dec
-  data.tar.gz: 0a3609002009c1dff4daaed53a5957369d81a0dfa3806a7afc93f2ee2fd3f3ba3ede86e802139f6d8a81a4dfc75f9bf0e89ab7d607472d9c84488300d70139a1
+  metadata.gz: cc51733b2f9e672c36766706ab55cc52cc14e530b1de6d46b9bfa9bc323ff9bd7f4d268f727ea4f2e833e28ec7e47f53b25c3218b2a434ff05f0e86a8b122451
+  data.tar.gz: 0ce870a40d24b737bf8a4e45d0fbec3763bbd0ec6e65e76ebc9a65bfdd44aa6cbaf677f84e61ad7060b8dd209a94ef3ba69fae20a1a63a1cc19c9348b099d67a

data/README.md

@@ -100,7 +100,7 @@ client = InternetData::Client.new(api_key: ENV['INTERNETDATA_API_KEY'], timeout:
 catalog = client.database.list(timeout: 5)
 ```
 
-`timeout` is in seconds and bounds each attempt, body included, so a call that is retried can take longer in total. It defaults to 30 seconds. The client's value is the default: from 2.1.0, `list`, `metadata`, `checksums`, `downloads` and `download_url` each take `timeout:` for that call alone.
+`timeout` is in seconds and bounds each attempt, body included, so a call that is retried can take longer in total. It defaults to 30 seconds, and 0 means no bound. The client's value is the default: from 2.1.0, `list`, `metadata`, `checksums`, `downloads` and `download_url` each take `timeout:` for that call alone. A negative value, anything that isn't a number, and anything past 2147483.647 seconds (the longest curl holds) raise `ArgumentError` where you pass them, before any request.
 
 `download` and `download_bytes` take no `timeout:` and raise `ArgumentError` if handed one, rather than accepting it and quietly doing nothing: a transfer runs to gigabytes and minutes, so any bound that suits a JSON call would abandon a healthy download. They bound only their connection with the client's value. `download_url` does take one, because minting the link is an ordinary API request - it bounds that request, not whatever you do with the link afterwards.
 
@@ -118,7 +118,7 @@ end
 
 `kind` is one of `:bad_request`, `:unauthorized`, `:forbidden`, `:rate_limited`, `:quota_exceeded`, `:server_error` or `:network`. `rc` is the API's own result code, such as `NOT_LICENSED` or `LICENSE_EXPIRED`, which is usually the specific thing you want to read.
 
-Note that `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a burst, so retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries the first for you and never the second.
+Note that `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a burst, so retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries the first for you and never the second. It waits the `Retry-After` the API sent, or its own backoff from 250 ms when that's past about 24.8 days.
 
 ### Sign in with OAuth (device flow)
 

data/lib/internetdata/client.rb

@@ -21,9 +21,13 @@ module InternetData
 
     # @param api_key [String, nil] a key carrying the `db.download` scope. Omit
     #   it and no credential is sent; every database published today answers 401.
-    # @param retries [Integer] extra attempts for a transient failure.
-    # @param timeout [Numeric] seconds allowed for one API call. It also bounds the
-    #   CONNECT phase of a transfer, which is otherwise unlimited.
+    # @param retries [Integer] extra attempts for a transient failure. Each waits
+    #   the server's `Retry-After` when it sent one of at most about 24.8 days,
+    #   and otherwise a backoff of 250 ms that doubles per retry.
+    # @param timeout [Numeric] seconds allowed for one API call, 0 for no bound. It
+    #   also bounds the CONNECT phase of a transfer, which is otherwise unlimited.
+    # @raise [ArgumentError] for a `timeout` that is negative, not a finite number,
+    #   or past 2147483.647 seconds (2**31 - 1 ms), the longest curl holds.
     # @param transport [Transport, nil] override the HTTP layer, mostly for tests.
     def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, retries: DEFAULT_RETRIES,
                    timeout: DEFAULT_TIMEOUT, transport: nil)

data/lib/internetdata/database_api.rb

@@ -7,7 +7,8 @@ module InternetData
   # the generated {DatabaseV2Api} underneath, which speaks the wire.
   #
   # Every JSON call here takes `timeout:`, in seconds, bounding each ATTEMPT of
-  # that call alone and overriding the bound the client was built with. The two
+  # that call alone and overriding the bound the client was built with; one the
+  # client would refuse raises ArgumentError before any request. The two
   # transfers take none, and are refused it rather than ignoring it: a database
   # runs to gigabytes and minutes, so a bound that suits a JSON call would
   # abandon a healthy download.

data/lib/internetdata/oauth_api.rb

@@ -17,6 +17,8 @@ module InternetData
     TOKEN_PATH = '/oauth/token'
     REVOKE_PATH = '/oauth/revoke'
     DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+    # The longest single `sleep` the poll asks Ruby for, in seconds.
+    LONGEST_SLEEP = 2**31 - 1
 
     # The members a 2xx must carry for its type to mean anything.
     REQUIRED = {
@@ -29,7 +31,7 @@ module InternetData
       @transport = transport
       @retries = retries
       # The poll's wait and its monotonic clock, which a test replaces together.
-      @wait = ->(seconds) { sleep(seconds) }
+      @wait = ->(seconds) { sleep_in_parts(seconds) }
       @now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
     end
 
@@ -96,7 +98,8 @@ module InternetData
     # Wait for the person to approve a device sign-in, and return its tokens.
     #
     # Waits `device.interval` seconds before EVERY exchange, the first included,
-    # and five seconds longer for good each time the server answers `slow_down`.
+    # and five seconds longer for good each time the server answers `slow_down`,
+    # but never past `device.expires_in`: a wait that would end later ends then.
     # Raises {OauthAccessDeniedError} when the person refuses and
     # {OauthExpiredTokenError} when the code expires, including locally, with no
     # status, once `device.expires_in` seconds have passed since this call. Any
@@ -109,10 +112,14 @@ module InternetData
     # @param timeout [Numeric, nil] bounds each exchange, never the whole wait.
     # @return [TokenResponse]
     def poll_device_token(client_id, device, timeout: nil)
+      Transport.checked_timeout(timeout) unless timeout.nil?
       interval = device.interval >= 1 ? device.interval : 5
       deadline = @now.call + device.expires_in
       loop do
-        @wait.call(interval)
+        # A wait that would end past the deadline waits only the time left, never
+        # a negative remainder, and the local expiry below follows with no request.
+        left = deadline - @now.call
+        @wait.call(interval < left ? interval : [left, 0].max)
         raise OauthExpiredTokenError, 'expired_token' if @now.call >= deadline
 
         begin
@@ -129,6 +136,17 @@ module InternetData
 
     private
 
+    # `sleep` raises RangeError for a Float from about 9.2e18 s and an Integer
+    # past 2**63 - 1, and a server's `expires_in` can leave a wait longer than
+    # either, so a long one is slept in parts rather than ending the poll.
+    def sleep_in_parts(seconds)
+      while seconds.positive?
+        part = [seconds, LONGEST_SLEEP].min
+        sleep(part)
+        seconds -= part
+      end
+    end
+
     def exchange(form, timeout)
       decode(TokenResponse, @transport.oauth_request(:POST, TOKEN_PATH, form: form, timeout: timeout).run)
     end

data/lib/internetdata/retries.rb

@@ -9,6 +9,10 @@ module InternetData
   module Retries
     BACKOFF_SECONDS = 0.25
 
+    # The longest `Retry-After` honored, in seconds: 2**31 - 1 ms, about 24.8
+    # days, the same bound as the .NET, erlang and perl SDKs'.
+    LONGEST_WAIT = 2_147_483.647
+
     module_function
 
     # `retry_if`, when given, is asked after each retryable failure, and a false
@@ -26,10 +30,16 @@ module InternetData
       end
     end
 
-    # A server-supplied delay always wins, including a `Retry-After: 0`, which
-    # is the server saying "immediately" rather than saying nothing.
+    # A server-supplied delay wins, including a `Retry-After: 0`, which is the
+    # server saying "immediately" rather than saying nothing. One past
+    # LONGEST_WAIT is waited out on the backoff instead, still rate_limited:
+    # honored, `2147483648` held the call for 68 years, and `sleep` raised a raw
+    # RangeError for `9223372036854775807`.
     def delay_for(error, attempt)
-      error.retry_after_seconds || BACKOFF_SECONDS * (2**(attempt - 1))
+      asked = error.retry_after_seconds
+      return asked if asked && asked <= LONGEST_WAIT
+
+      BACKOFF_SECONDS * (2**(attempt - 1))
     end
   end
 end

data/lib/internetdata/transport.rb

@@ -7,6 +7,23 @@ module InternetData
   # The generated wire client, with the three things it gets wrong for this API
   # corrected in one place.
   class Transport < ApiClient
+    # The longest `timeout` curl holds, in seconds: 2**31 - 1 ms, about 24.8 days.
+    # libcurl refuses a longer one, and any negative, and Ethon ignores the
+    # refusal, so the call would run with no bound at all.
+    LONGEST_TIMEOUT = 2_147_483.647
+
+    # `timeout`, once it is a bound curl can hold: seconds, 0 for none. Refused
+    # where it is set, because nothing downstream refuses it: a negative ran with
+    # no bound, and NaN, Infinity, a number past curl's ceiling or a string failed
+    # every call with an error from Ruby, FFI or Ethon that names none of this.
+    # NaN fails both comparisons, and an infinity one of them.
+    def self.checked_timeout(timeout)
+      return timeout if timeout.is_a?(Numeric) && timeout.real? && timeout >= 0 && timeout <= LONGEST_TIMEOUT
+
+      raise ArgumentError,
+            "timeout must be a number of seconds from 0 (no bound) to #{LONGEST_TIMEOUT}, not #{timeout.inspect}"
+    end
+
     # The generated Configuration applies a security scheme whatever it holds, so
     # a keyless client would send `Authorization: Bearer ` - an empty credential,
     # which the API answers 401 to rather than treating as no credential at all.
@@ -19,7 +36,7 @@ module InternetData
         self.host = uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
         self.base_path = uri.path
         self.access_token = api_key
-        self.timeout = timeout
+        self.timeout = timeout.nil? ? nil : Transport.checked_timeout(timeout)
       end
 
       # ONLY the bearer scheme, never `super`.
@@ -59,7 +76,7 @@ module InternetData
     def build_request(http_method, path, opts = {})
       request = super
       request.options[:followlocation] = false
-      request.options[:timeout] = opts[:timeout] unless opts[:timeout].nil?
+      request.options[:timeout] = Transport.checked_timeout(opts[:timeout]) unless opts[:timeout].nil?
       request
     end
 

data/lib/internetdata/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InternetData
-  VERSION = '2.3.1'
+  VERSION = '2.3.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internetdata
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.3.2
 platform: ruby
 authors:
 - Mslm Dev