faraday 0.14.0 → 0.17.6

data/lib/faraday/adapter/patron.rb

@@ -8,7 +8,8 @@ module Faraday
         # TODO: support streaming requests
         env[:body] = env[:body].read if env[:body].respond_to? :read
 
-        session = @session ||= create_session
+        session = ::Patron::Session.new
+        @config_block.call(session) if @config_block
         configure_ssl(session, env[:ssl]) if env[:url].scheme == 'https' and env[:ssl]
 
         if req = env[:request]
@@ -27,7 +28,7 @@ module Faraday
           data = env[:body] ? env[:body].to_s : nil
           session.request(env[:method], env[:url].to_s, env[:request_headers], :data => data)
         rescue Errno::ECONNREFUSED, ::Patron::ConnectionFailed
-          raise Error::ConnectionFailed, $!
+          raise Faraday::ConnectionFailed, $!
         end
 
         # Remove the "HTTP/1.1 200", leaving just the reason phrase
@@ -38,15 +39,15 @@ module Faraday
         @app.call env
       rescue ::Patron::TimeoutError => err
         if connection_timed_out_message?(err.message)
-          raise Faraday::Error::ConnectionFailed, err
+          raise Faraday::ConnectionFailed, err
         else
-          raise Faraday::Error::TimeoutError, err
+          raise Faraday::TimeoutError, err
         end
       rescue ::Patron::Error => err
         if err.message.include?("code 407")
-          raise Error::ConnectionFailed, %{407 "Proxy Authentication Required "}
+          raise Faraday::ConnectionFailed, %{407 "Proxy Authentication Required "}
         else
-          raise Error::ConnectionFailed, err
+          raise Faraday::ConnectionFailed, err
         end
       end
 
@@ -65,12 +66,6 @@ module Faraday
         end
       end
 
-      def create_session
-        session = ::Patron::Session.new
-        @config_block.call(session) if @config_block
-        session
-      end
-
       def configure_ssl(session, ssl)
         if ssl.fetch(:verify, true)
           session.cacert = ssl[:ca_file]

data/lib/faraday/adapter/rack.rb

@@ -41,7 +41,7 @@ module Faraday
 
         timeout  = env[:request][:timeout] || env[:request][:open_timeout]
         response = if timeout
-          Timer.timeout(timeout, Faraday::Error::TimeoutError) { execute_request(env, rack_env) }
+          Timer.timeout(timeout, Faraday::TimeoutError) { execute_request(env, rack_env) }
         else
           execute_request(env, rack_env)
         end

data/lib/faraday/adapter.rb

@@ -40,6 +40,8 @@ module Faraday
       env.clear_body if env.needs_body?
     end
 
+    private
+
     def save_response(env, status, body, headers = nil, reason_phrase = nil)
       env.status = status
       env.body = body

