httpi 0.7.4 → 0.7.5

data/README.md

@@ -25,7 +25,7 @@ Here's a POST request with a request object:
     request = HTTPI::Request.new
     request.url = "http://post.example.com"
     request.body = "send me"
-  
+    
     HTTPI.post request
 
 And a GET request using HTTP basic auth and the Curb adapter:
@@ -33,7 +33,7 @@ And a GET request using HTTP basic auth and the Curb adapter:
     request = HTTPI::Request.new
     request.url = "http://auth.example.com"
     request.auth.basic "username", "password"
-  
+    
     HTTPI.get request, :curb
 
 HTTPI also comes shortcuts. This executes a PUT request:
@@ -102,7 +102,7 @@ By default, HTTPI uses the `HTTPClient` adapter. But changing the default is fai
 
     HTTPI::Adapter.use = :curb  # or one of [:httpclient, :net_http]
 
-Notice: HTTPI does not force you to install any of these libraries. Instead you need to make sure to install the HTTP library of your choice and/or add it to your Gemfile. HTTPI will then load the library when executing HTTP requests.
+Notice: HTTPI does not force you to install any of these libraries. So please make sure to install the HTTP library of your choice and/or add it to your Gemfile. HTTPI will then load the library when executing HTTP requests. HTTPI will fall back to using net/http when any other adapter could not be loaded.
 
 HTTPI::Request
 --------------
