tcp-client 0.9.4 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 114da301d59fc9cf9c3d3bda508f4d23b5b4991877a5dc7504d4da97114f8e7f
-  data.tar.gz: 9d0815501de340b485cba157aff05097597948d023a7eca6c45a8ead3a4e3d0d
+  metadata.gz: 91bdfe4046f3e4baeefe4a140d7a2bdb0cac02d3c069102e9c574fe02e5ca1c8
+  data.tar.gz: e26cc5ce187d50aba43d06403730445f3605667a4cffc5d4c7105dd549ca4c9a
 SHA512:
-  metadata.gz: a560644d578cedccaf1e2665f518b3a6a4e225886cfc561a8b62087420d93b958ee4741d8efde3b456fa15ce24fd5ee2f6a1121b55855205ffae5abf17becf97
-  data.tar.gz: f1f0ed0b87f8ee9c9b376b6b567c45aecb204c5b3de044c97f6ba080071c3c8e70da8bca8cca2484d5ddec06df181ee4b007e9ed826045e205d77df38eefbbbd
+  metadata.gz: dfc647093949536fa3c040f9140ec5039a37934e1b77ccc3150f9c16a8de824123c7e8b374faa9479c5572a84f7cb9e08a051e356fe76e79d9245e10efd61bf4
+  data.tar.gz: 6046435c921660e284838c0e33559540f81de5f8b4c150ab63bf37ee72fc7605bc128d5c2b79d8ac7cb6cf657267bc445a4bef36103508ffaed4d6b0961d023c

data/README.md