data/lib/faraday/deprecate.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Faraday
+  # @param new_klass [Class] new Klass to use
+  #
+  # @return [Class] A modified version of new_klass that warns on
+  #   usage about deprecation.
+  # @see Faraday::Deprecate
+  module DeprecatedClass
+    def self.proxy_class(origclass, ver = '1.0')
+      proxy = Class.new(origclass) do
+        const_set("ORIG_CLASS", origclass)
+
+        class << self
+          extend Faraday::Deprecate
+
+          def ===(other)
+            (superclass == const_get("ORIG_CLASS") && other.is_a?(superclass)) || super
+          end
+        end
+      end
+      proxy.singleton_class.send(:deprecate, :new, "#{origclass}.new", ver)
+      proxy.singleton_class.send(:deprecate, :inherited, origclass.name, ver)
+      proxy
+    end
+  end
+
+  # Deprecation using semver instead of date, based on Gem::Deprecate
+  # Provides a single method +deprecate+ to be used to declare when
+  # something is going away.
+  #
+  #     class Legacy
+  #       def self.klass_method
+  #         # ...
+  #       end
+  #
+  #       def instance_method
+  #         # ...
+  #       end
+  #
+  #       extend Faraday::Deprecate
+  #       deprecate :instance_method, "X.z", '1.0'
+  #
+  #       class << self
+  #         extend Faraday::Deprecate
+  #         deprecate :klass_method, :none, '1.0'
+  #       end
+  #     end
+  module Deprecate
+    def self.skip # :nodoc:
+      @skip ||= begin
+        case ENV['FARADAY_DEPRECATE'].to_s.downcase
+        when '1', 'warn' then :warn
+        else :skip
+        end
+      end
+      @skip == :skip
+    end
+
+    def self.skip=(value) # :nodoc:
+      @skip = value ? :skip : :warn
+    end
+
+    # Temporarily turn off warnings. Intended for tests only.
+    def skip_during
+      original = Faraday::Deprecate.skip
+      Faraday::Deprecate.skip, = true
+      yield
+    ensure
+      Faraday::Deprecate.skip = original
+    end
+
+    # Simple deprecation method that deprecates +name+ by wrapping it up
+    # in a dummy method. It warns on each call to the dummy method
+    # telling the user of +repl+ (unless +repl+ is :none) and the
+    # semver that it is planned to go away.
+    # @param name [Symbol] the method symbol to deprecate
+    # @param repl [#to_s, :none] the replacement to use, when `:none` it will
+    #   alert the user that no replacemtent is present.
+    # @param ver [String] the semver the method will be removed.
+    def deprecate(name, repl, ver)
+      class_eval do
+        gem_ver = Gem::Version.new(ver)
+        old = "_deprecated_#{name}"
+        alias_method old, name
+        define_method name do |*args, &block|
+          mod = is_a? Module
+          target = mod ? "#{self}." : "#{self.class}#"
+          target_message = if name == :inherited
+                             "Inheriting #{self}"
+                           else
+                             "#{target}#{name}"
+                           end
+
+          msg = [
+            "NOTE: #{target_message} is deprecated",
+            repl == :none ? ' with no replacement' : "; use #{repl} instead. ",
+            "It will be removed in or after version #{gem_ver}",
+            "\n#{target}#{name} called from #{Gem.location_of_caller.join(':')}"
+          ]
+          warn "#{msg.join}." unless Faraday::Deprecate.skip
+          send old, *args, &block
+        end
+      end
+    end
+
+    module_function :deprecate, :skip_during
+  end
+end

data/lib/faraday/error.rb

@@ -1,23 +1,17 @@
-module Faraday
-  class Error < StandardError; end
-  class MissingDependency < Error; end
+# frozen_string_literal: true
 
-  class ClientError < Error
-    attr_reader :response, :wrapped_exception
+require 'faraday/deprecate'
 
-    def initialize(ex, response = nil)
-      @wrapped_exception = nil
-      @response = response
+# Faraday namespace.
+module Faraday
+  # Faraday error base class.
+  class Error < StandardError
+    attr_reader :response, :wrapped_exception
 
-      if ex.respond_to?(:backtrace)
-        super(ex.message)
-        @wrapped_exception = ex
-      elsif ex.respond_to?(:each_key)
-        super("the server responded with status #{ex[:status]}")
-        @response = ex
-      else
-        super(ex.to_s)
-      end
+    def initialize(exc, response = nil)
+      @wrapped_exception = nil unless defined?(@wrapped_exception)
+      @response = nil unless defined?(@response)
+      super(exc_msg_and_response!(exc, response))
     end
 
     def backtrace
@@ -30,34 +24,135 @@ module Faraday
 
     def inspect
       inner = ''
