faraday 0.7.4 → 1.0.1

data/lib/faraday.rb

@@ -1,88 +1,166 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'set'
+require 'forwardable'
+require 'faraday/middleware_registry'
+require 'faraday/dependency_loader'
+
+# This is the main namespace for Faraday.
+#
+# It provides methods to create {Connection} objects, and HTTP-related
+# methods to use directly.
+#
+# @example Helpful class methods for easy usage
+#   Faraday.get "http://faraday.com"
+#
+# @example Helpful class method `.new` to create {Connection} objects.
+#   conn = Faraday.new "http://faraday.com"
+#   conn.get '/'
+#
 module Faraday
-  VERSION = "0.7.4"
+  VERSION = '1.0.1'
+  METHODS_WITH_QUERY = %w[get head delete trace].freeze
+  METHODS_WITH_BODY = %w[post put patch].freeze
 
   class << self
-    attr_accessor :default_adapter
-    attr_writer   :default_connection
+    # The root path that Faraday is being loaded from.
+    #
+    # This is the root from where the libraries are auto-loaded.
+    #
+    # @return [String]
+    attr_accessor :root_path
 
-    def new(url = nil, options = {})
-      block = block_given? ? Proc.new : nil
-      Faraday::Connection.new(url, options, &block)
-    end
+    # Gets or sets the path that the Faraday libs are loaded from.
+    # @return [String]
+    attr_accessor :lib_path
 
-  private
-    def method_missing(name, *args, &block)
-      default_connection.send(name, *args, &block)
-    end
-  end
+    # @overload default_adapter
+    #   Gets the Symbol key identifying a default Adapter to use
+    #   for the default {Faraday::Connection}. Defaults to `:net_http`.
+    #   @return [Symbol] the default adapter
+    # @overload default_adapter=(adapter)
+    #   Updates default adapter while resetting {.default_connection}.
+    #   @return [Symbol] the new default_adapter.
+    attr_reader :default_adapter
 
-  self.default_adapter = :net_http
+    # Documented below, see default_connection
+    attr_writer :default_connection
 
-  def self.default_connection
-    @default_connection ||= Connection.new
-  end
+    # Tells Faraday to ignore the environment proxy (http_proxy).
+    # Defaults to `false`.
+    # @return [Boolean]
+    attr_accessor :ignore_env_proxy
 
-  module AutoloadHelper
-    def register_lookup_modules(mods)
-      (@lookup_module_index ||= {}).update(mods)
+    # Initializes a new {Connection}.
+    #
+    # @param url [String,Hash] The optional String base URL to use as a prefix
+    #           for all requests.  Can also be the options Hash. Any of these
+    #           values will be set on every request made, unless overridden
+    #           for a specific request.
+    # @param options [Hash]
+    # @option options [String] :url Base URL
+    # @option options [Hash] :params Hash of unencoded URI query params.
+    # @option options [Hash] :headers Hash of unencoded HTTP headers.
+    # @option options [Hash] :request Hash of request options.
+    # @option options [Hash] :ssl Hash of SSL options.
+    # @option options [Hash] :proxy Hash of Proxy options.
+    # @return [Faraday::Connection]
+    #
+    # @example With an URL argument
+    #   Faraday.new 'http://faraday.com'
+    #   # => Faraday::Connection to http://faraday.com
+    #
+    # @example With an URL argument and an options hash
+    #   Faraday.new 'http://faraday.com', params: { page: 1 }
+    #   # => Faraday::Connection to http://faraday.com?page=1
+    #
+    # @example With everything in an options hash
+    #   Faraday.new url: 'http://faraday.com',
+    #               params: { page: 1 }
+    #   # => Faraday::Connection to http://faraday.com?page=1
+    def new(url = nil, options = {}, &block)
+      options = default_connection_options.merge(options)
+      Faraday::Connection.new(url, options, &block)
     end
 
-    def lookup_module(key)
-      return if !@lookup_module_index
-      const_get @lookup_module_index[key] || key
+    # @private
+    # Internal: Requires internal Faraday libraries.
+    #
+    # @param libs [Array] one or more relative String names to Faraday classes.
+    # @return [void]
+    def require_libs(*libs)
+      libs.each do |lib|
+        require "#{lib_path}/#{lib}"
+      end
     end
 
