faraday 0.12.0 → 1.4.3

data/lib/faraday/request/retry.rb

@@ -1,163 +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)
-      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.125.
+    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])
-      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 methods
-        Array(self[:methods] ||= IDEMPOTENT_METHODS)
+        def retry_block
+          self[:retry_block] ||= proc {}
+        end
+
+        def retry_statuses
+          Array(self[:retry_statuses] ||= [])
+        end
       end
 
-      def retry_if
-        self[:retry_if] ||= DEFAULT_CHECK
+      # @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
 
-    end
+      def calculate_sleep_amount(retries, env)
+        retry_after = calculate_retry_after(env)
+        retry_interval = calculate_retry_interval(retries)
 
-    # 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])
-    # 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)
-    def initialize(app, options = nil)
-      super(app)
-      @options = Options.from(options)
-      @errmatch = build_exception_matcher(@options.exceptions)
-    end
+        return if retry_after && retry_after > @options.max_interval
 
-    def sleep_amount(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
+        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|
+            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
 
-    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)
-      rescue @errmatch => exception
-        if retries > 0 && retry_request?(env, exception)
-          retries -= 1
-          rewind_files(request_body)
-          sleep sleep_amount(retries + 1)
-          retry
-        end
-        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(env)
-      env && env.each do |_, value|
-        if value.is_a? UploadIO
-          value.rewind
+      def rewind_files(body)
+        return unless body.is_a?(Hash)
+
+        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
+
+        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/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,56 @@
+# 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
+      unless defined?(::Faraday::Request::UrlEncoded::CONTENT_TYPE)
+        CONTENT_TYPE = 'Content-Type'
+      end
 
-    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

data/lib/faraday/request.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module Faraday
-  # Used to setup urls, params, headers, and the request body in a sane manner.
+  # Used to setup URLs, params, headers, and the request body in a sane manner.
   #
+  # @example
   #   @connection.post do |req|
   #     req.url 'http://localhost', 'a' => '1' # 'http://localhost?a=1'
   #     req.headers['b'] = '2' # Header
@@ -9,25 +12,63 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
-  class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
+  # @!attribute http_method
+  #   @return [Symbol] the HTTP method of the Request
+  # @!attribute path
+  #   @return [URI, String] the path
+  # @!attribute params
+  #   @return [Hash] query parameters
+  # @!attribute headers
+  #   @return [Faraday::Utils::Headers] headers
+  # @!attribute body
+  #   @return [Hash] body
+  # @!attribute options
+  #   @return [RequestOptions] options
+  #
+  # rubocop:disable Style/StructInheritance
+  class Request < Struct.new(
+    :http_method, :path, :params, :headers, :body, :options
+  )
+    # rubocop:enable Style/StructInheritance
+
     extend MiddlewareRegistry
 
-    register_middleware File.expand_path('../request', __FILE__),
-      :url_encoded => [:UrlEncoded, 'url_encoded'],
-      :multipart => [:Multipart, 'multipart'],
-      :retry => [:Retry, 'retry'],
-      :authorization => [:Authorization, 'authorization'],
-      :basic_auth => [:BasicAuthentication, 'basic_authentication'],
-      :token_auth => [:TokenAuthentication, 'token_authentication'],
-      :instrumentation => [:Instrumentation, 'instrumentation']
+    register_middleware File.expand_path('request', __dir__),
+                        url_encoded: [:UrlEncoded, 'url_encoded'],
+                        multipart: [:Multipart, 'multipart'],
+                        retry: [:Retry, 'retry'],
+                        authorization: [:Authorization, 'authorization'],
+                        basic_auth: [
+                          :BasicAuthentication,
+                          'basic_authentication'
+                        ],
+                        token_auth: [
+                          :TokenAuthentication,
+                          'token_authentication'
+                        ],
+                        instrumentation: [:Instrumentation, 'instrumentation']
 
+    # @param request_method [String]
+    # @yield [request] for block customization, if block given
+    # @yieldparam request [Request]
+    # @return [Request]
     def self.create(request_method)
       new(request_method).tap do |request|
         yield(request) if block_given?
       end
     end
 
-    # Public: Replace params, preserving the existing hash type
+    def method
+      warn <<~TEXT
+        WARNING: `Faraday::Request##{__method__}` is deprecated; use `#http_method` instead. It will be removed in or after version 2.0.
+        `Faraday::Request##{__method__}` called from #{caller_locations(1..1).first}
+      TEXT
+      http_method
+    end
+
+    # Replace params, preserving the existing hash type.
+    #
+    # @param hash [Hash] new params
     def params=(hash)
       if params
         params.replace hash
@@ -36,7 +77,9 @@ module Faraday
       end
     end
 
-    # Public: Replace request headers, preserving the existing hash type
+    # Replace request headers, preserving the existing hash type.
+    #
+    # @param hash [Hash] new headers
     def headers=(hash)
       if headers
         headers.replace hash
@@ -45,9 +88,14 @@ module Faraday
       end
     end
 
+    # Update path and params.
+    #
+    # @param path [URI, String]
+    # @param params [Hash, nil]
+    # @return [void]
     def url(path, params = nil)
       if path.respond_to? :query
-        if query = path.query
+        if (query = path.query)
           path = path.dup
           path.query = nil
         end
@@ -61,34 +109,48 @@ module Faraday
       self.params.update(params) if params
     end
 
+    # @param key [Object] key to look up in headers
+    # @return [Object] value of the given header name
     def [](key)
       headers[key]
     end
 
+    # @param key [Object] key of header to write
+    # @param value [Object] value of header
     def []=(key, value)
       headers[key] = value
     end
 
-    # ENV Keys
-    # :method - a symbolized request method (:get, :post)
-    # :body   - the request body that will eventually be converted to a string.
-    # :url    - URI instance for the current request.
-    # :status           - HTTP response status code
-    # :request_headers  - hash of HTTP Headers to be sent to the server
-    # :response_headers - Hash of HTTP headers from the server
-    # :parallel_manager - sent if the connection is in parallel mode
-    # :request - Hash of options for configuring the request.
-    #   :timeout      - open/read timeout Integer in seconds
-    #   :open_timeout - read timeout Integer in seconds
-    #   :proxy        - Hash of proxy options
-    #     :uri        - Proxy Server URI
-    #     :user       - Proxy server username
-    #     :password   - Proxy server password
-    # :ssl - Hash of options for configuring SSL requests.
+    # Marshal serialization support.
+    #
+    # @return [Hash] the hash ready to be serialized in Marshal.
+    def marshal_dump
+      {
+        http_method: http_method,
+        body: body,
+        headers: headers,
+        path: path,
+        params: params,
+        options: options
+      }
+    end
+
+    # Marshal serialization support.
+    # Restores the instance variables according to the +serialised+.
+    # @param serialised [Hash] the serialised object.
+    def marshal_load(serialised)
+      self.http_method = serialised[:http_method]
+      self.body        = serialised[:body]
+      self.headers     = serialised[:headers]
+      self.path        = serialised[:path]
+      self.params      = serialised[:params]
+      self.options     = serialised[:options]
+    end
+
+    # @return [Env] the Env for this Request
     def to_env(connection)
-      Env.new(method, body, connection.build_exclusive_url(path, params),
-        options, headers, connection.ssl, connection.parallel_manager)
+      Env.new(http_method, body, connection.build_exclusive_url(path, params),
+              options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end
-