-      if @wrapped_exception
-        inner << " wrapped=#{@wrapped_exception.inspect}"
-      end
-      if @response
-        inner << " response=#{@response.inspect}"
-      end
-      if inner.empty?
-        inner << " #{super}"
-      end
+      inner += " wrapped=#{@wrapped_exception.inspect}" if @wrapped_exception
+      inner += " response=#{@response.inspect}" if @response
+      inner += " #{super}" if inner.empty?
       %(#<#{self.class}#{inner}>)
     end
+
+    protected
+
+    # Pulls out potential parent exception and response hash, storing them in
+    # instance variables.
+    # exc      - Either an Exception, a string message, or a response hash.
+    # response - Hash
+    #              :status  - Optional integer HTTP response status
+    #              :headers - String key/value hash of HTTP response header
+    #                         values.
+    #              :body    - Optional string HTTP response body.
+    #
+    # If a subclass has to call this, then it should pass a string message
+    # to `super`. See NilStatusError.
+    def exc_msg_and_response!(exc, response = nil)
+      if @response.nil? && @wrapped_exception.nil?
+        @wrapped_exception, msg, @response = exc_msg_and_response(exc, response)
+        return msg
+      end
+
+      exc.to_s
+    end
+
+    # Pulls out potential parent exception and response hash.
+    def exc_msg_and_response(exc, response = nil)
+      return [exc, exc.message, response] if exc.respond_to?(:backtrace)
+
+      return [nil, "the server responded with status #{exc[:status]}", exc] \
+        if exc.respond_to?(:each_key)
+
+      [nil, exc.to_s, response]
+    end
+  end
+
+  # Faraday client error class. Represents 4xx status responses.
+  class ClientError < Error
+  end
+
+  # Raised by Faraday::Response::RaiseError in case of a 400 response.
+  class BadRequestError < ClientError
+  end
+
+  # Raised by Faraday::Response::RaiseError in case of a 401 response.
+  class UnauthorizedError < ClientError
   end
 
-  class ConnectionFailed < ClientError;   end
-  class ResourceNotFound < ClientError;   end
-  class ParsingError     < ClientError;   end
+  # Raised by Faraday::Response::RaiseError in case of a 403 response.
+  class ForbiddenError < ClientError
+  end
+
+  # Raised by Faraday::Response::RaiseError in case of a 404 response.
+  class ResourceNotFound < ClientError
+  end
+
+  # Raised by Faraday::Response::RaiseError in case of a 407 response.
+  class ProxyAuthError < ClientError
+  end
+
+  # Raised by Faraday::Response::RaiseError in case of a 409 response.
+  class ConflictError < ClientError
+  end
 
+  # Raised by Faraday::Response::RaiseError in case of a 422 response.
+  class UnprocessableEntityError < ClientError
+  end
+
+  # Faraday server error class. Represents 5xx status responses.
+  class ServerError < Error
+  end
+
+  # A unified client error for timeouts.
   class TimeoutError < ClientError
-    def initialize(ex = nil)
-      super(ex || "timeout")
+    def initialize(exc = 'timeout', response = nil)
+      super(exc, response)
     end
   end
 
+  # Raised by Faraday::Response::RaiseError in case of a nil status in response.
+  class NilStatusError < ServerError
+    def initialize(exc, response = nil)
+      exc_msg_and_response!(exc, response)
+      @response = unwrap_resp!(@response)
+      super('http status could not be derived from the server response')
+    end
+
+    private
+
+    extend Faraday::Deprecate
+
+    def unwrap_resp(resp)
+      if inner = (resp.keys.size == 1 && resp[:response])
+        return unwrap_resp(inner)
+      end
+
+      resp
+    end
+
+    alias_method :unwrap_resp!, :unwrap_resp
+    deprecate('unwrap_resp', nil, '1.0')
+  end
+
+  # A unified error for failed connections.
+  class ConnectionFailed < ClientError
+  end
+
+  # A unified client error for SSL errors.
   class SSLError < ClientError
   end
 
-  [:MissingDependency, :ClientError, :ConnectionFailed, :ResourceNotFound,
-   :ParsingError, :TimeoutError, :SSLError].each do |const|
-    Error.const_set(const, Faraday.const_get(const))
+  # Raised by FaradayMiddleware::ResponseMiddleware
+  class ParsingError < ClientError
+  end
+
+  # Exception used to control the Retry middleware.
+  #
+  # @see Faraday::Request::Retry
+  class RetriableResponse < ClientError
+  end
+
+  [:ClientError, :ConnectionFailed, :ResourceNotFound,
+    :ParsingError, :TimeoutError, :SSLError, :RetriableResponse].each do |const|
+    Error.const_set(
+      const,
+      DeprecatedClass.proxy_class(Faraday.const_get(const))
+    )
   end
 end

data/lib/faraday/options.rb

@@ -72,7 +72,7 @@ module Faraday
         if args.size > 0
           send(key_setter, args.first)
         elsif block_given?
-          send(key_setter, Proc.new.call(key))
+          send(key_setter, yield(key))
         else
           raise self.class.fetch_error_class, "key not found: #{key.inspect}"
         end
@@ -162,8 +162,8 @@ module Faraday
       @attribute_options ||= {}
     end
 
-    def self.memoized(key)
-      memoized_attributes[key.to_sym] = Proc.new
+    def self.memoized(key, &block)
+      memoized_attributes[key.to_sym] = block
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{key}() self[:#{key}]; end
       RUBY
@@ -202,7 +202,7 @@ module Faraday
   end
 
   class RequestOptions < Options.new(:params_encoder, :proxy, :bind,
-    :timeout, :open_timeout, :boundary, :oauth, :context)
+    :timeout, :open_timeout, :write_timeout, :boundary, :oauth, :context)
 
     def []=(key, value)
       if key && key.to_sym == :proxy
@@ -214,7 +214,8 @@ module Faraday
   end
 
   class SSLOptions < Options.new(:verify, :ca_file, :ca_path, :verify_mode,
-    :cert_store, :client_cert, :client_key, :certificate, :private_key, :verify_depth, :version)
+    :cert_store, :client_cert, :client_key, :certificate, :private_key, :verify_depth,
+    :version, :min_version, :max_version)
 
     def verify?
       verify != false

