rest-client 0.9 → 0.9.2

data/README.rdoc

@@ -0,0 +1,138 @@
+= REST Client -- simple DSL for accessing REST resources
+
+A simple REST client for Ruby, inspired by the Sinatra's microframework style
+of specifying actions: get, put, post, delete.
+
+== Usage: Raw URL
+
+  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.delete 'http://example.com/resource'
+
+See RestClient module docs for details.
+
+== Usage: ActiveResource-Style
+
+  resource = RestClient::Resource.new 'http://example.com/resource'
+  resource.get
+
+  private_resource = RestClient::Resource.new 'https://example.com/private/resource', :user => 'adam', :password => 'secret', :timeout => 20, :open_timeout => 5
+  private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'
+
+See RestClient::Resource module docs for details.
+
+== Usage: Resource Nesting
+
+  site = RestClient::Resource.new('http://example.com')
+  site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+
+See RestClient::Resource docs for details.
+
+== Shell
+
+The restclient shell command gives an IRB session with RestClient already loaded:
+
+  $ restclient
+  >> RestClient.get 'http://example.com'
+
+Specify a URL argument for get/post/put/delete on that resource:
+
+  $ restclient http://example.com
+  >> put '/resource', 'data'
+
+Add a user and password for authenticated resources:
+
+  $ restclient https://example.com user pass
+  >> delete '/private/resource'
+
+Create ~/.restclient for named sessions:
+
+  sinatra:
+    url: http://localhost:4567
+  rack:
+    url: http://localhost:9292
+  private_site:
+    url: http://example.com
+    username: user
+    password: pass
+
+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
+
+Write calls to a log filename (can also be "stdout" or "stderr"):
+
+  RestClient.log = '/tmp/restclient.log'
+
+Or set an environment variable to avoid modifying the code:
+
+  $ 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
+
+== Meta
+
+Written by Adam Wiggins (adam at heroku dot com)
+
+Patches contributed by: Chris Anderson, Greg Borenstein, Ardekantur, Pedro
+Belo, Rafael Souza, Rick Olson, Aman Gupta, Blake Mizerany, Brian Donovan, Ivan
+Makfinsky, Marc-André Cournoyer, Coda Hale, Tetsuo Watanabe, Dusty Doris,
+Lennon Day-Reynolds, James Edward Gray II, Cyril Rohr, and Juan Alvarez
+
+Released under the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+http://rest-client.heroku.com
+
+http://github.com/adamwiggins/rest-client
+

data/Rakefile

@@ -31,7 +31,7 @@ require 'rake/gempackagetask'
 require 'rake/rdoctask'
 require 'fileutils'
 
-version = "0.9"
+version = "0.9.2"
 name = "rest-client"
 
 spec = Gem::Specification.new do |s|
@@ -47,7 +47,7 @@ spec = Gem::Specification.new do |s|
 	s.platform = Gem::Platform::RUBY
 	s.has_rdoc = true
 	
-	s.files = %w(Rakefile) + Dir.glob("{lib,spec}/**/*")
+	s.files = %w(Rakefile README.rdoc) + Dir.glob("{lib,spec}/**/*")
 	s.executables = ['restclient']
 	
 	s.require_path = "lib"

data/lib/restclient.rb

@@ -31,10 +31,14 @@ require File.dirname(__FILE__) + '/restclient/exceptions'
 #   # DELETE
 #   RestClient.delete 'http://example.com/resource'
 #
-#   # retreive the response headers
+#   # retreive the response http code and headers
 #   res = RestClient.get 'http://example.com/some.jpg'
+#   res.code                    # => 200
 #   res.headers[:content_type]  # => 'image/jpg'
 #
+#   # HEAD
+#   RestClient.head('http://example.com').headers
+#
 # To use with a proxy, just set RestClient.proxy to the proper http proxy:
 #
 #   RestClient.proxy = "http://proxy.example.com/"
@@ -65,6 +69,10 @@ module RestClient
 		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

data/lib/restclient/exceptions.rb

@@ -30,7 +30,7 @@ module RestClient
 		end
 	end
 
-	class NotModified < Exception
+	class NotModified < ExceptionWithResponse
 		ErrorMessage = 'NotModified'
 	end
 

data/lib/restclient/request.rb

@@ -6,7 +6,7 @@ module RestClient
 	#   RestClient::Request.execute(:method => :head, :url => 'http://example.com')
    #
 	class Request
-		attr_reader :method, :url, :payload, :headers, :user, :password, :timeout
+		attr_reader :method, :url, :payload, :headers, :cookies, :user, :password, :timeout, :open_timeout
 
 		def self.execute(args)
 			new(args).execute
