faraday 0.17.6 → 1.0.0.pre.rc1

data/lib/faraday/dependency_loader.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Faraday
+  # DependencyLoader helps Faraday adapters and middleware load dependencies.
+  module DependencyLoader
+    attr_reader :load_error
+
+    # Executes a block which should try to require and reference dependent
+    # libraries
+    def dependency(lib = nil)
+      lib ? require(lib) : yield
+    rescue LoadError, NameError => e
+      self.load_error = e
+    end
+
+    def new(*)
+      unless loaded?
+        raise "missing dependency for #{self}: #{load_error.message}"
+      end
+
+      super
+    end
+
+    def loaded?
+      load_error.nil?
+    end
+
+    def inherited(subclass)
+      super
+      subclass.send(:load_error=, load_error)
+    end
+
+    private
+
+    attr_writer :load_error
+  end
+end

data/lib/faraday/encoders/flat_params_encoder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Faraday
+  # FlatParamsEncoder manages URI params as a flat hash. Any Array values repeat
+  # the parameter multiple times.
+  module FlatParamsEncoder
+    class << self
+      extend Forwardable
+      def_delegators :'Faraday::Utils', :escape, :unescape
+    end
+
+    # Encode converts the given param into a URI querystring. Keys and values
+    # will converted to strings and appropriately escaped for the URI.
+    #
+    # @param params [Hash] query arguments to convert.
+    #
+    # @example
+    #
+    #   encode({a: %w[one two three], b: true, c: "C"})
+    #   # => 'a=one&a=two&a=three&b=true&c=C'
+    #
+    # @return [String] the URI querystring (without the leading '?')
+    def self.encode(params)
+      return nil if params.nil?
+
+      unless params.is_a?(Array)
+        unless params.respond_to?(:to_hash)
+          raise TypeError,
+                "Can't convert #{params.class} into Hash."
+        end
+        params = params.to_hash
+        params = params.map do |key, value|
+          key = key.to_s if key.is_a?(Symbol)
+          [key, value]
+        end
+        # Useful default for OAuth and caching.
+        # Only to be used for non-Array inputs. Arrays should preserve order.
+        params.sort!
+      end
+
+      # The params have form [['key1', 'value1'], ['key2', 'value2']].
+      buffer = +''
+      params.each do |key, value|
+        encoded_key = escape(key)
+        if value.nil?
+          buffer << "#{encoded_key}&"
+        elsif value.is_a?(Array)
+          value.each do |sub_value|
+            encoded_value = escape(sub_value)
+            buffer << "#{encoded_key}=#{encoded_value}&"
+          end
+        else
+          encoded_value = escape(value)
+          buffer << "#{encoded_key}=#{encoded_value}&"
+        end
+      end
+      buffer.chop
+    end
+
+    # Decode converts the given URI querystring into a hash.
+    #
+    # @param query [String] query arguments to parse.
+    #
+    # @example
+    #
+    #   decode('a=one&a=two&a=three&b=true&c=C')
+    #   # => {"a"=>["one", "two", "three"], "b"=>"true", "c"=>"C"}
+    #
+    # @return [Hash] parsed keys and value strings from the querystring.
+    def self.decode(query)
+      return nil if query.nil?
+
+      empty_accumulator = {}
+
+      split_query = (query.split('&').map do |pair|
+        pair.split('=', 2) if pair && !pair.empty?
+      end).compact
+      split_query.each_with_object(empty_accumulator.dup) do |pair, accu|
+        pair[0] = unescape(pair[0])
+        pair[1] = true if pair[1].nil?
+        if pair[1].respond_to?(:to_str)
+          pair[1] = unescape(pair[1].to_str.tr('+', ' '))
+        end
+        if accu[pair[0]].is_a?(Array)
+          accu[pair[0]] << pair[1]
+        elsif accu[pair[0]]
+          accu[pair[0]] = [accu[pair[0]], pair[1]]
+        else
+          accu[pair[0]] = pair[1]
+        end
+      end
+    end
+  end
+end

