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 unless defined?(HTTP_CONNECTION_RETRY_COUNT)   Number of times to retry the request after encountering the first error
HTTP_CONNECTION_OPEN_TIMEOUT = 5 unless defined?(HTTP_CONNECTION_OPEN_TIMEOUT)   Throw a Timeout::Error if a connection isn‘t established within this number of seconds
HTTP_CONNECTION_READ_TIMEOUT = 120 unless defined?(HTTP_CONNECTION_READ_TIMEOUT)   Throw a Timeout::Error if no data have been read on this connnection within this number of seconds
HTTP_CONNECTION_RETRY_DELAY = 15 unless defined?(HTTP_CONNECTION_RETRY_DELAY)   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.
 :fail_if_ca_mismatch => Boolean      # If ca_file is set and the server certificate doesn't verify, a log line is generated regardless, but normally right_http_connection continues on past the failure.  If this is set, fail to connect in that case.  Defaults to false.
 :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.
 :proxy_host => 'hostname'            # hostname of HTTP proxy host to use, default none.
 :proxy_port => port                  # port of HTTP proxy host to use, default none.
 :proxy_username => 'username'        # username to use for proxy authentication, default none.
 :proxy_password => 'password'        # password to use for proxy authentication, default none.
 :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]
 :raise_on_timeout                    # do not perform a retry if timeout is received (false by default)

[Source]

     # File lib/right_http_connection.rb, line 138
138:     def initialize(params={})
139:       @params = params
140:       @params[:http_connection_retry_count]  ||= @@params[:http_connection_retry_count]
141:       @params[:http_connection_open_timeout] ||= @@params[:http_connection_open_timeout]
142:       @params[:http_connection_read_timeout] ||= @@params[:http_connection_read_timeout]
143:       @params[:http_connection_retry_delay]  ||= @@params[:http_connection_retry_delay]
144:       @params[:proxy_host] ||= @@params[:proxy_host]
145:       @params[:proxy_port] ||= @@params[:proxy_port]
146:       @params[:proxy_username] ||= @@params[:proxy_username]
147:       @params[:proxy_password] ||= @@params[:proxy_password]
148:       @http   = nil
149:       @server = nil
150:       @logger = get_param(:logger) ||
151:                 (RAILS_DEFAULT_LOGGER if defined?(RAILS_DEFAULT_LOGGER)) ||
152:                 Logger.new(STDOUT)
153:       #--------------
154:       # Retry state - Keep track of errors on a per-server basis
155:       #--------------
156:       @state = {}  # retry state indexed by server: consecutive error count, error time, and error
157:       @eof   = {}
158:     end

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.
 :fail_if_ca_mismatch => Boolean      # If ca_file is set and the server certificate doesn't verify, a log line is generated regardless, but normally right_http_connection continues on past the failure.  If this is set, fail to connect in that case.  Defaults to false.
 :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.
 :proxy_host => 'hostname'            # hostname of HTTP proxy host to use, default none.
 :proxy_port => port                  # port of HTTP proxy host to use, default none.
 :proxy_username => 'username'        # username to use for proxy authentication, default none.
 :proxy_password => 'password'        # password to use for proxy authentication, default none.
 :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
 :raise_on_timeout                    # do not perform a retry if timeout is received (false by default)

[Source]

     # File lib/right_http_connection.rb, line 106
106:     def self.params
107:       @@params
108:     end

Set the global (class-level) parameters

[Source]

     # File lib/right_http_connection.rb, line 111
111:     def self.params=(params)
112:       @@params = params
113:     end

Public Instance methods

[Source]

     # File lib/right_http_connection.rb, line 459
459:     def finish(reason = '')
460:       if @http && @http.started?
461:         reason = ", reason: '#{reason}'" unless reason.empty?
462:         @logger.info("Closing #{@http.use_ssl? ? 'HTTPS' : 'HTTP'} connection to #{@http.address}:#{@http.port}#{reason}")
463:         @http.finish
464:       end
465:     end

[Source]

     # File lib/right_http_connection.rb, line 160
160:     def get_param(name, custom_options={})
161:       custom_options [name] || @params[name] || @@params[name]
162:     end

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.

[Source]

     # File lib/right_http_connection.rb, line 188
188:     def local_read_size=(newsize)
189:       Net::HTTPGenericRequest.local_read_size=(newsize)
190:     end

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.

[Source]

     # File lib/right_http_connection.rb, line 181
181:     def local_read_size?
182:       Net::HTTPGenericRequest.local_read_size?
183:     end

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
 :proxy_host => 'hostname'         # hostname of HTTP proxy host to use, default none.
 :proxy_port => port               # port of HTTP proxy host to use, default none.
 :proxy_username => 'username'     # username to use for proxy authentication, default none.
 :proxy_password => 'password'     # password to use for proxy authentication, default none.

 :raise_on_timeout                 # do not perform a retry if timeout is received (false by default)
 :http_connection_retry_count
 :http_connection_open_timeout
 :http_connection_read_timeout
 :http_connection_retry_delay
 :user_agent
 :exception

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

[Source]

     # File lib/right_http_connection.rb, line 358
