resilient_socket 0.0.2

data/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2012 Clarity Services, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,109 @@
+resilient_socket
+================
+
+A Resilient TCP Socket Client with built-in timeouts, retries, and logging
+
+* http://github.com/ClarityServices/resilient_socket
+
+### Introduction
+
+Resilient Socket implements resilience features that most developers wish was
+already included in the standard Ruby libraries.
+
+With so many "client" libraries to servers such us memcache, MongoDB, Redis, etc.
+their focus on the communication formats and messaging interactions. As a result
+adding resilience is usually an after thought.
+
+More importantly the way that each client implements connection failure handling
+varies dramatically. The purpose of this library is to try and extract the best
+of all the socket error handling out there and create a consistent way of dealing
+with connection failures.
+
+Another important feature is that the _connect_ and _read_ API's use timeout's to
+prevent a network issue from "hanging" the client program.
+
+It is expected that this library will undergo significant changes until V1 is reached
+as input is gathered from client library developers. After V1 the interface should
+not break existing users
+
+### TCPClient API
+
+#### Standard Logging methods
+
+TCPClient should be a drop in replacement for TCPSocket when used as a client
+in any way needed other than for the initializer that accepts several new options
+to adjust the retry logic
+
+### Dependencies
+
+- Ruby MRI 1.8.7 (or above) Or, JRuby 1.6.3 (or above)
+- SemanticLogger
+
+### Install
+
+    gem install semantic-logger
+
+To log to MongoDB
+
+    gem install mongo
+
+### Future
+
+- Web Interface to view and search log information stored in MongoDB
+
+Development
+-----------
+
+Want to contribute to Semantic Logger?
+
+First clone the repo and run the tests:
+
+    git clone git://github.com/ClarityServices/semantic-logger.git
+    cd semantic-logger
+    jruby -S rake test
+
+Feel free to ping the mailing list with any issues and we'll try to resolve it.
+
+Contributing
+------------
+
+Once you've made your great commits:
+
+1. [Fork](http://help.github.com/forking/) semantic-logger
+2. Create a topic branch - `git checkout -b my_branch`
+3. Push to your branch - `git push origin my_branch`
+4. Create an [Issue](http://github.com/ClarityServices/semantic-logger/issues) with a link to your branch
+5. That's it!
+
+Meta
+----
+
+* Code: `git clone git://github.com/ClarityServices/semantic-logger.git`
+* Home: <https://github.com/ClarityServices/semantic-logger>
+* Docs: TODO <http://ClarityServices.github.com/semantic-logger/>
+* Bugs: <http://github.com/reidmorrison/semantic-logger/issues>
+* Gems: <http://rubygems.org/gems/semantic-logger>
+
+This project uses [Semantic Versioning](http://semver.org/).
+
+Authors
+-------
+
+Reid Morrison :: reidmo@gmail.com :: @reidmorrison
+
+License
+-------
+
+Copyright 2012 Clarity Services, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -0,0 +1,37 @@
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'rubygems'
+require 'rake/clean'
+require 'rake/testtask'
+require 'date'
+require 'resilient_socket/version'
+
+desc "Build gem"
+task :gem  do |t|
+  gemspec = Gem::Specification.new do |spec|
+    spec.name        = 'resilient_socket'
+    spec.version     = ResilientSocket::VERSION
+    spec.platform    = Gem::Platform::RUBY
+    spec.authors     = ['Reid Morrison']
+    spec.email       = ['reidmo@gmail.com']
+    spec.homepage    = 'https://github.com/ClarityServices/resilient_socket'
+    spec.date        = Date.today.to_s
+    spec.summary     = "A Resilient TCP Socket Client with built-in timeouts, retries, and logging"
+    spec.description = "A Resilient TCP Socket Client with built-in timeouts, retries, and logging"
+    spec.files       = FileList["./**/*"].exclude('*.gem', 'nbproject').map{|f| f.sub(/^\.\//, '')}
+    spec.has_rdoc    = true
+    spec.add_dependency 'semantic_logger'
+  end
+  Gem::Builder.new(gemspec).build
+end
+
+desc "Run Test Suite"
+task :test do
+  Rake::TestTask.new(:functional) do |t|
+    t.test_files = FileList['test/*_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::Task['functional'].invoke
+end

data/lib/resilient_socket/exceptions.rb

@@ -0,0 +1,8 @@
+module ResilientSocket
+
+  class Exception < ::RuntimeError; end
+  class ConnectionTimeout < Exception; end
+  class ReadTimeout < Exception; end
+  class ConnectionFailure < Exception; end
+
+end

data/lib/resilient_socket/tcp_client.rb

@@ -0,0 +1,351 @@
+module ResilientSocket
+
+  # Make Socket calls resilient by adding timeouts, retries and specific
+  # exception categories
+  #
+  # Resilient TCP Client with:
+  # * Connection Timeouts
+  #   Ability to timeout if a connect does not complete within a reasonable time
+  #   For example, this can occur when the server is turned off without shutting down
+  #   causing clients to hang creating new connections
+  #
+  # * Automatic retries on startup connection failure
+  #   For example, the server is being restarted while the client is starting
+  #   Gives the server a few seconds to restart to
+  #
+  # * Automatic retries on active connection failures
+  #   If the server is restarted during
+  #
+  # Connection and Read Timeouts are fully configurable
+  #
+  # Raises ConnectionTimeout when the connection timeout is exceeded
+  # Raises ReadTimeout when the read timeout is exceeded
+  # Raises ConnectionFailure when a network error occurs whilst reading or writing
+  #
+  # Future:
+  #
+  # * Automatic failover to another server should the current server not respond
+  #   to a connection request by supplying an array of host names
+  #
+  class TCPClient
+    # Supports embedding user supplied data along with this connection
+    # such as sequence number, etc.
+    # TCPClient will reset this value to nil on connection start and
+    # after a connection is re-established. For example on automatic reconnect
+    # due to a failed connection to the server
+    attr_accessor :user_data
+
+    # [String] Name of the server currently connected to or being connected to
+    # including the port number
+    #
+    # Example:
+    #   "localhost:2000"
+    attr_reader :server
+
+    # Create a connection, call the supplied block and close the connection on
+    # completion of the block
+    #
+    # See #initialize for the list of parameters
+    #
+    # Example
+    #   ResilientSocket::TCPClient.connect(
+    #     :server                 => 'server:3300',
+    #     :connect_retry_interval => 0.1,
+    #     :connect_retry_count    => 5
+    #   ) do |client|
+    #     client.retry_on_connection_failure do
+    #       client.send('Update the database')
+    #     end
+    #     response = client.read(20)
+    #     puts "Received: #{response}"
+    #   end
+    #
+    def self.connect(params={})
+      begin
+        connection = self.new(params)
+        yield(connection)
+      ensure
+        connection.close if connection
+      end
+    end
+
+    # Create a new TCP Client connection
+    #
+    # Parameters:
+    #   :server [String]
+    #     URL of the server to connect to with port number
+    #     'localhost:2000'
+    #
+    #   :servers [Array of String]
+    #     Array of URL's of servers to connect to with port numbers
+    #     ['server1:2000', 'server2:2000']
+    #
+    #     The second server will only be attempted once the first server
+    #     cannot be connected to or has timed out on connect
+    #     A read failure or timeout will not result in switching to the second
+    #     server, only a connection failure or during an automatic reconnect
+    #
+    #   :read_timeout [Float]
+    #     Time in seconds to timeout on read
+    #     Can be overridden by supplying a timeout in the read call
+    #     Default: 60
+    #
+    #   :connect_timeout [Float]
+    #     Time in seconds to timeout when trying to connect to the server
+    #     Default: Half of the :read_timeout ( 30 seconds )
+    #
+    #   :log_level [Symbol]
+    #     Only set this level to override the global SemanticLogger logging level
+    #     Can be used to turn on trace or debug level logging in production
+    #     Any valid SemanticLogger log level:
+    #       :trace, :debug, :info, :warn, :error, :fatal
+    #
+    #   :buffered [Boolean]
+    #     Whether to use Nagle's Buffering algorithm (http://en.wikipedia.org/wiki/Nagle's_algorithm)
+    #     Recommend disabling for RPC style invocations where we don't want to wait for an
+    #     ACK from the server before sending the last partial segment
+    #     Buffering is recommended in a browser or file transfer style environment
+    #     where multiple sends are expected during a single response
+    #     Default: true
+    #
+    #   :connect_retry_count [Fixnum]
+    #     Number of times to retry connecting when a connection fails
+    #     Default: 10
+    #
+    #   :connect_retry_interval [Float]
+    #     Number of seconds between connection retry attempts after the first failed attempt
+    #     Default: 0.5
+    #
+    # Example
+    #   client = ResilientSocket::TCPClient.new(
+    #     :server                 => 'server:3300',
+    #     :connect_retry_interval => 0.1,
+    #     :connect_retry_count    => 5
+    #   )
+    #
+    #   client.retry_on_connection_failure do
+    #     client.send('Update the database')
+    #   end
+    #
+    #   response = client.read(20)
+    #   puts "Received: #{response}"
+    #   client.close
+    def initialize(parameters={})
+      params = parameters.dup
+      @read_timeout = (params.delete(:read_timeout) || 60.0).to_f
+      @connect_timeout = (params.delete(:connect_timeout) || (@read_timeout/2)).to_f
+      buffered = params.delete(:buffered)
+      @buffered = buffered.nil? ? true : buffered
+      @connect_retry_count = params.delete(:connect_retry_count) || 10
+      @connect_retry_interval = (params.delete(:connect_retry_interval) || 0.5).to_f
+
+      unless @servers = params[:servers]
+        raise "Missing mandatory :server or :servers" unless server = params.delete(:server)
+        @servers = [ server ]
+      end
+      @logger = SemanticLogger::Logger.new("#{self.class.name} #{@servers.inspect}", params[:log_level] || SemanticLogger::Logger.default_level)
+      params.each_pair {|k,v| @logger.warn "Ignoring unknown option #{k} = #{v}"}
+
+      # Connect to the Server
+      connect
+    end
+
+    # Connect to the TCP server
+    #
+    # Raises ConnectionTimeout when the time taken to create a connection
+    #        exceeds the :connect_timeout
+    # Raises ConnectionFailure whenever Socket raises an error such as Error::EACCESS etc, see Socket#connect for more information
+    #
+    # Error handling is implemented as follows:
+    # 1. TCP Socket Connect failure:
+    #    Cannot reach server
+    #    Server is being restarted, or is not running
+    #    Retry 50 times every 100ms before raising a ConnectionFailure
+    #    - Means all calls to #connect will take at least 5 seconds before failing if the server is not running
+    #    - Allows hot restart of server process if it restarts within 5 seconds
+    #
+    # 2. TCP Socket Connect timeout:
+    #    Timed out after 5 seconds trying to connect to the server
+    #    Usually means server is busy or the remote server disappeared off the network recently
+    #    No retry, just raise a ConnectionTimeout
+    def connect
+      retries = 0
+      @logger.benchmark_info "Connected to server" do
+        begin
+          # TODO Implement failover to second server if connect fails
+          @server = @servers.first
+
+          host_name, port = @server.split(":")
+          port = port.to_i
+          address = Socket.getaddrinfo('localhost', nil, Socket::AF_INET)
+
+          socket = Socket.new(Socket.const_get(address[0][0]), Socket::SOCK_STREAM, 0)
+          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) unless @buffered
+
+          # http://stackoverflow.com/questions/231647/how-do-i-set-the-socket-timeout-in-ruby
+          begin
+            socket_address = Socket.pack_sockaddr_in(port, address[0][3])
+            socket.connect_nonblock(socket_address)
+          rescue Errno::EINPROGRESS
+            resp = IO.select(nil, [socket], nil, @connect_timeout)
+            raise(ConnectionTimeout.new("Timedout after #{@connect_timeout} seconds trying to connect to #{host_name}:#{port}")) unless resp
+            begin
+              socket_address = Socket.pack_sockaddr_in(port, address[0][3])
+              socket.connect_nonblock(socket_address)
+            rescue Errno::EISCONN
+            end
+          end
+          @socket = socket
+
+        rescue SystemCallError => exception
+          if retries < @connect_retry_count
+            retries += 1
+            @logger.warn "Connection failure: #{exception.class}: #{exception.message}. Retry: #{retries}"
+            sleep @connect_retry_interval
+            retry
+          end
+          @logger.error "Connection failure: #{exception.class}: #{exception.message}. Giving up after #{retries} retries"
+          raise ConnectionFailure.new("After #{retries} attempts: #{exception.class}: #{exception.message}")
+        end
+      end
+      self.user_data = nil
+      true
+    end
+
+    # Send data to the server
+    #
+    # Use #with_retry to add resilience to the #send method
+    #
+    # Raises ConnectionFailure whenever the send fails
+    #        For a description of the errors, see Socket#write
+    #
+    def send(data)
+      @logger.trace("==> Sending", data)
+      @logger.benchmark_debug("==> #send Sent #{data.length} bytes") do
+        begin
+          @socket.write(data)
+        rescue SystemCallError => exception
+          @logger.warn "#send Connection failure: #{exception.class}: #{exception.message}"
+          close
+          raise ConnectionFailure.new("Send Connection failure: #{exception.class}: #{exception.message}")
+        end
+      end
+    end
+
+    # Send data with retry logic
+    #
+    # On a connection failure, it will close the connection and retry the block
+    # Returns immediately on exception ReadTimeout
+    #
+    # Note this method should only wrap a single standalone call to the server
+    #      since it will automatically retry the entire block every time a
+    #      connection failure is experienced
+    #
+    # Error handling is implemented as follows:
+    #    Network failure during send of either the header or the body
+    #    Since the entire message was not sent it is assumed that it will not be processed
+    #    Close socket
+    #    Retry 1 time using a new connection before raising a ConnectionFailure
+    #
+    # Example of a resilient request that could _modify_ data at the server:
+    #
+    # # Only the send is within the retry block since we cannot re-send once
+    # # the send was successful
+    #
+    # Example of a resilient _read-only_ request:
+    #
+    # # Since the send can be sent many times it is safe to also put the receive
+    # # inside the retry block
+    #
+    def retry_on_connection_failure
+      retries = 0
+      begin
+        connect if closed?
+        yield(self)
+      rescue ConnectionFailure => exception
+        close
+        if retries < 3
+          retries += 1
+          @logger.warn "#retry_on_connection_failure Connection failure: #{exception.message}. Retry: #{retries}"
+          connect
+          retry
+        end
+        @logger.error "#retry_on_connection_failure Connection failure: #{exception.class}: #{exception.message}. Giving up after #{retries} retries"
+        raise ConnectionFailure.new("After #{retries} retry_on_connection_failure attempts: #{exception.class}: #{exception.message}")
+      rescue Exception => exc
+        # With any other exception we have to close the connection since the connection
+        # is now in an unknown state
+        close
+        raise exc
+      end
+    end
+
+    # 4. TCP receive timeout:
+    #    Send was successful but receive timed out after X seconds (for example 10 seconds)
+    #    No data or partial data received ( for example header but no body )
+    #    Close socket
+    #    Don't retry since it could result in duplicating the request
+    #    No retry, just raise a ReadTimeout
+    #
+    # Parameters
+    #   maxlen [Fixnum]
+    #     The Maximum number of bytes to return
+    #     Very often less than maxlen bytes will be returned
+    #
+    #   timeout [Float]
+    #     Optional: Override the default read timeout for this read
+    #     Number of seconds before raising ReadTimeout when no data has
+    #     been returned
+    #     Default: :read_timeout supplied to #initialize
+    def read(maxlen, buffer=nil, timeout=nil)
+      buffer ||= ''
+      @logger.benchmark_debug("<== #read Received upto #{maxlen} bytes") do
+        # Block on data to read for @read_timeout seconds
+        begin
+          ready = IO.select([@socket], nil, [@socket], timeout || @read_timeout)
+          unless ready
+            @logger.warn "#read Timeout waiting for server to reply"
+            close
+            raise ReadTimeout.new("Timedout after #{timeout || @read_timeout} seconds trying to read from #{@server}")
+          end
+        rescue IOError => exception
+          @logger.warn "#read Connection failure while waiting for data: #{exception.class}: #{exception.message}"
+          close
+          raise ConnectionFailure, "#{exception.class}: #{exception.message}"
+        end
+
+        # Read data from socket
+        begin
+          @socket.sysread(maxlen, buffer)
+          @logger.trace("<== #read Received", buffer)
+        rescue SystemCallError, IOError => exception
+          @logger.warn "#read Connection failure while reading data: #{exception.class}: #{exception.message}"
+          close
+          raise ConnectionFailure, "#{exception.class}: #{exception.message}"
+        end
+      end
+      buffer
+    end
+
+    # Close the socket
+    #
+    # Logs a warning if an error occurs trying to close the socket
+    def close
+      @socket.close unless @socket.closed?
+    rescue IOError => exception
+      @logger.warn "IOError when attempting to close socket: #{exception.class}: #{exception.message}"
+    end
+
+    # Returns whether the socket is closed
+    def closed?
+      @socket.closed?
+    end
+
+    # See: Socket#setsockopt
+    def setsockopt(level, optname, optval)
+      @socket.setsockopt(level, optname, optval)
+    end
+
+  end
+
+end

data/lib/resilient_socket/version.rb

@@ -0,0 +1,3 @@
+module ResilientSocket #:nodoc
+  VERSION = "0.0.2"
+end

data/lib/resilient_socket.rb

@@ -0,0 +1,8 @@
+require 'socket'
+require 'semantic_logger'
+
+require 'resilient_socket/version'
+require 'resilient_socket/exceptions'
+module ResilientSocket
+  autoload :TCPClient, 'resilient_socket/tcp_client'
+end

data/nbproject/private/private.properties

@@ -0,0 +1,2 @@
+file.reference.resilient_socket-lib=/Users/rmorrison/Sandbox/resilient_socket/lib
+file.reference.resilient_socket-test=/Users/rmorrison/Sandbox/resilient_socket/test

data/nbproject/private/rake-d.txt

@@ -0,0 +1,4 @@
+clean=Remove any temporary products.
+clobber=Remove any generated file.
+gem=Build gem
+test=Run Test Suite

data/nbproject/project.properties

@@ -0,0 +1,7 @@
+file.reference.resilient_socket-lib=lib
+file.reference.resilient_socket-test=test
+main.file=
+platform.active=Ruby
+source.encoding=UTF-8
+src.dir=${file.reference.resilient_socket-lib}
+test.src.dir=${file.reference.resilient_socket-test}

data/nbproject/project.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://www.netbeans.org/ns/project/1">
+    <type>org.netbeans.modules.ruby.rubyproject</type>
+    <configuration>
+        <data xmlns="http://www.netbeans.org/ns/ruby-project/1">
+            <name>resilient_socket</name>
+            <source-roots>
+                <root id="src.dir"/>
+            </source-roots>
+            <test-roots>
+                <root id="test.src.dir"/>
+            </test-roots>
+        </data>
+    </configuration>
+</project>

data/test/simple_tcp_server.rb

@@ -0,0 +1,114 @@
+require 'rubygems'
+require 'socket'
+require 'bson'
+require 'semantic_logger'
+
+# Read the bson document, returning nil if the IO is closed
+# before receiving any data or a complete BSON document
+def read_bson_document(io)
+  bytebuf = BSON::ByteBuffer.new
+  # Read 4 byte size of following BSON document
+  bytes = io.read(4)
+  return unless bytes
+  # Read BSON document
+  sz = bytes.unpack("V")[0]
+  bytebuf.append!(bytes)
+  bytes = io.read(sz-4)
+  return unless bytes
+  bytebuf.append!(bytes)
+  return BSON.deserialize(bytebuf)
+end
+
+# Simple single threaded server for testing purposes using a local socket
+# Sends and receives BSON Messages
+class SimpleTCPServer
+  attr_reader :thread
+  def initialize(port = 2000)
+    start(port)
+  end
+
+  def start(port)
+    @server = TCPServer.open(port)
+    @logger = SemanticLogger::Logger.new(self.class)
+
+    @thread = Thread.new do
+      loop do
+        @logger.debug "Waiting for a client to connect"
+
+        # Wait for a client to connect
+        on_request(@server.accept)
+      end
+    end
+  end
+
+  def stop
+    if @thread
+      @thread.kill
+      @thread.join
+      @thread = nil
+    end
+    begin
+      @server.close if @server
+    rescue IOError
+    end
+  end
+
+  # Called for each message received from the client
+  # Returns a Hash that is sent back to the caller
+  def on_message(message)
+    case message['action']
+    when 'test1'
+      { 'result' => 'test1' }
+    when 'sleep'
+      sleep message['duration'] || 1
+      { 'result' => 'sleep' }
+    when 'fail'
+      if message['attempt'].to_i >= 2
+        { 'result' => 'fail' }
+      else
+        nil
+      end
+    else
+      { 'result' => "Unknown action: #{message['action']}" }
+    end
+  end
+
+  # Called for each client connection
+  # In a real server each request would be handled in a separate thread
+  def on_request(client)
+    @logger.debug "Client connected, waiting for data from client"
+
+    while(request = read_bson_document(client)) do
+      @logger.debug "\n****************** Received request"
+      @logger.trace 'Request', request
+      break unless request
+
+      if reply = on_message(request)
+        @logger.debug "Sending Reply"
+        @logger.trace 'Reply', reply
+        client.print(BSON.serialize(reply))
+      else
+        @logger.debug "Closing client since no reply is being sent back"
+        @server.close
+        client.close
+        @logger.debug "Server closed"
+        #@thread.kill
+        @logger.debug "thread killed"
+        start(2000)
+        @logger.debug "Server Restarted"
+        break
+      end
+    end
+    # Disconnect from the client
+    client.close
+    @logger.debug "Disconnected from the client"
+  end
+
+end
+
+if $0 == __FILE__
+  SemanticLogger::Logger.default_level = :trace
+  SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new(STDOUT)
+  server = SimpleTCPServer.new(2000)
+  server.thread.join
+end

data/test/tcp_client_test.rb

@@ -0,0 +1,101 @@
+# Allow test to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH.unshift File.dirname(__FILE__)
+
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'resilient_socket'
+require 'simple_tcp_server'
+
+SemanticLogger::Logger.default_level = :trace
+SemanticLogger::Logger.appenders << SemanticLogger::Appender::File.new('test.log')
+
+# Unit Test for ResilientSocket::TCPClient
+class TCPClientTest < Test::Unit::TestCase
+  context ResilientSocket::TCPClient do
+
+    context "without server" do
+      should "raise exception when cannot reach server after 5 retries" do
+        exception = assert_raise ResilientSocket::ConnectionFailure do
+          ResilientSocket::TCPClient.new(
+            :server                 => 'localhost:3300',
+            :connect_retry_interval => 0.1,
+            :connect_retry_count    => 5)
+        end
+        assert_match /After 5 attempts: Errno::ECONNREFUSED/, exception.message
+      end
+
+    end
+
+    context "with server" do
+      setup do
+        @server = SimpleTCPServer.new(2000)
+        @server_name = 'localhost:2000'
+      end
+
+      teardown do
+        @server.stop if @server
+      end
+
+      # Not sure how to automatically test this, need a server that is running
+      # but does not respond in time to a connect request
+      #
+      #should "timeout on connect" do
+      #  exception = assert_raise ResilientSocket::ConnectionTimeout do
+      #    ResilientSocket::TCPClient.new(
+      #      :server          => @server_name,
+      #      :connect_timeout => 0.1
+      #    )
+      #  end
+      #  assert_match /Timedout after/, exception.message
+      #end
+
+      context "with client connection" do
+        setup do
+          @read_timeout = 3.0
+          @client = ResilientSocket::TCPClient.new(
+            :server          => @server_name,
+            :read_timeout    => @read_timeout
+          )
+        end
+
+        def teardown
+          @client.close if @client
+        end
+
+        should "successfully send and receive data" do
+          request = { 'action' => 'test1' }
+          @client.send(BSON.serialize(request))
+          reply = read_bson_document(@client)
+          assert_equal 'test1', reply['result']
+        end
+
+        should "timeout on receive" do
+          request = { 'action' => 'sleep', 'duration' => @read_timeout + 0.5}
+          @client.send(BSON.serialize(request))
+
+          exception = assert_raise ResilientSocket::ReadTimeout do
+            # Read 4 bytes from server
+            @client.read(4)
+          end
+          assert_match /Timedout after #{@read_timeout} seconds trying to read from #{@server_name}/, exception.message
+        end
+
+        should "retry on connection failure" do
+          attempt = 0
+          reply = @client.retry_on_connection_failure do
+            request = { 'action' => 'fail', 'attempt' => (attempt+=1) }
+            @client.send(BSON.serialize(request))
+            # Note: Do not put the read in this block if it should never send the
+            #       same request twice to the server
+            read_bson_document(@client)
+          end
+          assert_equal 'fail', reply['result']
+        end
+
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: resilient_socket
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Reid Morrison
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: semantic_logger
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Resilient TCP Socket Client with built-in timeouts, retries, and logging
+email:
+- reidmo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/resilient_socket/exceptions.rb
+- lib/resilient_socket/tcp_client.rb
+- lib/resilient_socket/version.rb
+- lib/resilient_socket.rb
+- LICENSE.txt
+- nbproject/private/private.properties
+- nbproject/private/rake-d.txt
+- nbproject/project.properties
+- nbproject/project.xml
+- Rakefile
+- README.md
+- resilient_socket-0.0.1.gem
+- test/simple_tcp_server.rb
+- test/tcp_client_test.rb
+- test.log
+homepage: https://github.com/ClarityServices/resilient_socket
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A Resilient TCP Socket Client with built-in timeouts, retries, and logging
+test_files: []