@@ -27,11 +27,14 @@ cfg = TCPClient::Configuration.create(
 # - limit all network interactions to 1.5 seconds
 # - use the Configuration cfg
 # - send a simple HTTP get request
-# - read 12 byte: "HTTP/1.1 " + 3 byte HTTP status code
-TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
-  client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") # >= 40
-  client.read(12) # => "HTTP/1.1 200"
-end
+# - read the returned message and headers
+response =
+  TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
+    client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") #=> 40
+    client.readline("\r\n\r\n") #=> see response
+  end
+
+puts(response)
 ```
 
 For more samples see [the samples dir](https://github.com/mblumtritt/tcp-client/tree/main/sample)
@@ -58,7 +61,7 @@ To install the gem globally use:
 gem install tcp-client
 ```
 
-After that you need only a single line of code in your project to have all tools on board:
+After that you need only a single line of code in your project to have on board:
 
 ```ruby
 require 'tcp-client'

data/lib/tcp-client/address.rb

@@ -41,7 +41,7 @@ class TCPClient
     #   @param addrinfo [Addrinfo] containing the addressed host and port
     #
     # @overload initialize(port)
-    #   Adresses the port on the local machine.
+    #   Addresses the port on the local machine.
     #
     #   @example create an Address for localhost on port 80
     #     Address.new(80)

data/lib/tcp-client/configuration.rb

@@ -26,45 +26,29 @@ class TCPClient
     #   @example
     #     config = TCPClient::Configuration.create(buffered: false)
     #
-    #   @param options [Hash<Symbol,Object>] see {#initialize} for details
+    #   @param options [{Symbol => Object}] see {#initialize} for details
     #
     # @return [Configuration] the initialized configuration
     #
-    def self.create(options = {})
+    def self.create(options = nil)
       configuration = new(options)
       yield(configuration) if block_given?
       configuration
     end
 
     #
-    # Intializes the instance with given options.
+    # Initializes and optionally configures the instance with given options.
     #
-    # @param options [Hash<Symbol,Object>]
-    # @option options [Boolean] :buffered, see {#buffered}
-    # @option options [Boolean] :keep_alive, see {#keep_alive}
-    # @option options [Boolean] :reverse_lookup, see {#reverse_lookup}
-    # @option options [Hash<Symbol, Object>] :ssl_params, see {#ssl_params}
-    # @option options [Numeric] :connect_timeout, see {#connect_timeout}
-    # @option options [Class<Exception>] :connect_timeout_error, see
-    #   {#connect_timeout_error}
-    # @option options [Numeric] :read_timeout, see {#read_timeout}
-    # @option options [Class<Exception>] :read_timeout_error, see
-    #   {#read_timeout_error}
-    # @option options [Numeric] :write_timeout, see {#write_timeout}
-    # @option options [Class<Exception>] :write_timeout_error, see
-    #   {#write_timeout_error}
-    # @option options [Boolean] :normalize_network_errors, see
-    #   {#normalize_network_errors}
+    # @see #configure
     #
-    #
-    def initialize(options = {})
+    def initialize(options = nil)
       @buffered = @keep_alive = @reverse_lookup = true
       self.timeout = @ssl_params = nil
       @connect_timeout_error = ConnectTimeoutError
       @read_timeout_error = ReadTimeoutError
       @write_timeout_error = WriteTimeoutError
       @normalize_network_errors = false
-      options.each_pair { |attribute, value| set(attribute, value) }
+      configure(options) if options
     end
 
     # @!group Instance Attributes Socket Level
@@ -72,8 +56,8 @@ class TCPClient
     #
     # Enables/disables use of Socket-level buffering
     #
-    # @return [Boolean] wheter the connection is allowed to use internal buffers
-    #   (default) or not
+    # @return [Boolean] whether the connection is allowed to use internal
+    #   buffers (default) or not
     #
     attr_reader :buffered
 
@@ -84,7 +68,7 @@ class TCPClient
     #
     # Enables/disables use of Socket-level keep alive handling.
     #
-    # @return [Boolean] wheter the connection is allowed to use keep alive
+    # @return [Boolean] whether the connection is allowed to use keep alive
     #   signals (default) or not
     #
     attr_reader :keep_alive
@@ -96,7 +80,7 @@ class TCPClient
     #
     # Enables/disables address lookup.
     #
-    # @return [Boolean] wheter the connection is allowed to lookup the address
+    # @return [Boolean] whether the connection is allowed to lookup the address
     #   (default) or not
     #
     attr_reader :reverse_lookup
@@ -107,7 +91,7 @@ class TCPClient
 
     #
     # @!parse attr_reader :ssl?
-    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
+    # @return [Boolean] whether SSL is configured, see {#ssl_params}
     #
     def ssl?
       @ssl_params ? true : false
@@ -117,7 +101,7 @@ class TCPClient
     # Parameters used to initialize a SSL context. SSL/TLS will only be used if
     # this attribute is not `nil`.
     #
-    # @return [Hash<Symbol, Object>] SSL parameters for the SSL context
+    # @return [{Symbol => Object}] SSL parameters for the SSL context
     # @return [nil] if no SSL should be used (default)
     #
     attr_reader :ssl_params
@@ -226,7 +210,7 @@ class TCPClient
     # @attribute [w] timeout
     # Shorthand to set maximum time in seconds for all timeout monitoring.
     #
-    # @return [Numeric] maximum time in seconds for any actwion
+    # @return [Numeric] maximum time in seconds for any action
     # @return [nil] if all timeout monitoring should be disabled (default)
     #
     # @see #connect_timeout
@@ -239,7 +223,7 @@ class TCPClient
 
     #
     # @attribute [w] timeout_error
-    # Shorthand to set the exception class wich will by raised by any reached
+    # Shorthand to set the exception class which will by raised by any reached
     # timeout.
     #
     # @return [Class<Exception>] exception class raised
@@ -258,6 +242,8 @@ class TCPClient
 
     # @!endgroup
 
+    # @!group Other Instance Attributes
+
     #
     # Enables/disables if network exceptions should be raised as {NetworkError}.
     #
@@ -266,7 +252,7 @@ class TCPClient
     # manner. If this option is set to true all these error cases are raised as
     # {NetworkError} and can be easily captured.
     #
-    # @return [Boolean] wheter all network exceptions should be raised as
+    # @return [Boolean] whether all network exceptions should be raised as
     #   {NetworkError}, or not (default)
     #
     attr_reader :normalize_network_errors
@@ -275,12 +261,12 @@ class TCPClient
       @normalize_network_errors = value ? true : false
     end
 
+    # @!endgroup
+
     #
-    # Convert `self` to a Hash containing all attributes.
-    #
-    # @return [Hash<Symbol, Object>]
+    # @return [{Symbol => Object}] Hash containing all attributes
     #
-    # @see #initialize
+    # @see #configure
     #
     def to_h
       {
@@ -298,6 +284,33 @@ class TCPClient
       }
     end
 
+    #
+    # Configures the instance with given options Hash.
+    #
+    # @param options [{Symbol => Object}]
+    # @option options [Boolean] :buffered, see {#buffered}
+    # @option options [Boolean] :keep_alive, see {#keep_alive}
+    # @option options [Boolean] :reverse_lookup, see {#reverse_lookup}
+    # @option options [{Symbol => Object}] :ssl_params, see {#ssl_params}
+    # @option options [Numeric] :connect_timeout, see {#connect_timeout}
+    # @option options [Class<Exception>] :connect_timeout_error, see
+    #   {#connect_timeout_error}
+    # @option options [Numeric] :read_timeout, see {#read_timeout}
+    # @option options [Class<Exception>] :read_timeout_error, see
+    #   {#read_timeout_error}
+    # @option options [Numeric] :write_timeout, see {#write_timeout}
+    # @option options [Class<Exception>] :write_timeout_error, see
+    #   {#write_timeout_error}
+    # @option options [Boolean] :normalize_network_errors, see
+    #   {#normalize_network_errors}
+    #
+    # @return [Configuration] self
+    #
+    def configure(options)
+      options.each_pair { |attribute, value| set(attribute, value) }
+      self
+    end
+
     # @!visibility private
     def freeze
       @ssl_params.freeze

data/lib/tcp-client/default_configuration.rb

@@ -25,13 +25,13 @@ class TCPClient
     #     cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
     #   end
     #
-    # @param options [Hash] see {Configuration#initialize} for details
+    # @param options [Hash] see {Configuration#configure} for details
     #
     # @yieldparam cfg {Configuration} the new configuration
     #
     # @return [Configuration] the new default configuration
     #
-    def configure(options = {}, &block)
+    def configure(options = nil, &block)
       @default_configuration = Configuration.create(options, &block)
     end
   end
@@ -41,7 +41,7 @@ class TCPClient
       #
       # @!parse attr_reader :default
       # @return [Configuration] used by default if no dedicated configuration
-      # was specified
+      #   was specified
       #
       # @see TCPClient.open
       # @see TCPClient.with_deadline

data/lib/tcp-client/errors.rb

@@ -2,7 +2,7 @@
 
 class TCPClient
   #
-  # Raised when a SSL connection should be establshed but the OpenSSL gem is
+  # Raised when a SSL connection should be established but the OpenSSL gem is
   # not available.
   #
   class NoOpenSSLError < RuntimeError
@@ -38,7 +38,7 @@ class TCPClient
   #
   class UnknownAttributeError < ArgumentError
     #
-    # @param attribute [Object] the undefined atttribute
+    # @param attribute [Object] the undefined attribute
     #
     def initialize(attribute)
       super("unknown attribute - #{attribute}")

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

@@ -1,57 +1,80 @@
 # frozen_string_literal: true
 
-# @!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)
+class TCPClient
+  module IOWithDeadlineMixin
+    def self.included(mod)
+      methods = mod.instance_methods
+      return if methods.index(:wait_writable) && methods.index(:wait_readable)
+      mod.include(methods.index(:to_io) ? WaitWithIO : WaitWithSelect)
     end
-  end
 
-  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
-      )
+    def read_with_deadline(nbytes, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      return fetch_avail(deadline, exception) if nbytes.nil?
+      return ''.b if nbytes.zero?
+      @read_buffer ||= ''.b
+      while @read_buffer.bytesize < nbytes
+        read = fetch_next(deadline, exception) and next @read_buffer << read
+        close
+        break
+      end
+      fetch_slice(nbytes)
     end
-    result = ''.b
-    while result.bytesize < bytes_to_read
-      read =
-        with_deadline(deadline, exception) do
-          read_nonblock(bytes_to_read - result.bytesize, exception: false)
-        end
-      next result += read if read
-      close
-      break
+
+    def read_to_with_deadline(sep, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      @read_buffer ||= ''.b
+      while @read_buffer.index(sep).nil?
+        read = fetch_next(deadline, exception) and next @read_buffer << read
+        close
+        break
+      end
+      index = @read_buffer.index(sep)
+      return fetch_slice(index + sep.bytesize) if index
+      result = @read_buffer
+      @read_buffer = nil
+      result
     end
-    result
-  end
 
-  def write_with_deadline(data, deadline, exception)
-    raise(exception) unless deadline.remaining_time
-    return 0 if (size = data.bytesize).zero?
-    result = 0
-    loop do
-      written =
-        with_deadline(deadline, exception) do
-          write_nonblock(data, exception: false)
-        end
-      result += written
-      return result if result >= size
-      data = data.byteslice(written, data.bytesize - written)
+    def write_with_deadline(data, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      return 0 if (size = data.bytesize).zero?
+      result = 0
+      loop do
+        written =
+          with_deadline(deadline, exception) do
+            write_nonblock(data, exception: false)
+          end
+        (result += written) >= size and return result
+        data = data.byteslice(written, data.bytesize - written)
+      end
     end
-  end
 
-  module ViaWaitMethod
-    private def with_deadline(deadline, exception)
+    private
+
+    def fetch_avail(deadline, exception)
+      if (result = @read_buffer || fetch_next(deadline, exception)).nil?
+        close
+        return ''.b
+      end
+      @read_buffer = nil
+      result
+    end
+
+    def fetch_slice(size)
+      result = @read_buffer.byteslice(0, size)
+      rest = @read_buffer.bytesize - result.bytesize
+      @read_buffer = rest.zero? ? nil : @read_buffer.byteslice(size, rest)
+      result
+    end
+
+    def fetch_next(deadline, exception)
+      with_deadline(deadline, exception) do
+        read_nonblock(65_536, exception: false)
+      end
+    end
+
+    def with_deadline(deadline, exception)
       loop do
         case ret = yield
         when :wait_writable
@@ -67,45 +90,29 @@ module IOWithDeadlineMixin # :nodoc:
     rescue Errno::ETIMEDOUT
       raise(exception)
     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
+    module WaitWithIO
+      def wait_writable(remaining_time)
+        to_io.wait_writable(remaining_time)
+      end
+
+      def wait_readable(remaining_time)
+        to_io.wait_readable(remaining_time)
       end
-    rescue Errno::ETIMEDOUT
-      raise(exception)
     end
-  end
 
-  module ViaSelect
-    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 ::IO.select(nil, [self], nil, remaining_time).nil?
-        when :wait_readable
-          remaining_time = deadline.remaining_time or raise(exception)
-          raise(exception) if ::IO.select([self], nil, nil, remaining_time).nil?
-        else
-          return ret
-        end
+    module WaitWithSelect
+      def wait_writable(remaining_time)
+        ::IO.select(nil, [self], nil, remaining_time)
+      end
+
+      def wait_readable(remaining_time)
+        ::IO.select([self], nil, nil, remaining_time)
       end
-    rescue Errno::ETIMEDOUT
-      raise(exception)
     end
+
+    private_constant(:WaitWithIO, :WaitWithSelect)
   end
 
-  private_constant(:ViaWaitMethod, :ViaIOWaitMethod, :ViaSelect)
+  private_constant(:IOWithDeadlineMixin)
 end

data/lib/tcp-client/ssl_socket.rb

@@ -30,7 +30,7 @@ class TCPClient
       ::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 }
+        ctx.session_new_cb = proc { |_, session| @new_session = session }
       end
     end
 

data/lib/tcp-client/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 class TCPClient
-  VERSION = '0.9.4'
+  # The current version number.
+  VERSION = '0.11.0'
 end

data/lib/tcp-client.rb

@@ -13,15 +13,18 @@ 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.
+# terminate before given time limit - or raise an exception.
 #
 # @example request to Google.com and limit 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"
+#   # create a configuration to use at least TLS 1.2
+#   cfg = TCPClient::Configuration.create(ssl_params: {min_version: :TLS1_2})
 #
+#   response =
+#     TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
+#       client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") #=> 40
+#       client.readline("\r\n\r\n") #=> see response
+#     end
+#   # response contains the returned message and header
 #
 class TCPClient
   #
@@ -40,10 +43,10 @@ class TCPClient
   #
   # 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
+  # This can be used to create an ad-hoc connection which is guaranteed to be
   # closed.
   #
-  # If no block is giiven the connected client instance is returned.
+  # If no block is given 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 target address see
@@ -55,7 +58,7 @@ class TCPClient
   #
   def self.open(address, configuration = nil)
     client = new
-    client.connect(Address.new(address), configuration)
+    client.connect(address, configuration)
     block_given? ? yield(client) : client
   ensure
     client.close if block_given?
@@ -67,9 +70,9 @@ class TCPClient
   # the given time.
   #
   # It ensures to close the connection when the block execution ends and returns
-  # the block`s result.
+  # the block's result.
   #
-  # This can be used to create an ad-hoc connection which is garanteed to be
+  # This can be used to create an ad-hoc connection which is guaranteed to be
   # closed and which {#read}/{#write} call sequence should not last longer than
   # the `timeout` seconds.
   #
@@ -91,7 +94,6 @@ class TCPClient
   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))
