RubyGems - rest-client - Versions diffs - 1.2.0 → 1.3.0 - Mend

rest-client 1.2.0 → 1.3.0

Potentially problematic release.

This version of rest-client might be problematic. Click here for more details.

Files changed (19) hide show

data/README.rdoc +119 -7
data/Rakefile +2 -2
data/VERSION +1 -1
data/history.md +28 -0
data/lib/restclient.rb +63 -20
data/lib/restclient/exceptions.rb +77 -46
data/lib/restclient/mixin/response.rb +23 -7
data/lib/restclient/payload.rb +2 -2
data/lib/restclient/request.rb +60 -71
data/lib/restclient/resource.rb +11 -10
data/spec/exceptions_spec.rb +3 -5
data/spec/integration_spec.rb +38 -0
data/spec/mixin/response_spec.rb +1 -1
data/spec/payload_spec.rb +6 -6
data/spec/request_spec.rb +357 -332
data/spec/resource_spec.rb +24 -0
data/spec/response_spec.rb +51 -0
data/spec/restclient_spec.rb +21 -11
metadata +8 -4

data/README.rdoc CHANGED

@@ -1,6 +1,6 @@
-= REST Client -- simple DSL for accessing REST resources
+= REST Client -- simple DSL for accessing HTTP and REST resources
-A simple REST client for Ruby, inspired by the Sinatra's microframework style
+A simple HTTP and REST client for Ruby, inspired by the Sinatra's microframework style
 of specifying actions: get, put, post, delete.
 == Usage: Raw URL
@@ -49,6 +49,51 @@ See RestClient::Resource module docs for details.
 See RestClient::Resource docs for details.
+== Exceptions
+* for results code between 200 and 206 a RestClient::Response will be returned
+* for results code between 301 and 303 the redirection will be automatically followed
+* for other result codes a RestClient::Exception holding the Response will be raised, a specific exception class will be thrown for know error codes
+   RestClient.get 'http://example.com/resource'
+   ➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound
+   begin
+     RestClient.get 'http://example.com/resource'
+   rescue => e
+     e.response
+   end
+   ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+== Result handling
+A block can be passed to the RestClient method, this block will then be called with the Response.
+Response.return! can be called to invoke the default response's behavior (return the Response for 200..206, raise an exception in other cases).
+  # Don't raise exceptions but return the response
+  RestClient.get('http://example.com/resource'){|response| response}
+  ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+  # Manage a specific error code
+  RestClient.get('http://my-rest-service.com/resource'){ |response|
+    case response.code
+    when 200
+      p "It worked !"
+      response
+    when 423
+      raise SomeCustomExceptionIfYouWant
+    else
+      response.return!
+    end
+  }
+== Non-normalized URIs.
+If you want to use non-normalized URIs, you can normalize them with the addressable gem (http://addressable.rubyforge.org/api/).
+  require 'addressable/uri'
+  RestClient.get(Addressable::URI.parse("http://www.詹姆斯.com/").normalize.to_str)
 == Lower-level access
 For cases not covered by the general API, you can use the RestClient::Resource class which provide a lower-level API, see the class' rdoc for more information.
@@ -58,17 +103,17 @@ For cases not covered by the general API, you can use the RestClient::Resource c
 The restclient shell command gives an IRB session with RestClient already loaded:
   $ restclient
-  >> RestClient.get 'http://example.com'
+  ➔ RestClient.get 'http://example.com'
 Specify a URL argument for get/post/put/delete on that resource:
   $ restclient http://example.com
-  >> put '/resource', 'data'
+  ➔ put '/resource', 'data'
 Add a user and password for authenticated resources:
   $ restclient https://example.com user pass
-  >> delete '/private/resource'
+  ➔ delete '/private/resource'
 Create ~/.restclient for named sessions:
@@ -85,11 +130,78 @@ Then invoke:
   $ restclient private_site
+Use as a one-off, curl-style:
+  $ restclient get http://example.com/resource > output_body
+  $ restclient put http://example.com/resource < input_body
+== Logging
+To enable logging you can
+* set RestClient.log with a ruby Logger
+* or set an environment variable to avoid modifying the code (in this case you can use a file name, "stdout" or "stderr"):
+   $ RESTCLIENT_LOG=stdout path/to/my/program
+Either produces logs like this:
+  RestClient.get "http://some/resource"
+  # => 200 OK | text/html 250 bytes
+  RestClient.put "http://some/resource", "payload"
+  # => 401 Unauthorized | application/xml 340 bytes
+Note that these logs are valid Ruby, so you can paste them into the restclient
+shell or a script to replay your sequence of rest calls.
+== Proxy
+All calls to RestClient, including Resources, will use the proxy specified by
+RestClient.proxy:
+  RestClient.proxy = "http://proxy.example.com/"
+  RestClient.get "http://some/resource"
+  # => response from some/resource as proxied through proxy.example.com
+Often the proxy url is set in an environment variable, so you can do this to
+use whatever proxy the system is configured to use:
+  RestClient.proxy = ENV['http_proxy']
+== Cookies
+Request and Response objects know about HTTP cookies, and will automatically
+extract and set headers for them as needed:
+  response = RestClient.get 'http://example.com/action_which_sets_session_id'
+  response.cookies
+  # => {"_applicatioN_session_id" => "1234"}
+  response2 = RestClient.post(
+    'http://localhost:3000/',
+    {:param1 => "foo"},
+    {:cookies => {:session_id => "1234"}}
+  )
+  # ...response body
+== SSL Client Certificates
+  RestClient::Resource.new(
+    'https://example.com',
+    :ssl_client_cert  =>  OpenSSL::X509::Certificate.new(File.read("cert.pem")),
+    :ssl_client_key   =>  OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),
+    :ssl_ca_file      =>  "ca_certificate.pem",
+    :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER
+  ).get
+Self-signed certificates can be generated with the openssl command-line tool.
 == Meta
