excon 0.6.4 → 0.6.5

data/README.rdoc

@@ -4,35 +4,58 @@ Http(s) EXtended CONnections
 
 == Getting Started
 
-  sudo gem install excon
+Install the gem.
 
-Now you are ready to get started using one off requests.
+  $ sudo gem install excon
+
+Require with rubygems.
 
   require 'rubygems'
   require 'excon'
-  Excon.get('http://geemus.com')
 
-The returned response object has #body, #headers and #status attributes. Supported one off requests are #connect, #delete, #get, #head, #options, #post, #put, and #trace
+The simplest way to use excon is with one-off requests:
+
+  response = Excon.get('http://geemus.com')
+
+Supported one off request methods are #connect, #delete, #get, #head, #options, #post, #put, and #trace. 
 
-You can also create a connection to reuse across multiple requests (more performant!).
+The returned response object has #body, #headers and #status attributes. 
+
+Alternately you can create a connection object which is reusable across multiple requests (more performant!).
 
   connection = Excon.new('http://geemus.com')
-  connection.request(:method => 'GET')
+  response_one = connection.request(:method => 'GET')
+  response_two = connection.request(:method => 'POST', :path => '/foo')
+  response_three = connection.request(:method => 'DELETE', :path => '/bar')
 
-Both one off and persistent connections also support many other options, for example:
+Both one-off and persistent connections support many other options. Here are a few common examples:
 
+  # Custom headers
   Excon.get('http://geemus.com', :headers => {'Authorization' => 'Basic 0123456789ABCDEF'})
-  # or
   connection.request(:method => 'GET', :headers => {'Authorization' => 'Basic 0123456789ABCDEF'})
+  
+  # Changing query strings
+  connection = Excon.new('http://geemus.com/')
+  connection.request(:method => 'GET', :query => {:foo => 'bar'})
+  
+  # POST body
+  Excon.post('http://geemus.com', :body => 'language=ruby&class=fog')
+  
+  # Symbols can also be used for HTTP methods
+  connection.request(:method => :get)
 
-You can also stream responses by passing a block that will receive each chunk.
+These options can be combined to make pretty much any request you might need.
+
+== Streaming Responses
+
+You can stream responses by passing a block that will receive each chunk.
 
   Excon.get('http://geemus.com') do |chunk, remaining_bytes, total_bytes|
     puts chunk
     puts "Remaining: #{remaining_bytes.to_f / total_bytes}%"
   end
-
-These options can be combined to make pretty much any request you might need.
+  
+Iterating over each chunk will allow you to do work on the response incrementally without buffering the entire response first. For very large responses this can lead to significant memory savings.
 
 == Proxy Support
 
@@ -43,29 +66,44 @@ You can specify a proxy URL that Excon will use with both HTTP and HTTPS connect
 
 The proxy URL must be fully specified, including scheme (e.g. "http://") and port.
 
-Excon will also use the environment variables "http_proxy" and "https_proxy" if they are present. "http_proxy" will be used for HTTPS connections if "https_proxy" is not set.
+Excon will also use the environment variables "http_proxy" and "https_proxy" if they are present. 
+
+If "https_proxy" is not set, the value of "http_proxy" will be used for both HTTP and HTTPS connections.
+
+NOTE: Environment variables will take precedence over a :proxy option that has been specified in code.
+
+== Stubs
+
+You can stub out requests for testing purposes by enabling mock mode on a connection.
+
+  Excon.mock = true
+
+Then you can add stubs, for instance:
+
+  # Excon.stub(request_attributes, response_attributes)
+  Excon.stub({:method => :get}, {:body => 'body', :status => 200})
 
-Environment variables will take precedence over a :proxy option that has been specified in code.
+Omitted attributes are assumed to match, so this stub will match any get request and return an Excon::Response with a body of 'body' and status of 200.  You can add whatever stubs you might like this way and they will be checked against in the order they were added, if none of them match then excon will raise an error to let you know.
 
 == HTTPS/SSL Issues
 
-By default excon will try to verify peer certificates when using ssl for https, unfortunately on some operating systems the defaults will not work. This will likely manifest itself as something like "Excon::Errors::SocketError: SSL_connect returned=1 ..."
+By default excon will try to verify peer certificates when using SSL for HTTPS. Unfortunately on some operating systems the defaults will not work. This will likely manifest itself as something like "Excon::Errors::SocketError: SSL_connect returned=1 ..."
 
-If you have the misfortune of running into this problem you have a couple options. First, if you have certificates in a location that defaults fail to locate you can set a different path to certificates:
+If you have the misfortune of running into this problem you have a couple options. If you have certificates but they aren't being auto-discovered, you can specify the path to your certificates:
 
   Excon.ssl_ca_path = '/path/to/certs'
 
