aws-sdk 1.6.2 → 1.6.3

data/lib/aws/simple_email_service/request.rb

@@ -13,7 +13,6 @@
 
 module AWS
   class SimpleEmailService
-
     # @private
     class Request < Core::Http::Request
 
@@ -24,6 +23,5 @@ module AWS
       end
 
     end
-
   end
 end

data/lib/aws/simple_workflow/request.rb

@@ -19,9 +19,6 @@ module AWS
 
       include Core::Signature::Version3
 
-      # @return [String,nil]
-      attr_accessor :body
-
       def read_timeout
         # increase read timeout for long polling
         if headers['x-amz-target'] =~ /PollFor(Decision|Activity)Task/

data/lib/net/http/connection_pool.rb

@@ -16,18 +16,19 @@ require 'net/http/connection_pool/connection'
 require 'thread'
 require 'logger'
 
+# A wrapper around Net::HTTP that provides a manged pool of persistant HTTP
+# connections.
+#
+#   pool = Net::HTTP::ConnectionPool.new
+#   connection = pool.connection_for('domain.com')
+#   connection.request(Net::HTTP::Get.new('/')) do |resp|
+#     # Connection#request yields Net::HTTPResponse objects
+#     puts resp.body
+#   end
+#
 # @private
 class Net::HTTP::ConnectionPool
 
-  SOCKET_ERRORS = [
-    EOFError, 
-    IOError, 
-    Errno::ECONNABORTED, 
-    Errno::ECONNRESET, 
-    Errno::EPIPE, 
-    Errno::EINVAL 
-  ]
-
   # @param [Hash] options
   #
   # @option options [Numeric] :http_idle_timeout (60) The number of seconds a
@@ -42,10 +43,10 @@ class Net::HTTP::ConnectionPool
   #
   # @option options [Logger] :logger (Logger.new($stdout)) Where debug out
   #   is sent (wire traces).
-  # 
+  #
   def initialize options = {}
-    @pool = []
     @pool_mutex = Mutex.new
+    @pool = []
     @open_timeout = options[:http_open_timeout] || 15
     @idle_timeout = options[:http_idle_timeout] || 60
     @http_wire_trace = !!options[:http_wire_trace]
@@ -56,7 +57,7 @@ class Net::HTTP::ConnectionPool
     end
   end
 
-  # @return [Integer] 
+  # @return [Integer]
   attr_reader :idle_timeout
 
   # @return [Integer]
@@ -76,20 +77,18 @@ class Net::HTTP::ConnectionPool
   # Requests a connection object from the connection pool.
   #
   #   connection = pool.connection_for('domain.com')
-  #   connection.request(Net::HTTP::Get.new('/index.html'))
-  #   connection.request(Net::HTTP::Get.new('/about.html'))
+  #   connection.request(Net::HTTP::Get.new('/index.html')) {|resp|}
+  #   connection.request(Net::HTTP::Get.new('/about.html')) {|resp|}
   #
   #   # same thing in block form
   #   pool.connection_for('domain.com') do |connection|
-  #     connection.request(Net::HTTP::Get.new('/index.html'))
-  #     connection.request(Net::HTTP::Get.new('/about.html'))
+  #     connection.request(Net::HTTP::Get.new('/index.html')) {|resp|}
+  #     connection.request(Net::HTTP::Get.new('/about.html')) {|resp|}
   #   end
   #
   # Because the pool manages HTTP sessions you do not have to
   # worry about closing a connection or returning a connection
-  # to the pool.  Every time you call request on a connection
-  # object, a HTTP session received from the pool and returned after
-  # the request is complete.
+  # to the pool.
   #
   # @param [String] host
   #
@@ -102,12 +101,12 @@ class Net::HTTP::ConnectionPool
   #   SSL.  Defaults to +false+, unless +:port+ is 443, then it defaults
   #   to +true+.
   #
