excon 0.9.5 → 0.9.6

data/README.md

@@ -56,6 +56,12 @@ Both one-off and persistent connections support many other options. Here are a f
 
 These options can be combined to make pretty much any request you might need.
 
+Excon can also expect one or more HTTP status code in response, raising an exception if the response does not meet the criteria.
+
+If you need to accept as response one or more HTTP status codes you can declare them in an array:
+
+    connection.request(expects => [200, 201], :method => :get, :path => path, :query => {})
+
 Streaming Responses
 -------------------
 
@@ -76,7 +82,7 @@ You can specify a proxy URL that Excon will use with both HTTP and HTTPS connect
     connection = Excon.new('http://geemus.com', :proxy => 'http://my.proxy:3128')
     connection.request(:method => 'GET')
 
-The proxy URL must be fully specified, including scheme (e.g. "http://") and port. 
+The proxy URL must be fully specified, including scheme (e.g. "http://") and port.
 
 Proxy support must be set when establishing a connection object and cannot be overridden in individual requests. Because of this it is unavailable in one-off requests (Excon.get, etc.)
 
@@ -107,6 +113,16 @@ Alternatively you can pass a block instead of `response_attributes` and it will
       {:body => params[:body], :status => 200}
     end
 
+In order to clear previously defined stubs you can use:
+
+    Excon.stubs.clear
+
+For example, if using RSpec for your test suite you can clear stubs after running each example:
+
+    config.after(:each) do
+        Excon.stubs.clear
+    end
+
 HTTPS/SSL Issues
 ----------------
 
@@ -122,6 +138,44 @@ Failing that, you can turn off peer verification (less secure):
 
 Either of these should allow you to work around the socket error and continue with your work.
 
+Instrumentation
+---------------
+
+Excon calls can be timed using the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
+
+    connection = Excon.new('http://geemus.com',
+        :instrumentor => ActiveSupport::Notifications)
+
+Excon will then instrument each request, retry, and error.  The corresponding events are named excon.request, excon.retry, and excon.error respectively.
+
+    ActiveSupport::Notifications.subscribe(/excon/) do |*args|
+      puts "Excon did stuff!"
+    end
+
+If you prefer to label each event with something other than "excon," you may specify
+an alternate name in the constructor:
+
+    connection = Excon.new('http://geemus.com',
+        :instrumentor => ActiveSupport::Notifications,
+        :instrumentor_name => 'my_app')
+
+If you don't want to add activesupport to your application, simply define a class which implements the same #instrument method like so:
+
+    class SimpleInstrumentor
+      class << self
+        attr_accessor :events
+
+        def instrument(name, params = {}, &block)
+          puts "#{name} just happened."
+          yield if block_given?
+        end
+      end
+    end
+
+The #instrument method will be called for each HTTP request, retry, and error.
+
+See [the documentation for ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) for more detail on using the subscription interface.  See excon's instrumentation_test.rb for more examples of instrumenting excon.
+
 Copyright
 ---------
 

data/benchmarks/single_vs_double_quotes.rb

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'tach'
+
+Tach.meter(1_000_000) do
+  tach('double') do
+    "path"
+  end
+  tach('single') do
+    'path'
+  end
+end
+
+#  [double, single]
+#
+#  +--------+----------+
+#  | tach   | total    |
+#  +--------+----------+
+#  | single | 0.416340 |
+#  +--------+----------+
+#  | double | 0.416570 |
+#  +--------+----------+

data/changelog.txt

@@ -1,3 +1,13 @@
+0.9.6 02/22/12
+==============
+
+* add support for setting ca_file. Thanks mattmatt!
+* add docs for Excon.stubs.clear and expects. Thanks masterkain!
+* add class level defaults
+* fix ruby warnings. Thanks foca!
+* improve instrumentation docs. Thanks mkb!
+* fix for empty body and SSL sockets. Thanks pweldon!
+
 0.9.5 01/16/12
 ==============
 

data/excon.gemspec

@@ -13,8 +13,8 @@ Gem::Specification.new do |s|
   ## If your rubyforge_project name is different, then edit it and comment out
   ## the sub! line in the Rakefile
   s.name              = 'excon'