-Written by Adam Wiggins, major modifications by Blake Mizerany, maintained by Archiloque
+Written by Adam Wiggins, major modifications by Blake Mizerany, maintained by Julien Kirch
-Patches contributed by: Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, François Beausoleil and Nick Plante.
+Patches contributed by many, including Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, François Beausoleil and Nick Plante.
 Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

data/Rakefile CHANGED

@@ -4,8 +4,8 @@ require 'jeweler'
 Jeweler::Tasks.new do |s|
 	s.name = "rest-client"
-	s.description = "A simple REST client for Ruby, inspired by the Sinatra microframework style of specifying actions: get, put, post, delete."
-	s.summary = "Simple REST client for Ruby, inspired by microframework syntax for specifying actions."
+	s.description = "A simple HTTP and REST client for Ruby, inspired by the Sinatra microframework style of specifying actions: get, put, post, delete."
+	s.summary = "Simple HTTP and REST client for Ruby, inspired by microframework syntax for specifying actions."
 	s.author = "Adam Wiggins"
 	s.email = "rest.client@librelist.com"
 	s.homepage = "http://github.com/archiloque/rest-client"

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 1.2.0
1	+ 1.3.0

data/history.md ADDED

@@ -0,0 +1,28 @@
+# 1.3.0
+- a block can be used to process a request's result, this enable to handle custom error codes or paththrought (design by Cyril Rohr)
+- cleaner log API, add a warning for some cases but should be compatible
+- accept multiple "Set-Cookie" headers, see http://www.ietf.org/rfc/rfc2109.txt (patch provided by Cyril Rohr)
+- remove "Content-Length" and "Content-Type" headers when following a redirection (patch provided by haarts)
+- all http error codes have now a corresponding exception class and all of them contain the Reponse -> this means that the raised exception can be different
+- changed "Content-Disposition: multipart/form-data" to "Content-Disposition: form-data" per RFC 2388 (patch provided by Kyle Crawford)
+# 1.2.0
+- formatting changed from tabs to spaces
+- logged requests now include generated headers
+- accept and content-type headers can now be specified using extentions: RestClient.post "http://example.com/resource", { 'x' => 1 }.to_json, :content_type => :json, :accept => :json
+- should be 1.1.1 but renamed to 1.2.0 because 1.1.X versions has already been packaged on Debian
+# 1.1.0
+- new maintainer: Archiloque, the working repo is now at http://github.com/archiloque/rest-client
+- a mailing list has been created at rest.client@librelist.com and an freenode irc channel #rest-client
+- François Beausoleil' multipart code from http://github.com/francois/rest-client has been merged
+- ability to use hash in hash as payload
+- the mime-type code now rely on the mime-types gem http://mime-types.rubyforge.org/ instead of an internal partial list
+- 204 response returns a Response instead of nil (patch provided by Elliott Draper)
+All changes exept the last one should be fully compatible with the previous version.
+NOTE: due to a dependency problem and to the last change, heroku users should update their heroku gem to >= 1.5.3 to be able to use this version.

