faraday 0.15.4 → 0.16.0

data/lib/faraday/adapter/typhoeus.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module Faraday
   class Adapter
-    # This class is just a stub, the real adapter is in https://github.com/philsturgeon/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
+    # Typhoeus adapter. This class is just a stub, the real adapter is in
+    # https://github.com/philsturgeon/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
     class Typhoeus < Faraday::Adapter
       # Needs to define this method in order to support Typhoeus <= 1.3.0
       def call; end

data/lib/faraday/adapter_registry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Faraday
+  # AdapterRegistry registers adapter class names so they can be looked up by a
+  # String or Symbol name.
+  class AdapterRegistry
+    def initialize
+      @lock = Monitor.new
+      @constants = {}
+    end
+
+    def get(name)
+      klass = @constants[name]
+      return klass if klass
+
+      Object.const_get(name).tap { |c| set(c, name) }
+    end
+
+    def set(klass, name = nil)
+      name ||= klass.to_s
+      @lock.synchronize do
+        @constants[name] = klass
+      end
+    end
+  end
+end

data/lib/faraday/autoload.rb

@@ -1,84 +1,95 @@
+# frozen_string_literal: true
+
 module Faraday
-  # Internal: Adds the ability for other modules to manage autoloadable
+  # Adds the ability for other modules to manage autoloadable
   # constants.
+  #
+  # @api private
   module AutoloadHelper
-    # Internal: Registers the constants to be auto loaded.
+    # Registers the constants to be auto loaded.
     #
-    # prefix  - The String require prefix.  If the path is inside Faraday, then
-    #           it will be prefixed with the root path of this loaded Faraday
-    #           version.
-    # options - Hash of Symbol => String library names.
+    # @param prefix [String] The require prefix. If the path is inside Faraday,
+    #           then it will be prefixed with the root path of this loaded
+    #           Faraday version.
+    # @param options [{ Symbol => String }] library names.
     #
-    # Examples.
+    # @example
     #
     #   Faraday.autoload_all 'faraday/foo',
-    #     :Bar => 'bar'
+    #     Bar: 'bar'
     #
     #   # requires faraday/foo/bar to load Faraday::Bar.
     #   Faraday::Bar
     #
-    #
-    # Returns nothing.
+    # @return [void]
     def autoload_all(prefix, options)
-      if prefix =~ /^faraday(\/|$)/i
+      if prefix =~ %r{^faraday(/|$)}i
         prefix = File.join(Faraday.root_path, prefix)
       end
+
       options.each do |const_name, path|
         autoload const_name, File.join(prefix, path)
       end
     end
 
-    # Internal: Loads each autoloaded constant.  If thread safety is a concern,
+    # Loads each autoloaded constant.  If thread safety is a concern,
     # wrap this in a Mutex.
     #
-    # Returns nothing.
+    # @return [void]
     def load_autoloaded_constants
       constants.each do |const|
         const_get(const) if autoload?(const)
       end
     end
 
-    # Internal: Filters the module's contents with those that have been already
+    # Filters the module's contents with those that have been already
     # autoloaded.
     #
-    # Returns an Array of Class/Module objects.
+    # @return [Array<Class, Module>]
     def all_loaded_constants
-      constants.map { |c| const_get(c) }.
-        select { |a| a.respond_to?(:loaded?) && a.loaded? }
+      constants
+        .map { |c| const_get(c) }
+        .select { |a| a.respond_to?(:loaded?) && a.loaded? }
     end
   end
 
+  # Adapter is the base class for all Faraday adapters.
+  # @see lib/faraday/adapter.rb Original class location
   class Adapter
     extend AutoloadHelper
     autoload_all 'faraday/adapter',
