faraday 0.7.6 → 0.8.0.rc2

data/Gemfile

@@ -1,4 +1,4 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 group :development do
   gem 'sinatra', '~> 1.2'
@@ -14,9 +14,6 @@ end
 platforms :ruby do
   gem 'patron', '~> 0.4'
   gem 'typhoeus', '~> 0.3'
-  # ActiveSupport::JSON will be used in ruby 1.8 and Yajl in 1.9; this is to test against both adapters
-  gem 'activesupport', '~> 2.3', :require => nil, :platforms => [:ruby_18, :jruby]
-  gem 'yajl-ruby', '~> 1.0', :require => 'yajl', :platforms => :ruby_19
 end
 
 platforms :jruby do

data/README.md

@@ -1,177 +1,195 @@
-faraday
-=======
-Modular HTTP client library using middleware heavily inspired by Rack.
+# faraday [![Build Status](https://secure.travis-ci.org/technoweenie/faraday.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/technoweenie/faraday.png?travis)][gemnasium]
+Modular HTTP client library that uses middleware. Heavily inspired by Rack.
 
-This mess is gonna get raw, like sushi. So, haters to the left.
+[travis]: http://travis-ci.org/technoweenie/faraday
+[gemnasium]: https://gemnasium.com/technoweenie/faraday
 
-Usage
------
-    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
-      builder.use Faraday::Response::Logger     # log the request to STDOUT
-      builder.use Faraday::Adapter::NetHttp     # make http requests with Net::HTTP
+## <a name="usage"></a>Usage
 
-      # or, use shortcuts:
-      builder.request  :url_encoded
-      builder.request  :json
-      builder.response :logger
-      builder.adapter  :net_http
-    end
+```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::Response::Logger     # log the request to STDOUT
+  builder.use Faraday::Adapter::NetHttp     # make http requests with Net::HTTP
 
-    ## GET ##
+  # or, use shortcuts:
+  builder.request  :url_encoded
+  builder.response :logger
+  builder.adapter  :net_http
+end
 
-    response = conn.get '/nigiri/sake.json'     # GET http://sushi.com/nigiri/sake.json
-    response.body
+## GET ##
 
-    conn.get '/nigiri', 'X-Awesome' => true     # custom request header
+response = conn.get '/nigiri/sake.json'     # GET http://sushi.com/nigiri/sake.json
+response.body
 
-    conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100
-      req.url '/search', :page => 2
-      req.params['limit'] = 100
-    end
+conn.get '/nigiri', 'X-Awesome' => true     # custom request header
 
-    ## POST ##
+conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100
+  req.url '/search', :page => 2
+  req.params['limit'] = 100
+end
 
-    conn.post '/nigiri', { :name => 'Maguro' }  # POST "name=maguro" to http://sushi.com/nigiri
+## POST ##
 
-    # post payload as JSON instead of "www-form-urlencoded" encoding:
-    conn.post '/nigiri', payload, 'Content-Type' => 'application/json'
+conn.post '/nigiri', { :name => 'Maguro' }  # POST "name=maguro" to http://sushi.com/nigiri
 
-    # a more verbose way:
-    conn.post do |req|
-      req.url '/nigiri'
-      req.headers['Content-Type'] = 'application/json'
-      req.body = { :name => 'Unagi' }
-    end
+# post payload as JSON instead of "www-form-urlencoded" encoding:
+conn.post do |req|
+  req.url '/nigiri'
+  req.headers['Content-Type'] = 'application/json'
+  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:
 
-    # default stack (net/http), no extra middleware:
-    response = Faraday.get 'http://sushi.com/nigiri/sake.json'
+```ruby
+# default stack (net/http), no extra middleware:
+response = Faraday.get 'http://sushi.com/nigiri/sake.json'
+```
 
-Advanced middleware usage
--------------------------
+## 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.
 
-    conn = Faraday.new(:url => 'http://sushi.com') do |builder|
-      # POST/PUT params encoders:
-      builder.request  :multipart
-      builder.request  :url_encoded
-      builder.request  :json
+```ruby
+conn = Faraday.new(:url => 'http://sushi.com') do |builder|
+  # POST/PUT params encoders:
+  builder.request  :multipart
+  builder.request  :url_encoded
 
