Class: Faraday::Connection

Inherits:
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]
METHODS_WITH_BODIES =

A Set of HTTP verbs that typically send a body. If no body is set for these requests, the Content-Length header is set to 0.

Set.new [:post, :put, :patch, :options]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url = nil, options = {}) {|_self| ... } ⇒ Connection

Public: Initializes a new Faraday::Connection.

url - The optional String base URL to use as a prefix for all

requests.  Can also be the options Hash.

options - The optional Hash used to configure this Faraday::Connection.

Any of these values will be set on every request made, unless
overridden for a specific request.
:url     - String base URL.
: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   - Hash of Proxy options.

Yields:

  • (_self)

Yield Parameters:



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
 
# File 'lib/faraday/connection.rb', line 66

def initialize(url = nil, options = {})
  if url.is_a?(Hash)
    options = url
    url     = options[:url]
  end
  @headers = Utils::Headers.new
  @params  = Utils::ParamsHash.new
  @options = options[:request] || {}
  @ssl     = options[:ssl]     || {}
  adapter  = options[:adapter]

  @parallel_manager = nil
  @default_parallel_manager = options[:parallel_manager]

  @builder = options[:builder] || begin
    # pass an empty block to Builder so it doesn't assume default middleware
    block = block_given?? Proc.new {|b| } : nil
    Builder.new(&block)
  end

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

  @params.update options[:params]   if options[:params]
  @headers.update options[:headers] if options[:headers]

  @proxy = nil
  proxy(options.fetch(:proxy) { ENV['http_proxy'] })

  yield self if block_given?

  if adapter
    self.adapter = adapter
  end
end

Instance Attribute Details

#builder ⇒ Object (readonly)

Public: Returns the Faraday::Builder for this Connection.



39
40
41
 
# File 'lib/faraday/connection.rb', line 39

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.



272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/faraday/connection.rb', line 272

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 then handler.klass.setup_parallel_manager
    elsif block_given? then yield
    end
  end
end

#headers ⇒ Object

Public: Returns a Hash of unencoded HTTP header key/value pairs.



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

def headers
  @headers
end

#options ⇒ Object (readonly)

Public: Returns a Hash of the request options.



42
43
44
 
# File 'lib/faraday/connection.rb', line 42

def options
  @options
end

#parallel_manager ⇒ Object (readonly)

Public: Returns the parallel manager for this Connection.



48
49
50
 
# File 'lib/faraday/connection.rb', line 48

def parallel_manager
  @parallel_manager
end

#params ⇒ Object

Public: Returns a Hash of URI query unencoded key/value pairs.



29
30
31
 
# File 'lib/faraday/connection.rb', line 29

def params
  @params
end

#ssl ⇒ Object (readonly)

Public: Returns a Hash of the SSL options.



45
46
47
 
# File 'lib/faraday/connection.rb', line 45

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.



36
37
38
 
# File 'lib/faraday/connection.rb', line 36

def url_prefix
  @url_prefix
end

Class Method Details

.URI(url) ⇒ Object

Public: Normalize URI() behavior across Ruby versions

url - A String or URI.

Returns a parsed URI.



326
327
328
329
330
331
332
333
334
 
# File 'lib/faraday/connection.rb', line 326

def self.URI(url)
  if url.respond_to?(:host)
    url
  elsif url.respond_to?(:to_str)
    Kernel.URI(url)
  else
    raise ArgumentError, "bad argument (expected URI object or URI string)"
  end
end

Instance Method Details

#app ⇒ Object

The “rack app” wrapped in middleware. All requests are sent here.

The builder is responsible for creating the app object. After this, the builder gets locked to ensure no further modifications are made to the middleware stack.

Returns an object that responds to ‘call` and returns a Response.



123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/faraday/connection.rb', line 123

def app
  @app ||= begin
    builder.lock!
    builder.to_app(lambda { |env|
      # the inner app that creates and returns the Response object
      response = Response.new
      response.finish(env) unless env[:parallel_manager]
      env[:response] = response
    })
  end
end

#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.



261
262
263
264
 
# File 'lib/faraday/connection.rb', line 261

def authorization(type, token)
  headers[Faraday::Request::Authorization::KEY] =
    Faraday::Request::Authorization.header(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.



220
221
222
223
 
# File 'lib/faraday/connection.rb', line 220

def basic_auth(, pass)
  headers[Faraday::Request::Authorization::KEY] =
    Faraday::Request::BasicAuthentication.header(, pass)
end

#build_exclusive_url(url, params = 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.



448
449
450
451
452
453
454
455
456
457
458
459
 
# File 'lib/faraday/connection.rb', line 448

def build_exclusive_url(url, params = 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 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.



411
412
413
414
415
416
417
418
 
# File 'lib/faraday/connection.rb', line 411

def build_request(method)
  Request.create(method) do |req|
    req.params  = self.params.dup
    req.headers = self.headers.dup
    req.options = self.options.merge(:proxy => self.proxy)
    yield req if block_given?
  end
end

#build_url(url, extra_params = nil) ⇒ Object

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



431
432
433
434
435
436
437
438
439
 
# File 'lib/faraday/connection.rb', line 431

def build_url(url, extra_params = nil)
  uri = build_exclusive_url(url)

  query_values = self.params.dup.merge_query(uri.query)
  query_values.update extra_params if extra_params
  uri.query = query_values.empty? ? nil : query_values.to_query

  uri
end

#dup ⇒ Object

Internal: Creates a duplicate of this Faraday::Connection.

Returns a Faraday::Connection.



464
465
466
 
# File 'lib/faraday/connection.rb', line 464

def dup
  self.class.new(build_url(''), :headers => headers.dup, :params => params.dup, :builder => builder.dup, :ssl => ssl.dup)
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.



297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/faraday/connection.rb', line 297

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) 


287
288
289
 
# File 'lib/faraday/connection.rb', line 287

def in_parallel?
  !!@parallel_manager
end

#path_prefix=(value) ⇒ Object

Public: Sets the path prefix and ensures that it always has a leading but no trailing slash.

value - A String.

Returns the new String path prefix.



376
377
378
379
380
381
382
 
# File 'lib/faraday/connection.rb', line 376

def path_prefix=(value)
  url_prefix.path = if value
    value = value.chomp '/'
    value = '/' + value unless value[0,1] == '/'
    value
  end
end

#proxy(arg = nil) ⇒ Object

Public: Gets or Sets the Hash proxy options.



310
311
312
313
314
315
316
317
318
319
 
# File 'lib/faraday/connection.rb', line 310

def proxy(arg = nil)
  return @proxy if arg.nil?

  @proxy = if arg.is_a? Hash
    uri = arg.fetch(:uri) { raise ArgumentError, "no :uri option" }
    arg.merge :uri => self.class.URI(uri)
  else
    {:uri => self.class.URI(arg)}
  end
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 String body headers - Hash of unencoded HTTP header key/value pairs.

Returns a Faraday::Response.



392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/faraday/connection.rb', line 392

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

  env = request.to_env(self)
  self.app.call(env)
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.



238
239
240
241
 
# File 'lib/faraday/connection.rb', line 238

def token_auth(token, options = nil)
  headers[Faraday::Request::Authorization::KEY] =
    Faraday::Request::TokenAuthentication.header(token, options)
end