@@ -112,7 +114,7 @@ class TCPClient
 
   #
   # @!parse attr_reader :closed?
-  # @return [Boolean] wheter the connection is closed
+  # @return [Boolean] whether the connection is closed
   #
   def closed?
     @socket.nil? || @socket.closed?
@@ -121,7 +123,7 @@ class TCPClient
   #
   # Close the current connection if connected.
   #
-  # @return [self]
+  # @return [TCPClient] itself
   #
   def close
     @socket&.close
@@ -133,7 +135,7 @@ class TCPClient
   end
 
   #
-  # Establishes a new connection to a given `address`.
+  # Establishes a new connection to a server on given `address`.
   #
   # It accepts a connection-specific `configuration` or uses the
   # {.default_configuration}.
@@ -141,7 +143,7 @@ class TCPClient
   # The optional `timeout` and `exception` parameters allow to override the
   # `connect_timeout` and `connect_timeout_error` values.
   #
-  # @param address [Address, String, Addrinfo, Integer] the target address see
+  # @param address [Address, String, Addrinfo, Integer] the target address, see
   #   {Address#initialize} for valid formats
   # @param configuration [Configuration] the {Configuration} to be used for
   #   this instance
@@ -149,7 +151,7 @@ class TCPClient
   # @param exception [Class<Exception>] exception class to be used when the
   #   connect timeout reached
   #