-    def autoload_all(prefix, options)
-      options.each do |const_name, path|
-        autoload const_name, File.join(prefix, path)
-      end
+    alias require_lib require_libs
+
+    # Documented elsewhere, see default_adapter reader
+    def default_adapter=(adapter)
+      @default_connection = nil
+      @default_adapter = adapter
     end
 
-    # Loads each autoloaded constant.  If thread safety is a concern, wrap
-    # this in a Mutex.
-    def load_autoloaded_constants
-      constants.each do |const|
-        const_get(const) if autoload?(const)
-      end
+    def respond_to_missing?(symbol, include_private = false)
+      default_connection.respond_to?(symbol, include_private) || super
     end
 
-    def all_loaded_constants
-      constants.map { |c| const_get(c) }.
-        select { |a| a.respond_to?(:loaded?) && a.loaded? }
+    private
+
+    # Internal: Proxies method calls on the Faraday constant to
+    # .default_connection.
+    def method_missing(name, *args, &block)
+      if default_connection.respond_to?(name)
+        default_connection.send(name, *args, &block)
+      else
+        super
+      end
     end
   end
 
-  extend AutoloadHelper
+  self.ignore_env_proxy = false
+  self.root_path = File.expand_path __dir__
+  self.lib_path = File.expand_path 'faraday', __dir__
+  self.default_adapter = :net_http
 
-  autoload_all 'faraday',
-    :Middleware      => 'middleware',
-    :Builder         => 'builder',
-    :Request         => 'request',
-    :Response        => 'response',
-    :CompositeReadIO => 'upload_io',
-    :UploadIO        => 'upload_io',
-    :Parts           => 'upload_io'
-end
+  # @overload default_connection
+  #   Gets the default connection used for simple scripts.
+  #   @return [Faraday::Connection] a connection configured with
+  #   the default_adapter.
+  # @overload default_connection=(connection)
+  #   @param connection [Faraday::Connection]
+  #   Sets the default {Faraday::Connection} for simple scripts that
+  #   access the Faraday constant directly, such as
+  #   <code>Faraday.get "https://faraday.com"</code>.
+  def self.default_connection
+    @default_connection ||= Connection.new(default_connection_options)
+  end
 
-require 'faraday/utils'
-require 'faraday/connection'
-require 'faraday/adapter'
-require 'faraday/error'
+  # Gets the default connection options used when calling {Faraday#new}.
+  #
+  # @return [Faraday::ConnectionOptions]
+  def self.default_connection_options
+    @default_connection_options ||= ConnectionOptions.new
+  end
 
-# not pulling in active-support JUST for this method.
-class Object
-  # Yields <code>x</code> to the block, and then returns <code>x</code>.
-  # The primary purpose of this method is to "tap into" a method chain,
-  # in order to perform operations on intermediate results within the chain.
+  # Sets the default options used when calling {Faraday#new}.
   #
-  #   (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
-  #     tap    { |x| puts "array: #{x.inspect}" }.
-  #     select { |x| x%2 == 0 }.
-  #     tap    { |x| puts "evens: #{x.inspect}" }.
-  #     map    { |x| x*x }.
-  #     tap    { |x| puts "squares: #{x.inspect}" }
-  def tap
-    yield self
-    self
-  end unless Object.respond_to?(:tap)
+  # @param options [Hash, Faraday::ConnectionOptions]
+  def self.default_connection_options=(options)
+    @default_connection = nil
+    @default_connection_options = ConnectionOptions.from(options)
+  end
+
+  unless defined?(::Faraday::Timer)
+    require 'timeout'
+    Timer = Timeout
+  end
+
+  require_libs 'utils', 'options', 'connection', 'rack_builder', 'parameters',
+               'middleware', 'adapter', 'request', 'response', 'error',
+               'file_part', 'param_part'
+
+  require_lib 'autoload' unless ENV['FARADAY_NO_AUTOLOAD']
 end

data/spec/external_adapters/faraday_specs_setup.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'webmock/rspec'
+WebMock.disable_net_connect!(allow_localhost: true)
+
+require_relative '../support/helper_methods'
+require_relative '../support/disabling_stub'
+require_relative '../support/streaming_response_checker'
+require_relative '../support/shared_examples/adapter'
+require_relative '../support/shared_examples/request_method'
+
+RSpec.configure do |config|
+  config.include Faraday::HelperMethods
+end