-  # @option options [Boolean] :ssl_verify_peer (true) If true, ssl 
+  # @option options [Boolean] :ssl_verify_peer (true) If true, ssl
   #   connections should verify peer certificates.  This should only ever be
   #   set false false for debugging purposes.
   #
   # @option options [String] :ssl_ca_file Full path to the SSL certificate
-  #   authority bundle file that should be used when verifying peer 
+  #   authority bundle file that should be used when verifying peer
   #   certificates.  If you do not pass +:ssl_ca_file+ or +:ssl_ca_path+
   #   the the system default will be used if available.
   #
@@ -117,7 +116,7 @@ class Net::HTTP::ConnectionPool
   #   the the system default will be used if available.
   #
   # @option options [URI::HTTP,String] :proxy_uri (nil) A URI string or
-  #   URI::HTTP object to use as a proxy.  You should not provide 
+  #   URI::HTTP object to use as a proxy.  You should not provide
   #   +:proxy_uri+ with any other proxy options.
   #
   #     :proxy_uri => 'http://user:pass@host.com:80'
@@ -142,54 +141,19 @@ class Net::HTTP::ConnectionPool
     connection
   end
 
-  # @private
-  def request connection, *request_args, &block
-
-    session = nil
-    response = nil
-    retried = false
-
-    begin
-
-      session = session_for(connection, retried)
-      session.http_session.read_timeout = connection.read_timeout
-      response = session.request(*request_args, &block)
-
-    rescue Exception => error
-
-      # close the http session to prevent the connection from being
-      # left open and risk the other side sending data
-      session.finish if session
-
-      # retry socket errors once on a new session
-      if SOCKET_ERRORS.include?(error.class) and !retried
-        retried = true
-        retry
-      end
-
-      raise error
-
-    else
-      @pool_mutex.synchronize { @pool << session }
-    end
-
-    response
-
-  end
-
   # Returns the number of sessions currently in the pool, not counting those
   # currently in use.
   def size
-    @pool_mutex.synchronize { @pool.size }  
+    @pool_mutex.synchronize { @pool.size }
   end
 
-  # Removes stale http sessions from the pool (that have exceeded 
+  # Removes stale http sessions from the pool (that have exceeded
   # the idle timeout).
   def clean!
     @pool_mutex.synchronize { _clean }
   end
 
-  # Closes and removes removes all sessions from the pool.  
+  # Closes and removes removes all sessions from the pool.
   # If empty! is called while there are outstanding requests they may
   # get checked back into the pool, leaving the pool in a non-empty state.
   def empty!
@@ -199,33 +163,57 @@ class Net::HTTP::ConnectionPool
     end
   end
 
-  # Returns a suitable session from the pool or creates a new one
-  private
-  def session_for connection, force_new = false
+  # Makes a single HTTP request.  See {Connection#request} for more information
+  # on making an HTTP request.
+  # @return [nil]
+  # @private
+  def request connection, *args, &block
+    session_for(connection) do |session|
+      session.read_timeout = connection.read_timeout
+      session.request(*args, &block)
+    end
+  end
+
+  protected
+
+  # Yields an open http session for the given connection.
+  def session_for connection, &block
 
     session = nil
 
-    unless force_new
-      @pool_mutex.synchronize do
-        _clean
-        session = @pool.find{|idle_session| idle_session.key == connection.key }
-        @pool.delete(session) if session
-      end
+    # search the pool for an idle session that can be used
+    @pool_mutex.synchronize do
+      _clean # removes stale sessions
+      session = @pool.find{|idle_session| idle_session.key == connection.key }
+      @pool.delete(session) if session
     end
 
-    if session.nil?
-      logger = http_wire_trace? ? self.logger : nil 
-      session = Session.for(connection, open_timeout, logger)
+    begin
+      # opens a new HTTP session if no suitable idle session was found
+      session = _create_session(connection) unless session
+      yield(session)
+    rescue Exception => error
+      session.finish if session
+      raise error
+    else
+      # only check the session back into the pool if no errors were raised
+      @pool_mutex.synchronize { @pool << session }
     end
 