-  s.version           = '0.9.5'
-  s.date              = '2012-01-16'
+  s.version           = '0.9.6'
+  s.date              = '2012-02-22'
   s.rubyforge_project = 'excon'
 
   ## Make sure your summary is short. The description may be as long
@@ -83,6 +83,7 @@ Gem::Specification.new do |s|
     benchmarks/headers_split_vs_match.rb
     benchmarks/implicit_block-vs-explicit_block.rb
     benchmarks/merging.rb
+    benchmarks/single_vs_double_quotes.rb
     benchmarks/string_ranged_index.rb
     benchmarks/strip_newline.rb
     benchmarks/vs_stdlib.rb

data/lib/excon.rb

@@ -17,27 +17,65 @@ require 'excon/ssl_socket'
 
 module Excon
   class << self
-    # @return [String] The filesystem path to the SSL Certificate Authority
-    attr_accessor :ssl_ca_path
 
-    # @return [true, false] Whether or not to verify the peer's SSL certificate / chain
-    attr_reader :ssl_verify_peer
+    # @return [Hash] defaults for Excon connections
+    def defaults
+      @defaults ||= {
+        :connect_timeout    => 60,
+        :headers            => {},
+        :instrumentor_name  => 'excon',
+        :mock               => false,
+        :read_timeout       => 60,
+        :retry_limit        => DEFAULT_RETRY_LIMIT,
+        :ssl_verify_peer    => RbConfig::CONFIG['host_os'] !~ /mswin|win32|dos|cygwin|mingw/i,
+        :write_timeout      => 60
+      }
+    end
 
-    # setup ssl defaults based on platform
-    @ssl_verify_peer = RbConfig::CONFIG['host_os'] !~ /mswin|win32|dos|cygwin|mingw/i
+    # Change defaults for Excon connections
+    # @return [Hash] defaults for Excon connections
+    def defaults=(new_defaults)
+      self.defaults = new_defaults
+    end
 
     # Status of mocking
     def mock
-      puts("Excon#mock is deprecated, pass :mock to the initializer (#{caller.first})")
-      @mock
+      puts("Excon#mock is deprecated, pass Excon.defaults[:mock] instead (#{caller.first})")
+      self.defaults[:mock]
     end
 
     # Change the status of mocking
     # false is the default and works as expected
     # true returns a value from stubs or raises
     def mock=(new_mock)
-      puts("Excon#mock= is deprecated, pass :mock to the initializer (#{caller.first})")
-      @mock = new_mock
+      puts("Excon#mock is deprecated, pass Excon.defaults[:mock]= instead (#{caller.first})")
+      self.defaults[:mock] = new_mock
+    end
+
+    # @return [String] The filesystem path to the SSL Certificate Authority
+    def ssl_ca_path
+      puts("Excon#ssl_ca_path is deprecated, use Excon.defaults[:ssl_ca_path] instead (#{caller.first})")
+      self.defaults[:ssl_ca_path]
+    end
+
+    # Change path to the SSL Certificate Authority
+    # @return [String] The filesystem path to the SSL Certificate Authority
+    def ssl_ca_path=(new_ssl_ca_path)
+      puts("Excon#ssl_ca_path= is deprecated, use Excon.defaults[:ssl_ca_path]= instead (#{caller.first})")
+      self.defaults[:ssl_ca_path] = new_ssl_ca_path
+    end
+
+    # @return [true, false] Whether or not to verify the peer's SSL certificate / chain
+    def ssl_verify_peer
+      puts("Excon#ssl_verify_peer= is deprecated, use Excon.defaults[:ssl_verify_peer]= instead (#{caller.first})")
+      self.defaults[:ssl_verify_peer]
+    end
+
+    # Change the status of ssl peer verification
+    # @see Excon#ssl_verify_peer (attr_reader)
+    def ssl_verify_peer=(new_ssl_verify_peer)
+      puts("Excon#ssl_verify_peer is deprecated, use Excon.defaults[:ssl_verify_peer] instead (#{caller.first})")
+      self.defaults[:ssl_verify_peer] = new_ssl_verify_peer
     end
 
     # @see Connection#initialize
@@ -49,12 +87,6 @@ module Excon
       Excon::Connection.new(url, params)
     end
 
