httpi 0.1.0 → 0.2.0

data/Gemfile

@@ -6,6 +6,6 @@ group :development, :test do
 end
 
 group :test do
-  gem "rspec", "2.0.0.beta.19"
+  gem "rspec", "2.0.0.beta.22"
   gem "mocha", "~> 0.9.8"
 end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    curb (0.7.8)
+    diff-lcs (1.1.2)
+    httpclient (2.1.5.2)
+    mocha (0.9.8)
+      rake
+    rake (0.8.7)
+    rspec (2.0.0.beta.22)
+      rspec-core (= 2.0.0.beta.22)
+      rspec-expectations (= 2.0.0.beta.22)
+      rspec-mocks (= 2.0.0.beta.22)
+    rspec-core (2.0.0.beta.22)
+    rspec-expectations (2.0.0.beta.22)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.0.beta.22)
+      rspec-core (= 2.0.0.beta.22)
+      rspec-expectations (= 2.0.0.beta.22)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  curb (~> 0.7.8)
+  httpclient (~> 2.1.5)
+  mocha (~> 0.9.8)
+  rspec (= 2.0.0.beta.22)

data/README.rdoc

@@ -1,6 +1,6 @@
 = HTTPI
 
-HTTPI provides a common interface for different HTTP libraries.
+HTTPI provides a common interface for Ruby HTTP libraries.
 
 == Installation
 