-      :NetHttp           => 'net_http',
-      :NetHttpPersistent => 'net_http_persistent',
-      :EMSynchrony       => 'em_synchrony',
-      :EMHttp            => 'em_http',
-      :Typhoeus          => 'typhoeus',
-      :Patron            => 'patron',
-      :Excon             => 'excon',
-      :Test              => 'test',
-      :Rack              => 'rack',
-      :HTTPClient        => 'httpclient'
+                 NetHttp: 'net_http',
+                 NetHttpPersistent: 'net_http_persistent',
+                 EMSynchrony: 'em_synchrony',
+                 EMHttp: 'em_http',
+                 Typhoeus: 'typhoeus',
+                 Patron: 'patron',
+                 Excon: 'excon',
+                 Test: 'test',
+                 Rack: 'rack',
+                 HTTPClient: 'httpclient'
   end
 
+  # Request represents a single HTTP request for a Faraday adapter to make.
+  # @see lib/faraday/request.rb Original class location
   class Request
     extend AutoloadHelper
     autoload_all 'faraday/request',
-      :UrlEncoded => 'url_encoded',
-      :Multipart => 'multipart',
-      :Retry => 'retry',
-      :Authorization => 'authorization',
-      :BasicAuthentication => 'basic_authentication',
-      :TokenAuthentication => 'token_authentication',
-      :Instrumentation => 'instrumentation'
+                 UrlEncoded: 'url_encoded',
+                 Multipart: 'multipart',
+                 Retry: 'retry',
+                 Authorization: 'authorization',
+                 BasicAuthentication: 'basic_authentication',
+                 TokenAuthentication: 'token_authentication',
+                 Instrumentation: 'instrumentation'
   end
 
+  # Response represents the returned value of a sent Faraday request.
+  # @see lib/faraday/response.rb Original class location
   class Response
     extend AutoloadHelper
     autoload_all 'faraday/response',
-      :RaiseError => 'raise_error',
-      :Logger     => 'logger'
+                 RaiseError: 'raise_error',
+                 Logger: 'logger'
   end
 end

data/lib/faraday/connection.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Faraday
-  # Public: Connection objects manage the default properties and the middleware
+  # Connection objects manage the default properties and the middleware
   # stack for fulfilling an HTTP request.
   #
-  # Examples
+  # @example
   #
   #   conn = Faraday::Connection.new 'http://sushi.com'
   #
@@ -12,51 +14,51 @@ module Faraday
   #
   class Connection
     # A Set of allowed HTTP verbs.
-    METHODS = Set.new [:get, :post, :put, :delete, :head, :patch, :options]
+    METHODS = Set.new %i[get post put delete head patch options trace connect]
 
-    # Public: Returns a Hash of URI query unencoded key/value pairs.
+    # @return [Hash] URI query unencoded key/value pairs.
     attr_reader :params
 
-    # Public: Returns a Hash of unencoded HTTP header key/value pairs.
+    # @return [Hash] unencoded HTTP header key/value pairs.
     attr_reader :headers
 
-    # Public: Returns a URI with the prefix used for all requests from this
-    # Connection.  This includes a default host name, scheme, port, and path.
+    # @return [String] a URI with the prefix used for all requests from this
+    #   Connection. This includes a default host name, scheme, port, and path.
     attr_reader :url_prefix
 
-    # Public: Returns the Faraday::Builder for this Connection.
+    # @return [Faraday::Builder] Builder for this Connection.
     attr_reader :builder
 
-    # Public: Returns a Hash of the request options.
-    attr_reader :options
-
-    # Public: Returns a Hash of the SSL options.
+    # @return [Hash] SSL options.
     attr_reader :ssl
 
-    # Public: Returns the parallel manager for this Connection.
+    # @return [Object] the parallel manager for this Connection.
     attr_reader :parallel_manager
 
-    # Public: Sets the default parallel manager for this connection.
+    # Sets the default parallel manager for this connection.
     attr_writer :default_parallel_manager
 
-    # Public: Gets or Sets the Hash proxy options.
-    # attr_reader :proxy
+    # @return [Hash] proxy options.
+    attr_reader :proxy
 
-    # Public: Initializes a new Faraday::Connection.
+    # Initializes a new Faraday::Connection.
     #
