right_http_connection 1.1.0

data/History.txt

@@ -0,0 +1,30 @@
++++ 0.0.1 2007-05-15
+
++ 1 major enhancement:
+  + Initial release
+
++++ 0.1.2 2007-6-27
+
+No major changes.
+
++++ 0.1.3 2007-7-09
+
+No change.
+
++++ 0.1.4 2007-8-10
+
+------------------------------------------------------------------------
+r1442 | todd | 2007-08-07 15:45:24 -0700 (Tue, 07 Aug 2007) | 654 lines
+
+(#373) Add support in right_http_connection for bailing out to a block while
+reading the HTTP response (to support GET streaming...)
+
+------------------------------------------------------------------------
+r1411 | todd | 2007-08-03 15:14:45 -0700 (Fri, 03 Aug 2007) | 3 lines
+
+(#373) Stream uploads (PUTs) if the source is a file, stream, or anything
+read()-able
+
++++ 1.1.0 2007-08-15
+Initial public release
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/right_http_connection.rb
+lib/right_http_connection/version.rb
+setup.rb

data/README.txt

@@ -0,0 +1,48 @@
+RightScale::HttpConnection
+    by RightScale, Inc.
+    www.RightScale.com 
+
+== DESCRIPTION:
+
+Rightscale::HttpConnection is a robust HTTP/S library.  It implements a retry
+algorithm for low-level network errors.
+
+== FEATURES/PROBLEMS:
+
+- provides put/get streaming
+- does configurable retries on connect and read timeouts, DNS failures, etc.
+- HTTPS certificate checking
+  
+== SYNOPSIS:
+
+
+== REQUIREMENTS:
+
+None.
+
+== INSTALL:
+
+sudo gem install
+
+== LICENSE:
+
+Copyright (c) 2007 RightScale, Inc. 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,90 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'right_http_connection', 'version')
+
+AUTHOR = 'RightScale'  # can also be an array of Authors
+EMAIL = "support@rightscale.com"
+DESCRIPTION = "RightScale's robust HTTP/S connection module"
+GEM_NAME = 'right_http_connection' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'rightaws' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "right_http_connection"
+REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = RightHttpConnection::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'right_http_connection documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  p.remote_rdoc_dir = "/right_http_gem_doc"
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+
+desc 'Generate website files'
+task :website_generate do
+  Dir['website/**/*.txt'].each do |txt|
+    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+  host = "#{config["username"]}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{RUBYFORGE_PROJECT}/"
+  # remote_dir = "/var/www/gforge-projects/#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+  local_dir = 'website'
+  sh %{rsync -av #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload]
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end

data/lib/right_http_connection.rb

@@ -0,0 +1,306 @@
+#
+# Copyright (c) 2007 RightScale Inc, all rights reserved
+#
+
+require "net/https"
+require "uri"
+require "time"
+require "logger"
+
+
+module Rightscale
+ 
+=begin rdoc
+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.
+=end
+
+  class HttpConnection 
+
+    # Number of times to retry the request after encountering the first error
+    HTTP_CONNECTION_RETRY_COUNT   = 3   
+    # Throw a Timeout::Error if a connection isn't established within this number of seconds
+    HTTP_CONNECTION_OPEN_TIMEOUT  = 5   
+    # Throw a Timeout::Error if no data have been read on this connnection within this number of seconds
+    HTTP_CONNECTION_READ_TIMEOUT  = 30  
+    # Length of the post-error probationary period during which all requests will fail 
+    HTTP_CONNECTION_RETRY_DELAY   = 15  
+
+    #--------------------
+    # class methods
+    #--------------------
+      # Params hash
+      # :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.
+    @@params = {}
+   
+    # Query the global (class-level) parameters
+    def self.params
+      @@params
+    end
+   
+    # Set the global (class-level) parameters
+    def self.params=(params)
+      @@params = params
+    end
+
+    #------------------
+    # instance methods
+    #------------------
+    attr_accessor :http
+    attr_accessor :server
+    attr_accessor :params      # see @@params
+    attr_accessor :logger
+
+=begin rdoc
+      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.
+                                            
+=end 
+    def initialize(params={})
+      @params = params     
+      @http   = nil
+      @server = nil
+      @logger = get_param(:logger) || 
+                (RAILS_DEFAULT_LOGGER if defined?(RAILS_DEFAULT_LOGGER)) ||
+                Logger.new(STDOUT)
+    end
+
+    def get_param(name)
+      @params[name] || @@params[name]
+    end
+
+  private
+    #--------------
+    # Retry state - Keep track of errors on a per-server basis
+    #--------------
+    @@state = {}  # retry state indexed by server: consecutive error count, error time, and error
+    @@eof   = {}
+
+    # number of consecutive errors seen for server, 0 all is ok
+    def error_count
+      @@state[@server] ? @@state[@server][:count] : 0
+    end
+    
+    # time of last error for server, nil if all is ok
+    def error_time
+      @@state[@server] && @@state[@server][:time]
+    end
+    
+    # message for last error for server, "" if all is ok
+    def error_message
+      @@state[@server] ? @@state[@server][:message] : ""
+    end
+    
+    # add an error for a server
+    def error_add(message)
+      @@state[@server] = { :count => error_count+1, :time => Time.now, :message => message }
+    end
+    
+    # reset the error state for a server (i.e. a request succeeded)
+    def error_reset
+      @@state.delete(@server)
+    end
+    
+    # Error message stuff...
+    def banana_message
+      return "#{@server} temporarily unavailable: (#{error_message})"
+    end
+
+    def err_header
+      return "#{self.class.name} :"
+    end
+    
+      # Adds new EOF timestamp.
+      # Returns the number of seconds to wait before new conection retry:
+      #  0.5, 1, 2, 4, 8
+    def add_eof
+      (@@eof[@server] ||= []).unshift Time.now
+      0.25 * 2 ** @@eof[@server].size
+    end
+
+      # Returns first EOF timestamp or nul if have no EOFs being tracked.
+    def eof_time
+      @@eof[@server] && @@eof[@server].last
+    end
+    
+      # Returns true if we are receiving EOFs during last HTTP_CONNECTION_RETRY_DELAY seconds
+      # and there were no successful response from server
+    def raise_on_eof_exception?
+      @@eof[@server].blank? ? false : ( (Time.now.to_i-HTTP_CONNECTION_RETRY_DELAY) > @@eof[@server].last.to_i )
+    end 
+    
+      # Reset a list of EOFs for this server.
+      # This is being called when we have got an successful response from server.
+    def eof_reset
+      @@eof.delete(@server)
+    end
+
+    # Start a fresh connection. The object closes any existing connection and
+    # opens a new one.
+    def start(request_params)
+      # close the previous if exists
+      @http.finish if @http && @http.started?
+      # create new connection
+      @server   = request_params[:server]
+      @port     = request_params[:port]
+      @protocol = request_params[:protocol] || (@port==443 ? 'https' : 'http')
+      
+      @logger.info("Opening new HTTP connection to #{@server}")
+      @http = Net::HTTP.new(@server, @port)
+      @http.open_timeout = HTTP_CONNECTION_OPEN_TIMEOUT
+      @http.read_timeout = HTTP_CONNECTION_READ_TIMEOUT
+      
+      if @protocol == 'https'
+        verifyCallbackProc = Proc.new{ |ok, x509_store_ctx|
+          code = x509_store_ctx.error
+          msg = x509_store_ctx.error_string
+            #debugger
+          @logger.warn("##### #{@server} certificate verify failed: #{msg}") unless code == 0
+          true
+        }
+        @http.use_ssl = true
+        ca_file = get_param(:ca_file)
+        if ca_file
+          @http.verify_mode     = OpenSSL::SSL::VERIFY_PEER
+          @http.verify_callback = verifyCallbackProc
+          @http.ca_file         = ca_file 
+        end
+      end
+      # open connection
+      @http.start
+    end
+
+  public
+    
+=begin rdoc    
+    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).
+    
+=end
+    def request(request_params, &block)
+      loop do
+        # if we are inside a delay between retries: no requests this time!
+        if error_count > HTTP_CONNECTION_RETRY_COUNT \
+        && error_time + HTTP_CONNECTION_RETRY_DELAY > Time.now
+          @logger.warn("#{err_header} re-raising same error: #{banana_message} " +
+                      "-- error count: #{error_count}, error age: #{Time.now.to_i - error_time.to_i}")  
+          exception = get_param(:exception) || RuntimeError
+          raise exception.new(banana_message)
+        end
+      
+        # try to connect server(if connection does not exist) and get response data
+        begin
+          # (re)open connection to server if none exists
+          # TODO TRB 8/2/07 - you also need to get a new connection if the
+          # server, port, or proto has changed in the request_params
+          start(request_params) unless @http
+          
+          # get response and return it
+          request  = request_params[:request]
+          request['User-Agent'] = get_param(:user_agent) || ''
+
+          # Detect if the body is a streamable object like a file or socket.  If so, stream that
+          # bad boy.
+          if(request.body && request.body.respond_to?(:read))
+            body = request.body
+            request.content_length = body.respond_to?(:lstat) ? body.lstat.size : body.size 
+            request.body_stream = request.body
+          end
+          response = @http.request(request, &block)
+          
+          error_reset
+          eof_reset
+          return response
+
+        # We treat EOF errors and the timeout/network errors differently.  Both
+        # are tracked in different statistics blocks.  Note below that EOF
+        # errors will sleep for a certain (exponentially increasing) period.
+        # Other errors don't sleep because there is already an inherent delay
+        # in them; connect and read timeouts (for example) have already
+        # 'slept'.  It is still not clear which way we should treat errors
+        # like RST and resolution failures.  For now, there is no additional
+        # delay for these errors although this may change in the future.
+        
+        # EOFError means the server closed the connection on us.
+        rescue EOFError => e
+          @logger.debug("#{err_header} server #{@server} closed connection")
+          @http = nil
+          
+            # if we have waited long enough - raise an exception...
+          if raise_on_eof_exception?
+            exception = get_param(:exception) || RuntimeError
+            @logger.warn("#{err_header} raising #{exception} due to permanent EOF being received from #{@server}, error age: #{Time.now.to_i - eof_time.to_i}")  
+            raise exception.new("Permanent EOF is being received from #{@server}.")
+          else
+              # ... else just sleep a bit before new retry
+            sleep(add_eof)
+          end 
+          
+        rescue Exception => e  # See comment at bottom for the list of errors seen...
+          # if ctrl+c is pressed - we have to reraise exception to terminate proggy 
+          if e.is_a?(Interrupt) && !( e.is_a?(Errno::ETIMEDOUT) || e.is_a?(Timeout::Error))
+            @logger.debug( "#{err_header} request to server #{@server} interrupted by ctrl-c")
+            @http = nil
+            raise
+          end
+          # oops - we got a banana: log it
+          error_add(e.message)
+          @logger.warn("#{err_header} request failure count: #{error_count}, exception: #{e.inspect}")
+          @http = nil
+        end
+      end
+    end
+
+  # Errors received during testing:
+  #
+  #  #<Timeout::Error: execution expired>
+  #  #<Errno::ETIMEDOUT: Connection timed out - connect(2)>
+  #  #<SocketError: getaddrinfo: Name or service not known>
+  #  #<SocketError: getaddrinfo: Temporary failure in name resolution>
+  #  #<EOFError: end of file reached>
+  #  #<Errno::ECONNRESET: Connection reset by peer>
+  #  #<OpenSSL::SSL::SSLError: SSL_write:: bad write retry>
+  end
+  
+end