tcp-client 0.9.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 114da301d59fc9cf9c3d3bda508f4d23b5b4991877a5dc7504d4da97114f8e7f
-  data.tar.gz: 9d0815501de340b485cba157aff05097597948d023a7eca6c45a8ead3a4e3d0d
+  metadata.gz: e88146d7f1f966d6c9e7dce6a876c17dca7383ee88eb76a8e5caf36076a03720
+  data.tar.gz: 493d8cbf748789df4efd0301679082023c140f23dbc2a3d52ccfcf8d71a4a1b4
 SHA512:
-  metadata.gz: a560644d578cedccaf1e2665f518b3a6a4e225886cfc561a8b62087420d93b958ee4741d8efde3b456fa15ce24fd5ee2f6a1121b55855205ffae5abf17becf97
-  data.tar.gz: f1f0ed0b87f8ee9c9b376b6b567c45aecb204c5b3de044c97f6ba080071c3c8e70da8bca8cca2484d5ddec06df181ee4b007e9ed826045e205d77df38eefbbbd
+  metadata.gz: 070ba42a0a185a67ae1ac4d1912220ab0aa297a6cdc4147d3afaf8593129f3b25da2ecad7a8569651c6d54dd1ba11c7705ebf8bcc1def2d525388025b45d12b3
+  data.tar.gz: 4c34127d89744a537d5b64c578ac4c1e2121c27e9412208f7c0abcf74999bb1e85c1c246bebfea83401c8caaf4c472daee7ff5e599989632076784881131b3ea

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)

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,7 +26,7 @@ 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
     #
@@ -37,13 +37,13 @@ class TCPClient
     end
 
     #
-    # Intializes the instance with given options.
+    # Initializes the instance with given options.
     #
-    # @param options [Hash<Symbol,Object>]
+    # @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 [Hash<Symbol, Object>] :ssl_params, see {#ssl_params}
+    # @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}
@@ -56,7 +56,6 @@ class TCPClient
     # @option options [Boolean] :normalize_network_errors, see
     #   {#normalize_network_errors}
     #
-    #
     def initialize(options = {})
       @buffered = @keep_alive = @reverse_lookup = true
       self.timeout = @ssl_params = nil
@@ -72,8 +71,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 +83,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 +95,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 +106,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 +116,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 +225,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 +238,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
@@ -266,7 +265,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
@@ -276,9 +275,7 @@ class TCPClient
     end
 
     #
-    # Convert `self` to a Hash containing all attributes.
-    #
-    # @return [Hash<Symbol, Object>]
+    # @return [{Symbol => Object}] Hash containing all attributes
     #
     # @see #initialize
     #

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

@@ -13,25 +13,30 @@ module IOWithDeadlineMixin # :nodoc:
     end
   end
 
-  def read_with_deadline(bytes_to_read, deadline, exception)
+  def read_with_deadline(nbytes, 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
-      )
+    return fetch_avail(deadline, exception) if nbytes.nil?
+    return ''.b if nbytes.zero?
+    @buf ||= ''.b
+    while @buf.bytesize < nbytes
+      read = fetch_next(deadline, exception) and next @buf << read
+      close
+      break
     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
+    fetch_buffer_slice(nbytes)
+  end
+
+  def readto_with_deadline(sep, deadline, exception)
+    raise(exception) unless deadline.remaining_time
+    @buf ||= ''.b
+    while (index = @buf.index(sep)).nil?
+      read = fetch_next(deadline, exception) and next @buf << read
       close
       break
     end
+    index = @buf.index(sep) and return fetch_buffer_slice(index + sep.bytesize)
+    result = @buf
+    @buf = nil
     result
   end
 
@@ -44,12 +49,37 @@ module IOWithDeadlineMixin # :nodoc:
         with_deadline(deadline, exception) do
           write_nonblock(data, exception: false)
         end
-      result += written
-      return result if result >= size
+      (result += written) >= size and return result
       data = data.byteslice(written, data.bytesize - written)
     end
   end
 
+  private
+
+  def fetch_avail(deadline, exception)
+    if @buf.nil?
+      result = fetch_next(deadline, exception) and return result
+      close
+      return ''.b
+    end
+    result = @buf
+    @buf = nil
+    result
+  end
+
+  def fetch_buffer_slice(size)
+    result = @buf.byteslice(0, size)
+    rest = @buf.bytesize - result.bytesize
+    @buf = rest.zero? ? nil : @buf.byteslice(size, rest)
+    result
+  end
+
+  def fetch_next(deadline, exception)
+    with_deadline(deadline, exception) do
+      read_nonblock(65_536, exception: false)
+    end
+  end
+
   module ViaWaitMethod
     private def with_deadline(deadline, exception)
       loop do

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.10.0'
 end

data/lib/tcp-client.rb

@@ -16,12 +16,15 @@ require_relative 'tcp-client/version'
 # terminate before given time limits - 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.readto_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)

data/rakefile.rb

@@ -6,7 +6,13 @@ require 'rspec/core/rake_task'
 require 'yard'
 
 $stdout.sync = $stderr.sync = true
-CLOBBER << 'prj' << 'doc' << '.yardoc'
+
+CLEAN << 'prj' << 'doc'
+
+CLOBBER << '.yardoc'
+
 task(:default) { exec('rake --tasks') }
+
 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") #=> see response
+  end
+
+puts(response)

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
@@ -157,6 +157,8 @@ RSpec.describe TCPClient do
 
   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 +171,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 +179,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(client).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 +209,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 +251,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 +295,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 +397,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 +671,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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.10.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-16 00:00:00.000000000 Z
+date: 2022-01-09 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.3
 signing_key:
 specification_version: 4
 summary: A TCP client implementation with working timeout support.