faraday 0.15.4 → 0.16.0

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,21 +1,22 @@
-module Faraday
-  class Error < StandardError; end
+# frozen_string_literal: true
 
-  class ClientError < Error
+module Faraday
+  # Faraday error base class.
+  class Error < StandardError
     attr_reader :response, :wrapped_exception
 
-    def initialize(ex, response = nil)
+    def initialize(exc, 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
+      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(ex.to_s)
+        super(exc.to_s)
       end
     end
 
@@ -28,39 +29,72 @@ 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
   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")
-    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
+
+  # Raised by Faraday::Response::RaiseError in case of a 403 response.
+  class ForbiddenError < ClientError
   end
 
-  class SSLError < ClientError
+  # Raised by Faraday::Response::RaiseError in case of a 404 response.
+  class ResourceNotFound < ClientError
   end
 
-  class RetriableResponse < 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
 
-  [:ClientError, :ConnectionFailed, :ResourceNotFound,
-   :ParsingError, :TimeoutError, :SSLError, :RetriableResponse].each do |const|
-    Error.const_set(const, Faraday.const_get(const))
+  # A unified client error for timeouts.
+  class TimeoutError < ServerError
+    def initialize(exc = 'timeout', response = nil)
+      super(exc, response)
+    end
+  end
+
+  # A unified error for failed connections.
+  class ConnectionFailed < Error
   end
 
+  # 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