-    # Change the status of ssl peer verification
-    # @see Excon#ssl_verify_peer (attr_reader)
-    def ssl_verify_peer=(new_ssl_verify_peer)
-      @ssl_verify_peer = new_ssl_verify_peer && true || false
-    end
-
     # push an additional stub onto the list to check for mock requests
     #   @param [Hash<Symbol, >] request params to match against, omitted params match all
     #   @param [Hash<Symbol, >] response params to return from matched request or block to call with params

data/lib/excon/connection.rb

@@ -18,20 +18,17 @@ module Excon
     #     @option params [String] :instrumentor_name Name prefix for #instrument events.  Defaults to 'excon'
     def initialize(url, params = {})
       uri = URI.parse(url)
-      @connection = {
-        :connect_timeout   => 60,
-        :headers           => {},
+      @connection = Excon.defaults.merge({
         :host              => uri.host,
-        :instrumentor_name => 'excon',
-        :mock              => Excon.instance_variable_get(:@mock),
         :path              => uri.path,
         :port              => uri.port.to_s,
         :query             => uri.query,
-        :read_timeout      => 60,
-        :retry_limit       => DEFAULT_RETRY_LIMIT,
         :scheme            => uri.scheme,
-        :write_timeout     => 60
-      }.merge!(params)
+      }).merge!(params)
+      # merge does not deep-dup, so make sure headers is not the original
+      @connection[:headers] = @connection[:headers].dup
+
+      @proxy = nil
 
       # use proxy from the environment if present
       if ENV.has_key?('http_proxy')
@@ -201,7 +198,7 @@ module Excon
           socket.write(request)
 
           # write out the body
-          if params[:body]
+          if params[:headers]['Content-Length'] != 0
             if params[:body].is_a?(String)
               socket.write(params[:body])
             else

data/lib/excon/constants.rb

@@ -1,6 +1,6 @@
 module Excon
   unless const_defined?(:VERSION)
-    VERSION = '0.9.5'
+    VERSION = '0.9.6'
   end
 
   unless const_defined?(:CHUNK_SIZE)

data/lib/excon/errors.rb

@@ -8,7 +8,7 @@ module Excon
 
       def initialize(socket_error=nil)
         if socket_error.message =~ /certificate verify failed/
-          super('Unable to verify certificate, please set `Excon.ssl_ca_path = path_to_certs` or `Excon.ssl_verify_peer = false` (less secure).')
+          super('Unable to verify certificate, please set `Excon.defaults[:ssl_ca_path] = path_to_certs`, `Excon.defaults[:ssl_ca_file] = path_to_file`, or `Excon.defaults[:ssl_verify_peer] = false` (less secure).')
         else
           super(socket_error.message)
         end

data/lib/excon/ssl_socket.rb

@@ -23,12 +23,14 @@ module Excon
       # create ssl context
       ssl_context = OpenSSL::SSL::SSLContext.new
 
-      if Excon.ssl_verify_peer
+      if Excon.defaults[:ssl_verify_peer]
         # turn verification on
         ssl_context.verify_mode = OpenSSL::SSL::VERIFY_PEER
 
-        if Excon.ssl_ca_path
-          ssl_context.ca_path = Excon.ssl_ca_path
+        if Excon.defaults[:ssl_ca_path]
+          ssl_context.ca_path = Excon.defaults[:ssl_ca_path]
+        elsif Excon.defaults[:ssl_ca_file]
+          ssl_context.ca_file = Excon.defaults[:ssl_ca_file]
         else
           # use default cert store
           store = OpenSSL::X509::Store.new
@@ -62,7 +64,7 @@ module Excon
       @socket.connect
 
       # verify connection
-      if Excon.ssl_verify_peer
+      if Excon.defaults[:ssl_verify_peer]
         @socket.post_connection_check(@params[:host])
       end
 

data/tests/idempotent_tests.rb

@@ -20,7 +20,7 @@ Shindo.tests('Excon request idempotencey') do
       end
     }
 
-    response = @connection.request(:method => :get, :path => '/some-path')
+    @connection.request(:method => :get, :path => '/some-path')
   end
 
   tests("Idempotent request with socket erroring first 3 times").returns(200) do