data/lib/faraday/encoders/nested_params_encoder.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Faraday
+  # Sub-module for encoding parameters into query-string.
+  module EncodeMethods
+    # @param params [nil, Array, #to_hash] parameters to be encoded
+    #
+    # @return [String] the encoded params
+    #
+    # @raise [TypeError] if params can not be converted to a Hash
+    def encode(params)
+      return nil if params.nil?
+
+      unless params.is_a?(Array)
+        unless params.respond_to?(:to_hash)
+          raise TypeError, "Can't convert #{params.class} into Hash."
+        end
+
+        params = params.to_hash
+        params = params.map do |key, value|
+          key = key.to_s if key.is_a?(Symbol)
+          [key, value]
+        end
+        # Useful default for OAuth and caching.
+        # Only to be used for non-Array inputs. Arrays should preserve order.
+        params.sort!
+      end
+
+      # The params have form [['key1', 'value1'], ['key2', 'value2']].
+      buffer = +''
+      params.each do |parent, value|
+        encoded_parent = escape(parent)
+        buffer << "#{encode_pair(encoded_parent, value)}&"
+      end
+      buffer.chop
+    end
+
+    protected
+
+    def encode_pair(parent, value)
+      if value.is_a?(Hash)
+        encode_hash(parent, value)
+      elsif value.is_a?(Array)
+        encode_array(parent, value)
+      elsif value.nil?
+        parent
+      else
+        encoded_value = escape(value)
+        "#{parent}=#{encoded_value}"
+      end
+    end
+
+    def encode_hash(parent, value)
+      value = value.map { |key, val| [escape(key), val] }.sort
+
+      buffer = +''
+      value.each do |key, val|
+        new_parent = "#{parent}%5B#{key}%5D"
+        buffer << "#{encode_pair(new_parent, val)}&"
+      end
+      buffer.chop
+    end
+
+    def encode_array(parent, value)
+      new_parent = "#{parent}%5B%5D"
+      return new_parent if value.empty?
+
+      buffer = +''
+      value.each { |val| buffer << "#{encode_pair(new_parent, val)}&" }
+      buffer.chop
+    end
+  end
+
+  # Sub-module for decoding query-string into parameters.
+  module DecodeMethods
+    # @param query [nil, String]
+    #
+    # @return [Array<Array, String>] the decoded params
+    #
+    # @raise [TypeError] if the nesting is incorrect
+    def decode(query)
+      return nil if query.nil?
+
+      params = {}
+      query.split('&').each do |pair|
+        next if pair.empty?
+
+        key, value = pair.split('=', 2)
+        key = unescape(key)
+        value = unescape(value.tr('+', ' ')) if value
+        decode_pair(key, value, params)
+      end
+
+      dehash(params, 0)
+    end
+
+    protected
+
+    SUBKEYS_REGEX = /[^\[\]]+(?:\]?\[\])?/.freeze
+
+    def decode_pair(key, value, context)
+      subkeys = key.scan(SUBKEYS_REGEX)
+      subkeys.each_with_index do |subkey, i|
+        is_array = subkey =~ /[\[\]]+\Z/
+        subkey = $` if is_array
+        last_subkey = i == subkeys.length - 1
+
+        context = prepare_context(context, subkey, is_array, last_subkey)
+        add_to_context(is_array, context, value, subkey) if last_subkey
+      end
+    end
+
+    def prepare_context(context, subkey, is_array, last_subkey)
+      if !last_subkey || is_array
+        context = new_context(subkey, is_array, context)
+      end
+      if context.is_a?(Array) && !is_array
+        context = match_context(context, subkey)
+      end
+      context
+    end
+
+    def new_context(subkey, is_array, context)
+      value_type = is_array ? Array : Hash
+      if context[subkey] && !context[subkey].is_a?(value_type)
+        raise TypeError, "expected #{value_type.name} " \
+          "(got #{context[subkey].class.name}) for param `#{subkey}'"
+      end
+
+      context[subkey] ||= value_type.new
+    end
+
+    def match_context(context, subkey)
+      context << {} if !context.last.is_a?(Hash) || context.last.key?(subkey)
+      context.last
+    end
+
+    def add_to_context(is_array, context, value, subkey)
+      is_array ? context << value : context[subkey] = value
+    end
+
+    # Internal: convert a nested hash with purely numeric keys into an array.
+    # FIXME: this is not compatible with Rack::Utils.parse_nested_query
+    # @!visibility private
+    def dehash(hash, depth)
+      hash.each do |key, value|
+        hash[key] = dehash(value, depth + 1) if value.is_a?(Hash)
+      end
+
+      if depth.positive? && !hash.empty? && hash.keys.all? { |k| k =~ /^\d+$/ }
+        hash.sort.map(&:last)
+      else
+        hash
+      end
+    end
+  end
+
+  # This is the default encoder for Faraday requests.
+  # Using this encoder, parameters will be encoded respecting their structure,
+  # so you can send objects such as Arrays or Hashes as parameters
+  # for your requests.
+  module NestedParamsEncoder
+    class << self
+      extend Forwardable
+      def_delegators :'Faraday::Utils', :escape, :unescape
+    end
+
+    extend EncodeMethods
+    extend DecodeMethods
+  end
+end

