faraday-retry 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1e1671b917edb92ca89a4cebdd676bc6dfbc63956ef5d17a79bb467dd8134b9
+  data.tar.gz: b29b41e84db3b281a91fbef905925579d3d9ab003dba97e66c2dc906d1ed0d60
+SHA512:
+  metadata.gz: 56bc36544781fe865ba266157f5f07365e69e2efb4aa51fce0e638dec8b19a14e9b1be68f3401e43db7bc76daaf278edcd457fb693f6b314f901c270eb78f3bd
+  data.tar.gz: 363570c19fb872444515db4caa4fda1ba3f135510ce0e6d67d32ab8005d73b06270a48ea41b03ac7b707ae63f97f47b92145dbfeb25e28a546691b147328a3ed

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## v1.0
+
+Initial release.
+This release consists of the same middleware that was previously bundled with Faraday but removed in Faraday v2.0.

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Mattia Giuffrida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# Faraday Retry
+
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/lostisland/faraday-retry/CI)](https://github.com/lostisland/faraday-retry/actions?query=branch%3Amain)
+[![Gem](https://img.shields.io/gem/v/faraday-retry.svg?style=flat-square)](https://rubygems.org/gems/faraday-retry)
+[![License](https://img.shields.io/github/license/lostisland/faraday-retry.svg?style=flat-square)](LICENSE.md)
+
+The `Retry` middleware automatically retries requests that fail due to intermittent client
+or server errors (such as network hiccups).
+By default, it retries 2 times and handles only timeout exceptions.
+It can be configured with an arbitrary number of retries, a list of exceptions to handle,
+a retry interval, a percentage of randomness to add to the retry interval, and a backoff factor.
+The middleware can also handle the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
+header automatically when configured with the right status codes (see below for an example).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faraday-retry'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install faraday-retry
+```
+
+## Usage
+
+This example will result in a first interval that is random between 0.05 and 0.075
+and a second interval that is random between 0.1 and 0.125.
+
+```ruby
+require 'faraday'
+require 'faraday/retry'
+
+retry_options = {
+  max: 2,
+  interval: 0.05,
+  interval_randomness: 0.5,
+  backoff_factor: 2
+}
+
+conn = Faraday.new(...) do |f|
+  f.request :retry, retry_options
+  #...
+end
+
+conn.get('/')
+```
+
+### Control when the middleware will retry requests
+
+By default, the `Retry` middleware will only retry idempotent methods and the most common network-related exceptions.
+You can change this behaviour by providing the right option when adding the middleware to your connection.
+
+#### Specify which methods will be retried
+
+You can provide a `methods` option with a list of HTTP methods.
+This will replace the default list of HTTP methods: `delete`, `get`, `head`, `options`, `put`.
+
+```ruby
+retry_options = {
+  methods: %i[get post]
+}
+```
+
+#### Specify which exceptions should trigger a retry
+
+You can provide an `exceptions` option with a list of exceptions that will replace
+the default list of network-related exceptions: `Errno::ETIMEDOUT`, `Timeout::Error`, `Faraday::TimeoutError`.
+This can be particularly useful when combined with the [RaiseError][raise_error] middleware.
+
+```ruby
+retry_options = {
+  exceptions: [Faraday::ResourceNotFound, Faraday::UnauthorizedError]
+}
+```
+
+#### Specify on which response statuses to retry
+
+By default the `Retry` middleware will only retry the request if one of the expected exceptions arise.
+However, you can specify a list of HTTP statuses you'd like to be retried. When you do so, the middleware will
+check the response `status` code and will retry the request if included in the list.
+
+```ruby
+retry_options = {
+  retry_statuses: [401, 409]
+}
+```
+
+#### Automatically handle the `Retry-After` header
+
+Some APIs, like the [Slack API](https://api.slack.com/docs/rate-limits), will inform you when you reach their API limits by replying with a response status code of `429` and a response header of `Retry-After` containing a time in seconds. You should then only retry querying after the amount of time provided by the `Retry-After` header, otherwise you won't get a response.
+
+You can automatically handle this and have Faraday pause and retry for the right amount of time by including the `429` status code in the retry statuses list:
+
+```ruby
+retry_options = {
+  retry_statuses: [429]
+}
+```
+
+#### Specify a custom retry logic
+
+You can also specify a custom retry logic with the `retry_if` option.
+This option accepts a block that will receive the `env` object and the exception raised
+and should decide if the code should retry still the action or not independent of the retry count.
+This would be useful if the exception produced is non-recoverable or if the the HTTP method called is not idempotent.
+
+**NOTE:** this option will only be used for methods that are not included in the `methods` option.
+If you want this to apply to all HTTP methods, pass `methods: []` as an additional option.
+
+```ruby
+# Retries the request if response contains { success: false }
+retry_options = {
+  retry_if: -> (env, _exc) { env.body[:success] == 'false' }
+}
+```
+
+### Call a block on every retry
+
+You can specify a block through the `retry_block` option that will be called before every retry.
+There are many different applications for this feature, spacing from instrumentation to monitoring.
+Request environment, middleware options, current number of retries and the exception is passed to the block as parameters.
+For example, you might want to keep track of the response statuses:
+
+```ruby
+response_statuses = []
+retry_options = {
+  retry_block: -> (env, options, retries, exc) { response_statuses << env.status }
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Then, run `bin/test` to run the tests.
+
+To install this gem onto your local machine, run `rake build`.
+
+To release a new version, make a commit with a message such as "Bumped to 0.0.2" and then run `rake release`.
+See how it works [here](https://bundler.io/guides/creating_gem.html#releasing-the-gem).
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/lostisland/faraday-retry).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[raise_error]:  https://lostisland.github.io/faraday/middleware/raise-error

data/lib/faraday/retriable_response.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Faraday namespace.
+module Faraday
+  # Exception used to control the Retry middleware.
+  class RetriableResponse < Error
+  end
+end

data/lib/faraday/retry/middleware.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Faraday
+  module Retry
+    # This class provides the main implementation for your middleware.
+    # Your middleware can implement any of the following methods:
+    # * on_request - called when the request is being prepared
+    # * on_complete - called when the response is being processed
+    #
+    # Optionally, you can also override the following methods from Faraday::Middleware
+    # * initialize(app, options = {}) - the initializer method
+    # * call(env) - the main middleware invocation method.
+    #   This already calls on_request and on_complete, so you normally don't need to override it.
+    #   You may need to in case you need to "wrap" the request or need more control
+    #   (see "retry" middleware: https://github.com/lostisland/faraday/blob/main/lib/faraday/request/retry.rb#L142).
+    #   IMPORTANT: Remember to call `@app.call(env)` or `super` to not interrupt the middleware chain!
+    class Middleware < Faraday::Middleware
+      DEFAULT_EXCEPTIONS = [
+        Errno::ETIMEDOUT, 'Timeout::Error',
+        Faraday::TimeoutError, Faraday::RetriableResponse
+      ].freeze
+      IDEMPOTENT_METHODS = %i[delete get head options put].freeze
+
+      # Options contains the configurable parameters for the Retry middleware.
+      class Options < Faraday::Options.new(:max, :interval, :max_interval,
+                                           :interval_randomness,
+                                           :backoff_factor, :exceptions,
+                                           :methods, :retry_if, :retry_block,
+                                           :retry_statuses)
+
+        DEFAULT_CHECK = ->(_env, _exception) { false }
+
+        def self.from(value)
+          if value.is_a?(Integer)
+            new(value)
+          else
+            super(value)
+          end
+        end
+
+        def max
+          (self[:max] ||= 2).to_i
+        end
+
+        def interval
+          (self[:interval] ||= 0).to_f
+        end
+
+        def max_interval
+          (self[:max_interval] ||= Float::MAX).to_f
+        end
+
+        def interval_randomness
+          (self[:interval_randomness] ||= 0).to_f
+        end
+
+        def backoff_factor
+          (self[:backoff_factor] ||= 1).to_f
+        end
+
+        def exceptions
+          Array(self[:exceptions] ||= DEFAULT_EXCEPTIONS)
+        end
+
+        def methods
+          Array(self[:methods] ||= IDEMPOTENT_METHODS)
+        end
+
+        def retry_if
+          self[:retry_if] ||= DEFAULT_CHECK
+        end
+
+        def retry_block
+          self[:retry_block] ||= proc {}
+        end
+
+        def retry_statuses
+          Array(self[:retry_statuses] ||= [])
+        end
+      end
+
+      # @param app [#call]
+      # @param options [Hash]
+      # @option options [Integer] :max (2) Maximum number of retries
+      # @option options [Integer] :interval (0) Pause in seconds between retries
+      # @option options [Integer] :interval_randomness (0) The maximum random
+      #   interval amount expressed as a float between
+      #   0 and 1 to use in addition to the interval.
+      # @option options [Integer] :max_interval (Float::MAX) An upper limit
+      #   for the interval
+      # @option options [Integer] :backoff_factor (1) The amount to multiply
+      #   each successive retry's interval amount by in order to provide backoff
+      # @option options [Array] :exceptions ([ Errno::ETIMEDOUT,
+      #   'Timeout::Error', Faraday::TimeoutError, Faraday::RetriableResponse])
+      #   The list of exceptions to handle. Exceptions can be given as
+      #   Class, Module, or String.
+      # @option options [Array] :methods (the idempotent HTTP methods
+      #   in IDEMPOTENT_METHODS) A list of HTTP methods to retry without
+      #   calling retry_if. Pass an empty Array to call retry_if
+      #   for all exceptions.
+      # @option options [Block] :retry_if (false) block that will receive
+      #   the env object and the exception raised
+      #   and should decide if the code should retry still the action or
+      #   not independent of the retry count. This would be useful
+      #   if the exception produced is non-recoverable or if the
+      #   the HTTP method called is not idempotent.
+      # @option options [Block] :retry_block block that is executed before
+      #   every retry. Request environment, middleware options, current number
+      #   of retries and the exception is passed to the block as parameters.
+      # @option options [Array] :retry_statuses Array of Integer HTTP status
+      #   codes or a single Integer value that determines whether to raise
+      #   a Faraday::RetriableResponse exception based on the HTTP status code
+      #   of an HTTP response.
+      def initialize(app, options = nil)
+        super(app)
+        @options = Options.from(options)
+        @errmatch = build_exception_matcher(@options.exceptions)
+      end
+
+      def calculate_sleep_amount(retries, env)
+        retry_after = calculate_retry_after(env)
+        retry_interval = calculate_retry_interval(retries)
+
+        return if retry_after && retry_after > @options.max_interval
+
+        if retry_after && retry_after >= retry_interval
+          retry_after
+        else
+          retry_interval
+        end
+      end
+
+      # @param env [Faraday::Env]
+      def call(env)
+        retries = @options.max
+        request_body = env[:body]
+        begin
+          # after failure env[:body] is set to the response body
+          env[:body] = request_body
+          @app.call(env).tap do |resp|
+            raise Faraday::RetriableResponse.new(nil, resp) if @options.retry_statuses.include?(resp.status)
+          end
+        rescue @errmatch => e
+          if retries.positive? && retry_request?(env, e)
+            retries -= 1
+            rewind_files(request_body)
+            if (sleep_amount = calculate_sleep_amount(retries + 1, env))
+              @options.retry_block.call(env, @options, retries, e)
+              sleep sleep_amount
+              retry
+            end
+          end
+
+          raise unless e.is_a?(Faraday::RetriableResponse)
+
+          e.response
+        end
+      end
+
+      # An exception matcher for the rescue clause can usually be any object
+      # that responds to `===`, but for Ruby 1.8 it has to be a Class or Module.
+      #
+      # @param exceptions [Array]
+      # @api private
+      # @return [Module] an exception matcher
+      def build_exception_matcher(exceptions)
+        matcher = Module.new
+        (
+          class << matcher
+            self
+          end).class_eval do
+          define_method(:===) do |error|
+            exceptions.any? do |ex|
+              if ex.is_a? Module
+                error.is_a? ex
+              else
+                Object.const_defined?(ex.to_s) && error.is_a?(Object.const_get(ex.to_s))
+              end
+            end
+          end
+        end
+        matcher
+      end
+
+      private
+
+      def retry_request?(env, exception)
+        @options.methods.include?(env[:method]) ||
+          @options.retry_if.call(env, exception)
+      end
+
+      def rewind_files(body)
+        return unless body.is_a?(Hash)
+
+        body.each do |_, value|
+          value.rewind if value.is_a?(UploadIO)
+        end
+      end
+
+      # MDN spec for Retry-After header:
+      # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+      def calculate_retry_after(env)
+        response_headers = env[:response_headers]
+        return unless response_headers
+
+        retry_after_value = env[:response_headers]['Retry-After']
+
+        # Try to parse date from the header value
+        begin
+          datetime = DateTime.rfc2822(retry_after_value)
+          datetime.to_time - Time.now.utc
+        rescue ArgumentError
+          retry_after_value.to_f
+        end
+      end
+
+      def calculate_retry_interval(retries)
+        retry_index = @options.max - retries
+        current_interval = @options.interval *
+                           (@options.backoff_factor**retry_index)
+        current_interval = [current_interval, @options.max_interval].min
+        random_interval = rand * @options.interval_randomness.to_f *
+                          @options.interval
+
+        current_interval + random_interval
+      end
+    end
+  end
+end

data/lib/faraday/retry/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Faraday
+  module Retry
+    VERSION = '1.0.0'
+  end
+end

data/lib/faraday/retry.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require_relative 'retriable_response'
+require_relative 'retry/middleware'
+require_relative 'retry/version'
+
+module Faraday
+  # Middleware main module.
+  module Retry
+    Faraday::Request.register_middleware(retry: Faraday::Retry::Middleware)
+  end
+end

metadata

@@ -0,0 +1,187 @@
+--- !ruby/object:Gem::Specification
+name: faraday-retry
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mattia Giuffrida
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0.alpha.pre.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0.alpha.pre.4
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-packaging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Catches exceptions and retries each request a limited number of times.
+
+  '
+email:
+- giuffrida.mattia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/faraday/retriable_response.rb
+- lib/faraday/retry.rb
+- lib/faraday/retry/middleware.rb
+- lib/faraday/retry/version.rb
+homepage: https://github.com/lostisland/faraday-retry
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/lostisland/faraday-retry/issues
+  changelog_uri: https://github.com/lostisland/faraday-retry/blob/v1.0.0/CHANGELOG.md
+  documentation_uri: http://www.rubydoc.info/gems/faraday-retry/1.0.0
+  homepage_uri: https://github.com/lostisland/faraday-retry
+  source_code_uri: https://github.com/lostisland/faraday-retry
+  wiki_uri: https://github.com/lostisland/faraday-retry/wiki
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Catches exceptions and retries each request a limited number of times
+test_files: []