class Faraday::Connection

Constants

METHODS
METHODS_WITH_BODIES

Attributes

builder[R]
default_parallel_manager[W]
headers[R]
options[R]
parallel_manager[R]
params[R]
ssl[R]
url_prefix[R]

Public Class Methods

URI(url) click to toggle source

normalize URI() behavior across Ruby versions

# 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
new(url = nil, options = {}) { |self| ... } click to toggle source

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)
# 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/
      uri
    end
  })

  yield self if block_given?

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

Public Instance Methods

app() click to toggle source

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.

# 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) click to toggle source
# 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) click to toggle source
# File lib/faraday/connection.rb, line 123
def basic_auth(login, pass)
  headers[Faraday::Request::Authorization::KEY] =
    Faraday::Request::BasicAuthentication.header(login, pass)
end
build_exclusive_url(url, params = nil) click to toggle source

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.

# 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) { |req| ... } click to toggle source

Internal: Creates and configures the request object.

Returns the new Request.

# 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) click to toggle source

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
# 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
default_parallel_manager() { || ... } click to toggle source

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.

# 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
dup() click to toggle source
# 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
headers=(hash) click to toggle source

Public: Replace default request headers.

# File lib/faraday/connection.rb, line 76
def headers=(hash)
  @headers.replace hash
end
in_parallel(manager = nil) { || ... } click to toggle source
# 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?() click to toggle source
# File lib/faraday/connection.rb, line 156
def in_parallel?
  !!@parallel_manager
end
params=(hash) click to toggle source

Public: Replace default query parameters.

# File lib/faraday/connection.rb, line 71
def params=(hash)
  @params.replace hash
end
path_prefix=(value) click to toggle source

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

# 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) click to toggle source
# 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) { |req| ... } click to toggle source
# 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) click to toggle source
# 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
url_prefix=(url) click to toggle source

Parses the giving url with ::URI and stores the individual components in this connection. These components serve as defaults for requests made by this connection.

conn = Faraday::Connection.new { ... }
conn.url_prefix = "https://sushi.com/api"
conn.scheme      # => https
conn.path_prefix # => "/api"

conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
# File lib/faraday/connection.rb, line 216
def url_prefix=(url)
  uri = @url_prefix = self.class.URI(url)
  self.path_prefix = uri.path

  params.merge_query(uri.query)
  uri.query = nil

  with_uri_credentials(uri) do |user, password|
    basic_auth user, password
    uri.user = uri.password = nil
  end

  uri
end
with_uri_credentials(uri) { |unescape, unescape| ... } click to toggle source

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

# 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