data/lib/restclient.rb CHANGED

@@ -9,12 +9,12 @@ rescue LoadError => e
   raise LoadError, "no such file to load -- net/https. Try running apt-get install libopenssl-ruby"
 end
+require File.dirname(__FILE__) + '/restclient/exceptions'
 require File.dirname(__FILE__) + '/restclient/request'
 require File.dirname(__FILE__) + '/restclient/mixin/response'
 require File.dirname(__FILE__) + '/restclient/response'
 require File.dirname(__FILE__) + '/restclient/raw_response'
 require File.dirname(__FILE__) + '/restclient/resource'
-require File.dirname(__FILE__) + '/restclient/exceptions'
 require File.dirname(__FILE__) + '/restclient/payload'
 require File.dirname(__FILE__) + '/restclient/net_http_ext'
@@ -64,40 +64,38 @@ require File.dirname(__FILE__) + '/restclient/net_http_ext'
 #
 module RestClient
-  def self.get(url, headers={})
-    Request.execute(:method => :get, :url => url, :headers => headers)
+  def self.get(url, headers={}, &block)
+    Request.execute(:method => :get, :url => url, :headers => headers, &block)
   end
-  def self.post(url, payload, headers={})
-    Request.execute(:method => :post, :url => url, :payload => payload, :headers => headers)
+  def self.post(url, payload, headers={}, &block)
+    Request.execute(:method => :post, :url => url, :payload => payload, :headers => headers, &block)
   end
-  def self.put(url, payload, headers={})
-    Request.execute(:method => :put, :url => url, :payload => payload, :headers => headers)
+  def self.put(url, payload, headers={}, &block)
+    Request.execute(:method => :put, :url => url, :payload => payload, :headers => headers, &block)
   end
-  def self.delete(url, headers={})
-    Request.execute(:method => :delete, :url => url, :headers => headers)
+  def self.delete(url, headers={}, &block)
+    Request.execute(:method => :delete, :url => url, :headers => headers, &block)
   end
-  def self.head(url, headers={})
-    Request.execute(:method => :head, :url => url, :headers => headers)
+  def self.head(url, headers={}, &block)
+    Request.execute(:method => :head, :url => url, :headers => headers, &block)
   end
   class << self
     attr_accessor :proxy
   end
-  # Print log of RestClient calls.  Value can be stdout, stderr, or a filename.
+  # Setup the log for RestClient calls.
+  # Value should be a logger but can can be stdout, stderr, or a filename.
   # You can also configure logging by the environment variable RESTCLIENT_LOG.
-  def self.log=(log)
-    @@log = log
-  end
-  def self.log # :nodoc:
-    return ENV['RESTCLIENT_LOG'] if ENV['RESTCLIENT_LOG']
-    return @@log if defined? @@log
-    nil
+  def self.log= log
+    if log.is_a? String
+      warn "[warning] You should set the log with a logger"
+    end
+    @@log = create_log log
   end
   def self.version
@@ -105,4 +103,49 @@ module RestClient
     return File.read(version_path).chomp if File.file?(version_path)
     "0.0.0"
   end
+  # Create a log that respond to << like a logger
+  # param can be 'stdout', 'stderr', a string (then we will log to that file) or a logger (then we return it)
+  def self.create_log param
+    if param
+      if param.is_a? String
+        if param == 'stdout'
+          stdout_logger = Class.new do
+            def << obj
+              STDOUT.puts obj
+            end
+          end
+          stdout_logger.new
+        elsif param == 'stderr'
+          stderr_logger = Class.new do
+            def << obj
+              STDERR.puts obj
+            end
+          end
+          stderr_logger.new
+        else
+          file_logger = Class.new do
+            attr_writer :target_file
+            def << obj
+              File.open(@target_file, 'a') { |f| f.puts obj }
+            end
+          end
+          logger = file_logger.new
+          logger.target_file = param
+          logger
+        end
+      else
+        param
+      end
+    end
+  end
+  @@env_log = create_log ENV['RESTCLIENT_LOG']
+  @@log = nil
+  def self.log # :nodoc:
+    @@env_log || @@log
+  end
 end

data/lib/restclient/exceptions.rb CHANGED

