rest-client 1.6.14 → 2.0.2

data/lib/restclient/params_array.rb

@@ -0,0 +1,72 @@
+module RestClient
+
+  # The ParamsArray class is used to represent an ordered list of [key, value]
+  # pairs. Use this when you need to include a key multiple times or want
+  # explicit control over parameter ordering.
+  #
+  # Most of the request payload & parameter functions normally accept a Hash of
+  # keys => values, which does not allow for duplicated keys.
+  #
+  # @see RestClient::Utils.encode_query_string
+  # @see RestClient::Utils.flatten_params
+  #
+  class ParamsArray
+    include Enumerable
+
+    # @param array [Array<Array>] An array of parameter key,value pairs. These
+    #   pairs may be 2 element arrays [key, value] or single element hashes
+    #   {key => value}. They may also be single element arrays to represent a
+    #   key with no value.
+    #
+    # @example
+    #   >> ParamsArray.new([[:foo, 123], [:foo, 456], [:bar, 789]])
+    #   This will be encoded as "foo=123&foo=456&bar=789"
+    #
+    # @example
+    #   >> ParamsArray.new({foo: 123, bar: 456})
+    #   This is valid, but there's no reason not to just use the Hash directly
+    #   instead of a ParamsArray.
+    #
+    #
+    def initialize(array)
+      @array = process_input(array)
+    end
+
+    def each(*args, &blk)
+      @array.each(*args, &blk)
+    end
+
+    def empty?
+      @array.empty?
+    end
+
+    private
+
+    def process_input(array)
+      array.map {|v| process_pair(v) }
+    end
+
+    # A pair may be:
+    # - A single element hash, e.g. {foo: 'bar'}
+    # - A two element array, e.g. ['foo', 'bar']
+    # - A one element array, e.g. ['foo']
+    #
+    def process_pair(pair)
+      case pair
+      when Hash
+        if pair.length != 1
+          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
+        end
+        pair.to_a.fetch(0)
+      when Array
+        if pair.length > 2
+          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
+        end
+        [pair.fetch(0), pair[1]]
+      else
+        # recurse, converting any non-array to an array
+        process_pair(pair.to_a)
+      end
+    end
+  end
+end

data/lib/restclient/payload.rb

@@ -1,5 +1,7 @@
 require 'tempfile'
+require 'securerandom'
 require 'stringio'
+
 require 'mime/types'
 
 module RestClient
@@ -23,28 +25,20 @@ module RestClient
     end
 
     def has_file?(params)
-      params.any? do |_, v|
-        case v
-          when Hash
-            has_file?(v)
-          when Array
-            has_file_array?(v)
-          else
-            v.respond_to?(:path) && v.respond_to?(:read)
-        end
+      unless params.is_a?(Hash)
+        raise ArgumentError.new("Must pass Hash, not #{params.inspect}")
       end
+      _has_file?(params)
     end
 
-    def has_file_array?(params)
-      params.any? do |v|
-        case v
-          when Hash
-            has_file?(v)
-          when Array
-            has_file_array?(v)
-          else
-            v.respond_to?(:path) && v.respond_to?(:read)
-        end
+    def _has_file?(obj)
+      case obj
+      when Hash, ParamsArray
+        obj.any? {|_, v| _has_file?(v) }
+      when Array
+        obj.any? {|v| _has_file?(v) }
+      else
+        obj.respond_to?(:path) && obj.respond_to?(:read)
       end
     end
 
@@ -58,40 +52,13 @@ module RestClient
         @stream.seek(0)
       end
 
-      def read(bytes=nil)
-        @stream.read(bytes)
-      end
-
-      alias :to_s :read
-
-      # Flatten parameters by converting hashes of hashes to flat hashes
-      # {keys1 => {keys2 => value}} will be transformed into [keys1[key2], value]
-      def flatten_params(params, parent_key = nil)
-        result = []
-        params.each do |key, value|
-          calculated_key = parent_key ? "#{parent_key}[#{handle_key(key)}]" : handle_key(key)
-          if value.is_a? Hash
-            result += flatten_params(value, calculated_key)
-          elsif value.is_a? Array
-            result += flatten_params_array(value, calculated_key)
-          else
-            result << [calculated_key, value]
-          end
-        end
-        result
+      def read(*args)
+        @stream.read(*args)
       end
 
-      def flatten_params_array value, calculated_key
-        result = []
-        value.each do |elem|
-          if elem.is_a? Hash
-            result += flatten_params(elem, calculated_key)
-          elsif elem.is_a? Array
-            result += flatten_params_array(elem, calculated_key)
-          else
-            result << ["#{calculated_key}[]", elem]
-          end
-        end
+      def to_s
+        result = read
+        @stream.seek(0)
         result
       end
 
@@ -109,14 +76,12 @@ module RestClient
         @stream.close unless @stream.closed?
       end
 
-      def inspect
-        result = to_s.inspect
-        @stream.seek(0)
-        result
+      def to_s_inspect
+        to_s.inspect
       end
 
       def short_inspect
-        (size > 500 ? "#{size} byte(s) length" : inspect)
+        (size > 500 ? "#{size} byte(s) length" : to_s_inspect)
       end
 
     end
@@ -139,39 +104,28 @@ module RestClient
 
     class UrlEncoded < Base
       def build_stream(params = nil)
-        @stream = StringIO.new(flatten_params(params).collect do |entry|
-          "#{entry[0]}=#{handle_key(entry[1])}"
-        end.join("&"))
+        @stream = StringIO.new(Utils.encode_query_string(params))
         @stream.seek(0)
       end
 
