tcp-client 0.9.1 → 0.10.0

data/lib/tcp-client/errors.rb

@@ -2,7 +2,8 @@
 
 class TCPClient
   #
-  # Raised when a SSL connection should be establshed but the OpenSSL gem is not available.
+  # Raised when a SSL connection should be established but the OpenSSL gem is
+  # not available.
   #
   class NoOpenSSLError < RuntimeError
     def initialize
@@ -11,7 +12,8 @@ class TCPClient
   end
 
   #
-  # Raised when a method requires a callback block but no such block is specified.
+  # Raised when a method requires a callback block but no such block is
+  # specified.
   #
   class NoBlockGivenError < ArgumentError
     def initialize
@@ -20,9 +22,12 @@ class TCPClient
   end
 
   #
-  # Raised when a an invalid timeout value was specified.
+  # Raised when an invalid timeout value was specified.
   #
   class InvalidDeadLineError < ArgumentError
+    #
+    # @param timeout [Object] the invalid value
+    #
     def initialize(timeout)
       super("invalid deadline - #{timeout}")
     end
@@ -32,6 +37,9 @@ class TCPClient
   # Raised by {Configuration} when an undefined attribute should  be set.
   #
   class UnknownAttributeError < ArgumentError
+    #
+    # @param attribute [Object] the undefined attribute
+    #
     def initialize(attribute)
       super("unknown attribute - #{attribute}")
     end
@@ -41,6 +49,9 @@ class TCPClient
   # Raised when a given timeout exception parameter is not an exception class.
   #
   class NotAnExceptionError < TypeError
+    #
+    # @param object [Object] the invalid object
+    #
     def initialize(object)
       super("exception class required - #{object.inspect}")
     end
@@ -49,15 +60,18 @@ class TCPClient
   #
   # Base exception class for all network related errors.
   #
-  # Will be raised for any system level network error when {Configuration.normalize_network_errors} is configured.
+  # Will be raised for any system level network error when
+  # {Configuration.normalize_network_errors} is configured.
   #
-  # You should catch this exception class when you like to handle any relevant {TCPClient} error.
+  # You should catch this exception class when you like to handle any relevant
+  # {TCPClient} error.
   #
   class NetworkError < StandardError
   end
 
   #
-  # Raised when a {TCPClient} instance should read/write from/to the network but is not connected.
+  # Raised when a {TCPClient} instance should read/write from/to the network
+  # but is not connected.
   #
   class NotConnectedError < NetworkError
     def initialize
@@ -68,23 +82,26 @@ class TCPClient
   #
   # Base exception class for a detected timeout.
   #
-  # You should catch this exception class when you like to handle any timeout error.
+  # You should catch this exception class when you like to handle any timeout
+  # error.
   #
   class TimeoutError < NetworkError
     #
     # Initializes the instance with an optional message.
     #
-    # the message will be generated from {#action} when not specified.
+    # The message will be generated from {#action} when not specified.
+    #
     # @overload initialize
     # @overload initialize(message)
     #
-    # @param message [String, #to_s] the error message
+    # @param message [#to_s] the error message
     #
     def initialize(message = nil)
       super(message || "unable to #{action} in time")
     end
 
     #
+    # @attribute [r] action
     # @return [Symbol] the action which timed out
     #
     def action
@@ -97,7 +114,8 @@ class TCPClient
   #
   class ConnectTimeoutError < TimeoutError
     #
-    # @return [Symbol] the action which timed out: +:connect+
+    # @attribute [r] action
+    # @return [Symbol] the action which timed out: `:connect`
     #
     def action
       :connect
@@ -105,11 +123,12 @@ class TCPClient
   end
 
   #
-  # Raised by default whenever a {TCPClient.read} timed out.
+  # Raised by default whenever a {TCPClient#read} timed out.
   #
   class ReadTimeoutError < TimeoutError
     #
-    # @return [Symbol] the action which timed out: +:read+
+    # @attribute [r] action
+    # @return [Symbol] the action which timed out: :read`
     #
     def action
       :read
@@ -117,11 +136,12 @@ class TCPClient
   end
 
   #
-  # Raised by default whenever a {TCPClient.write} timed out.
+  # Raised by default whenever a {TCPClient#write} timed out.
   #
   class WriteTimeoutError < TimeoutError
     #
