RubyGems - rest-client-next - Versions diffs - 1.1.0 → 1.3.0 - Mend

rest-client-next 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

data/README.rdoc +122 -7
data/Rakefile +4 -4
data/VERSION +1 -1
data/history.md +28 -0
data/lib/restclient.rb +83 -39
data/lib/restclient/exceptions.rb +114 -82
data/lib/restclient/mixin/response.rb +56 -40
data/lib/restclient/net_http_ext.rb +11 -11
data/lib/restclient/payload.rb +175 -168
data/lib/restclient/raw_response.rb +22 -22
data/lib/restclient/request.rb +272 -248
data/lib/restclient/resource.rb +133 -132
data/lib/restclient/response.rb +13 -13
data/spec/exceptions_spec.rb +48 -50
data/spec/integration_spec.rb +38 -0
data/spec/mixin/response_spec.rb +38 -38
data/spec/payload_spec.rb +98 -98
data/spec/raw_response_spec.rb +11 -11
data/spec/request_spec.rb +542 -493
data/spec/resource_spec.rb +95 -71
data/spec/response_spec.rb +68 -17
data/spec/restclient_spec.rb +59 -49
metadata +9 -5

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
@@ -8,10 +8,13 @@ of specifying actions: get, put, post, delete.
   require 'rest_client'
   RestClient.get 'http://example.com/resource'
   RestClient.get 'https://user:password@example.com/private/resource'
   RestClient.post 'http://example.com/resource', :param1 => 'one', :nested => { :param2 => 'two' }
+  RestClient.post "http://example.com/resource", { 'x' => 1 }.to_json, :content_type => :json, :accept => :json
   RestClient.delete 'http://example.com/resource'
 == Multipart
@@ -46,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.
@@ -55,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:
@@ -82,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,11 +4,11 @@ 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 = "adam@heroku.com"
-	s.homepage = "http://rest-client.heroku.com/"
+	s.email = "rest.client@librelist.com"
+	s.homepage = "http://github.com/archiloque/rest-client"
 	s.rubyforge_project = "rest-client"
 	s.has_rdoc = true
 	s.files = FileList["[A-Z]*", "{bin,lib,spec}/**/*"]

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 1.1.6
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

@@ -3,18 +3,18 @@ require 'zlib'
 require 'stringio'
 begin
-	require 'net/https'
+  require 'net/https'
 rescue LoadError => e
-	raise e unless RUBY_PLATFORM =~ /linux/
-	raise LoadError, "no such file to load -- net/https. Try running apt-get install libopenssl-ruby"
+  raise e unless RUBY_PLATFORM =~ /linux/
+  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'
@@ -63,45 +63,89 @@ require File.dirname(__FILE__) + '/restclient/net_http_ext'
 #   => "PUT http://rest-test.heroku.com/resource with a 7 byte payload, content type application/x-www-form-urlencoded {\"foo\"=>\"baz\"}"
 #
 module RestClient
-	def self.get(url, headers={})
-		Request.execute(:method => :get, :url => url, :headers => headers)
-	end
-	def self.post(url, payload, headers={})
-		Request.execute(:method => :post, :url => url, :payload => payload, :headers => headers)
-	end
-	def self.put(url, payload, headers={})
-		Request.execute(:method => :put, :url => url, :payload => payload, :headers => headers)
-	end
-	def self.delete(url, headers={})
-		Request.execute(:method => :delete, :url => url, :headers => headers)
-	end
-	def self.head(url, headers={})
-		Request.execute(:method => :head, :url => url, :headers => headers)
-	end
-	class << self
-		attr_accessor :proxy
-	end
-	# Print log of RestClient calls.  Value 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
-	end
+  def self.get(url, headers={}, &block)
+    Request.execute(:method => :get, :url => url, :headers => headers, &block)
+  end
+  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={}, &block)
+    Request.execute(:method => :put, :url => url, :payload => payload, :headers => headers, &block)
+  end
+  def self.delete(url, headers={}, &block)
+    Request.execute(:method => :delete, :url => url, :headers => headers, &block)
+  end
+  def self.head(url, headers={}, &block)
+    Request.execute(:method => :head, :url => url, :headers => headers, &block)
+  end
+  class << self
+    attr_accessor :proxy
+  end
+  # 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
+    if log.is_a? String
+      warn "[warning] You should set the log with a logger"
+    end
+    @@log = create_log log
+  end
   def self.version
     version_path = File.dirname(__FILE__) + "/../VERSION"
     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,88 +1,120 @@
 module RestClient
-	# This is the base RestClient exception class. Rescue it if you want to
-	# catch any exception that your request might raise
-	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
-		def initialize(response=nil)
-			@response = response
-		end
-		def http_code
-			@response.code.to_i if @response
-		end
-		def http_body
-			RestClient::Request.decode(@response['content-encoding'], @response.body) if @response
-		end
-	end
-	# A redirect was encountered; caught by execute to retry with the new url.
-	class Redirect < Exception
-		ErrorMessage = "Redirect"
-		attr_accessor :url
-		def initialize(url)
-			@url = url
-		end
-	end
-	class NotModified < ExceptionWithResponse
-		ErrorMessage = 'NotModified'
-	end
-	# Authorization is required to access the resource specified.
-	class Unauthorized < ExceptionWithResponse
-		ErrorMessage = 'Unauthorized'
-	end
-	# No resource was found at the given URL.
-	class ResourceNotFound < ExceptionWithResponse
-		ErrorMessage = 'Resource not found'
-	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'
-	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
+  # 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
+    attr_accessor :message, :response
+    def initialize response = nil
+      @response = response
+    end
+    def http_code
+      # return integer for compatibility
+      @response.code.to_i if @response
+    end
+    def http_body
+      @response
+    end
+    def inspect
+      "#{self.class} : #{http_code} #{message}"
+    end
+  end
+  # Compatibility
+  class ExceptionWithResponse < Exception
+  end
+  # The request failed with an error code not managed by the code
+  class RequestFailed < ExceptionWithResponse
+    def message
+      "HTTP status code #{http_code}"
+    end
+    def to_s
+      message
+    end
+  end
+  # 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
+  {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
+  # 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
+    message = 'Server broke connection'
+  end
 end
 # backwards compatibility
 class RestClient::Request
-	Redirect = RestClient::Redirect
-	Unauthorized = RestClient::Unauthorized
-	RequestFailed = RestClient::RequestFailed
+  Redirect = RestClient::Redirect
+  Unauthorized = RestClient::Unauthorized
+  RequestFailed = RestClient::RequestFailed
 end