data/spec/faraday/adapter/em_http_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::EMHttp, unless: defined?(JRUBY_VERSION) do
+  features :request_body_on_query_methods, :reason_phrase_parse, :trace_method,
+           :skip_response_body_on_head, :parallel, :local_socket_binding
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    url = URI('https://example.com:1234')
+    adapter = described_class.new nil, inactivity_timeout: 20
+    req = adapter.create_request(url: url, request: {})
+
+    expect(req.connopts.inactivity_timeout).to eq(20)
+  end
+
+  context 'Options' do
+    let(:request) { Faraday::RequestOptions.new }
+    let(:env) { { request: request } }
+    let(:options) { {} }
+    let(:adapter) { Faraday::Adapter::EMHttp.new }
+
+    it 'configures timeout' do
+      request.timeout = 5
+      adapter.configure_timeout(options, env)
+      expect(options[:inactivity_timeout]).to eq(5)
+      expect(options[:connect_timeout]).to eq(5)
+    end
+
+    it 'configures timeout and open_timeout' do
+      request.timeout = 5
+      request.open_timeout = 1
+      adapter.configure_timeout(options, env)
+      expect(options[:inactivity_timeout]).to eq(5)
+      expect(options[:connect_timeout]).to eq(1)
+    end
+
+    it 'configures all timeout settings' do
+      request.timeout = 5
+      request.read_timeout = 3
+      request.open_timeout = 1
+      adapter.configure_timeout(options, env)
+      expect(options[:inactivity_timeout]).to eq(3)
+      expect(options[:connect_timeout]).to eq(1)
+    end
+  end
+end

data/spec/faraday/adapter/em_synchrony_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::EMSynchrony, unless: defined?(JRUBY_VERSION) do
+  features :request_body_on_query_methods, :reason_phrase_parse,
+           :skip_response_body_on_head, :parallel, :local_socket_binding
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    url = URI('https://example.com:1234')
+    adapter = described_class.new nil, inactivity_timeout: 20
+    req = adapter.create_request(url: url, request: {})
+
+    expect(req.connopts.inactivity_timeout).to eq(20)
+  end
+end

data/spec/faraday/adapter/excon_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::Excon do
+  features :request_body_on_query_methods, :reason_phrase_parse, :trace_method
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    url = URI('https://example.com:1234')
+
+    adapter = described_class.new(nil, debug_request: true)
+
+    conn = adapter.build_connection(url: url)
+
+    expect(conn.data[:debug_request]).to be_truthy
+  end
+
+  context 'config' do
+    let(:adapter) { Faraday::Adapter::Excon.new }
+    let(:request) { Faraday::RequestOptions.new }
+    let(:uri) { URI.parse('https://example.com') }
+    let(:env) { { request: request, url: uri } }
+
+    it 'sets timeout' do
+      request.timeout = 5
+      options = adapter.send(:opts_from_env, env)
+      expect(options[:read_timeout]).to eq(5)
+      expect(options[:write_timeout]).to eq(5)
+      expect(options[:connect_timeout]).to eq(5)
+    end
+
+    it 'sets timeout and open_timeout' do
+      request.timeout = 5
+      request.open_timeout = 3
+      options = adapter.send(:opts_from_env, env)
+      expect(options[:read_timeout]).to eq(5)
+      expect(options[:write_timeout]).to eq(5)
+      expect(options[:connect_timeout]).to eq(3)
+    end
+
+    it 'sets open_timeout' do
+      request.open_timeout = 3
+      options = adapter.send(:opts_from_env, env)
+      expect(options[:read_timeout]).to eq(nil)
+      expect(options[:write_timeout]).to eq(nil)
+      expect(options[:connect_timeout]).to eq(3)
+    end
+  end
+end