-    # url     - URI or String base URL to use as a prefix for all
+    # @param url [URI, String] URI or String base URL to use as a prefix for all
     #           requests (optional).
-    # options - Hash or Faraday::ConnectionOptions.
-    #           :url     - URI or String base URL (default: "http:/").
-    #           :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   - URI, String or Hash of HTTP proxy options
-    #                     (default: "http_proxy" environment variable).
-    #                     :uri      - URI or String
-    #                     :user     - String (optional)
-    #                     :password - String (optional)
+    # @param options [Hash, Faraday::ConnectionOptions]
+    # @option options [URI, String] :url ('http:/') URI or String base URL
+    # @option options [Hash<String => String>] :params URI query unencoded
+    #                 key/value pairs.
+    # @option options [Hash<String => String>] :headers Hash of unencoded HTTP
+    #                 header key/value pairs.
+    # @option options [Hash] :request Hash of request options.
+    # @option options [Hash] :ssl Hash of SSL options.
+    # @option options [Hash, URI, String] :proxy proxy options, either as a URL
+    #                 or as a Hash
+    # @option options [URI, String] :proxy[:uri]
+    # @option options [String] :proxy[:user]
+    # @option options [String] :proxy[:password]
+    # @yield [self] after all setup has been done
     def initialize(url = nil, options = nil)
       options = ConnectionOptions.from(options)
 
@@ -74,7 +76,7 @@ module Faraday
 
       @builder = options.builder || begin
         # pass an empty block to Builder so it doesn't assume default middleware
-        options.new_builder(block_given? ? Proc.new { |b| } : nil)
+        options.new_builder(block_given? ? proc { |b| } : nil)
       end
 
       self.url_prefix = url || 'http:/'
@@ -82,21 +84,32 @@ module Faraday
       @params.update(options.params)   if options.params
       @headers.update(options.headers) if options.headers
 
-      @manual_proxy = !!options.proxy
-      @proxy = options.proxy ? ProxyOptions.from(options.proxy) : proxy_from_env(url)
-      @temp_proxy = @proxy
+      initialize_proxy(url, options)
 
       yield(self) if block_given?
 
       @headers[:user_agent] ||= "Faraday v#{VERSION}"
     end
 
-    # Public: Sets the Hash of URI query unencoded key/value pairs.
+    def initialize_proxy(url, options)
+      @manual_proxy = !!options.proxy
+      @proxy =
+        if options.proxy
+          ProxyOptions.from(options.proxy)
+        else
+          proxy_from_env(url)
+        end
+      @temp_proxy = @proxy
+    end
+
+    # Sets the Hash of URI query unencoded key/value pairs.
+    # @param hash [Hash]
     def params=(hash)
       @params.replace hash
     end
 
-    # Public: Sets the Hash of unencoded HTTP header key/value pairs.
+    # Sets the Hash of unencoded HTTP header key/value pairs.
+    # @param hash [Hash]
     def headers=(hash)
       @headers.replace hash
     end
@@ -105,71 +118,171 @@ module Faraday
 
     def_delegators :builder, :build, :use, :request, :response, :adapter, :app
 
-    # Public: Makes an HTTP request without a body.
+    # @!method get(url = nil, params = nil, headers = nil)
+    # Makes a GET HTTP request without a body.
+    # @!scope class
     #
-    # url     - The optional String base URL to use as a prefix for all
-    #           requests.  Can also be the options Hash.
-    # params  - Hash of URI query unencoded key/value pairs.
-    # headers - Hash of unencoded HTTP header key/value pairs.
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param params [Hash] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
     #
-    # Examples
-    #
-    #   conn.get '/items', {:page => 1}, :accept => 'application/json'
-    #   conn.head '/items/1'
+    # @example
+    #   conn.get '/items', { page: 1 }, :accept => 'application/json'
     #
     #   # ElasticSearch example sending a body with GET.
     #   conn.get '/twitter/tweet/_search' do |req|
     #     req.headers[:content_type] = 'application/json'
     #     req.params[:routing] = 'kimchy'
