tcp-client 0.5.1 → 0.9.0

data/lib/tcp-client/errors.rb

@@ -1,70 +1,145 @@
 # frozen_string_literal: true
 
 class TCPClient
-  class NoOpenSSL < RuntimeError
+  #
+  # Raised when a SSL connection should be establshed but the OpenSSL gem is not available.
+  #
+  class NoOpenSSLError < RuntimeError
     def initialize
       super('OpenSSL is not available')
     end
   end
 
-  class NoBlockGiven < ArgumentError
+  #
+  # Raised when a method requires a callback block but no such block is specified.
+  #
+  class NoBlockGivenError < ArgumentError
     def initialize
       super('no block given')
     end
   end
 
-  class InvalidDeadLine < ArgumentError
+  #
+  # Raised when a an invalid timeout value was specified.
+  #
+  class InvalidDeadLineError < ArgumentError
     def initialize(timeout)
       super("invalid deadline - #{timeout}")
     end
   end
 
-  class UnknownAttribute < ArgumentError
+  #
+  # Raised by {Configuration} when an undefined attribute should  be set.
+  #
+  class UnknownAttributeError < ArgumentError
     def initialize(attribute)
       super("unknown attribute - #{attribute}")
     end
   end
 
-  class NotAnException < TypeError
+  #
+  # Raised when a given timeout exception parameter is not an exception class.
+  #
+  class NotAnExceptionError < TypeError
     def initialize(object)
       super("exception class required - #{object.inspect}")
     end
   end
 
-  class NotConnected < IOError
+  #
+  # Base exception class for all network related errors.
+  #
+  # Will be raised for any system level network error when {Configuration.normalize_network_errors} is configured.
+  #
+  # You should catch this exception class when you like to handle any relevant {TCPClient} error.
+  #
+  class NetworkError < StandardError
+  end
+
+  #
+  # Raised when a {TCPClient} instance should read/write from/to the network but is not connected.
+  #
+  class NotConnectedError < NetworkError
     def initialize
       super('client not connected')
     end
   end
 
-  class TimeoutError < IOError
+  #
+  # Base exception class for a detected timeout.
+  #
+  # You should catch this exception class when you like to handle any timeout error.
+  #
+  class TimeoutError < NetworkError
+    #
+    # Initializes the instance with an optional message.
+    #
+    # the message will be generated from {#action} when not specified.
+    # @overload initialize
+    # @overload initialize(message)
+    #
+    # @param message [String, #to_s] the error message
+    #
     def initialize(message = nil)
       super(message || "unable to #{action} in time")
     end
 
+    #
+    # @return [Symbol] the action which timed out
+    #
     def action
       :process
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.connect} timed out.
+  #
   class ConnectTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:connect+
+    #
     def action
       :connect
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.read} timed out.
+  #
   class ReadTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:read+
+    #
     def action
       :read
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.write} timed out.
+  #
   class WriteTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:write+
+    #
     def action
       :write
     end
   end
 
-  Timeout = TimeoutError # backward compatibility
-  deprecate_constant(:Timeout)
+  NoOpenSSL = NoOpenSSLError # @!visibility private
+  NoBlockGiven = NoBlockGivenError # @!visibility private
+  InvalidDeadLine = InvalidDeadLineError # @!visibility private
+  UnknownAttribute = UnknownAttributeError # @!visibility private
+  NotAnException = NotAnExceptionError # @!visibility private
+  NotConnected = NotConnectedError # @!visibility private
+  deprecate_constant(
+    :NoOpenSSL,
+    :NoBlockGiven,
+    :InvalidDeadLine,
+    :UnknownAttribute,
+    :NotAnException,
+    :NotConnected
+  )
 end

data/lib/tcp-client/mixin/io_with_deadline.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
-module IOWithDeadlineMixin
+# @!visibility private
+module IOWithDeadlineMixin # :nodoc:
   def self.included(mod)
     methods = mod.instance_methods
     if methods.index(:wait_writable) && methods.index(:wait_readable)
       mod.include(ViaWaitMethod)
