faraday 0.17.4 → 1.8.0

data/lib/faraday.rb

@@ -1,247 +1,185 @@
-require 'thread'
+# frozen_string_literal: true
+
 require 'cgi'
+require 'date'
 require 'set'
 require 'forwardable'
+require 'faraday/middleware_registry'
+require 'faraday/dependency_loader'
+
+unless defined?(::Faraday::Timer)
+  require 'timeout'
+  ::Faraday::Timer = Timeout
+end
 
-# Public: This is the main namespace for Faraday.  You can either use it to
-# create Faraday::Connection objects, or access it directly.
+require 'faraday/version'
+require 'faraday/methods'
+require 'faraday/utils'
+require 'faraday/options'
+require 'faraday/connection'
+require 'faraday/rack_builder'
+require 'faraday/parameters'
+require 'faraday/middleware'
+require 'faraday/adapter'
+require 'faraday/request'
+require 'faraday/response'
+require 'faraday/error'
+require 'faraday/file_part'
+require 'faraday/param_part'
+
+unless defined?(JRUBY_VERSION)
+  require 'faraday/em_http'
+  require 'faraday/em_synchrony'
+end
+require 'faraday/excon'
+require 'faraday/httpclient'
+require 'faraday/net_http'
+require 'faraday/net_http_persistent'
+require 'faraday/patron'
+require 'faraday/rack'
+
+# This is the main namespace for Faraday.
 #
-# Examples
+# 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.17.4"
-
   class << self
-    # Public: Gets or sets the root path that Faraday is being loaded from.
-    # This is the root from where the libraries are auto-loaded from.
+    # 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
 
-    # Public: Gets or sets the path that the Faraday libs are loaded from.
+    # Gets or sets the path that the Faraday libs are loaded from.
+    # @return [String]
     attr_accessor :lib_path
 
-    # Public: Gets or sets the Symbol key identifying a default Adapter to use
-    # for the default Faraday::Connection.
+    # @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
 
-    # Public: Sets the default Faraday::Connection for simple scripts that
-    # access the Faraday constant directly.
-    #
-    #     Faraday.get "https://faraday.com"
+    # Documented below, see default_connection
     attr_writer :default_connection
 
-    # Public: Tells faraday to ignore the environment proxy (http_proxy).
+    # Tells Faraday to ignore the environment proxy (http_proxy).
+    # Defaults to `false`.
+    # @return [Boolean]
     attr_accessor :ignore_env_proxy
 
-    # Public: Initializes a new Faraday::Connection.
-    #
-    # url     - The optional String base URL to use as a prefix for all
-    #           requests.  Can also be the options Hash.
-    # options - The optional Hash used to configure this Faraday::Connection.
-    #           Any of these values will be set on every request made, unless
-    #           overridden for a specific request.
-    #           :url     - String base URL.
-    #           :params  - Hash of URI query unencoded key/value pairs.
-    #           :headers - Hash of unencoded HTTP header key/value pairs.
-    #           :request - Hash of request options.
-    #           :ssl     - Hash of SSL options.
-    #           :proxy   - Hash of Proxy options.
-    #
-    # Examples
-    #
+    # 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'
-    #
-    #   # http://faraday.com?page=1
-    #   Faraday.new 'http://faraday.com', :params => {:page => 1}
-    #
-    #   # same
-    #
-    #   Faraday.new :url => 'http://faraday.com',
-    #     :params => {:page => 1}
-    #
-    # Returns a Faraday::Connection.
-    def new(url = nil, options = nil, &block)
-      options = options ? default_connection_options.merge(options) : default_connection_options
+    #   # => 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
 
+    # @private
     # Internal: Requires internal Faraday libraries.
     #
-    # *libs - One or more relative String names to Faraday classes.
-    #
-    # Returns nothing.
+    # @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
 
-    # Public: Updates default adapter while resetting
-    # #default_connection.
-    #
-    # Returns the new default_adapter.
+    alias require_lib require_libs
+
+    # Documented elsewhere, see default_adapter reader
     def default_adapter=(adapter)
       @default_connection = nil
       @default_adapter = adapter
     end
 
-    alias require_lib require_libs
-
-    def respond_to?(symbol, include_private = false)
+    def respond_to_missing?(symbol, include_private = false)
       default_connection.respond_to?(symbol, include_private) || super
     end
 
-  private
-    # Internal: Proxies method calls on the Faraday constant to
-    # #default_connection.
-    def method_missing(name, *args, &block)
-      default_connection.send(name, *args, &block)
+    # @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 default_connection
+      @default_connection ||= Connection.new(default_connection_options)
     end
-  end
-
-  self.ignore_env_proxy = false
-  self.root_path = File.expand_path "..", __FILE__
-  self.lib_path = File.expand_path "../faraday", __FILE__
-  self.default_adapter = :net_http
 