-      # for UrlEncoded escape the keys
-      def handle_key key
-        parser.escape(key.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
-      end
-
       def headers
         super.merge({'Content-Type' => 'application/x-www-form-urlencoded'})
       end
-
-      private
-        def parser
-          URI.const_defined?(:Parser) ? URI::Parser.new : URI
-        end
     end
 
     class Multipart < Base
       EOL = "\r\n"
 
       def build_stream(params)
-        b = "--#{boundary}"
+        b = '--' + boundary
 
         @stream = Tempfile.new("RESTClient.Stream.#{rand(1000)}")
         @stream.binmode
         @stream.write(b + EOL)
 
-        if params.is_a? Hash
-          x = flatten_params(params)
+        case params
+        when Hash, ParamsArray
+          x = Utils.flatten_params(params)
         else
           x = params
         end
@@ -206,7 +160,7 @@ module RestClient
           s.write(" filename=\"#{v.respond_to?(:original_filename) ? v.original_filename : File.basename(v.path)}\"#{EOL}")
           s.write("Content-Type: #{v.respond_to?(:content_type) ? v.content_type : mime_for(v.path)}#{EOL}")
           s.write(EOL)
-          while data = v.read(8124)
+          while (data = v.read(8124))
             s.write(data)
           end
         ensure
@@ -220,10 +174,25 @@ module RestClient
       end
 
       def boundary
-        @boundary ||= rand(1_000_000).to_s
+        return @boundary if defined?(@boundary) && @boundary
+
+        # Use the same algorithm used by WebKit: generate 16 random
+        # alphanumeric characters, replacing `+` `/` with `A` `B` (included in
+        # the list twice) to round out the set of 64.
+        s = SecureRandom.base64(12)
+        s.tr!('+/', 'AB')
+
+        @boundary = '----RubyFormBoundary' + s
       end
 
       # for Multipart do not escape the keys
+      #
+      # Ostensibly multipart keys MAY be percent encoded per RFC 7578, but in
+      # practice no major browser that I'm aware of uses percent encoding.
+      #
+      # Further discussion of multipart encoding:
+      # https://github.com/rest-client/rest-client/pull/403#issuecomment-156976930
+      #
       def handle_key key
         key
       end

data/lib/restclient/platform.rb

@@ -1,10 +1,12 @@
+require 'rbconfig'
+
 module RestClient
   module Platform
     # Return true if we are running on a darwin-based Ruby platform. This will
     # be false for jruby even on OS X.
     #
     # @return [Boolean]
-    def self.mac?
+    def self.mac_mri?
       RUBY_PLATFORM.include?('darwin')
     end
 
@@ -23,7 +25,25 @@ module RestClient
     # @return [Boolean]
     #
     def self.jruby?
-      RUBY_PLATFORM == 'java'
+      # defined on mri >= 1.9
+      RUBY_ENGINE == 'jruby'
+    end
+
+    def self.architecture
+      "#{RbConfig::CONFIG['host_os']} #{RbConfig::CONFIG['host_cpu']}"
+    end
+
+    def self.ruby_agent_version
+      case RUBY_ENGINE
+      when 'jruby'
+        "jruby/#{JRUBY_VERSION} (#{RUBY_VERSION}p#{RUBY_PATCHLEVEL})"
+      else
+        "#{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL}"
+      end
+    end
+
+    def self.default_user_agent
+      "rest-client/#{VERSION} (#{architecture}) #{ruby_agent_version}"
     end
   end
 end

data/lib/restclient/raw_response.rb

@@ -13,12 +13,16 @@ module RestClient
 
     include AbstractResponse
 
-    attr_reader :file
+    attr_reader :file, :request
 
-    def initialize tempfile, net_http_res, args
+    def inspect
+      "<RestClient::RawResponse @code=#{code.inspect}, @file=#{file.inspect}, @request=#{request.inspect}>"
+    end
+
+    def initialize(tempfile, net_http_res, request)
       @net_http_res = net_http_res
-      @args = args
       @file = tempfile
+      @request = request
     end
 
     def to_s

data/lib/restclient/request.rb

@@ -1,6 +1,8 @@
 require 'tempfile'
 require 'mime/types'
 require 'cgi'
+require 'netrc'
+require 'set'
 
 module RestClient
   # This class is used internally by RestClient to send the request, but you can also
@@ -14,135 +16,602 @@ module RestClient
   # * :url
   # Optional parameters (have a look at ssl and/or uri for some explanations):
   # * :headers a hash containing the request headers
-  # * :cookies will replace possible cookies in the :headers
+  # * :cookies may be a Hash{String/Symbol => String} of cookie values, an
+  #     Array<HTTP::Cookie>, or an HTTP::CookieJar containing cookies. These
+  #     will be added to a cookie jar before the request is sent.
   # * :user and :password for basic auth, will be replaced by a user/password available in the :url
   # * :block_response call the provided block with the HTTPResponse as parameter
   # * :raw_response return a low-level RawResponse instead of a Response
   # * :max_redirects maximum number of redirections (default to 10)
-  # * :verify_ssl enable ssl verification, possible values are constants from OpenSSL::SSL
-  # * :timeout and :open_timeout passing in -1 will disable the timeout by setting the corresponding net timeout values to nil
-  # * :ssl_client_cert, :ssl_client_key, :ssl_ca_file
-  # * :ssl_verify_callback, :ssl_verify_callback_warnings
+  # * :proxy An HTTP proxy URI to use for this request. Any value here
+  #   (including nil) will override RestClient.proxy.
+  # * :verify_ssl enable ssl verification, possible values are constants from
+  #     OpenSSL::SSL::VERIFY_*, defaults to OpenSSL::SSL::VERIFY_PEER
+  # * :read_timeout and :open_timeout are how long to wait for a response and
+  #     to open a connection, in seconds. Pass nil to disable the timeout.
+  # * :timeout can be used to set both timeouts
+  # * :ssl_client_cert, :ssl_client_key, :ssl_ca_file, :ssl_ca_path,
+  #     :ssl_cert_store, :ssl_verify_callback, :ssl_verify_callback_warnings
+  # * :ssl_version specifies the SSL version for the underlying Net::HTTP connection
+  # * :ssl_ciphers sets SSL ciphers for the connection. See
+  #     OpenSSL::SSL::SSLContext#ciphers=
+  # * :before_execution_proc a Proc to call before executing the request. This
+  #      proc, like procs from RestClient.before_execution_procs, will be
+  #      called with the HTTP request and request params.
   class Request
 
-    attr_reader :method, :url, :headers, :cookies,
-                :payload, :user, :password, :timeout, :max_redirects,
-                :open_timeout, :raw_response, :verify_ssl, :ssl_client_cert,
-                :ssl_client_key, :ssl_ca_file, :processed_headers, :args,
-                :ssl_verify_callback, :ssl_verify_callback_warnings
+    attr_reader :method, :uri, :url, :headers, :payload, :proxy,
+                :user, :password, :read_timeout, :max_redirects,
+                :open_timeout, :raw_response, :processed_headers, :args,
+                :ssl_opts
+
+    # An array of previous redirection responses
+    attr_accessor :redirection_history
 
     def self.execute(args, & block)
       new(args).execute(& block)
     end
 
+    SSLOptionList = %w{client_cert client_key ca_file ca_path cert_store
+                       version ciphers verify_callback verify_callback_warnings}
+
+    def inspect
+      "<RestClient::Request @method=#{@method.inspect}, @url=#{@url.inspect}>"
+    end
+
     def initialize args
-      @method = args[:method] or raise ArgumentError, "must pass :method"
-      @headers = args[:headers] || {}
+      @method = normalize_method(args[:method])
+      @headers = (args[:headers] || {}).dup
       if args[:url]
-        @url = process_url_params(args[:url], headers)
+        @url = process_url_params(normalize_url(args[:url]), headers)
       else
         raise ArgumentError, "must pass :url"
       end
-      @cookies = @headers.delete(:cookies) || args[:cookies] || {}
+
+      @user = @password = nil
+      parse_url_with_auth!(url)
+
+      # process cookie arguments found in headers or args
+      @cookie_jar = process_cookie_args!(@uri, @headers, args)
+
       @payload = Payload.generate(args[:payload])
-      @user = args[:user]
-      @password = args[:password]
-      @timeout = args[:timeout]
-      @open_timeout = args[:open_timeout]
+
+      @user = args[:user] if args.include?(:user)
+      @password = args[:password] if args.include?(:password)
+
+      if args.include?(:timeout)
+        @read_timeout = args[:timeout]
+        @open_timeout = args[:timeout]
+      end
+      if args.include?(:read_timeout)
+        @read_timeout = args[:read_timeout]
+      end
+      if args.include?(:open_timeout)
+        @open_timeout = args[:open_timeout]
+      end
       @block_response = args[:block_response]
       @raw_response = args[:raw_response] || false
-      @verify_ssl = args[:verify_ssl] || false
-      @ssl_client_cert = args[:ssl_client_cert] || nil
-      @ssl_client_key = args[:ssl_client_key] || nil
-      @ssl_ca_file = args[:ssl_ca_file] || nil
-      @ssl_verify_callback = args[:ssl_verify_callback] || nil
-      @ssl_verify_callback_warnings = args.fetch(:ssl_verify_callback, true)
+
+      @proxy = args.fetch(:proxy) if args.include?(:proxy)
+
+      @ssl_opts = {}
+
+      if args.include?(:verify_ssl)
+        v_ssl = args.fetch(:verify_ssl)
+        if v_ssl
+          if v_ssl == true
+            # interpret :verify_ssl => true as VERIFY_PEER
+            @ssl_opts[:verify_ssl] = OpenSSL::SSL::VERIFY_PEER
+          else
+            # otherwise pass through any truthy values
+            @ssl_opts[:verify_ssl] = v_ssl
+          end
+        else
+          # interpret all falsy :verify_ssl values as VERIFY_NONE
+          @ssl_opts[:verify_ssl] = OpenSSL::SSL::VERIFY_NONE
+        end
+      else
+        # if :verify_ssl was not passed, default to VERIFY_PEER
+        @ssl_opts[:verify_ssl] = OpenSSL::SSL::VERIFY_PEER
+      end
+
+      SSLOptionList.each do |key|
+        source_key = ('ssl_' + key).to_sym
+        if args.has_key?(source_key)
+          @ssl_opts[key.to_sym] = args.fetch(source_key)
+        end
+      end
+
+      # Set some other default SSL options, but only if we have an HTTPS URI.
+      if use_ssl?
+
+        # If there's no CA file, CA path, or cert store provided, use default
+        if !ssl_ca_file && !ssl_ca_path && !@ssl_opts.include?(:cert_store)
+          @ssl_opts[:cert_store] = self.class.default_ssl_cert_store
+        end
+      end
+
       @tf = nil # If you are a raw request, this is your tempfile
       @max_redirects = args[:max_redirects] || 10
       @processed_headers = make_headers headers
       @args = args
+
+      @before_execution_proc = args[:before_execution_proc]
     end
 
     def execute & block
-      uri = parse_url_with_auth(url)
-      transmit uri, net_http_request_class(method).new(uri.request_uri, processed_headers), payload, & block
+      # With 2.0.0+, net/http accepts URI objects in requests and handles wrapping
+      # IPv6 addresses in [] for use in the Host request header.
+      transmit uri, net_http_request_class(method).new(uri, processed_headers), payload, & block
     ensure
       payload.close if payload
     end
 
+    # SSL-related options
+    def verify_ssl
+      @ssl_opts.fetch(:verify_ssl)
+    end
+    SSLOptionList.each do |key|
+      define_method('ssl_' + key) do
+        @ssl_opts[key.to_sym]
+      end
+    end
+
+    # Return true if the request URI will use HTTPS.
+    #
+    # @return [Boolean]
+    #
+    def use_ssl?
+      uri.is_a?(URI::HTTPS)
+    end
+
     # Extract the query parameters and append them to the url
-    def process_url_params url, headers
-      url_params = {}
+    #
+    # Look through the headers hash for a :params option (case-insensitive,
+    # may be string or symbol). If present and the value is a Hash or
+    # RestClient::ParamsArray, *delete* the key/value pair from the headers
+    # hash and encode the value into a query string. Append this query string
+    # to the URL and return the resulting URL.
+    #
+    # @param [String] url
+    # @param [Hash] headers An options/headers hash to process. Mutation
+    #   warning: the params key may be removed if present!
+    #
+    # @return [String] resulting url with query string
+    #
+    def process_url_params(url, headers)
+      url_params = nil
+
+      # find and extract/remove "params" key if the value is a Hash/ParamsArray
       headers.delete_if do |key, value|
-        if 'params' == key.to_s.downcase && value.is_a?(Hash)
-          url_params.merge! value
+        if key.to_s.downcase == 'params' &&
+            (value.is_a?(Hash) || value.is_a?(RestClient::ParamsArray))
+          if url_params
+            raise ArgumentError.new("Multiple 'params' options passed")
+          end
+          url_params = value
           true
         else
           false
         end
       end
-      unless url_params.empty?
-        query_string = url_params.collect { |k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}" }.join('&')
-        url + "?#{query_string}"
+
+      # build resulting URL with query string
+      if url_params && !url_params.empty?
+        query_string = RestClient::Utils.encode_query_string(url_params)
+
+        if url.include?('?')
+          url + '&' + query_string
+        else
+          url + '?' + query_string
+        end
       else
         url
       end
     end
 
-    def make_headers user_headers
-      unless @cookies.empty?
-        user_headers[:cookie] = @cookies.map { |(key, val)| "#{key.to_s}=#{CGI::unescape(val)}" }.sort.join('; ')
+    # Render a hash of key => value pairs for cookies in the Request#cookie_jar
+    # that are valid for the Request#uri. This will not necessarily include all
+    # cookies if there are duplicate keys. It's safer to use the cookie_jar
+    # directly if that's a concern.
+    #
+    # @see Request#cookie_jar
+    #
+    # @return [Hash]
+    #
+    def cookies
+      hash = {}
+
+      @cookie_jar.cookies(uri).each do |c|
+        hash[c.name] = c.value
+      end
+
+      hash
+    end
+
+    # @return [HTTP::CookieJar]
+    def cookie_jar
+      @cookie_jar
+    end
+
+    # Render a Cookie HTTP request header from the contents of the @cookie_jar,
+    # or nil if the jar is empty.
+    #
+    # @see Request#cookie_jar
+    #
+    # @return [String, nil]
+    #
+    def make_cookie_header
+      return nil if cookie_jar.nil?
+
+      arr = cookie_jar.cookies(url)
+      return nil if arr.empty?
+
+      return HTTP::Cookie.cookie_value(arr)
+    end
+
+    # Process cookies passed as hash or as HTTP::CookieJar. For backwards
+    # compatibility, these may be passed as a :cookies option masquerading
+    # inside the headers hash. To avoid confusion, if :cookies is passed in
+    # both headers and Request#initialize, raise an error.
+    #
+    # :cookies may be a:
+    # - Hash{String/Symbol => String}
+    # - Array<HTTP::Cookie>
+    # - HTTP::CookieJar
+    #
+    # Passing as a hash:
+    #   Keys may be symbols or strings. Values must be strings.
+    #   Infer the domain name from the request URI and allow subdomains (as
+    #   though '.example.com' had been set in a Set-Cookie header). Assume a
+    #   path of '/'.
+    #
+    #     RestClient::Request.new(url: 'http://example.com', method: :get,
+    #       :cookies => {:foo => 'Value', 'bar' => '123'}
+    #     )
+    #
+    # results in cookies as though set from the server by:
+    #     Set-Cookie: foo=Value; Domain=.example.com; Path=/
+    #     Set-Cookie: bar=123; Domain=.example.com; Path=/
+    #
+    # which yields a client cookie header of:
+    #     Cookie: foo=Value; bar=123
+    #
+    # Passing as HTTP::CookieJar, which will be passed through directly:
+    #
+    #     jar = HTTP::CookieJar.new
+    #     jar.add(HTTP::Cookie.new('foo', 'Value', domain: 'example.com',
+    #                              path: '/', for_domain: false))
+    #
+    #     RestClient::Request.new(..., :cookies => jar)
+    #
+    # @param [URI::HTTP] uri The URI for the request. This will be used to
+    # infer the domain name for cookies passed as strings in a hash. To avoid
+    # this implicit behavior, pass a full cookie jar or use HTTP::Cookie hash
+    # values.
+    # @param [Hash] headers The headers hash from which to pull the :cookies
+    #   option. MUTATION NOTE: This key will be deleted from the hash if
+    #   present.
+    # @param [Hash] args The options passed to Request#initialize. This hash
+    #   will be used as another potential source for the :cookies key.
+    #   These args will not be mutated.
+    #
+    # @return [HTTP::CookieJar] A cookie jar containing the parsed cookies.
+    #
+    def process_cookie_args!(uri, headers, args)
+
+      # Avoid ambiguity in whether options from headers or options from
+      # Request#initialize should take precedence by raising ArgumentError when
+      # both are present. Prior versions of rest-client claimed to give
+      # precedence to init options, but actually gave precedence to headers.
+      # Avoid that mess by erroring out instead.
+      if headers[:cookies] && args[:cookies]
+        raise ArgumentError.new(
+          "Cannot pass :cookies in Request.new() and in headers hash")
       end
+
+      cookies_data = headers.delete(:cookies) || args[:cookies]
+
+      # return copy of cookie jar as is
+      if cookies_data.is_a?(HTTP::CookieJar)
+        return cookies_data.dup
+      end
+
+      # convert cookies hash into a CookieJar
+      jar = HTTP::CookieJar.new
+
+      (cookies_data || []).each do |key, val|
+
+        # Support for Array<HTTP::Cookie> mode:
+        # If key is a cookie object, add it to the jar directly and assert that
+        # there is no separate val.
+        if key.is_a?(HTTP::Cookie)
+          if val
+            raise ArgumentError.new("extra cookie val: #{val.inspect}")
+          end
+
+          jar.add(key)
+          next
+        end
+
+        if key.is_a?(Symbol)
+          key = key.to_s
+        end
+
+        # assume implicit domain from the request URI, and set for_domain to
+        # permit subdomains
+        jar.add(HTTP::Cookie.new(key, val, domain: uri.hostname.downcase,
+                                 path: '/', for_domain: true))
+      end
+
+      jar
+    end
+
+    # Generate headers for use by a request. Header keys will be stringified
+    # using `#stringify_headers` to normalize them as capitalized strings.
+    #
+    # The final headers consist of:
+    #   - default headers from #default_headers
+    #   - user_headers provided here
+    #   - headers from the payload object (e.g. Content-Type, Content-Lenth)
+    #   - cookie headers from #make_cookie_header
+    #
+    # @param [Hash] user_headers User-provided headers to include
+    #
+    # @return [Hash<String, String>] A hash of HTTP headers => values
+    #
+    def make_headers(user_headers)
       headers = stringify_headers(default_headers).merge(stringify_headers(user_headers))
-      headers.merge!(@payload.headers) if @payload
+
+      # override headers from the payload (e.g. Content-Type, Content-Length)
+      if @payload
+        payload_headers = @payload.headers
+
+        # Warn the user if we override any headers that were previously
+        # present. This usually indicates that rest-client was passed
+        # conflicting information, e.g. if it was asked to render a payload as
+        # x-www-form-urlencoded but a Content-Type application/json was
+        # also supplied by the user.
+        payload_headers.each_pair do |key, val|
+          if headers.include?(key) && headers[key] != val
+            warn("warning: Overriding #{key.inspect} header " +
+                 "#{headers.fetch(key).inspect} with #{val.inspect} " +
+                 "due to payload")
+          end
+        end
+
+        headers.merge!(payload_headers)
+      end
+
+      # merge in cookies
+      cookies = make_cookie_header
+      if cookies && !cookies.empty?
+        if headers['Cookie']
+          warn('warning: overriding "Cookie" header with :cookies option')
+        end
+        headers['Cookie'] = cookies
+      end
+
       headers
     end
 
-    def net_http_class
-      if RestClient.proxy
-        proxy_uri = URI.parse(RestClient.proxy)
-        Net::HTTP::Proxy(proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password)
+    # The proxy URI for this request. If `:proxy` was provided on this request,
+    # use it over `RestClient.proxy`.
+    #
+    # Return false if a proxy was explicitly set and is falsy.
+    #
+    # @return [URI, false, nil]
+    #
+    def proxy_uri
+      if defined?(@proxy)
+        if @proxy
+          URI.parse(@proxy)
+        else
+          false
+        end
+      elsif RestClient.proxy_set?
+        if RestClient.proxy
+          URI.parse(RestClient.proxy)
+        else
+          false
+        end
       else
-        Net::HTTP
+        nil
+      end
+    end
+
+    def net_http_object(hostname, port)
+      p_uri = proxy_uri
+
+      if p_uri.nil?
+        # no proxy set
+        Net::HTTP.new(hostname, port)
+      elsif !p_uri
+        # proxy explicitly set to none
+        Net::HTTP.new(hostname, port, nil, nil, nil, nil)
+      else
+        Net::HTTP.new(hostname, port,
+                      p_uri.hostname, p_uri.port, p_uri.user, p_uri.password)
+
       end
     end
 
     def net_http_request_class(method)
-      Net::HTTP.const_get(method.to_s.capitalize)
+      Net::HTTP.const_get(method.capitalize, false)
     end
 
-    def parse_url(url)
-      url = "http://#{url}" unless url.match(/^http/)
-      URI.parse(url)
+    def net_http_do_request(http, req, body=nil, &block)
+      if body && body.respond_to?(:read)
+        req.body_stream = body
+        return http.request(req, nil, &block)
+      else
+        return http.request(req, body, &block)
+      end
     end
 
-    def parse_url_with_auth(url)
-      uri = parse_url(url)
-      @user = CGI.unescape(uri.user) if uri.user
-      @password = CGI.unescape(uri.password) if uri.password
-      uri
+    # Normalize a URL by adding a protocol if none is present.
+    #
+    # If the string has no HTTP-like scheme (i.e. scheme followed by '//'), a
+    # scheme of 'http' will be added. This mimics the behavior of browsers and
+    # user agents like cURL.
+    #
+    # @param [String] url A URL string.
+    #
+    # @return [String]
+    #
+    def normalize_url(url)
+      url = 'http://' + url unless url.match(%r{\A[a-z][a-z0-9+.-]*://}i)
+      url
+    end
+
+    # Return a certificate store that can be used to validate certificates with
+    # the system certificate authorities. This will probably not do anything on
+    # OS X, which monkey patches OpenSSL in terrible ways to insert its own
+    # validation. On most *nix platforms, this will add the system certifcates
+    # using OpenSSL::X509::Store#set_default_paths. On Windows, this will use
+    # RestClient::Windows::RootCerts to look up the CAs trusted by the system.
+    #
+    # @return [OpenSSL::X509::Store]
+    #
+    def self.default_ssl_cert_store
+      cert_store = OpenSSL::X509::Store.new
+      cert_store.set_default_paths
+
+      # set_default_paths() doesn't do anything on Windows, so look up
+      # certificates using the win32 API.
+      if RestClient::Platform.windows?
+        RestClient::Windows::RootCerts.instance.to_a.uniq.each do |cert|
+          begin
+            cert_store.add_cert(cert)
+          rescue OpenSSL::X509::StoreError => err
+            # ignore duplicate certs
+            raise unless err.message == 'cert already in hash table'
+          end
+        end
+      end
+
+      cert_store
     end
 
-    def process_payload(p=nil, parent_key=nil)
-      unless p.is_a?(Hash)
-        p
+    def self.decode content_encoding, body
+      if (!body) || body.empty?
+        body
+      elsif content_encoding == 'gzip'
+        Zlib::GzipReader.new(StringIO.new(body)).read
+      elsif content_encoding == 'deflate'
+        begin
+          Zlib::Inflate.new.inflate body
+        rescue Zlib::DataError
+          # No luck with Zlib decompression. Let's try with raw deflate,
+          # like some broken web servers do.
+          Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate body
+        end
+      else
+        body
+      end
+    end
+
+    def redacted_uri
+      if uri.password
+        sanitized_uri = uri.dup
+        sanitized_uri.password = 'REDACTED'
+        sanitized_uri
       else
-        @headers[:content_type] ||= 'application/x-www-form-urlencoded'
-        p.keys.map do |k|
-          key = parent_key ? "#{parent_key}[#{k}]" : k
-          if p[k].is_a? Hash
-            process_payload(p[k], key)
+        uri
+      end
+    end
+
+    def redacted_url
+      redacted_uri.to_s
+    end
+
+    def log_request
+      return unless RestClient.log
+
+      out = []
+
+      out << "RestClient.#{method} #{redacted_url.inspect}"
+      out << payload.short_inspect if payload
+      out << processed_headers.to_a.sort.map { |(k, v)| [k.inspect, v.inspect].join("=>") }.join(", ")
+      RestClient.log << out.join(', ') + "\n"
+    end
+
+    def log_response res
+      return unless RestClient.log
+
+      size = if @raw_response
+               File.size(@tf.path)
+             else
+               res.body.nil? ? 0 : res.body.size
+             end
+
+      RestClient.log << "# => #{res.code} #{res.class.to_s.gsub(/^Net::HTTP/, '')} | #{(res['Content-type'] || '').gsub(/;.*$/, '')} #{size} bytes\n"
+    end
+
+    # Return a hash of headers whose keys are capitalized strings
+    def stringify_headers headers
+      headers.inject({}) do |result, (key, value)|
+        if key.is_a? Symbol
+          key = key.to_s.split(/_/).map(&:capitalize).join('-')
+        end
+        if 'CONTENT-TYPE' == key.upcase
+          result[key] = maybe_convert_extension(value.to_s)
+        elsif 'ACCEPT' == key.upcase
+          # Accept can be composed of several comma-separated values
+          if value.is_a? Array
+            target_values = value
           else
-            value = parser.escape(p[k].to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
-            "#{key}=#{value}"
+            target_values = value.to_s.split ','
           end
-        end.join("&")
+          result[key] = target_values.map { |ext|
+            maybe_convert_extension(ext.to_s.strip)
+          }.join(', ')
+        else
+          result[key] = value.to_s
+        end
+        result
+      end
+    end
+
+    def default_headers
+      {
+        :accept => '*/*',
+        :accept_encoding => 'gzip, deflate',
+        :user_agent => RestClient::Platform.default_user_agent,
+      }
+    end
+
+    private
+
+    # Parse the `@url` string into a URI object and save it as
+    # `@uri`. Also save any basic auth user or password as @user and @password.
+    # If no auth info was passed, check for credentials in a Netrc file.
+    #
+    # @param [String] url A URL string.
+    #
+    # @return [URI]
+    #
+    # @raise URI::InvalidURIError on invalid URIs
+    #
+    def parse_url_with_auth!(url)
+      uri = URI.parse(url)
+
+      if uri.hostname.nil?
+        raise URI::InvalidURIError.new("bad URI(no host provided): #{url}")
       end
+
+      @user = CGI.unescape(uri.user) if uri.user
+      @password = CGI.unescape(uri.password) if uri.password
+      if !@user && !@password
+        @user, @password = Netrc.read[uri.hostname]
+      end
+
+      @uri = uri
     end
 
     def print_verify_callback_warnings
       warned = false
-      if RestClient::Platform.mac?
+      if RestClient::Platform.mac_mri?
         warn('warning: ssl_verify_callback return code is ignored on OS X')
         warned = true
       end
@@ -154,32 +623,47 @@ module RestClient
       warned
     end
 
+    # Parse a method and return a normalized string version.
+    #
+    # Raise ArgumentError if the method is falsy, but otherwise do no
+    # validation.
+    #
+    # @param method [String, Symbol]
+    #
+    # @return [String]
+    #
+    # @see net_http_request_class
+    #
+    def normalize_method(method)
+      raise ArgumentError.new('must pass :method') unless method
+      method.to_s.downcase
+    end
+
     def transmit uri, req, payload, & block
+
+      # We set this to true in the net/http block so that we can distinguish
+      # read_timeout from open_timeout. Now that we only support Ruby 2.0+,
+      # this is only needed for Timeout exceptions thrown outside of Net::HTTP.
+      established_connection = false
+
       setup_credentials req
 
-      net = net_http_class.new(uri.host, uri.port)
+      net = net_http_object(uri.hostname, uri.port)
       net.use_ssl = uri.is_a?(URI::HTTPS)
-      if @verify_ssl
-        if @verify_ssl.is_a? Integer
-          net.verify_mode = @verify_ssl
-        else
-          net.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        end
-      else
-        net.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      end
-      net.cert = @ssl_client_cert if @ssl_client_cert
-      net.key = @ssl_client_key if @ssl_client_key
-      net.ca_file = @ssl_ca_file if @ssl_ca_file
-      net.read_timeout = @timeout if @timeout
-      net.open_timeout = @open_timeout if @open_timeout
+      net.ssl_version = ssl_version if ssl_version
+      net.ciphers = ssl_ciphers if ssl_ciphers
+
+      net.verify_mode = verify_ssl
 
-      # disable the timeout if the timeout value is -1
-      net.read_timeout = nil if @timeout == -1
-      net.open_timeout = nil if @open_timeout == -1
+      net.cert = ssl_client_cert if ssl_client_cert
+      net.key = ssl_client_key if ssl_client_key
+      net.ca_file = ssl_ca_file if ssl_ca_file
+      net.ca_path = ssl_ca_path if ssl_ca_path
+      net.cert_store = ssl_cert_store if ssl_cert_store
 
-      # verify_callback isn't well supported on all platforms, but do allow
-      # users to set one if they want.
+      # We no longer rely on net.verify_callback for the main SSL verification
+      # because it's not well supported on all platforms (see comments below).
+      # But do allow users to set one if they want.
       if ssl_verify_callback
         net.verify_callback = ssl_verify_callback
 
@@ -197,34 +681,88 @@ module RestClient
         end
       end
 
+      if OpenSSL::SSL::VERIFY_PEER == OpenSSL::SSL::VERIFY_NONE
+        warn('WARNING: OpenSSL::SSL::VERIFY_PEER == OpenSSL::SSL::VERIFY_NONE')
+        warn('This dangerous monkey patch leaves you open to MITM attacks!')
+        warn('Try passing :verify_ssl => false instead.')
+      end
+
+      if defined? @read_timeout
+        if @read_timeout == -1
+          warn 'Deprecated: to disable timeouts, please use nil instead of -1'
+          @read_timeout = nil
+        end
+        net.read_timeout = @read_timeout
+      end
+      if defined? @open_timeout
+        if @open_timeout == -1
+          warn 'Deprecated: to disable timeouts, please use nil instead of -1'
+          @open_timeout = nil
+        end
+        net.open_timeout = @open_timeout
+      end
+
       RestClient.before_execution_procs.each do |before_proc|
         before_proc.call(req, args)
       end
 
+      if @before_execution_proc
+        @before_execution_proc.call(req, args)
+      end
+
       log_request
 
       net.start do |http|
+        established_connection = true
+
         if @block_response
-          http.request(req, payload ? payload.to_s : nil, & @block_response)
+          net_http_do_request(http, req, payload, &@block_response)
         else
-          res = http.request(req, payload ? payload.to_s : nil) { |http_response| fetch_body(http_response) }
+          res = net_http_do_request(http, req, payload) { |http_response|
+            fetch_body(http_response)
+          }
           log_response res
           process_result res, & block
         end
       end
     rescue EOFError
       raise RestClient::ServerBrokeConnection
-    rescue Timeout::Error
-      raise RestClient::RequestTimeout
+    rescue Net::OpenTimeout => err
+      raise RestClient::Exceptions::OpenTimeout.new(nil, err)
+    rescue Net::ReadTimeout => err
+      raise RestClient::Exceptions::ReadTimeout.new(nil, err)
+    rescue Timeout::Error, Errno::ETIMEDOUT => err
+      # handling for non-Net::HTTP timeouts
+      if established_connection
+        raise RestClient::Exceptions::ReadTimeout.new(nil, err)
+      else
+        raise RestClient::Exceptions::OpenTimeout.new(nil, err)
+      end
+
     rescue OpenSSL::SSL::SSLError => error
-      # UGH. Not sure if this is needed at all. SSLCertificateNotVerified is not being used internally.
-      # I think it would be better to leave SSLError processing to the client (they'd have to do that anyway...)
-      raise SSLCertificateNotVerified.new(error.message) if error.message.include?("certificate verify failed")
-      raise error
+      # TODO: deprecate and remove RestClient::SSLCertificateNotVerified and just
+      # pass through OpenSSL::SSL::SSLError directly.
+      #
+      # Exceptions in verify_callback are ignored [1], and jruby doesn't support
+      # it at all [2]. RestClient has to catch OpenSSL::SSL::SSLError and either
+      # re-throw it as is, or throw SSLCertificateNotVerified based on the
+      # contents of the message field of the original exception.
+      #
+      # The client has to handle OpenSSL::SSL::SSLError exceptions anyway, so
+      # we shouldn't make them handle both OpenSSL and RestClient exceptions.
+      #
+      # [1] https://github.com/ruby/ruby/blob/89e70fe8e7/ext/openssl/ossl.c#L238
+      # [2] https://github.com/jruby/jruby/issues/597
+
+      if error.message.include?("certificate verify failed")
+        raise SSLCertificateNotVerified.new(error.message)
+      else
+        raise error
+      end
     end
 
     def setup_credentials(req)
-      req.basic_auth(user, password) if user
+      req.basic_auth(user, password) if user && !headers.has_key?("Authorization")
     end
 
     def fetch_body(http_response)
@@ -232,18 +770,19 @@ module RestClient
         # Taken from Chef, which as in turn...
         # Stolen from http://www.ruby-forum.com/topic/166423
         # Kudos to _why!
-        @tf = Tempfile.new("rest-client")
-        size, total = 0, http_response.header['Content-Length'].to_i
+        @tf = Tempfile.new('rest-client.')
+        @tf.binmode
+        size, total = 0, http_response['Content-Length'].to_i
         http_response.read_body do |chunk|
           @tf.write chunk
           size += chunk.size
           if RestClient.log
             if size == 0
-              RestClient.log << "#{@method} #{@url} done (0 length file\n)"
+              RestClient.log << "%s %s done (0 length file)\n" % [@method, @url]
             elsif total == 0
-              RestClient.log << "#{@method} #{@url} (zero content length)\n"
+              RestClient.log << "%s %s (zero content length)\n" % [@method, @url]
             else
-              RestClient.log << "#{@method} #{@url} %d%% done (%d of %d)\n" % [(size * 100) / total, size, total]
+              RestClient.log << "%s %s %d%% done (%d of %d)\n" % [@method, @url, (size * 100) / total, size, total]
             end
           end
         end
@@ -258,102 +797,56 @@ module RestClient
     def process_result res, & block
       if @raw_response
         # We don't decode raw requests
-        response = RawResponse.new(@tf, res, args)
+        response = RawResponse.new(@tf, res, self)
       else
-        response = Response.create(Request.decode(res['content-encoding'], res.body), res, args)
+        decoded = Request.decode(res['content-encoding'], res.body)
+        response = Response.create(decoded, res, self)
       end
 
       if block_given?
         block.call(response, self, res, & block)
       else
-        response.return!(self, res, & block)
+        response.return!(&block)
       end
 
     end
 
-    def self.decode content_encoding, body
-      if (!body) || body.empty?
-        body
-      elsif content_encoding == 'gzip'
-        Zlib::GzipReader.new(StringIO.new(body)).read
-      elsif content_encoding == 'deflate'
-        begin
-          Zlib::Inflate.new.inflate body
-        rescue Zlib::DataError
-          # No luck with Zlib decompression. Let's try with raw deflate,
-          # like some broken web servers do.
-          Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate body
-        end
-      else
-        body
-      end
-    end
-
-    def log_request
-      if RestClient.log
-        out = []
-        out << "RestClient.#{method} #{url.inspect}"
-        out << payload.short_inspect if payload
-        out << processed_headers.to_a.sort.map { |(k, v)| [k.inspect, v.inspect].join("=>") }.join(", ")
-        RestClient.log << out.join(', ') + "\n"
-      end
+    def parser
+      URI.const_defined?(:Parser) ? URI::Parser.new : URI
     end
 
-    def log_response res
-      if RestClient.log
-        size = @raw_response ? File.size(@tf.path) : (res.body.nil? ? 0 : res.body.size)
-        RestClient.log << "# => #{res.code} #{res.class.to_s.gsub(/^Net::HTTP/, '')} | #{(res['Content-type'] || '').gsub(/;.*$/, '')} #{size} bytes\n"
+    # Given a MIME type or file extension, return either a MIME type or, if
+    # none is found, the input unchanged.
+    #
+    #     >> maybe_convert_extension('json')
+    #     => 'application/json'
+    #
+    #     >> maybe_convert_extension('unknown')
+    #     => 'unknown'
+    #
+    #     >> maybe_convert_extension('application/xml')
+    #     => 'application/xml'
+    #
+    # @param ext [String]
+    #
+    # @return [String]
+    #
+    def maybe_convert_extension(ext)
+      unless ext =~ /\A[a-zA-Z0-9_@-]+\z/
+        # Don't look up strings unless they look like they could be a file
+        # extension known to mime-types.
+        #
+        # There currently isn't any API public way to look up extensions
+        # directly out of MIME::Types, but the type_for() method only strips
+        # off after a period anyway.
+        return ext
       end
-    end
 
-    # Return a hash of headers whose keys are capitalized strings
-    def stringify_headers headers
-      headers.inject({}) do |result, (key, value)|
-        if key.is_a? Symbol
-          key = key.to_s.split(/_/).map { |w| w.capitalize }.join('-')
-        end
-        if 'CONTENT-TYPE' == key.upcase
-          target_value = value.to_s
-          result[key] = MIME::Types.type_for_extension target_value
-        elsif 'ACCEPT' == key.upcase
-          # Accept can be composed of several comma-separated values
-          if value.is_a? Array
-            target_values = value
-          else
-            target_values = value.to_s.split ','
-          end
-          result[key] = target_values.map { |ext| MIME::Types.type_for_extension(ext.to_s.strip) }.join(', ')
-        else
-          result[key] = value.to_s
-        end
-        result
-      end
-    end
-
-    def default_headers
-      {:accept => '*/*; q=0.5, application/xml', :accept_encoding => 'gzip, deflate'}
-    end
-
-    private
-      def parser
-        URI.const_defined?(:Parser) ? URI::Parser.new : URI
-      end
-
-  end
-end
-
-module MIME
-  class Types
-
-    # Return the first found content-type for a value considered as an extension or the value itself
-    def type_for_extension ext
-      candidates = @extension_index[ext]
-      candidates.empty? ? ext : candidates[0].content_type
-    end
-
-    class << self
-      def type_for_extension ext
-        @__types__.type_for_extension ext
+      types = MIME::Types.type_for(ext)
+      if types.empty?
+        ext
+      else
+        types.first.content_type
       end
     end
   end