make socket read timeout raise a BERTRPC::ReadTimeoutError and enhanc…

…e readme

README.md

@@ -3,7 +3,8 @@ BERTRPC
 
 By Tom Preston-Werner (tom@mojombo.com)
 
-BERT-RPC client library for Ruby. Makes it ridiculously simple to interface with BERT-RPC servers.
+BERT-RPC client library for Ruby. Makes it ridiculously simple to interface
+with BERT-RPC servers.
 
 See the full BERT-RPC specification at [bert-rpc.org](http://bert-rpc.org).
 
@@ -12,7 +13,9 @@ This library currently only supports the following BERT-RPC features:
 * `call` requests
 * `cast` requests
 
-BERTRPC was developed for GitHub and is currently in production use performing millions of RPC requests every day. The stability and performance have been exemplary.
+BERTRPC was developed for GitHub and is currently in production use performing
+millions of RPC requests every day. The stability and performance have been
+exemplary.
 
 
 Installation
@@ -50,6 +53,18 @@ The underlying BERT-RPC transaction of the above cast is:
     <- {noreply}
 
 
+Documentation
+-------------
+
+Creating a service:
+
+    # No timeout
+    svc = BERTRPC::Service.new('localhost', 9999)
+
+    # 10s socket read timeout, raises BERTRPC::ReadTimeoutError
+    svc = BERTRPC::Service.new('localhost', 9999, 10)
+
+
 Copyright
 ---------
 

lib/bertrpc/action.rb

@@ -42,8 +42,10 @@ def transaction(bert_request)
       raise ProtocolError.new(ProtocolError::NO_DATA) unless bert_response
       sock.close
       bert_response
-    rescue Errno::ECONNREFUSED, Timeout::Error
+    rescue Errno::ECONNREFUSED
       raise ConnectionError.new("Unable to connect to #{@svc.host}:#{@svc.port}")
+    rescue Timeout::Error
+      raise ReadTimeoutError.new("No response from #{@svc.host}:#{@svc.port} in #{@svc.timeout}s")
     end
 
     # Creates a socket object which does speedy, non-blocking reads

lib/bertrpc/errors.rb

@@ -28,6 +28,10 @@ class ConnectionError < BERTRPCError
 
   end
 
+  class ReadTimeoutError < BERTRPCError
+
+  end
+
   class ProtocolError < BERTRPCError
     NO_HEADER = [0, "Unable to read length header from server."]
     NO_DATA = [1, "Unable to read data from server."]

test/action_test.rb

@@ -89,6 +89,20 @@ class ActionTest < Test::Unit::TestCase
           assert_equal 1, e.code
         end
       end
+
+      should "raise a ReadTimeoutError when the connection times out" do
+        io = stub()
+        io.expects(:write).with("\000\000\000\003")
+        io.expects(:write).with("foo")
+        io.expects(:read).with(4).raises(Timeout::Error)
+        @call.expects(:connect_to).returns(io)
+        begin
+          @call.transaction("foo")
+          fail "Should have thrown an error"
+        rescue BERTRPC::ReadTimeoutError => e
+          assert_equal 0, e.code
+        end
+      end
     end
   end
 end

test/service_test.rb

@@ -2,10 +2,15 @@
 
 class ServiceTest < Test::Unit::TestCase
   context "A Service" do
-    should "be created with host and port" do
+    should "be creatable with host and port" do
       svc = BERTRPC::Service.new('localhost', 9941)
       assert svc.is_a?(BERTRPC::Service)
     end
+
+    should "be creatable with host, port, and timeout" do
+      svc = BERTRPC::Service.new('localhost', 9941, 5)
+      assert svc.is_a?(BERTRPC::Service)
+    end
   end
 
   context "A Service Instance's" do