Class: Faraday::Connection
- Inherits:
-
Object
- Object
- Faraday::Connection
- Extended by:
- Forwardable
- Defined in:
- lib/faraday/connection.rb
Overview
Constant Summary collapse
- METHODS =
A Set of allowed HTTP verbs.
Set.new [:get, :post, :put, :delete, :head, :patch, :options]
Instance Attribute Summary collapse
-
#builder ⇒ Object
readonly
Public: Returns the Faraday::Builder for this Connection.
-
#default_parallel_manager ⇒ Object
Internal: Traverse the middleware stack in search of a parallel-capable adapter.
-
#headers ⇒ Object
Public: Returns a Hash of unencoded HTTP header key/value pairs.
-
#options ⇒ Object
readonly
Public: Returns a Hash of the request options.
-
#parallel_manager ⇒ Object
readonly
Public: Returns the parallel manager for this Connection.
-
#params ⇒ Object
Public: Returns a Hash of URI query unencoded key/value pairs.
-
#ssl ⇒ Object
readonly
Public: Returns a Hash of the SSL options.
-
#url_prefix ⇒ Object
Public: Returns a URI with the prefix used for all requests from this Connection.
Instance Method Summary collapse
-
#authorization(type, token) ⇒ Object
Public: Sets up a custom Authorization header.
-
#basic_auth(login, pass) ⇒ Object
Public: Sets up the Authorization header with these credentials, encoded with base64.
-
#build_exclusive_url(url = nil, params = nil, params_encoder = nil) ⇒ Object
Internal: Build an absolute URL based on url_prefix.
-
#build_request(method) ⇒ Object
Creates and configures the request object.
-
#build_url(url = nil, extra_params = nil) ⇒ Object
Public: Takes a relative url for a request and combines it with the defaults set on the connection instance.
-
#dup ⇒ Object
Internal: Creates a duplicate of this Faraday::Connection.
- #find_default_proxy ⇒ Object
-
#in_parallel(manager = nil) ⇒ Object
Public: Sets up the parallel manager to make a set of requests.
-
#in_parallel? ⇒ Boolean
Public: Determine if this Faraday::Connection can make parallel requests.
-
#initialize(url = nil, options = nil) {|_self| ... } ⇒ Connection
constructor
Public: Initializes a new Faraday::Connection.
-
#path_prefix=(value) ⇒ Object
Public: Sets the path prefix and ensures that it always has a leading slash.
-
#proxy(arg = nil) ⇒ Object
Public: Gets or Sets the Hash proxy options.
-
#proxy=(new_value) ⇒ Object
Public: Sets the Hash proxy options.
- #proxy_for_request(url) ⇒ Object
- #proxy_from_env(url) ⇒ Object
-
#run_request(method, url, body, headers) ⇒ Object
Builds and runs the Faraday::Request.
- #set_authorization_header(header_type, *args) ⇒ Object
-
#token_auth(token, options = nil) ⇒ Object
Public: Sets up the Authorization header with the given token.
-
#with_uri_credentials(uri) ⇒ Object
Internal: Yields username and password extracted from a URI if they both exist.
Constructor Details
#initialize(url = nil, options = nil) {|_self| ... } ⇒ Connection
Public: Initializes a new Faraday::Connection.
url - 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)
60 61 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 60 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.new { |b| } : nil) end self.url_prefix = url || 'http:/' @params.update(.params) if .params @headers.update(.headers) if .headers @manual_proxy = !!.proxy @proxy = .proxy ? ProxyOptions.from(.proxy) : proxy_from_env(url) @temp_proxy = @proxy yield(self) if block_given? @headers[:user_agent] ||= "Faraday v#{VERSION}" end |
Instance Attribute Details
#builder ⇒ Object (readonly)
Public: Returns the Faraday::Builder for this Connection.
28 29 30 |
# File 'lib/faraday/connection.rb', line 28 def builder @builder end |
#default_parallel_manager ⇒ Object
Internal: Traverse the middleware stack in search of a parallel-capable adapter.
Yields in case of not found.
Returns a parallel manager or nil if not found.
242 243 244 245 246 247 248 249 250 251 252 253 254 |
# File 'lib/faraday/connection.rb', line 242 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 if handler handler.klass.setup_parallel_manager elsif block_given? yield end end end |
#headers ⇒ Object
Public: Returns a Hash of unencoded HTTP header key/value pairs.
21 22 23 |
# File 'lib/faraday/connection.rb', line 21 def headers @headers end |
#options ⇒ Object (readonly)
Public: Returns a Hash of the request options.
31 32 33 |
# File 'lib/faraday/connection.rb', line 31 def @options end |
#parallel_manager ⇒ Object (readonly)
Public: Returns the parallel manager for this Connection.
37 38 39 |
# File 'lib/faraday/connection.rb', line 37 def parallel_manager @parallel_manager end |
#params ⇒ Object
Public: Returns a Hash of URI query unencoded key/value pairs.
18 19 20 |
# File 'lib/faraday/connection.rb', line 18 def params @params end |
#ssl ⇒ Object (readonly)
Public: Returns a Hash of the SSL options.
34 35 36 |
# File 'lib/faraday/connection.rb', line 34 def ssl @ssl end |
#url_prefix ⇒ Object
Public: Returns a URI with the prefix used for all requests from this Connection. This includes a default host name, scheme, port, and path.
25 26 27 |
# File 'lib/faraday/connection.rb', line 25 def url_prefix @url_prefix end |
Instance Method Details
#authorization(type, token) ⇒ Object
Public: 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.
Examples
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.headers['Authorization']
# => "Token token=\"abcdef\",
foo=\"bar\""
Returns nothing.
232 233 234 |
# File 'lib/faraday/connection.rb', line 232 def (type, token) (:authorization, type, token) end |
#basic_auth(login, pass) ⇒ Object
Public: Sets up the Authorization header with these credentials, encoded with base64.
login - The authentication login. pass - The authentication password.
Examples
conn.basic_auth 'Aladdin', 'open sesame'
conn.headers['Authorization']
# => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
Returns nothing.
193 194 195 |
# File 'lib/faraday/connection.rb', line 193 def basic_auth(login, pass) (:basic_auth, login, pass) end |
#build_exclusive_url(url = nil, params = nil, params_encoder = nil) ⇒ Object
Internal: 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
of the resulting url (default: nil).
Returns the resulting URI instance.
409 410 411 412 413 414 415 416 417 418 419 420 |
# File 'lib/faraday/connection.rb', line 409 def build_exclusive_url(url = nil, params = nil, params_encoder = nil) url = nil if url.respond_to?(:empty?) and url.empty? base = url_prefix if url and base.path and base.path !~ /\/$/ base = base.dup base.path = base.path + '/' # ensure trailing slash end uri = url ? base + url : base uri.query = params.to_query(params_encoder || .params_encoder) if params uri.query = nil if uri.query and uri.query.empty? uri end |
#build_request(method) ⇒ Object
Creates and configures the request object.
Returns the new Request.
393 394 395 396 397 398 399 400 |
# File 'lib/faraday/connection.rb', line 393 def build_request(method) Request.create(method) do |req| req.params = self.params.dup req.headers = self.headers.dup req. = self. yield(req) if block_given? end end |
#build_url(url = nil, extra_params = nil) ⇒ Object
Public: Takes a relative url for a request and combines it with the defaults set on the connection instance.
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
353 354 355 356 357 358 359 360 361 |
# File 'lib/faraday/connection.rb', line 353 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 = query_values.empty? ? nil : query_values.to_query(.params_encoder) uri end |
#dup ⇒ Object
Internal: Creates a duplicate of this Faraday::Connection.
Returns a Faraday::Connection.
425 426 427 428 429 430 431 432 |
# File 'lib/faraday/connection.rb', line 425 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
467 468 469 470 471 472 473 |
# File 'lib/faraday/connection.rb', line 467 def find_default_proxy uri = ENV['http_proxy'] if uri && !uri.empty? uri = 'http://' + uri if uri !~ /^http/i uri end end |
#in_parallel(manager = nil) ⇒ Object
Public: Sets up the parallel manager to make a set of requests.
manager - The parallel manager that this Connection’s Adapter uses.
Yields a block to execute multiple requests. Returns nothing.
269 270 271 272 273 274 275 276 277 278 279 |
# File 'lib/faraday/connection.rb', line 269 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") nil } yield @parallel_manager && @parallel_manager.run ensure @parallel_manager = nil end |
#in_parallel? ⇒ Boolean
Public: Determine if this Faraday::Connection can make parallel requests.
Returns true or false.
259 260 261 |
# File 'lib/faraday/connection.rb', line 259 def in_parallel? !!@parallel_manager end |
#path_prefix=(value) ⇒ Object
Public: Sets the path prefix and ensures that it always has a leading slash.
value - A String.
Returns the new String path prefix.
335 336 337 338 339 340 |
# File 'lib/faraday/connection.rb', line 335 def path_prefix=(value) url_prefix.path = if value value = '/' + value unless value[0,1] == '/' value end end |
#proxy(arg = nil) ⇒ Object
Public: Gets or Sets the Hash proxy options.
282 283 284 285 286 287 |
# File 'lib/faraday/connection.rb', line 282 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 |
#proxy=(new_value) ⇒ Object
Public: Sets the Hash proxy options.
290 291 292 293 |
# File 'lib/faraday/connection.rb', line 290 def proxy=(new_value) @manual_proxy = true @proxy = new_value ? ProxyOptions.from(new_value) : nil end |
#proxy_for_request(url) ⇒ Object
475 476 477 478 479 480 481 482 |
# File 'lib/faraday/connection.rb', line 475 def proxy_for_request(url) return self.proxy if @manual_proxy if url && Utils.URI(url).absolute? proxy_from_env(url) else self.proxy end end |
#proxy_from_env(url) ⇒ Object
447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 |
# File 'lib/faraday/connection.rb', line 447 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 |
#run_request(method, url, body, headers) ⇒ Object
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.
Returns a Faraday::Response.
371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 |
# File 'lib/faraday/connection.rb', line 371 def run_request(method, url, body, headers) if !METHODS.include?(method) raise ArgumentError, "unknown http method: #{method}" end # Resets temp_proxy @temp_proxy = proxy_for_request(url) request = build_request(method) do |req| req. = req..merge(:proxy => @temp_proxy) 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
441 442 443 444 445 |
# File 'lib/faraday/connection.rb', line 441 def (header_type, *args) header = Faraday::Request.lookup_middleware(header_type). header(*args) headers[Faraday::Request::Authorization::KEY] = header end |
#token_auth(token, options = nil) ⇒ Object
Public: Sets up the Authorization header with the given token.
token - The String token. options - Optional Hash of extra token options.
Examples
conn.token_auth 'abcdef', :foo => 'bar'
conn.headers['Authorization']
# => "Token token=\"abcdef\",
foo=\"bar\""
Returns nothing.
210 211 212 |
# File 'lib/faraday/connection.rb', line 210 def token_auth(token, = nil) (:token_auth, token, ) end |
#with_uri_credentials(uri) ⇒ Object
Internal: Yields username and password extracted from a URI if they both exist.
435 436 437 438 439 |
# File 'lib/faraday/connection.rb', line 435 def with_uri_credentials(uri) if uri.user and uri.password yield(Utils.unescape(uri.user), Utils.unescape(uri.password)) end end |