@@ -178,6 +178,15 @@ The `response.body` handles gzipped and [DIME](http://en.wikipedia.org/wiki/Dire
 * Return the original `HTTPI::Request` for debugging purposes
 * Return the time it took to execute the request
 
+Logging
+-------
+
+HTTPI by default logs each HTTP request to STDOUT using a log level of :debug.
+
+    HTTPI.log       = false     # disabling logging
+    HTTPI.logger    = MyLogger  # changing the logger
+    HTTPI.log_level = :info     # changing the log level
+
 Participate
 -----------
 

data/httpi.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "curb", "~> 0.7.8"
 
   s.add_development_dependency "rspec", "~> 2.2"
+  s.add_development_dependency "autotest"
   s.add_development_dependency "mocha", "~> 0.9.9"
   s.add_development_dependency "webmock", "~> 1.4.0"
 

data/lib/httpi.rb

@@ -1,3 +1,4 @@
+require "logger"
 require "httpi/version"
 require "httpi/request"
 require "httpi/adapter"
@@ -72,13 +73,15 @@ module HTTPI
 
   REQUEST_METHODS = [:get, :post, :head, :put, :delete]
 
+  DEFAULT_LOG_LEVEL = :debug
+
   class << self
 
     # Executes an HTTP GET request.
     def get(request, adapter = nil)
       request = Request.new :url => request if request.kind_of? String
       
-      with request, adapter do |adapter|
+      with_adapter :get, request, adapter do |adapter|
         yield adapter.client if block_given?
         adapter.get request
       end
@@ -88,7 +91,7 @@ module HTTPI
     def post(*args)
       request, adapter = request_and_adapter_from(args)
       
-      with request, adapter do |adapter|
+      with_adapter :post, request, adapter do |adapter|
         yield adapter.client if block_given?
         adapter.post request
       end
@@ -98,7 +101,7 @@ module HTTPI
     def head(request, adapter = nil)
       request = Request.new :url => request if request.kind_of? String
       
-      with request, adapter do |adapter|
+      with_adapter :head, request, adapter do |adapter|
         yield adapter.client if block_given?
         adapter.head request
       end
@@ -108,7 +111,7 @@ module HTTPI
     def put(*args)
       request, adapter = request_and_adapter_from(args)
       
-      with request, adapter do |adapter|
+      with_adapter :put, request, adapter do |adapter|
         yield adapter.client if block_given?
         adapter.put request
       end
@@ -118,7 +121,7 @@ module HTTPI
     def delete(request, adapter = nil)
       request = Request.new :url => request if request.kind_of? String
       
-      with request, adapter do |adapter|
+      with_adapter :delete, request, adapter do |adapter|
         yield adapter.client if block_given?
         adapter.delete request
       end
@@ -130,6 +133,42 @@ module HTTPI
       send method, request, adapter
     end
 
+    # Sets whether to log HTTP requests.
+    attr_writer :log
+
+    # Returns whether to log HTTP requests. Defaults to +true+.
+    def log?
+      @log != false
+    end
+
+    # Sets the logger to use.
+    attr_writer :logger
+
+    # Returns the logger. Defaults to an instance of +Logger+ writing to STDOUT.
+    def logger
+      @logger ||= ::Logger.new STDOUT
+    end
+
+    # Sets the log level.
+    attr_writer :log_level
+
+    # Returns the log level. Defaults to :debug.
+    def log_level
+      @log_level ||= :debug
+    end
+
+    # Logs given +messages+.
+    def log(*messages)
+      logger.send log_level, messages.join(" ") if log?
+    end
+
+    # Reset the default config.
+    def reset_config!
+      @log = nil
+      @logger = nil
+      @log_level = nil
+    end
+
   private
 
     # Checks whether +args+ contains of an <tt>HTTPI::Request</tt> or a URL
@@ -140,11 +179,14 @@ module HTTPI
       [Request.new(:url => args[0], :body => args[1]), args[2]]
     end
 
-    # Expects a +request+ and an +adapter+ (defaults to <tt>Adapter.use</tt>)
-    # and yields a new instance of the adapter to a given block.
-    def with(request, adapter)
+    # Expects a request +method+, a +request+ and an +adapter+ (defaults to
+    # <tt>Adapter.use</tt>) and yields an instance of the adapter to a given block.
+    def with_adapter(method, request, adapter)
       adapter ||= Adapter.use
-      yield Adapter.find(adapter).new(request)
+      adapter, adapter_class = Adapter.find adapter
+      
+      HTTPI.log "HTTPI executes HTTP #{method.to_s.upcase} using the #{adapter} adapter"
+      yield adapter_class.new(request)
     end
 
   end

data/lib/httpi/adapter.rb

@@ -15,6 +15,9 @@ module HTTPI
     # The default adapter.
     DEFAULT = :httpclient
 
+    # The fallback (worst-choice) adapter.
+    FALLBACK = :net_http
+
     # Returns the adapter to use. Defaults to <tt>HTTPI::Adapter::DEFAULT</tt>.
     def self.use
       @use ||= DEFAULT
@@ -28,13 +31,17 @@ module HTTPI
 
     # Returns a memoized +Hash+ of adapters.
     def self.adapters
-      @adapters ||= { :httpclient => HTTPClient, :curb => Curb, :net_http => NetHTTP }
+      @adapters ||= {
+        :httpclient => { :class => HTTPClient, :require => "httpclient" },
+        :curb       => { :class => Curb,       :require => "curb" },
+        :net_http   => { :class => NetHTTP,    :require => "net/https" }
+      }
     end
 
     # Returns an +adapter+. Raises an +ArgumentError+ unless the +adapter+ exists.
     def self.find(adapter)
       validate_adapter! adapter
-      adapters[adapter]
+      load_adapter adapter
     end
 
   private
@@ -44,5 +51,17 @@ module HTTPI
       raise ArgumentError, "Invalid HTTPI adapter: #{adapter}" unless adapters[adapter]
     end
 
+    # Tries to load and return the given +adapter+ name and class and falls back to the +FALLBACK+ adapter.
+    def self.load_adapter(adapter)
+      require adapters[adapter][:require]
+      [adapter, adapters[adapter][:class]]
+    rescue LoadError
+      HTTPI.log "HTTPI tried to use the #{adapter} adapter, but was unable to find the library in the LOAD_PATH.",
+        "Falling back to using the #{FALLBACK} adapter now."
+      
+      require adapters[FALLBACK][:require]
+      [FALLBACK, adapters[FALLBACK][:class]]
+    end
+
   end
 end

data/lib/httpi/adapter/curb.rb

@@ -9,9 +9,7 @@ module HTTPI
     # http://rubygems.org/gems/curb
     class Curb
 
-      # Requires the "curb" gem.
       def initialize(request = nil)
-        require "curb"
       end
 
       # Returns a memoized <tt>Curl::Easy</tt> instance.

data/lib/httpi/adapter/httpclient.rb

@@ -9,9 +9,7 @@ module HTTPI
     # http://rubygems.org/gems/httpclient
     class HTTPClient
 
-      # Requires the "httpclient" gem.
       def initialize(request = nil)
-        require "httpclient"
       end
 
       # Returns a memoized <tt>HTTPClient</tt> instance.

data/lib/httpi/adapter/net_http.rb

@@ -10,9 +10,7 @@ module HTTPI
     # http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/
     class NetHTTP
 
-      # Requires the "net/https" library and sets up a new client.
       def initialize(request)
-        require "net/https"
         self.client = new_client request
       end
 

data/lib/httpi/version.rb

@@ -1,5 +1,5 @@
 module HTTPI
 
-  VERSION = "0.7.4"
+  VERSION = "0.7.5"
 
 end

data/spec/httpi/adapter/curb_spec.rb

@@ -8,13 +8,6 @@ describe HTTPI::Adapter::Curb do
   let(:adapter) { HTTPI::Adapter::Curb.new }
   let(:curb) { Curl::Easy.any_instance }
 
-  describe ".new" do
-    it "should require the Curb gem" do
-      HTTPI::Adapter::Curb.any_instance.expects(:require).with("curb")
-      HTTPI::Adapter::Curb.new
-    end
-  end
-
   describe "#get" do
     before do
       curb.expects(:http_get)

data/spec/httpi/adapter/httpclient_spec.rb

@@ -9,13 +9,6 @@ describe HTTPI::Adapter::HTTPClient do
   let(:httpclient) { HTTPClient.any_instance }
   let(:ssl_config) { HTTPClient::SSLConfig.any_instance }
 
-  describe ".new" do
-    it "should require the HTTPClient gem" do
-      HTTPI::Adapter::HTTPClient.any_instance.expects(:require).with("httpclient")
-      HTTPI::Adapter::HTTPClient.new
-    end
-  end
-
   describe "#get" do
     it "should return a valid HTTPI::Response" do
       httpclient.expects(:get).with(basic_request.url, nil, basic_request.headers).returns(http_message)

data/spec/httpi/adapter/net_http_spec.rb

@@ -9,13 +9,6 @@ describe HTTPI::Adapter::NetHTTP do
     @adapter ||= HTTPI::Adapter::NetHTTP.new request
   end
 
-  describe ".new" do
-    it "should require the Net::HTTP library" do
-      HTTPI::Adapter::NetHTTP.any_instance.expects(:require).with("net/https")
-      HTTPI::Adapter::NetHTTP.new HTTPI::Request.new(:url => "http://example.com")
-    end
-  end
-
   describe "#get" do
     it "should return a valid HTTPI::Response" do
       stub_request(:get, basic_request.url.to_s).to_return(:body => Fixture.xml)

data/spec/httpi/adapter_spec.rb

@@ -23,24 +23,47 @@ describe HTTPI::Adapter do
   end
 
   describe ".adapters" do
-    it "should return a memoized Hash of adapters" do
-      adapter.adapters.should have(3).items
-      adapter.adapters.should include(
-        :httpclient => HTTPI::Adapter::HTTPClient,
-        :curb => HTTPI::Adapter::Curb,
-        :net_http => HTTPI::Adapter::NetHTTP
-      )
+    it "should return a Hash of adapter details" do
+      adapter.adapters.should == {
+        :httpclient => { :class => HTTPI::Adapter::HTTPClient, :require => "httpclient" },
+        :curb       => { :class => HTTPI::Adapter::Curb,       :require => "curb" },
+        :net_http   => { :class => HTTPI::Adapter::NetHTTP,    :require => "net/https" }
+      }
+    end
+
+    it "should return a memoized Hash" do
+      adapter.adapters.should equal(adapter.adapters)
     end
   end
 
   describe ".find" do
-    it "should return the adapter for a given Symbol" do
-      adapter.find(:httpclient).should == HTTPI::Adapter::HTTPClient
+    it "should return the adapter name and class for a given Symbol" do
+      adapter.find(:httpclient).should == [:httpclient, HTTPI::Adapter::HTTPClient]
     end
 
     it "should raise an ArgumentError in case of an invalid adapter" do
       lambda { adapter.find :unknown }.should raise_error(ArgumentError)
     end
+
+    context "when the given adapter could not be found" do
+      before do
+        adapter.expects(:require).with("httpclient").raises(LoadError)
+        adapter.expects(:require).with(HTTPI::Adapter.adapters[HTTPI::Adapter::FALLBACK][:require])
+      end
+
+      it "should fall back to use the HTTPI::Adapter::FALLBACK adapter" do
+        adapter.find :httpclient
+      end
+
+      it "should log that the adapter to use could not be required" do
+        HTTPI.expects(:log).with(
+          "HTTPI tried to use the httpclient adapter, but was unable to find the library in the LOAD_PATH.",
+          "Falling back to using the #{HTTPI::Adapter::FALLBACK} adapter now."
+        )
+        
+        adapter.find :httpclient
+      end
+    end
   end
 
 end

data/spec/httpi/httpi_spec.rb

@@ -3,8 +3,8 @@ require "httpi"
 
 describe HTTPI do
   let(:client) { HTTPI }
-  let(:default_adapter) { HTTPI::Adapter.find HTTPI::Adapter.use }
-  let(:curb) { HTTPI::Adapter.find :curb }
+  let(:default_adapter) { HTTPI::Adapter.find(HTTPI::Adapter.use)[1] }
+  let(:curb) { HTTPI::Adapter.find(:curb)[1] }
 
   describe ".get(request)" do
     it "should execute an HTTP GET request using the default adapter" do
@@ -197,7 +197,6 @@ describe HTTPI do
   end
 
   HTTPI::REQUEST_METHODS.each do |method|
-
     describe ".request(#{method}, request, adapter)" do
       it "should delegate to the .#{method} method" do
         HTTPI.expects(method)
@@ -206,25 +205,30 @@ describe HTTPI do
     end
 
     describe ".#{method}" do
+      let(:request) { HTTPI::Request.new :url => "http://example.com" }
+
       it "should raise an ArgumentError in case of an invalid adapter" do
-        lambda { client.request method, HTTPI::Request.new, :invalid }.should raise_error(ArgumentError)
+        lambda { client.request method, request, :invalid }.should raise_error(ArgumentError)
       end
 
       it "should raise an ArgumentError in case of an invalid request" do
         lambda { client.request method, "invalid" }.should raise_error(ArgumentError)
       end
 
-      HTTPI::Adapter.adapters.each do |adapter, adapter_class|
+      HTTPI::Adapter.adapters.each do |adapter, values|
         client_class = {
           :httpclient => lambda { HTTPClient },
           :curb       => lambda { Curl::Easy },
           :net_http   => lambda { Net::HTTP }
         }
 
-        context "using :#{adapter} with a block" do
-          let(:request) { HTTPI::Request.new :url => "http://example.com" }
+        context "using #{adapter}" do
+          before { values[:class].any_instance.expects(method) }
 
-          before { adapter_class.any_instance.stubs(method) }
+          it "should log that we're executing an HTTP request" do
+            HTTPI.expects(:log).with("HTTPI executes HTTP #{method.to_s.upcase} using the #{adapter} adapter")
+            client.request method, request, adapter
+          end
 
           it "should yield the HTTP client instance used for the request" do
             block = lambda { |http| http.should be_a(client_class[adapter].call) }
@@ -233,6 +237,75 @@ describe HTTPI do
         end
       end
 
+      HTTPI::Adapter.adapters.reject { |key, value| key == HTTPI::Adapter::FALLBACK }.each do |adapter, values|
+        context "when #{adapter} could not be loaded" do
+          before do
+            HTTPI::Adapter.expects(:require).with(values[:require]).raises(LoadError)
+            HTTPI::Adapter.expects(:require).with("net/https")
+            HTTPI::Adapter::NetHTTP.any_instance.expects(method)
+          end
+
+          it "should fall back to using the FALLBACK adapter" do
+            HTTPI.expects(:log).with(
+              "HTTPI tried to use the #{adapter} adapter, but was unable to find the library in the LOAD_PATH.",
+              "Falling back to using the #{HTTPI::Adapter::FALLBACK} adapter now."
+            )
+            HTTPI.expects(:log).with("HTTPI executes HTTP #{method.to_s.upcase} using the #{HTTPI::Adapter::FALLBACK} adapter")
+            
+            client.request method, request, adapter
+          end
+        end
+      end
+    end
+  end
+
+  context "with resetting the defaults" do
+    before { HTTPI.reset_config! }
+
+    after do
+      HTTPI.reset_config!
+      HTTPI.log = false  # disable for specs
+    end
+
+    describe ".log" do
+      it "should default to true" do
+        HTTPI.log?.should be_true
+      end
+
+      it "should set whether to log" do
+        HTTPI.log = false
+        HTTPI.log?.should be_false
+      end
+    end
+
+    describe ".logger" do
+      it "should default to Logger writing to STDOUT" do
+        HTTPI.logger.should be_a(Logger)
+      end
+
+      it "should set the logger to use" do
+        MyLogger = Class.new
+        HTTPI.logger = MyLogger
+        HTTPI.logger.should == MyLogger
+      end
+    end
+
+    describe ".log_level" do
+      it "should default to :debug" do
+        HTTPI.log_level.should == :debug
+      end
+
+      it "should set the log level to use" do
+        HTTPI.log_level = :info
+        HTTPI.log_level.should == :info
+      end
+    end
+
+    describe ".log" do
+      it "should log given messages" do
+        HTTPI.logger.expects(:debug).with("Log this")
+        HTTPI.log "Log", "this"
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -6,5 +6,7 @@ RSpec.configure do |config|
   config.mock_with :mocha
 end
 
+HTTPI.log = false  # disable for specs
+
 require "support/fixture"
 require "support/matchers"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: httpi
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: false
   segments: 
   - 0
   - 7
-  - 4
-  version: 0.7.4
+  - 5
+  version: 0.7.5
 platform: ruby
 authors: 
 - Daniel Harrington
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-20 00:00:00 +01:00
+date: 2010-12-22 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -81,9 +81,23 @@ dependencies:
   type: :development
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: mocha
+  name: autotest
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -95,11 +109,11 @@ dependencies:
         - 9
         version: 0.9.9
   type: :development
-  version_requirements: *id005
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: webmock
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -111,7 +125,7 @@ dependencies:
         - 0
         version: 1.4.0
   type: :development
-  version_requirements: *id006
+  version_requirements: *id007
 description: HTTPI provides a common interface for Ruby HTTP libraries.
 email: me@rubiii.com
 executables: []