rest-client 0.4 → 0.5

data/Rakefile

@@ -3,6 +3,7 @@ require 'spec/rake/spectask'
 
 desc "Run all specs"
 Spec::Rake::SpecTask.new('spec') do |t|
+	t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
 	t.spec_files = FileList['spec/*_spec.rb']
 end
 
@@ -30,14 +31,14 @@ require 'rake/gempackagetask'
 require 'rake/rdoctask'
 require 'fileutils'
 
-version = "0.4"
+version = "0.5"
 name = "rest-client"
 
 spec = Gem::Specification.new do |s|
 	s.name = name
 	s.version = version
 	s.summary = "Simple REST client for Ruby, inspired by microframework syntax for specifying actions."
-	s.description = "A simple REST client for Ruby, inspired by the microframework (Camping, Sinatra...) style of specifying actions: get, put, post, delete."
+	s.description = "A simple REST client for Ruby, inspired by the Sinatra microframework style of specifying actions: get, put, post, delete."
 	s.author = "Adam Wiggins"
 	s.email = "adam@heroku.com"
 	s.homepage = "http://rest-client.heroku.com/"

data/lib/request_errors.rb

@@ -0,0 +1,55 @@
+require 'rexml/document'
+
+module RestClient
+	# A redirect was encountered; caught by execute to retry with the new url.
+	class Redirect < RuntimeError; end
+
+	# Authorization is required to access the resource specified.
+	class Unauthorized < RuntimeError; end
+
+	# The server broke the connection prior to the request completing.
+	class ServerBrokeConnection < RuntimeError; end
+
+	# The server took too long to respond.
+	class RequestTimeout < RuntimeError; 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 < RuntimeError
+		attr_accessor :response
+
+		def initialize(response)
+			@response = response
+		end
+
+		def http_code
+			@response.code.to_i
+		end
+
+		def message(default="Unknown error, HTTP status code #{http_code}")
+			return "Resource not found" if http_code == 404
+			parse_error_xml rescue default
+		end
+
+		def parse_error_xml
+			xml_errors = REXML::Document.new(@response.body).elements.to_a("//errors/error")
+			xml_errors.empty? ? raise : xml_errors.map { |a| a.text }.join(" / ")
+		end
+
+		def to_s
+			message
+		end
+	end
+end
+
+# backwards compatibility
+RestClient::Resource::Redirect = RestClient::Redirect
+RestClient::Resource::Unauthorized = RestClient::Unauthorized
+RestClient::Resource::RequestFailed = RestClient::RequestFailed

data/lib/resource.rb

@@ -12,6 +12,11 @@ module RestClient
 	#   resource = RestClient::Resource.new('http://protected/resource', 'user', 'pass')
 	#   resource.delete
 	#
+	# Use the [] syntax to allocate subresources:
+	#
+	#   site = RestClient::Resource.new('http://example.com', 'adam', 'mypasswd')
+	#   site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+	#
 	class Resource
 		attr_reader :url, :user, :password
 
@@ -54,5 +59,43 @@ module RestClient
 				:password => password,
 				:headers => headers)
 		end
+
+		# Construct a subresource, preserving authentication.
+		#
+		# Example:
+		#
+		#   site = RestClient::Resource.new('http://example.com', 'adam', 'mypasswd')
+		#   site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+		#
+		# This is especially useful if you wish to define your site in one place and
+		# call it in multiple locations:
+		#
+		#   def product(id)
+		#     RestClient::Resource.new('http://example.com/products/#{id}', 'adam', 'mypasswd')
+		#   end
+		#
+		#   product(123).get
+		#   product(123).put params.to_xml
+		#   product(123).delete
+		#
+		# Nest resources as far as you want:
+		#
+		#   site = RestClient::Resource.new('http://example.com')
+		#   posts = site['posts']
+		#   first_post = posts['1']
+		#   comments = first_post['comments']
+		#   comments.post 'Hello', :content_type => 'text/plain'
+		#
+		def [](suburl)
+			self.class.new(concat_urls(url, suburl), user, password)
+		end
+
+		def concat_urls(url, suburl)   # :nodoc:
+			if url.slice(-1, 1) == '/' or suburl.slice(0, 1) == '/'
+				"#{url}#{suburl}"
+			else
+				"#{url}/#{suburl}"
+			end
+		end
 	end
 end

