giant_client 0.1.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Zack Reneau-Wedeen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+##Giant Client
+
+Giant Client is a ruby library which exposes a simple and uniform API for
+using a variety of http clients. Advantages of Giant Client:
+* Clean, easy-to-use, cruftless API
+* Testing as simple as it gets with a built in test framework that uses the exact same API
+* Take advantage of 5+ http clients while only learning one API
+* Seamlessly swap between http clients with one line of configuration (rather than erasing all of your code)
+
+
+## Installation
+
+*Note: not yet available*
+
+Add this line to your application's Gemfile:
+
+    gem 'giant_client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install giant_client
+
+## Usage
+*In this guide, I am very exhaustive with options, so it seems long winded, but this is just to show all configuration options, most are optional.*
+
+####Initialize a new Giant Client
+    options = {
+      :host => "www.example.com",  # optional, defaults to ""
+      :ssl => true,                # optional, defaults to false
+      :port => 443,                # optional, defaults to 443 when ssl == true,
+                                   #                 and to 80 when ssl == false
+      :adapter => :typhoeus  # optional, defaults to :net_http, options detailed below
+    }
+
+    client = GiantClient.new(options)
+
+######Passing a symbol argument as the first argument to initialize is assumed to be the adapter
+######short hand
+    client = GiantClient.new :patron, :host => 'example.com'
+
+####Adapters
+*There are currently five adapters supported. They use the libraries they are named after.*
+    :net_http
+    :patron
+    :excon
+    :curb
+    :typhoeus
+
+####The API
+Giant Client supports the HTTP 'GET', 'POST', 'PUT', 'DELETE', and 'HEAD' methods
+*The 'GET', 'DELETE', and 'HEAD' methods do not support a request body. Attempting to pass one will cause Giant Client to throw a NotImplementedError*
+#####All methods support ssl, host, port, path, query, headers, and body as options.
+
+#####Note:
+*ssl defaults to ssl provided in new (true here)*
+*host defaults to host provided in new ('www.example.com' here)*
+*port defaults to port provided in new ('443' here)*
+
+
+######GET
+    client.get({
+      :path => '/path/to/resource',                    # optional, defaults to '/'
+      :headers => { 'Accepts' => 'application/json' }, # optional, defaults to {}
+      :query => { 'post_id' => '29' }                  # optional, defaults to {}
+    })
+######POST
+    client.post({
+      :path => '/path/to/resource',                    # optional, defaults to '/'
+      :body => 'hey, how\'s it going?',                # optional, defaults to ''
+    })
+######PUT
+    client.put({
+      :path => '/path/to/resource',                    # optional, defaults to '/'
+      :body => 'hey, how\'s it going?'                # optional, defaults to ''
+    })
+######DELETE
+    client.delete({
+      :path => '/path/to/resource?for_good=true'
+    })
+######HEAD
+    client.head({
+      :path => '/path/to/resource'
+    })
+######Giant Client also exposes a general `request` method, which each method calls under the hood.
+    client.request(:get, {
+      :path => '/search?q=ahoy',
+    })
+
+####Return Value
+All of Giant Client's request methods return a uniform response object. This object has accessors for `status_code`, `headers`, and `body`
+In general, `status_code` is a number, `headers` is a Hash, and `body` is a String.
+######Example
+    response = client.request(:get, {
+      :path => '/search?q=ahoy',
+    })
+    puts response.status_code  # e.g. 200
+    puts response.headers      # e.g. {'Content-Type' => 'application/json' }
+    puts response.body         # e.g. 'ahoy matee'
+
+######Giant Client provides getters and setters to default port, host, and ssl.
+    # one request over http on port 80
+    g_client = GiantClient.new( :adapter => :typhoeus, :host => 'www.google.com' )
+    g_client.get(:path => '/')
+
+    # the next on port 8080
+    # 2 ways to do this:
+    # way 1
+    g_client.port = 8080
+    g_client.get(:path => '/')
+    # way 2
+    g_client.get(:path => '/', :port => 8080)
+
+######Timeouts
+In GiantClient timeouts can be configured on initialization or request by request. 
+If you just leave it alone, the default timeout is 30 seconds. This is roughly the average of the clients supported. 
+Setting a timeout sets both the read timeout and the connect timeout.
+*Setting a Timeout*
+    # on configuration
+    client = GiantClient.new( :adapter => :typhoeus, :timeout => 5 ) # five second timeout
+    client.get '/'                                                   # will raise a GiantClient::TimeoutError if it takes longer than 5 seconds.
+
+    # request specific timeout
+    client = GiantClient.new :typhoeus           # five second timeout
+    client.get '/', :timeout => 1                # will raise a GiantClient::TimeoutError if it takes longer than 1 second.
+
+######Passing a string as the options will set path = to that string and all other options to their defaults
+    client.get('/') # same as :path => '/'
+
+######Passing a string and options will set path = to that string and all other options to those specified in the options
+    client.get('/', { :query => "foo=bar" }) # same as :path => '/', :query => "foo=bar"
+
+######The string argument takes precedence
+    client.get('/', {:path => '/this/does/not/matter'}) # same as :path => '/'
+
+######Passing more than 2 arguments or fewer than one argument will raise an ArgumentError
+    client.get('I', 'skipped', 'the', 'README') # ArgumentError
+
+*Note: this is true with initialize too*
+
+####Testing
+
+Testing is easier than ever if you use GiantClient. Just call `GiantClient.new :adapter => :mock` and GiantClient will stub out all your requests.
+When the adapter is set to `:mock` GiantClient stores all of your requests on a stack: `client.requests`. This is also true for responses.
+`last_request` is shorthand (or longhand, actually) for `requests[0]` Check it out.
+
+    describe 'Mock Adapter' do
+      let(:client){ GiantClient.new :host => 'example.com', :adapter => :mock }
+
+      context 'super simple request' do
+        before do
+          client.get('/')
+        end
+
+        it 'should record the url' do
+          client.last_request.url.should == 'http://example.com/'
+        end
+      end
+      context 'request with all options set' do
+        before do
+          opts = {
+            :ssl => true,
+            :port => 9292,
+            :path => '/hey/there',
+            :query => { 'howya' => 'doing' },
+            :headers => { 'Content-Type' => 'application/awesome' },
+            :body => 'test body',
+            :timeout => 27
+          }
+          client.get(opts)
+        end
+
+        it 'should record the (correct) url' do
+          url = 'https://example.com:9292/hey/there?howya=doing'
+          client.last_request.url.should == url
+        end
+
+        it 'should record the (correct) ssl' do
+          client.last_request.ssl.should == true
+        end
+        it 'should record the (correct) port' do
+          client.last_request.port.should == 9292
+        end
+        it 'should record the (correct) path' do
+          client.last_request.path.should == '/hey/there'
+        end
+        it 'should record the (correct) query' do
+          client.last_request.query.should == { 'howya' => 'doing' }
+        end
+        it 'should record the (correct) query_string' do
+          client.last_request.querystring.should == 'howya=doing'
+        end
+        it 'should record the (correct) headers' do
+          client.last_request.headers.should ==
+                                { 'Content-Type' => 'application/awesome' }
+        end
+        it 'should record the (correct) body' do
+          client.last_request.body.should == 'test body'
+        end
+        it 'should record the (correct) timeout' do
+          client.last_request.timeout.should == 27
+        end
+      end
+    end
+
+Giant Client creates a response hash for the mock requests. By default it is this:
+
+    {
+      :status_code => 200,
+      :headers     => {},
+      :body        => nil
+    }
+
+You can manipulate the response to a specific request with the `respond_with` method, which merges in your settings:
+    client.get('/').respond_with(:body => 'hey')
+    client.last_response.should == {
+                                     :status_code => 200,
+                                     :headers     => {},
+                                     :body        => 'hey'
+                                   }
+You can set arbitrary fields (although there usually isn't reason to)
+
+    client.get('/').respond_with(:headers => {}:body => 'hey')
+    client.last_response.should == {
+                                     :status_code => 200,
+                                     :headers     => {},
+                                     :body        => 'hey'
+                                   }
+
+As many as you want
+
+    client.get('/').respond_with(:headers => {
+                                                'Content-Type' => 'application/json',
+                                                'X-Powered-By' => 'Internet'
+                                             },
+                                             :body => 'hey',
+                                             :foo  => 'bar'
+                                )
+    client.last_response.should == {
+                                     :status_code => 200,
+                                     :headers     => {
+                                                        'Content-Type' => 'application/json',
+                                                        'X-Powered-By' => 'Internet'
+                                                     },
+                                     :body        => 'hey',
+                                     :foo        => 'bar'
+                                   }
+
+    # in practice you'll usually just test a property at a time e.g.
+    client.last_response[:body].should == 'hey' # much cleaner
+
+
+*For tests with multiple requests / responses, visit spec/examples/mock_adapter_spec.rb*
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/giant_client.rb

@@ -0,0 +1,105 @@
+require 'giant_client/response'
+require 'giant_client/error'
+
+class GiantClient
+  BODYLESS_METHODS = [:get, :delete, :head]
+
+  attr_accessor :host, :ssl, :port
+  attr_reader :adapter
+
+  def initialize(*args)
+
+    unless args.length.between?(1, 2)
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+
+    opts = Hash === args.last ? args.last : { :adapter => args.last }
+    if String === args.first
+      opts[:adapter] = args.first
+    end
+
+    @host = opts[:host]
+    @ssl = !!opts[:ssl]
+    default_port = @ssl ? 443 : 80
+    @port = opts[:port] || default_port
+    @timeout = opts[:timeout] || 2
+
+    @default_opts = {
+      :host => @host,
+      :ssl => @ssl,
+      :port => @port,
+      :path => '/',
+      :query => {},
+      :headers => {},
+      :body => "",
+      :timeout => 30
+    }
+
+    # default timeouts
+    # patron:      5
+    # net/http:    60
+    # curb:        none
+    # excon:       60
+    # typhoeus:
+
+    self.adapter = opts[:adapter] || :net_http
+    @client = @adapter.new
+
+  end
+
+  def adapter=(new_adapter)
+    require "giant_client/#{new_adapter}_adapter"
+    normalized = new_adapter.to_s.split('_').map{ |s| s.capitalize }.join
+    @adapter = GiantClient.const_get("#{normalized}Adapter")
+    @client = @adapter.new
+  end
+
+  def method_missing(method, *args)
+
+    unless args.length.between?(1, 2)
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+
+    opts = Hash === args.last ? args.last : { :path => args.last }
+    if String === args.first
+      opts[:path] = args.first
+    end
+
+    opts = @default_opts.merge(opts)
+    @client.__send__(method, opts)
+  end
+
+  # for the mock adapter only
+  def last_request
+    if MockAdapter === @client
+      @client.last_request
+    else
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+  end
+
+  def requests
+    if MockAdapter === @client
+      @client.requests
+    else
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+  end
+
+  def last_response
+    if MockAdapter === @client
+      @client.last_response
+    else
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+  end
+
+  def responses
+    if MockAdapter === @client
+      @client.responses
+    else
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)";
+    end
+  end
+
+end

