faraday 0.9.1 → 2.5.2

data/README.md

@@ -1,200 +1,31 @@
-# Faraday
+# [![Faraday](./docs/assets/img/repo-card-slim.png)][website]
 
-Faraday is an HTTP client lib that provides a common interface over many
-adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
-processing the request/response cycle.
+[![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
+[![GitHub Actions CI](https://github.com/lostisland/faraday/workflows/CI/badge.svg)](https://github.com/lostisland/faraday/actions?query=workflow%3ACI)
+[![GitHub Discussions](https://img.shields.io/github/discussions/lostisland/faraday?logo=github)](https://github.com/lostisland/faraday/discussions)
 
-Faraday supports these adapters:
 
-* Net::HTTP
-* [Excon][]
-* [Typhoeus][]
-* [Patron][]
-* [EventMachine][]
-* [HTTPClient][]
+Faraday is an HTTP client library abstraction layer that provides a common interface over many
+adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.
+You probably don't want to use Faraday directly in your project, as it will lack an actual client library to perform
+requests. Instead, you probably want to have a look at [Awesome Faraday][awesome] for a list of available adapters.
 
-It also includes a Rack adapter for hitting loaded Rack applications through
-Rack::Test, and a Test adapter for stubbing requests by hand.
+## Getting Started
 
-## Usage
-
-```ruby
-conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
-  faraday.request  :url_encoded             # form-encode POST params
-  faraday.response :logger                  # log requests to STDOUT
-  faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
-end
-
-## GET ##
-
-response = conn.get '/nigiri/sake.json'     # GET http://sushi.com/nigiri/sake.json
-response.body
-
-conn.get '/nigiri', { :name => 'Maguro' }   # GET http://sushi.com/nigiri?name=Maguro
-
-conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100
-  req.url '/search', :page => 2
-  req.params['limit'] = 100
-end
-
-## POST ##
-
-conn.post '/nigiri', { :name => 'Maguro' }  # POST "name=maguro" to http://sushi.com/nigiri
-
-# 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
-
-## Per-request options ##
-
-conn.get do |req|
-  req.url '/search'
-  req.options.timeout = 5           # open/read timeout in seconds
-  req.options.open_timeout = 2      # connection open timeout in seconds
-end
-```
-
-If you don't need to set up anything, you can roll with just the default middleware
-stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)):
-
-```ruby
-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 must be the adapter.
-
-```ruby
-Faraday.new(...) do |conn|
-  # POST/PUT params encoders:
-  conn.request :multipart
-  conn.request :url_encoded
-
-  conn.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
-
-Swapping middleware means giving the other priority. Specifying the
-"Content-Type" for the request is explicitly stating which middleware should
-process it.
-
-Examples:
-
-```ruby
-# uploading a file:
-payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
-
-# "Multipart" middleware detects files and encodes with "multipart/form-data":
-conn.put '/profile', payload
-```
-
-## Writing middleware
-
-Middleware are classes that implement a `call` instance method. They hook into
-the request/response cycle.
-
-```ruby
-def call(request_env)
-  # do something with the request
-  # request_env[:request_headers].merge!(...)
-
-  @app.call(request_env).on_complete do |response_env|
-    # do something with the response
-    # response_env[:response_headers].merge!(...)
-  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
-```
-
-## Using Faraday for 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') { |env| [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') { |env| [ 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') { |env| [ 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
-
-* support streaming requests/responses
-* better stubbing API
+The best starting point is the [Faraday Website][website], with its introduction and explanation.
+Need more details? See the [Faraday API Documentation][apidoc] to see how it works internally.
 
 ## Supported Ruby versions
 
-This library aims to support and is [tested against][travis] the following Ruby
-implementations:
-
-* MRI 1.8.7
-* MRI 1.9.2
-* MRI 1.9.3
-* MRI 2.0.0
-* MRI 2.1.0
-* [JRuby][]
-* [Rubinius][]
+This library aims to support and is [tested against][actions] the currently officially supported Ruby
+implementations. This means that, even without a major release, we could add or drop support for Ruby versions,
+following their [EOL](https://endoflife.date/ruby).
+Currently that means we support Ruby 2.6+
 
 If something doesn't work on one of these Ruby versions, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
-implementations, however support will only be provided for the versions listed
+implementations and versions, however support will only be provided for the versions listed
 above.
 
 If you would like this library to support another Ruby version, you may
@@ -204,17 +35,21 @@ implementation, you will be 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
+## Contribute
 
-Copyright (c) 2009-2013 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
-See [LICENSE][] for details.
+Do you want to contribute to Faraday?
+Open the issues page and check for the `help wanted` label!
+But before you start coding, please read our [Contributing Guide][contributing]
 
-[travis]:    http://travis-ci.org/lostisland/faraday
-[excon]:     https://github.com/geemus/excon#readme
-[typhoeus]:  https://github.com/typhoeus/typhoeus#readme
-[patron]:    http://toland.github.com/patron/
-[eventmachine]: https://github.com/igrigorik/em-http-request#readme
-[httpclient]: https://github.com/nahi/httpclient
-[jruby]:     http://jruby.org/
-[rubinius]:  http://rubini.us/
-[license]:   LICENSE.md
+## Copyright
+© 2009 - 2022, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
+
+[awesome]:      https://github.com/lostisland/awesome-faraday/#adapters
+[website]:      https://lostisland.github.io/faraday
+[faraday_team]: https://lostisland.github.io/faraday/team
+[contributing]: https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md
+[apidoc]:       https://www.rubydoc.info/github/lostisland/faraday
+[actions]:      https://github.com/lostisland/faraday/actions
+[jruby]:        http://jruby.org/
+[rubinius]:     http://rubini.us/
+[license]:      LICENSE.md

data/Rakefile

@@ -1,71 +1,7 @@
-require 'date'
-require 'fileutils'
-require 'openssl'
-require 'rake/testtask'
-require 'bundler'
-Bundler::GemHelper.install_tasks
+# frozen_string_literal: true
 
-task :default => :test
+require 'rspec/core/rake_task'
 
-## helper functions
+RSpec::Core::RakeTask.new(:spec)
 
-def name
-  @name ||= Dir['*.gemspec'].first.split('.').first
-end
-
-def version
-  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
-  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
-end
-
-def gemspec_file
-  "#{name}.gemspec"
-end
-
-def gem_file
-  "#{name}-#{version}.gem"
-end
-
-def replace_header(head, header_name)
-  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
-end
-
-# Adapted from WEBrick::Utils. Skips cert extensions so it
-# can be used as a CA bundle
-def create_self_signed_cert(bits, cn, comment)
-  rsa = OpenSSL::PKey::RSA.new(bits)
-  cert = OpenSSL::X509::Certificate.new
-  cert.version = 2
-  cert.serial = 1
-  name = OpenSSL::X509::Name.new(cn)
-  cert.subject = name
-  cert.issuer = name
-  cert.not_before = Time.now
-  cert.not_after = Time.now + (365*24*60*60)
-  cert.public_key = rsa.public_key
-  cert.sign(rsa, OpenSSL::Digest::SHA1.new)
-  return [cert, rsa]
-end
-
-## standard tasks
-
-desc "Run all tests"
-task :test do
-  exec 'script/test'
-end
-
-desc "Generate certificates for SSL tests"
-task :'test:generate_certs' do
-  cert, key = create_self_signed_cert(1024, [['CN', 'localhost']], 'Faraday Test CA')
-  FileUtils.mkdir_p 'tmp'
-  File.open('tmp/faraday-cert.key', 'w') {|f| f.puts(key) }
-  File.open('tmp/faraday-cert.crt', 'w') {|f| f.puts(cert.to_s) }
-end
-
-file 'tmp/faraday-cert.key' => :'test:generate_certs'
-file 'tmp/faraday-cert.crt' => :'test:generate_certs'
-
-desc "Open an irb session preloaded with this library"
-task :console do
-  sh "irb -rubygems -r ./lib/#{name}.rb"
-end
+task default: :spec

data/examples/client_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Requires Ruby with rspec and faraday gems.
+# rspec client_spec.rb
+
+require 'faraday'
+require 'json'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def httpbingo(jname, params: {})
+    res = @conn.get("/#{jname}", params)
+    data = JSON.parse(res.body)
+    data['origin']
+  end
+
+  def foo(params)
+    res = @conn.post('/foo', JSON.dump(params))
+    res.status
+  end
+end
+
+RSpec.describe Client do
+  let(:stubs)  { Faraday::Adapter::Test::Stubs.new }
+  let(:conn)   { Faraday.new { |b| b.adapter(:test, stubs) } }
+  let(:client) { Client.new(conn) }
+
+  it 'parses origin' do
+    stubs.get('/ip') do |env|
+      # optional: you can inspect the Faraday::Env
+      expect(env.url.path).to eq('/ip')
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"origin": "127.0.0.1"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    expect(client.httpbingo('ip')).to eq('127.0.0.1')
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles 404' do
+    stubs.get('/api') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+    expect(client.httpbingo('api')).to be_nil
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles exception' do
+    stubs.get('/api') do
+      raise Faraday::ConnectionFailed
+    end
+
+    expect { client.httpbingo('api') }.to raise_error(Faraday::ConnectionFailed)
+    stubs.verify_stubbed_calls
+  end
+
+  context 'When the test stub is run in strict_mode' do
+    let(:stubs) { Faraday::Adapter::Test::Stubs.new(strict_mode: true) }
+
+    it 'verifies the all parameter values are identical' do
+      stubs.get('/api?abc=123') do
+        [
+          200,
+          { 'Content-Type': 'application/javascript' },
+          '{"origin": "127.0.0.1"}'
+        ]
+      end
+
+      # uncomment to raise Stubs::NotFound
+      # expect(client.httpbingo('api', params: { abc: 123, foo: 'Kappa' })).to eq('127.0.0.1')
+      expect(client.httpbingo('api', params: { abc: 123 })).to eq('127.0.0.1')
+      stubs.verify_stubbed_calls
+    end
+  end
+
+  context 'When the Faraday connection is configured with FlatParamsEncoder' do
+    let(:conn) { Faraday.new(request: { params_encoder: Faraday::FlatParamsEncoder }) { |b| b.adapter(:test, stubs) } }
+
+    it 'handles the same multiple URL parameters' do
+      stubs.get('/api?a=x&a=y&a=z') { [200, { 'Content-Type' => 'application/json' }, '{"origin": "127.0.0.1"}'] }
+
+      # uncomment to raise Stubs::NotFound
+      # expect(client.httpbingo('api', params: { a: %w[x y] })).to eq('127.0.0.1')
+      expect(client.httpbingo('api', params: { a: %w[x y z] })).to eq('127.0.0.1')
+      stubs.verify_stubbed_calls
+    end
+  end
+
+  context 'When you want to test the body, you can use a proc as well as string' do
+    it 'tests with a string' do
+      stubs.post('/foo', '{"name":"YK"}') { [200, {}, ''] }
+
+      expect(client.foo(name: 'YK')).to eq 200
+      stubs.verify_stubbed_calls
+    end
+
+    it 'tests with a proc' do
+      check = ->(request_body) { JSON.parse(request_body).slice('name') == { 'name' => 'YK' } }
+      stubs.post('/foo', check) { [200, {}, ''] }
+
+      expect(client.foo(name: 'YK', created_at: Time.now)).to eq 200
+      stubs.verify_stubbed_calls
+    end
+  end
+end

data/examples/client_test.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Requires Ruby with test-unit and faraday gems.
+# ruby client_test.rb
+
+require 'faraday'
+require 'json'
+require 'test/unit'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def httpbingo(jname, params: {})
+    res = @conn.get("/#{jname}", params)
+    data = JSON.parse(res.body)
+    data['origin']
+  end
+
+  def foo(params)
+    res = @conn.post('/foo', JSON.dump(params))
+    res.status
+  end
+end
+
+# Example API client test
+class ClientTest < Test::Unit::TestCase
+  def test_httpbingo_name
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/api') do |env|
+      # optional: you can inspect the Faraday::Env
+      assert_equal '/api', env.url.path
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"origin": "127.0.0.1"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    cli = client(stubs)
+    assert_equal '127.0.0.1', cli.httpbingo('api')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_httpbingo_not_found
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/api') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+
+    cli = client(stubs)
+    assert_nil cli.httpbingo('api')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_httpbingo_exception
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/api') do
+      raise Faraday::ConnectionFailed
+    end
+
+    cli = client(stubs)
+    assert_raise Faraday::ConnectionFailed do
+      cli.httpbingo('api')
+    end
+    stubs.verify_stubbed_calls
+  end
+
+  def test_strict_mode
+    stubs = Faraday::Adapter::Test::Stubs.new(strict_mode: true)
+    stubs.get('/api?abc=123') do
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"origin": "127.0.0.1"}'
+      ]
+    end
+
+    cli = client(stubs)
+    assert_equal '127.0.0.1', cli.httpbingo('api', params: { abc: 123 })
+
+    # uncomment to raise Stubs::NotFound
+    # assert_equal '127.0.0.1', cli.httpbingo('api', params: { abc: 123, foo: 'Kappa' })
+    stubs.verify_stubbed_calls
+  end
+
+  def test_non_default_params_encoder
+    stubs = Faraday::Adapter::Test::Stubs.new(strict_mode: true)
+    stubs.get('/api?a=x&a=y&a=z') do
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"origin": "127.0.0.1"}'
+      ]
+    end
+    conn = Faraday.new(request: { params_encoder: Faraday::FlatParamsEncoder }) do |builder|
+      builder.adapter :test, stubs
+    end
+
+    cli = Client.new(conn)
+    assert_equal '127.0.0.1', cli.httpbingo('api', params: { a: %w[x y z] })
+
+    # uncomment to raise Stubs::NotFound
+    # assert_equal '127.0.0.1', cli.httpbingo('api', params: { a: %w[x y] })
+    stubs.verify_stubbed_calls
+  end
+
+  def test_with_string_body
+    stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+      stub.post('/foo', '{"name":"YK"}') { [200, {}, ''] }
+    end
+    cli = client(stubs)
+    assert_equal 200, cli.foo(name: 'YK')
+
+    stubs.verify_stubbed_calls
+  end
+
+  def test_with_proc_body
+    stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+      check = ->(request_body) { JSON.parse(request_body).slice('name') == { 'name' => 'YK' } }
+      stub.post('/foo', check) { [200, {}, ''] }
+    end
+    cli = client(stubs)
+    assert_equal 200, cli.foo(name: 'YK', created_at: Time.now)
+
+    stubs.verify_stubbed_calls
+  end
+
+  def client(stubs)
+    conn = Faraday.new do |builder|
+      builder.adapter :test, stubs
+    end
+    Client.new(conn)
+  end
+end