data/lib/faraday/error.rb

@@ -1,17 +1,23 @@
 # frozen_string_literal: true
 
-require 'faraday/deprecate'
-
-# Faraday namespace.
 module Faraday
   # Faraday error base class.
   class Error < StandardError
     attr_reader :response, :wrapped_exception
 
     def initialize(exc, response = nil)
-      @wrapped_exception = nil unless defined?(@wrapped_exception)
-      @response = nil unless defined?(@response)
-      super(exc_msg_and_response!(exc, response))
+      @wrapped_exception = nil
+      @response = response
+
+      if exc.respond_to?(:backtrace)
+        super(exc.message)
+        @wrapped_exception = exc
+      elsif exc.respond_to?(:each_key)
+        super("the server responded with status #{exc[:status]}")
+        @response = exc
+      else
+        super(exc.to_s)
+      end
     end
 
     def backtrace
@@ -23,44 +29,12 @@ module Faraday
     end
 
     def inspect
-      inner = ''
-      inner += " wrapped=#{@wrapped_exception.inspect}" if @wrapped_exception
-      inner += " response=#{@response.inspect}" if @response
-      inner += " #{super}" if inner.empty?
+      inner = +''
+      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.
@@ -100,59 +74,27 @@ module Faraday
   end
 
   # A unified client error for timeouts.
-  class TimeoutError < ClientError
+  class TimeoutError < ServerError
     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
+  class ConnectionFailed < Error
   end
 
   # A unified client error for SSL errors.
-  class SSLError < ClientError
+  class SSLError < Error
   end
 
   # Raised by FaradayMiddleware::ResponseMiddleware
-  class ParsingError < ClientError
+  class ParsingError < Error
   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))
-    )
+  class RetriableResponse < Error
   end
 end

data/lib/faraday/logging/formatter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'pp'
+module Faraday
+  module Logging
+    # Serves as an integration point to customize logging
+    class Formatter
+      extend Forwardable
+
+      DEFAULT_OPTIONS = { headers: true, bodies: false }.freeze
+
+      def initialize(logger:, options:)
+        @logger = logger
+        @filter = []
+        @options = DEFAULT_OPTIONS.merge(options)
+      end
+
+      def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+      def request(env)
+        info('request') do
+          "#{env.method.upcase} #{apply_filters(env.url.to_s)}"
+        end
+        if log_headers?(:request)
+          debug('request') { apply_filters(dump_headers(env.request_headers)) }
+        end
+        return unless env[:body] && log_body?(:request)
+
+        debug('request') { apply_filters(dump_body(env[:body])) }
+      end
+
+      def response(env)
+        info('response') { "Status #{env.status}" }
+        if log_headers?(:response)
+          debug('response') do
+            apply_filters(dump_headers(env.response_headers))
+          end
+        end
+        return unless env[:body] && log_body?(:response)
+
+        debug('response') { apply_filters(dump_body(env[:body])) }
+      end
+
+      def filter(filter_word, filter_replacement)
+        @filter.push([filter_word, filter_replacement])
+      end
+
+      private
+
+      def dump_headers(headers)
+        headers.map { |k, v| "#{k}: #{v.inspect}" }.join("\n")
+      end
+
+      def dump_body(body)
+        if body.respond_to?(:to_str)
+          body.to_str
+        else
+          pretty_inspect(body)
+        end
+      end
+
+      def pretty_inspect(body)
+        body.pretty_inspect
+      end
+
+      def log_headers?(type)
+        case @options[:headers]
+        when Hash
+          @options[:headers][type]
+        else
+          @options[:headers]
+        end
+      end
+
+      def log_body?(type)
+        case @options[:bodies]
+        when Hash
+          @options[:bodies][type]
+        else
+          @options[:bodies]
+        end
+      end
+
+      def apply_filters(output)
+        @filter.each do |pattern, replacement|
+          output = output.to_s.gsub(pattern, replacement)
+        end
+        output
+      end
+    end
+  end
+end

data/lib/faraday/middleware.rb