data/tests/stub_tests.rb

@@ -2,7 +2,7 @@ Shindo.tests('Excon stubs') do
 
   tests("missing stub").raises(Excon::Errors::StubNotFound) do
     connection = Excon.new('http://127.0.0.1:9292', :mock => true)
-    response = connection.request(:method => :get, :path => '/content-length/100')
+    connection.request(:method => :get, :path => '/content-length/100')
   end
 
   tests("stub({})").raises(ArgumentError) do
@@ -116,7 +116,7 @@ Shindo.tests('Excon stubs') do
 
     test("with block") do
       chunks = []
-      response = connection.request(:method => :get, :path => '/content-length/100') do |chunk, remaining_bytes, total_bytes|
+      connection.request(:method => :get, :path => '/content-length/100') do |chunk, remaining_bytes, total_bytes|
         chunks << chunk
       end
       chunks == ['x' * Excon::CHUNK_SIZE, 'x']

data/tests/test_helper.rb

@@ -6,6 +6,7 @@ Bundler.require(:default, :development)
 def basic_tests(url = 'http://127.0.0.1:9292')
   tests('GET /content-length/100') do
 
+    Excon.defaults[:ssl_verify_peer] = false
     connection = Excon.new(url)
     response = connection.request(:method => :get, :path => '/content-length/100')
 
@@ -54,9 +55,14 @@ def basic_tests(url = 'http://127.0.0.1:9292')
   tests('POST /body-sink') do
 
     connection = Excon.new(url)
-    response = connection.request(:method => :post, :path => '/body-sink', :headers => { 'Content-Type' => 'text/plain' }, :body => 'x' * 5_000_000)
 
     tests('response.body').returns("5000000") do
+      response = connection.request(:method => :post, :path => '/body-sink', :headers => { 'Content-Type' => 'text/plain' }, :body => 'x' * 5_000_000)
+      response.body
+    end
+
+    tests('empty body').returns('0') do
+      response = connection.request(:method => :post, :path => '/body-sink', :headers => { 'Content-Type' => 'text/plain' }, :body => '')
       response.body
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 0.9.6
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-16 00:00:00.000000000Z
+date: 2012-02-22 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70238243324360 !ruby/object:Gem::Requirement
+  requirement: &9166800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -23,10 +23,10 @@ dependencies:
         version: 3.1.3
   type: :development
   prerelease: false
-  version_requirements: *70238243324360
+  version_requirements: *9166800
 - !ruby/object:Gem::Dependency
   name: delorean
-  requirement: &70238243323780 !ruby/object:Gem::Requirement
+  requirement: &9166610 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243323780
+  version_requirements: *9166610
 - !ruby/object:Gem::Dependency
   name: open4
-  requirement: &70238243322680 !ruby/object:Gem::Requirement
+  requirement: &9166380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243322680
+  version_requirements: *9166380
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70238243322040 !ruby/object:Gem::Requirement
+  requirement: &9166170 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243322040
+  version_requirements: *9166170
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70238243321160 !ruby/object:Gem::Requirement
+  requirement: &9165960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -67,10 +67,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243321160
+  version_requirements: *9165960
 - !ruby/object:Gem::Dependency
   name: shindo
-  requirement: &70238243320420 !ruby/object:Gem::Requirement
+  requirement: &9165750 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -78,10 +78,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243320420
+  version_requirements: *9165750
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &70238243319760 !ruby/object:Gem::Requirement
+  requirement: &9165510 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -89,7 +89,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70238243319760
+  version_requirements: *9165510
 description: EXtended http(s) CONnections
 email: geemus@gmail.com
 executables: []
@@ -114,6 +114,7 @@ files:
 - benchmarks/headers_split_vs_match.rb
 - benchmarks/implicit_block-vs-explicit_block.rb
 - benchmarks/merging.rb
+- benchmarks/single_vs_double_quotes.rb
 - benchmarks/string_ranged_index.rb
 - benchmarks/strip_newline.rb
 - benchmarks/vs_stdlib.rb
@@ -160,7 +161,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1843710619352471147
+      hash: -511600863
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -169,7 +170,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: excon
-rubygems_version: 1.8.10
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 2
 summary: speed, persistence, http(s)