-  # @return [self]
+  # @return [TCPClient] itself
   #
   # @raise {NoOpenSSLError} if SSL should be used but OpenSSL is not avail
   #
@@ -157,17 +159,17 @@ class TCPClient
   #
   def connect(address, configuration = nil, timeout: nil, exception: nil)
     close if @socket
-    @address = Address.new(address)
     @configuration = (configuration || Configuration.default).dup
     raise(NoOpenSSLError) if @configuration.ssl? && !defined?(SSLSocket)
+    @address = stem_errors { Address.new(address) }
     @socket = create_socket(timeout, exception)
     self
   end
 
   #
-  # Flushes all internal buffers (write all through).
+  # Flushes all internal buffers (write all buffered data).
   #
-  # @return [self]
+  # @return [TCPClient] itself
   #
   def flush
     stem_errors { @socket&.flush }
@@ -201,6 +203,39 @@ class TCPClient
     end
   end
 
+  #
+  # Reads the next line from server.
+  #
+  # The standard record separator is used as `separator`.
+  #
+  # The optional `timeout` and `exception` parameters allow to override the
+  # `read_timeout` and `read_timeout_error` values of the used {#configuration}.
+  #
+  # @param separator [String] the line separator to be used
+  # @param timeout [Numeric] maximum time in seconds to read
+  # @param exception [Class<Exception>] exception class to be used when the
+  #   read timeout reached
+  #
+  # @return [String] the read line
+  #
+  # @raise [NotConnectedError] if {#connect} was not called before
+  #
+  # @see NetworkError
+  #
+  def readline(separator = $/, chomp: false, timeout: nil, exception: nil)
+    raise(NotConnectedError) if closed?
+    deadline = create_deadline(timeout, configuration.read_timeout)
+    unless deadline.valid?
+      return stem_errors { @socket.readline(separator, chomp: chomp) }
+    end
+    exception ||= configuration.read_timeout_error
+    line =
+      stem_errors(exception) do
+        @socket.read_to_with_deadline(separator, deadline, exception)
+      end
+    chomp ? line.chomp : line
+  end
+
   #
   # @return [String] the currently used address as text.
   #