-    #     req.body = JSON.generate(:query => {...})
+    #     req.body = JSON.generate(query: {...})
     #   end
     #
-    # Yields a Faraday::Request for further request customizations.
-    # Returns a Faraday::Response.
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!method head(url = nil, params = nil, headers = nil)
+    # Makes a HEAD HTTP request without a body.
+    # @!scope class
+    #
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param params [Hash] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    #
+    # @example
+    #   conn.head '/items/1'
+    #
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!method delete(url = nil, params = nil, headers = nil)
+    # Makes a DELETE HTTP request without a body.
+    # @!scope class
+    #
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param params [Hash] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    #
+    # @example
+    #   conn.delete '/items/1'
     #
-    # Signature
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!method connect(url = nil, params = nil, headers = nil)
+    # Makes a CONNECT HTTP request without a body.
+    # @!scope class
     #
-    #   <verb>(url = nil, params = nil, headers = nil)
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param params [Hash] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
     #
-    # verb - An HTTP verb: get, head, or delete.
-    %w[get head delete].each do |method|
+    # @example
+    #   conn.connect '/items/1'
+    #
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!method trace(url = nil, params = nil, headers = nil)
+    # Makes a TRACE HTTP request without a body.
+    # @!scope class
+    #
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param params [Hash] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    #
+    # @example
+    #   conn.connect '/items/1'
+    #
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!visibility private
+    METHODS_WITH_QUERY.each do |method|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method}(url = nil, params = nil, headers = nil)
-          run_request(:#{method}, url, nil, headers) { |request|
+          run_request(:#{method}, url, nil, headers) do |request|
             request.params.update(params) if params
-            yield(request) if block_given?
-          }
+            yield request if block_given?
+          end
         end
       RUBY
     end
 
-    # Public: Makes an HTTP request with a body.
+    # @overload options()
+    #   Returns current Connection options.
     #
-    # url     - The optional String base URL to use as a prefix for all
-    #           requests.  Can also be the options Hash.
-    # body    - The String body for the request.
-    # headers - Hash of unencoded HTTP header key/value pairs.
+    # @overload options(url, params = nil, headers = nil)
+    #   Makes an OPTIONS HTTP request to the given URL.
+    #   @param url [String] String base URL to sue as a prefix for all requests.
+    #   @param params [Hash] Hash of URI query unencoded key/value pairs.
+    #   @param headers [Hash] unencoded HTTP header key/value pairs.
     #
-    # Examples
+    # @example
+    #   conn.options '/items/1'
     #
-    #   conn.post '/items', data, :content_type => 'application/json'
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+    def options(*args)
+      return @options if args.size.zero?
+
+      url, params, headers = *args
+      run_request(:options, url, nil, headers) do |request|
+        request.params.update(params) if params
+        yield request if block_given?
+      end
+    end
+
+    # @!method post(url = nil, body = nil, headers = nil)
+    # Makes a POST HTTP request with a body.
+    # @!scope class
+    #
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param body [String] body for the request.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    #
+    # @example
+    #   conn.post '/items', data, content_type: 'application/json'
     #
     #   # Simple ElasticSearch indexing sample.
     #   conn.post '/twitter/tweet' do |req|
     #     req.headers[:content_type] = 'application/json'
     #     req.params[:routing] = 'kimchy'
-    #     req.body = JSON.generate(:user => 'kimchy', ...)
+    #     req.body = JSON.generate(user: 'kimchy', ...)
     #   end
     #
-    # Yields a Faraday::Request for further request customizations.
-    # Returns a Faraday::Response.
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!method put(url = nil, body = nil, headers = nil)
+    # Makes a PUT HTTP request with a body.
+    # @!scope class
     #
-    # Signature
+    # @param url [String] The optional String base URL to use as a prefix for
+    #            all requests.  Can also be the options Hash.
+    # @param body [String] body for the request.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
     #
-    #   <verb>(url = nil, body = nil, headers = nil)
+    # @example
+    #   # TODO: Make it a PUT example
+    #   conn.post '/items', data, content_type: 'application/json'
     #
-    # verb - An HTTP verb: post, put, or patch.
-    %w[post put patch].each do |method|
+    #   # Simple ElasticSearch indexing sample.
+    #   conn.post '/twitter/tweet' do |req|
+    #     req.headers[:content_type] = 'application/json'
+    #     req.params[:routing] = 'kimchy'
+    #     req.body = JSON.generate(user: 'kimchy', ...)
+    #   end
+    #
+    # @yield [Faraday::Request] for further request customizations
+    # @return [Faraday::Response]
+
+    # @!visibility private
+    METHODS_WITH_BODY.each do |method|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method}(url = nil, body = nil, headers = nil, &block)
           run_request(:#{method}, url, body, headers, &block)
@@ -177,116 +290,110 @@ module Faraday
       RUBY
     end
 
-    # Public: Sets up the Authorization header with these credentials, encoded
+    # Sets up the Authorization header with these credentials, encoded
     # with base64.
     #
-    # login - The authentication login.
-    # pass  - The authentication password.
+    # @param login [String] The authentication login.
+    # @param pass [String] The authentication password.
     #
-    # Examples
+    # @example
     #
     #   conn.basic_auth 'Aladdin', 'open sesame'
     #   conn.headers['Authorization']
     #   # => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
     #
-    # Returns nothing.
+    # @return [void]
     def basic_auth(login, pass)
       set_authorization_header(:basic_auth, login, pass)
     end
 
-    # Public: Sets up the Authorization header with the given token.
+    # Sets up the Authorization header with the given token.
     #
-    # token   - The String token.
-    # options - Optional Hash of extra token options.
+    # @param token [String]
+    # @param options [Hash] extra token options.
     #
-    # Examples
+    # @example
     #
-    #   conn.token_auth 'abcdef', :foo => 'bar'
+    #   conn.token_auth 'abcdef', foo: 'bar'
     #   conn.headers['Authorization']
     #   # => "Token token=\"abcdef\",
     #               foo=\"bar\""
     #
-    # Returns nothing.
+    # @return [void]
     def token_auth(token, options = nil)
       set_authorization_header(:token_auth, token, options)
     end
 
-    # Public: Sets up a custom Authorization header.
+    # Sets up a custom Authorization header.
     #
-    # type  - The String authorization type.
-    # token - The String or Hash token.  A String value is taken literally, and
-    #         a Hash is encoded into comma separated key/value pairs.
+    # @param type [String] authorization type
+    # @param token [String, Hash] token. A String value is taken literally, and
+    #         a Hash is encoded into comma-separated key/value pairs.
     #
-    # Examples
+    # @example
     #
     #   conn.authorization :Bearer, 'mF_9.B5f-4.1JqM'
     #   conn.headers['Authorization']
     #   # => "Bearer mF_9.B5f-4.1JqM"
     #
-    #   conn.authorization :Token, :token => 'abcdef', :foo => 'bar'
+    #   conn.authorization :Token, token: 'abcdef', foo: 'bar'
     #   conn.headers['Authorization']
     #   # => "Token token=\"abcdef\",
     #               foo=\"bar\""
     #
-    # Returns nothing.
+    # @return [void]
     def authorization(type, token)
       set_authorization_header(:authorization, type, token)
     end
 
-    # Internal: Traverse the middleware stack in search of a
-    # parallel-capable adapter.
+    # Check if the adapter is parallel-capable.
     #
-    # Yields in case of not found.
+    # @yield if the adapter isn't parallel-capable, or if no adapter is set yet.
     #
-    # Returns a parallel manager or nil if not found.
+    # @return [Object, nil] a parallel manager or nil if yielded
+    # @api private
     def default_parallel_manager
       @default_parallel_manager ||= begin
-        handler = @builder.handlers.detect do |h|
-          h.klass.respond_to?(:supports_parallel?) and h.klass.supports_parallel?
-        end
+        adapter = @builder.adapter.klass if @builder.adapter
 
-        if handler
-          handler.klass.setup_parallel_manager
+        if support_parallel?(adapter)
+          adapter.setup_parallel_manager
         elsif block_given?
           yield
         end
       end
     end
 
-    # Public: Determine if this Faraday::Connection can make parallel requests.
+    # Determine if this Faraday::Connection can make parallel requests.
     #
-    # Returns true or false.
+    # @return [Boolean]
     def in_parallel?
       !!@parallel_manager
     end
 
-    # Public: Sets up the parallel manager to make a set of requests.
+    # Sets up the parallel manager to make a set of requests.
     #
-    # manager - The parallel manager that this Connection's Adapter uses.
+    # @param manager [Object] The parallel manager that this Connection's
+    #                Adapter uses.
     #
-    # Yields a block to execute multiple requests.
-    # Returns nothing.
+    # @yield a block to execute multiple requests.
+    # @return [void]
     def in_parallel(manager = nil)
-      @parallel_manager = manager || default_parallel_manager {
-        warn "Warning: `in_parallel` called but no parallel-capable adapter on Faraday stack"
-        warn caller[2,10].join("\n")
+      @parallel_manager = manager || default_parallel_manager do
+        warn 'Warning: `in_parallel` called but no parallel-capable adapter ' \
+             'on Faraday stack'
+        warn caller[2, 10].join("\n")
         nil
-      }
+      end
       yield
-      @parallel_manager && @parallel_manager.run
+      @parallel_manager&.run
     ensure
       @parallel_manager = nil
     end
 
-    # Public: Gets or Sets the Hash proxy options.
-    def proxy(arg = nil)
-      return @proxy if arg.nil?
-      warn 'Warning: use of proxy(new_value) to set connection proxy have been DEPRECATED and will be removed in Faraday 1.0'
-      @manual_proxy = true
-      @proxy = ProxyOptions.from(arg)
-    end
-
-    # Public: Sets the Hash proxy options.
+    # Sets the Hash proxy options.
+    #
+    # @param new_value [Object]
     def proxy=(new_value)
       @manual_proxy = true
       @proxy = new_value ? ProxyOptions.from(new_value) : nil
@@ -295,13 +402,14 @@ module Faraday
     def_delegators :url_prefix, :scheme, :scheme=, :host, :host=, :port, :port=
     def_delegator :url_prefix, :path, :path_prefix
 
-    # Public: Parses the giving url with URI and stores the individual
-    # components in this connection.  These components serve as defaults for
+    # Parses the given URL with URI and stores the individual
+    # components in this connection. These components serve as defaults for
     # requests made by this connection.
     #
-    # url - A String or URI.
+    # @param url [String, URI]
+    # @param encoder [Object]
     #
-    # Examples
+    # @example
     #
     #   conn = Faraday::Connection.new { ... }
     #   conn.url_prefix = "https://sushi.com/api"
@@ -309,8 +417,6 @@ module Faraday
     #   conn.path_prefix # => "/api"
     #
     #   conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
-    #
-    # Returns the parsed URI from the given input..
     def url_prefix=(url, encoder = nil)
       uri = @url_prefix = Utils.URI(url)
       self.path_prefix = uri.path
@@ -322,54 +428,65 @@ module Faraday
         basic_auth user, password
         uri.user = uri.password = nil
       end
-
-      uri
     end
 
-    # Public: Sets the path prefix and ensures that it always has a leading
+    # Sets the path prefix and ensures that it always has a leading
     # slash.
     #
-    # value - A String.
+    # @param value [String]
     #
-    # Returns the new String path prefix.
+    # @return [String] the new path prefix
     def path_prefix=(value)
       url_prefix.path = if value
-        value = '/' + value unless value[0,1] == '/'
-        value
-      end
+                          value = '/' + value unless value[0, 1] == '/'
+                          value
+                        end
     end
 
-    # Public: Takes a relative url for a request and combines it with the defaults
+    # Takes a relative url for a request and combines it with the defaults
     # set on the connection instance.
     #
+    # @param url [String]
+    # @param extra_params [Hash]
+    #
+    # @example
     #   conn = Faraday::Connection.new { ... }
     #   conn.url_prefix = "https://sushi.com/api?token=abc"
     #   conn.scheme      # => https
     #   conn.path_prefix # => "/api"
     #
-    #   conn.build_url("nigiri?page=2")      # => https://sushi.com/api/nigiri?token=abc&page=2
-    #   conn.build_url("nigiri", :page => 2) # => https://sushi.com/api/nigiri?token=abc&page=2
+    #   conn.build_url("nigiri?page=2")
+    #   # => https://sushi.com/api/nigiri?token=abc&page=2
+    #
+    #   conn.build_url("nigiri", page: 2)
+    #   # => https://sushi.com/api/nigiri?token=abc&page=2
     #
     def build_url(url = nil, extra_params = nil)
       uri = build_exclusive_url(url)
 
       query_values = params.dup.merge_query(uri.query, options.params_encoder)
-      query_values.update extra_params if extra_params
-      uri.query = query_values.empty? ? nil : query_values.to_query(options.params_encoder)
+      query_values.update(extra_params) if extra_params
+      uri.query =
+        if query_values.empty?
+          nil
+        else
+          query_values.to_query(options.params_encoder)
+        end
 
       uri
     end
 
     # Builds and runs the Faraday::Request.
     #
-    # method  - The Symbol HTTP method.
-    # url     - The String or URI to access.
-    # body    - The request body that will eventually be converted to a string.
-    # headers - Hash of unencoded HTTP header key/value pairs.
+    # @param method [Symbol] HTTP method.
+    # @param url [String, URI] String or URI to access.
+    # @param body [Object] The request body that will eventually be converted to
+    #             a string.
+    # @param headers [Hash] unencoded HTTP header key/value pairs.
     #
-    # Returns a Faraday::Response.
+    # @return [Faraday::Response]
     def run_request(method, url, body, headers)
-      if !METHODS.include?(method)
+      unless METHODS.include?(method)
         raise ArgumentError, "unknown http method: #{method}"
       end
 
@@ -377,7 +494,7 @@ module Faraday
       @temp_proxy = proxy_for_request(url)
 
       request = build_request(method) do |req|
-        req.options = req.options.merge(:proxy => @temp_proxy)
+        req.options = req.options.merge(proxy: @temp_proxy)
         req.url(url)                if url
         req.headers.update(headers) if headers
         req.body = body             if body
@@ -389,73 +506,93 @@ module Faraday
 
     # Creates and configures the request object.
     #
-    # Returns the new Request.
+    # @param method [Symbol]
+    #
+    # @yield [Faraday::Request] if block given
+    # @return [Faraday::Request]
     def build_request(method)
       Request.create(method) do |req|
-        req.params  = self.params.dup
-        req.headers = self.headers.dup
-        req.options = self.options
+        req.params  = params.dup
+        req.headers = headers.dup
+        req.options = options
         yield(req) if block_given?
       end
     end
 
-    # Internal: Build an absolute URL based on url_prefix.
+    # Build an absolute URL based on url_prefix.
     #
-    # url    - A String or URI-like object
-    # params - A Faraday::Utils::ParamsHash to replace the query values
+    # @param url [String, URI]
+    # @param params [Faraday::Utils::ParamsHash] A Faraday::Utils::ParamsHash to
+    #               replace the query values
     #          of the resulting url (default: nil).
     #
-    # Returns the resulting URI instance.
+    # @return [URI]
     def build_exclusive_url(url = nil, params = nil, params_encoder = nil)
-      url = nil if url.respond_to?(:empty?) and url.empty?
+      url = nil if url.respond_to?(:empty?) && url.empty?
       base = url_prefix
-      if url and base.path and base.path !~ /\/$/
+      if url && base.path && base.path !~ %r{/$}
         base = base.dup
-        base.path = base.path + '/'  # ensure trailing slash
+        base.path = base.path + '/' # ensure trailing slash
       end
       uri = url ? base + url : base
-      uri.query = params.to_query(params_encoder || options.params_encoder) if params
-      uri.query = nil if uri.query and uri.query.empty?
+      if params
+        uri.query = params.to_query(params_encoder || options.params_encoder)
+      end
+      # rubocop:disable Style/SafeNavigation
+      uri.query = nil if uri.query && uri.query.empty?
+      # rubocop:enable Style/SafeNavigation
       uri
     end
 
-    # Internal: Creates a duplicate of this Faraday::Connection.
+    # Creates a duplicate of this Faraday::Connection.
     #
-    # Returns a Faraday::Connection.
+    # @api private
+    #
+    # @return [Faraday::Connection]
     def dup
       self.class.new(build_exclusive_url,
-                     :headers => headers.dup,
-                     :params => params.dup,
-                     :builder => builder.dup,
-                     :ssl => ssl.dup,
-                     :request => options.dup)
+                     headers: headers.dup,
+                     params: params.dup,
+                     builder: builder.dup,
+                     ssl: ssl.dup,
+                     request: options.dup)
     end
 
