Class: Faraday::Connection

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

Constant Summary collapse

METHODS = 
Set.new [:get, :post, :put, :delete, :head, :patch, :options]
METHODS_WITH_BODIES = 
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 - URI or String base URL to use as a prefix for all

requests (optional).

options - Hash of settings that will be applied to every request made

from this Connection (default: {}).
: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:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/faraday/connection.rb', line 32

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]     || {}

  @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) {
    uri = ENV['http_proxy']
    if uri && !uri.empty?
      uri = 'http://' + uri if uri !~ /^http/i
      uri
    end
  })

  yield self if block_given?

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

Instance Attribute Details

#builder ⇒ Object (readonly)

Returns the value of attribute builder.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

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.



144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/faraday/connection.rb', line 144

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

Returns the value of attribute headers.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def headers
  @headers
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def options
  @options
end

#parallel_manager ⇒ Object (readonly)

Returns the value of attribute parallel_manager.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def parallel_manager
  @parallel_manager
end

#params ⇒ Object

Returns the value of attribute params.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def params
  @params
end

#ssl ⇒ Object (readonly)

Returns the value of attribute ssl.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def ssl
  @ssl
end

#url_prefix ⇒ Object

Returns the value of attribute url_prefix.



13
14
15
 
# File 'lib/faraday/connection.rb', line 13

def url_prefix
  @url_prefix
end

Class Method Details

.URI(url) ⇒ Object

normalize URI() behavior across Ruby versions



192
193
194
195
196
197
198
199
200
 
# File 'lib/faraday/connection.rb', line 192

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.



90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/faraday/connection.rb', line 90

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 



133
134
135
136
 
# File 'lib/faraday/connection.rb', line 133

def authorization(type, token)
  headers[Faraday::Request::Authorization::KEY] =
    Faraday::Request::Authorization.header(type, token)
end

#basic_auth(login, pass) ⇒ Object 



123
124
125
126
 
# File 'lib/faraday/connection.rb', line 123

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.



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

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

Internal: Creates and configures the request object.

Returns the new Request.



259
260
261
262
263
264
265
266
 
# File 'lib/faraday/connection.rb', line 259

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



279
280
281
282
283
284
285
286
287
 
# File 'lib/faraday/connection.rb', line 279

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 



309
310
311
 
# File 'lib/faraday/connection.rb', line 309

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 



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/faraday/connection.rb', line 160

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

Returns:

  • (Boolean) 


156
157
158
 
# File 'lib/faraday/connection.rb', line 156

def in_parallel?
  !!@parallel_manager
end

#path_prefix=(value) ⇒ Object

Ensures that the path prefix always has a leading but no trailing slash



232
233
234
235
236
237
238
 
# File 'lib/faraday/connection.rb', line 232

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 



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/faraday/connection.rb', line 172

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

  @proxy = if arg.is_a? Hash
    uri = self.class.URI arg.fetch(:uri) { raise ArgumentError, "missing :uri" }
    arg.merge :uri => uri
  else
    uri = self.class.URI(arg)
    {:uri => uri}
  end

  with_uri_credentials(uri) do |user, password|
    @proxy[:user]     ||= user
    @proxy[:password] ||= password
  end

  @proxy
end

#run_request(method, url, body, headers) ⇒ Object 



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/faraday/connection.rb', line 240

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 



128
129
130
131
 
# File 'lib/faraday/connection.rb', line 128

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

#with_uri_credentials(uri) ⇒ Object

Internal: Yields username and password extracted from a URI if they both exist.



314
315
316
317
318
 
# File 'lib/faraday/connection.rb', line 314

def with_uri_credentials(uri)
  if uri.user and uri.password
    yield Utils.unescape(uri.user), Utils.unescape(uri.password)
  end
end