faraday 0.17.5 → 2.3.0

data/lib/faraday/encoders/flat_params_encoder.rb

@@ -0,0 +1,105 @@
+# 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
+
+        # Only to be used for non-Array inputs. Arrays should preserve order.
+        params.sort! if @sort_params
+      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)
+          if value.empty?
+            buffer << "#{encoded_key}=&"
+          else
+            value.each do |sub_value|
+              encoded_value = escape(sub_value)
+              buffer << "#{encoded_key}=#{encoded_value}&"
+            end
+          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
+
+    class << self
+      attr_accessor :sort_params
+    end
+
+    # Useful default for OAuth and caching.
+    @sort_params = true
+  end
+end

data/lib/faraday/encoders/nested_params_encoder.rb

@@ -0,0 +1,183 @@
+# 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
+
+        # Only to be used for non-Array inputs. Arrays should preserve order.
+        params.sort! if @sort_params
+      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)
+      return "#{parent}%5B%5D" if value.empty?
+
+      buffer = +''
+      value.each_with_index do |val, index|
+        new_parent = if @array_indices
+                       "#{parent}%5B#{index}%5D"
+                     else
+                       "#{parent}%5B%5D"
+                     end
+        buffer << "#{encode_pair(new_parent, val)}&"
+      end
+      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 = Regexp.last_match.pre_match 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
+      attr_accessor :sort_params, :array_indices
+
+      extend Forwardable
+      def_delegators :'Faraday::Utils', :escape, :unescape
+    end
+
+    # Useful default for OAuth and caching.
+    @sort_params = true
+    @array_indices = false
+
+    extend EncodeMethods
+    extend DecodeMethods
+  end
+end

data/lib/faraday/error.rb

@@ -1,14 +1,12 @@
 # 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)
+    def initialize(exc = nil, response = nil)
       @wrapped_exception = nil unless defined?(@wrapped_exception)
       @response = nil unless defined?(@response)
       super(exc_msg_and_response!(exc, response))
@@ -23,13 +21,25 @@ 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
 
+    def response_status
+      @response[:status] if @response
+    end
+
+    def response_headers
+      @response[:headers] if @response
+    end
+
+    def response_body
+      @response[:body] if @response
+    end
+
     protected
 
     # Pulls out potential parent exception and response hash, storing them in
@@ -40,6 +50,15 @@ module Faraday
     #              :headers - String key/value hash of HTTP response header
     #                         values.
     #              :body    - Optional string HTTP response body.
+    #              :request - Hash
+    #                           :method   - Symbol with the request HTTP method.
+    #                           :url      - URI object with the url requested.
+    #                           :url_path - String with the url path requested.
+    #                           :params   - String key/value hash of query params
+    #                                     present in the request.
+    #                           :headers  - String key/value hash of HTTP request
+    #                                     header values.
+    #                           :body     - String HTTP request body.
     #
     # If a subclass has to call this, then it should pass a string message
     # to `super`. See NilStatusError.
@@ -100,7 +119,7 @@ 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
@@ -110,49 +129,19 @@ module Faraday
   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
-  end
-
-  # Raised by FaradayMiddleware::ResponseMiddleware
-  class ParsingError < ClientError
-  end
-
-  # Exception used to control the Retry middleware.
-  #
-  # @see Faraday::Request::Retry
-  class RetriableResponse < ClientError
+  class SSLError < Error
   end
 
-  [:ClientError, :ConnectionFailed, :ResourceNotFound,
-    :ParsingError, :TimeoutError, :SSLError, :RetriableResponse].each do |const|
-    Error.const_set(
-      const,
-      DeprecatedClass.proxy_class(Faraday.const_get(const))
-    )
+  # Raised by middlewares that parse the response, like the JSON response middleware.
+  class ParsingError < Error
   end
 end

data/lib/faraday/logging/formatter.rb