@@ -16,10 +16,12 @@ module RestClient
 			@method = args[:method] or raise ArgumentError, "must pass :method"
 			@url = args[:url] or raise ArgumentError, "must pass :url"
 			@headers = args[:headers] || {}
+      @cookies = @headers.delete(:cookies) || args[:cookies] || {}
 			@payload = process_payload(args[:payload])
 			@user = args[:user]
 			@password = args[:password]
 			@timeout = args[:timeout]
+			@open_timeout = args[:open_timeout]
 		end
 
 		def execute
@@ -35,6 +37,10 @@ module RestClient
 		end
 
 		def make_headers(user_headers)
+      unless @cookies.empty?
+        user_headers[:cookie] = @cookies.map {|key, val| "#{key.to_s}=#{val}" }.join('; ')
+      end
+
 			default_headers.merge(user_headers).inject({}) do |final, (key, value)|
 				final[key.to_s.gsub(/_/, '-').capitalize] = value.to_s
 				final
@@ -89,15 +95,17 @@ module RestClient
 			net = net_http_class.new(uri.host, uri.port)
 			net.use_ssl = uri.is_a?(URI::HTTPS)
 			net.verify_mode = OpenSSL::SSL::VERIFY_NONE
+			net.read_timeout = @timeout if @timeout
+			net.open_timeout = @open_timeout if @open_timeout
 
 			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
+
+				if string or @method == :head
 					Response.new(string, res)
 				else
 					nil
@@ -114,8 +122,8 @@ module RestClient
 		end
 
 		def process_result(res)
-			if %w(200 201 202).include? res.code
-				decode res['content-encoding'], res.body
+			if res.code =~ /\A2\d{2}\z/
+				decode res['content-encoding'], res.body if res.body
 			elsif %w(301 302 303).include? res.code
 				url = res.header['Location']
 
@@ -127,7 +135,7 @@ module RestClient
 
 				raise Redirect, url
 			elsif res.code == "304"
-				raise NotModified
+				raise NotModified, res
 			elsif res.code == "401"
 				raise Unauthorized, res
 			elsif res.code == "404"
@@ -138,7 +146,7 @@ module RestClient
 		end
 
 		def decode(content_encoding, body)
-			if content_encoding == 'gzip'
+			if content_encoding == 'gzip' and not body.empty?
 				Zlib::GzipReader.new(StringIO.new(body)).read
 			elsif content_encoding == 'deflate'
 				Zlib::Inflate.new.inflate(body)

data/lib/restclient/resource.rb

@@ -16,6 +16,10 @@ module RestClient
 	#
 	#   RestClient::Resource.new('http://slow', :timeout => 10)
 	#
+	# With an open timeout (seconds):
+	#
+	#   RestClient::Resource.new('http://behindfirewall', :open_timeout => 10)
+	#
 	# You can also use resources to share common headers. For headers keys,
 	# symbols are converted to strings. Example:
 	#
@@ -94,6 +98,10 @@ module RestClient
 		def timeout
 			options[:timeout]
 		end
+		
+		def open_timeout
+		  options[:open_timeout]
+	  end
 
 		# Construct a subresource, preserving authentication.
 		#

data/lib/restclient/response.rb

@@ -10,7 +10,7 @@ module RestClient
 
 		def initialize(string, net_http_res)
 			@net_http_res = net_http_res
-			super string
+			super(string || "")
 		end
 
 		# HTTP status code, always 200 since RestClient throws exceptions for
@@ -25,6 +25,17 @@ module RestClient
 			@headers ||= self.class.beautify_headers(@net_http_res.to_hash)
 		end
 
+    # Hash of cookies extracted from response headers
+    def cookies
+      @cookies ||= (self.headers[:set_cookie] || "").split('; ').inject({}) do |out, raw_c|
+        key, val = raw_c.split('=')
+        unless %w(expires domain path secure).member?(key)
+          out[key] = val
+        end
+        out
+      end
+    end
+
 		def self.beautify_headers(headers)
 			headers.inject({}) do |out, (key, value)|
 				out[key.gsub(/-/, '_').to_sym] = value.first

data/spec/request_spec.rb

@@ -28,18 +28,32 @@ describe RestClient::Request do
 	it "decodes a gzip body" do
 		@request.decode('gzip', "\037\213\b\b\006'\252H\000\003t\000\313T\317UH\257\312,HM\341\002\000G\242(\r\v\000\000\000").should == "i'm gziped\n"
 	end
+	
+	it "ingores gzip for empty bodies" do
+		@request.decode('gzip', '').should be_empty
+	end
 
 	it "decodes a deflated body" do
 		@request.decode('deflate', "x\234+\316\317MUHIM\313I,IMQ(I\255(\001\000A\223\006\363").should == "some deflated text"
 	end
 
