merge readme changes

README.md

@@ -5,6 +5,8 @@ Modular HTTP client library that uses middleware. Heavily inspired by Rack.
 [gemnasium]: https://gemnasium.com/technoweenie/faraday
 
 ## <a name="usage"></a>Usage
+
+```ruby
 conn = Faraday.new(:url => 'http://sushi.com') do |builder|
   builder.use Faraday::Request::UrlEncoded  # convert request params as "www-form-urlencoded"
   builder.use Faraday::Request::JSON        # encode request params as json
@@ -44,14 +46,33 @@ Modular HTTP client library that uses middleware. Heavily inspired by Rack.
   req.body = { :name => 'Unagi' }
 end
 
+## Options ##
+
+conn.get do |req|
+  req.url '/search'
+  req.options = {
+    :timeout => 5,                    # open/read timeout Integer in seconds
+    :open_timeout => 2,               # read timeout Integer in seconds
+    :proxy => {
+      :uri => "http://example.org/",  # proxy server URI
+      :user => "me",                  # proxy server username
+      :password => "test123"          # proxy server password
+    }
+  }
+end
+```
+
 If you're ready to roll with just the bare minimum:
 
+```ruby
 # default stack (net/http), no extra middleware:
 response = Faraday.get 'http://sushi.com/nigiri/sake.json'
+```
 
 ## Advanced middleware usage
 The order in which middleware is stacked is important. Like with Rack, the first middleware on the list wraps all others, while the last middleware is the innermost one, so that's usually the adapter.
 
+```ruby
 conn = Faraday.new(:url => 'http://sushi.com') do |builder|
   # POST/PUT params encoders:
   builder.request  :multipart
@@ -60,6 +81,7 @@ The order in which middleware is stacked is important. Like with Rack, the first
 
   builder.adapter  :net_http
 end
+```
 
 This request middleware setup affects POST/PUT requests in the following way:
 
@@ -71,6 +93,7 @@ Because "UrlEncoded" is higher on the stack than JSON encoder, it will get to pr
 
 Examples:
 
+```ruby
 payload = { :name => 'Maguro' }
 
 # post payload as JSON instead of urlencoded:
@@ -81,10 +104,12 @@ Examples:
 
 # "Multipart" middleware detects files and encodes with "multipart/form-data":
 conn.put '/profile', payload
+```
 
 ## Writing middleware
 Middleware are classes that respond to `call()`. They wrap the request/response cycle.
 
+```ruby
 def call(env)
   # do something with the request
 
@@ -92,11 +117,13 @@ Middleware are classes that respond to `call()`. They wrap the request/response
     # do something with the response
   end
 end
+```
 
 It's important to do all processing of the response only in the `on_complete` block. This enables middleware to work in parallel mode where requests are asynchronous.
 
 The `env` is a hash with symbol keys that contains info about the request and, later, response. Some keys are:
 
+```
 # request phase
 :method - :get, :post, ...
 :url    - URI for the current request; also contains GET parameters
@@ -107,8 +134,11 @@ The `env` is a hash with symbol keys that contains info about the request and, l
 :status - HTTP response status code, such as 200
 :body   - the response body
 :response_headers
+```
 
 ## <a name="testing"></a>Testing
+
+```ruby
 # It's possible to define stubbed request outside a test adapter block.
 stubs = Faraday::Adapter::Test::Stubs.new do |stub|
   stub.get('/tamago') { [200, {}, 'egg'] }
@@ -139,11 +169,11 @@ The `env` is a hash with symbol keys that contains info about the request and, l
 # experimental: It will not verify the order or count of any stub, only that
 # it was called once during the course of the test.
 stubs.verify_stubbed_calls
+```
 
 ## <a name="todo"></a>TODO
 * support streaming requests/responses
 * better stubbing API
-* Support timeouts
 * Add curb, em-http, fast_http
 
 ## <a name="pulls"></a>Note on Patches/Pull Requests

lib/faraday/request.rb

@@ -15,12 +15,16 @@ module Faraday
     autoload_all 'faraday/request',
       :JSON       => 'json',
       :UrlEncoded => 'url_encoded',
-      :Multipart  => 'multipart'
+      :Multipart  => 'multipart',
+      :Retry      => 'retry',
+      :Timeout    => 'timeout'
 
     register_lookup_modules \
       :json        => :JSON,
       :url_encoded => :UrlEncoded,
-      :multipart   => :Multipart
+      :multipart   => :Multipart,
+      :retry       => :Retry,
+      :timeout     => :Timeout
 
     attr_reader :method
 

lib/faraday/request/retry.rb

@@ -0,0 +1,21 @@
+module Faraday
+  class Request::Retry < Faraday::Middleware
+    def initialize(app, retries = 2)
+      @retries = retries
+      super(app)
+    end
+
+    def call(env)
+      retries = @retries
+      begin
+        @app.call(env)
+      rescue StandardError, Timeout::Error => e
+        if retries > 0
+          retries -= 1
+          retry
+        end
+        raise
+      end
+    end
+  end
+end

lib/faraday/request/timeout.rb

@@ -0,0 +1,31 @@
+module Faraday
+  class Request::Timeout < Faraday::Middleware
+    dependency "timeout"
+
+    def initialize(app, timeout = 2)
+      self.class.dependency "system_timer" if ruby18?
+      @timeout = timeout
+      super(app)
+    end
+
+    def call(env)
+      method =
+      if ruby18? && self.class.loaded?
+        SystemTimer.method(:timeout_after)
+      else
+        Timeout.method(:timeout)
+      end
+
+      method.call(@timeout) do
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def ruby18?
+      @ruby18 ||= RUBY_VERSION =~ /^1\.8/
+    end
+
+  end
+end

test/middleware/retry_test.rb

@@ -0,0 +1,25 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "helper"))
+
+module Middleware
+  class RetryTest < Faraday::TestCase
+    def setup
+      @stubs = Faraday::Adapter::Test::Stubs.new
+      @conn = Faraday.new do |b|
+        b.request :retry, 2
+        b.adapter :test, @stubs
+      end
+    end
+
+    def test_retries
+      times_called = 0
+
+      @stubs.post("/echo") do
+        times_called += 1
+        raise "Error occurred"
+      end
+
+      @conn.post("/echo") rescue nil
+      assert_equal times_called, 3
+    end
+  end
+end

test/middleware/timeout_test.rb

@@ -0,0 +1,20 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "helper"))
+
+module Middleware
+  class TimeoutTest < Faraday::TestCase
+    def setup
+      @conn = Faraday.new do |b|
+        b.request :timeout, 0.01 # 10 ms
+        b.adapter :test do |stub|
+          stub.post("/echo") do |env|
+            sleep(1)
+          end
+        end
+      end
+    end
+
+    def test_request_times_out
+      assert_raise(TimeoutError) { @conn.post("/echo") }
+    end
+  end
+end