-    # @return [Symbol] the action which timed out: +:write+
+    # @attribute [r] action
+    # @return [Symbol] the action which timed out: `:write`
     #
     def action
       :write

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,8 +1,6 @@
 # frozen_string_literal: true
 
 class TCPClient
-  #
-  # The current gem version.
-  #
-  VERSION = '0.9.1'
+  # The current version number.
+  VERSION = '0.10.0'
 end

data/lib/tcp-client.rb

@@ -15,71 +15,85 @@ require_relative 'tcp-client/version'
 # All connect/read/write actions can be monitored to ensure that all actions
 # terminate before given time limits - or raise an exception.
 #
-# @example - request to Google.com and limit all network interactions to 1.5 seconds
-#   TCPClient.with_deadline(1.5, 'www.google.com:443') do |client|
-#     client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
-#     client.read(12)
-#   end
-#   # => "HTTP/1.1 200"
+# @example request to Google.com and limit network interactions to 1.5 seconds
+#   # 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
   #
   # Creates a new instance which is connected to the server on the given
-  # address and uses the given or the {.default_configuration}.
+  # `address`.
+  #
+  # 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 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
+  # @param address [Address, String, Addrinfo, Integer] the target address see
+  #   {Address#initialize} for valid formats
+  # @param configuration [Configuration] the {Configuration} to be used for
+  #   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 and uses the given or the {.default_configuration}.
-  # It ensures to close the connection when the block execution ends.
-  # It also limits all {#read} and {#write} actions within the block to a given
-  # time.
+  # 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.
   #
-  # This can be used to create an ad-hoc connection which is garanteed to be
-  # closed and which read/write calls should not last longer than the timeout
-  # limit.
+  # It ensures to close the connection when the block execution ends and returns
+  # the block's result.
   #
-  # @param timeout [Numeric] maximum time in seconds for all {#read} and {#write} calls within the block
-  # @param address [Address, String, Addrinfo, Integer] the address to connect to, see {Address#initialize} for valid formats
-  # @param configuration [Configuration] the {Configuration} to be used for this instance
+  # 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.
+  #
+  # 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 target address see
+  #   {Address#initialize} for valid formats
+  # @param configuration [Configuration] the {Configuration} to be used for
+  #   the instance
   #
   # @yieldparam client [TCPClient] the connected client
-  # @yieldreturn [Object] any result
   #
-  # @return [Object] the block result
+  # @return [Object] the block's result
   #
   # @see #with_deadline
   #
   def self.with_deadline(timeout, address, configuration = nil)
     client = nil
     raise(NoBlockGivenError) unless block_given?
-    address = Address.new(address)
     client = new
     client.with_deadline(timeout) do
       yield(client.connect(address, configuration))
@@ -89,89 +103,168 @@ class TCPClient
   end
 
   #
-  # @return [Address] the address used for this client
+  # @return [Address] the address used by this client instance
   #
   attr_reader :address
 
   #
-  # @return [Configuration] the configuration used by this client.
+  # @return [Configuration] the configuration used by this client instance
   #
   attr_reader :configuration
 
   #
-  # @attribute [r] closed?
-  # @return [Boolean] true when the connection is closed, false when connected
+  # @!parse attr_reader :closed?
+  # @return [Boolean] whether the connection is closed
   #
   def closed?
     @socket.nil? || @socket.closed?
   end
 
   #
-  # @return [String] the currently used address as text.
+  # Close the current connection if connected.
   #
-  # @see Address#to_s
+  # @return [TCPClient] itself
   #
-  def to_s
-    @address&.to_s || ''
+  def close
+    @socket&.close
+    self
+  rescue *NETWORK_ERRORS
+    self
+  ensure
+    @socket = @deadline = nil
   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}.
   #
-  # It accepts a connection-specific configuration or uses the global {.default_configuration}. The {#configuration} used by this instance will
-  # be a copy of the configuration used for this method call. This allows to
-  # configure the behavior per connection.
+  # 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 configuration [Configuration] the {Configuration} to be used for this instance
-  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +connect_timeout+.
-  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +connect_timeout_error+.
+  # @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>] 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
   #
+  # @see NetworkError
+  #
   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
 
   #
-  # Close the current connection.
+  # Flushes all internal buffers (write all buffered data).
   #
-  # @return [self]
+  # @return [TCPClient] itself
   #
-  def close
-    @socket&.close
-    self
-  rescue *NETWORK_ERRORS
+  def flush
+    stem_errors { @socket&.flush }
     self
