excon 0.8.0 → 0.9.0

data/Rakefile

@@ -56,7 +56,7 @@ task :coverage do
   sh "open coverage/index.html"
 end
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "#{name} #{version}"

data/changelog.txt

@@ -1,3 +1,10 @@
+0.9.0 12/14/11
+==============
+
+* add ability to do instrumentation
+* misc cleanup
+* deprecate retry_limit accessor in favor of passing as a param
+
 0.8.0 12/12/11
 ==============
 

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.8.0'
-  s.date              = '2011-12-12'
+  s.version           = '0.9.0'
+  s.date              = '2011-12-14'
   s.rubyforge_project = 'excon'
 
   ## Make sure your summary is short. The description may be as long
@@ -57,6 +57,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency('rake')
   s.add_development_dependency('shindo', '0.2.0')
   s.add_development_dependency('sinatra')
+  s.add_development_dependency('activesupport', '~>3.1.3')
+  s.add_development_dependency('delorean')
 
   ## Leave this section as-is. It will be automatically generated from the
   ## contents of your Git repository via the gemspec task. DO NOT REMOVE
@@ -96,6 +98,7 @@ Gem::Specification.new do |s|
     tests/basic_tests.rb
     tests/header_tests.rb
     tests/idempotent_tests.rb
+    tests/instrumentation_tests.rb
     tests/proxy_tests.rb
     tests/query_string_tests.rb
     tests/rackups/basic.ru

data/lib/excon/connection.rb

@@ -2,10 +2,6 @@ module Excon
   class Connection
     attr_reader :connection, :proxy
 
-    CR_NL     = "\r\n"
-    HTTP_1_1  = " HTTP/1.1\r\n"
-    FORCE_ENC = CR_NL.respond_to?(:force_encoding)
-
     # Initializes a new Connection instance
     #   @param [String] url The destination URL
     #   @param [Hash<Symbol, >] params One or more optional params
@@ -18,19 +14,23 @@ module Excon
     #     @option params [String] :scheme The protocol; 'https' causes OpenSSL to be used
     #     @option params [String] :proxy Proxy server; e.g. 'http://myproxy.com:8888'
     #     @option params [Fixnum] :retry_limit Set how many times we'll retry a failed request.  (Default 4)
+    #     @option params [Class] :instrumentor Responds to #instrument as in ActiveSupport::Notifications
+    #     @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          => {},
-        :host             => uri.host,
-        :mock             => Excon.mock,
-        :path             => uri.path,
-        :port             => uri.port.to_s,
-        :query            => uri.query,
-        :read_timeout     => 60,
-        :scheme           => uri.scheme,
-        :write_timeout    => 60
+        :connect_timeout   => 60,
+        :headers           => {},
+        :host              => uri.host,
+        :instrumentor_name => 'excon',
+        :mock              => Excon.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)
 
       # use proxy from the environment if present
@@ -40,9 +40,7 @@ module Excon
         @proxy = setup_proxy(params[:proxy])
       end
 
-      self.retry_limit = params[:retry_limit] || DEFAULT_RETRY_LIMIT
-
-      if @connection[:scheme] == 'https'
+      if @connection[:scheme] == HTTPS
         # use https_proxy if that has been specified
         if ENV.has_key?('https_proxy')
           @proxy = setup_proxy(ENV['https_proxy'])
@@ -68,24 +66,84 @@ module Excon
     #     @option params [Hash]   :query appended to the 'scheme://host:port/path/' in the form of '?key=value'
     #     @option params [String] :scheme The protocol; 'https' causes OpenSSL to be used
     def request(params, &block)
