vpndetection 5.4.1 → 5.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f1e4982b72ed2bd82abdc656375e35282b567aa9b1ca549308b2739ab7334f1
-  data.tar.gz: ee66d0a96bd81eb8344be23df461bc6969fd12f528ff44717975c0e85b627db8
+  metadata.gz: ba80a879812af8dc9d6cdefdb305d97fe38281550cad1b2c9bd76ab31b416bf2
+  data.tar.gz: 602fb1b3b602fa0ec12ca8d465dcda92e22d87610714ca31ec735033a83b61f6
 SHA512:
-  metadata.gz: 0473751a9f0be66de9b1ef36e383eb5b27f24c3be1c54d33defb4d09c331d6bbfc8b48e55e62a7442d2ae8575fd02f43250d402c8afe790a98359095c0d4f0b9
-  data.tar.gz: d070aac3cc244abbb3f3fe2342f2b9812e4f73256573b5d1a144627ecc7afee34866844edfe260f564e50c33f397f3d8333f299a628f34a590f756ec773e50c5
+  metadata.gz: 340fbe8a1a6265f5dec5d5e93fecd2c63c171af83699fdc073ac98410d83e2ec4924c2b358c4a30785f3aeebb8b606cbefa0eeba0c54f402fda60a03dda1f843
+  data.tar.gz: eae9ca20b51fbb6d12060add25b281625c5096e9b54fd7ef1b596a8c54c476589fc09662c117c4eeb879556482fe7caa9056c0b81581af98d739079df544d557

data/README.md

@@ -150,7 +150,7 @@ end
 
 `kind` is one of `:bad_request`, `:unauthorized`, `:forbidden`, `:rate_limited`, `:quota_exceeded`, `:server_error` or `:network`.
 
-Note that `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.
+Note that `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded. It waits the `Retry-After` the API sent, or its own backoff from 250 ms when that's past about 24.8 days.
 
 ### Timeouts and retries
 