data/spec/faraday/adapter/httpclient_spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::HTTPClient do
+  # ruby gem defaults for testing purposes
+  HTTPCLIENT_OPEN = 60
+  HTTPCLIENT_READ = 60
+  HTTPCLIENT_WRITE = 120
+
+  features :request_body_on_query_methods, :reason_phrase_parse, :compression,
+           :trace_method, :local_socket_binding
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    adapter = described_class.new do |client|
+      client.keep_alive_timeout = 20
+      client.ssl_config.timeout = 25
+    end
+
+    client = adapter.build_connection(url: URI.parse('https://example.com'))
+    expect(client.keep_alive_timeout).to eq(20)
+    expect(client.ssl_config.timeout).to eq(25)
+  end
+
+  context 'Options' do
+    let(:request) { Faraday::RequestOptions.new }
+    let(:env) { { request: request } }
+    let(:options) { {} }
+    let(:adapter) { Faraday::Adapter::HTTPClient.new }
+    let(:client) { adapter.connection(url: URI.parse('https://example.com')) }
+
+    it 'configures timeout' do
+      assert_default_timeouts!
+
+      request.timeout = 5
+      adapter.configure_timeouts(client, request)
+
+      expect(client.connect_timeout).to eq(5)
+      expect(client.send_timeout).to eq(5)
+      expect(client.receive_timeout).to eq(5)
+    end
+
+    it 'configures open timeout' do
+      assert_default_timeouts!
+
+      request.open_timeout = 1
+      adapter.configure_timeouts(client, request)
+
+      expect(client.connect_timeout).to eq(1)
+      expect(client.send_timeout).to eq(HTTPCLIENT_WRITE)
+      expect(client.receive_timeout).to eq(HTTPCLIENT_READ)
+    end
+
+    it 'configures multiple timeouts' do
+      assert_default_timeouts!
+
+      request.open_timeout = 1
+      request.write_timeout = 10
+      request.read_timeout = 5
+      adapter.configure_timeouts(client, request)
+
+      expect(client.connect_timeout).to eq(1)
+      expect(client.send_timeout).to eq(10)
+      expect(client.receive_timeout).to eq(5)
+    end
+
+    def assert_default_timeouts!
+      expect(client.connect_timeout).to eq(HTTPCLIENT_OPEN)
+      expect(client.send_timeout).to eq(HTTPCLIENT_WRITE)
+      expect(client.receive_timeout).to eq(HTTPCLIENT_READ)
+    end
+  end
+end

data/spec/faraday/adapter/net_http_persistent_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::NetHttpPersistent do
+  features :request_body_on_query_methods, :reason_phrase_parse, :compression, :trace_method
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    url = URI('https://example.com')
+
+    adapter = described_class.new do |http|
+      http.idle_timeout = 123
+    end
+
+    http = adapter.send(:connection, url: url, request: {})
+    adapter.send(:configure_request, http, {})
+
+    expect(http.idle_timeout).to eq(123)
+  end
+
+  it 'sets max_retries to 0' do
+    url = URI('http://example.com')
+
+    adapter = described_class.new
+
+    http = adapter.send(:connection, url: url, request: {})
+    adapter.send(:configure_request, http, {})
+
+    # `max_retries=` is only present in Ruby 2.5
+    expect(http.max_retries).to eq(0) if http.respond_to?(:max_retries=)
+  end
+
+  it 'allows to set pool_size on initialize' do
+    url = URI('https://example.com')
+
+    adapter = described_class.new(nil, pool_size: 5)
+
+    http = adapter.send(:connection, url: url, request: {})
+
+    # `pool` is only present in net_http_persistent >= 3.0
+    expect(http.pool.size).to eq(5) if http.respond_to?(:pool)
+  end
+
+  context 'min_version' do
+    it 'allows to set min_version in SSL settings' do
+      url = URI('https://example.com')
+
+      adapter = described_class.new(nil)
+
+      http = adapter.send(:connection, url: url, request: {})
+      adapter.send(:configure_ssl, http, min_version: :TLS1_2)
+
+      # `min_version` is only present in net_http_persistent >= 3.1 (UNRELEASED)
+      expect(http.min_version).to eq(:TLS1_2) if http.respond_to?(:min_version)
+    end
+  end
+end