-    session
+    nil
+
+  end
+
+  def _create_session connection
+    Session.start(connection,
+      :open_timeout => open_timeout,
+      :debug_logger => log_wire_trace? ? logger : nil)
   end
 
-  private
   def _clean
     now = Time.now
     @pool.delete_if do |idle_session|
-      if 
+      if
         idle_session.last_used_at.nil? or
         now - idle_session.last_used_at > idle_timeout
       then

data/lib/net/http/connection_pool/connection.rb

@@ -15,17 +15,34 @@ require 'uri'
 
 class Net::HTTP::ConnectionPool
 
-  # A light wrapper around Net::HTTP.  
+  # Represents a HTTP connection.  Call {#request} on a connection like
+  # you would with a Net::HTTPSession object.
   #
-  # You should not need to construct connection objects yourself.  
-  # You receive them as a response to {ConnectionPool#connection_for}.
+  # == Getting a Connection object
+  #
+  # To get a connection object, you start with a connection pool:
+  #
+  #   pool = Net::HTTP::ConnectionPool.new
+  #   connection = pool.connection_for('domain.com')
+  #
+  # {ConnectionPool#connection_for} accepts a number of options to control
+  # the connection settings (SSL, proxy, timeouts, etc).
+  #
+  # == Making Requests
+  #
+  # Given a connection object, you call #request.  {Connection#request}
+  # yields Net::HTTPResponse objects (when given a block).  You should 
+  # read the response (via #body or #read_body) before the end of the
+  # block.
+  #
+  #   connection.request(Net::HTTP::Get.new('/')) do |resp|
+  #     puts resp.body
+  #   end
   #
   class Connection
 
-    # @param [ConnectionPool] pool
-    # @param (see ConnectionPool#connection_for) 
-    # @option (see ConnectionPool#connection_for)
-    # @return [Connection]
+    # Use {ConnectionPool#connection_for} to construct {Connection} objects.
+    # @private
     def initialize pool, host, options = {}
 
       @pool = pool
@@ -96,35 +113,72 @@ class Net::HTTP::ConnectionPool
     # @return [Numeric,nil]
     attr_accessor :read_timeout
 
-    # @return [Boolean] Returns true if this connection requires SSL.
+    # @return [Boolean] Returns +true+ if this connection requires SSL.
     def ssl?
       @ssl
     end
 
-    # @return [Boolean] Returns true if ssl connections should verify the
+    # @return [Boolean] Returns +true+ if ssl connections should verify the
     #   peer certificate.
     def ssl_verify_peer?
       @ssl_verify_peer
     end
 
-    # @return [Boolean] Returns true if this connection proxies requests.
+    # @return [Boolean] Returns +true+ if this connection proxies requests.
     def proxy?
       !!proxy_address
     end
 
-    # Makes a HTTP request.  See Net::HTTPSession#request documentation
-    # from the Ruby standard library for information about argments.
-    # @return [Net::HTTPResponse]
+    # Makes a single HTTP request.  The Net::HTTPResponse is yielded to the
+    # given block.
+    #
+    #   pool = Net::HTTP::ConnectionPool.new
+    #   connection = pool.connection_for('www.google.com')
+    #
+    #   connection.request(Net::HTTP::Get.new('/')) do |response|
+    #     # yeilds a Net::HTTPResponse object
+    #     puts "STATUS CODE: #{response.code}"
+    #     puts "HEADERS: #{response.to_hash.inspect}"
+    #     puts "BODY:\n#{response.body}"
+    #   end
+    #
+    # If you want to read the HTTP response body in chunks (useful for
+    # large responses you do not want to load into memory), you should
+    # pass a block to the #read_body method of the yielded response.
+    #
+    #   File.open('output.txt', 'w') do |file|
+    #     connection.request(Net::HTTP::Get.new('/')) do |response|
+    #       response.read_body do |chunk|
+    #         file.write(chunk)
+    #       end
+    #     end
+    #   end
+    #
+    # If you omit the block when calling #request, you will not be able
+    # to read the response.  This method never returns the 
+    # Net::HTTPResponse generated.
+    #
+    # This method passes *args to Net::HTTPSession#request.  See the
+    # Ruby standard lib documentation for more documentation about 
+    # accepted arguments.
+    #
+    # @note You should read the yielded response object before the end
+    #  of the passed block. Do no save a reference to yielded response
+    #  objects.
+    #
+    # @yield [response]
+    # @yieldparam [Net::HTTPResponse] response
+    # @return [nil]
     def request *args, &block
       pool.request(self, *args, &block)
     end
 
     # @return [String] Returns a key that can be used to group connections