-  ensure
-    @socket = @deadline = nil
   end
 
   #
-  # Executes a block with a given overall timeout.
+  # Read the given `nbytes` or the next available buffer from server.
+  #
+  # The optional `timeout` and `exception` parameters allow to override the
+  # `read_timeout` and `read_timeout_error` values of the used {#configuration}.
+  #
+  # @param nbytes [Integer] the number of bytes to read
+  # @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 buffer
+  #
+  # @raise [NotConnectedError] if {#connect} was not called before
+  #
+  # @see NetworkError
+  #
+  def read(nbytes = nil, timeout: nil, exception: nil)
+    raise(NotConnectedError) if closed?
+    deadline = create_deadline(timeout, configuration.read_timeout)
+    return stem_errors { @socket.read(nbytes) } unless deadline.valid?
+    exception ||= configuration.read_timeout_error
+    stem_errors(exception) do
+      @socket.read_with_deadline(nbytes, deadline, exception)
+    end
+  end
+
+  #
+  # Reads the next line from server.
+  #
+  # The standard record separator is used as `separator`.
   #
-  # When you like to ensure that a complete read/write communication sequence
-  # with the server is finished before a given amount of time you can use this
-  # method to define such a deadline.
+  # The optional `timeout` and `exception` parameters allow to override the
+  # `read_timeout` and `read_timeout_error` values of the used {#configuration}.
   #
-  # @example - ensure to send a welcome message and receive a 64 byte answer from server
+  # @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.
+  #
+  # @see Address#to_s
+  #
+  def to_s
+    @address&.to_s || ''
+  end
+
+  #
+  # 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
+  # this method.
+  #
+  # @example ensure to send SMTP welcome message and receive a 4 byte answer
   #   answer = client.with_deadline(2.5) do
-  #     client.write('Helo')
-  #     client.read(64)
+  #     client.write('HELO')
+  #     client.read(4)
   #   end
+  #   # answer is EHLO when server speaks fluent SMPT
   #
-  # @param timeout [Numeric] maximum time in seconds for all {#read} and {#write} calls within the block
+  # @param timeout [Numeric] maximum time in seconds for all {#read} and
+  #   {#write} calls within the block
   #
   # @yieldparam client [TCPClient] self
   #
-  # @return [Object] result of the given block
+  # @return [Object] the block's result
   #
   # @raise [NoBlockGivenError] if the block is missing
   #
@@ -186,37 +279,23 @@ class TCPClient
   end
 
   #
-  # Read the given nbytes or the next available buffer from server.
+  # Writes the given `messages` to the server.
   #
-  # @param nbytes [Integer] the number of bytes to read
-  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +read_timeout+.
-  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +read_timeout_error+.
+  # The optional `timeout` and `exception` parameters allow to override the
+  # `write_timeout` and `write_timeout_error` values of the used
+  # {#configuration}.
   #
-  # @return [String] buffer read
-  #
-  # @raise [NotConnectedError] if {#connect} was not called before
-  #
-  def read(nbytes = nil, timeout: nil, exception: nil)
-    raise(NotConnectedError) if closed?
-    deadline = create_deadline(timeout, configuration.read_timeout)
-    return stem_errors { @socket.read(nbytes) } unless deadline.valid?
-    exception ||= configuration.read_timeout_error
-    stem_errors(exception) do
-      @socket.read_with_deadline(nbytes, deadline, exception)
-    end
-  end
-
-  #
-  # Write the given messages to the server.
-  #
-  # @param messages [Array<String>] messages to write
-  # @param timeout [Numeric] maximum time in seconds to read; used to override the configuration's +write_timeout+.
-  # @param exception [Class] exception class to be used when the read timeout reached; used to override the configuration's +write_timeout_error+.
+  # @param messages [Array<String>] one or more messages to write
+  # @param timeout [Numeric] maximum time in seconds to write
+  # @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)
@@ -229,16 +308,6 @@ class TCPClient
     end
   end
 
-  #
-  # Flush all internal buffers (write all through).
-  #
-  # @return [self]
-  #
-  def flush
-    stem_errors { @socket&.flush }
-    self
-  end
-
   private
 
   def create_deadline(timeout, default)

data/rakefile.rb

@@ -7,7 +7,12 @@ require 'yard'
 
 $stdout.sync = $stderr.sync = true
 
-CLOBBER << 'prj' << 'doc'
+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)