-    # Internal: Yields username and password extracted from a URI if they both exist.
+    # Yields username and password extracted from a URI if they both exist.
+    #
+    # @param uri [URI]
+    # @yield [username, password] any username and password
+    # @yieldparam username [String] any username from URI
+    # @yieldparam password [String] any password from URI
+    # @return [void]
+    # @api private
     def with_uri_credentials(uri)
-      if uri.user and uri.password
-        yield(Utils.unescape(uri.user), Utils.unescape(uri.password))
-      end
+      return unless uri.user && uri.password
+
+      yield(Utils.unescape(uri.user), Utils.unescape(uri.password))
     end
 
     def set_authorization_header(header_type, *args)
-      header = Faraday::Request.lookup_middleware(header_type).
-        header(*args)
+      header = Faraday::Request
+               .lookup_middleware(header_type)
+               .header(*args)
+
       headers[Faraday::Request::Authorization::KEY] = header
     end
 
     def proxy_from_env(url)
       return if Faraday.ignore_env_proxy
+
       uri = nil
       if URI.parse('').respond_to?(:find_proxy)
         case url
         when String
-            uri = Utils.URI(url)
-            uri = URI.parse("#{uri.scheme}://#{uri.hostname}").find_proxy
-          when URI
-            uri = url.find_proxy
-          when nil
-            uri = find_default_proxy
+          uri = Utils.URI(url)
+          uri = URI.parse("#{uri.scheme}://#{uri.hostname}").find_proxy
+        when URI
+          uri = url.find_proxy
+        when nil
+          uri = find_default_proxy
         end
       else
         warn 'no_proxy is unsupported' if ENV['no_proxy'] || ENV['NO_PROXY']
@@ -466,19 +603,24 @@ module Faraday
 
     def find_default_proxy
       uri = ENV['http_proxy']
-      if uri && !uri.empty?
-        uri = 'http://' + uri if uri !~ /^http/i
-        uri
-      end
+      return unless uri && !uri.empty?
+
+      uri = 'http://' + uri if uri !~ /^http/i
+      uri
     end
 
     def proxy_for_request(url)
-      return self.proxy if @manual_proxy
+      return proxy if @manual_proxy
+
       if url && Utils.URI(url).absolute?
         proxy_from_env(url)
       else
-        self.proxy
+        proxy
       end
     end
+
+    def support_parallel?(adapter)
+      adapter&.respond_to?(:supports_parallel?) && adapter&.supports_parallel?
+    end
   end
 end