-    #   that connection to the same host.
+    #   that may share the same HTTP sessions.
     def key
       @key ||= begin
         %w(
-          host port 
+          host port
           ssl ssl_verify_peer ssl_ca_file ssl_ca_path
           proxy_address proxy_port proxy_user proxy_password
         ).map{|part| send(part).to_s }.join(":")

data/lib/net/http/connection_pool/session.rb

@@ -17,9 +17,13 @@ require 'openssl'
 
 class Net::HTTP::ConnectionPool
 
+  # Used by Net::HTTP::ConnectionPool to wrap Net::HTTP::Session objects.
+  # Users should never need to interact with these session wrappers.
   # @private
   class Session
 
+    # @param [Net::HTTPSession] http_session
+    # @param [String] key
     def initialize http_session, key
       @http_session = http_session
       @key = key
@@ -27,20 +31,42 @@ class Net::HTTP::ConnectionPool
       @last_used_at = nil
     end
 
+    # @return [Net::HTTPSession]
     attr_reader :http_session
 
+    # @return [String]
     attr_reader :key
 
+    # @return [Time]
     attr_reader :created_at
 
+    # @return [Time]
     attr_reader :last_used_at
 
+    # @param [Integer] timeout Number of seconds before Net::HTTP should
+    #   timeout while waiting to read a response.
+    def read_timeout= timeout
+      http_session.read_timeout = timeout
+    end
+
+    # Makes a HTTP request.  See Net::HTTPSession#request documentation
+    # from the Ruby standard library for information about argments.
+    #
+    #   connection.request(Net::HTTP::Get.new('/')) do |response|
+    #     # Parse the response (status, headers and body) here.
+    #     # You should be done with the response by the end of the block.
+    #   end
+    #
+    # @yield [response]
+    # @yieldparam [Net::HTTPResponse] response
+    # @return [nil]
     def request *args, &block
-      response = http_session.request(*args, &block)
+      http_session.request(*args, &block)
       @last_used_at = Time.now
-      response
+      nil
     end
 
+    # Attempts to cleanly close the HTTP session.
     # @return [nil]
     def finish
       begin
@@ -52,7 +78,15 @@ class Net::HTTP::ConnectionPool
 
     class << self
 
-      def for connection, open_timeout, debug_logger = nil
+      # Starts a new HTTP session and returns it wrapped in a {Session} object.
+      # @param [Connection] connection
+      # @param [Hash] options
+      # @option options [Integer] :open_timeout (15) The number of seconds to
+      #   wait while trying to open the HTTP session before timeing out.
+      # @option options [Logger] :debug_logger HTTP wire traces are logged
+      #   here when specified.
+      # @return [Session]
+      def start connection, options = {}
 
         http_args = []
         http_args << connection.host
@@ -65,8 +99,8 @@ class Net::HTTP::ConnectionPool
         end
 
         http = Net::HTTP.new(*http_args)
-        http.set_debug_output(debug_logger)
-        http.open_timeout = open_timeout
+        http.set_debug_output(options[:debug_logger]) if options[:debug_logger]
+        http.open_timeout = options[:open_timeout] || 15
 
         if connection.ssl?
           http.use_ssl = true
@@ -88,6 +122,5 @@ class Net::HTTP::ConnectionPool
       end
 
     end
-
   end
 end