-      builder.adapter  :net_http
-    end
+  builder.adapter  :net_http
+end
+```
 
 This request middleware setup affects POST/PUT requests in the following way:
 
 1. `Request::Multipart` checks for files in the payload, otherwise leaves everything untouched;
 2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not already encoded or of another type
-2. `Request::JSON` encodes as "application/json" if not already encoded or of another type
 
-Because "UrlEncoded" is higher on the stack than JSON encoder, it will get to process the request first. Swapping them means giving the other priority. Specifying the "Content-Type" for the request is explicitly stating which middleware should process it.
+Swapping middleware means giving the other priority. Specifying the "Content-Type" for the request is explicitly stating which middleware should process it.
 
 Examples:
 
-    payload = { :name => 'Maguro' }
+```ruby
+payload = { :name => 'Maguro' }
 
-    # post payload as JSON instead of urlencoded:
-    conn.post '/nigiri', payload, 'Content-Type' => 'application/json'
+# uploading a file:
+payload = { :profile_pic => Faraday::UploadIO.new('avatar.jpg', 'image/jpeg') }
 
-    # uploading a file:
-    payload = { :profile_pic => Faraday::UploadIO.new('avatar.jpg', 'image/jpeg') }
+# "Multipart" middleware detects files and encodes with "multipart/form-data":
+conn.put '/profile', payload
+```
 
-    # "Multipart" middleware detects files and encodes with "multipart/form-data":
-    conn.put '/profile', payload
-
-Writing middleware
-------------------
+## Writing middleware
 Middleware are classes that respond to `call()`. They wrap the request/response cycle.
 
-    def call(env)
-      # do something with the request
+```ruby
+def call(env)
+  # do something with the request
 
