rest-client 1.8.0 → 2.1.0

data/lib/restclient/exceptions.rb

@@ -1,5 +1,19 @@
 module RestClient
 
+  # Hash of HTTP status code => message.
+  #
+  # 1xx: Informational - Request received, continuing process
+  # 2xx: Success - The action was successfully received, understood, and
+  #      accepted
+  # 3xx: Redirection - Further action must be taken in order to complete the
+  #      request
+  # 4xx: Client Error - The request contains bad syntax or cannot be fulfilled
+  # 5xx: Server Error - The server failed to fulfill an apparently valid
+  #      request
+  #
+  # @see
+  #   http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+  #
   STATUSES = {100 => 'Continue',
               101 => 'Switching Protocols',
               102 => 'Processing', #WebDAV
@@ -12,6 +26,8 @@ module RestClient
               205 => 'Reset Content',
               206 => 'Partial Content',
               207 => 'Multi-Status', #WebDAV
+              208 => 'Already Reported', # RFC5842
+              226 => 'IM Used', # RFC3229
 
               300 => 'Multiple Choices',
               301 => 'Moved Permanently',
@@ -21,12 +37,13 @@ module RestClient
               305 => 'Use Proxy', # http/1.1
               306 => 'Switch Proxy', # no longer used
               307 => 'Temporary Redirect', # http/1.1
+              308 => 'Permanent Redirect', # RFC7538
 
               400 => 'Bad Request',
               401 => 'Unauthorized',
               402 => 'Payment Required',
               403 => 'Forbidden',
-              404 => 'Resource Not Found',
+              404 => 'Not Found',
               405 => 'Method Not Allowed',
               406 => 'Not Acceptable',
               407 => 'Proxy Authentication Required',
@@ -35,10 +52,10 @@ module RestClient
               410 => 'Gone',
               411 => 'Length Required',
               412 => 'Precondition Failed',
-              413 => 'Request Entity Too Large',
-              414 => 'Request-URI Too Long',
+              413 => 'Payload Too Large', # RFC7231 (renamed, see below)
+              414 => 'URI Too Long', # RFC7231 (renamed, see below)
               415 => 'Unsupported Media Type',
-              416 => 'Requested Range Not Satisfiable',
+              416 => 'Range Not Satisfiable', # RFC7233 (renamed, see below)
               417 => 'Expectation Failed',
               418 => 'I\'m A Teapot', #RFC2324
               421 => 'Too Many Connections From This IP',
@@ -61,22 +78,27 @@ module RestClient
               505 => 'HTTP Version Not Supported',
               506 => 'Variant Also Negotiates',
               507 => 'Insufficient Storage', #WebDAV
+              508 => 'Loop Detected', # RFC5842
               509 => 'Bandwidth Limit Exceeded', #Apache
               510 => 'Not Extended',
               511 => 'Network Authentication Required', # RFC6585
   }
 
-  # Compatibility : make the Response act like a Net::HTTPResponse when needed
-  module ResponseForException
-    def method_missing symbol, *args
-      if net_http_res.respond_to? symbol
-        warn "[warning] The response contained in an RestClient::Exception is now a RestClient::Response instead of a Net::HTTPResponse, please update your code"
-        net_http_res.send symbol, *args
-      else
-        super
-      end
-    end
-  end
+  STATUSES_COMPATIBILITY = {
+    # The RFCs all specify "Not Found", but "Resource Not Found" was used in
+    # earlier RestClient releases.
+    404 => ['ResourceNotFound'],
+
+    # HTTP 413 was renamed to "Payload Too Large" in RFC7231.
+    413 => ['RequestEntityTooLarge'],
+
+    # HTTP 414 was renamed to "URI Too Long" in RFC7231.
+    414 => ['RequestURITooLong'],
+
+    # HTTP 416 was renamed to "Range Not Satisfiable" in RFC7233.
+    416 => ['RequestedRangeNotSatisfiable'],
+  }
+
 
   # This is the base RestClient exception class. Rescue it if you want to
   # catch any exception that your request might raise
@@ -86,15 +108,13 @@ module RestClient
   # probably an HTML error page) is e.response.
   class Exception < RuntimeError
     attr_accessor :response