@@ -160,7 +160,7 @@ client = VPNDetection::Client.new(timeout: 10, retries: 4)
 result = client.lookup('45.83.91.1', timeout: 2, retries: 0)
 ```
 
-`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; before 5.2.0 the default was 10, so pass `timeout: 10` to keep that bound. The client's values are defaults: `lookup`, `lookup_batch`, `my_ip` and `my_entitlement` each take `timeout:` and `retries:` for that call alone, and every `client.oauth` method and every `client.database` call that is not a transfer takes `timeout:` (from 5.3.0). A database download bounds only its connection with it, because a whole transfer can take minutes.
+`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; before 5.2.0 the default was 10, so pass `timeout: 10` to keep that bound. The client's values are defaults: `lookup`, `lookup_batch`, `my_ip` and `my_entitlement` each take `timeout:` and `retries:` for that call alone, and every `client.oauth` method and every `client.database` call that is not a transfer takes `timeout:` (from 5.3.0). A database download bounds only its connection with it, because a whole transfer can take minutes. 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.
 
 ### Database downloads
 

data/lib/vpndetection/client.rb

@@ -29,11 +29,17 @@ module VPNDetection
     # @param cache [Boolean] pass false to disable caching.
     # @param cache_ttl [Numeric] how long an answer stays fresh, in seconds.
     # @param concurrency [Integer] batch requests - chunks of up to 1000 addresses - in flight during a batch.
-    # @param retries [Integer] extra attempts for a transient failure.
+    # @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 one request may take before it is
-    #   abandoned. Applies per ATTEMPT, so a retried call may take longer in
-    #   total, and every call that takes `retries:` also takes `timeout:` to
-    #   override it. A dataset transfer bounds only its connect phase with it.
+    #   abandoned, 0 for no bound. Applies per ATTEMPT, so a retried call may take
+    #   longer in total, and every call that takes `retries:` also takes
+    #   `timeout:` to override it. A dataset transfer bounds only its connect
+    #   phase with it.
+    # @raise [ArgumentError] for a `timeout`, here or on any call, 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, cache: true,
                    cache_max_size: DEFAULT_CACHE_MAX_SIZE, cache_ttl: DEFAULT_CACHE_TTL,
@@ -43,6 +49,9 @@ module VPNDetection
         Transport::Config.new(api_key: api_key, base_url: base_url, timeout: timeout),
       )
       @cache = cache ? Cache.new(max_size: cache_max_size, ttl: cache_ttl) : nil
+      # The addresses with a request in flight, each a Flight its waiters block on.
+      @flights = {}
+      @flights_lock = Mutex.new
       @concurrency = concurrency
       @retries = retries
       @database = DatabaseApi.new(@transport, retries: retries)
@@ -68,16 +77,30 @@ module VPNDetection
     # @param retries [Integer, nil] extra attempts, for THIS call only.
     # @param timeout [Numeric, nil] seconds each attempt may take, for THIS call only.
     def lookup(ip, retries: nil, timeout: nil)
+      # Here as well as in the transport: a bogon or a cached answer returns before any request.
+      Transport.checked_timeout(timeout) unless timeout.nil?
       return Bogon.result(ip) if Bogon.bogon?(ip)
 
-      hit = @cache&.get(ip)
-      return hit unless hit.nil?
+      loop do
+        hit = @cache&.get(ip)
+        return hit unless hit.nil?
 
-      result = Retries.with_retries(retries || @retries) do
-        Transport.lookup_result(@transport.lookup_request(ip, timeout: timeout).run)
+        flight, leader = board(ip)
+        return fetch(ip, retries, timeout) if flight.nil?
+
+        if leader
+          # Read once more now the address is boarded: a leader that landed
+          # between the miss above and boarding has already cached its answer.
+          hit = @cache.get(ip)
+          return unboard(ip, flight, :served, hit) unless hit.nil?
+
+          return lead(ip, flight) { fetch(ip, retries, timeout) }
+        end
+        state, value = flight.wait
+        return value if state == :served
+        raise value if state == :failed
+        # :abandoned - its leader never finished, so this caller asks again.
       end
-      @cache&.set(ip, result)
-      result
     end
 
     # Classify the address this client is calling from.
@@ -142,6 +165,7 @@ module VPNDetection
       unless limit.is_a?(Numeric) && limit >= 1
         raise Error.new(:bad_request, "concurrency must be at least 1, not #{limit.inspect}")
       end
+      Transport.checked_timeout(timeout) unless timeout.nil?
 
       addresses = ips.to_a.uniq
       answers = {}
@@ -151,9 +175,27 @@ module VPNDetection
         hit = Bogon.bogon?(ip) ? Bogon.result(ip) : @cache&.get(ip)
         hit.nil? ? pending << ip : answers[ip] = hit
       end
-      unless pending.empty?
-        run_batch(pending.each_slice(BATCH_MAX).to_a, answers, limit, retries || @retries, timeout)
+      # Boarded before any chunk is built, so a lookup arriving meanwhile waits
+      # for this batch; an address already in flight is not sent again.
+      boarded = {}
+      joined = {}
+      pending.each do |ip|
+        flight, leader = board(ip)
+        if leader == false
+          joined[ip] = flight
+        else
+          boarded[ip] = flight
+        end
+      end
+      begin
+        unless boarded.empty?
+          chunks = boarded.keys.each_slice(BATCH_MAX).to_a
+          run_batch(chunks, answers, limit, retries || @retries, timeout, boarded)
+        end
+      ensure
+        boarded.each { |ip, flight| unboard(ip, flight, :abandoned) unless flight.nil? }
       end
+      joined.each { |ip, flight| answers[ip] = joined_answer(ip, flight, retries, timeout) }
 
       # Reinstated in input order: a hydra settles in completion order, and a
       # caller iterating the hash should see what they passed in.
@@ -162,11 +204,83 @@ module VPNDetection
 
     private
 
+    # Concurrent misses for one address share ONE request (docs/sdk/contract.md,
+    # UMAN-4645): 5.4.2 sent one per calling thread. The first miss boards the
+    # address and every miss after it, a batch's included, waits on its Flight.
+    class Flight
+      def initialize
+        @lock = Mutex.new
+        @landed = ConditionVariable.new
+        @state = :pending
+      end
+
+      # Settles the flight once, for every waiter: :served with a Result,
+      # :failed with an Error, or :abandoned when its leader never finished.
+      def land(state, value = nil)
+        @lock.synchronize do
+          next unless @state == :pending
+
+          @state = state
+          @value = value
+          @landed.broadcast
+        end
+      end
+
+      # Blocks until the flight lands, then [state, value].
+      def wait
+        @lock.synchronize do
+          @landed.wait(@lock) while @state == :pending
+          [@state, @value]
+        end
+      end
+    end
+
+    # [flight, true] when this caller leads the request for `ip`, [flight,
+    # false] when one is already in flight, and nil without a cache: every
+    # lookup is then served, so nothing is shared.
+    def board(ip)
+      return nil if @cache.nil?
+
+      @flights_lock.synchronize do
+        existing = @flights[ip]
+        existing ? [existing, false] : [@flights[ip] = Flight.new, true]
+      end
+    end
+
+    # Takes `ip` off the board and lands its flight. Returns `value`.
+    def unboard(ip, flight, state, value = nil)
+      @flights_lock.synchronize { @flights.delete(ip) if @flights[ip].equal?(flight) }
+      flight.land(state, value)
+      value
+    end
+
+    # Runs the request a flight is waiting on, under the options of the call
+    # that leads it. A served answer is cached before it lands; a failure
+    # reaches every waiter and is cached for none; and a leader that never
+    # finishes - a killed thread, a Timeout.timeout - abandons the flight, so
+    # its waiters ask again rather than failing with it.
+    def lead(ip, flight)
+      unboard(ip, flight, :served, yield)
+    rescue Error => e
+      unboard(ip, flight, :failed, e)
+      raise
+    ensure
+      unboard(ip, flight, :abandoned)
+    end
+
+    def fetch(ip, retries, timeout)
+      result = Retries.with_retries(retries || @retries) do
+        Transport.lookup_result(@transport.lookup_request(ip, timeout: timeout).run)
+      end
+      @cache&.set(ip, result)
+      result
+    end
+
     # One hydra per call, sized for THIS call. Reusing an instance-level hydra
     # would silently cap a per-call concurrency at the client's setting, and
     # would not be safe to drive from two threads either. Each request is one
     # chunk of up to 1000 addresses.
-    def run_batch(chunks, answers, concurrency, retries, timeout)
+    def run_batch(chunks, answers, concurrency, retries, timeout, boarded)
       hydra = Typhoeus::Hydra.new(max_concurrency: concurrency)
       attempts = Hash.new(0)
 
@@ -174,7 +288,11 @@ module VPNDetection
         request = @transport.batch_request(chunk, timeout: timeout)
         request.on_complete do |response|
           outcome = settle(chunk, response, attempts, retries, enqueue)
-          answers.merge!(outcome) unless outcome.nil?
+          outcome&.each do |ip, answer|
+            answers[ip] = answer
+            flight = boarded[ip]
+            unboard(ip, flight, answer.is_a?(Result) ? :served : :failed, answer) unless flight.nil?
+          end
         end
         hydra.queue(request)
       end
@@ -205,6 +323,17 @@ module VPNDetection
       nil
     end
 
+    # What a batch takes for an address another call was fetching: that call's
+    # answer or error, or, when its leader never finished, its own lookup.
+    def joined_answer(ip, flight, retries, timeout)
+      state, value = flight.wait
+      return value unless state == :abandoned
+
+      lookup(ip, retries: retries, timeout: timeout)
+    rescue Error => e
+      e
+    end
+
     # Every address lands in exactly one of `results` and `errors`; an address in
     # neither is the server breaking its own contract, and is reported as such
     # rather than lost.

data/lib/vpndetection/database_api.rb

@@ -7,7 +7,8 @@ module VPNDetection
   # needs a key carrying the `db.download` scope.
   #
   # 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 dataset
   # runs to gigabytes and minutes, so a bound that suits a JSON call would
   # abandon a healthy download.

data/lib/vpndetection/oauth_api.rb

@@ -17,6 +17,8 @@ module VPNDetection
     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 VPNDetection
       @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 VPNDetection
     # 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 VPNDetection
     # @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 VPNDetection
 
     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/vpndetection/retries.rb

@@ -9,6 +9,10 @@ module VPNDetection
   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, perl and php 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 VPNDetection
       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, `2147484` held the call for 24.8 days, and `sleep` raised a raw
+    # RangeError for `9223372036854775807` and `1e400`.
     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/vpndetection/transport.rb

@@ -17,6 +17,23 @@ module VPNDetection
     ENTITLEMENT_PATH = '/api/v1/entitlement'
     BATCH_PATH = '/batch'
 
+    # 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 EVERY security scheme the spec lists,
     # so a keyless client would send `Authorization: Bearer `, an empty
     # `X-Api-Key` and an empty `apikey` query parameter. The API answers 401 to
@@ -29,7 +46,7 @@ module VPNDetection
         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
 
       def auth_settings
@@ -59,7 +76,7 @@ module VPNDetection
     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/vpndetection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VPNDetection
-  VERSION = '5.4.1'
+  VERSION = '5.4.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 5.4.1
+  version: 5.4.3
 platform: ruby
 authors:
 - Mslm Dev