data/lib/rest_client.rb

@@ -1,7 +1,8 @@
 require 'uri'
-require 'net/http'
+require 'net/https'
 
 require File.dirname(__FILE__) + '/resource'
+require File.dirname(__FILE__) + '/request_errors'
 
 # This module's static methods are the entry point for using the REST client.
 module RestClient
@@ -11,9 +12,6 @@ module RestClient
 			:headers => headers)
 	end
 
-	# Payload can either be a string or a hash.  If it is a hash, your
-	# content-type will be set to www-form-urlencoded and the parameters
-	# converted to a CGI encoded string.
 	def self.post(url, payload, headers={})
 		Request.execute(:method => :post,
 			:url => url,
@@ -59,7 +57,7 @@ module RestClient
 		end
 
 		def execute_inner
-			uri = parse_url(url)
+			uri = parse_url_with_auth(url)
 			transmit uri, net_http_class(method).new(uri.request_uri, make_headers(headers)), payload
 		end
 
@@ -81,30 +79,38 @@ module RestClient
 			URI.parse(url)
 		end
 
-		# A redirect was encountered; caught by execute to retry with the new url.
-		class Redirect < Exception; end
-
-		# Request failed with an unhandled http error code.
-		class RequestFailed < Exception; end
-
-		# Authorization is required to access the resource specified.
-		class Unauthorized < Exception; end
+		def parse_url_with_auth(url)
+			uri = parse_url(url)
+			@user = uri.user if uri.user
+			@password = uri.password if uri.password
+			uri
+		end
 
 		def process_payload(p=nil)
 			unless p.is_a?(Hash)
 				p
 			else
 				@headers[:content_type] = 'application/x-www-form-urlencoded'
-				p.keys.map { |k| "#{k}=#{URI.escape(p[k].to_s)}" }.join("&")
+				p.keys.map do |k|
+					v = URI.escape(p[k].to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+					"#{k}=#{v}"
+				end.join("&")
 			end
 		end
 
 		def transmit(uri, req, payload)
 			setup_credentials(req)
 
-			Net::HTTP.start(uri.host, uri.port) do |http|
+			net = Net::HTTP.new(uri.host, uri.port)
+			net.use_ssl = uri.is_a?(URI::HTTPS)
+
+			net.start do |http|
 				process_result http.request(req, payload || "")
 			end
+		rescue EOFError
+			raise RestClient::ServerBrokeConnection
+		rescue Timeout::Error
+			raise RestClient::RequestTimeout
 		end
 
 		def setup_credentials(req)
@@ -119,14 +125,10 @@ module RestClient
 			elsif res.code == "401"
 				raise Unauthorized
 			else
-				raise RequestFailed, error_message(res)
+				raise RequestFailed, res
 			end
 		end
 
-		def error_message(res)
-			"HTTP code #{res.code}: #{res.body}"
-		end
-
 		def default_headers
 			{ :accept => 'application/xml' }
 		end

data/spec/request_errors_spec.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/base'
+
+describe RestClient::RequestFailed do
+	before do
+		@error = RestClient::RequestFailed.new(nil)
+	end
+
+	it "extracts the error message from xml" do
+		@error.response = mock('response', :code => '422', :body => '<errors><error>Error 1</error><error>Error 2</error></errors>')
+		@error.message.should == 'Error 1 / Error 2'
+	end
+
+	it "ignores responses without xml since they might contain sensitive data" do
+		@error.response = mock('response', :code => '500', :body => 'Syntax error in SQL query: SELECT * FROM ...')
+		@error.message.should == 'Unknown error, HTTP status code 500'
+	end
+
+	it "accepts a default error message" do
+		@error.response = mock('response', :code => '500', :body => 'Internal Server Error')
+		@error.message('Custom default message').should == 'Custom default message'
+	end
+
+	it "doesn't show the default error message when there's something in the xml" do
+		@error.response = mock('response', :code => '422', :body => '<errors><error>Specific error message</error></errors>')
+		@error.message('Custom default message').should == 'Specific error message'
+	end
+end
+
+describe "backwards compatibility" do
+	it "alias RestClient::Resource::Redirect to RestClient::Redirect" do
+		RestClient::Resource::Redirect.should == RestClient::Redirect
+	end
+
+	it "alias RestClient::Resource::Unauthorized to RestClient::Unauthorized" do
+		RestClient::Resource::Unauthorized.should == RestClient::Unauthorized
+	end
+
+	it "alias RestClient::Resource::RequestFailed to RestClient::RequestFailed" do
+		RestClient::Resource::RequestFailed.should == RestClient::RequestFailed
+	end
+end

data/spec/resource_spec.rb

@@ -28,4 +28,25 @@ describe RestClient::Resource do
 	it "can instantiate with no user/password" do
 		@resource = RestClient::Resource.new('http://some/resource')
 	end
+
+	it "concatinates urls, inserting a slash when it needs one" do
+		@resource.concat_urls('http://example.com', 'resource').should == 'http://example.com/resource'
+	end
+
+	it "concatinates urls, using no slash if the first url ends with a slash" do
+		@resource.concat_urls('http://example.com/', 'resource').should == 'http://example.com/resource'
+	end
+
+	it "concatinates urls, using no slash if the second url starts with a slash" do
+		@resource.concat_urls('http://example.com', '/resource').should == 'http://example.com/resource'
+	end
+
+	it "concatinates even non-string urls (i.e. 'posts' + 1)" do
+		@resource.concat_urls('posts/', 1).should == 'posts/1'
+	end
+
+	it "offers subresources via []" do
+		parent = RestClient::Resource.new('http://example.com')
+		parent['posts'].url.should == 'http://example.com/posts'
+	end
 end

data/spec/rest_client_spec.rb

@@ -31,6 +31,12 @@ describe RestClient do
 			@uri.stub!(:request_uri).and_return('/resource')
 			@uri.stub!(:host).and_return('some')
 			@uri.stub!(:port).and_return(80)
+
+			@net = mock("net::http base")
+			@http = mock("net::http connection")
+			Net::HTTP.stub!(:new).and_return(@net)
+			@net.stub!(:start).and_yield(@http)
+			@net.stub!(:use_ssl=)
 		end
 
 		it "requests xml mimetype" do
@@ -54,6 +60,21 @@ describe RestClient do
 			@request.parse_url('example.com/resource')
 		end
 
+		it "extracts the username and password when parsing http://user:password@example.com/" do
+			URI.stub!(:parse).and_return(mock('uri', :user => 'joe', :password => 'pass1'))
+			@request.parse_url_with_auth('http://joe:pass1@example.com/resource')
+			@request.user.should == 'joe'
+			@request.password.should == 'pass1'
+		end
+
+		it "doesn't overwrite user and password (which may have already been set by the Resource constructor) if there is no user/password in the url" do
+			URI.stub!(:parse).and_return(mock('uri', :user => nil, :password => nil))
+			@request = RestClient::Request.new(:method => 'get', :url => 'example.com', :user => 'beth', :password => 'pass2')
+			@request.parse_url_with_auth('http://example.com/resource')
+			@request.user.should == 'beth'
+			@request.password.should == 'pass2'
+		end
+
 		it "determines the Net::HTTP class to instantiate by the method name" do
 			@request.net_http_class(:put).should == Net::HTTP::Put
 		end
@@ -74,7 +95,7 @@ describe RestClient do
 		end
 
 		it "executes by constructing the Net::HTTP object, headers, and payload and calling transmit" do
-			@request.should_receive(:parse_url).with('http://some/resource').and_return(@uri)
+			@request.should_receive(:parse_url_with_auth).with('http://some/resource').and_return(@uri)
 			klass = mock("net:http class")
 			@request.should_receive(:net_http_class).with(:put).and_return(klass)
 			klass.should_receive(:new).and_return('result')
@@ -83,17 +104,21 @@ describe RestClient do
 		end
 
 		it "transmits the request with Net::HTTP" do
-			http = mock("net::http connection")
-			Net::HTTP.should_receive(:start).and_yield(http)
-			http.should_receive(:request).with('req', 'payload')
+			@http.should_receive(:request).with('req', 'payload')
 			@request.should_receive(:process_result)
 			@request.transmit(@uri, 'req', 'payload')
 		end
 
+		it "uses SSL when the URI refers to a https address" do
+			@uri.stub!(:is_a?).with(URI::HTTPS).and_return(true)
+			@net.should_receive(:use_ssl=).with(true)
+			@http.stub!(:request)
+			@request.stub!(:process_result)
+			@request.transmit(@uri, 'req', 'payload')
+		end
+
 		it "doesn't send nil payloads" do
-			http = mock("net::http connection")
-			Net::HTTP.should_receive(:start).and_yield(http)
-			http.should_receive(:request).with('req', '')
+			@http.should_receive(:request).with('req', '')
 			@request.should_receive(:process_result)
 			@request.transmit(@uri, 'req', nil)
 		end
@@ -103,7 +128,7 @@ describe RestClient do
 		end
 
 		it "converts a hash payload to urlencoded data" do
-			@request.process_payload(:a => 'b c').should == "a=b%20c"
+			@request.process_payload(:a => 'b c+d').should == "a=b%20c%2Bd"
 		end
 
 		it "set urlencoded content_type header on hash payloads" do
@@ -112,9 +137,7 @@ describe RestClient do
 		end
 
 		it "sets up the credentials prior to the request" do
-			http = mock("net::http connection")
-			Net::HTTP.should_receive(:start).and_yield(http)
-			http.stub!(:request)
+			@http.stub!(:request)
 			@request.stub!(:process_result)
 
 			@request.stub!(:user).and_return('joe')
@@ -131,7 +154,7 @@ describe RestClient do
 			@request.setup_credentials(req)
 		end
 
-		it "does not attempt to send any credentials if user is nil" do
+		it "setup credentials when there's a user" do
 			@request.stub!(:user).and_return('joe')
 			@request.stub!(:password).and_return('mypass')
 			req = mock("request")
@@ -139,6 +162,11 @@ describe RestClient do
 			@request.setup_credentials(req)
 		end
 
+		it "catches EOFError and shows the more informative ServerBrokeConnection" do
+			@http.stub!(:request).and_raise(EOFError)
+			lambda { @request.transmit(@uri, 'req', nil) }.should raise_error(RestClient::ServerBrokeConnection)
+		end
+
 		it "execute calls execute_inner" do
 			@request.should_receive(:execute_inner)
 			@request.execute
@@ -150,5 +178,20 @@ describe RestClient do
 			req.should_receive(:execute)
 			RestClient::Request.execute(1 => 2)
 		end
+
+		it "raises a Redirect with the new location when the response is in the 30x range" do
+			res = mock('response', :code => '301', :header => { 'Location' => 'http://new/resource' })
+			lambda { @request.process_result(res) }.should raise_error(RestClient::Redirect, 'http://new/resource')
+		end
+
+		it "raises Unauthorized when the response is 401" do
+			res = mock('response', :code => '401')
+			lambda { @request.process_result(res) }.should raise_error(RestClient::Unauthorized)
+		end
+
+		it "raises RequestFailed otherwise" do
+			res = mock('response', :code => '500')
+			lambda { @request.process_result(res) }.should raise_error(RestClient::RequestFailed)
+		end
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rest-client
 version: !ruby/object:Gem::Version 
-  version: "0.4"
+  version: "0.5"
 platform: ruby
 authors: 
 - Adam Wiggins
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-04-04 00:00:00 -07:00
+date: 2008-06-20 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: "A simple REST client for Ruby, inspired by the microframework (Camping, Sinatra...) style of specifying actions: get, put, post, delete."
+description: "A simple REST client for Ruby, inspired by the Sinatra microframework style of specifying actions: get, put, post, delete."
 email: adam@heroku.com
 executables: []
 
@@ -25,7 +25,9 @@ files:
 - Rakefile
 - lib/resource.rb
 - lib/rest_client.rb
+- lib/request_errors.rb
 - spec/resource_spec.rb
+- spec/request_errors_spec.rb
 - spec/rest_client_spec.rb
 - spec/base.rb
 has_rdoc: true
@@ -50,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rest-client
-rubygems_version: 1.0.0
+rubygems_version: 1.1.1
 signing_key: 
 specification_version: 2
 summary: Simple REST client for Ruby, inspired by microframework syntax for specifying actions.