+    attr_accessor :original_exception
     attr_writer :message
 
     def initialize response = nil, initial_response_code = nil
       @response = response
       @message = nil
       @initial_response_code = initial_response_code
-
-      # compatibility: this make the exception behave like a Net::HTTPResponse
-      response.extend ResponseForException if response
     end
 
     def http_code
@@ -106,32 +126,35 @@ module RestClient
       end
     end
 
-    def http_body
-      @response.body if @response
+    def http_headers
+      @response.headers if @response
     end
 
-    def inspect
-      "#{message}: #{http_body}"
+    def http_body
+      @response.body if @response
     end
 
     def to_s
-      inspect
+      message
     end
 
     def message
-      @message || self.class.name
+      @message || default_message
     end
 
+    def default_message
+      self.class.name
+    end
   end
 
   # Compatibility
-  class ExceptionWithResponse < Exception
+  class ExceptionWithResponse < RestClient::Exception
   end
 
   # The request failed with an error code not managed by the code
   class RequestFailed < ExceptionWithResponse
 
-    def message
+    def default_message
       "HTTP status code #{http_code}"
     end
 
@@ -140,64 +163,82 @@ module RestClient
     end
   end
 
-  # We will a create an exception for each status code, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+  # RestClient exception classes. TODO: move all exceptions into this module.
+  #
+  # We will a create an exception for each status code, see
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+  #
   module Exceptions
     # Map http status codes to the corresponding exception class
     EXCEPTIONS_MAP = {}
   end
 
+  # Create HTTP status exception classes
   STATUSES.each_pair do |code, message|
