rest-client 1.6.14 → 2.0.2

data/lib/restclient/abstract_response.rb

@@ -1,16 +1,25 @@
 require 'cgi'
+require 'http-cookie'
 
 module RestClient
 
   module AbstractResponse
 
-    attr_reader :net_http_res, :args
+    attr_reader :net_http_res, :request
+
+    def inspect
+      raise NotImplementedError.new('must override in subclass')
+    end
 
     # HTTP status code
     def code
       @code ||= @net_http_res.code.to_i
     end
 
+    def history
+      @history ||= request.redirection_history || []
+    end
+
     # A hash of the headers, beautified with symbols and underscores.
     # e.g. "Content-type" will become :content_type.
     def headers
@@ -22,85 +31,196 @@ module RestClient
       @raw_headers ||= @net_http_res.to_hash
     end
 
-    # Hash of cookies extracted from response headers
+    def response_set_vars(net_http_res, request)
+      @net_http_res = net_http_res
+      @request = request
+
+      # prime redirection history
+      history
+    end
+
+    # Hash of cookies extracted from response headers.
+    #
+    # NB: This will return only cookies whose domain matches this request, and
+    # may not even return all of those cookies if there are duplicate names.
+    # Use the full cookie_jar for more nuanced access.
+    #
+    # @see #cookie_jar
+    #
+    # @return [Hash]
+    #
     def cookies
-      @cookies ||= (self.headers[:set_cookie] || {}).inject({}) do |out, cookie_content|
-        out.merge parse_cookie(cookie_content)
+      hash = {}
+
+      cookie_jar.cookies(@request.uri).each do |cookie|
+        hash[cookie.name] = cookie.value
       end
+
+      hash
+    end
+
+    # Cookie jar extracted from response headers.
+    #
+    # @return [HTTP::CookieJar]
+    #
+    def cookie_jar
+      return @cookie_jar if defined?(@cookie_jar) && @cookie_jar
+
+      jar = @request.cookie_jar.dup
+      headers.fetch(:set_cookie, []).each do |cookie|
+        jar.parse(cookie, @request.uri)
+      end
+
+      @cookie_jar = jar
     end
 
     # Return the default behavior corresponding to the response code:
-    # the response itself for code in 200..206, redirection for 301, 302 and 307 in get and head cases, redirection for 303 and an exception in other cases
-    def return! request = nil, result = nil, & block
-      if (200..207).include? code
+    #
+    # For 20x status codes: return the response itself
+    #
+    # For 30x status codes:
+    #   301, 302, 307: redirect GET / HEAD if there is a Location header
+    #   303: redirect, changing method to GET, if there is a Location header
+    #
+    # For all other responses, raise a response exception
+    #
+    def return!(&block)
+      case code
+      when 200..207
         self
-      elsif [301, 302, 307].include? code
-        unless [:get, :head].include? args[:method]
-          raise Exceptions::EXCEPTIONS_MAP[code].new(self, code)
+      when 301, 302, 307
+        case request.method
+        when 'get', 'head'
+          check_max_redirects
+          follow_redirection(&block)
         else
-          follow_redirection(request, result, & block)
+          raise exception_with_response
         end
-      elsif code == 303
-        args[:method] = :get
-        args.delete :payload
-        follow_redirection(request, result, & block)
-      elsif Exceptions::EXCEPTIONS_MAP[code]
-        raise Exceptions::EXCEPTIONS_MAP[code].new(self, code)
+      when 303
+        check_max_redirects
+        follow_get_redirection(&block)
       else
-        raise RequestFailed.new(self, code)
+        raise exception_with_response
       end
     end
 
     def to_i
-      code
+      warn('warning: calling Response#to_i is not recommended')
+      super
     end
 
     def description
       "#{code} #{STATUSES[code]} | #{(headers[:content_type] || '').gsub(/;.*$/, '')} #{size} bytes\n"
     end
 
-    # Follow a redirection
-    def follow_redirection request = nil, result = nil, & block
-      url = headers[:location]
-      if url !~ /^http/
-        url = URI.parse(args[:url]).merge(url).to_s
-      end
-      args[:url] = url
-      if request
-        if request.max_redirects == 0
-          raise MaxRedirectsReached
-        end
-        args[:password] = request.password
-        args[:user] = request.user
-        args[:headers] = request.headers
-        args[:max_redirects] = request.max_redirects - 1
-        # pass any cookie set in the result
-        if result && result['set-cookie']
-          args[:headers][:cookies] = (args[:headers][:cookies] || {}).merge(parse_cookie(result['set-cookie']))
-        end
-      end
-      Request.execute args, &block
+    # Follow a redirection response by making a new HTTP request to the
+    # redirection target.
+    def follow_redirection(&block)
+      _follow_redirection(request.args.dup, &block)
+    end
+
+    # Follow a redirection response, but change the HTTP method to GET and drop
+    # the payload from the original request.
+    def follow_get_redirection(&block)
+      new_args = request.args.dup
+      new_args[:method] = :get
+      new_args.delete(:payload)
+
+      _follow_redirection(new_args, &block)
     end
 
