class Faraday::Connection

Connection objects manage the default properties and the middleware stack for fulfilling an HTTP request.

@example

conn = Faraday::Connection.new 'http://httpbingo.org'

# GET http://httpbingo.org/nigiri
conn.get 'nigiri'
# => #<Faraday::Response>

Constants

METHODS: A Set of allowed HTTP verbs.
USER_AGENT

Attributes

builder [R]

@return [Faraday::RackBuilder] Builder for this Connection.

default_parallel_manager [W]

Sets the default parallel manager for this connection.

headers [R]

@return [Hash] unencoded HTTP header key/value pairs.

parallel_manager [R]

@return [Object] the parallel manager for this Connection.

params [R]

@return [Hash] URI query unencoded key/value pairs.

proxy [R]

@return [Hash] proxy options.

ssl [R]

@return [Hash] SSL options.

url_prefix [R]

@return [String] a URI with the prefix used for all requests from this

Connection. This includes a default host name, scheme, port, and path.

Public Class Methods

new (url = nil, options = nil) { |self| ... }

Initializes a new Faraday::Connection.

@param url [URI, String] URI or String base URL to use as a prefix for all

requests (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 @option options [String] :proxy @option options [String] :proxy @yield [self] after all setup has been done

# File lib/faraday/connection.rb, line 63
def initialize(url = nil, options = nil)
  options = ConnectionOptions.from(options)

  if url.is_a?(Hash) || url.is_a?(ConnectionOptions)
    options = Utils.deep_merge(options, url)
    url     = options.url
  end

  @parallel_manager = nil
  @headers = Utils::Headers.new
  @params  = Utils::ParamsHash.new
  @options = options.request
  @ssl = options.ssl
  @default_parallel_manager = options.parallel_manager
  @manual_proxy = nil

  @builder = options.builder || begin
    # pass an empty block to Builder so it doesn't assume default middleware
    options.new_builder(block_given? ? proc { |b| } : nil)
  end

  self.url_prefix = url || 'http:/'

  @params.update(options.params)   if options.params
  @headers.update(options.headers) if options.headers

  initialize_proxy(url, options)

  yield(self) if block_given?

  @headers[:user_agent] ||= USER_AGENT
end

Public Instance Methods

build_exclusive_url (url = nil, params = nil, params_encoder = nil)

Build an absolute URL based on url_prefix.

@param url [String, URI, nil] @param params [Faraday::Utils::ParamsHash] A Faraday::Utils::ParamsHash to

     replace the query values
of the resulting url (default: nil).

@return [URI]

# File lib/faraday/connection.rb, line 478
def build_exclusive_url(url = nil, params = nil, params_encoder = nil)
  url = nil if url.respond_to?(:empty?) && url.empty?
  base = url_prefix.dup
  if url && !base.path.end_with?('/')
    base.path = "#{base.path}/" # ensure trailing slash
  end
  # Ensure relative url will be parsed correctly (such as `service:search` )
  url = "./#{url}" if url.respond_to?(:start_with?) && !url.start_with?('http://', 'https://', '/', './', '../')
  uri = url ? base + url : base
  if params
    uri.query = params.to_query(params_encoder || options.params_encoder)
  end
  uri.query = nil if uri.query && uri.query.empty?
  uri
end

build_request (method) { |req| ... }

Creates and configures the request object.

@param method [Symbol]

@yield [Faraday::Request] if block given @return [Faraday::Request]

# File lib/faraday/connection.rb, line 461
def build_request(method)
  Request.create(method) do |req|
    req.params  = params.dup
    req.headers = headers.dup
    req.options = options.dup
    yield(req) if block_given?
  end
end

build_url (url = nil, extra_params = nil)

Takes a relative url for a request and combines it with the defaults set on the connection instance.

@param url [String, URI, nil] @param extra_params [Hash]

@example

conn = Faraday::Connection.new { ... }
conn.url_prefix = "https://httpbingo.org/api?token=abc"
conn.scheme      # => https
conn.path_prefix # => "/api"

conn.build_url("nigiri?page=2")
# => https://httpbingo.org/api/nigiri?token=abc&page=2

conn.build_url("nigiri", page: 2)
# => https://httpbingo.org/api/nigiri?token=abc&page=2

# File lib/faraday/connection.rb, line 415
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 =
    if query_values.empty?
      nil
    else
      query_values.to_query(options.params_encoder)
    end

  uri
end

close ()

Closes the underlying resources and/or connections. In the case of persistent connections, this closes all currently open connections but does not prevent new connections from being made.

# File lib/faraday/connection.rb, line 125
def close
  app.close
end

default_parallel_manager () { || ... }

Check if the adapter is parallel-capable.

@yield if the adapter isn’t parallel-capable, or if no adapter is set yet.

@return [Object, nil] a parallel manager or nil if yielded @api private

# File lib/faraday/connection.rb, line 291
def default_parallel_manager
  @default_parallel_manager ||= begin
    adapter = @builder.adapter.klass if @builder.adapter

    if support_parallel?(adapter)
      adapter.setup_parallel_manager
    elsif block_given?
      yield
    end
  end
end

dup ()

Creates a duplicate of this Faraday::Connection.

@api private

@return [Faraday::Connection]

# File lib/faraday/connection.rb, line 499
def dup
  self.class.new(build_exclusive_url,
                 headers: headers.dup,
                 params: params.dup,
                 builder: builder.dup,
                 ssl: ssl.dup,
                 request: options.dup)
end

find_default_proxy ()

# File lib/faraday/connection.rb, line 542
def find_default_proxy
  uri = ENV.fetch('http_proxy', nil)
  return unless uri && !uri.empty?

  uri = "http://#{uri}" unless uri.match?(/^http/i)
  uri
end

headers= (hash)

Sets the Hash of unencoded HTTP header key/value pairs. @param hash [Hash]

# File lib/faraday/connection.rb, line 114
def headers=(hash)
  @headers.replace hash
end

in_parallel (manager = nil) { || ... }

Sets up the parallel manager to make a set of requests.

@param manager [Object] The parallel manager that this Connection’s

Adapter uses.

@yield a block to execute multiple requests. @return [void]

# File lib/faraday/connection.rb, line 317
def in_parallel(manager = nil, &block)
  @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
  return yield unless @parallel_manager

  if @parallel_manager.respond_to?(:execute)
    # Execute is the new method that is responsible for executing the block.
    @parallel_manager.execute(&block)
  else
    # TODO: Old behaviour, deprecate and remove in 3.0
    yield
    @parallel_manager.run
  end
ensure
  @parallel_manager = nil
end

in_parallel? ()

Determine if this Faraday::Connection can make parallel requests.

@return [Boolean]

# File lib/faraday/connection.rb, line 306
def in_parallel?
  !!@parallel_manager
end

initialize_proxy (url, options)

# File lib/faraday/connection.rb, line 96
def initialize_proxy(url, options)
  @manual_proxy = !!options.proxy
  @proxy =
    if options.proxy
      ProxyOptions.from(options.proxy)
    else
      proxy_from_env(url)
    end
end

options (*args) { |request| ... }

@overload options()

Returns current Connection options.

@overload options(url, params = nil, headers = nil)

Makes an OPTIONS HTTP request to the given URL.
@param url [String, URI, nil] String base URL to sue as a prefix for all requests.
@param params [Hash, nil] Hash of URI query unencoded key/value pairs.
@param headers [Hash, nil] unencoded HTTP header key/value pairs.

@example

conn.options '/items/1'

@yield [Faraday::Request] for further request customizations @return [Faraday::Response]

# File lib/faraday/connection.rb, line 222
def options(*args)
  return @options if args.empty?

  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

params= (hash)

Sets the Hash of URI query unencoded key/value pairs. @param hash [Hash]

# File lib/faraday/connection.rb, line 108
def params=(hash)
  @params.replace hash
end

path_prefix= (value)

Sets the path prefix and ensures that it always has a leading slash.

@param value [String]

@return [String] the new path prefix

# File lib/faraday/connection.rb, line 390
def path_prefix=(value)
  url_prefix.path = if value
                      value = "/#{value}" unless value[0, 1] == '/'
                      value
                    end
end

proxy= (new_value)

Sets the Hash proxy options.

@param new_value [Object]

# File lib/faraday/connection.rb, line 341
def proxy=(new_value)
  @manual_proxy = true
  @proxy = new_value ? ProxyOptions.from(new_value) : nil
end

proxy_for_request (url)

# File lib/faraday/connection.rb, line 550
def proxy_for_request(url)
  return proxy if @manual_proxy

  if url && Utils.URI(url).absolute?
    proxy_from_env(url)
  else
    proxy
  end
end

proxy_from_env (url)

# File lib/faraday/connection.rb, line 522
def proxy_from_env(url)
  return if Faraday.ignore_env_proxy

  uri = nil
  case url
  when String
    uri = Utils.URI(url)
    uri = if uri.host.nil?
            find_default_proxy
          else
            URI.parse("#{uri.scheme}://#{uri.host}").find_proxy
          end
  when URI
    uri = url.find_proxy
  when nil
    uri = find_default_proxy
  end
  ProxyOptions.from(uri) if uri
end

run_request (method, url, body, headers) { |req| ... }

Builds and runs the Faraday::Request.

@param method [Symbol] HTTP method. @param url [String, URI, nil] String or URI to access. @param body [String, Hash, Array, nil] The request body that will eventually be converted to

a string; middlewares can be used to support more complex types.

@param headers [Hash, nil] unencoded HTTP header key/value pairs.

@return [Faraday::Response]

# File lib/faraday/connection.rb, line 439
def run_request(method, url, body, headers)
  unless METHODS.include?(method)
    raise ArgumentError, "unknown http method: #{method}"
  end

  request = build_request(method) do |req|
    req.options.proxy = proxy_for_request(url)
    req.url(url)                if url
    req.headers.update(headers) if headers
    req.body = body             if body
    yield(req) if block_given?
  end

  builder.build_response(self, request)
end

set_basic_auth (user, password)

# File lib/faraday/connection.rb, line 379
def set_basic_auth(user, password)
  header = Faraday::Utils.basic_header_from(user, password)
  headers[Faraday::Request::Authorization::KEY] = header
end

support_parallel? (adapter)

# File lib/faraday/connection.rb, line 560
def support_parallel?(adapter)
  adapter.respond_to?(:supports_parallel?) && adapter&.supports_parallel?
end

url_prefix= (url, encoder = nil)

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.

@param url [String, URI] @param encoder [Object]

@example

conn = Faraday::Connection.new { ... }
conn.url_prefix = "https://httpbingo.org/api"
conn.scheme      # => https
conn.path_prefix # => "/api"

conn.get("nigiri?page=2") # accesses https://httpbingo.org/api/nigiri

# File lib/faraday/connection.rb, line 364
def url_prefix=(url, encoder = nil)
  uri = @url_prefix = Utils.URI(url)
  self.path_prefix = uri.path

  params.merge_query(uri.query, encoder)
  uri.query = nil

  with_uri_credentials(uri) do |user, password|
    set_basic_auth(user, password)
    uri.user = uri.password = nil
  end

  @proxy = proxy_from_env(url) unless @manual_proxy
end

with_uri_credentials (uri) { |unescape, unescape| ... }

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

# File lib/faraday/connection.rb, line 516
def with_uri_credentials(uri)
  return unless uri.user && uri.password

  yield(Utils.unescape(uri.user), Utils.unescape(uri.password))
end