rest-client 0.8.2 → 0.9

data/Rakefile

@@ -31,7 +31,7 @@ require 'rake/gempackagetask'
 require 'rake/rdoctask'
 require 'fileutils'
 
-version = "0.8.2"
+version = "0.9"
 name = "rest-client"
 
 spec = Gem::Specification.new do |s|
@@ -76,8 +76,9 @@ Rake::RDocTask.new do |t|
 	t.title    = "rest-client, fetch RESTful resources effortlessly"
 	t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
 	t.options << '--charset' << 'utf-8'
-	t.rdoc_files.include('README')
-	t.rdoc_files.include('lib/*.rb')
+	t.rdoc_files.include('README.rdoc')
+	t.rdoc_files.include('lib/restclient.rb')
+	t.rdoc_files.include('lib/restclient/*.rb')
 end
 
 CLEAN.include [ 'pkg', '*.gem', '.config' ]

data/bin/restclient

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 $:.unshift File.dirname(__FILE__) + "/../lib"
-require 'rest_client'
+require 'restclient'
 
 require "yaml"
 

data/lib/rest_client.rb

@@ -1,250 +1,2 @@
-require 'uri'
-require 'net/https'
-require 'zlib'
-require 'stringio'
-
-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.
-#
-#   # GET
-#   xml = RestClient.get 'http://example.com/resource'
-#   jpg = RestClient.get 'http://example.com/resource', :accept => 'image/jpg'
-#
-#   # authentication and SSL
-#   RestClient.get 'https://user:password@example.com/private/resource'
-#
-#   # POST or PUT with a hash sends parameters as a urlencoded form body
-#   RestClient.post 'http://example.com/resource', :param1 => 'one'
-#
-#   # nest hash parameters
-#   RestClient.post 'http://example.com/resource', :nested => { :param1 => 'one' }
-#
-#   # POST and PUT with raw payloads
-#   RestClient.post 'http://example.com/resource', 'the post body', :content_type => 'text/plain'
-#   RestClient.post 'http://example.com/resource.xml', xml_doc
-#   RestClient.put 'http://example.com/resource.pdf', File.read('my.pdf'), :content_type => 'application/pdf'
-#
-#   # DELETE
-#   RestClient.delete 'http://example.com/resource'
-#
-# To use with a proxy, just set RestClient.proxy to the proper http proxy:
-#
-#   RestClient.proxy = "http://proxy.example.com/"
-#
-# Or inherit the proxy from the environment:
-#
-#   RestClient.proxy = ENV['http_proxy']
-#
-# For live tests of RestClient, try using http://rest-test.heroku.com, which echoes back information about the rest call:
-#
-#   >> RestClient.put 'http://rest-test.heroku.com/resource', :foo => 'baz'
-#   => "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
-
-	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
-
-	# Internal class used to build and execute the request.
-	class Request
-		attr_reader :method, :url, :payload, :headers, :user, :password
-
-		def self.execute(args)
-			new(args).execute
-		end
-
-		def initialize(args)
-			@method = args[:method] or raise ArgumentError, "must pass :method"
-			@url = args[:url] or raise ArgumentError, "must pass :url"
-			@headers = args[:headers] || {}
-			@payload = process_payload(args[:payload])
-			@user = args[:user]
-			@password = args[:password]
-		end
-
-		def execute
-			execute_inner
-		rescue Redirect => e
-			@url = e.url
-			execute
-		end
-
-		def execute_inner
-			uri = parse_url_with_auth(url)
-			transmit uri, net_http_request_class(method).new(uri.request_uri, make_headers(headers)), payload
-		end
-
-		def make_headers(user_headers)
-			default_headers.merge(user_headers).inject({}) do |final, (key, value)|
-				final[key.to_s.gsub(/_/, '-').capitalize] = value.to_s
-				final
-			end
-		end
-
-		def net_http_class
-			if RestClient.proxy
-				proxy_uri = URI.parse(RestClient.proxy)
-				Net::HTTP::Proxy(proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password)
-			else
-				Net::HTTP
-			end
-		end
-
-		def net_http_request_class(method)
-			Net::HTTP.const_get(method.to_s.capitalize)
-		end
-
-		def parse_url(url)
-			url = "http://#{url}" unless url.match(/^http/)
-			URI.parse(url)
-		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, parent_key=nil)
-			unless p.is_a?(Hash)
-				p
-			else
-				@headers[:content_type] ||= 'application/x-www-form-urlencoded'
-				p.keys.map do |k|
-					key = parent_key ? "#{parent_key}[#{k}]" : k
-					if p[k].is_a? Hash
-						process_payload(p[k], key)
-					else
-						value = URI.escape(p[k].to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
-						"#{key}=#{value}"
-					end
-				end.join("&")
-			end
-		end
-
-		def transmit(uri, req, payload)
-			setup_credentials(req)
-
-			net = net_http_class.new(uri.host, uri.port)
-			net.use_ssl = uri.is_a?(URI::HTTPS)
-			net.verify_mode = OpenSSL::SSL::VERIFY_NONE
-
-			display_log request_log
-
-			net.start do |http|
-				res = http.request(req, payload || "")
-				display_log response_log(res)
-				process_result res
-			end
-		rescue EOFError
-			raise RestClient::ServerBrokeConnection
-		rescue Timeout::Error
-			raise RestClient::RequestTimeout
-		end
-
-		def setup_credentials(req)
-			req.basic_auth(user, password) if user
-		end
-
-		def process_result(res)
-			if %w(200 201 202).include? res.code
-				decode res['content-encoding'], res.body
-			elsif %w(301 302 303).include? res.code
-				url = res.header['Location']
-
-				if url !~ /^http/
-					uri = URI.parse(@url)
-					uri.path = "/#{url}".squeeze('/')
-					url = uri.to_s
-				end
-
-				raise Redirect, url
-			elsif res.code == "401"
-				raise Unauthorized, res
-			elsif res.code == "404"
-				raise ResourceNotFound, res
-			else
-				raise RequestFailed, res
-			end
-		end
-
-		def decode(content_encoding, body)
-			if content_encoding == 'gzip'
-				Zlib::GzipReader.new(StringIO.new(body)).read
-			elsif content_encoding == 'deflate'
-				Zlib::Inflate.new.inflate(body)
-			else
-				body
-			end
-		end
-
-		def request_log
-			out = []
-			out << "RestClient.#{method} #{url.inspect}"
-			out << (payload.size > 100 ? "(#{payload.size} byte payload)".inspect : payload.inspect) if payload
-			out << headers.inspect.gsub(/^\{/, '').gsub(/\}$/, '') unless headers.empty?
-			out.join(', ')
-		end
-
-		def response_log(res)
-			"# => #{res.code} #{res.class.to_s.gsub(/^Net::HTTP/, '')} | #{(res['Content-type'] || '').gsub(/;.*$/, '')} #{res.body.size} bytes"
-		end
-
-		def display_log(msg)
-			return unless log_to = RestClient.log
-
-			if log_to == 'stdout'
-				STDOUT.puts msg
-			elsif log_to == 'stderr'
-				STDERR.puts msg
-			else
-				File.open(log_to, 'a') { |f| f.puts msg }
-			end
-		end
-
-		def default_headers
-			{ :accept => 'application/xml', :accept_encoding => 'gzip, deflate' }
-		end
-	end
-end
+# This file exists for backward compatbility with require 'rest_client'
+require File.dirname(__FILE__) + '/restclient'

data/lib/restclient.rb

@@ -0,0 +1,83 @@
+require 'uri'
+require 'net/https'
+require 'zlib'
+require 'stringio'
+
+require File.dirname(__FILE__) + '/restclient/request'
+require File.dirname(__FILE__) + '/restclient/response'
+require File.dirname(__FILE__) + '/restclient/resource'
+require File.dirname(__FILE__) + '/restclient/exceptions'
+
+# This module's static methods are the entry point for using the REST client.
+#
+#   # GET
+#   xml = RestClient.get 'http://example.com/resource'
+#   jpg = RestClient.get 'http://example.com/resource', :accept => 'image/jpg'
+#
+#   # authentication and SSL
+#   RestClient.get 'https://user:password@example.com/private/resource'
+#
+#   # POST or PUT with a hash sends parameters as a urlencoded form body
+#   RestClient.post 'http://example.com/resource', :param1 => 'one'
+#
+#   # nest hash parameters
+#   RestClient.post 'http://example.com/resource', :nested => { :param1 => 'one' }
+#
+#   # POST and PUT with raw payloads
+#   RestClient.post 'http://example.com/resource', 'the post body', :content_type => 'text/plain'
+#   RestClient.post 'http://example.com/resource.xml', xml_doc
+#   RestClient.put 'http://example.com/resource.pdf', File.read('my.pdf'), :content_type => 'application/pdf'
+#
+#   # DELETE
+#   RestClient.delete 'http://example.com/resource'
+#
+#   # retreive the response headers
+#   res = RestClient.get 'http://example.com/some.jpg'
+#   res.headers[:content_type]  # => 'image/jpg'
+#
+# To use with a proxy, just set RestClient.proxy to the proper http proxy:
+#
+#   RestClient.proxy = "http://proxy.example.com/"
+#
+# Or inherit the proxy from the environment:
+#
+#   RestClient.proxy = ENV['http_proxy']
+#
+# For live tests of RestClient, try using http://rest-test.heroku.com, which echoes back information about the rest call:
+#
+#   >> RestClient.put 'http://rest-test.heroku.com/resource', :foo => 'baz'
+#   => "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
+
+	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
+end

data/lib/{request_errors.rb → restclient/exceptions.rb}

@@ -30,6 +30,10 @@ module RestClient
 		end
 	end
 
+	class NotModified < Exception
+		ErrorMessage = 'NotModified'
+	end
+
 	# Authorization is required to access the resource specified.
 	class Unauthorized < ExceptionWithResponse
 		ErrorMessage = 'Unauthorized'
@@ -40,7 +44,9 @@ module RestClient
 		ErrorMessage = 'Resource not found'
 	end
 
-	# The server broke the connection prior to the request completing.
+	# 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

data/lib/restclient/request.rb

@@ -0,0 +1,178 @@
+module RestClient
+	# This class is used internally by RestClient to send the request, but you can also
+	# access it internally if you'd like to use a method not directly supported by the
+	# main API.  For example:
+	#
+	#   RestClient::Request.execute(:method => :head, :url => 'http://example.com')
+   #
+	class Request
+		attr_reader :method, :url, :payload, :headers, :user, :password, :timeout
+
+		def self.execute(args)
+			new(args).execute
+		end
+
+		def initialize(args)
+			@method = args[:method] or raise ArgumentError, "must pass :method"
+			@url = args[:url] or raise ArgumentError, "must pass :url"
+			@headers = args[:headers] || {}
+			@payload = process_payload(args[:payload])
+			@user = args[:user]
+			@password = args[:password]
+			@timeout = args[:timeout]
+		end
+
+		def execute
+			execute_inner
+		rescue Redirect => e
+			@url = e.url
+			execute
+		end
+
+		def execute_inner
+			uri = parse_url_with_auth(url)
+			transmit uri, net_http_request_class(method).new(uri.request_uri, make_headers(headers)), payload
+		end
+
+		def make_headers(user_headers)
+			default_headers.merge(user_headers).inject({}) do |final, (key, value)|
+				final[key.to_s.gsub(/_/, '-').capitalize] = value.to_s
+				final
+			end
+		end
+
+		def net_http_class
+			if RestClient.proxy
+				proxy_uri = URI.parse(RestClient.proxy)
+				Net::HTTP::Proxy(proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password)
+			else
+				Net::HTTP
+			end
+		end
+
+		def net_http_request_class(method)
+			Net::HTTP.const_get(method.to_s.capitalize)
+		end
+
+		def parse_url(url)
+			url = "http://#{url}" unless url.match(/^http/)
+			URI.parse(url)
+		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, parent_key=nil)
+			unless p.is_a?(Hash)
+				p
+			else
+				@headers[:content_type] ||= 'application/x-www-form-urlencoded'
+				p.keys.map do |k|
+					key = parent_key ? "#{parent_key}[#{k}]" : k
+					if p[k].is_a? Hash
+						process_payload(p[k], key)
+					else
+						value = URI.escape(p[k].to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+						"#{key}=#{value}"
+					end
+				end.join("&")
+			end
+		end
+
+		def transmit(uri, req, payload)
+			setup_credentials(req)
+
+			net = net_http_class.new(uri.host, uri.port)
+			net.use_ssl = uri.is_a?(URI::HTTPS)
+			net.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+			display_log request_log
+
+			net.start do |http|
+				http.read_timeout = @timeout if @timeout
+				res = http.request(req, payload)
+				display_log response_log(res)
+				string = process_result(res)
+				if string
+					Response.new(string, res)
+				else
+					nil
+				end
+			end
+		rescue EOFError
+			raise RestClient::ServerBrokeConnection
+		rescue Timeout::Error
+			raise RestClient::RequestTimeout
+		end
+
+		def setup_credentials(req)
+			req.basic_auth(user, password) if user
+		end
+
+		def process_result(res)
+			if %w(200 201 202).include? res.code
+				decode res['content-encoding'], res.body
+			elsif %w(301 302 303).include? res.code
+				url = res.header['Location']
+
+				if url !~ /^http/
+					uri = URI.parse(@url)
+					uri.path = "/#{url}".squeeze('/')
+					url = uri.to_s
+				end
+
+				raise Redirect, url
+			elsif res.code == "304"
+				raise NotModified
+			elsif res.code == "401"
+				raise Unauthorized, res
+			elsif res.code == "404"
+				raise ResourceNotFound, res
+			else
+				raise RequestFailed, res
+			end
+		end
+
+		def decode(content_encoding, body)
+			if content_encoding == 'gzip'
+				Zlib::GzipReader.new(StringIO.new(body)).read
+			elsif content_encoding == 'deflate'
+				Zlib::Inflate.new.inflate(body)
+			else
+				body
+			end
+		end
+
+		def request_log
+			out = []
+			out << "RestClient.#{method} #{url.inspect}"
+			out << (payload.size > 100 ? "(#{payload.size} byte payload)".inspect : payload.inspect) if payload
+			out << headers.inspect.gsub(/^\{/, '').gsub(/\}$/, '') unless headers.empty?
+			out.join(', ')
+		end
+
+		def response_log(res)
+			"# => #{res.code} #{res.class.to_s.gsub(/^Net::HTTP/, '')} | #{(res['Content-type'] || '').gsub(/;.*$/, '')} #{(res.body) ? res.body.size : nil} bytes"
+		end
+
+		def display_log(msg)
+			return unless log_to = RestClient.log
+
+			if log_to == 'stdout'
+				STDOUT.puts msg
+			elsif log_to == 'stderr'
+				STDERR.puts msg
+			else
+				File.open(log_to, 'a') { |f| f.puts msg }
+			end
+		end
+
+		def default_headers
+			{ :accept => 'application/xml', :accept_encoding => 'gzip, deflate' }
+		end
+	end
+end