-or failing that, you can turn off peer verification (less secure):
+Failing that, you can turn off peer verification (less secure):
 
   Excon.ssl_verify_peer = false
 
-Either of these should allow you to work around the socket error and continue with getting your work done.
+Either of these should allow you to work around the socket error and continue with your work.
 
 == Copyright
 
 (The MIT License)
 
-Copyright (c) 2010 {geemus (Wesley Beary)}[http://github.com/geemus]
+Copyright (c) 2010-2011 {geemus (Wesley Beary)}[http://github.com/geemus]
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

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.6.4'
-  s.date              = '2011-07-05'
+  s.version           = '0.6.5'
+  s.date              = '2011-07-13'
   s.rubyforge_project = 'excon'
 
   ## Make sure your summary is short. The description may be as long

data/lib/excon.rb

@@ -13,7 +13,7 @@ require 'excon/response'
 
 module Excon
   unless const_defined?(:VERSION)
-    VERSION = '0.6.4'
+    VERSION = '0.6.5'
   end
 
   unless const_defined?(:CHUNK_SIZE)

data/lib/excon/connection.rb

@@ -78,20 +78,23 @@ module Excon
             # all specified non-headers params match and no headers were specified or all specified headers match
             if (stub.keys - [:headers]).all? {|key| stub[key] == params[key] } &&
               (!stub.has_key?(:headers) || stub[:headers].keys.all? {|key| stub[:headers][key] == params[:headers][key]})
-              if block_given?
-                body = response.delete(:body)
+              response_attributes = case response
+              when Proc
+                response.call(params)
+              else
+                response
+              end
+              if block_given? && response_attributes.has_key?(:body)
+                body = response_attributes.delete(:body)
+                content_length = remaining = body.bytesize
                 i = 0
                 while i < body.length
-                  yield body[i, CHUNK_SIZE]
+                  yield(body[i, CHUNK_SIZE], [remaining - CHUNK_SIZE, 0].max, content_length)
+                  remaining -= CHUNK_SIZE
                   i += CHUNK_SIZE
                 end
               end
-              case response
-              when Proc
-                return Excon::Response.new(response.call(params))
-              else
-                return Excon::Response.new(response)
-              end
+              return Excon::Response.new(response_attributes)
             end
           end
           # if we reach here no stubs matched

data/tests/stub_tests.rb

@@ -33,6 +33,14 @@ Shindo.tests('Excon stubs') do
       response.status
     end
 
+    tests('request body with block given').returns('body') do
+      body = ''
+      connection.request(:method => :get, :path => '/content-length/100') do |chunk, remaining_bytes, total_bytes|
+        body << chunk
+      end
+      body
+    end
+
     Excon.stubs.pop
 
   end
@@ -56,6 +64,14 @@ Shindo.tests('Excon stubs') do
       response.status
     end
 
+    tests('request body with block given').returns('body') do
+      body = ''
+      connection.request(:body => 'body', :method => :get, :path => '/content-length/100') do |chunk, remaining_bytes, total_bytes|
+        body << chunk
+      end
+      body
+    end
+
     Excon.stubs.pop
 
   end
@@ -71,7 +87,7 @@ Shindo.tests('Excon stubs') do
 
     test("with block") do
       chunks = []
-      response = connection.request(:method => :get, :path => '/content-length/100') do |chunk|
+      response = 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

@@ -40,6 +40,14 @@ def basic_tests
     tests("response.body").returns('x' * 100) do
       response.body
     end
+
+    tests("block usage").returns(['x' * 100, 0, 100]) do
+      data = []
+      connection.request(:method => :get, :path => '/content-length/100') do |chunk, remaining_length, total_length|
+        data = [chunk, remaining_length, total_length]
+      end
+      data
+    end
   end
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: excon
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 13
   prerelease: 
   segments: 
   - 0
   - 6
-  - 4
-  version: 0.6.4
+  - 5
+  version: 0.6.5
 platform: ruby
 authors: 
 - geemus (Wesley Beary)
@@ -15,8 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-05 00:00:00 -05:00
-default_executable: 
+date: 2011-07-13 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: open4
@@ -124,7 +123,6 @@ files:
 - tests/stub_tests.rb
 - tests/test_helper.rb
 - tests/thread_safety_tests.rb
-has_rdoc: true
 homepage: https://github.com/geemus/excon
 licenses: []
 
@@ -154,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: excon
-rubygems_version: 1.4.1
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 2
 summary: speed, persistence, http(s)