@@ -8,78 +8,107 @@ The gem is available through {Rubygems}[http://rubygems.org/gems/httpi] and can
 
   $ gem install httpi
 
-== Supported libraries
+== Basic examples
 
-* {httpclient}[http://rubygems.org/gems/httpclient] ~> 2.1.5
-* {curb}[http://rubygems.org/gems/curb] ~> 0.7.8
+Let's create the most basic request object and execute a GET request:
 
-== Getting started
+  request = HTTPI::Request.new :url => "http://example.com"
+  HTTPI::Client.get request
 
-To get started, simply create a new HTTPI::Client:
+And a POST request with a request object:
 
-  client = HTTPI::Client.new :curb
+  request = HTTPI::Request.new
+  request.url = "http://post.example.com"
+  request.body = "send me"
+  
+  HTTPI::Client.post request
 
-Notice that when you're not passing a library to use, HTTPI will default to use the HTTPClient library:
+Or a GET request using HTTP basic auth and the Curb adapter:
 
-  HTTPI::Adapter.use  # => :httpclient
+  request = HTTPI::Request.new
+  request.url = "http://auth.example.com"
+  request.basic_auth "username", "password"
+  
+  HTTPI::Client.get request, :curb
 
-Changing the default is fairly easy:
+HTTPI also comes with some shortcuts. This executes a GET request:
 
-  HTTPI::Adapter.use = :curb
+  HTTPI::Client.get "http://example.com"
 
-== Settings
+And here's a POST:
 
-=== #headers
+  HTTPI::Client.post "http://example.com", "<some>xml</some>"
 
-Accessor for the HTTP request headers:
+== HTTPI::Request
 
-  client.headers = { "Accept-Encoding" => "gzip" }
-  client.headers  # => { "Accept-Encoding" => "gzip" }
+The HTTPI::Request serves as a common denominator of options that HTTPI adapters need to support. It represents an HTTP request and lets you customize various settings:
 
-=== #proxy
+* [url]           the URL to access
+* [proxy]         the proxy server to use
+* [headers]       a Hash of HTTP headers
+* [body]          the HTTP request body
+* [open_timeout]  the open timeout (sec)
+* [read_timeout]  the read timeout (sec)
 
-Accessor for the proxy server to use:
+It also contains methods for setting up authentication:
 
-  client.proxy = "http://proxy.example.com"
-  client.proxy  # => #<URI::HTTP:0x1026240f0 URL:http://proxy.example.com>
+* [basic_auth]  HTTP basic auth credentials
 
-=== #auth(username, password)
+==== TODO:
 
-Setting authentication credentials:
+* Add support for HTTP digest authentication
+* Add support for SSL client authentication
 
-  client.auth "username", "password"
+== HTTPI::Client
 
-== Request methods
+The HTTPI::Client uses one of the available adapters to execute HTTP requests. It currently supports GET and POST requests:
 
-=== #get(url)
+=== GET
 
-Sending an HTTP GET request:
+* get(request, adapter = nil)
+* get(url, adapter = nil)
 
-  client.get "http://example.com"
+=== POST
 
-=== #post(url, body)
+* post(request, adapter = nil)
+* post(url, body, adapter = nil)
 
-Sending an HTTP POST request:
+You can specify the adapter to use per request. Request methods always returns an HTTPI::Response.
 
-  client.post "http://example.com", "<some>xml</xml>"
+==== TODO:
+
+* Add support for HEAD, PUT and DELETE requests
+
+== HTTPI::Adapter
+
+HTTPI uses adapters to support multiple HTTP libraries. It currently contains adapters for:
+
+* {httpclient}[http://rubygems.org/gems/httpclient] ~> 2.1.5
+* {curb}[http://rubygems.org/gems/curb] ~> 0.7.8
+
+By default, HTTPI uses the HTTPClient. But changing the default is fairly easy:
+
+  HTTPI::Adapter.use = :curb
+
+You can find a list of supported adapters via:
+
+  HTTPI::Adapter.adapters  # returns a Hash of supported adapters
 
 == HTTPI::Response
 
-Every HTTP request method is supposed to return an HTTPI::Response containing the response code, headers and body.
+As mentioned before, every request method return an HTTPI::Response. It contains the response code, headers and body.
 
-  response = client.get "http://example.com"
+  response = HTTPI::Client.get request
   
   response.code     # => 200
   response.headers  # => { "Content-Encoding" => "gzip" }
   response.body     # => "<!DOCTYPE HTML PUBLIC ..."
 
-== Participate
-
-I would appreciate any help to support additional libraries and methods!
+==== TODO
 
-== TODO
+* Return the original HTTPI::Request for debugging purposes
+* Return the time it took to execute the request
 
-Implement methods for:
+== Participate
 
-* add SSL configuration method
-* add timeout methods
+We appreciate any help and feedback, so please get in touch!

data/Rakefile

@@ -1,8 +1,34 @@
+require "rake"
+
 begin
-  require "rspec/core/rake_task"
+  require "yard"
+  
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["README.rdoc", "lib/**/*.rb"]
+  end
+rescue LoadError
+  desc message = %{"gem install yard" to generate documentation}
+  task("yard") { abort message }
+end
+
+begin
+  require "metric_fu"
+  
+  MetricFu::Configuration.run do |c|
+    c.metrics = [:churn, :flog, :flay, :reek, :roodi, :saikuro] # :rcov seems to be broken
+    c.graphs = [:flog, :flay, :reek, :roodi]
+    c.rcov[:rcov_opts] << "-Ilib -Ispec"
+  end
+rescue LoadError
+  desc message = %{"gem install metric_fu" to generate metrics}
+  task("metrics:all") { abort message }
+end
 
+begin
+  require "rspec/core/rake_task"
+  
   RSpec::Core::RakeTask.new do |t|
-    t.spec_opts = %w(-fd -c)
+    t.rspec_opts = %w(-fd -c)
   end
 rescue LoadError
   task :spec do

data/lib/httpi/adapter.rb

@@ -4,7 +4,7 @@ require "httpi/adapter/curb"
 module HTTPI
   module Adapter
 
-    # The default adapter.
+    # The def self.ault adapter.
     DEFAULT = :httpclient
 
     # Returns the adapter to use. Defaults to <tt>HTTPI::Adapter::DEFAULT</tt>.

data/lib/httpi/adapter/curb.rb

@@ -1,56 +1,48 @@
 require "httpi/response"
-require "httpi/adapter/base"
 
 module HTTPI
   module Adapter
-    module Curb
-      include Base
+    class Curb
 
-      def setup
+      def initialize
         require "curb"
       end
 
-      def client
-        @client ||= Curl::Easy.new
+      def get(request)
+        get_request(request) { |client| client.http_get }
       end
 
-      def headers
-        client.headers
+      def post(request)
+        post_request(request) { |client, body| client.http_post body }
       end
 
-      def headers=(headers)
-        client.headers = headers
-      end
-
-      def proxy
-        proxy = client.proxy_url
-        proxy.kind_of?(URI) ? proxy : URI(proxy)
-      end
-
-      def proxy=(proxy)
-        client.proxy_url = proxy
-      end
+    private
 
-      def auth(username, password)
-        client.username = username
-        client.password = password
+      def get_request(request)
+        client = client_for request
+        yield client
+        respond_with client
       end
 
-      def get(url)
-        client.url = url.to_s
-        client.http_get
-        respond
+      def post_request(request)
+        request.url = request.url.to_s
+        request.url.gsub!('?wsdl', '') if request.url =~ /\?wsdl$/
+        
+        client = client_for request
+        yield client, request.body
+        respond_with client
       end
 
-      def post(url, body)
-        client.url = url.to_s
-        client.http_post body
-        respond
+      def client_for(request)
+        client = Curl::Easy.new request.url.to_s
+        client.timeout = request.read_timeout
+        client.connect_timeout = request.open_timeout
+        client.headers = request.headers
+        client.verbose = false
+        client
       end
 
-    private
-
-      def respond
+      def respond_with(client)
         Response.new client.response_code, client.headers, client.body_str
       end
 

data/lib/httpi/adapter/httpclient.rb

@@ -1,47 +1,45 @@
 require "httpi/response"
-require "httpi/adapter/base"
 
 module HTTPI
   module Adapter
-    module HTTPClient
-      include Base
+    class HTTPClient
 
-      def setup
+      def initialize
         require "httpclient"
       end
 
-      def client
-        @client ||= ::HTTPClient.new
+      def get(request)
+        get_request request do |client, url, headers|
+          client.get url, nil, headers
+        end
       end
 
-      def headers
-        @headers ||= {}
+      def post(request)
+        post_request request do |client, url, headers, body|
+          client.post url, body, headers
+        end
       end
 
-      attr_writer :headers
-
-      def proxy
-        client.proxy
-      end
-
-      def proxy=(proxy)
-        client.proxy = proxy
-      end
+    private
 
-      def auth(username, password)
-        client.set_auth nil, username, password
+      def get_request(request)
+        client = client_for request
+        respond_with yield(client, request.url, request.headers)
       end
 
-      def get(url)
-        respond_with client.get(url)
+      def post_request(request)
+        client = client_for request
+        respond_with yield(client, request.url, request.headers, request.body)
       end
 
-      def post(url, body)
-        respond_with client.post(url, body, headers)
+      def client_for(request)
+        client = ::HTTPClient.new
+        client.proxy = request.proxy if request.proxy
+        client.connect_timeout = request.open_timeout
+        client.receive_timeout = request.read_timeout
+        client
       end
 
-    private
-
       def respond_with(response)
         Response.new response.code, Hash[response.header.all], response.content
       end

data/lib/httpi/client.rb

@@ -1,12 +1,70 @@
-require "httpi/interface"
+require "httpi/request"
+require "httpi/adapter"
 
 module HTTPI
   class Client
-    include Interface
+    class << self
 
-    def initialize(adapter = nil)
-      load! adapter
-    end
+      # Executes an HTTP GET request and returns an <tt>HTTPI::Response</tt>.
+      #
+      # ==== Example
+      #
+      # Accepts an <tt>HTTPI::Request</tt> and an optional adapter:
+      #
+      #   request = HTTPI::Request.new :url => "http://example.com"
+      #   HTTPI::Client.get request, :httpclient
+      #
+      # ==== Shortcut
+      #
+      # You can also just pass a URL and an optional adapter if you don't
+      # need to configure the request:
+      #
+      #   HTTPI::Client.get "http://example.com", :curb
+      def get(request, adapter = nil)
+        request = Request.new :url => request if request.kind_of? String
+        find_adapter(adapter).get request
+      end
+
+      # Executes an HTTP POST request and returns an <tt>HTTPI::Response</tt>.
+      #
+      # ==== Example
+      #
+      # Accepts an <tt>HTTPI::Request</tt> and an optional adapter:
+      #
+      #   request = HTTPI::Request.new
+      #   request.url = "http://example.com"
+      #   request.body = "<some>xml</some>"
+      #   
+      #   HTTPI::Client.post request, :httpclient
+      #
+      # ==== Shortcut
+      #
+      # You can also just pass a URL, a request body and an optional adapter
+      # if you don't need to configure the request:
+      #
+      #   HTTPI::Client.post "http://example.com", "<some>xml</some>", :curb
+      def post(*args)
+        request, adapter = extract_post_args(args)
+        find_adapter(adapter).post request
+      end
+
+    private
 
+      # Checks whether +args+ contains of an <tt>HTTPI::Request</tt> or a URL
+      # and a request body plus an optional adapter and returns an Array with
+      # an <tt>HTTPI::Request</tt> and (if given) an adapter.
+      def extract_post_args(args)
+        return args if args.first.kind_of? Request
+        [Request.new(:url => args[0], :body => args[1]), args[2]]
+      end
+
+      # Accepts an +adapter+ (defaults to <tt>Adapter.use</tt>) and returns
+      # a new instance of the adapter to use.
+      def find_adapter(adapter)
+        adapter ||= Adapter.use
+        Adapter.find(adapter).new
+      end
+
+    end
   end
 end