Class: Faraday::Connection

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

Constant Summary

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

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

:url :params :headers :request :ssl

Yields:

  • (_self)

Yield Parameters:



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# File 'lib/faraday/connection.rb', line 22

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) { ENV['http_proxy'] })

  yield self if block_given?
end

Instance Attribute Details

- (Object) builder (readonly)

Returns the value of attribute builder



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

def builder
  @builder
end

- (Object) default_parallel_manager

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.



119
120
121
122
123
124
125
126
127
128
# File 'lib/faraday/connection.rb', line 119

def default_parallel_manager
  @default_parallel_manager ||= begin
    handler = @builder.handlers.find { |h|
      h.klass.respond_to?(:supports_parallel?) and h.klass.supports_parallel?
    }
    if handler then handler.klass.setup_parallel_manager
    elsif block_given? then yield
    end
  end
end

- (Object) headers

Returns the value of attribute headers



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

def headers
  @headers
end

- (Object) options (readonly)

Returns the value of attribute options



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

def options
  @options
end

- (Object) parallel_manager (readonly)

Returns the value of attribute parallel_manager



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

def parallel_manager
  @parallel_manager
end

- (Object) params

Returns the value of attribute params



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

def params
  @params
end

- (Object) ssl (readonly)

Returns the value of attribute ssl



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

def ssl
  @ssl
end

- (Object) url_prefix

Returns the value of attribute url_prefix



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

def url_prefix
  @url_prefix
end

Class Method Details

+ (Object) URI(url)

normalize URI() behavior across Ruby versions



158
159
160
161
162
# File 'lib/faraday/connection.rb', line 158

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

Instance Method Details

- (Object) app

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.



72
73
74
75
76
77
78
79
80
81
82
# File 'lib/faraday/connection.rb', line 72

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

- (Object) basic_auth(login, pass)



105
106
107
# File 'lib/faraday/connection.rb', line 105

def basic_auth(, pass)
  @builder.insert(0, Faraday::Request::BasicAuthentication, , pass)
end

- (Object) build_exclusive_url(url, params = nil)

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.



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

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

- (Object) build_request(method)

Internal: Creates and configures the request object.

Returns the new Request.



221
222
223
224
225
226
227
228
# File 'lib/faraday/connection.rb', line 221

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

- (Object) build_url(url, extra_params = nil)

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


241
242
243
244
245
246
247
248
249
# File 'lib/faraday/connection.rb', line 241

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

- (Object) dup



271
272
273
# File 'lib/faraday/connection.rb', line 271

def dup
  self.class.new(build_url(''), :headers => headers.dup, :params => params.dup, :builder => builder.dup, :ssl => ssl.dup)
end

- (Object) in_parallel(manager = nil)



134
135
136
137
138
139
140
141
142
143
144
# File 'lib/faraday/connection.rb', line 134

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

- (Boolean) in_parallel?

Returns:

  • (Boolean)


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

def in_parallel?
  !!@parallel_manager
end

- (Object) path_prefix=(value)

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



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

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

- (Object) proxy(arg = nil)



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

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

- (Object) run_request(method, url, body, headers)



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
# File 'lib/faraday/connection.rb', line 202

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

- (Object) token_auth(token, options = {})



109
110
111
# File 'lib/faraday/connection.rb', line 109

def token_auth(token, options = {})
  @builder.insert(0, Faraday::Request::TokenAuthentication, token, options)
end