Class: Fog::Core::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/fog/core/connection.rb

Overview

Fog::Core::Connection is a generic class to contain a HTTP link to an API.

It is intended to be subclassed by providers who can then add their own modifications such as authentication or response object.

Constant Summary collapse

@@user_agents = 
[]

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url, persistent = false, params = {}) ⇒ Connection

Prepares the connection and sets defaults for any future requests.

Parameters:

  • url (String) —

    The destination URL

  • persistent (Boolean) (defaults to: false)
  • params (Hash) (defaults to: {})

Options Hash (params):

  • :body (String) —

    Default text to be sent over a socket. Only used if :body absent in Connection#request params

  • :headers (Hash<Symbol, String>) —

    The default headers to supply in a request. Only used if params is not supplied to Connection#request

  • :host (String) —

    The destination host’s reachable DNS name or IP, in the form of a String

  • :path (String) —

    Default path; appears after ‘scheme://host:port/’. Only used if params is not supplied to Connection#request

  • :path_prefix (String) —

    Sticky version of the “path” arg. :XSpath_prefix => “foo/bar” with a request with :path => “blech” sends a request to path “foo/bar/blech”

  • :port (Fixnum) —

    The port on which to connect, to the destination host

  • :query (Hash) —

    Default query; appended to the ‘scheme://host:port/path/’ in the form of ‘?key=value’. Will only be used if params is not supplied to Connection#request

  • :scheme (String) —

    The protocol; ‘https’ causes OpenSSL to be used

  • :proxy (String) —

    Proxy server; e.g. ‘myproxy.com:8888’

  • :retry_limit (Fixnum) —

    Set how many times we’ll retry a failed request. (Default 4)

  • :instrumentor (Class) —

    Responds to #instrument as in ActiveSupport::Notifications

  • :instrumentor_name (String) —

    Name prefix for #instrument events. Defaults to ‘excon’



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/fog/core/connection.rb', line 46

def initialize(url, persistent = false, params = {})
  if params[:path_prefix]
    if params[:path]
      raise ArgumentError, "optional arg 'path' is invalid when 'path_prefix' is provided"
    end

    @path_prefix = params.delete(:path_prefix)
  end

  params[:debug_response] = true unless params.key?(:debug_response)
  params[:headers] ||= {}
  params.merge!(:persistent => params.fetch(:persistent, persistent))
  params[:headers]["User-Agent"] ||= user_agent
  @excon = Excon.new(url, params)
end

Class Method Details

.add_user_agent(str) ⇒ Object 



13
14
15
16
17
18
19
 
# File 'lib/fog/core/connection.rb', line 13

def add_user_agent(str)
  if /\S+\/[\d|.]+/.match(str)
    @@user_agents << str
  else
    raise "User Agent must be in <app name>/<app version> notation."
  end
end

.user_agents ⇒ Object 



21
22
23
24
25
26
 
# File 'lib/fog/core/connection.rb', line 21

def user_agents
  agents = @@user_agents.dup
  agents << "fog/#{Fog::VERSION}" if defined?(Fog::VERSION)
  agents << "fog-core/#{Fog::Core::VERSION}"
  agents.uniq.compact.join(" ")
end

Instance Method Details

#request(params, &block) ⇒ Excon::Response Also known as: original_request

Makes a request using the connection using Excon

Parameters:

  • params (Hash)

Options Hash (params):

  • :body (String) —

    text to be sent over a socket

  • :headers (Hash<Symbol, String>) —

    The default headers to supply in a request

  • :host (String) —

    The destination host’s reachable DNS name or IP, in the form of a String

  • :path (String) —

    appears after ‘scheme://host:port/’

  • :port (Fixnum) —

    The port on which to connect, to the destination host

  • :query (Hash) —

    appended to the ‘scheme://host:port/path/’ in the form of ‘?key=value’

  • :scheme (String) —

    The protocol; ‘https’ causes OpenSSL to be used

  • :response_block (Proc)

Returns:

  • (Excon::Response)

Raises:

  • (Excon::Errors::StubNotFound)
  • (Excon::Errors::Timeout)
  • (Excon::Errors::SocketError) 


80
81
82
 
# File 'lib/fog/core/connection.rb', line 80

def request(params, &block)
  @excon.request(handle_path_prefix_for(params), &block)
end

#reset ⇒ Object

Closes the connection



92
93
94
 
# File 'lib/fog/core/connection.rb', line 92

def reset
  @excon.reset
end