Class: Faraday::Connection
- Inherits:
-
Object
- Object
- Faraday::Connection
- Extended by:
- Forwardable
- Defined in:
- lib/faraday/connection.rb
Overview
Connection objects manage the default properties and the middleware stack for fulfilling an HTTP request.
Constant Summary collapse
- METHODS =
A Set of allowed HTTP verbs.
Set.new %i[get post put delete head patch options trace]
Instance Attribute Summary collapse
-
#builder ⇒ Faraday::Builder
readonly
Builder for this Connection.
-
#default_parallel_manager { ... } ⇒ Object?
private
Check if the adapter is parallel-capable.
-
#headers ⇒ Hash
Unencoded HTTP header key/value pairs.
-
#parallel_manager ⇒ Object
readonly
The parallel manager for this Connection.
-
#params ⇒ Hash
URI query unencoded key/value pairs.
-
#proxy ⇒ Hash
Proxy options.
-
#ssl ⇒ Hash
readonly
SSL options.
-
#url_prefix ⇒ String
A URI with the prefix used for all requests from this Connection.
Class Method Summary collapse
-
.delete(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a DELETE HTTP request without a body.
-
.get(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a GET HTTP request without a body.
-
.head(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a HEAD HTTP request without a body.
-
.post(url = nil, body = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a POST HTTP request with a body.
-
.put(url = nil, body = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a PUT HTTP request with a body.
-
.trace(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a TRACE HTTP request without a body.
Instance Method Summary collapse
-
#authorization(type, token) ⇒ void
Sets up a custom Authorization header.
-
#basic_auth(login, pass) ⇒ void
Sets up the Authorization header with these credentials, encoded with base64.
-
#build_exclusive_url(url = nil, params = nil, params_encoder = nil) ⇒ URI
Build an absolute URL based on url_prefix.
-
#build_request(method) {|Faraday::Request| ... } ⇒ Faraday::Request
Creates and configures the request object.
-
#build_url(url = nil, extra_params = nil) ⇒ Object
Takes a relative url for a request and combines it with the defaults set on the connection instance.
-
#close ⇒ Object
Closes the underlying resources and/or connections.
-
#dup ⇒ Faraday::Connection
private
Creates a duplicate of this Faraday::Connection.
- #find_default_proxy ⇒ Object
-
#in_parallel(manager = nil) { ... } ⇒ void
Sets up the parallel manager to make a set of requests.
-
#in_parallel? ⇒ Boolean
Determine if this Faraday::Connection can make parallel requests.
-
#initialize(url = nil, options = nil) {|self| ... } ⇒ Connection
constructor
Initializes a new Faraday::Connection.
- #initialize_proxy(url, options) ⇒ Object
- #options(*args) {|Faraday::Request| ... } ⇒ Faraday::Response
-
#path_prefix=(value) ⇒ String
Sets the path prefix and ensures that it always has a leading slash.
- #proxy_for_request(url) ⇒ Object
- #proxy_from_env(url) ⇒ Object
-
#run_request(method, url, body, headers) ⇒ Faraday::Response
Builds and runs the Faraday::Request.
- #set_authorization_header(header_type, *args) ⇒ Object
- #support_parallel?(adapter) ⇒ Boolean
-
#token_auth(token, options = nil) ⇒ void
Sets up the Authorization header with the given token.
-
#with_uri_credentials(uri) {|username, password| ... } ⇒ void
private
Yields username and password extracted from a URI if they both exist.
Constructor Details
#initialize(url = nil, options = nil) {|self| ... } ⇒ Connection
Initializes a new Faraday::Connection.
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 |
# File 'lib/faraday/connection.rb', line 62 def initialize(url = nil, = nil) = ConnectionOptions.from() if url.is_a?(Hash) || url.is_a?(ConnectionOptions) = .merge(url) url = .url end @parallel_manager = nil @headers = Utils::Headers.new @params = Utils::ParamsHash.new @options = .request @ssl = .ssl @default_parallel_manager = .parallel_manager @builder = .builder || begin # pass an empty block to Builder so it doesn't assume default middleware .new_builder(block_given? ? proc { |b| } : nil) end self.url_prefix = url || 'http:/' @params.update(.params) if .params @headers.update(.headers) if .headers initialize_proxy(url, ) yield(self) if block_given? @headers[:user_agent] ||= "Faraday v#{VERSION}" end |
Instance Attribute Details
#builder ⇒ Faraday::Builder (readonly)
Returns Builder for this Connection.
30 31 32 |
# File 'lib/faraday/connection.rb', line 30 def builder @builder end |
#default_parallel_manager { ... } ⇒ Object?
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Check if the adapter is parallel-capable.
346 347 348 349 350 351 352 353 354 355 356 |
# 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 |
#headers ⇒ Hash
Returns unencoded HTTP header key/value pairs.
23 24 25 |
# File 'lib/faraday/connection.rb', line 23 def headers @headers end |
#parallel_manager ⇒ Object (readonly)
Returns the parallel manager for this Connection.
36 37 38 |
# File 'lib/faraday/connection.rb', line 36 def parallel_manager @parallel_manager end |
#params ⇒ Hash
Returns URI query unencoded key/value pairs.
20 21 22 |
# File 'lib/faraday/connection.rb', line 20 def params @params end |
#proxy ⇒ Hash
Returns proxy options.
42 43 44 |
# File 'lib/faraday/connection.rb', line 42 def proxy @proxy end |
#ssl ⇒ Hash (readonly)
Returns SSL options.
33 34 35 |
# File 'lib/faraday/connection.rb', line 33 def ssl @ssl end |
#url_prefix ⇒ String
Returns a URI with the prefix used for all requests from this Connection. This includes a default host name, scheme, port, and path.
27 28 29 |
# File 'lib/faraday/connection.rb', line 27 def url_prefix @url_prefix end |
Class Method Details
.delete(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a DELETE HTTP request without a body.
|
# File 'lib/faraday/connection.rb', line 164
|
.get(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a GET HTTP request without a body.
|
# File 'lib/faraday/connection.rb', line 127
|
.head(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a HEAD HTTP request without a body.
|
# File 'lib/faraday/connection.rb', line 149
|
.post(url = nil, body = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a POST HTTP request with a body.
|
# File 'lib/faraday/connection.rb', line 230
|
.put(url = nil, body = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a PUT HTTP request with a body.
|
# File 'lib/faraday/connection.rb', line 252
|
.trace(url = nil, params = nil, headers = nil) {|Faraday::Request| ... } ⇒ Faraday::Response
Makes a TRACE HTTP request without a body.
|
# File 'lib/faraday/connection.rb', line 179
|
Instance Method Details
#authorization(type, token) ⇒ void
This method returns an undefined value.
Sets up a custom Authorization header.
336 337 338 |
# File 'lib/faraday/connection.rb', line 336 def (type, token) (:authorization, type, token) end |
#basic_auth(login, pass) ⇒ void
This method returns an undefined value.
Sets up the Authorization header with these credentials, encoded with base64.
297 298 299 |
# File 'lib/faraday/connection.rb', line 297 def basic_auth(login, pass) (:basic_auth, login, pass) end |
#build_exclusive_url(url = nil, params = nil, params_encoder = nil) ⇒ URI
Build an absolute URL based on url_prefix.
of the resulting url (default: nil).
520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 |
# File 'lib/faraday/connection.rb', line 520 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 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 || .params_encoder) end # rubocop:disable Style/SafeNavigation uri.query = nil if uri.query && uri.query.empty? # rubocop:enable Style/SafeNavigation uri end |
#build_request(method) {|Faraday::Request| ... } ⇒ Faraday::Request
Creates and configures the request object.
503 504 505 506 507 508 509 510 |
# File 'lib/faraday/connection.rb', line 503 def build_request(method) Request.create(method) do |req| req.params = params.dup req.headers = headers.dup req. = .dup yield(req) if block_given? end end |
#build_url(url = nil, extra_params = nil) ⇒ Object
Takes a relative url for a request and combines it with the defaults set on the connection instance.
457 458 459 460 461 462 463 464 465 466 467 468 469 470 |
# File 'lib/faraday/connection.rb', line 457 def build_url(url = nil, extra_params = nil) uri = build_exclusive_url(url) query_values = params.dup.merge_query(uri.query, .params_encoder) query_values.update(extra_params) if extra_params uri.query = if query_values.empty? nil else query_values.to_query(.params_encoder) end uri end |
#close ⇒ Object
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.
123 124 125 |
# File 'lib/faraday/connection.rb', line 123 def close app.close end |
#dup ⇒ Faraday::Connection
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Creates a duplicate of this Faraday::Connection.
543 544 545 546 547 548 549 550 |
# File 'lib/faraday/connection.rb', line 543 def dup self.class.new(build_exclusive_url, headers: headers.dup, params: params.dup, builder: builder.dup, ssl: ssl.dup, request: .dup) end |
#find_default_proxy ⇒ Object
599 600 601 602 603 604 605 |
# File 'lib/faraday/connection.rb', line 599 def find_default_proxy uri = ENV['http_proxy'] return unless uri && !uri.empty? uri = "http://#{uri}" unless uri.match?(/^http/i) uri end |
#in_parallel(manager = nil) { ... } ⇒ void
This method returns an undefined value.
Sets up the parallel manager to make a set of requests.
372 373 374 375 376 377 378 379 380 381 382 383 |
# 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 |
#in_parallel? ⇒ Boolean
Determine if this Faraday::Connection can make parallel requests.
361 362 363 |
# File 'lib/faraday/connection.rb', line 361 def in_parallel? !!@parallel_manager end |
#initialize_proxy(url, options) ⇒ Object
94 95 96 97 98 99 100 101 102 |
# File 'lib/faraday/connection.rb', line 94 def initialize_proxy(url, ) @manual_proxy = !!.proxy @proxy = if .proxy ProxyOptions.from(.proxy) else proxy_from_env(url) end end |
#options ⇒ Faraday::Response #options(url, params = nil, headers = nil) ⇒ Faraday::Response
220 221 222 223 224 225 226 227 228 |
# File 'lib/faraday/connection.rb', line 220 def (*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 |
#path_prefix=(value) ⇒ String
Sets the path prefix and ensures that it always has a leading slash.
432 433 434 435 436 437 |
# File 'lib/faraday/connection.rb', line 432 def path_prefix=(value) url_prefix.path = if value value = "/#{value}" unless value[0, 1] == '/' value end end |
#proxy_for_request(url) ⇒ Object
607 608 609 610 611 612 613 614 615 |
# File 'lib/faraday/connection.rb', line 607 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) ⇒ Object
574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 |
# File 'lib/faraday/connection.rb', line 574 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 |
#run_request(method, url, body, headers) ⇒ Faraday::Response
Builds and runs the Faraday::Request.
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 |
# File 'lib/faraday/connection.rb', line 481 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..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_authorization_header(header_type, *args) ⇒ Object
566 567 568 569 570 571 572 |
# File 'lib/faraday/connection.rb', line 566 def (header_type, *args) header = Faraday::Request .lookup_middleware(header_type) .header(*args) headers[Faraday::Request::Authorization::KEY] = header end |
#support_parallel?(adapter) ⇒ Boolean
617 618 619 |
# File 'lib/faraday/connection.rb', line 617 def support_parallel?(adapter) adapter&.respond_to?(:supports_parallel?) && adapter&.supports_parallel? end |
#token_auth(token, options = nil) ⇒ void
This method returns an undefined value.
Sets up the Authorization header with the given token.
314 315 316 |
# File 'lib/faraday/connection.rb', line 314 def token_auth(token, = nil) (:token_auth, token, ) end |
#with_uri_credentials(uri) {|username, password| ... } ⇒ void
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
This method returns an undefined value.
Yields username and password extracted from a URI if they both exist.
560 561 562 563 564 |
# File 'lib/faraday/connection.rb', line 560 def with_uri_credentials(uri) return unless uri.user && uri.password yield(Utils.unescape(uri.user), Utils.unescape(uri.password)) end |