data/lib/giant_client/abstract_adapter.rb

@@ -0,0 +1,71 @@
+class GiantClient
+  class AbstractAdapter
+
+    def url_from_opts(opts)
+      query = encode_query(opts[:query])
+
+      if opts[:ssl]
+        scheme = 'https://'
+        port = opts[:port] == 443 ? '' : ":#{opts[:port]}"
+      else
+        scheme = 'http://'
+        port = opts[:port] == 80 ? '' : ":#{opts[:port]}"
+      end
+
+      "#{scheme}#{opts[:host]}#{port}#{opts[:path]}#{query}"
+    end
+
+    def encode_query(query)
+      query = stringify_query(query)
+      query = prepend_question_mark(query) unless query == ''
+      query
+    end
+
+    def stringify_query(query)
+      if Hash === query
+        query = URI.encode_www_form(query)
+      elsif query.nil?
+        query = ''
+      end
+      query
+    end
+
+    def prepend_question_mark(str)
+      "?#{str}"
+    end
+
+    def normalize_header_hash(headers)
+      normalized_headers = {}
+      headers.each do |header, value|
+        normalized = normalize_header(header)
+        normalized_headers[normalized] = value
+      end
+      normalized_headers
+    end
+
+    def normalize_header(header)
+      header.split('-').map{|h| h.capitalize}.join('-')
+    end
+
+    def get(opts)
+      request(:get, opts)
+    end
+
+    def post(opts)
+      request(:post, opts)
+    end
+
+    def put(opts)
+      request(:put, opts)
+    end
+
+    def delete(opts)
+      request(:delete, opts)
+    end
+
+    def head(opts)
+      request(:head, opts)
+    end
+
+  end
+end