Class Rightscale::HttpConnection
In: lib/right_http_connection.rb
Parent: Object

HttpConnection maintains a persistent HTTP connection to a remote server. Each instance maintains its own unique connection to the HTTP server. HttpConnection makes a best effort to receive a proper HTTP response from the server, although it does not guarantee that this response contains a HTTP Success code.

On low-level errors (TCP/IP errors) HttpConnection invokes a reconnect and retry algorithm. Note that although each HttpConnection object has its own connection to the HTTP server, error handling is shared across all connections to a server. For example, if there are three connections to www.somehttpserver.com, a timeout error on one of those connections will cause all three connections to break and reconnect. A connection will not break and reconnect, however, unless a request becomes active on it within a certain amount of time after the error (as specified by HTTP_CONNECTION_RETRY_DELAY). An idle connection will not break even if other connections to the same server experience errors.

A HttpConnection will retry a request a certain number of times (as defined by HTTP_CONNNECTION_RETRY_COUNT). If all the retries fail, an exception is thrown and all HttpConnections associated with a server enter a probationary period defined by HTTP_CONNECTION_RETRY_DELAY. If the user makes a new request subsequent to entering probation, the request will fail immediately with the same exception thrown on probation entry. This is so that if the HTTP server has gone down, not every subsequent request must wait for a connect timeout before failing. After the probation period expires, the internal state of the HttpConnection is reset and subsequent requests have the full number of potential reconnects and retries available to them.

Methods

Constants

HTTP_CONNECTION_RETRY_COUNT = 3   Number of times to retry the request after encountering the first error
HTTP_CONNECTION_OPEN_TIMEOUT = 5   Throw a Timeout::Error if a connection isn‘t established within this number of seconds
HTTP_CONNECTION_READ_TIMEOUT = 120   Throw a Timeout::Error if no data have been read on this connnection within this number of seconds
HTTP_CONNECTION_RETRY_DELAY = 15   Length of the post-error probationary period during which all requests will fail

Attributes

http  [RW] 
logger  [RW] 
params  [RW] 
server  [RW] 

Public Class methods

Params hash:

 :user_agent => 'www.HostName.com'    # String to report as HTTP User agent
 :ca_file    => 'path_to_file'        # A path of a CA certification file in PEM format. The file can contain several CA certificates.
 :logger     => Logger object         # If omitted, HttpConnection logs to STDOUT
 :exception  => Exception to raise    # The type of exception to raise if a request repeatedly fails. RuntimeError is raised if this parameter is omitted.
 :http_connection_retry_count         # by default == Rightscale::HttpConnection.params[:http_connection_retry_count]
 :http_connection_open_timeout        # by default == Rightscale::HttpConnection.params[:http_connection_open_timeout]
 :http_connection_read_timeout        # by default == Rightscale::HttpConnection.params[:http_connection_read_timeout]
 :http_connection_retry_delay         # by default == Rightscale::HttpConnection.params[:http_connection_retry_delay]

Query the global (class-level) parameters:

 :user_agent => 'www.HostName.com'    # String to report as HTTP User agent
 :ca_file    => 'path_to_file'        # Path to a CA certification file in PEM format. The file can contain several CA certificates.  If this parameter isn't set, HTTPS certs won't be verified.
 :logger     => Logger object         # If omitted, HttpConnection logs to STDOUT
 :exception  => Exception to raise    # The type of exception to raise
                                      # if a request repeatedly fails. RuntimeError is raised if this parameter is omitted.
 :http_connection_retry_count         # by default == Rightscale::HttpConnection::HTTP_CONNECTION_RETRY_COUNT
 :http_connection_open_timeout        # by default == Rightscale::HttpConnection::HTTP_CONNECTION_OPEN_TIMEOUT
 :http_connection_read_timeout        # by default == Rightscale::HttpConnection::HTTP_CONNECTION_READ_TIMEOUT
 :http_connection_retry_delay         # by default == Rightscale::HttpConnection::HTTP_CONNECTION_RETRY_DELAY

Set the global (class-level) parameters

Public Instance methods

Set the maximum size (in bytes) of a single read from local data sources like files. This can be used to tune the performance of, for example, a streaming PUT of a large buffer.

Query for the maximum size (in bytes) of a single read from local data sources like files. This is important, for example, in a streaming PUT of a large buffer.

Send HTTP request to server

 request_params hash:
 :server   => 'www.HostName.com'   # Hostname or IP address of HTTP server
 :port     => '80'                 # Port of HTTP server
 :protocol => 'https'              # http and https are supported on any port
 :request  => 'requeststring'      # Fully-formed HTTP request to make

Raises RuntimeError, Interrupt, and params[:exception] (if specified in new).

Set the maximum size (in bytes) of a single read from the underlying socket. For bulk transfer, especially over fast links, this is value is critical to performance.

Query for the maximum size (in bytes) of a single read from the underlying socket. For bulk transfer, especially over fast links, this is value is critical to performance.

[Validate]