data/spec/faraday/adapter/net_http_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::NetHttp do
+  features :request_body_on_query_methods, :reason_phrase_parse, :compression, :streaming, :trace_method
+
+  it_behaves_like 'an adapter'
+
+  context 'checking http' do
+    let(:url) { URI('http://example.com') }
+    let(:adapter) { described_class.new }
+    let(:http) { adapter.send(:connection, url: url, request: {}) }
+
+    it { expect(http.port).to eq(80) }
+
+    it 'sets max_retries to 0' do
+      adapter.send(:configure_request, http, {})
+
+      expect(http.max_retries).to eq(0) if http.respond_to?(:max_retries=)
+    end
+
+    it 'supports write_timeout' do
+      adapter.send(:configure_request, http, write_timeout: 10)
+
+      expect(http.write_timeout).to eq(10) if http.respond_to?(:write_timeout=)
+    end
+
+    it 'supports open_timeout' do
+      adapter.send(:configure_request, http, open_timeout: 10)
+
+      expect(http.open_timeout).to eq(10)
+    end
+
+    it 'supports read_timeout' do
+      adapter.send(:configure_request, http, read_timeout: 10)
+
+      expect(http.read_timeout).to eq(10)
+    end
+
+    context 'with https url' do
+      let(:url) { URI('https://example.com') }
+
+      it { expect(http.port).to eq(443) }
+    end
+
+    context 'with http url including port' do
+      let(:url) { URI('https://example.com:1234') }
+
+      it { expect(http.port).to eq(1234) }
+    end
+
+    context 'with custom adapter config' do
+      let(:adapter) do
+        described_class.new do |http|
+          http.continue_timeout = 123
+        end
+      end
+
+      it do
+        adapter.send(:configure_request, http, {})
+        expect(http.continue_timeout).to eq(123)
+      end
+    end
+  end
+end

data/spec/faraday/adapter/patron_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::Patron, unless: defined?(JRUBY_VERSION) do
+  features :reason_phrase_parse
+
+  it_behaves_like 'an adapter'
+
+  it 'allows to provide adapter specific configs' do
+    conn = Faraday.new do |f|
+      f.adapter :patron do |session|
+        session.max_redirects = 10
+        raise 'Configuration block called'
+      end
+    end
+
+    expect { conn.get('/') }.to raise_error(RuntimeError, 'Configuration block called')
+  end
+end

data/spec/faraday/adapter/rack_spec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::Rack do
+  features :request_body_on_query_methods, :trace_method,
+           :skip_response_body_on_head
+
+  it_behaves_like 'an adapter', adapter_options: WebmockRackApp.new
+end

data/spec/faraday/adapter/typhoeus_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter::Typhoeus do
+  features :request_body_on_query_methods, :parallel, :trace_method
+
+  it_behaves_like 'an adapter'
+end

data/spec/faraday/adapter_registry_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::AdapterRegistry do
+  describe '#initialize' do
+    subject(:registry) { described_class.new }
+
+    it { expect { registry.get(:FinFangFoom) }.to raise_error(NameError) }
+    it { expect { registry.get('FinFangFoom') }.to raise_error(NameError) }
+
+    it 'looks up class by string name' do
+      expect(registry.get('Faraday::Connection')).to eq(Faraday::Connection)
+    end
+
+    it 'looks up class by symbol name' do
+      expect(registry.get(:Faraday)).to eq(Faraday)
+    end
+
+    it 'caches lookups with implicit name' do
+      registry.set :symbol
+      expect(registry.get('symbol')).to eq(:symbol)
+    end
+
+    it 'caches lookups with explicit name' do
+      registry.set 'string', :name
+      expect(registry.get(:name)).to eq('string')
+    end
+  end
+end

data/spec/faraday/adapter_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+RSpec.describe Faraday::Adapter do
+  let(:adapter) { Faraday::Adapter.new }
+  let(:request) { {} }
+
+  context '#request_timeout' do
+    it 'gets :read timeout' do
+      expect(timeout(:read)).to eq(nil)
+
+      request[:timeout] = 5
+      request[:write_timeout] = 1
+
+      expect(timeout(:read)).to eq(5)
+
+      request[:read_timeout] = 2
+
+      expect(timeout(:read)).to eq(2)
+    end
+
+    it 'gets :open timeout' do
+      expect(timeout(:open)).to eq(nil)
+
+      request[:timeout] = 5
+      request[:write_timeout] = 1
+
+      expect(timeout(:open)).to eq(5)
+
+      request[:open_timeout] = 2
+
+      expect(timeout(:open)).to eq(2)
+    end
+
+    it 'gets :write timeout' do
+      expect(timeout(:write)).to eq(nil)
+
+      request[:timeout] = 5
+      request[:read_timeout] = 1
+
+      expect(timeout(:write)).to eq(5)
+
+      request[:write_timeout] = 2
+
+      expect(timeout(:write)).to eq(2)
+    end
+
+    it 'attempts unknown timeout type' do
+      expect { timeout(:unknown) }.to raise_error(ArgumentError)
+    end
+
+    def timeout(type)
+      adapter.send(:request_timeout, type, request)
+    end
+  end
+end