persistent option

Brian D. Burns · Brian D. Burns · commit a3a00eadc885 · 2013-12-02T01:26:28.000-05:00
diff --git a/README.md b/README.md
@@ -45,6 +45,41 @@ post_response = connection.post(:path => '/foo')
 delete_response = connection.delete(:path => '/bar')
 ```
 
+By default, each connection is non-persistent. This means that each request made against a connection behaves like a
+one-off request. Each request will establish a socket connection to the server, then close the socket once the request
+is complete.
+
+To use a persistent connection, use the `:persistent` option:
+
+```ruby
+connection = Excon.new('http://geemus.com', :persistent => true)
+```
+
+The initial request will establish a socket connection to the server and leave the socket open. Subsequent requests
+will reuse that socket. You may call `Connection#reset` at any time to close the underlying socket, and the next request
+will establish a new socket connection.
+
+You may also control persistence on a per-request basis by setting the `:persistent` option for each request.
+
+```ruby
+connection = Excon.new('http://geemus.com') # non-persistent by default
+connection.get # socket established, then closed
+connection.get(:persistent => true) # socket established, left open
+connection.get(:persistent => true) # socket reused
+connection.get # socket reused, then closed
+
+connection = Excon.new('http://geemus.com', :persistent => true)
+connection.get # socket established, left open
+connection.get(:persistent => false) # socket reused, then closed
+connection.get(:persistent => false) # socket established, then closed
+connection.get # socket established, left open
+connection.get # socket reused
+```
+
+Note that sending a request with `:persistent => false` to close the socket will also send `Connection: close` to inform
+the server the connection is no longer needed. `Connection#reset` will simply close our end of the socket.
+
+
 Options
 -------
 
@@ -131,13 +166,16 @@ Iterating in this way allows you to have more granular control over writes and t
 Pipelining Requests
 ------------------
 
-You can make use of HTTP pipelining to improve performance. Instead of the normal request/response cyle, pipelining sends a series of requests and then receives a series of responses. You can take advantage of this using the `requests` method, which takes an array of params where each is a hash like request would receive and returns an array of responses.
+You can make use of HTTP pipelining to improve performance. Instead of the normal request/response cycle, pipelining sends a series of requests and then receives a series of responses. You can take advantage of this using the `requests` method, which takes an array of params where each is a hash like request would receive and returns an array of responses.
 
 ```ruby
 connection = Excon.new('http://geemus.com/')
 connection.requests([{:method => :get}, {:method => :get}])
 ```
 
+By default, each call to `requests` will use a separate persistent socket connection. To make multiple `requests` calls
+using a single persistent connection, set `:persistent => true` when establishing the connection.
+
 Streaming Responses
 -------------------
 
diff --git a/lib/excon.rb b/lib/excon.rb
@@ -41,6 +41,7 @@ def defaults
         :mock               => false,
         :nonblock           => true,
         :omit_default_port  => false,
+        :persistent         => false,
         :read_timeout       => 60,
         :retry_limit        => DEFAULT_RETRY_LIMIT,
         :ssl_verify_peer    => true,
diff --git a/lib/excon/connection.rb b/lib/excon/connection.rb
@@ -152,7 +152,7 @@ def request_call(datum)
           else
             datum[:headers]['TE'] = 'trailers, deflate, gzip'
           end
-          datum[:headers]['Connection'] = 'TE'
+          datum[:headers]['Connection'] = datum[:persistent] ? 'TE' : 'TE, close'
 
           # add headers to request
           datum[:headers].each do |key, values|
@@ -267,10 +267,14 @@ def request(params={}, &block)
       unless datum[:pipeline]
         datum = response(datum)
 
-        if key = datum[:response][:headers].keys.detect {|k| k.casecmp('Connection') == 0 }
-          if split_header_value(datum[:response][:headers][key]).any? {|t| t.casecmp('close') }
-            reset
+        if datum[:persistent]
+          if key = datum[:response][:headers].keys.detect {|k| k.casecmp('Connection') == 0 }
+            if split_header_value(datum[:response][:headers][key]).any? {|t| t.casecmp('close') }
+              reset
+            end
           end