-	it "processes a successful result" do
-		res = mock("result")
-		res.stub!(:code).and_return("200")
-		res.stub!(:body).and_return('body')
-		res.stub!(:[]).with('content-encoding').and_return(nil)
-		@request.process_result(res).should == 'body'
-	end
+  it "processes a successful result" do
+    res = mock("result")
+    res.stub!(:code).and_return("200")
+    res.stub!(:body).and_return('body')
+    res.stub!(:[]).with('content-encoding').and_return(nil)
+    @request.process_result(res).should == 'body'
+  end
+
+  it "doesn't classify successful requests as failed" do
+    203.upto(206) do |code|
+      res = mock("result")
+      res.stub!(:code).and_return(code.to_s)
+      res.stub!(:body).and_return("")
+      res.stub!(:[]).with('content-encoding').and_return(nil)
+      @request.process_result(res).should be_empty
+    end
+  end
 
 	it "parses a url into a URI object" do
 		URI.should_receive(:parse).with('http://example.com/resource')
@@ -66,6 +80,13 @@ describe RestClient::Request do
 		@request.password.should == 'pass2'
 	end
 
+  it "correctly formats cookies provided to the constructor" do
+    URI.stub!(:parse).and_return(mock('uri', :user => nil, :password => nil))
+    @request = RestClient::Request.new(:method => 'get', :url => 'example.com', :cookies => {:session_id => '1' })
+    @request.should_receive(:default_headers).and_return({'foo' => 'bar'})
+    headers = @request.make_headers({}).should == { 'Foo' => 'bar', 'Cookie' => 'session_id=1'}
+  end
+
 	it "determines the Net::HTTP class to instantiate by the method name" do
 		@request.net_http_request_class(:put).should == Net::HTTP::Put
 	end
@@ -289,7 +310,18 @@ describe RestClient::Request do
 		@request.stub!(:process_result)
 		@request.stub!(:response_log)
 		
-		@http.should_receive(:read_timeout=).with(123)
+		@net.should_receive(:read_timeout=).with(123)
+		
+		@request.transmit(@uri, 'req', nil)
+	end
+	
+	it "set open_timeout" do
+		@request = RestClient::Request.new(:method => :put, :url => 'http://some/resource', :payload => 'payload', :open_timeout => 123)
+		@http.stub!(:request)
+		@request.stub!(:process_result)
+		@request.stub!(:response_log)
+		
+		@net.should_receive(:open_timeout=).with(123)
 		
 		@request.transmit(@uri, 'req', nil)
 	end

data/spec/response_spec.rb

@@ -30,7 +30,16 @@ describe RestClient::Response do
 		@response.headers.should == { :content_type => 'text/html' }
 	end
 
+  it "extracts cookies from response headers" do
+    @net_http_res.should_receive(:to_hash).and_return('set-cookie' => ['session_id=1; path=/'])
+    @response.cookies.should == { 'session_id' => '1' }
+  end
+
 	it "can access the net http result directly" do
 		@response.net_http_res.should == @net_http_res
 	end
+
+	it "accepts nil strings and sets it to empty for the case of HEAD" do
+		RestClient::Response.new(nil, @net_http_res).should == ""
+	end
 end

data/spec/restclient_spec.rb

@@ -21,6 +21,11 @@ describe RestClient do
 			RestClient::Request.should_receive(:execute).with(:method => :delete, :url => 'http://some/resource', :headers => {})
 			RestClient.delete('http://some/resource')
 		end
+
+		it "HEAD" do
+			RestClient::Request.should_receive(:execute).with(:method => :head, :url => 'http://some/resource', :headers => {})
+			RestClient.head('http://some/resource')
+		end
 	end
 
 	describe "logging" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rest-client
 version: !ruby/object:Gem::Version 
-  version: "0.9"
+  version: 0.9.2
 platform: ruby
 authors: 
 - Adam Wiggins
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-24 00:00:00 -08:00
+date: 2009-03-12 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -23,19 +23,20 @@ extra_rdoc_files: []
 
 files: 
 - Rakefile
+- README.rdoc
+- lib/restclient.rb
 - lib/rest_client.rb
 - lib/restclient
-- lib/restclient/exceptions.rb
-- lib/restclient/request.rb
-- lib/restclient/resource.rb
 - lib/restclient/response.rb
-- lib/restclient.rb
+- lib/restclient/resource.rb
+- lib/restclient/request.rb
+- lib/restclient/exceptions.rb
+- spec/resource_spec.rb
+- spec/restclient_spec.rb
+- spec/response_spec.rb
 - spec/base.rb
 - spec/exceptions_spec.rb
 - spec/request_spec.rb
-- spec/resource_spec.rb
-- spec/response_spec.rb
-- spec/restclient_spec.rb
 has_rdoc: true
 homepage: http://rest-client.heroku.com/
 post_install_message: