fulfil-io 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d85caade2af0ca4d9ede6a970d0c9b802960e5bc192a41d70eb9c70f153640b1
-  data.tar.gz: 13b43002ee089a9781221b7c42cef81a12474a11ccdb9f6e9df248eaabff8f84
+  metadata.gz: 379e34db2187ee0e41cbc4a530deec467a6f7874c8474c6a5057981ed6ff7ffc
+  data.tar.gz: da1e1fcf9945729d29554c803fcd954611575ba54f74e7f1c1931fe4e4554731
 SHA512:
-  metadata.gz: 415418f4c4a54490b95d3823272096e481b064bf0be0f45cd44dc2c093af7616d93e56b46e0286447febf154f1187fbcbf31a0d3f3d8e456846a5590b636bc04
-  data.tar.gz: 854d989c8b343dabd2317850f578a7a2c37c9a19d04873b19eb278c278a78a51c94a928d5cf24f5a7265f05a63ff6d1dfcb5853971448843957827af9554bb9e
+  metadata.gz: 12f8136e71bbe678bac2e3091209b5c56f03f3a70ceb3df50ebca4d88ac32f527e3f29c308affa2180f6e0e6c23964b48fed87801f18173c369f8cc161eb794f
+  data.tar.gz: 415ab129cabfe1bba36c7fd9bd94b083eeeb64fe0ff71ad508a6f29e74111ab863c281d4da93020b44ec54b1d9ef3fc1ac19ef1809e74af08091deb8824bac1f

data/README.md

@@ -145,6 +145,34 @@ $ Fulfil.rate_limit.limit
 $ Fulfil.rate_limit.resets_at
 => #<DateTime: 2022-01-21T16:36:01-04:00 />
 ```
+
+### Automatic retry API call after rate limit hit
+
+Automatic retries are supported whenever the rate limit is reached. However, it's not enabled by default. To enable it, set the `retry_on_rate_limit` to `true`. By default, the request will be retried in 1 second.
+
+```ruby
+# config/initializers/fulfil.rb
+
+Fulfil.configure do |config|
+  config.retry_on_rate_limit = true # Defaults to false
+  config.retry_on_rate_limit_wait = 0.25 # Defaults to 1 (second)
+end
+```
+
+### Monitor rate limit hits
+
+Through the configurable `rate_limit_notification_handler` one can monitor the rate limit hits to the APM tool of choice.
+
+```ruby
+# config/initializers/fulfil.rb
+
+Fulfil.configure do |config|
+  config.rate_limit_notification_handler = proc {
+    FakeAPM.increment_counter('fulfil.rate_limit_exceeded')
+  }
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/fulfil/client.rb

@@ -164,6 +164,13 @@ module Fulfil
     rescue HTTP::ResponseError => e
       raise ResponseError, "Can't process response: #{e}"
       []
+    # If configured, the client will wait whenever the `RateLimitExceeded` exception
+    # is raised. Check `Fulfil::Configuration` for more details.
+    rescue RateLimitExceeded => e
+      raise e unless config.retry_on_rate_limit?
+
+      sleep config.retry_on_rate_limit_wait
+      retry
     end
 
     def client
@@ -172,5 +179,9 @@ module Fulfil
       client = client.headers(@headers)
       client
     end
+
+    def config
+      Fulfil.config
+    end
   end
 end

data/lib/fulfil/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Fulfil
+  # The `Fulfil::Configuration` contains the available configuration options
+  # for the `Fulfil` gem.
+  class Configuration
+    # Allow the `Fulfil::Client` to automatically retry when the rate limit is hit.
+    # By default, the `Fulfil::Client` will wait 1 second before retrying again.
+    attr_accessor :retry_on_rate_limit
+    attr_accessor :retry_on_rate_limit_wait
+
+    # Allows the client to configure a notification handler. Can be used by APM
+    # tools to monitor the number of rate limit hits.
+    #
+    # @example Use APM to monitor the API rate limit hits
+    #   Fulfil.configure do |config|
+    #     config.rate_limit_notification_handler = proc {
+    #       FakeAPM.increment_counter('fulfil.rate_limit_exceeded')
+    #     }
+    #   end
+    #
+    # @return [Proc, nil]
+    attr_accessor :rate_limit_notification_handler
+
+    def initialize
+      @retry_on_rate_limit = false
+      @retry_on_rate_limit_wait = 1
+    end
+
+    def retry_on_rate_limit?
+      @retry_on_rate_limit
+    end
+  end
+
+  # Returns Fulfil's configuration.
+  # @return [Fulfil::Configuration] Fulfil's configuration
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Allows setting a new configuration for Fulfil.
+  # @return [Fulfil::Configuration] Fulfil's new configuration
+  def self.config=(configuration)
+    @config = configuration
+  end
+
+  # Allows modifying Fulfil's configuration.
+  #
+  # Example usage:
+  #
+  #   Fulfil.configure do |config|
+  #     config.api_key = "..."
+  #   end
+  #
+  def self.configure
+    yield(config)
+  end
+end

data/lib/fulfil/rate_limit.rb

@@ -8,7 +8,8 @@ module Fulfil
 
     # Analyses the rate limit based on the response headers from Fulfil.
     # @param headers [HTTP::Headers] The HTTP response headers from Fulfil.
-    # @return [Fulfil::RateLimit]
+    # @raise [Fulfil::RateLimitExceeded] When the rate limit is hit.
+    # @return [true]
     def analyse!(headers)
       rate_limit_headers = RateLimitHeaders.new(headers)
 
@@ -16,7 +17,9 @@ module Fulfil
       self.requests_left = rate_limit_headers.requests_left
       self.resets_at = rate_limit_headers.resets_at
 
-      raise Fulfil::RateLimitExceeded unless requests_left?
+      return true if requests_left?
+
+      report_rate_limit_hit_and_raise
     end
 
     # Returns whether there are any requests left in the current rate limit window.
@@ -24,5 +27,13 @@ module Fulfil
     def requests_left?
       requests_left&.positive?
     end
+
+    private
+
+    # @raise [Fulfil::RateLimitExceeded]
+    def report_rate_limit_hit_and_raise
+      Fulfil.config.rate_limit_notification_handler&.call
+      raise Fulfil::RateLimitExceeded
+    end
   end
 end

data/lib/fulfil/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fulfil
-  VERSION = "0.6.1"
+  VERSION = "0.7.1"
 end

data/lib/fulfil.rb

@@ -2,6 +2,7 @@
 
 require 'fulfil/version'
 require 'fulfil/error'
+require 'fulfil/configuration'
 require 'fulfil/client'
 require 'fulfil/model'
 require 'fulfil/interactive_report'

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: fulfil-io
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Chris Moore
 - Kat Fairbanks
+- Stefan Vermaas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-22 00:00:00.000000000 Z
+date: 2022-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -20,7 +21,7 @@ dependencies:
         version: 4.4.1
     - - "<"
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -30,7 +31,7 @@ dependencies:
         version: 4.4.1
     - - "<"
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +153,7 @@ files:
 - lib/fulfil-io.rb
 - lib/fulfil.rb
 - lib/fulfil/client.rb
+- lib/fulfil/configuration.rb
 - lib/fulfil/error.rb
 - lib/fulfil/interactive_report.rb
 - lib/fulfil/model.rb
@@ -180,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.12
 signing_key:
 specification_version: 4
 summary: Interact with the Fulfil.io API