-      begin
-        # connection has defaults, merge in new params to override
-        params = @connection.merge(params)
-        params[:headers] = @connection[:headers].merge(params[:headers] || {})
-        params[:headers]['Host'] ||= '' << params[:host] << ':' << params[:port]
+      # connection has defaults, merge in new params to override
+      params = @connection.merge(params)
+      params[:headers] = @connection[:headers].merge(params[:headers] || {})
+      params[:headers]['Host'] ||= '' << params[:host] << ':' << params[:port]
+
+      # if path is empty or doesn't start with '/', insert one
+      unless params[:path][0, 1] == '/'
+        params[:path].insert(0, '/')
+      end
 
-        # if path is empty or doesn't start with '/', insert one
-        unless params[:path][0, 1] == '/'
-          params[:path].insert(0, '/')
+      if params.has_key?(:instrumentor)
+        if (retries_remaining ||= params[:retry_limit]) < params[:retry_limit]
+          event_name = "#{params[:instrumentor_name]}.retry"
+        else
+          event_name = "#{params[:instrumentor_name]}.request"
         end
-
-        unless params[:mock]
-          socket.params = params
+        params[:instrumentor].instrument(event_name, params) do
+          request_kernel(params, &block)
+        end
+      else
+        request_kernel(params, &block)
+      end
+    rescue => request_error
+      if params[:idempotent] && [Excon::Errors::SocketError,
+          Excon::Errors::HTTPStatusError].any? {|ex| request_error.kind_of? ex }
+        retries_remaining ||= params[:retry_limit]
+        retries_remaining -= 1
+        if retries_remaining > 0
+          if params[:body].respond_to?(:pos=)
+            params[:body].pos = 0
+          end
+          retry
         else
