tcp-client 0.9.3 → 0.10.1

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
   #
@@ -30,57 +33,59 @@ class TCPClient
   #
   # If no `configuration` is given, the {.default_configuration} will be used.
   #
+  # @overload open(address, configuration = nil)
+  #   @yieldparam client [TCPClient] the connected client
+  #
+  #   @return [Object] the block result
+  #
+  # @overload open(address, configuration = nil)
+  #   @return [TCPClient] the connected client
+  #
   # 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 address to connect
-  #   to, see {Address#initialize} for valid formats
+  # @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
-  #
-  # @yieldparam client [TCPClient] the connected client
-  # @yieldreturn [Object] any result
-  #
-  # @return [Object, TCPClient] the block result or the connected client
+  #   the new instance
   #
   # @see #connect
   #
   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?
   end
 
   #
-  # Yields a new instance which is connected to the server on the given
-  # `address`.It limits all {#read} and {#write} actions within the block to
+  # Yields an instance which is connected to the server on the given
+  # `address`. It limits all {#read} and {#write} actions within the block to
   # 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`.
+  # the `timeout` seconds.
   #
   # If no `configuration` is given, the {.default_configuration} will be used.
   #
   # @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 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
+  #   the instance
   #
   # @yieldparam client [TCPClient] the connected client
-  # @yieldreturn [Object] any result
   #
   # @return [Object] the block's result
   #
@@ -89,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))
@@ -110,7 +114,7 @@ class TCPClient
 
   #
   # @!parse attr_reader :closed?
-  # @return [Boolean] true when the connection is closed, false when connected
+  # @return [Boolean] whether the connection is closed
   #
   def closed?
     @socket.nil? || @socket.closed?
@@ -119,7 +123,7 @@ class TCPClient
   #
   # Close the current connection if connected.
   #
-  # @return [self]
+  # @return [TCPClient] itself
   #
   def close
     @socket&.close
@@ -131,25 +135,23 @@ 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}. 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.
+  # It accepts a connection-specific `configuration` or uses the
+  # {.default_configuration}.
   #
   # The optional `timeout` and `exception` parameters allow to override the
   # `connect_timeout` and `connect_timeout_error` values.
   #
-  # @param address [Address, String, Addrinfo, Integer] the address to connect
-  #   to, see {Address#initialize} for valid formats
+  # @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
   # @param timeout [Numeric] maximum time in seconds to connect
-  # @param exception [Class] exception class to be used when the connect timeout
-  #   reached
+  # @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
 
   #
-  # Flush 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 }
@@ -182,8 +184,8 @@ class TCPClient
   #
   # @param nbytes [Integer] the number of bytes to read
   # @param timeout [Numeric] maximum time in seconds to read
-  # @param exception [Class] exception class to be used when the read timeout
-  #   reached
+  # @param exception [Class<Exception>] exception class to be used when the
+  #   read timeout reached
   #
   # @return [String] the read buffer
   #
@@ -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.
   #
@@ -211,7 +246,7 @@ class TCPClient
   end
 
   #
-  # Execute a block with a given overall time limit.
+  # Executes a block with a given overall time limit.
   #
   # When you like to ensure that a complete {#read}/{#write} communication
   # sequence with the server is finished before a given amount of time you use
@@ -228,9 +263,8 @@ class TCPClient
   #   {#write} calls within the block
   #
   # @yieldparam client [TCPClient] self
-  # @yieldreturn [Object] any result
   #
-  # @return [Object] the block`s result
+  # @return [Object] the block's result
   #
   # @raise [NoBlockGivenError] if the block is missing
   #
@@ -245,21 +279,23 @@ class TCPClient
   end
 
   #
-  # Write the given `messages` to the server.
+  # Writes the given `messages` to the server.
   #
   # The optional `timeout` and `exception` parameters allow to override the
   # `write_timeout` and `write_timeout_error` values of the used
   # {#configuration}.
   #
-  # @param messages [String] one or more messages to write
+  # @param messages [Array<String>] one or more messages to write
   # @param timeout [Numeric] maximum time in seconds to write
-  # @param exception [Class] exception class to be used when the write timeout
-  #   reached
+  # @param exception [Class<Exception>] exception class to be used when the
+  #   write timeout reached
   #
   # @return [Integer] bytes written
   #
   # @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/address_spec.rb

@@ -9,8 +9,8 @@ RSpec.describe TCPClient::Address do
 
       it 'points to the given port on localhost' do
         expect(address.hostname).to eq 'localhost'
