faraday 0.12.2 → 1.3.0

data/lib/faraday/request/authorization.rb

@@ -1,41 +1,55 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Request::Authorization < Faraday::Middleware
-    KEY = "Authorization".freeze unless defined? KEY
+  class Request
+    # Request middleware for the Authorization HTTP header
+    class Authorization < Faraday::Middleware
+      unless defined?(::Faraday::Request::Authorization::KEY)
+        KEY = 'Authorization'
+      end
 
-    # Public
-    def self.header(type, token)
-      case token
-      when String, Symbol
-        "#{type} #{token}"
-      when Hash
-        build_hash(type.to_s, token)
-      else
-        raise ArgumentError, "Can't build an Authorization #{type} header from #{token.inspect}"
+      # @param type [String, Symbol]
+      # @param token [String, Symbol, Hash]
+      # @return [String] a header value
+      def self.header(type, token)
+        case token
+        when String, Symbol
+          "#{type} #{token}"
+        when Hash
+          build_hash(type.to_s, token)
+        else
+          raise ArgumentError,
+                "Can't build an Authorization #{type}" \
+                  "header from #{token.inspect}"
+        end
       end
-    end
 
-    # Internal
-    def self.build_hash(type, hash)
-      comma = ", "
-      values = []
-      hash.each do |key, value|
-        values << "#{key}=#{value.to_s.inspect}"
+      # @param type [String]
+      # @param hash [Hash]
+      # @return [String] type followed by comma-separated key=value pairs
+      # @api private
+      def self.build_hash(type, hash)
+        comma = ', '
+        values = []
+        hash.each do |key, value|
+          values << "#{key}=#{value.to_s.inspect}"
+        end
+        "#{type} #{values * comma}"
       end
-      "#{type} #{values * comma}"
-    end
 
-    def initialize(app, type, token)
-      @header_value = self.class.header(type, token)
-      super(app)
-    end
+      # @param app [#call]
+      # @param type [String, Symbol] Type of Authorization
+      # @param token [String, Symbol, Hash] Token value for the Authorization
+      def initialize(app, type, token)
+        @header_value = self.class.header(type, token)
+        super(app)
+      end
 
-    # Public
-    def call(env)
-      unless env.request_headers[KEY]
-        env.request_headers[KEY] = @header_value
+      # @param env [Faraday::Env]
+      def call(env)
+        env.request_headers[KEY] = @header_value unless env.request_headers[KEY]
+        @app.call(env)
       end
-      @app.call(env)
     end
   end
 end
-

data/lib/faraday/request/basic_authentication.rb

@@ -1,13 +1,20 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Faraday
-  class Request::BasicAuthentication < Request.load_middleware(:authorization)
-    # Public
-    def self.header(login, pass)
-      value = Base64.encode64([login, pass].join(':'))
-      value.gsub!("\n", '')
-      super(:Basic, value)
+  class Request
+    # Authorization middleware for Basic Authentication.
+    class BasicAuthentication < load_middleware(:authorization)
+      # @param login [String]
+      # @param pass [String]
+      #
+      # @return [String] a Basic Authentication header line
+      def self.header(login, pass)
+        value = Base64.encode64([login, pass].join(':'))
+        value.delete!("\n")
+        super(:Basic, value)
+      end
     end
   end
 end
-

data/lib/faraday/request/instrumentation.rb

@@ -1,35 +1,53 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Request::Instrumentation < Faraday::Middleware
-    class Options < Faraday::Options.new(:name, :instrumenter)
-      def name
-        self[:name] ||= 'request.faraday'
-      end
+  class Request
+    # Middleware for instrumenting Requests.
+    class Instrumentation < Faraday::Middleware
+      # Options class used in Request::Instrumentation class.
+      class Options < Faraday::Options.new(:name, :instrumenter)
+        # @return [String]
+        def name
+          self[:name] ||= 'request.faraday'
+        end
 
-      def instrumenter
-        self[:instrumenter] ||= ActiveSupport::Notifications
+        # @return [Class]
+        def instrumenter
+          self[:instrumenter] ||= ActiveSupport::Notifications
+        end
       end
-    end
 
-    # Public: Instruments requests using Active Support.
-    #
-    # Measures time spent only for synchronous requests.
-    #
-    # Examples
-    #
-    #   ActiveSupport::Notifications.subscribe('request.faraday') do |name, starts, ends, _, env|
-    #     url = env[:url]
-    #     http_method = env[:method].to_s.upcase
-    #     duration = ends - starts
-    #     $stderr.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
-    #   end
-    def initialize(app, options = nil)
-      super(app)
-      @name, @instrumenter = Options.from(options).values_at(:name, :instrumenter)
-    end
+      # Instruments requests using Active Support.
+      #
+      # Measures time spent only for synchronous requests.
+      #
+      # @example Using ActiveSupport::Notifications to measure time spent
+      #   for Faraday requests.
+      #   ActiveSupport::Notifications
+      #     .subscribe('request.faraday') do |name, starts, ends, _, env|
+      #     url = env[:url]
+      #     http_method = env[:method].to_s.upcase
+      #     duration = ends - starts
+      #     $stderr.puts '[%s] %s %s (%.3f s)' %
+      #       [url.host, http_method, url.request_uri, duration]
+      #   end
+      # @param app [#call]
+      # @param options [nil, Hash] Options hash
+      # @option options [String] :name ('request.faraday')
+      #   Name of the instrumenter
+      # @option options [Class] :instrumenter (ActiveSupport::Notifications)
+      #   Active Support instrumenter class.
+      def initialize(app, options = nil)
+        super(app)
+        @name, @instrumenter = Options.from(options)
+                                      .values_at(:name, :instrumenter)
+      end
 