-
-    # Compatibility
-    superclass = ([304, 401, 404].include? code) ? ExceptionWithResponse : RequestFailed
-    klass = Class.new(superclass) do
-      send(:define_method, :message) {"#{http_code ? "#{http_code} " : ''}#{message}"}
+    klass = Class.new(RequestFailed) do
+      send(:define_method, :default_message) {"#{http_code ? "#{http_code} " : ''}#{message}"}
     end
-    klass_constant = const_set message.delete(' \-\''), klass
+    klass_constant = const_set(message.delete(' \-\''), klass)
     Exceptions::EXCEPTIONS_MAP[code] = klass_constant
   end
 
-  # A redirect was encountered; caught by execute to retry with the new url.
-  class Redirect < Exception
-
-    def message
-      'Redirect'
+  # Create HTTP status exception classes used for backwards compatibility
+  STATUSES_COMPATIBILITY.each_pair do |code, compat_list|
+    klass = Exceptions::EXCEPTIONS_MAP.fetch(code)
+    compat_list.each do |old_name|
+      const_set(old_name, klass)
     end
+  end
 
-    attr_accessor :url
+  module Exceptions
+    # We have to split the Exceptions module like we do here because the
+    # EXCEPTIONS_MAP is under Exceptions, but we depend on
+    # RestClient::RequestTimeout below.
+
+    # Base class for request timeouts.
+    #
+    # NB: Previous releases of rest-client would raise RequestTimeout both for
+    # HTTP 408 responses and for actual connection timeouts.
+    class Timeout < RestClient::RequestTimeout
+      def initialize(message=nil, original_exception=nil)
+        super(nil, nil)
+        self.message = message if message
+        self.original_exception = original_exception if original_exception
+      end
+    end
 
-    def initialize(url)
-      @url = url
+    # Timeout when connecting to a server. Typically wraps Net::OpenTimeout (in
+    # ruby 2.0 or greater).
+    class OpenTimeout < Timeout
+      def default_message
+        'Timed out connecting to server'
+      end
     end
-  end
 
-  class MaxRedirectsReached < Exception
-    def message
-      'Maximum number of redirect reached'
+    # Timeout when reading from a server. Typically wraps Net::ReadTimeout (in
+    # ruby 2.0 or greater).
+    class ReadTimeout < Timeout
+      def default_message
+        'Timed out reading data from server'
+      end
     end
   end
 
+
   # The server broke the connection prior to the request completing.  Usually
   # this means it crashed, or sometimes that your network connection was
   # severed before it could complete.
-  class ServerBrokeConnection < Exception
+  class ServerBrokeConnection < RestClient::Exception
     def initialize(message = 'Server broke connection')
       super nil, nil
       self.message = message
     end
   end
 
-  class SSLCertificateNotVerified < Exception
-    def initialize(message)
+  class SSLCertificateNotVerified < RestClient::Exception
+    def initialize(message = 'SSL certificate not verified')
       super nil, nil
       self.message = message
     end
   end
 end
-
-class RestClient::Request
-  # backwards compatibility
-  Redirect = RestClient::Redirect
-  Unauthorized = RestClient::Unauthorized
-  RequestFailed = RestClient::RequestFailed
-end

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,13 +1,23 @@
 require 'tempfile'
+require 'securerandom'
 require 'stringio'
-require 'mime/types'
+
+begin
+  # Use mime/types/columnar if available, for reduced memory usage
+  require 'mime/types/columnar'
+rescue LoadError
+  require 'mime/types'
+end
 
 module RestClient
   module Payload
     extend self
 
     def generate(params)
-      if params.is_a?(String)
+      if params.is_a?(RestClient::Payload::Base)
+        # pass through Payload objects unchanged
+        params
+      elsif params.is_a?(String)
         Base.new(params)
       elsif params.is_a?(Hash)
         if params.delete(:multipart) == true || has_file?(params)
@@ -15,6 +25,12 @@ module RestClient
         else
           UrlEncoded.new(params)
         end
+      elsif params.is_a?(ParamsArray)
+        if _has_file?(params)
+          Multipart.new(params)
+        else
+          UrlEncoded.new(params)
+        end
       elsif params.respond_to?(:read)
         Streamed.new(params)
       else
@@ -23,28 +39,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 +66,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 +90,20 @@ module RestClient
         @stream.close unless @stream.closed?
       end
 
-      def inspect
-        result = to_s.inspect
-        @stream.seek(0)
-        result
+      def closed?
+        @stream.closed?
+      end
+
+      def to_s_inspect
+        to_s.inspect
       end
 
       def short_inspect
-        (size > 500 ? "#{size} byte(s) length" : inspect)
+        if size && size > 500
+          "#{size} byte(s) length"
+        else
+          to_s_inspect
+        end
       end
 
     end
@@ -134,42 +121,36 @@ module RestClient
         end
       end
 
+      # TODO (breaks compatibility): ought to use mime_for() to autodetect the
+      # Content-Type for stream objects that have a filename.
+
       alias :length :size
     end
 
     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, Escape)
-      end
-
       def headers
         super.merge({'Content-Type' => 'application/x-www-form-urlencoded'})
       end
-
-      Parser = URI.const_defined?(:Parser) ? URI::Parser.new : URI
-      Escape = Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")
     end
 
     class Multipart < Base
       EOL = "\r\n"
 
       def build_stream(params)
-        b = "--#{boundary}"
+        b = '--' + boundary
 
-        @stream = Tempfile.new("RESTClient.Stream.#{rand(1000)}")
+        @stream = Tempfile.new('rest-client.multipart.')
         @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
@@ -218,10 +199,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,3 +1,5 @@
+require 'rbconfig'
+
 module RestClient
   module Platform
     # Return true if we are running on a darwin-based Ruby platform. This will
@@ -26,5 +28,22 @@ module RestClient
       # 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,22 +13,36 @@ module RestClient
 
     include AbstractResponse
 
-    attr_reader :file, :request
+    attr_reader :file, :request, :start_time, :end_time
 
-    def initialize(tempfile, net_http_res, args, request)
-      @net_http_res = net_http_res
-      @args = args
+    def inspect
+      "<RestClient::RawResponse @code=#{code.inspect}, @file=#{file.inspect}, @request=#{request.inspect}>"
+    end
+
+    # @param [Tempfile] tempfile The temporary file containing the body
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestClient::Request] request
+    # @param [Time] start_time
+    def initialize(tempfile, net_http_res, request, start_time=nil)
       @file = tempfile
-      @request = request
+
+      # reopen the tempfile so we can read it
+      @file.open
+
+      response_set_vars(net_http_res, request, start_time)
     end
 
     def to_s
-      @file.open
+      body
+    end
+
+    def body
+      @file.rewind
       @file.read
     end
 
     def size
-      File.size file
+      file.size
     end
 
   end