358:     def request(request_params, &block)
359:       current_params = @params.merge(request_params)
360:       exception = get_param(:exception, current_params) || RuntimeError
361: 
362:       # We save the offset here so that if we need to retry, we can return the file pointer to its initial position
363:       mypos = get_fileptr_offset(current_params)
364:       loop do
365:         current_params[:protocol] ||= (current_params[:port] == 443 ? 'https' : 'http')
366:         # (re)open connection to server if none exists or params has changed
367:         same_server_as_before = @server   == current_params[:server] &&
368:                                 @port     == current_params[:port]   &&
369:                                 @protocol == current_params[:protocol]
370: 
371:         # if we are inside a delay between retries: no requests this time!
372:         # (skip this step if the endpoint has changed)
373:         if error_count > current_params[:http_connection_retry_count]            &&
374:            error_time  + current_params[:http_connection_retry_delay] > Time.now &&
375:            same_server_as_before
376: 
377:           # store the message (otherwise it will be lost after error_reset and
378:           # we will raise an exception with an empty text)
379:           banana_message_text = banana_message
380:           @logger.warn("#{err_header} re-raising same error: #{banana_message_text} " +
381:                       "-- error count: #{error_count}, error age: #{Time.now.to_i - error_time.to_i}")
382:           raise exception.new(banana_message_text)
383:         end
384: 
385:         # try to connect server(if connection does not exist) and get response data
386:         begin
387:           request = current_params[:request]
388:           request['User-Agent'] = get_param(:user_agent, current_params) || ''
389:           unless @http          &&
390:                  @http.started? &&
391:                  same_server_as_before
392:             start(current_params)
393:           end
394: 
395:           # Detect if the body is a streamable object like a file or socket.  If so, stream that
396:           # bad boy.
397:           setup_streaming(request)
398:           # update READ_TIMEOUT value (it can be passed with request_params hash)
399:           @http.read_timeout = get_param(:http_connection_read_timeout, current_params)
400:           response = @http.request(request, &block)
401: 
402:           error_reset
403:           eof_reset
404:           return response
405: 
406:         # We treat EOF errors and the timeout/network errors differently.  Both
407:         # are tracked in different statistics blocks.  Note below that EOF
408:         # errors will sleep for a certain (exponentially increasing) period.
409:         # Other errors don't sleep because there is already an inherent delay
410:         # in them; connect and read timeouts (for example) have already
411:         # 'slept'.  It is still not clear which way we should treat errors
412:         # like RST and resolution failures.  For now, there is no additional
413:         # delay for these errors although this may change in the future.
414: 
415:         # EOFError means the server closed the connection on us.
416:         rescue EOFError => e
417:           @logger.debug("#{err_header} server #{@server} closed connection")
418:           @http = nil
419: 
420:             # if we have waited long enough - raise an exception...
421:           if raise_on_eof_exception?
422:             @logger.warn("#{err_header} raising #{exception} due to permanent EOF being received from #{@server}, error age: #{Time.now.to_i - eof_time.to_i}")
423:             raise exception.new("Permanent EOF is being received from #{@server}.")
424:           else
425:               # ... else just sleep a bit before new retry
426:             sleep(add_eof)
427:             # We will be retrying the request, so reset the file pointer
428:             reset_fileptr_offset(request, mypos)
429:           end
430:         rescue Exception => e  # See comment at bottom for the list of errors seen...
431:           @http = nil
432:           timeout_exception = e.is_a?(Errno::ETIMEDOUT) || e.is_a?(Timeout::Error)
433:           # Omit retries if it was explicitly requested
434:           if current_params[:raise_on_timeout] && timeout_exception
435:             # #6481:
436:             # ... When creating a resource in EC2 (instance, volume, snapshot, etc) it is undetermined what happened if the call times out.
437:             # The resource may or may not have been created in EC2. Retrying the call may cause multiple resources to be created...
438:             raise e
439:           end
440:           # if ctrl+c is pressed - we have to reraise exception to terminate proggy
441:           if e.is_a?(Interrupt) && !timeout_exception
442:             @logger.debug( "#{err_header} request to server #{@server} interrupted by ctrl-c")
443:             raise
444:           elsif e.is_a?(ArgumentError) && e.message.include?('wrong number of arguments (5 for 4)')
445:             # seems our net_fix patch was overriden...
446:             raise exception.new('incompatible Net::HTTP monkey-patch')
447:           end
448:           # oops - we got a banana: log it
449:           error_add(e.message)
450:           @logger.warn("#{err_header} request failure count: #{error_count}, exception: #{e.inspect}")
451: 
452:           # We will be retrying the request, so reset the file pointer
453:           reset_fileptr_offset(request, mypos)
454: 
455:         end
456:       end
457:     end

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.

[Source]

     # File lib/right_http_connection.rb, line 174
174:     def socket_read_size=(newsize)
175:       Net::BufferedIO.socket_read_size=(newsize)
176:     end

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.

[Source]

     # File lib/right_http_connection.rb, line 167
167:     def socket_read_size?
168:       Net::BufferedIO.socket_read_size?
169:     end

[Validate]