-    def call(env)
-      @instrumenter.instrument(@name, env) do
-        @app.call(env)
+      # @param env [Faraday::Env]
+      def call(env)
+        @instrumenter.instrument(@name, env) do
+          @app.call(env)
+        end
       end
     end
   end

data/lib/faraday/request/multipart.rb

@@ -1,66 +1,104 @@
-require File.expand_path("../url_encoded", __FILE__)
+# frozen_string_literal: true
+
+require File.expand_path('url_encoded', __dir__)
 require 'securerandom'
 
 module Faraday
-  class Request::Multipart < Request::UrlEncoded
-    self.mime_type = 'multipart/form-data'.freeze
-    DEFAULT_BOUNDARY_PREFIX = "-----------RubyMultipartPost".freeze unless defined? DEFAULT_BOUNDARY_PREFIX
-
-    def call(env)
-      match_content_type(env) do |params|
-        env.request.boundary ||= unique_boundary
-        env.request_headers[CONTENT_TYPE] += "; boundary=#{env.request.boundary}"
-        env.body = create_multipart(env, params)
+  class Request
+    # Middleware for supporting multi-part requests.
+    class Multipart < UrlEncoded
+      self.mime_type = 'multipart/form-data'
+      unless defined?(::Faraday::Request::Multipart::DEFAULT_BOUNDARY_PREFIX)
+        DEFAULT_BOUNDARY_PREFIX = '-----------RubyMultipartPost'
       end
-      @app.call env
-    end
 
-    def process_request?(env)
-      type = request_type(env)
-      env.body.respond_to?(:each_key) and !env.body.empty? and (
-        (type.empty? and has_multipart?(env.body)) or
-        type == self.class.mime_type
-      )
-    end
+      def initialize(app = nil, options = {})
+        super(app)
+        @options = options
+      end
 
-    def has_multipart?(obj)
-      # string is an enum in 1.8, returning list of itself
-      if obj.respond_to?(:each) && !obj.is_a?(String)
-        (obj.respond_to?(:values) ? obj.values : obj).each do |val|
-          return true if (val.respond_to?(:content_type) || has_multipart?(val))
+      # Checks for files in the payload, otherwise leaves everything untouched.
+      #
+      # @param env [Faraday::Env]
+      def call(env)
+        match_content_type(env) do |params|
+          env.request.boundary ||= unique_boundary
+          env.request_headers[CONTENT_TYPE] +=
+            "; boundary=#{env.request.boundary}"
+          env.body = create_multipart(env, params)
         end
+        @app.call env
       end
-      false
-    end
 
-    def create_multipart(env, params)
-      boundary = env.request.boundary
-      parts = process_params(params) do |key, value|
-        Faraday::Parts::Part.new(boundary, key, value)
+      # @param env [Faraday::Env]
+      def process_request?(env)
+        type = request_type(env)
+        env.body.respond_to?(:each_key) && !env.body.empty? && (
+          (type.empty? && has_multipart?(env.body)) ||
+            (type == self.class.mime_type)
+        )
       end
-      parts << Faraday::Parts::EpiloguePart.new(boundary)
 
-      body = Faraday::CompositeReadIO.new(parts)
-      env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
-      return body
-    end
+      # Returns true if obj is an enumerable with values that are multipart.
+      #
+      # @param obj [Object]
+      # @return [Boolean]
+      def has_multipart?(obj) # rubocop:disable Naming/PredicateName
+        if obj.respond_to?(:each)
+          (obj.respond_to?(:values) ? obj.values : obj).each do |val|
+            return true if val.respond_to?(:content_type) || has_multipart?(val)
+          end
+        end
+        false
+      end
 
-    def unique_boundary
-      "#{DEFAULT_BOUNDARY_PREFIX}-#{SecureRandom.hex}"
-    end
+      # @param env [Faraday::Env]
+      # @param params [Hash]
+      def create_multipart(env, params)
+        boundary = env.request.boundary
+        parts = process_params(params) do |key, value|
+          part(boundary, key, value)
+        end
+        parts << Faraday::Parts::EpiloguePart.new(boundary)
 
-    def process_params(params, prefix = nil, pieces = nil, &block)
-      params.inject(pieces || []) do |all, (key, value)|
-        key = "#{prefix}[#{key}]" if prefix
+        body = Faraday::CompositeReadIO.new(parts)
+        env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
+        body
+      end
 
-        case value
-        when Array
-          values = value.inject([]) { |a,v| a << [nil, v] }
-          process_params(values, key, all, &block)
-        when Hash
-          process_params(value, key, all, &block)
+      def part(boundary, key, value)
+        if value.respond_to?(:to_part)
+          value.to_part(boundary, key)
         else
-          all << block.call(key, value)
+          Faraday::Parts::Part.new(boundary, key, value)
+        end
+      end
+
+      # @return [String]
+      def unique_boundary
+        "#{DEFAULT_BOUNDARY_PREFIX}-#{SecureRandom.hex}"
+      end
+
+      # @param params [Hash]
+      # @param prefix [String]
+      # @param pieces [Array]
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          if prefix
+            key = @options[:flat_encode] ? prefix.to_s : "#{prefix}[#{key}]"
+          end
+
+          case value
+          when Array
+            values = value.inject([]) { |a, v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            # rubocop:disable Performance/RedundantBlockCall
+            all << block.call(key, value)
+            # rubocop:enable Performance/RedundantBlockCall
+          end
         end
       end
     end

data/lib/faraday/request/retry.rb

@@ -1,164 +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(body)
-      return unless body.is_a?(Hash)
-      body.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