faraday 0.15.2 → 0.16.0

data/lib/faraday/request/retry.rb

@@ -1,211 +1,239 @@
+# frozen_string_literal: true
+
 module Faraday
-  # Catches exceptions and retries each request a limited number of times.
-  #
-  # 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.
-  #
-  # Examples
-  #
-  #   Faraday.new do |conn|
-  #     conn.request :retry, max: 2, interval: 0.05,
-  #                          interval_randomness: 0.5, backoff_factor: 2,
-  #                          exceptions: [CustomException, 'Timeout::Error']
-  #     conn.adapter ...
-  #   end
-  #
-  # 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.15
-  #
-  class Request::Retry < Faraday::Middleware
-
-    IDEMPOTENT_METHODS = [:delete, :get, :head, :options, :put]
-
-    class Options < Faraday::Options.new(:max, :interval, :max_interval, :interval_randomness,
-                                         :backoff_factor, :exceptions, :methods, :retry_if, :retry_block,
-                                         :retry_statuses)
-
-      DEFAULT_CHECK = lambda { |env,exception| false }
-
-      def self.from(value)
-        if Integer === value
-          new(value)
-        else
-          super(value)
+  class Request
+    # Catches exceptions and retries each request a limited number of times.
+    #
+    # 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.
+    #
+    # @example Configure Retry middleware using intervals
+    #   Faraday.new do |conn|
+    #     conn.request(:retry, max: 2,
+    #                          interval: 0.05,
+    #                          interval_randomness: 0.5,
+    #                          backoff_factor: 2,
+    #                          exceptions: [CustomException, 'Timeout::Error'])
+    #
+    #     conn.adapter(:net_http) # NB: Last middleware must be the adapter
+    #   end
+    #
+    # 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.15.
+    class Retry < 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
-      end
 
-      def max
-        (self[:max] ||= 2).to_i
-      end
+        def max
+          (self[:max] ||= 2).to_i
+        end
 
-      def interval
-        (self[:interval] ||= 0).to_f
-      end
+        def interval
+          (self[:interval] ||= 0).to_f
+        end
 
-      def max_interval
-        (self[:max_interval] ||= Float::MAX).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 interval_randomness
+          (self[:interval_randomness] ||= 0).to_f
+        end
 
-      def backoff_factor
-        (self[:backoff_factor] ||= 1).to_f
-      end
+        def backoff_factor
+          (self[:backoff_factor] ||= 1).to_f
+        end
 
-      def exceptions
-        Array(self[:exceptions] ||= [Errno::ETIMEDOUT, 'Timeout::Error',
-                                     Error::TimeoutError,
-                                     Faraday::Error::RetriableResponse])
-      end
+        def exceptions
+          Array(self[:exceptions] ||= DEFAULT_EXCEPTIONS)
+        end
 
-      def methods
-        Array(self[:methods] ||= IDEMPOTENT_METHODS)
-      end
+        def methods
+          Array(self[:methods] ||= IDEMPOTENT_METHODS)
+        end
 
-      def retry_if
-        self[:retry_if] ||= DEFAULT_CHECK
-      end
+        def retry_if
+          self[:retry_if] ||= DEFAULT_CHECK
+        end
 
-      def retry_block
-        self[:retry_block] ||= Proc.new {}
-      end
+        def retry_block
+          self[:retry_block] ||= proc {}
+        end
 
-      def retry_statuses
-        Array(self[:retry_statuses] ||= [])
+        def retry_statuses
+          Array(self[:retry_statuses] ||= [])
+        end
       end
-    end
 
-    # Public: Initialize middleware
-    #
-    # Options:
-    # max                 - Maximum number of retries (default: 2)
-    # interval            - Pause in seconds between retries (default: 0)
-    # interval_randomness - The maximum random interval amount expressed
-    #                       as a float between 0 and 1 to use in addition to the
-    #                       interval. (default: 0)
-    # max_interval        - An upper limit for the interval (default: Float::MAX)
-    # backoff_factor      - The amount to multiple each successive retry's
-    #                       interval amount by in order to provide backoff
-    #                       (default: 1)
-    # exceptions          - The list of exceptions to handle. Exceptions can be
-    #                       given as Class, Module, or String. (default:
-    #                       [Errno::ETIMEDOUT, 'Timeout::Error',
-    #                       Error::TimeoutError, Faraday::Error::RetriableResponse])
-    # methods             - A list of HTTP methods to retry without calling retry_if.  Pass
-    #                       an empty Array to call retry_if for all exceptions.
-    #                       (defaults to the idempotent HTTP methods in IDEMPOTENT_METHODS)
-    # retry_if            - 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.
-    #                       (defaults to return false)
-    # retry_block         - block that is executed after every retry. Request environment, middleware options,
-    #                       current number of retries and the exception is passed to the block as parameters.
-    def initialize(app, options = nil)
-      super(app)
-      @options = Options.from(options)
-      @errmatch = build_exception_matcher(@options.exceptions)
-    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 after
+      #   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)
+      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
+        return if retry_after && retry_after > @options.max_interval
 
-      retry_after && retry_after >= retry_interval ? retry_after : retry_interval
-    end
+        if retry_after && retry_after >= retry_interval
+          retry_after
+        else
+          retry_interval
+        end
+      end
 