data/lib/faraday/parameters.rb

@@ -40,9 +40,10 @@ module Faraday
           end
           return buffer.chop
         elsif value.is_a?(Array)
+          new_parent = "#{parent}%5B%5D"
+          return new_parent if value.empty?
           buffer = ""
           value.each_with_index do |val, i|
-            new_parent = "#{parent}%5B%5D"
             buffer << "#{to_query.call(new_parent, val)}&"
           end
           return buffer.chop

data/lib/faraday/rack_builder.rb

@@ -49,10 +49,10 @@ module Faraday
       end
     end
 
-    def initialize(handlers = [])
+    def initialize(handlers = [], &block)
       @handlers = handlers
       if block_given?
-        build(&Proc.new)
+        build(&block)
       elsif @handlers.empty?
         # default stack, if nothing else is configured
         self.request :url_encoded

data/lib/faraday/request/retry.rb

@@ -1,3 +1,5 @@
+require 'date'
+
 module Faraday
   # Catches exceptions and retries each request a limited number of times.
   #
@@ -19,11 +21,15 @@ module Faraday
   # interval that is random between 0.1 and 0.15
   #
   class Request::Retry < Faraday::Middleware
-
+    DEFAULT_EXCEPTIONS = [Errno::ETIMEDOUT, 'Timeout::Error',
+                          Faraday::TimeoutError, Faraday::RetriableResponse
+                         ].freeze
     IDEMPOTENT_METHODS = [:delete, :get, :head, :options, :put]
 
     class Options < Faraday::Options.new(:max, :interval, :max_interval, :interval_randomness,
-                                         :backoff_factor, :exceptions, :methods, :retry_if)
+                                         :backoff_factor, :exceptions, :methods, :retry_if, :retry_block,
+                                         :retry_statuses)
+
       DEFAULT_CHECK = lambda { |env,exception| false }
 
       def self.from(value)
@@ -55,8 +61,7 @@ module Faraday
       end
 
       def exceptions
-        Array(self[:exceptions] ||= [Errno::ETIMEDOUT, 'Timeout::Error',
-                                     Error::TimeoutError])
+        Array(self[:exceptions] ||= DEFAULT_EXCEPTIONS)
       end
 
       def methods
@@ -67,6 +72,13 @@ module Faraday
         self[:retry_if] ||= DEFAULT_CHECK
       end
 
+      def retry_block
+        self[:retry_block] ||= Proc.new {}
+      end
+
+      def retry_statuses
+        Array(self[:retry_statuses] ||= [])
+      end
     end
 
     # Public: Initialize middleware
@@ -83,8 +95,8 @@ module Faraday
     #                       (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])
+    #                       [Errno::ETIMEDOUT, 'Timeout::Error',
+    #                       Faraday::TimeoutError, Faraday::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)
@@ -94,18 +106,21 @@ module Faraday
     #                       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
 
-    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
+    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
+
+      retry_after && retry_after >= retry_interval ? retry_after : retry_interval
     end
 
     def call(env)