@@ -1,34 +1,10 @@
+# frozen_string_literal: true
+
 module Faraday
+  # Middleware is the basic base class of any Faraday middleware.
   class Middleware
     extend MiddlewareRegistry
-
-    class << self
-      attr_accessor :load_error
-      private :load_error=
-    end
-
-    self.load_error = nil
-
-    # Executes a block which should try to require and reference dependent libraries
-    def self.dependency(lib = nil)
-      lib ? require(lib) : yield
-    rescue LoadError, NameError => error
-      self.load_error = error
-    end
-
-    def self.new(*)
-      raise "missing dependency for #{self}: #{load_error.message}" unless loaded?
-      super
-    end
-
-    def self.loaded?
-      load_error.nil?
-    end
-
-    def self.inherited(subclass)
-      super
-      subclass.send(:load_error=, self.load_error)
-    end
+    extend DependencyLoader
 
     def initialize(app = nil)
       @app = app

data/lib/faraday/middleware_registry.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Faraday
+  # Adds the ability for other modules to register and lookup
+  # middleware classes.
+  module MiddlewareRegistry
+    # Register middleware class(es) on the current module.
+    #
+    # @param autoload_path [String] Middleware autoload path
+    # @param mapping [Hash{
+    #          Symbol => Module,
+    #          Symbol => Array<Module, Symbol, String>,
+    #        }] Middleware mapping from a lookup symbol to a reference to the
+    #        middleware.
+    #        Classes can be expressed as:
+    #          - a fully qualified constant
+    #          - a Symbol
+    #          - a Proc that will be lazily called to return the former
+    #          - an array is given, its first element is the constant or symbol,
+    #            and its second is a file to `require`.
+    # @return [void]
+    #
+    # @example Lookup by a constant
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
+    #       register_middleware foo: Foo
+    #     end
+    #   end
+    #
+    # @example Lookup by a symbol
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :bar returns
+    #       # Faraday::Whatever.const_get(:Bar)
+    #       register_middleware bar: :Bar
+    #     end
+    #   end
+    #
+    # @example Lookup by a symbol and string in an array
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :baz requires 'baz' and returns
+    #       # Faraday::Whatever.const_get(:Baz)
+    #       register_middleware baz: [:Baz, 'baz']
+    #     end
+    #   end
+    #
+    def register_middleware(autoload_path = nil, mapping = nil)
+      if mapping.nil?
+        mapping = autoload_path
+        autoload_path = nil
+      end
+      middleware_mutex do
+        @middleware_autoload_path = autoload_path if autoload_path
+        (@registered_middleware ||= {}).update(mapping)
+      end
+    end
+
+    # Unregister a previously registered middleware class.
+    #
+    # @param key [Symbol] key for the registered middleware.
+    def unregister_middleware(key)
+      @registered_middleware.delete(key)
+    end
+
+    # Lookup middleware class with a registered Symbol shortcut.
+    #
+    # @param key [Symbol] key for the registered middleware.
+    # @return [Class] a middleware Class.
+    # @raise [Faraday::Error] if given key is not registered
+    #
+    # @example
+    #
+    #   module Faraday
+    #     class Whatever
+    #       register_middleware foo: Foo
+    #     end
+    #   end
+    #
+    #   Faraday::Whatever.lookup_middleware(:foo)
+    #   # => Faraday::Whatever::Foo
+    #
+    def lookup_middleware(key)
+      load_middleware(key) ||
+        raise(Faraday::Error, "#{key.inspect} is not registered on #{self}")
+    end
+
+    def middleware_mutex(&block)
+      @middleware_mutex ||= Monitor.new
+      @middleware_mutex.synchronize(&block)
+    end
+
+    def fetch_middleware(key)
+      defined?(@registered_middleware) && @registered_middleware[key]
+    end
+
+    def load_middleware(key)
+      value = fetch_middleware(key)
+      case value
+      when Module
+        value
+      when Symbol, String
+        middleware_mutex do
+          @registered_middleware[key] = const_get(value)
+        end
+      when Proc
+        middleware_mutex do
+          @registered_middleware[key] = value.call
+        end
+      when Array
+        middleware_mutex do
+          const, path = value
+          if (root = @middleware_autoload_path)
+            path = "#{root}/#{path}"
+          end
+          require(path)
+          @registered_middleware[key] = const
+        end
+        load_middleware(key)
+      end
+    end
+  end
+end