-    def call(env)
-      retries = @options.max
-      request_body = env[:body]
-      begin
-        env[:body] = request_body # after failure env[:body] is set to the response body
-        @app.call(env).tap do |resp|
-          raise Faraday::Error::RetriableResponse.new(nil, resp) if @options.retry_statuses.include?(resp.status)
-        end
-      rescue @errmatch => exception
-        if retries > 0 && retry_request?(env, exception)
-          retries -= 1
-          rewind_files(request_body)
-          @options.retry_block.call(env, @options, retries, exception)
-          if (sleep_amount = calculate_sleep_amount(retries + 1, env))
-            sleep sleep_amount
-            retry
+      # @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|
+            if @options.retry_statuses.include?(resp.status)
+              raise Faraday::RetriableResponse.new(nil, resp)
+            end
+          end
+        rescue @errmatch => e
+          if retries.positive? && retry_request?(env, e)
+            retries -= 1
+            rewind_files(request_body)
+            @options.retry_block.call(env, @options, retries, e)
+            if (sleep_amount = calculate_sleep_amount(retries + 1, env))
+              sleep sleep_amount
+              retry
+            end
           end
-        end
 
-        if exception.is_a?(Faraday::Error::RetriableResponse)
-          exception.response
-        else
-          raise
+          raise unless e.is_a?(Faraday::RetriableResponse)
+
+          e.response
         end
       end
-    end
 
-    # Private: construct an exception matcher object.
-    #
-    # 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.
-    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
-              error.class.to_s == ex.to_s
+      # 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
+                error.class.to_s == ex.to_s
+              end
             end
           end
         end
+        matcher
       end
-      matcher
-    end
 
-    private
+      private
 
-    def retry_request?(env, exception)
-      @options.methods.include?(env[:method]) || @options.retry_if.call(env, exception)
-    end
+      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)
 
-    def rewind_files(body)
-      return unless body.is_a?(Hash)
-      body.each do |_, value|
-        if value.is_a? UploadIO
-          value.rewind
+        body.each do |_, value|
+          value.rewind if value.is_a?(UploadIO)
         end
       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
+      # 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"]
+        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
+        # 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
-    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
+      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
+        current_interval + random_interval
+      end
     end
   end
 end

data/lib/faraday/request/token_authentication.rb

@@ -1,15 +1,20 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Request::TokenAuthentication < Request.load_middleware(:authorization)
-    # Public
-    def self.header(token, options = nil)
-      options ||= {}
-      options[:token] = token
-      super(:Token, options)
-    end
+  class Request
+    # TokenAuthentication is a middleware that adds a 'Token' header to a
+    # Faraday request.
+    class TokenAuthentication < load_middleware(:authorization)
+      # Public
+      def self.header(token, options = nil)
+        options ||= {}
+        options[:token] = token
+        super(:Token, options)
+      end
 
-    def initialize(app, token, options = nil)
-      super(app, token, options)
+      def initialize(app, token, options = nil)
+        super(app, token, options)
+      end
     end
   end
 end
-

data/lib/faraday/request/url_encoded.rb

@@ -1,36 +1,54 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Request::UrlEncoded < Faraday::Middleware
-    CONTENT_TYPE = 'Content-Type'.freeze unless defined? CONTENT_TYPE
+  class Request
+    # Middleware for supporting urlencoded requests.
+    class UrlEncoded < Faraday::Middleware
+      CONTENT_TYPE = 'Content-Type' unless defined? CONTENT_TYPE
 
-    class << self
-      attr_accessor :mime_type
-    end
-    self.mime_type = 'application/x-www-form-urlencoded'.freeze
+      class << self
+        attr_accessor :mime_type
+      end
+      self.mime_type = 'application/x-www-form-urlencoded'
 
-    def call(env)
-      match_content_type(env) do |data|
-        params = Faraday::Utils::ParamsHash[data]
-        env.body = params.to_query(env.params_encoder)
+      # Encodes as "application/x-www-form-urlencoded" if not already encoded or
+      # of another type.
+      #
+      # @param env [Faraday::Env]
+      def call(env)
+        match_content_type(env) do |data|
+          params = Faraday::Utils::ParamsHash[data]
+          env.body = params.to_query(env.params_encoder)
+        end
+        @app.call env
       end
-      @app.call env
-    end
 
-    def match_content_type(env)
-      if process_request?(env)
+      # @param env [Faraday::Env]
+      # @yield [request_body] Body of the request
+      def match_content_type(env)
+        return unless process_request?(env)
+
         env.request_headers[CONTENT_TYPE] ||= self.class.mime_type
         yield(env.body) unless env.body.respond_to?(:to_str)
       end
-    end
 
-    def process_request?(env)
-      type = request_type(env)
-      env.body and (type.empty? or type == self.class.mime_type)
-    end
+      # @param env [Faraday::Env]
+      #
+      # @return [Boolean] True if the request has a body and its Content-Type is
+      #                   urlencoded.
+      def process_request?(env)
+        type = request_type(env)
+        env.body && (type.empty? || (type == self.class.mime_type))
+      end
 
-    def request_type(env)
-      type = env.request_headers[CONTENT_TYPE].to_s
-      type = type.split(';', 2).first if type.index(';')
-      type
+      # @param env [Faraday::Env]
+      #
+      # @return [String]
+      def request_type(env)
+        type = env.request_headers[CONTENT_TYPE].to_s
+        type = type.split(';', 2).first if type.index(';')
+        type
+      end
     end
   end
 end