+    elsif methods.index(:to_io)
+      mod.include(ViaIOWaitMethod)
     else
       mod.include(ViaSelect)
     end
@@ -12,6 +15,13 @@ module IOWithDeadlineMixin
 
   def read_with_deadline(bytes_to_read, deadline, exception)
     raise(exception) unless deadline.remaining_time
+    if bytes_to_read.nil?
+      return(
+        with_deadline(deadline, exception) do
+          read_nonblock(65_536, exception: false)
+        end
+      )
+    end
     result = ''.b
     while result.bytesize < bytes_to_read
       read =
@@ -59,6 +69,25 @@ module IOWithDeadlineMixin
     end
   end
 
+  module ViaIOWaitMethod
+    private def with_deadline(deadline, exception)
+      loop do
+        case ret = yield
+        when :wait_writable
+          remaining_time = deadline.remaining_time or raise(exception)
+          raise(exception) if to_io.wait_writable(remaining_time).nil?
+        when :wait_readable
+          remaining_time = deadline.remaining_time or raise(exception)
+          raise(exception) if to_io.wait_readable(remaining_time).nil?
+        else
+          return ret
+        end
+      end
+    rescue Errno::ETIMEDOUT
+      raise(exception)
+    end
+  end
+
   module ViaSelect
     private def with_deadline(deadline, exception)
       loop do
@@ -78,5 +107,5 @@ module IOWithDeadlineMixin
     end
   end
 
-  private_constant(:ViaWaitMethod, :ViaSelect)
+  private_constant(:ViaWaitMethod, :ViaIOWaitMethod, :ViaSelect)
 end

data/lib/tcp-client/ssl_socket.rb

@@ -18,6 +18,7 @@ class TCPClient
       super(socket, create_context(ssl_params))
       self.sync_close = true
       self.hostname = address.hostname
+      check_new_session if @new_session
       deadline.valid? ? connect_with_deadline(deadline, exception) : connect
       post_connection_check(address.hostname) if should_verify?(ssl_params)
     end
@@ -25,7 +26,19 @@ class TCPClient
     private
 
     def create_context(ssl_params)
-      OpenSSL::SSL::SSLContext.new.tap { |ctx| ctx.set_params(ssl_params) }
+      @new_session = nil
+      ::OpenSSL::SSL::SSLContext.new.tap do |ctx|
+        ctx.set_params(ssl_params)
+        ctx.session_cache_mode = CONTEXT_CACHE_MODE
+        ctx.session_new_cb = proc { |_, sess| @new_session = sess }
+      end
+    end
+
+    def check_new_session
+      time = @new_session.time.to_f + @new_session.timeout
+      if Process.clock_gettime(Process::CLOCK_REALTIME) < time
+        self.session = @new_session
+      end
     end
 
     def connect_with_deadline(deadline, exception)
@@ -33,8 +46,13 @@ class TCPClient
     end
 
     def should_verify?(ssl_params)
-      ssl_params[:verify_mode] != OpenSSL::SSL::VERIFY_NONE
+      ssl_params[:verify_mode] != ::OpenSSL::SSL::VERIFY_NONE &&
+        context.verify_hostname
     end
+
+    CONTEXT_CACHE_MODE =
+      ::OpenSSL::SSL::SSLContext::SESSION_CACHE_CLIENT |
+        ::OpenSSL::SSL::SSLContext::SESSION_CACHE_NO_INTERNAL_STORE
   end
 
   private_constant(:SSLSocket)

data/lib/tcp-client/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 class TCPClient
-  VERSION = '0.5.1'
+  #
+  # The current gem version.
+  #
+  VERSION = '0.9.0'
 end

data/lib/tcp-client.rb

@@ -9,102 +9,272 @@ require_relative 'tcp-client/configuration'
 require_relative 'tcp-client/default_configuration'
 require_relative 'tcp-client/version'
 
+#
+# Client class to communicate with a server via TCP w/o SSL.
+#
+# All connect/read/write actions can be monitored to ensure that all actions
+# terminate before given time limits - or raise an exception.
+#
+# @example - request to Google.com and limit all network interactions to 1.5 seconds
+#   TCPClient.with_deadline(1.5, 'www.google.com:443') do |client|
+#     client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
+#     client.read(12)
+#   end
+#   # => "HTTP/1.1 200"
+#
+#
 class TCPClient