-          mocked_response = invoke_stub(params, &block)
-          return mocked_response unless mocked_response.nil?
+          if params.has_key?(:instrumentor)
+            params[:instrumentor].instrument("#{params[:instrumentor_name]}.error", :error => request_error)
+          end
+          raise(request_error)
+        end
+      else
+        if params.has_key?(:instrumentor)
+          params[:instrumentor].instrument("#{params[:instrumentor_name]}.error", :error => request_error)
+        end
+        raise(request_error)
+      end
+    end
+
+    def reset
+      (old_socket = sockets.delete(@socket_key)) && old_socket.close
+    end
+
+    # Generate HTTP request verb methods
+    Excon::HTTP_VERBS.each do |method|
+      eval <<-DEF
+        def #{method}(params={}, &block)
+          request(params.merge!(:method => :#{method}), &block)
+        end
+      DEF
+    end
+
+    def retry_limit=(new_retry_limit)
+      puts("Excon::Connection#retry_limit= is deprecated, pass :retry_limit to the initializer (#{caller.first})")
+      @connection[:retry_limit] = new_retry_limit
+    end
+
+    def retry_limit
+      puts("Excon::Connection#retry_limit is deprecated, pass :retry_limit to the initializer (#{caller.first})")
+      @connection[:retry_limit] ||= DEFAULT_RETRY_LIMIT
+    end
+
+  private
+
+    def request_kernel(params, &block)
+      begin
+        if params[:mock]
+          return invoke_stub(params, &block)
         end
 
+        socket.params = params
         # start with "METHOD /path"
         request = params[:method].to_s.upcase << ' '
         if @proxy
@@ -175,24 +233,8 @@ module Excon
       else
         response
       end
-
-    rescue => request_error
-      if params[:idempotent] && [Excon::Errors::SocketError, Excon::Errors::HTTPStatusError].any? {|ex| request_error.kind_of? ex }
-        retries_remaining ||= retry_limit
-        retries_remaining -= 1
-        if retries_remaining > 0
-          if params[:body].respond_to?(:pos=)
-            params[:body].pos = 0
-          end
-          retry
-        else
-          raise(request_error)
-        end
-      else
-        raise(request_error)
-      end
     end
-    
+
     def invoke_stub(params)
       for stub, response in Excon.stubs
         # all specified non-headers params match and no headers were specified or all specified headers match
@@ -221,29 +263,8 @@ module Excon
       raise(Excon::Errors::StubNotFound.new('no stubs matched ' << params.inspect))
     end
 
-    def reset
-      (old_socket = sockets.delete(@socket_key)) && old_socket.close
-    end
-
-    # Generate HTTP request verb methods
-    Excon::HTTP_VERBS.each do |method|
-      eval <<-DEF
-        def #{method}(params={}, &block)
-          request(params.merge!(:method => :#{method}), &block)
-        end
-      DEF
-    end
-
-    attr_writer :retry_limit
-
-    def retry_limit
-      @retry_limit ||= DEFAULT_RETRY_LIMIT
-    end
-
-  private
-
     def socket
-      sockets[@socket_key] ||= if @connection[:scheme] == 'https'
+      sockets[@socket_key] ||= if @connection[:scheme] == HTTPS
         Excon::SSLSocket.new(@connection, @proxy)
       else
         Excon::Socket.new(@connection, @proxy)

data/lib/excon/constants.rb

@@ -1,20 +1,36 @@
 module Excon
   unless const_defined?(:VERSION)
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 
   unless const_defined?(:CHUNK_SIZE)
     CHUNK_SIZE = 1048576 # 1 megabyte
   end
 
-  unless const_defined?(:HTTP_VERBS)
-    HTTP_VERBS = %w{connect delete get head options post put trace}
+  unless const_defined?(:CR_NL)
+    CR_NL = "\r\n"
   end
 
   unless const_defined?(:DEFAULT_RETRY_LIMIT)
     DEFAULT_RETRY_LIMIT = 4
   end
 
+  unless const_defined?(:FORCE_ENC)
+    FORCE_ENC = CR_NL.respond_to?(:force_encoding)
+  end
+
+  unless const_defined?(:HTTP_1_1)
+    HTTP_1_1 = " HTTP/1.1\r\n"
+  end
+
+  unless const_defined?(:HTTP_VERBS)
+    HTTP_VERBS = %w{connect delete get head options post put trace}
+  end
+
+  unless const_defined?(:HTTPS)
+    HTTPS = 'https'
+  end
+
   unless ::IO.const_defined?(:WaitReadable)
     class ::IO
       module WaitReadable; end

data/tests/idempotent_tests.rb

@@ -64,8 +64,7 @@ Shindo.tests('Excon request idempotencey') do
       end
     }
 
-    connection = Excon.new('http://127.0.0.1:9292')
-    connection.retry_limit = 2
+    connection = Excon.new('http://127.0.0.1:9292', :retry_limit => 2)
     response = connection.request(:method => :get, :idempotent => true, :path => '/some-path')
     response.status
   end
@@ -81,8 +80,7 @@ Shindo.tests('Excon request idempotencey') do
       end
     }
 
-    connection = Excon.new('http://127.0.0.1:9292')
-    connection.retry_limit = 2
+    connection = Excon.new('http://127.0.0.1:9292', :retry_limit => 2)
     response = connection.request(:method => :get, :idempotent => true, :path => '/some-path')
     response.status
   end
@@ -98,8 +96,7 @@ Shindo.tests('Excon request idempotencey') do
       end
     }
 
-    connection = Excon.new('http://127.0.0.1:9292')
-    connection.retry_limit = 8
+    connection = Excon.new('http://127.0.0.1:9292', :retry_limit => 8)
     response = connection.request(:method => :get, :idempotent => true, :path => '/some-path')
     response.status
   end
@@ -115,8 +112,7 @@ Shindo.tests('Excon request idempotencey') do
       end
     }
 
-    connection = Excon.new('http://127.0.0.1:9292')
-    connection.retry_limit = 8
+    connection = Excon.new('http://127.0.0.1:9292', :retry_limit => 8)
     response = connection.request(:method => :get, :idempotent => true, :path => '/some-path')
     response.status
   end
@@ -125,9 +121,6 @@ Shindo.tests('Excon request idempotencey') do
     run_count = 0
 
     connection = Excon.new('http://127.0.0.1:9292', :retry_limit => 6)