@@ -229,7 +264,7 @@ class TCPClient
   #
   # @yieldparam client [TCPClient] self
   #
-  # @return [Object] the block`s result
+  # @return [Object] the block's result
   #
   # @raise [NoBlockGivenError] if the block is missing
   #
@@ -259,6 +294,8 @@ class TCPClient
   #
   # @raise [NotConnectedError] if {#connect} was not called before
   #
+  # @see NetworkError
+  #
   def write(*messages, timeout: nil, exception: nil)
     raise(NotConnectedError) if closed?
     deadline = create_deadline(timeout, configuration.write_timeout)
@@ -307,7 +344,8 @@ class TCPClient
       IOError,
       SocketError
     ].tap do |errors|
-      errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
-    end.freeze
+        errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
+      end
+      .freeze
   private_constant(:NETWORK_ERRORS)
 end

data/rakefile.rb

@@ -6,7 +6,11 @@ require 'rspec/core/rake_task'
 require 'yard'
 
 $stdout.sync = $stderr.sync = true
-CLOBBER << 'prj' << 'doc' << '.yardoc'
+
+CLEAN << '.yardoc'
+CLOBBER << 'prj' << 'doc'
+
 task(:default) { exec('rake --tasks') }
+task(test: :spec)
 RSpec::Core::RakeTask.new { |task| task.ruby_opts = %w[-w] }
 YARD::Rake::YardocTask.new { |task| task.stats_options = %w[--list-undoc] }

data/sample/google_ssl.rb

@@ -18,8 +18,11 @@ cfg =
 # - limit all network interactions to 1.5 seconds
 # - use the Configuration cfg
 # - send a simple HTTP get request
-# - read 12 byte: "HTTP/1.1 " + 3 byte HTTP status code
-TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
-  p client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
-  p client.read(12)
-end
+# - read the returned message and headers
+response =
+  TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
+    client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") #=> 40
+    client.readline("\r\n\r\n") #=> header, see response
+  end
+
+puts(response)

data/spec/tcp-client/configuration_spec.rb

@@ -60,20 +60,34 @@ RSpec.describe TCPClient::Configuration do
       end
     end
 
-    context 'with valid options' do
-      subject(:configuration) do
-        TCPClient::Configuration.new(
-          buffered: false,
-          keep_alive: false,
-          reverse_lookup: false,
-          normalize_network_errors: true,
-          ssl: true,
-          timeout: 60,
-          timeout_error: custom_error
-        )
+    context 'when options are given' do
+      let(:options) { double(:options) }
+
+      it 'calls #configure with given options' do
+        expect_any_instance_of(TCPClient::Configuration).to receive(
+          :configure
+        ).once.with(options)
+
+        TCPClient::Configuration.new(options)
       end
-      let(:custom_error) { Class.new(StandardError) }
+    end
+  end
+
+  describe '#configure' do
+    subject(:configuration) do
+      TCPClient::Configuration.new.configure(
+        buffered: false,
+        keep_alive: false,
+        reverse_lookup: false,
+        normalize_network_errors: true,
+        ssl: true,
+        timeout: 60,
+        timeout_error: custom_error
+      )
+    end
+    let(:custom_error) { Class.new(StandardError) }
 
+    context 'with valid options' do
       it 'allows to configure buffering' do
         expect(configuration.buffered).to be false
       end
@@ -107,52 +121,56 @@ RSpec.describe TCPClient::Configuration do
       end
 
       it 'allows to configure dedicated timeout values' do
-        config =
-          TCPClient::Configuration.new(
-            connect_timeout: 21,
-            read_timeout: 42,
-            write_timeout: 84
-          )
-        expect(config.connect_timeout).to be 21
-        expect(config.read_timeout).to be 42
-        expect(config.write_timeout).to be 84
+        configuration.configure(
+          connect_timeout: 21,
+          read_timeout: 42,
+          write_timeout: 84
+        )
+        expect(configuration.connect_timeout).to be 21
+        expect(configuration.read_timeout).to be 42
+        expect(configuration.write_timeout).to be 84
       end
 
       it 'allows to configure dedicated timeout errors' do
         custom_connect = Class.new(StandardError)
         custom_read = Class.new(StandardError)
         custom_write = Class.new(StandardError)