@@ -0,0 +1,106 @@
+# 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,
+                          log_level: :info }.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)
+        request_log = proc do
+          "#{env.method.upcase} #{apply_filters(env.url.to_s)}"
+        end
+        public_send(log_level, 'request', &request_log)
+
+        log_headers('request', env.request_headers) if log_headers?(:request)
+        log_body('request', env[:body]) if env[:body] && log_body?(:request)
+      end
+
+      def response(env)
+        status = proc { "Status #{env.status}" }
+        public_send(log_level, 'response', &status)
+
+        log_headers('response', env.response_headers) if log_headers?(:response)
+        log_body('response', env[:body]) if env[:body] && log_body?(:response)
+      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
+
+      def log_level
+        unless %i[debug info warn error fatal].include?(@options[:log_level])
+          return :info
+        end
+
+        @options[:log_level]
+      end
+
+      def log_headers(type, headers)
+        headers_log = proc { apply_filters(dump_headers(headers)) }
+        public_send(log_level, type, &headers_log)
+      end
+
+      def log_body(type, body)
+        body_log = proc { apply_filters(dump_body(body)) }
+        public_send(log_level, type, &body_log)
+      end
+    end
+  end
+end

data/lib/faraday/methods.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Faraday
+  METHODS_WITH_QUERY = %w[get head delete trace].freeze
+  METHODS_WITH_BODY = %w[post put patch].freeze
+end

data/lib/faraday/middleware.rb

@@ -1,37 +1,30 @@
+# 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
+    attr_reader :app, :options
 
-    def self.new(*)
-      raise "missing dependency for #{self}: #{load_error.message}" unless loaded?
-      super
-    end
-
-    def self.loaded?
-      load_error.nil?
+    def initialize(app = nil, options = {})
+      @app = app
+      @options = options
     end
 
-    def self.inherited(subclass)
-      super
-      subclass.send(:load_error=, self.load_error)
+    def call(env)
+      on_request(env) if respond_to?(:on_request)
+      app.call(env).on_complete do |environment|
+        on_complete(environment) if respond_to?(:on_complete)
+      end
     end
 
-    def initialize(app = nil)
-      @app = app
+    def close
+      if app.respond_to?(:close)
+        app.close
+      else
+        warn "#{app} does not implement \#close!"
+      end
     end
   end
 end

data/lib/faraday/middleware_registry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Faraday
+  # Adds the ability for other modules to register and lookup
+  # middleware classes.
+  module MiddlewareRegistry
+    def registered_middleware
+      @registered_middleware ||= {}
+    end
+
+    # Register middleware class(es) on the current module.
+    #
+    # @param mappings [Hash] Middleware mappings from a lookup symbol to a middleware class.
+    # @return [void]
+    #
+    # @example Lookup by a constant
+    #
+    #   module Faraday
+    #     class Whatever < Middleware
+    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
+    #       register_middleware(foo: Whatever)
+    #     end
+    #   end
+    def register_middleware(**mappings)
+      middleware_mutex do
+        registered_middleware.update(mappings)
+      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 < Middleware
+    #       register_middleware(foo: Whatever)
+    #     end
+    #   end
+    #
+    #   Faraday::Middleware.lookup_middleware(:foo)
+    #   # => Faraday::Whatever
+    def lookup_middleware(key)
+      load_middleware(key) ||
+        raise(Faraday::Error, "#{key.inspect} is not registered on #{self}")
+    end
+
+    private
+
+    def middleware_mutex(&block)
+      @middleware_mutex ||= Monitor.new
+      @middleware_mutex.synchronize(&block)
+    end
+
+    def load_middleware(key)
+      value = registered_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
+      end
+    end
+  end
+end

data/lib/faraday/options/connection_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Faraday
+  # ConnectionOptions contains the configurable properties for a Faraday
+  # connection object.
+  class ConnectionOptions < Options.new(:request, :proxy, :ssl, :builder, :url,
+                                        :parallel_manager, :params, :headers,
+                                        :builder_class)
+
+    options request: RequestOptions, ssl: SSLOptions
+
+    memoized(:request) { self.class.options_for(:request).new }
+
+    memoized(:ssl) { self.class.options_for(:ssl).new }
+
+    memoized(:builder_class) { RackBuilder }
+
+    def new_builder(block)
+      builder_class.new(&block)
+    end
+  end
+end