@@ -1,84 +1,115 @@
 module RestClient
   # This is the base RestClient exception class. Rescue it if you want to
   # catch any exception that your request might raise
+  # You can get the status code by e.http_code, or see anything about the
+  # response via e.response.
+  # For example, the entire result body (which is
+  # probably an HTML error page) is e.response.
   class Exception < RuntimeError
-    def message(default=nil)
-      self.class::ErrorMessage
-    end
-  end
-  # Base RestClient exception when there's a response available
-  class ExceptionWithResponse < Exception
-    attr_accessor :response
+    attr_accessor :message, :response
-    def initialize(response=nil)
+    def initialize response = nil
       @response = response
     end
     def http_code
+      # return integer for compatibility
       @response.code.to_i if @response
     end
     def http_body
-      RestClient::Request.decode(@response['content-encoding'], @response.body) if @response
+      @response
     end
+    def inspect
+      "#{self.class} : #{http_code} #{message}"
+    end
   end
-  # A redirect was encountered; caught by execute to retry with the new url.
-  class Redirect < Exception
-    ErrorMessage = "Redirect"
+  # Compatibility
+  class ExceptionWithResponse < Exception
+  end
-    attr_accessor :url
+  # The request failed with an error code not managed by the code
+  class RequestFailed < ExceptionWithResponse
-    def initialize(url)
-      @url = url
+    def message
+      "HTTP status code #{http_code}"
+    end
+    def to_s
+      message
     end
   end
-  class NotModified < ExceptionWithResponse
-    ErrorMessage = 'NotModified'
+  # 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
-  # Authorization is required to access the resource specified.
-  class Unauthorized < ExceptionWithResponse
-    ErrorMessage = 'Unauthorized'
+  {300 => 'Multiple Choices',
+   301 => 'Moved Permanently',
+   302 => 'Found',
+   303 => 'See Other',
+   304 => 'Not Modified',
+   305 => 'Use Proxy',
+   400 => 'Bad Request',
+   401 => 'Unauthorized',
+   403 => 'Forbidden',
+   404 => 'Resource Not Found',
+   405 => 'Method Not Allowed',
+   406 => 'Not Acceptable',
+   407 => 'Proxy Authentication Required',
+   408 => 'Request Timeout',
+   409 => 'Conflict',
+   410 => 'Gone',
+   411 => 'Length Required',
+   412 => 'Precondition Failed',
+   413 => 'Request Entity Too Large',
+   414 => 'Request-URI Too Long',
+   415 => 'Unsupported Media Type',
+   416 => 'Requested Range Not Satisfiable',
+   417 => 'Expectation Failed',
+   500 => 'Internal Server Error',
+   501 => 'Not Implemented',
+   502 => 'Bad Gateway',
+   503 => 'Service Unavailable',
+   504 => 'Gateway Timeout',
+   505 => 'HTTP Version Not Supported'}.each_pair do |code, message|
+    # Compatibility
+    superclass = ([304, 401, 404].include? code) ? ExceptionWithResponse : RequestFailed
+    klass = Class.new(superclass) do
+      send(:define_method, :message) {message}
+    end
+    klass_constant = const_set message.gsub(/ /, '').gsub(/-/, ''), klass
+    Exceptions::EXCEPTIONS_MAP[code] = klass_constant
   end
-  # No resource was found at the given URL.
-  class ResourceNotFound < ExceptionWithResponse
-    ErrorMessage = 'Resource not found'
+  # A redirect was encountered; caught by execute to retry with the new url.
+  class Redirect < Exception
+    message = 'Redirect'
+    attr_accessor :url
+    def initialize(url)
+      @url = url
+    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
-    ErrorMessage = 'Server broke connection'
+    message = 'Server broke connection'
   end
-  # The server took too long to respond.
-  class RequestTimeout < Exception
-    ErrorMessage = 'Request timed out'
-  end
-  # The request failed, meaning the remote HTTP server returned a code other
-  # than success, unauthorized, or redirect.
-  #
-  # The exception message attempts to extract the error from the XML, using
-  # format returned by Rails: <errors><error>some message</error></errors>
-  #
-  # You can get the status code by e.http_code, or see anything about the
-  # response via e.response.  For example, the entire result body (which is
-  # probably an HTML error page) is e.response.body.
-  class RequestFailed < ExceptionWithResponse
-    def message
-      "HTTP status code #{http_code}"
-    end
-    def to_s
-      message
-    end
-  end
 end
 # backwards compatibility