+        else
+          reset
         end
 
         Excon::Response.new(datum[:response])
@@ -290,16 +294,23 @@ def request(params={}, &block)
     # Sends the supplied requests to the destination host using pipelining.
     #   @pipeline_params [Array<Hash>] pipeline_params An array of one or more optional params, override defaults set in Connection.new, see #request for details
     def requests(pipeline_params)
+      pipeline_params.each {|params| params.merge!(:pipeline => true, :persistent => true) }
+      pipeline_params.last.merge!(:persistent => @data[:persistent])
+
       responses = pipeline_params.map do |params|
-        request(params.merge!(:pipeline => true))
+        request(params)
       end.map do |datum|
         Excon::Response.new(response(datum)[:response])
       end
 
-      if key = responses.last[:headers].keys.detect {|k| k.casecmp('Connection') == 0 }
-        if split_header_value(responses.last[:headers][key]).any? {|t| t.casecmp('close') }
-          reset
+      if @data[:persistent]
+        if key = responses.last[:headers].keys.detect {|k| k.casecmp('Connection') == 0 }
+          if split_header_value(responses.last[:headers][key]).any? {|t| t.casecmp('close') }
+            reset
+          end
         end
+      else
+        reset
       end
 
       responses
diff --git a/lib/excon/constants.rb b/lib/excon/constants.rb
@@ -46,6 +46,7 @@ module Excon
     :middlewares,
     :mock,
     :path,
+    :persistent,
     :pipeline,
     :query,
     :read_timeout,
diff --git a/tests/basic_tests.rb b/tests/basic_tests.rb
@@ -61,8 +61,7 @@
 
     basic_tests('https://127.0.0.1:8443',
                 :client_key => File.join(File.dirname(__FILE__), 'data', 'excon.cert.key'),
-                :client_cert => File.join(File.dirname(__FILE__), 'data', 'excon.cert.crt'),
-                :reset_connection => RUBY_VERSION == '1.9.2'
+                :client_cert => File.join(File.dirname(__FILE__), 'data', 'excon.cert.crt')
                )
 
   end
diff --git a/tests/middlewares/mock_tests.rb b/tests/middlewares/mock_tests.rb
@@ -219,11 +219,5 @@
     Excon.stubs.clear
   end
 
-  tests('mock = false') do
-    with_rackup('basic.ru') do
-      basic_tests
-    end
-  end
-
   env_restore
 end
