Class: Faraday::Connection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/faraday/connection.rb

Overview

Public: Connection objects manage the default properties and the middleware stack for fulfilling an HTTP request.

Examples

conn = Faraday::Connection.new 'http://sushi.com'

# GET http://sushi.com/nigiri
conn.get 'nigiri'# => #<Faraday::Response>

Constant Summary collapse

METHODS =

A Set of allowed HTTP verbs.

Set.new [:get, :post, :put, :delete, :head, :patch, :options]

Instance Attribute Summary collapse

Instance Method Summary collapse

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)

Yields:

  • (_self)

Yield Parameters:


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, 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.new { |b| } : nil)
  end

  self.url_prefix = url || 'http:/'

  @params.update(options.params)   if options.params
  @headers.update(options.headers) if options.headers

  @manual_proxy = !!options.proxy
  @proxy = options.proxy ? ProxyOptions.from(options.proxy) : proxy_from_env(url)
  @temp_proxy = @proxy

  yield(self) if block_given?

  @headers[:user_agent] ||= "Faraday v#{VERSION}"
end

Instance Attribute Details

#builderObject (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_managerObject

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

#headersObject

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

#optionsObject (readonly)

Public: Returns a Hash of the request options.


31
32
33
# File 'lib/faraday/connection.rb', line 31

def options
  @options
end

#parallel_managerObject (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

#paramsObject

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

#sslObject (readonly)

Public: Returns a Hash of the SSL options.


34
35
36
# File 'lib/faraday/connection.rb', line 34

def ssl
  @ssl
end

#url_prefixObject

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 authorization(type, token)
  set_authorization_header(: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(, pass)
  set_authorization_header(:basic_auth, , 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 || options.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.options = self.options
    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, options.params_encoder)
  query_values.update extra_params if extra_params
  uri.query = query_values.empty? ? nil : query_values.to_query(options.params_encoder)

  uri
end

#dupObject

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 => options.dup)
end

#find_default_proxyObject


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.

Returns:

  • (Boolean)

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.options = req.options.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 set_authorization_header(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, options = nil)
  set_authorization_header(:token_auth, token, options)
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