faraday 0.15.4 → 1.0.1

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,98 @@
+# 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)
+          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
+  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,22 +1,15 @@
-module Faraday
-  class Error < StandardError; end
+# frozen_string_literal: true
 
-  class ClientError < Error
+# Faraday namespace.
+module Faraday
+  # Faraday error base class.
+  class Error < StandardError
     attr_reader :response, :wrapped_exception
 
-    def initialize(ex, response = nil)
-      @wrapped_exception = nil
-      @response = response
-
-      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
@@ -28,39 +21,112 @@ module Faraday
     end
 
     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 = +''
+      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
 
-  class ConnectionFailed < ClientError;   end
-  class ResourceNotFound < ClientError;   end
-  class ParsingError     < ClientError;   end
+  # Faraday client error class. Represents 4xx status responses.
+  class ClientError < Error
+  end
 
-  class TimeoutError < ClientError
-    def initialize(ex = nil)
-      super(ex || "timeout")
+  # 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
+
+  # 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 < ServerError
+    def initialize(exc = 'timeout', response = nil)
+      super(exc, response)
     end
   end
 
-  class SSLError < ClientError
+  # 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)
+      super('http status could not be derived from the server response')
+    end
   end
 
-  class RetriableResponse < ClientError; end
+  # A unified error for failed connections.
+  class ConnectionFailed < Error
+  end
 
-  [:ClientError, :ConnectionFailed, :ResourceNotFound,
-   :ParsingError, :TimeoutError, :SSLError, :RetriableResponse].each do |const|
-    Error.const_set(const, Faraday.const_get(const))
+  # A unified client error for SSL errors.
+  class SSLError < Error
   end
 
+  # Raised by FaradayMiddleware::ResponseMiddleware
+  class ParsingError < Error
+  end
 
+  # Exception used to control the Retry middleware.
+  #
+  # @see Faraday::Request::Retry
+  class RetriableResponse < Error
+  end
 end

data/lib/faraday/file_part.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+# multipart-post gem
+require 'composite_io'
+require 'parts'
+
+module Faraday
+  # Multipart value used to POST a binary data from a file or
+  #
+  # @example
+  #   payload = { file: Faraday::FilePart.new("file_name.ext", "content/type") }
+  #   http.post("/upload", payload)
+  #
+
+  # @!method initialize(filename_or_io, content_type, filename = nil, opts = {})
+  #
+  #   @param filename_or_io [String, IO] Either a String filename to a local
+  #     file or an open IO object.
+  #   @param content_type [String] String content type of the file data.
+  #   @param filename [String] Optional String filename, usually to add context
+  #     to a given IO object.
+  #   @param opts [Hash] Optional Hash of String key/value pairs to describethis
+  #     this uploaded file. Expected Header keys include:
+  #     * Content-Transfer-Encoding - Defaults to "binary"
+  #     * Content-Disposition - Defaults to "form-data"
+  #     * Content-Type - Defaults to the content_type argument.
+  #     * Content-ID - Optional.
+  #
+  # @return [Faraday::FilePart]
+  #
+  # @!attribute [r] content_type
+  # The uploaded binary data's content type.
+  #
+  # @return [String]
+  #
+  # @!attribute [r] original_filename
+  # The base filename, taken either from the filename_or_io or filename
+  # arguments in #initialize.
+  #
+  # @return [String]
+  #
+  # @!attribute [r] opts
+  # Extra String key/value pairs to make up the header for this uploaded file.
+  #
+  # @return [Hash]
+  #
+  # @!attribute [r] io
+  # The open IO object for the uploaded file.
+  #
+  # @return [IO]
+  FilePart = ::UploadIO
+
+  # Multipart value used to POST a file.
+  #
+  # @deprecated Use FilePart instead of this class. It behaves identically, with
+  #   a matching name to ParamPart.
+  UploadIO = ::UploadIO
+
+  Parts = ::Parts
+
+  # Similar to, but not compatible with CompositeReadIO provided by the
+  # multipart-post gem.
+  # https://github.com/nicksieger/multipart-post/blob/master/lib/composite_io.rb
+  class CompositeReadIO
+    def initialize(*parts)
+      @parts = parts.flatten
+      @ios = @parts.map(&:to_io)
+      @index = 0
+    end
+
+    # @return [Integer] sum of the lengths of all the parts
+    def length
+      @parts.inject(0) { |sum, part| sum + part.length }
+    end
+
+    # Rewind each of the IOs and reset the index to 0.
+    #
+    # @return [void]
+    def rewind
+      @ios.each(&:rewind)
+      @index = 0
+    end
+
+    # Read from IOs in order until `length` bytes have been received.
+    #
+    # @param length [Integer, nil]
+    # @param outbuf [String, nil]
+    def read(length = nil, outbuf = nil)
+      got_result = false
+      outbuf = outbuf ? (+outbuf).replace('') : +''
+
+      while (io = current_io)
+        if (result = io.read(length))
+          got_result ||= !result.nil?
+          result.force_encoding('BINARY') if result.respond_to?(:force_encoding)
+          outbuf << result
+          length -= result.length if length
+          break if length&.zero?
+        end
+        advance_io
+      end
+      !got_result && length ? nil : outbuf
+    end
+
+    # Close each of the IOs.
+    #
+    # @return [void]
+    def close
+      @ios.each(&:close)
+    end
+
+    def ensure_open_and_readable
+      # Rubinius compatibility
+    end
+
+    private
+
+    def current_io
+      @ios[@index]
+    end
+
+    def advance_io
+      @index += 1
+    end
+  end
+end

data/lib/faraday/logging/formatter.rb

@@ -0,0 +1,105 @@
+# 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