-        config =
-          TCPClient::Configuration.new(
-            connect_timeout_error: custom_connect,
-            read_timeout_error: custom_read,
-            write_timeout_error: custom_write
-          )
-        expect(config.connect_timeout_error).to be custom_connect
-        expect(config.read_timeout_error).to be custom_read
-        expect(config.write_timeout_error).to be custom_write
+        configuration.configure(
+          connect_timeout_error: custom_connect,
+          read_timeout_error: custom_read,
+          write_timeout_error: custom_write
+        )
+        expect(configuration.connect_timeout_error).to be custom_connect
+        expect(configuration.read_timeout_error).to be custom_read
+        expect(configuration.write_timeout_error).to be custom_write
       end
+    end
 
-      it 'raises when no exception class is used to configure a timeout error' do
-        expect do
-          TCPClient::Configuration.new(
-            connect_timeout_error: double(:something)
-          )
-        end.to raise_error(TCPClient::NotAnExceptionError)
+    context 'when an invalid attribute is given' do
+      it 'raises an error' do
+        expect { configuration.configure(invalid: :value) }.to raise_error(
+          TCPClient::UnknownAttributeError
+        )
+      end
+    end
+
+    context 'when no exception class is used to configure a timeout error' do
+      it 'raises with invalid connect_timeout_error' do
         expect do
-          TCPClient::Configuration.new(read_timeout_error: double(:something))
+          configuration.configure(connect_timeout_error: double(:something))
         end.to raise_error(TCPClient::NotAnExceptionError)
+      end
+
+      it 'raises with invalid read_timeout_error' do
         expect do
-          TCPClient::Configuration.new(write_timeout_error: double(:something))
+          configuration.configure(read_timeout_error: double(:something))
         end.to raise_error(TCPClient::NotAnExceptionError)
       end
-    end
 
-    context 'with invalid attribute' do
-      it 'raises an error' do
-        expect { TCPClient::Configuration.new(invalid: :value) }.to raise_error(
-          TCPClient::UnknownAttributeError
-        )
+      it 'raises with invalid write_timeout_error' do
+        expect do
+          configuration.configure(write_timeout_error: double(:something))
+        end.to raise_error(TCPClient::NotAnExceptionError)
       end
     end
   end

data/spec/tcp-client/default_configuration_spec.rb

@@ -9,8 +9,9 @@ RSpec.describe 'TCPClient.configure' do
 
   context 'called with parameters' do
     it 'creates a new configuratiion' do
-      expect(TCPClient::Configuration).to receive(:create).once.with(a: 1, b: 2)
-      TCPClient.configure(a: 1, b: 2)
+      options = double(:options)
+      expect(TCPClient::Configuration).to receive(:create).once.with(options)
+      TCPClient.configure(options)
     end
 
     it 'returns the new configuratiion' do

data/spec/tcp_client_spec.rb

@@ -26,7 +26,7 @@ RSpec.describe TCPClient do
     subject(:client) { TCPClient.new }
 
     it 'is closed' do
-      expect(client.closed?).to be true
+      expect(client).to be_closed
     end
 
     it 'has no address' do
@@ -64,7 +64,7 @@ RSpec.describe TCPClient do
     before { allow_any_instance_of(::Socket).to receive(:connect) }
 
     it 'is not closed' do
-      expect(client.closed?).to be false
+      expect(client).not_to be_closed
     end
 
     it 'has an address' do
@@ -115,7 +115,7 @@ RSpec.describe TCPClient do
     end
 
     it 'is closed' do
-      expect(client.closed?).to be true
+      expect(client).to be_closed
     end
 
     it 'has an address' do
@@ -130,11 +130,11 @@ RSpec.describe TCPClient do
       expect(client.configuration).to be configuration
     end
 
-    it 'failes when read is called' do
+    it 'fails when read is called' do
       expect { client.read(42) }.to raise_error(TCPClient::NotConnectedError)
     end
 
-    it 'failes when write is called' do
+    it 'fails when write is called' do
       expect { client.write('?!') }.to raise_error(TCPClient::NotConnectedError)
     end
 
@@ -149,14 +149,10 @@ RSpec.describe TCPClient do
     end
   end
 
-  xdescribe '.open' do
-  end
-
-  xdescribe '.with_deadline' do
-  end
-
   context 'when not using SSL' do
     describe '#connect' do
+      subject(:client) { TCPClient.new }
+
       it 'configures the socket' do
         expect_any_instance_of(::Socket).to receive(:sync=).once.with(true)
         expect_any_instance_of(::Socket).to receive(:setsockopt)
@@ -169,7 +165,7 @@ RSpec.describe TCPClient do
           .once
           .with(false)
         expect_any_instance_of(::Socket).to receive(:connect)
-        TCPClient.new.connect('localhost:1234', configuration)
+        client.connect('localhost:1234', configuration)
       end
 
       context 'when a timeout is specified' do
@@ -177,7 +173,26 @@ RSpec.describe TCPClient do
           expect_any_instance_of(::Socket).to receive(:connect_nonblock)
             .once
             .with(kind_of(String), exception: false)
