rest-client 1.6.7 → 2.1.0

data/lib/restclient/resource.rb

@@ -14,7 +14,7 @@ module RestClient
   #
   # With a timeout (seconds):
   #
-  #   RestClient::Resource.new('http://slow', :timeout => 10)
+  #   RestClient::Resource.new('http://slow', :read_timeout => 10)
   #
   # With an open timeout (seconds):
   #
@@ -51,7 +51,8 @@ module RestClient
       Request.execute(options.merge(
               :method => :get,
               :url => url,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def head(additional_headers={}, &block)
@@ -59,7 +60,8 @@ module RestClient
       Request.execute(options.merge(
               :method => :head,
               :url => url,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def post(payload, additional_headers={}, &block)
@@ -68,7 +70,8 @@ module RestClient
               :method => :post,
               :url => url,
               :payload => payload,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def put(payload, additional_headers={}, &block)
@@ -77,7 +80,8 @@ module RestClient
               :method => :put,
               :url => url,
               :payload => payload,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def patch(payload, additional_headers={}, &block)
@@ -86,7 +90,8 @@ module RestClient
               :method => :patch,
               :url => url,
               :payload => payload,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def delete(additional_headers={}, &block)
@@ -94,7 +99,8 @@ module RestClient
       Request.execute(options.merge(
               :method => :delete,
               :url => url,
-              :headers => headers), &(block || @block))
+              :headers => headers,
+              :log => log), &(block || @block))
     end
 
     def to_s
@@ -113,14 +119,18 @@ module RestClient
       options[:headers] || {}
     end
 
-    def timeout
-      options[:timeout]
+    def read_timeout
+      options[:read_timeout]
     end
 
     def open_timeout
       options[:open_timeout]
     end
 
+    def log
+      options[:log] || RestClient.log
+    end
+
     # Construct a subresource, preserving authentication.
     #
     # Example:
@@ -149,10 +159,9 @@ module RestClient
     #
     def [](suburl, &new_block)
       case
-        when block_given? then self.class.new(concat_urls(url, suburl), options, &new_block)
-        when block        then self.class.new(concat_urls(url, suburl), options, &block)
-      else
-        self.class.new(concat_urls(url, suburl), options)
+      when block_given? then self.class.new(concat_urls(url, suburl), options, &new_block)
+      when block        then self.class.new(concat_urls(url, suburl), options, &block)
+      else                   self.class.new(concat_urls(url, suburl), options)
       end
     end
 

data/lib/restclient/response.rb

@@ -2,23 +2,89 @@ module RestClient
 
   # A Response from RestClient, you can access the response body, the code or the headers.
   #
-  module Response
+  class Response < String
 
     include AbstractResponse
 
-    attr_accessor :args, :body, :net_http_res
-
+    # Return the HTTP response body.
+    #
+    # Future versions of RestClient will deprecate treating response objects
+    # directly as strings, so it will be necessary to call `.body`.
+    #
+    # @return [String]
+    #
     def body
-      self
+      # Benchmarking suggests that "#{self}" is fastest, and that caching the
+      # body string in an instance variable doesn't make it enough faster to be
+      # worth the extra memory storage.
+      String.new(self)
+    end
+
+    # Convert the HTTP response body to a pure String object.
+    #
+    # @return [String]
+    def to_s
+      body
+    end
+
+    # Convert the HTTP response body to a pure String object.
+    #
+    # @return [String]
+    def to_str
+      body
     end
 
-    def Response.create body, net_http_res, args
-      result = body || ''
-      result.extend Response
-      result.net_http_res = net_http_res
-      result.args = args
+    def inspect
+      "<RestClient::Response #{code.inspect} #{body_truncated(10).inspect}>"
+    end
+
+    # Initialize a Response object. Because RestClient::Response is
+    # (unfortunately) a subclass of String for historical reasons,
+    # Response.create is the preferred initializer.
+    #
+    # @param [String, nil] body The response body from the Net::HTTPResponse
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestClient::Request] request
+    # @param [Time] start_time
+    def self.create(body, net_http_res, request, start_time=nil)
+      result = self.new(body || '')
+
+      result.response_set_vars(net_http_res, request, start_time)
+      fix_encoding(result)
+
       result
     end
 
+    # Set the String encoding according to the 'Content-Type: charset' header,
+    # if possible.
+    def self.fix_encoding(response)
+      charset = RestClient::Utils.get_encoding_from_headers(response.headers)
+      encoding = nil
+
+      begin
+        encoding = Encoding.find(charset) if charset
+      rescue ArgumentError
+        if response.log
+          response.log << "No such encoding: #{charset.inspect}"
+        end
+      end
+
+      return unless encoding
+
+      response.force_encoding(encoding)
+
+      response
+    end
+
+    private
+
+    def body_truncated(length)
+      b = body
+      if b.length > length
+        b[0..length] + '...'
+      else
+        b
+      end
+    end
   end
 end

data/lib/restclient/utils.rb

@@ -0,0 +1,274 @@
+require 'http/accept'
+
+module RestClient
+  # Various utility methods
+  module Utils
+
+    # Return encoding from an HTTP header hash.
+    #
+    # We use the RFC 7231 specification and do not impose a default encoding on
+    # text. This differs from the older RFC 2616 behavior, which specifies
+    # using ISO-8859-1 for text/* content types without a charset.
+    #
+    # Strings will use the default encoding when this method returns nil. This
+    # default is likely to be UTF-8 for Ruby >= 2.0
+    #
+    # @param headers [Hash<Symbol,String>]
+    #
+    # @return [String, nil] Return the string encoding or nil if no header is
+    #   found.
+    #
+    # @example
+    #   >> get_encoding_from_headers({:content_type => 'text/plain; charset=UTF-8'})
+    #   => "UTF-8"
+    #
+    def self.get_encoding_from_headers(headers)
+      type_header = headers[:content_type]
+      return nil unless type_header
+
+      # TODO: remove this hack once we drop support for Ruby 2.0
+      if RUBY_VERSION.start_with?('2.0')
+        _content_type, params = deprecated_cgi_parse_header(type_header)
+
+        if params.include?('charset')
+          return params.fetch('charset').gsub(/(\A["']*)|(["']*\z)/, '')
+        end
+
+      else
+
+        begin
+          _content_type, params = cgi_parse_header(type_header)
+        rescue HTTP::Accept::ParseError
+          return nil
+        else
+          params['charset']
+        end
+      end
+    end
+
+    # Parse a Content-Type like header.
+    #
+    # Return the main content-type and a hash of params.
+    #
+    # @param [String] line
+    # @return [Array(String, Hash)]
+    #
+    def self.cgi_parse_header(line)
+      types = HTTP::Accept::MediaTypes.parse(line)
+
+      if types.empty?
+        raise HTTP::Accept::ParseError.new("Found no types in header line")
+      end
+
+      [types.first.mime_type, types.first.parameters]
+    end
+
+    # Parse semi-colon separated, potentially quoted header string iteratively.
+    #
+    # @private
+    #
+    # @deprecated This method is deprecated and only exists to support Ruby
+    #   2.0, which is not supported by HTTP::Accept.
+    #
+    # @todo remove this method when dropping support for Ruby 2.0
+    #
+    def self._cgi_parseparam(s)
+      return enum_for(__method__, s) unless block_given?
+
+      while s[0] == ';'
+        s = s[1..-1]
+        ends = s.index(';')
+        while ends && ends > 0 \
+              && (s[0...ends].count('"') -
+                  s[0...ends].scan('\"').count) % 2 != 0
+          ends = s.index(';', ends + 1)
+        end
+        if ends.nil?
+          ends = s.length
+        end
+        f = s[0...ends]
+        yield f.strip
+        s = s[ends..-1]
+      end
+      nil
+    end
+
+    # Parse a Content-Type like header.
+    #
+    # Return the main content-type and a hash of options.
+    #
+    # This method was ported directly from Python's cgi.parse_header(). It
+    # probably doesn't read or perform particularly well in ruby.
+    # https://github.com/python/cpython/blob/3.4/Lib/cgi.py#L301-L331
+    #
+    # @param [String] line
+    # @return [Array(String, Hash)]
+    #
+    # @deprecated This method is deprecated and only exists to support Ruby
+    #   2.0, which is not supported by HTTP::Accept.
+    #
+    # @todo remove this method when dropping support for Ruby 2.0
+    #
+    def self.deprecated_cgi_parse_header(line)
+      parts = _cgi_parseparam(';' + line)
+      key = parts.next
+      pdict = {}
+
+      begin
+        while (p = parts.next)
+          i = p.index('=')
+          if i
+            name = p[0...i].strip.downcase
+            value = p[i+1..-1].strip
+            if value.length >= 2 && value[0] == '"' && value[-1] == '"'
+              value = value[1...-1]
+              value = value.gsub('\\\\', '\\').gsub('\\"', '"')
+            end
+            pdict[name] = value
+          end
+        end
+      rescue StopIteration
+      end
+
+      [key, pdict]
+    end
+
+    # Serialize a ruby object into HTTP query string parameters.
+    #
+    # There is no standard for doing this, so we choose our own slightly
+    # idiosyncratic format. The output closely matches the format understood by
+    # Rails, Rack, and PHP.
+    #
+    # If you don't want handling of complex objects and only want to handle
+    # simple flat hashes, you may want to use `URI.encode_www_form` instead,
+    # which implements HTML5-compliant URL encoded form data.
+    #
+    # @param [Hash,ParamsArray] object The object to serialize
+    #
+    # @return [String] A string appropriate for use as an HTTP query string
+    #
+    # @see {flatten_params}
+    #
+    # @see URI.encode_www_form
+    #
+    # @see See also Object#to_query in ActiveSupport
+    # @see http://php.net/manual/en/function.http-build-query.php
+    #   http_build_query in PHP
+    # @see See also Rack::Utils.build_nested_query in Rack
+    #
+    # Notable differences from the ActiveSupport implementation:
+    #
+    # - Empty hash and empty array are treated the same as nil instead of being
+    #   omitted entirely from the output. Rather than disappearing, they will
+    #   appear to be nil instead.
+    #
+    # It's most common to pass a Hash as the object to serialize, but you can
+    # also use a ParamsArray if you want to be able to pass the same key with
+    # multiple values and not use the rack/rails array convention.
+    #
+    # @since 2.0.0
+    #
+    # @example Simple hashes
+    #   >> encode_query_string({foo: 123, bar: 456})
+    #   => 'foo=123&bar=456'
+    #
+    # @example Simple arrays
+    #   >> encode_query_string({foo: [1,2,3]})
+    #   => 'foo[]=1&foo[]=2&foo[]=3'
+    #
+    # @example Nested hashes
+    #   >> encode_query_string({outer: {foo: 123, bar: 456}})
+    #   => 'outer[foo]=123&outer[bar]=456'
+    #
+    # @example Deeply nesting
+    #   >> encode_query_string({coords: [{x: 1, y: 0}, {x: 2}, {x: 3}]})
+    #   => 'coords[][x]=1&coords[][y]=0&coords[][x]=2&coords[][x]=3'
+    #
+    # @example Null and empty values
+    #   >> encode_query_string({string: '', empty: nil, list: [], hash: {}})
+    #   => 'string=&empty&list&hash'
+    #
+    # @example Nested nulls
+    #   >> encode_query_string({foo: {string: '', empty: nil}})
+    #   => 'foo[string]=&foo[empty]'
+    #
+    # @example Multiple fields with the same name using ParamsArray
+    #   >> encode_query_string(RestClient::ParamsArray.new([[:foo, 1], [:foo, 2], [:foo, 3]]))
+    #   => 'foo=1&foo=2&foo=3'
+    #
+    # @example Nested ParamsArray
+    #   >> encode_query_string({foo: RestClient::ParamsArray.new([[:a, 1], [:a, 2]])})
+    #   => 'foo[a]=1&foo[a]=2'
+    #
+    #   >> encode_query_string(RestClient::ParamsArray.new([[:foo, {a: 1}], [:foo, {a: 2}]]))
+    #   => 'foo[a]=1&foo[a]=2'
+    #
+    def self.encode_query_string(object)
+      flatten_params(object, true).map {|k, v| v.nil? ? k : "#{k}=#{v}" }.join('&')
+    end
+
+    # Transform deeply nested param containers into a flat array of [key,
+    # value] pairs.
+    #
+    # @example
+    #   >> flatten_params({key1: {key2: 123}})
+    #   => [["key1[key2]", 123]]
+    #
+    # @example
+    #   >> flatten_params({key1: {key2: 123, arr: [1,2,3]}})
+    #   => [["key1[key2]", 123], ["key1[arr][]", 1], ["key1[arr][]", 2], ["key1[arr][]", 3]]
+    #
+    # @param object [Hash, ParamsArray] The container to flatten
+    # @param uri_escape [Boolean] Whether to URI escape keys and values
+    # @param parent_key [String] Should not be passed (used for recursion)
+    #
+    def self.flatten_params(object, uri_escape=false, parent_key=nil)
+      unless object.is_a?(Hash) || object.is_a?(ParamsArray) ||
+             (parent_key && object.is_a?(Array))
+        raise ArgumentError.new('expected Hash or ParamsArray, got: ' + object.inspect)
+      end
+
+      # transform empty collections into nil, where possible
+      if object.empty? && parent_key
+        return [[parent_key, nil]]
+      end
+
+      # This is essentially .map(), but we need to do += for nested containers
+      object.reduce([]) { |result, item|
+        if object.is_a?(Array)
+          # item is already the value
+          k = nil
+          v = item
+        else
+          # item is a key, value pair
+          k, v = item
+          k = escape(k.to_s) if uri_escape
+        end
+
+        processed_key = parent_key ? "#{parent_key}[#{k}]" : k
+
+        case v
+        when Array, Hash, ParamsArray
+          result.concat flatten_params(v, uri_escape, processed_key)
+        else
+          v = escape(v.to_s) if uri_escape && v
+          result << [processed_key, v]
+        end
+      }
+    end
+
+    # Encode string for safe transport by URI or form encoding. This uses a CGI
+    # style escape, which transforms ` ` into `+` and various special
+    # characters into percent encoded forms.
+    #
+    # This calls URI.encode_www_form_component for the implementation. The only
+    # difference between this and CGI.escape is that it does not escape `*`.
+    # http://stackoverflow.com/questions/25085992/
+    #
+    # @see URI.encode_www_form_component
+    #
+    def self.escape(string)
+      URI.encode_www_form_component(string)
+    end
+  end
+end