-  def self.open(address, configuration = Configuration.default)
+  #
+  # Creates a new instance which is connected to the server on the given
+  # address and uses the given or the {.default_configuration}.
+  #
+  # If an optional block is given, then the block's result is returned and the
+  # connection will be closed when the block execution ends.
+  # This can be used to create an ad-hoc connection which is garanteed to be
+  # closed.
+  #
+  # If no block is giiven the connected client instance is returned.
+  # This can be used as a shorthand to create & connect a client.
+  #
+  # @param address [Address, String, Addrinfo, Integer] the address to connect to, see {Address#initialize} for valid formats
+  # @param configuration [Configuration] the {Configuration} to be used for this instance
+  #
+  # @yieldparam client [TCPClient] the connected client
+  # @yieldreturn [Object] any result
+  #
+  # @return [Object, TCPClient] the block result or the connected client
+  #
+  # @see #connect
+  #
+  def self.open(address, configuration = nil)
     client = new
     client.connect(Address.new(address), configuration)
-    return client unless block_given?
-    begin
-      yield(client)
-    ensure
-      client.close
+    block_given? ? yield(client) : client
+  ensure
+    client.close if block_given?
+  end
+
+  #
+  # Yields a new instance which is connected to the server on the given
+  # address and uses the given or the {.default_configuration}.
+  # It ensures to close the connection when the block execution ends.
+  # It also limits all {#read} and {#write} actions within the block to a given
+  # time.
+  #
+  # This can be used to create an ad-hoc connection which is garanteed to be
+  # closed and which read/write calls should not last longer than the timeout
+  # limit.
+  #
+  # @param timeout [Numeric] maximum time in seconds for all {#read} and {#write} calls within the block
+  # @param address [Address, String, Addrinfo, Integer] the address to connect to, see {Address#initialize} for valid formats
+  # @param configuration [Configuration] the {Configuration} to be used for this instance
+  #
+  # @yieldparam client [TCPClient] the connected client
+  # @yieldreturn [Object] any result
+  #
+  # @return [Object] the block result
+  #
+  # @see #with_deadline
+  #
+  def self.with_deadline(timeout, address, configuration = nil)
+    client = nil
+    raise(NoBlockGivenError) unless block_given?
+    address = Address.new(address)
+    client = new
+    client.with_deadline(timeout) do
+      yield(client.connect(address, configuration))
     end
+  ensure
+    client&.close
   end
 
-  attr_reader :address, :configuration
+  #
+  # @return [Address] the address used for this client
+  #
+  attr_reader :address
 
-  def initialize
-    @socket = @address = @deadline = @configuration = nil
+  #
+  # @return [Configuration] the configuration used by this client.
+  #
+  attr_reader :configuration
+
+  #
+  # @attribute [r] closed?
+  # @return [Boolean] true when the connection is closed, false when connected
+  #
+  def closed?
+    @socket.nil? || @socket.closed?
   end
 
+  #
+  # @return [String] the currently used address as text.
+  #
+  # @see Address#to_s
+  #
   def to_s
     @address&.to_s || ''
   end
 
-  def connect(address, configuration, exception: nil)
-    raise(NoOpenSSL) if configuration.ssl? && !defined?(SSLSocket)
-    close
+  #
+  # Establishes a new connection to a given address.
+  #
+  # It accepts a connection-specific configuration or uses the global {.default_configuration}. The {#configuration} used by this instance will
+  # be a copy of the configuration used for this method call. This allows to
+  # configure the behavior per connection.
+  #
+  # @param address [Address, String, Addrinfo, Integer] the address to connect to, see {Address#initialize} for valid formats
+  # @param configuration [Configuration] the {Configuration} to be used for this instance
+  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +connect_timeout+.
+  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +connect_timeout_error+.
+  #
+  # @return [self]
+  #
+  # @raise {NoOpenSSLError} if SSL should be used but OpenSSL is not avail
+  #
+  def connect(address, configuration = nil, timeout: nil, exception: nil)
+    close if @socket
+    raise(NoOpenSSLError) if configuration.ssl? && !defined?(SSLSocket)
     @address = Address.new(address)
