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.
-
#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)
57 58 59 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 93 94 95 96 97 98 99 100 101 102 103 |
# File 'lib/faraday/connection.rb', line 57 def initialize(url = nil, = nil) = ConnectionOptions.from() if url.is_a?(Hash) = .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 @proxy = nil proxy(.fetch(:proxy) { uri = nil if URI.parse("").respond_to?(:find_proxy) case url when String uri = URI.parse(url).find_proxy when URI uri = url.find_proxy when nil uri = find_default_proxy end else uri = find_default_proxy end uri }) 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.
253 254 255 256 257 258 259 260 261 262 263 264 265 |
# File 'lib/faraday/connection.rb', line 253 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.
243 244 245 |
# File 'lib/faraday/connection.rb', line 243 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.
204 205 206 |
# File 'lib/faraday/connection.rb', line 204 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.
408 409 410 411 412 413 414 415 416 417 418 419 |
# File 'lib/faraday/connection.rb', line 408 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.
392 393 394 395 396 397 398 399 |
# File 'lib/faraday/connection.rb', line 392 def build_request(method) Request.create(method) do |req| req.params = self.params.dup req.headers = self.headers.dup req. = self..merge(:proxy => self.proxy) 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
356 357 358 359 360 361 362 363 364 |
# File 'lib/faraday/connection.rb', line 356 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.
424 425 426 427 428 429 430 431 |
# File 'lib/faraday/connection.rb', line 424 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
446 447 448 449 450 451 452 453 |
# File 'lib/faraday/connection.rb', line 446 def find_default_proxy warn 'no_proxy is unsupported' if ENV['no_proxy'] || ENV['NO_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.
280 281 282 283 284 285 286 287 288 289 290 |
# File 'lib/faraday/connection.rb', line 280 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.
270 271 272 |
# File 'lib/faraday/connection.rb', line 270 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.
338 339 340 341 342 343 |
# File 'lib/faraday/connection.rb', line 338 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.
293 294 295 296 |
# File 'lib/faraday/connection.rb', line 293 def proxy(arg = nil) return @proxy if arg.nil? @proxy = ProxyOptions.from(arg) 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.
374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
# File 'lib/faraday/connection.rb', line 374 def run_request(method, url, body, headers) if !METHODS.include?(method) raise ArgumentError, "unknown http method: #{method}" end request = build_request(method) do |req| 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
440 441 442 443 444 |
# File 'lib/faraday/connection.rb', line 440 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.
221 222 223 |
# File 'lib/faraday/connection.rb', line 221 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.
434 435 436 437 438 |
# File 'lib/faraday/connection.rb', line 434 def with_uri_credentials(uri) if uri.user and uri.password yield(Utils.unescape(uri.user), Utils.unescape(uri.password)) end end |