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.
Attributes
@return [Faraday::Builder] 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
Source
# File lib/faraday/connection.rb, line 62 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 @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] ||= "Faraday v#{VERSION}" end
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
Public Instance Methods
Source
# File lib/faraday/connection.rb, line 297 def basic_auth(login, pass) set_authorization_header(:basic_auth, login, pass) end
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]
Source
# File lib/faraday/connection.rb, line 518 def build_exclusive_url(url = nil, params = nil, params_encoder = nil) url = nil if url.respond_to?(:empty?) && url.empty? base = url_prefix if url && base.path && base.path !~ %r{/$} base = base.dup base.path = base.path + '/' # ensure trailing slash end 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
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]
Source
# File lib/faraday/connection.rb, line 501 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
Creates and configures the request object.
@param method [Symbol]
@yield [Faraday::Request] if block given @return [Faraday::Request]
Source
# File lib/faraday/connection.rb, line 455 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
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
Source
# File lib/faraday/connection.rb, line 123 def close app.close 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.
Source
# File lib/faraday/connection.rb, line 346 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
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
Source
# File lib/faraday/connection.rb, line 540 def dup self.class.new(build_exclusive_url, headers: headers.dup, params: params.dup, builder: builder.dup, ssl: ssl.dup, request: options.dup) end
Creates a duplicate of this Faraday::Connection
.
@api private
@return [Faraday::Connection]
Source
# File lib/faraday/connection.rb, line 592 def find_default_proxy uri = ENV['http_proxy'] return unless uri && !uri.empty? uri = 'http://' + uri if uri !~ /^http/i uri end
Source
# File lib/faraday/connection.rb, line 112 def headers=(hash) @headers.replace hash end
Sets the Hash of unencoded HTTP header key/value pairs. @param hash [Hash]
Source
# File lib/faraday/connection.rb, line 372 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
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]
Source
# File lib/faraday/connection.rb, line 361 def in_parallel? !!@parallel_manager end
Determine if this Faraday::Connection
can make parallel requests.
@return [Boolean]
Source
# File lib/faraday/connection.rb, line 94 def initialize_proxy(url, options) @manual_proxy = !!options.proxy @proxy = if options.proxy ProxyOptions.from(options.proxy) else proxy_from_env(url) end end
Source
# File lib/faraday/connection.rb, line 220 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
@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]
Source
# File lib/faraday/connection.rb, line 106 def params=(hash) @params.replace hash end
Sets the Hash of URI query unencoded key/value pairs. @param hash [Hash]
Source
# File lib/faraday/connection.rb, line 430 def path_prefix=(value) url_prefix.path = if value value = '/' + value unless value[0, 1] == '/' value end end
Sets the path prefix and ensures that it always has a leading slash.
@param value [String]
@return [String] the new path prefix
Source
# File lib/faraday/connection.rb, line 388 def proxy=(new_value) @manual_proxy = true @proxy = new_value ? ProxyOptions.from(new_value) : nil end
Sets the Hash proxy options.
@param new_value [Object]
Source
# File lib/faraday/connection.rb, line 600 def proxy_for_request(url) return proxy if @manual_proxy if url && Utils.URI(url).absolute? proxy_from_env(url) else proxy end end
Source
# File lib/faraday/connection.rb, line 571 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 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
Source
# File lib/faraday/connection.rb, line 479 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
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]
Source
# File lib/faraday/connection.rb, line 610 def support_parallel?(adapter) adapter&.respond_to?(:supports_parallel?) && adapter&.supports_parallel? end
Source
# File lib/faraday/connection.rb, line 314 def token_auth(token, options = nil) set_authorization_header(:token_auth, token, options) 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]
Source
# File lib/faraday/connection.rb, line 411 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| basic_auth user, password uri.user = uri.password = nil end 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
Source
# File lib/faraday/connection.rb, line 557 def with_uri_credentials(uri) return unless uri.user && uri.password yield(Utils.unescape(uri.user), Utils.unescape(uri.password)) 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