-    @configuration = configuration.dup.freeze
-    @socket = create_socket(exception)
+    @configuration = (configuration || Configuration.default).dup
+    @socket = create_socket(timeout, exception)
     self
   end
 
+  #
+  # Close the current connection.
+  #
+  # @return [self]
+  #
   def close
     @socket&.close
     self
-  rescue IOError
+  rescue *NETWORK_ERRORS
     self
   ensure
     @socket = @deadline = nil
   end
 
-  def closed?
-    @socket.nil? || @socket.closed?
-  end
-
+  #
+  # Executes a block with a given overall timeout.
+  #
+  # When you like to ensure that a complete read/write communication sequence
+  # with the server is finished before a given amount of time you can use this
+  # method to define such a deadline.
+  #
+  # @example - ensure to send a welcome message and receive a 64 byte answer from server
+  #   answer = client.with_deadline(2.5) do
+  #     client.write('Helo')
+  #     client.read(64)
+  #   end
+  #
+  # @param timeout [Numeric] maximum time in seconds for all {#read} and {#write} calls within the block
+  #
+  # @yieldparam client [TCPClient] self
+  #
+  # @return [Object] result of the given block
+  #
+  # @raise [NoBlockGivenError] if the block is missing
+  #
   def with_deadline(timeout)
     previous_deadline = @deadline
-    raise(NoBlockGiven) unless block_given?
+    raise(NoBlockGivenError) unless block_given?
     @deadline = Deadline.new(timeout)
-    raise(InvalidDeadLine, timeout) unless @deadline.valid?
+    raise(InvalidDeadLineError, timeout) unless @deadline.valid?
     yield(self)
   ensure
     @deadline = previous_deadline
   end
 
-  def read(nbytes, timeout: nil, exception: nil)
-    raise(NotConnected) if closed?
-    timeout.nil? && @deadline and
-      return read_with_deadline(nbytes, @deadline, exception)
-    deadline = Deadline.new(timeout || @configuration.read_timeout)
-    return @socket.read(nbytes) unless deadline.valid?
-    read_with_deadline(nbytes, deadline, exception)
+  #
+  # Read the given nbytes or the next available buffer from server.
+  #
+  # @param nbytes [Integer] the number of bytes to read
+  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +read_timeout+.
+  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +read_timeout_error+.
+  #
+  # @return [String] buffer read
+  #
+  # @raise [NotConnectedError] if {#connect} was not called before
+  #
+  def read(nbytes = nil, timeout: nil, exception: nil)
+    raise(NotConnectedError) if closed?
+    deadline = create_deadline(timeout, configuration.read_timeout)
+    return stem_errors { @socket.read(nbytes) } unless deadline.valid?
+    exception ||= configuration.read_timeout_error
+    stem_errors(exception) do
+      @socket.read_with_deadline(nbytes, deadline, exception)
+    end
   end
 
-  def write(*msg, timeout: nil, exception: nil)
-    raise(NotConnected) if closed?
-    timeout.nil? && @deadline and
-      return write_with_deadline(msg, @deadline, exception)
-    deadline = Deadline.new(timeout || @configuration.read_timeout)
-    return @socket.write(*msg) unless deadline.valid?
-    write_with_deadline(msg, deadline, exception)
+  #
+  # Write the given messages to the server.
+  #
+  # @param messages [Array<String>] messages to write
+  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +write_timeout+.
+  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +write_timeout_error+.
+  #
+  # @return [Integer] bytes written
+  #
+  # @raise [NotConnectedError] if {#connect} was not called before
+  #
+  def write(*messages, timeout: nil, exception: nil)
+    raise(NotConnectedError) if closed?
+    deadline = create_deadline(timeout, configuration.write_timeout)
+    return stem_errors { @socket.write(*messages) } unless deadline.valid?
+    exception ||= configuration.write_timeout_error
+    stem_errors(exception) do
+      messages.sum do |chunk|
+        @socket.write_with_deadline(chunk.b, deadline, exception)
+      end
+    end
   end
 