+        expect(address.port).to be 42
         expect(address.to_s).to eq 'localhost:42'
-        expect(address.addrinfo.ip_port).to be 42
       end
 
       it 'uses IPv6' do
@@ -29,8 +29,9 @@ RSpec.describe TCPClient::Address do
       end
 
       it 'points to the given host and port' do
-        expect(address.hostname).to eq addrinfo.getnameinfo[0]
-        expect(address.addrinfo.ip_port).to be 42
+        expect(address.hostname).to eq 'localhost'
+        expect(address.port).to be 42
+        expect(address.to_s).to eq 'localhost:42'
       end
 
       it 'uses IPv6' do
@@ -46,30 +47,21 @@ RSpec.describe TCPClient::Address do
 
         it 'points to the given host and port' do
           expect(address.hostname).to eq 'localhost'
+          expect(address.port).to be 42
           expect(address.to_s).to eq 'localhost:42'
-          expect(address.addrinfo.ip_port).to be 42
-        end
-
-        it 'uses IPv6' do
           expect(address.addrinfo.ip?).to be true
-          expect(address.addrinfo.ipv6?).to be true
-          expect(address.addrinfo.ipv4?).to be false
         end
+
       end
 
       context 'when only a port is provided' do
-        subject(:address) { TCPClient::Address.new(':21') }
+        subject(:address) { TCPClient::Address.new(':42') }
 
         it 'points to the given port on localhost' do
-          expect(address.hostname).to eq ''
-          expect(address.to_s).to eq ':21'
-          expect(address.addrinfo.ip_port).to be 21
-        end
-
-        it 'uses IPv4' do
+          expect(address.hostname).to eq 'localhost'
+          expect(address.port).to be 42
+          expect(address.to_s).to eq 'localhost:42'
           expect(address.addrinfo.ip?).to be true
-          expect(address.addrinfo.ipv6?).to be false
-          expect(address.addrinfo.ipv4?).to be true
         end
       end
 
@@ -78,14 +70,9 @@ RSpec.describe TCPClient::Address do
 
         it 'points to the given port on localhost' do
           expect(address.hostname).to eq '::1'
+          expect(address.port).to be 42
           expect(address.to_s).to eq '[::1]:42'
-          expect(address.addrinfo.ip_port).to be 42
-        end
-
-        it 'uses IPv6' do
           expect(address.addrinfo.ip?).to be true
-          expect(address.addrinfo.ipv6?).to be true
-          expect(address.addrinfo.ipv4?).to be false
         end
       end
     end
@@ -108,13 +95,13 @@ RSpec.describe TCPClient::Address do
         expect(address_a).to eq address_b
       end
 
-      context 'using the == opperator' do
+      context 'using the == operator' do
         it 'compares to equal' do
           expect(address_a == address_b).to be true
         end
       end
 
-      context 'using the === opperator' do
+      context 'using the === operator' do
         it 'compares to equal' do
           expect(address_a === address_b).to be true
         end
@@ -129,13 +116,13 @@ RSpec.describe TCPClient::Address do
         expect(address_a).not_to eq address_b
       end
 
-      context 'using the == opperator' do
+      context 'using the == operator' do
         it 'compares not to equal' do
           expect(address_a == address_b).to be false
         end
       end
 
-      context 'using the === opperator' do
+      context 'using the === operator' do
         it 'compares not to equal' do
           expect(address_a === address_b).to be false
         end

data/spec/tcp-client/configuration_spec.rb

@@ -233,13 +233,13 @@ RSpec.describe TCPClient::Configuration do
         expect(config_a).to eq config_b
       end
 
-      context 'using the == opperator' do
+      context 'using the == operator' do
         it 'compares to equal' do
           expect(config_a == config_b).to be true
         end
       end
 
-      context 'using the === opperator' do
+      context 'using the === operator' do
         it 'compares to equal' do
           expect(config_a === config_b).to be true
         end
@@ -254,13 +254,13 @@ RSpec.describe TCPClient::Configuration do
         expect(config_a).not_to eq config_b
       end
 
-      context 'using the == opperator' do
+      context 'using the == operator' do
         it 'compares not to equal' do
           expect(config_a == config_b).to be false
         end
       end
 
-      context 'using the === opperator' do
+      context 'using the === operator' do
         it 'compares not to equal' do
           expect(config_a === config_b).to be false
         end