-      @app.call(env).on_complete do
-        # do something with the response
-      end
-    end
+  @app.call(env).on_complete do
+    # 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
-    :body   - POST parameters for :post/:put requests
-    :request_headers
-
-    # response phase
-    :status - HTTP response status code, such as 200
-    :body   - the response body
-    :response_headers
-
-Testing
--------
-    # 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'] }
-    end
-
-    # You can pass stubbed request to the test adapter or define them in a block
-    # or a combination of the two.
-    test = Faraday.new do |builder|
-      builder.adapter :test, stubs do |stub|
-        stub.get('/ebi') {[ 200, {}, 'shrimp' ]}
-      end
-    end
-
-    # It's also possible to stub additional requests after the connection has
-    # been initialized. This is useful for testing.
-    stubs.get('/uni') {[ 200, {}, 'urchin' ]}
-
-    resp = test.get '/tamago'
-    resp.body # => 'egg'
-    resp = test.get '/ebi'
-    resp.body # => 'shrimp'
-    resp = test.get '/uni'
-    resp.body # => 'urchin'
-    resp = test.get '/else' #=> raises "no such stub" error
-
-    # If you like, you can treat your stubs as mocks by verifying that all of
-    # the stubbed calls were made. NOTE that this feature is still fairly
-    # 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
-
-TODO
-----
+```
+# request phase
+:method - :get, :post, ...
+:url    - URI for the current request; also contains GET parameters
+:body   - POST parameters for :post/:put requests
+:request_headers
+
+# response phase
+: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'] }
+end
+
+# You can pass stubbed request to the test adapter or define them in a block
+# or a combination of the two.
+test = Faraday.new do |builder|
+  builder.adapter :test, stubs do |stub|
+    stub.get('/ebi') {[ 200, {}, 'shrimp' ]}
+  end
+end
+
+# It's also possible to stub additional requests after the connection has
+# been initialized. This is useful for testing.
+stubs.get('/uni') {[ 200, {}, 'urchin' ]}
+
+resp = test.get '/tamago'
+resp.body # => 'egg'
+resp = test.get '/ebi'
+resp.body # => 'shrimp'
+resp = test.get '/uni'
+resp.body # => 'urchin'
+resp = test.get '/else' #=> raises "no such stub" error
+
+# If you like, you can treat your stubs as mocks by verifying that all of
+# the stubbed calls were made. NOTE that this feature is still fairly
+# 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
 
-Note on Patches/Pull Requests
------------------------------
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-Supported Rubies
-----------------
-This library aims to support and is [tested
-against](http://travis-ci.org/technoweenie/faraday) the following Ruby
+## <a name="pulls"></a>Note on Patches/Pull Requests
+1. Fork the project.
+2. Make your feature addition or bug fix.
+3. Add tests for it. This is important so I don't break it in a future version
+   unintentionally.
+4. Commit, do not mess with rakefile, version, or history. (if you want to have
+   your own version, that is fine but bump version in a commit by itself I can
+   ignore when I pull)
+5. Send me a pull request. Bonus points for topic branches.
+
+## <a name="versions"></a>Supported Ruby Versions
+This library aims to support and is [tested against][travis] the following Ruby
 implementations:
 
 * Ruby 1.8.7
-* Ruby 1.9.1
 * Ruby 1.9.2
-* [Rubinius](http://rubini.us)
-* [Ruby Enterprise Edition](http://www.rubyenterpriseedition.com/)
+* Ruby 1.9.3
+* JRuby[]
+* [Rubinius][]
+* [Ruby Enterprise Edition][ree]
+
+[jruby]: http://jruby.org/
+[rubinius]: http://rubini.us/
+[ree]: http://www.rubyenterpriseedition.com/
 
 If something doesn't work on one of these interpreters, it should be considered
 a bug.
@@ -187,8 +205,7 @@ implementation, you will be personally responsible for providing patches in a
 timely fashion. If critical issues for a particular implementation exist at the
 time of a major release, support for that Ruby version may be dropped.
 
-Copyright
----------
-Copyright (c) 2009-2011 rick, hobson. See [LICENSE][license] for details.
+## <a name="copyright"></a>Copyright
+Copyright (c) 2009 rick olson, zack hobson. See [LICENSE][] for details.
 
 [license]: https://github.com/technoweenie/faraday/blob/master/LICENSE.md

data/Rakefile

@@ -1,12 +1,9 @@
-#!/usr/bin/env rake
-
 require 'date'
+require 'rake/testtask'
 
-#############################################################################
-#
-# Helper functions
-#
-#############################################################################
+task :default => :test
+
+## helper functions
 
 def name
   @name ||= Dir['*.gemspec'].first.split('.').first
@@ -17,14 +14,6 @@ def version
   line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
 end
 
-def date
-  Date.today.to_s
-end
-
-def rubyforge_project
-  name
-end
-
 def gemspec_file
   "#{name}.gemspec"
 end
@@ -37,26 +26,17 @@ def replace_header(head, header_name)
   head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
 end
 
-#############################################################################
-#
-# Standard tasks
-#
-#############################################################################
+## standard tasks
 
-task :default => :test
-
-require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/*_test.rb'
   test.verbose = true
 end
 
-TEST_SERVER = 'http://faradaylive.heroku.com'
-
-desc "Run tests including live tests against #{TEST_SERVER}"
-task :"test:live" do
-  ENV['LIVE'] = TEST_SERVER
+desc "Run tests including live tests against a local server on port 4567"
+task :"test:local" do
+  ENV['LIVE'] = '1'
   Rake::Task[:test].invoke
 end
 
@@ -65,25 +45,13 @@ task :console do
   sh "irb -rubygems -r ./lib/#{name}.rb"
 end
 
-#############################################################################
-#
-# Custom tasks (add your own tasks here)
-#
-#############################################################################
-
+## release management tasks
 
-
-#############################################################################
-#
-# Packaging tasks
-#
-#############################################################################
-
-desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+desc "Commit, create tag v#{version} and build and push #{gem_file} to Rubygems"
 task :release => :build do
   sh "git commit --allow-empty -a -m 'Release #{version}'"
   sh "git tag v#{version}"
-  sh "git push origin master"
+  sh "git push"
   sh "git push origin v#{version}"
   sh "gem push pkg/#{gem_file}"
 end
@@ -96,7 +64,7 @@ task :build => :gemspec do
 end
 
 desc "Generate #{gemspec_file}"
-task :gemspec => :validate do
+task :gemspec do
   # read spec file and split out manifest section
   spec = File.read(gemspec_file)
   head, manifest, tail = spec.split("  # = MANIFEST =\n")
@@ -104,9 +72,6 @@ task :gemspec => :validate do
   # replace name version and date
   replace_header(head, :name)
   replace_header(head, :version)
-  replace_header(head, :date)
-  #comment this out if your rubyforge_project has a different name
-  replace_header(head, :rubyforge_project)
 
   # determine file list from git ls-files
   files = `git ls-files`.
@@ -123,16 +88,3 @@ task :gemspec => :validate do
   File.open(gemspec_file, 'w') { |io| io.write(spec) }
   puts "Updated #{gemspec_file}"
 end
-
-desc "Validate #{gemspec_file}"
-task :validate do
-  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
-  unless libfiles.empty?
-    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
-    exit!
-  end
-  unless Dir['VERSION*'].empty?
-    puts "A `VERSION` file at root level violates Gem best practices."
-    exit!
-  end
-end