@@ -113,15 +128,25 @@ module Faraday
       request_body = env[:body]
       begin
         env[:body] = request_body # after failure env[:body] is set to the response body
-        @app.call(env)
+        @app.call(env).tap do |resp|
+          raise Faraday::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)
-          sleep sleep_amount(retries + 1)
-          retry
+          @options.retry_block.call(env, @options, retries, exception)
+          if (sleep_amount = calculate_sleep_amount(retries + 1, env))
+            sleep sleep_amount
+            retry
+          end
+        end
+
+        if exception.is_a?(Faraday::RetriableResponse)
+          exception.response
+        else
+          raise
         end
-        raise
       end
     end
 
@@ -160,5 +185,29 @@ module Faraday
       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

data/lib/faraday/request.rb

@@ -12,6 +12,8 @@ module Faraday
   class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
     extend MiddlewareRegistry
 
+    alias_method :http_method, :method
+
     register_middleware File.expand_path('../request', __FILE__),
       :url_encoded => [:UrlEncoded, 'url_encoded'],
       :multipart => [:Multipart, 'multipart'],
@@ -69,6 +71,26 @@ module Faraday
       headers[key] = value
     end
 
+    def marshal_dump
+      {
+        :method  => method,
+        :body    => body,
+        :headers => headers,
+        :path    => path,
+        :params  => params,
+        :options => options
+      }
+    end
+
+    def marshal_load(serialised)
+      self.method  = serialised[:method]
+      self.body    = serialised[:body]
+      self.headers = serialised[:headers]
+      self.path    = serialised[:path]
+      self.params  = serialised[:params]
+      self.options = serialised[:options]
+    end
+
     # ENV Keys
     # :method - a symbolized request method (:get, :post)
     # :body   - the request body that will eventually be converted to a string.

data/lib/faraday/response/logger.rb

@@ -10,7 +10,7 @@ module Faraday
       super(app)
       @logger = logger || begin
         require 'logger'
-        ::Logger.new(STDOUT)
+        ::Logger.new($stdout)
       end
       @filter = []
       @options = DEFAULT_OPTIONS.merge(options)
@@ -20,14 +20,14 @@ module Faraday
     def_delegators :@logger, :debug, :info, :warn, :error, :fatal
 
     def call(env)
-      info "#{env.method} #{apply_filters(env.url.to_s)}"
+      info('request')  { "#{env.method.upcase} #{apply_filters(env.url.to_s)}" }
       debug('request') { apply_filters( dump_headers env.request_headers ) } if log_headers?(:request)
       debug('request') { apply_filters( dump_body(env[:body]) ) } if env[:body] && log_body?(:request)
       super
     end
 
     def on_complete(env)
-      info('Status') { env.status.to_s }
+      info('response')  { "Status #{env.status.to_s}" }
       debug('response') { apply_filters( dump_headers env.response_headers ) } if log_headers?(:response)
       debug('response') { apply_filters( dump_body env[:body] ) } if env[:body] && log_body?(:response)
     end

data/lib/faraday/response/raise_error.rb

@@ -5,12 +5,16 @@ module Faraday
     def on_complete(env)
       case env[:status]
       when 404
-        raise Faraday::Error::ResourceNotFound, response_values(env)
+        raise Faraday::ResourceNotFound, response_values(env)
       when 407
         # mimic the behavior that we get with proxy requests with HTTPS
-        raise Faraday::Error::ConnectionFailed, %{407 "Proxy Authentication Required "}
+        raise Faraday::ConnectionFailed.new(
+                %{407 "Proxy Authentication Required "},
+                response_values(env))
       when ClientErrorStatuses
-        raise Faraday::Error::ClientError, response_values(env)
+        raise Faraday::ClientError, response_values(env)
+      when nil
+        raise Faraday::NilStatusError, response_values(env)
       end
     end
 

data/lib/faraday/response.rb

@@ -54,9 +54,9 @@ module Faraday
       !!env
     end
 
-    def on_complete
-      if not finished?
-        @on_complete_callbacks << Proc.new
+    def on_complete(&block)
+      if !finished?
+        @on_complete_callbacks << block
       else
         yield(env)
       end