+  #
+  # Flush all internal buffers (write all through).
+  #
+  # @return [self]
+  #
   def flush
-    @socket.flush unless closed?
+    stem_errors { @socket&.flush }
     self
   end
 
   private
 
-  def create_socket(exception)
-    exception ||= @configuration.connect_timeout_error
-    deadline = Deadline.new(@configuration.connect_timeout)
-    @socket = TCPSocket.new(@address, @configuration, deadline, exception)
-    return @socket unless @configuration.ssl?
-    SSLSocket.new(@socket, @address, @configuration, deadline, exception)
+  def create_deadline(timeout, default)
+    timeout.nil? && @deadline ? @deadline : Deadline.new(timeout || default)
   end
 
-  def read_with_deadline(nbytes, deadline, exception)
-    exception ||= @configuration.read_timeout_error
-    @socket.read_with_deadline(nbytes, deadline, exception)
+  def create_socket(timeout, exception)
+    deadline = create_deadline(timeout, configuration.connect_timeout)
+    exception ||= configuration.connect_timeout_error
+    stem_errors(exception) do
+      @socket = TCPSocket.new(address, configuration, deadline, exception)
+      return @socket unless configuration.ssl?
+      SSLSocket.new(@socket, address, configuration, deadline, exception)
+    end
   end
 
-  def write_with_deadline(msg, deadline, exception)
-    exception ||= @configuration.write_timeout_error
-    msg.sum do |chunk|
-      @socket.write_with_deadline(chunk.b, deadline, exception)
-    end
+  def stem_errors(except = nil)
+    yield
+  rescue *NETWORK_ERRORS => e
+    raise unless configuration.normalize_network_errors
+    (except && e.is_a?(except)) ? raise : raise(NetworkError, e)
   end
+
+  NETWORK_ERRORS =
+    [
+      Errno::EADDRNOTAVAIL,
+      Errno::ECONNABORTED,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::EINVAL,
+      Errno::ENETUNREACH,
+      Errno::EPIPE,
+      IOError,
+      SocketError
+    ].tap do |errors|
+      errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
+    end.freeze
 end

data/rakefile.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
 require 'rake/clean'
-require 'rake/testtask'
 require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
 
 $stdout.sync = $stderr.sync = true
 
-CLOBBER << 'prj'
-
+CLOBBER << 'prj' << 'doc'
 task(:default) { exec('rake --tasks') }
-
-Rake::TestTask.new(:test) do |task|
-  task.pattern = 'test/**/*_test.rb'
-  task.warning = task.verbose = true
-end
+RSpec::Core::RakeTask.new { |task| task.ruby_opts = %w[-w] }
+YARD::Rake::YardocTask.new { |task| task.stats_options = %w[--list-undoc] }

data/sample/google.rb

@@ -2,21 +2,20 @@
 
 require_relative '../lib/tcp-client'
 
-TCPClient.configure(
-  connect_timeout: 0.5, # seconds to connect the server
-  write_timeout: 0.25, # seconds to write a single data junk
-  read_timeout: 0.5 # seconds to read some bytes
-)
-
-# the following sequence is not allowed to last longer than 1.25 seconds:
-#   0.5 seconds to connect
-# + 0.25 seconds to write data
-# + 0.5 seconds to read a response
+# global configuration.
+# - 0.5 seconds to connect the server
+# - 0.25 seconds to write a single data junk
+# - 0.25 seconds to read some bytes
+TCPClient.configure do |cfg|
+  cfg.connect_timeout = 0.5
+  cfg.write_timeout = 0.25
+  cfg.read_timeout = 0.25
+end
 
+# request to Google:
+# - send a simple HTTP get request
+# - read 12 byte: "HTTP/1.1 " + 3 byte HTTP status code
 TCPClient.open('www.google.com:80') do |client|
-  # simple HTTP get request
-  pp client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
-
-  # read "HTTP/1.1 " + 3 byte HTTP status code
-  pp client.read(12)
+  p client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
+  p client.read(12)
 end