class Faraday::Connection
Connection
objects manage the default properties and the middleware stack for fulfilling an HTTP request.
@example
conn = Faraday::Connection.new 'http://sushi.com' # GET http://sushi.com/nigiri conn.get 'nigiri' # => #<Faraday::Response>
Constants
- METHODS
A Set of allowed HTTP verbs.
- USER_AGENT
Attributes
@return [Faraday::RackBuilder] Builder for this Connection
.
Sets the default parallel manager for this connection.
@return [Hash] unencoded HTTP header key/value pairs.
@return [Object] the parallel manager for this Connection
.
@return [Hash] URI query unencoded key/value pairs.
@return [Hash] proxy options.
@return [Hash] SSL options.
@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
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 = options.merge(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
Sets up the Authorization header with these credentials, encoded with base64.
@param login [String] The authentication login. @param pass [String] The authentication password.
@example
conn.basic_auth 'Aladdin', 'open sesame' conn.headers['Authorization'] # => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
@return [void]
# File lib/faraday/connection.rb, line 299 def basic_auth(login, pass) warn <<~TEXT WARNING: `Faraday::Connection#basic_auth` is deprecated; it will be removed in version 2.0. While initializing your connection, use `#request(:basic_auth, ...)` instead. See https://lostisland.github.io/faraday/middleware/authentication for more usage info. TEXT set_authorization_header(:basic_auth, login, pass) end
Build an absolute URL based on url_prefix.
@param url [String, URI] @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 542 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 && base.path !~ %r{/$} base.path = "#{base.path}/" # ensure trailing slash end url = url && URI.parse(url.to_s).opaque ? url.to_s.gsub(':', '%3A') : url uri = url ? base + url : base 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
Creates and configures the request object.
@param method [Symbol]
@yield [Faraday::Request] if block given @return [Faraday::Request]
# File lib/faraday/connection.rb, line 525 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
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
# File lib/faraday/connection.rb, line 479 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
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
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 363 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
Creates a duplicate of this Faraday::Connection
.
@api private
@return [Faraday::Connection]
# File lib/faraday/connection.rb, line 564 def dup self.class.new(build_exclusive_url, headers: headers.dup, params: params.dup, builder: builder.dup, ssl: ssl.dup, request: options.dup) end
# File lib/faraday/connection.rb, line 620 def find_default_proxy uri = ENV['http_proxy'] return unless uri && !uri.empty? uri = "http://#{uri}" unless uri.match?(/^http/i) uri end
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
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 389 def in_parallel(manager = nil) @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&.run ensure @parallel_manager = nil end
Determine if this Faraday::Connection
can make parallel requests.
@return [Boolean]
# File lib/faraday/connection.rb, line 378 def in_parallel? !!@parallel_manager end
# 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
@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] 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.
@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.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
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
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 454 def path_prefix=(value) url_prefix.path = if value value = "/#{value}" unless value[0, 1] == '/' value end end
Sets the Hash proxy options.
@param new_value [Object]
# File lib/faraday/connection.rb, line 405 def proxy=(new_value) @manual_proxy = true @proxy = new_value ? ProxyOptions.from(new_value) : nil end
# File lib/faraday/connection.rb, line 628 def proxy_for_request(url) return proxy if @manual_proxy if url && Utils.URI(url).absolute? proxy_from_env(url) else proxy end end
# File lib/faraday/connection.rb, line 595 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 = 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 else warn 'no_proxy is unsupported' if ENV['no_proxy'] || ENV['NO_PROXY'] uri = find_default_proxy end ProxyOptions.from(uri) if uri end
Builds and runs the Faraday::Request
.
@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.
@return [Faraday::Response]
# File lib/faraday/connection.rb, line 503 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
# File lib/faraday/connection.rb, line 443 def set_basic_auth(user, password) header = Faraday::Request::BasicAuthentication.header(user, password) headers[Faraday::Request::Authorization::KEY] = header end
# File lib/faraday/connection.rb, line 638 def support_parallel?(adapter) adapter&.respond_to?(:supports_parallel?) && adapter&.supports_parallel? end
Sets up the Authorization header with the given token.
@param token [String] @param options [Hash] extra token options.
@example
conn.token_auth 'abcdef', foo: 'bar' conn.headers['Authorization'] # => "Token token=\"abcdef\", foo=\"bar\""
@return [void]
# File lib/faraday/connection.rb, line 321 def token_auth(token, options = nil) warn <<~TEXT WARNING: `Faraday::Connection#token_auth` is deprecated; it will be removed in version 2.0. While initializing your connection, use `#request(:token_auth, ...)` instead. See https://lostisland.github.io/faraday/middleware/authentication for more usage info. TEXT set_authorization_header(:token_auth, token, options) end
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://sushi.com/api" conn.scheme # => https conn.path_prefix # => "/api" conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
# File lib/faraday/connection.rb, line 428 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
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 581 def with_uri_credentials(uri) return unless uri.user && uri.password yield(Utils.unescape(uri.user), Utils.unescape(uri.password)) end