-  # Gets the default connection used for simple scripts.
-  #
-  # Returns a Faraday::Connection, configured with the #default_adapter.
-  def self.default_connection
-    @default_connection ||= Connection.new(default_connection_options)
-  end
-
-  # Gets the default connection options used when calling Faraday#new.
-  #
-  # Returns a Faraday::ConnectionOptions.
-  def self.default_connection_options
-    @default_connection_options ||= ConnectionOptions.new
-  end
-
-  # Public: Sets the default options used when calling Faraday#new.
-  def self.default_connection_options=(options)
-    @default_connection = nil
-    @default_connection_options = ConnectionOptions.from(options)
-  end
-
-  unless const_defined? :Timer
-    require 'timeout'
-    Timer = Timeout
-  end
-
-  # Public: Adds the ability for other modules to register and lookup
-  # middleware classes.
-  module MiddlewareRegistry
-    # Public: Register middleware class(es) on the current module.
-    #
-    # mapping - A Hash mapping Symbol keys to classes. Classes can be expressed
-    #           as fully qualified constant, or a Proc that will be lazily
-    #           called to return the former.
-    #
-    # Examples
-    #
-    #   module Faraday
-    #     class Whatever
-    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
-    #       register_middleware :foo => Foo
+    # Gets the default connection options used when calling {Faraday#new}.
     #
-    #       # Middleware looked up by :bar returns Faraday::Whatever.const_get(:Bar)
-    #       register_middleware :bar => :Bar
-    #
-    #       # Middleware looked up by :baz requires 'baz' and returns Faraday::Whatever.const_get(:Baz)
-    #       register_middleware :baz => [:Baz, 'baz']
-    #     end
-    #   end
-    #
-    # Returns nothing.
-    def register_middleware(autoload_path = nil, mapping = nil)
-      if mapping.nil?
-        mapping = autoload_path
-        autoload_path = nil
-      end
-      middleware_mutex do
-        @middleware_autoload_path = autoload_path if autoload_path
-        (@registered_middleware ||= {}).update(mapping)
-      end
+    # @return [Faraday::ConnectionOptions]
+    def default_connection_options
+      @default_connection_options ||= ConnectionOptions.new
     end
 
-    # Public: Lookup middleware class with a registered Symbol shortcut.
-    #
-    # key - The Symbol key for the registered middleware.
-    #
-    # Examples
-    #
-    #   module Faraday
-    #     class Whatever
-    #       register_middleware :foo => Foo
-    #     end
-    #   end
+    # Sets the default options used when calling {Faraday#new}.
     #
-    #   Faraday::Whatever.lookup_middleware(:foo)
-    #   # => Faraday::Whatever::Foo
-    #
-    # Returns a middleware Class.
-    def lookup_middleware(key)
-      load_middleware(key) ||
-        raise(Faraday::Error.new("#{key.inspect} is not registered on #{self}"))
-    end
-
-    def middleware_mutex(&block)
-      @middleware_mutex ||= begin
-        require 'monitor'
-        Monitor.new
-      end
-      @middleware_mutex.synchronize(&block)
+    # @param options [Hash, Faraday::ConnectionOptions]
+    def default_connection_options=(options)
+      @default_connection = nil
+      @default_connection_options = ConnectionOptions.from(options)
     end
 
-    def fetch_middleware(key)
-      defined?(@registered_middleware) && @registered_middleware[key]
-    end
+    private
 
-    def load_middleware(key)
-      value = fetch_middleware(key)
-      case value
-      when Module
-        value
-      when Symbol, String
-        middleware_mutex do
-          @registered_middleware[key] = const_get(value)
-        end
-      when Proc
-        middleware_mutex do
-          @registered_middleware[key] = value.call
-        end
-      when Array
-        middleware_mutex do
-          const, path = value
-          if root = @middleware_autoload_path
-            path = "#{root}/#{path}"
-          end
-          require(path)
-          @registered_middleware[key] = const
-        end
-        load_middleware(key)
+    # 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
 
-  def self.const_missing(name)
-    if name.to_sym == :Builder
-      warn "Faraday::Builder is now Faraday::RackBuilder."
-      const_set name, RackBuilder
-    else
-      super
-    end
-  end
-
-  require_libs "utils", "options", "connection", "rack_builder", "parameters",
-    "middleware", "adapter", "request", "response", "upload_io", "error"
+  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
 
-  if !ENV["FARADAY_NO_AUTOLOAD"]
-    require_lib 'autoload'
-  end
+  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,49 @@
+# frozen_string_literal: true
+
+unless defined?(JRUBY_VERSION)
+  RSpec.describe Faraday::Adapter::EMHttp 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
+end

data/spec/faraday/adapter/em_synchrony_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+unless defined?(JRUBY_VERSION)
+  RSpec.describe Faraday::Adapter::EMSynchrony 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
+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_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