diff --git a/tests/pipeline_tests.rb b/tests/pipeline_tests.rb
@@ -0,0 +1,40 @@
+Shindo.tests('Pipelined Requests') do
+  with_server('good') do
+
+    tests('with default :persistent => true') do
+      connection = Excon.new('http://127.0.0.1:9292', :persistent => true)
+
+      returns(%w{ 1 2 3 4 }, 'connection is persistent') do
+        ret = []
+        ret << connection.requests([
+          {:method => :get, :path => '/echo/request_count'},
+          {:method => :get, :path => '/echo/request_count'}
+        ]).map(&:body)
+        ret << connection.requests([
+          {:method => :get, :path => '/echo/request_count'},
+          {:method => :get, :path => '/echo/request_count'}
+        ]).map(&:body)
+        ret.flatten
+      end
+    end
+
+    tests('with default :persistent => false') do
+      connection = Excon.new('http://127.0.0.1:9292', :persistent => false)
+
+      returns(%w{ 1 2 1 2 }, 'connection is persistent per call to #requests') do
+        ret = []
+        ret << connection.requests([
+          {:method => :get, :path => '/echo/request_count'},
+          {:method => :get, :path => '/echo/request_count'}
+        ]).map(&:body)
+        ret << connection.requests([
+          {:method => :get, :path => '/echo/request_count'},
+          {:method => :get, :path => '/echo/request_count'}
+        ]).map(&:body)
+        ret.flatten
+      end
+
+    end
+
+  end
+end
diff --git a/tests/request_tests.rb b/tests/request_tests.rb
@@ -0,0 +1,109 @@
+Shindo.tests('Request Tests') do
+  with_server('good') do
+
+    tests('sets transfer-coding and connection options') do
+
+      tests('without a :response_block') do
+        request = Marshal.load(
+          Excon.get('http://127.0.0.1:9292/echo/request').body
+        )
+
+        returns('trailers, deflate, gzip', 'sets encoding options') do
+          request[:headers]['TE']
+        end
+
+        returns(true, 'TE added to Connection header') do
+          request[:headers]['Connection'].include?('TE')
+        end
+      end
+
+      tests('with a :response_block') do
+        captures = capture_response_block do |block|
+          Excon.get('http://127.0.0.1:9292/echo/request',
+                    :response_block => block)
+        end
+        data = captures.map {|capture| capture[0] }.join
+        request = Marshal.load(data)
+
+        returns('trailers', 'does not set encoding options') do
+          request[:headers]['TE']
+        end
+
+        returns(true, 'TE added to Connection header') do
+          request[:headers]['Connection'].include?('TE')
+        end
+      end
+
+    end
+
+    tests('persistent connections') do
+
+      tests('with default :persistent => true') do
+        connection = nil
+
+        returns(['1', '2'], 'uses a persistent connection') do
+          connection = Excon.new('http://127.0.0.1:9292', :persistent => true)
+          2.times.map do
+            connection.request(:method => :get, :path => '/echo/request_count').body
+          end
+        end
+
+        returns(['3', '1', '2'], ':persistent => false resets connection') do
+          ret = []
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count',
+                                    :persistent => false).body
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count').body
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count').body
+        end
+      end
+
+      tests('with default :persistent => false') do
+        connection = nil
+
+        returns(['1', '1'], 'does not use a persistent connection') do
+          connection = Excon.new('http://127.0.0.1:9292', :persistent => false)
+          2.times.map do
+            connection.request(:method => :get, :path => '/echo/request_count').body
+          end
+        end
+
+        returns(['1', '2', '3', '1'], ':persistent => true enables persistence') do
+          ret = []
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count',
+                                    :persistent => true).body
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count',
+                                    :persistent => true).body
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count').body
+          ret << connection.request(:method => :get,
+                                    :path   => '/echo/request_count').body
+        end
+      end
+
+      tests('sends `Connection: close`') do
+        returns(true, 'when :persistent => false') do
+          request = Marshal.load(
+            Excon.get('http://127.0.0.1:9292/echo/request',
+                      :persistent => false).body
+          )
+          request[:headers]['Connection'].include?('close')
+        end
+
+        returns(false, 'not when :persistent => true') do
+          request = Marshal.load(
+            Excon.get('http://127.0.0.1:9292/echo/request',
+                      :persistent => true).body
+          )
+          request[:headers]['Connection'].include?('close')
+        end
+      end
+
+    end
+
+  end
+end
diff --git a/tests/requests_tests.rb b/tests/requests_tests.rb
diff --git a/tests/servers/good.rb b/tests/servers/good.rb
@@ -30,6 +30,13 @@ def send_response(request)
         send_data "\r\n"
         send_data data
 
+      when 'request_count'
+        (@request_count ||= '0').next!
+        start_response
+        send_data "Content-Length: #{ @request_count.size }\r\n"
+        send_data "\r\n"
+        send_data @request_count
+
       when /(content|transfer)-encoded\/?(.*)/
         if (encoding_type = $1) == 'content'
           accept_header = 'Accept-Encoding'
diff --git a/tests/test_helper.rb b/tests/test_helper.rb

Original file line number	Diff line number	Diff line change
`@@ -61,8 +61,7 @@`
`61`	`61`
`62`	`62`	`basic_tests('https://127.0.0.1:8443',`
`63`	`63`	`:client_key => File.join(File.dirname(__FILE__), 'data', 'excon.cert.key'),`
`64`		`- :client_cert => File.join(File.dirname(__FILE__), 'data', 'excon.cert.crt'),`
`65`		`- :reset_connection => RUBY_VERSION == '1.9.2'`
	`64`	`+ :client_cert => File.join(File.dirname(__FILE__), 'data', 'excon.cert.crt')`
`66`	`65`	`)`
`67`	`66`
`68`	`67`	`end`