-    def AbstractResponse.beautify_headers(headers)
+    # Convert headers hash into canonical form.
+    #
+    # Header names will be converted to lowercase symbols with underscores
+    # instead of hyphens.
+    #
+    # Headers specified multiple times will be joined by comma and space,
+    # except for Set-Cookie, which will always be an array.
+    #
+    # Per RFC 2616, if a server sends multiple headers with the same key, they
+    # MUST be able to be joined into a single header by a comma. However,
+    # Set-Cookie (RFC 6265) cannot because commas are valid within cookie
+    # definitions. The newer RFC 7230 notes (3.2.2) that Set-Cookie should be
+    # handled as a special case.
+    #
+    # http://tools.ietf.org/html/rfc2616#section-4.2
+    # http://tools.ietf.org/html/rfc7230#section-3.2.2
+    # http://tools.ietf.org/html/rfc6265
+    #
+    # @param headers [Hash]
+    # @return [Hash]
+    #
+    def self.beautify_headers(headers)
       headers.inject({}) do |out, (key, value)|
-        out[key.gsub(/-/, '_').downcase.to_sym] = %w{ set-cookie }.include?(key.downcase) ? value : value.first
+        key_sym = key.tr('-', '_').downcase.to_sym
+
+        # Handle Set-Cookie specially since it cannot be joined by comma.
+        if key.downcase == 'set-cookie'
+          out[key_sym] = value
+        else
+          out[key_sym] = value.join(', ')
+        end
+
         out
       end
     end
 
     private
 
-    # Parse a cookie value and return its content in an Hash
-    def parse_cookie cookie_content
-      out = {}
-      CGI::Cookie::parse(cookie_content).each do |key, cookie|
-        unless ['expires', 'path'].include? key
-          out[CGI::escape(key)] = cookie.value[0] ? (CGI::escape(cookie.value[0]) || '') : ''
-        end
+    # Follow a redirection
+    #
+    # @param new_args [Hash] Start with this hash of arguments for the
+    #   redirection request. The hash will be mutated, so be sure to dup any
+    #   existing hash that should not be modified.
+    #
+    def _follow_redirection(new_args, &block)
+
+      # parse location header and merge into existing URL
+      url = headers[:location]
+
+      # cannot follow redirection if there is no location header
+      unless url
+        raise exception_with_response
+      end
+
+      # handle relative redirects
+      unless url.start_with?('http')
+        url = URI.parse(request.url).merge(url).to_s
+      end
+      new_args[:url] = url
+
+      new_args[:password] = request.password
+      new_args[:user] = request.user
+      new_args[:headers] = request.headers
+      new_args[:max_redirects] = request.max_redirects - 1
+
+      # pass through our new cookie jar
+      new_args[:cookies] = cookie_jar
+
+      # prepare new request
+      new_req = Request.new(new_args)
+
+      # append self to redirection history
+      new_req.redirection_history = history + [self]
+
+      # execute redirected request
+      new_req.execute(&block)
+    end
+
+    def check_max_redirects
+      if request.max_redirects <= 0
+        raise exception_with_response
       end
-      out
     end
-  end
 
+    def exception_with_response
+      begin
+        klass = Exceptions::EXCEPTIONS_MAP.fetch(code)
+      rescue KeyError
+        raise RequestFailed.new(self, code)
+      end
+
+      raise klass.new(self, code)
+    end
+  end
 end

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,18 +52,21 @@ 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',
+              418 => 'I\'m A Teapot', #RFC2324
               421 => 'Too Many Connections From This IP',
               422 => 'Unprocessable Entity', #WebDAV
               423 => 'Locked', #WebDAV
               424 => 'Failed Dependency', #WebDAV
               425 => 'Unordered Collection', #WebDAV
               426 => 'Upgrade Required',
+              428 => 'Precondition Required', #RFC6585
+              429 => 'Too Many Requests', #RFC6585
+              431 => 'Request Header Fields Too Large', #RFC6585
               449 => 'Retry With', #Microsoft
               450 => 'Blocked By Windows Parental Controls', #Microsoft
 
@@ -58,20 +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'}
-
-  # 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
+              510 => 'Not Extended',
+              511 => 'Network Authentication Required', # RFC6585
+  }
+
+  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
@@ -81,15 +108,13 @@ module RestClient
   # probably an HTML error page) is e.response.
   class Exception < RuntimeError
     attr_accessor :response
-    attr_writer   :message
+    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
@@ -101,22 +126,25 @@ 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
@@ -126,7 +154,7 @@ module RestClient
   # 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
 
@@ -135,43 +163,68 @@ 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.
@@ -183,16 +236,9 @@ module RestClient
   end
 
   class SSLCertificateNotVerified < Exception
-    def initialize(message)
+    def initialize(message = 'SSL certificate not verified')
       super nil, nil
       self.message = message
     end
   end
 end
-
-# backwards compatibility
-class RestClient::Request
-  Redirect = RestClient::Redirect
-  Unauthorized = RestClient::Unauthorized
-  RequestFailed = RestClient::RequestFailed
-end