-    tests("setter sets").returns(6) do
-      connection.retry_limit
-    end
 
     Excon.stub({:method => :get}) { |params|
       run_count += 1

data/tests/instrumentation_tests.rb

@@ -0,0 +1,192 @@
+require 'active_support/notifications'
+
+class SimpleInstrumentor
+  class << self
+    attr_accessor :events
+
+    def instrument(name, params = {}, &block)
+      @events ||= []
+      @events << name
+      yield if block_given?
+    end
+  end
+end
+
+Shindo.tests('Excon instrumentation') do
+  before do
+    Excon.mock = true
+  end
+
+  after do
+    ActiveSupport::Notifications.unsubscribe("excon")
+    ActiveSupport::Notifications.unsubscribe("excon.request")
+    ActiveSupport::Notifications.unsubscribe("excon.retry")
+    ActiveSupport::Notifications.unsubscribe("excon.error")
+    ActiveSupport::Notifications.unsubscribe("gug")
+    Delorean.back_to_the_present
+    Excon.stubs.clear
+    Excon.mock = false
+  end
+
+  def subscribe(match)
+    @events = []
+    ActiveSupport::Notifications.subscribe(match) do |*args|
+      @events << ActiveSupport::Notifications::Event.new(*args)
+    end
+  end
+
+  def make_request(idempotent = false, params = {})
+    connection = Excon.new('http://127.0.0.1:9292',
+        :instrumentor => ActiveSupport::Notifications)
+    if idempotent
+      params[:idempotent] = :true
+    end
+    connection.get(params)
+  end
+
+  REQUEST_DELAY_SECONDS = 30
+  def stub_success
+    Excon.stub({:method => :get}) { |params|
+      Delorean.jump REQUEST_DELAY_SECONDS
+      {:body => params[:body], :headers => params[:headers], :status => 200}
+    }
+  end
+
+  def stub_retries
+    run_count = 0
+    Excon.stub({:method => :get}) { |params|
+      run_count += 1
+      if run_count <= 3 # First 3 calls fail.
+        raise Excon::Errors::SocketError.new(Exception.new "Mock Error")
+      else
+        {:body => params[:body], :headers => params[:headers], :status => 200}
+      end
+    }
+  end
+
+  def stub_failure
+    Excon.stub({:method => :get}) { |params|
+      raise Excon::Errors::SocketError.new(Exception.new "Mock Error")
+    }
+  end
+
+  tests('basic notification').returns('excon.request') do
+    subscribe(/excon/)
+    stub_success
+    make_request
+    @events.first.name
+  end
+
+  tests('captures scheme, host, port, and path').returns([:host, :path, :port, :scheme]) do
+    subscribe(/excon/)
+    stub_success
+    make_request
+    [:host, :path, :port, :scheme].select {|k| @events.first.payload.has_key? k}
+  end
+
+  tests('params in request overwrite those in construcor').returns('cheezburger') do
+    subscribe(/excon/)
+    stub_success
+    make_request(false, :host => 'cheezburger')
+    @events.first.payload[:host]
+  end
+
+  tests('notify on retry').returns(3) do
+    subscribe(/excon/)
+    stub_retries
+    make_request(true)
+    @events.count{|e| e.name =~ /retry/}
+  end
+
+  tests('notify on error').returns(true) do
+    subscribe(/excon/)
+    stub_failure
+    raises(Excon::Errors::SocketError) do
+      make_request
+    end
+
+    @events.any?{|e| e.name =~ /error/}
+  end
+
+  tests('filtering').returns(['excon.request', 'excon.error']) do
+    subscribe(/excon.request/)
+    subscribe(/excon.error/)
+    stub_failure
+    raises(Excon::Errors::SocketError) do
+      make_request(true)
+    end
+
+    @events.map(&:name)
+  end
+
+  tests('more filtering').returns(['excon.retry', 'excon.retry', 'excon.retry']) do
+    subscribe(/excon.retry/)
+    stub_failure
+    raises(Excon::Errors::SocketError) do
+      make_request(true)
+    end
+
+    @events.map(&:name)
+  end
+
+  tests('indicates duration').returns(true) do
+    subscribe(/excon/)
+    stub_success
+    make_request
+    (@events.first.duration/1000 - REQUEST_DELAY_SECONDS).abs < 1
+  end
+
+  tests('use our own instrumentor').returns(
+      ['excon.request', 'excon.retry', 'excon.retry', 'excon.retry', 'excon.error']) do
+    stub_failure
+    connection = Excon.new('http://127.0.0.1:9292',
+        :instrumentor => SimpleInstrumentor)
+    raises(Excon::Errors::SocketError) do
+      connection.get(:idempotent => true)
+    end
+
+    SimpleInstrumentor.events
+  end
+
+  tests('does not generate events when not provided').returns(0) do
+    subscribe(/excon/)
+    stub_success
+    connection = Excon.new('http://127.0.0.1:9292')
+    connection.get(:idempotent => true)
+    @events.count
+  end
+
+  tests('allows setting the prefix').returns(
+      ['gug.request', 'gug.retry', 'gug.retry','gug.retry', 'gug.error']) do
+    subscribe(/gug/)
+    stub_failure
+    connection = Excon.new('http://127.0.0.1:9292',
+        :instrumentor => ActiveSupport::Notifications, :instrumentor_name => 'gug')
+    raises(Excon::Errors::SocketError) do
+      connection.get(:idempotent => true)
+    end
+    @events.map(&:name)
+  end
+
+  tests('allows setting the prefix when not idempotent', 'foo').returns(
+    ['gug.request', 'gug.error']) do
+    subscribe(/gug/)
+    stub_failure
+    connection = Excon.new('http://127.0.0.1:9292',
+        :instrumentor => ActiveSupport::Notifications, :instrumentor_name => 'gug')
+    raises(Excon::Errors::SocketError) do
+      connection.get()
+    end
+    @events.map(&:name)
+  end
+
+  with_rackup('basic.ru') do
+    tests('works unmocked').returns('excon.request') do
+      Excon.mock = false
+      subscribe(/excon/)
+      make_request
+      @events.first.name
+    end
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-12 00:00:00.000000000Z
+date: 2011-12-14 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: open4
-  requirement: &5046310 !ruby/object:Gem::Requirement
+  requirement: &70338621231260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *5046310
+  version_requirements: *70338621231260
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &5046020 !ruby/object:Gem::Requirement
+  requirement: &70338621230800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *5046020
+  version_requirements: *70338621230800
 - !ruby/object:Gem::Dependency
   name: shindo
-  requirement: &5045670 !ruby/object:Gem::Requirement
+  requirement: &70338621230300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -45,10 +45,10 @@ dependencies:
         version: 0.2.0
   type: :development
   prerelease: false
-  version_requirements: *5045670
+  version_requirements: *70338621230300
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &5045400 !ruby/object:Gem::Requirement
+  requirement: &70338621229880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,7 +56,29 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *5045400
+  version_requirements: *70338621229880
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70338621220620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.3
+  type: :development
+  prerelease: false
+  version_requirements: *70338621220620
+- !ruby/object:Gem::Dependency
+  name: delorean
+  requirement: &70338621220200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70338621220200
 description: EXtended http(s) CONnections
 email: geemus@gmail.com
 executables: []
@@ -97,6 +119,7 @@ files:
 - tests/basic_tests.rb
 - tests/header_tests.rb
 - tests/idempotent_tests.rb
+- tests/instrumentation_tests.rb
 - tests/proxy_tests.rb
 - tests/query_string_tests.rb
 - tests/rackups/basic.ru
@@ -132,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: excon
-rubygems_version: 1.8.6
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 2
 summary: speed, persistence, http(s)