-          TCPClient.new.connect('localhost:1234', configuration, timeout: 10)
+          client.connect('localhost:1234', configuration, timeout: 10)
+        end
+
+        it 'is returns itself' do
+          allow_any_instance_of(::Socket).to receive(:connect_nonblock).with(
+            kind_of(String),
+            exception: false
+          )
+          result = client.connect('localhost:1234', configuration, timeout: 10)
+
+          expect(result).to be client
+        end
+
+        it 'is not closed' do
+          allow_any_instance_of(::Socket).to receive(:connect_nonblock).with(
+            kind_of(String),
+            exception: false
+          )
+          client.connect('localhost:1234', configuration, timeout: 10)
+          expect(client).not_to be_closed
         end
 
         context 'when the connection can not be established in time' do
@@ -188,25 +203,29 @@ RSpec.describe TCPClient do
 
           it 'raises an exception' do
             expect do
-              TCPClient.new.connect(
-                'localhost:1234',
-                configuration,
-                timeout: 0.25
-              )
+              client.connect('localhost:1234', configuration, timeout: 0.1)
             end.to raise_error(TCPClient::ConnectTimeoutError)
           end
 
           it 'allows to raise a custom exception' do
             exception = Class.new(StandardError)
             expect do
-              TCPClient.new.connect(
+              client.connect(
                 'localhost:1234',
                 configuration,
-                timeout: 0.25,
+                timeout: 0.1,
                 exception: exception
               )
             end.to raise_error(exception)
           end
+
+          it 'is still closed' do
+            begin
+              client.connect('localhost:1234', configuration, timeout: 0.1)
+            rescue TCPClient::ConnectTimeoutError
+            end
+            expect(client).to be_closed
+          end
         end
       end
 
@@ -226,7 +245,7 @@ RSpec.describe TCPClient do
           end
 
           SOCKET_ERRORS.each do |error_class|
-            it "raises a TCPClient::NetworkError when a #{error_class} appeared" do
+            it "raises TCPClient::NetworkError when a #{error_class} appeared" do
               allow_any_instance_of(::Socket).to receive(:connect) {
                 raise error_class
               }
@@ -270,18 +289,61 @@ RSpec.describe TCPClient do
           expect(client.read(timeout: 10)).to be data
         end
 
+        context 'when socket closed before any data can be read' do
+          it 'returns empty buffer' do
+            expect_any_instance_of(::Socket).to receive(:read_nonblock)
+              .and_return(nil)
+            expect(client.read(timeout: 10)).to be_empty
+          end
+
+          it 'is closed' do
+            expect_any_instance_of(::Socket).to receive(:read_nonblock)
+              .and_return(nil)
+
+            client.read(timeout: 10)
+            expect(client).to be_closed
+          end
+        end
+
         context 'when data can not be fetched in a single chunk' do
           it 'reads chunk by chunk' do
             expect_any_instance_of(::Socket).to receive(:read_nonblock)
               .once
-              .with(data_size * 2, exception: false)
+              .with(instance_of(Integer), exception: false)
               .and_return(data)
             expect_any_instance_of(::Socket).to receive(:read_nonblock)
               .once
-              .with(data_size, exception: false)
+              .with(instance_of(Integer), exception: false)
               .and_return(data)
             expect(client.read(data_size * 2, timeout: 10)).to eq data * 2
           end
+
+          context 'when socket closed before enough data is avail' do
+            it 'returns available data only' do
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(data)
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(nil)
+              expect(client.read(data_size * 2, timeout: 10)).to eq data
+            end
+
+            it 'is closed' do
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(data)
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(nil)
+              client.read(data_size * 2, timeout: 10)
+              expect(client).to be_closed
+            end
+          end
         end
 
         context 'when the data can not be read in time' do
@@ -329,6 +391,146 @@ RSpec.describe TCPClient do
       end
     end
 
+    describe '#readline' do
+      before { allow_any_instance_of(::Socket).to receive(:connect) }
+
+      it 'reads from socket' do
+        expect_any_instance_of(::Socket).to receive(:readline)
+          .once
+          .with($/, chomp: false)
+          .and_return("Hello World\n")
+        expect(client.readline).to eq "Hello World\n"
+      end
+
+      context 'when a separator is specified' do
+        it 'forwards the separator' do
+          expect_any_instance_of(::Socket).to receive(:readline)
+            .once
+            .with('/', chomp: false)
+            .and_return('Hello/')
+          expect(client.readline('/')).to eq 'Hello/'
+        end
+      end
+
+      context 'when chomp is true' do
+        it 'forwards the flag' do
+          expect_any_instance_of(::Socket).to receive(:readline)
+            .once
+            .with($/, chomp: true)
+            .and_return('Hello World')
+          expect(client.readline(chomp: true)).to eq 'Hello World'
+        end
+      end
+
+      context 'when a timeout is specified' do
+        it 'checks the time' do
+          expect_any_instance_of(::Socket).to receive(:read_nonblock)
+            .and_return("Hello World\nHello World\n")
+          expect(client.readline(timeout: 10)).to eq "Hello World\n"
+        end
+
+        it 'optional chomps the line' do
+          expect_any_instance_of(::Socket).to receive(:read_nonblock)
+            .and_return("Hello World\nHello World\n")
+          expect(client.readline(chomp: true, timeout: 10)).to eq 'Hello World'
+        end
+
+        it 'uses the given separator' do
+          expect_any_instance_of(::Socket).to receive(:read_nonblock)
+            .and_return("Hello/World\n")
+          expect(client.readline('/', timeout: 10)).to eq 'Hello/'
+        end
+
+        context 'when data can not be fetched in a single chunk' do
+          it 'reads chunk by chunk' do
+            expect_any_instance_of(::Socket).to receive(:read_nonblock)
+              .once
+              .with(instance_of(Integer), exception: false)
+              .and_return('Hello ')
+            expect_any_instance_of(::Socket).to receive(:read_nonblock)
+              .once
+              .with(instance_of(Integer), exception: false)
+              .and_return('World')
+            expect_any_instance_of(::Socket).to receive(:read_nonblock)
+              .once
+              .with(instance_of(Integer), exception: false)
+              .and_return("\nAnd so...")
+            expect(client.readline(timeout: 10)).to eq "Hello World\n"
+          end
+
+          context 'when socket closed before enough data is avail' do
+            it 'returns available data only' do
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return('Hello ')
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(nil)
+              expect(client.readline(timeout: 10)).to eq 'Hello '
+            end
+
+            it 'is closed' do
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return('Hello ')
+              expect_any_instance_of(::Socket).to receive(:read_nonblock)
+                .once
+                .with(instance_of(Integer), exception: false)
+                .and_return(nil)
+              client.readline(timeout: 10)
+              expect(client).to be_closed
+            end
+          end
+        end
+
+        context 'when the data can not be read in time' do
+          before do
+            allow_any_instance_of(::Socket).to receive(:read_nonblock)
+              .and_return(:wait_readable)
+          end
+          it 'raises an exception' do
+            expect { client.readline(timeout: 0.25) }.to raise_error(
+              TCPClient::ReadTimeoutError
+            )
+          end
+
+          it 'allows to raise a custom exception' do
+            exception = Class.new(StandardError)
+            expect do
+              client.read(timeout: 0.25, exception: exception)
+            end.to raise_error(exception)
+          end
+        end
+      end
+
+      context 'when a SocketError appears' do
+        it 'does not handle it' do
+          allow_any_instance_of(::Socket).to receive(:read) {
+            raise SocketError
+          }
+          expect { client.read(10) }.to raise_error(SocketError)
+        end
+
+        context 'when normalize_network_errors is configured' do
+          let(:configuration) do
+            TCPClient::Configuration.create(normalize_network_errors: true)
+          end
+
+          SOCKET_ERRORS.each do |error_class|
+            it "raises a TCPClient::NetworkError when a #{error_class} appeared" do
+              allow_any_instance_of(::Socket).to receive(:read) {
+                raise error_class
+              }
+              expect { client.read(12) }.to raise_error(TCPClient::NetworkError)
+            end
+          end
+        end
+      end
+    end
+
     describe '#write' do
       let(:data) { 'some bytes' }
       let(:data_size) { data.bytesize }
@@ -463,20 +665,16 @@ RSpec.describe TCPClient do
           .with(kind_of(String), exception: false)
         expect_any_instance_of(::Socket).to receive(:read_nonblock)
           .once
-          .with(12, exception: false)
-          .and_return('123456789012')
+          .with(instance_of(Integer), exception: false)
+          .and_return('123456789012abcdefgAB')
         expect_any_instance_of(::Socket).to receive(:write_nonblock)
           .once
           .with('123456', exception: false)
           .and_return(6)
         expect_any_instance_of(::Socket).to receive(:read_nonblock)
           .once
-          .with(7, exception: false)
-          .and_return('abcdefg')
-        expect_any_instance_of(::Socket).to receive(:read_nonblock)
-          .once
-          .with(7, exception: false)
-          .and_return('ABCDEFG')
+          .with(instance_of(Integer), exception: false)
+          .and_return('CDEFG')
         expect_any_instance_of(::Socket).to receive(:write_nonblock)
           .once
           .with('abc', exception: false)
@@ -575,7 +773,7 @@ RSpec.describe TCPClient do
         #     :set_params
         #   )
         #   .once
-        #   .with(ssl_version: :TLSv1_2)
+        #   .with(max_version: :TLS1_3, min_version: :TLS1_2)
         #   .and_call_original
         expect_any_instance_of(::OpenSSL::SSL::SSLSocket).to receive(
             :sync_close=

data/tcp-client.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
 
   spec.author = 'Mike Blumtritt'
   spec.summary = 'A TCP client implementation with working timeout support.'
-  spec.description = <<~description
+  spec.description = <<~DESCRIPTION
     This Gem implements a TCP client with (optional) SSL support.
     It is an easy to use, versatile configurable client that can correctly
     handle time limits.
@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
     predefined/configurable time limits for each method
     (`connect`, `read`, `write`). Deadlines for a sequence of read/write
     actions can also be monitored.
-  description
+  DESCRIPTION
 
   spec.homepage = 'https://github.com/mblumtritt/tcp-client'
   spec.license = 'BSD-3-Clause'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.11.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-16 00:00:00.000000000 Z
+date: 2022-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -129,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A TCP client implementation with working timeout support.