tcp-client 0.9.3 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75811fed2b0735c2cac6a4e9671e138df88e6b8ada2be03a0d86b4b83b37b863
-  data.tar.gz: 9c715081912711178a0038d9af9832cf6c45e2620c2cff6dad899565de86be02
+  metadata.gz: 02440fe17a1480ba18bec8b6918cea6420a065d997c423a6602e165e0f316564
+  data.tar.gz: 73e315f2c80a2f0f1cf0cb57b24f2f2cd45e10caffebd83dd47510ea85de1f25
 SHA512:
-  metadata.gz: d2842f5bd4fa2806c15bb94d6c1da9a897be40959a5db9033f404f1c980648a997daee0d49ad1fb75e4cf680644f72dfb04e880eb0c9e9ba9207d6ee3dd75240
-  data.tar.gz: 174878bab1414b1ef49bd67a1f296d21e463bd7d817442340192aace8af88e56d941b647ad43ff0ed5126e2c2ab16e0159c0467dd7a08289d93c423ca520e2cb
+  metadata.gz: bb22bb974aacd8cfc9d4a1ebcc66393172ec949db8038ecbc37c1a4187bb8a1d703206625f25fb7dba5e336217d2de31475220aa4147bc20df26a5deff7bd7b7
+  data.tar.gz: 0fd048dda8d10ba76659276cd7f5c09e1fba73560d482a5cbbb35ba6db034192137552531dcd294d45a50a10a211839b318015d0546ded7df28c8f55246fe7fd

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)
@@ -62,19 +62,28 @@ class TCPClient
       @addrinfo.freeze
     end
 
+    #
+    # @attribute [r] port
+    # @return [Integer] the port number
+    #
+    def port
+      @addrinfo.ip_port
+    end
+
     #
     # @return [String] text representation of self as "host:port"
     #
     def to_s
-      return "[#{@hostname}]:#{@addrinfo.ip_port}" if @hostname.index(':') # IP6
-      "#{@hostname}:#{@addrinfo.ip_port}"
+      hostname.index(':') ? "[#{hostname}]:#{port}" : "#{hostname}:#{port}"
     end
 
     #
-    # @return [Hash] containing the host and port
+    # Convert `self` to a Hash containing host and port attribute.
+    #
+    # @return [Hash] host and port
     #
     def to_h
-      { host: @hostname, port: @addrinfo.ip_port }
+      { host: hostname, port: port }
     end
 
     # @!visibility private
@@ -96,7 +105,7 @@ class TCPClient
     end
 
     def init_from_addrinfo(addrinfo)
-      @hostname, _port = addrinfo.getnameinfo(Socket::NI_NUMERICSERV)
+      @hostname = addrinfo.getnameinfo(Socket::NI_NUMERICSERV).first
       @addrinfo = addrinfo
     end
 
@@ -109,7 +118,7 @@ class TCPClient
     def from_string(str)
       idx = str.rindex(':') or return nil, str.to_i
       name = str[0, idx].delete_prefix('[').delete_suffix(']')
-      [name, str[idx + 1, str.size - idx].to_i]
+      [name.empty? ? nil : name, str[idx + 1, str.size - idx].to_i]
     end
   end
 end

data/lib/tcp-client/configuration.rb

@@ -6,24 +6,14 @@ class TCPClient
   #
   # A Configuration is used to configure the behavior of a {TCPClient} instance.
   #
-  # It allows to specify to monitor timeout, how to handle exceptions, if SSL
+  # It allows to specify the monitor timeout, how to handle exceptions, if SSL
   # should be used and to setup the underlying Socket.
   #
   class Configuration
     #
-    # @overload create(options)
-    #   Shorthand to create a new configuration with given options.
-    #
-    #   @example
-    #     config = TCPClient::Configuration.create(buffered: false)
-    #
-    #   @param options [Hash] see {#initialize} for details
-    #
-    #   @return [Configuration] the initialized configuration
-    #
-    # @overload create(&block)
-    #   Shorthand to create a new configuration within a code block.
+    # Shorthand to create a new configuration.
     #
+    # @overload create()
     #   @example
     #     config = TCPClient::Configuration.create do |cfg|
     #       cfg.buffered = false
@@ -32,7 +22,13 @@ class TCPClient
     #
     #   @yieldparam configuration {Configuration}
     #
-    #   @return [Configuration] the initialized configuration
+    # @overload create(options)
+    #   @example
+    #     config = TCPClient::Configuration.create(buffered: false)
+    #
+    #   @param options [{Symbol => Object}] see {#initialize} for details
+    #
+    # @return [Configuration] the initialized configuration
     #
     def self.create(options = {})
       configuration = new(options)
@@ -41,25 +37,25 @@ class TCPClient
     end
 
     #
-    # Intializes the instance with given options.
+    # Initializes the instance with given options.
     #
-    # @param 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 [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 [Exception] :connect_timeout_error, see
+    # @option options [Class<Exception>] :connect_timeout_error, see
     #   {#connect_timeout_error}
     # @option options [Numeric] :read_timeout, see {#read_timeout}
-    # @option options [Exception] :read_timeout_error, see {#read_timeout_error}
+    # @option options [Class<Exception>] :read_timeout_error, see
+    #   {#read_timeout_error}
     # @option options [Numeric] :write_timeout, see {#write_timeout}
-    # @option options [Exception] :write_timeout_error, see
+    # @option options [Class<Exception>] :write_timeout_error, see
     #   {#write_timeout_error}
     # @option options [Boolean] :normalize_network_errors, see
     #   {#normalize_network_errors}
     #
-    #
     def initialize(options = {})
       @buffered = @keep_alive = @reverse_lookup = true
       self.timeout = @ssl_params = nil
@@ -75,9 +71,8 @@ class TCPClient
     #
     # Enables/disables use of Socket-level buffering
     #
-    # @return [true] if the connection is allowed to use internal buffers
-    #   (default)
-    # @return [false] if buffering is not allowed
+    # @return [Boolean] whether the connection is allowed to use internal
+    #   buffers (default) or not
     #
     attr_reader :buffered
 
@@ -88,9 +83,8 @@ class TCPClient
     #
     # Enables/disables use of Socket-level keep alive handling.
     #
-    # @return [true] if the connection is allowed to use keep alive signals
-    #   (default)
-    # @return [false] if the connection should not check keep alive
+    # @return [Boolean] whether the connection is allowed to use keep alive
+    #   signals (default) or not
     #
     attr_reader :keep_alive
 
@@ -101,9 +95,8 @@ class TCPClient
     #
     # Enables/disables address lookup.
     #
-    # @return [true] if the connection is allowed to lookup the address
-    #   (default)
-    # @return [false] if the address lookup is not required
+    # @return [Boolean] whether the connection is allowed to lookup the address
+    #   (default) or not
     #
     attr_reader :reverse_lookup
 
@@ -113,16 +106,17 @@ 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
     end
 
     #
-    # Parameters used to initialize a SSL context.
+    # 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
@@ -161,7 +155,7 @@ class TCPClient
     # The exception class which will be raised if {TCPClient#connect} can not
     # be finished in time.
     #
-    # @return [Class] exception class raised
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :connect_timeout_error
@@ -189,7 +183,7 @@ class TCPClient
     # The exception class which will be raised if {TCPClient#read} can not be
     # finished in time.
     #
-    # @return [Class] exception class raised
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :read_timeout_error
@@ -217,7 +211,7 @@ class TCPClient
     # The exception class which will be raised if {TCPClient#write} can not be
     # finished in time.
     #
-    # @return [Class] exception class raised
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :write_timeout_error
@@ -231,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
@@ -244,9 +238,10 @@ class TCPClient
 
     #
     # @attribute [w] timeout_error
-    # Shorthand to set the exception class wich will by raised by any timeout.
+    # Shorthand to set the exception class which will by raised by any reached
+    # timeout.
     #
-    # @return [Class] exception class raised
+    # @return [Class<Exception>] exception class raised
     #
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
@@ -270,9 +265,8 @@ class TCPClient
     # manner. If this option is set to true all these error cases are raised as
     # {NetworkError} and can be easily captured.
     #
-    # @return [true] if all network exceptions should be raised as
-    #   {NetworkError}
-    # @return [false] if socket/system errors should not be normalzed (default)
+    # @return [Boolean] whether all network exceptions should be raised as
+    #   {NetworkError}, or not (default)
     #
     attr_reader :normalize_network_errors
 
@@ -281,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/deadline.rb

@@ -2,8 +2,6 @@
 
 class TCPClient
   class Deadline
-    MONOTONIC = defined?(Process::CLOCK_MONOTONIC) ? true : false
-
     def initialize(timeout)
       timeout = timeout&.to_f
       @deadline = timeout&.positive? ? now + timeout : 0
@@ -19,7 +17,7 @@ class TCPClient
 
     private
 
-    if MONOTONIC
+    if defined?(Process::CLOCK_MONOTONIC)
       def now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/tcp-client/default_configuration.rb

@@ -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,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
@@ -36,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}")
@@ -58,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
@@ -77,7 +82,8 @@ 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
     #

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

@@ -1,111 +1,149 @@
 # 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
+      if methods.index(:wait_writable) && methods.index(:wait_readable)
+        mod.include(ViaWaitMethod)
+      elsif methods.index(:to_io)
+        mod.include(ViaIOWaitMethod)
+      else
+        mod.include(ViaSelect)
+      end
     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
-      )
-    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_with_deadline(nbytes, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      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
+      fetch_buffer_slice(nbytes)
     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 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)
+      return fetch_buffer_slice(index + sep.bytesize) if index
+      result = @buf
+      @buf = nil
+      result
     end
-  end
 
-  module ViaWaitMethod
-    private def with_deadline(deadline, exception)
+    def write_with_deadline(data, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      return 0 if (size = data.bytesize).zero?
+      result = 0
       loop do
-        case ret = yield
-        when :wait_writable
-          remaining_time = deadline.remaining_time or raise(exception)
-          raise(exception) if wait_writable(remaining_time).nil?
-        when :wait_readable
-          remaining_time = deadline.remaining_time or raise(exception)
-          raise(exception) if wait_readable(remaining_time).nil?
-        else
-          return ret
+        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
+
+    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
+          case ret = yield
+          when :wait_writable
+            remaining_time = deadline.remaining_time or raise(exception)
+            raise(exception) if wait_writable(remaining_time).nil?
+          when :wait_readable
+            remaining_time = deadline.remaining_time or raise(exception)
+            raise(exception) if wait_readable(remaining_time).nil?
+          else
+            return ret
+          end
         end
+      rescue Errno::ETIMEDOUT
+        raise(exception)
       end
-    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
+    module ViaIOWaitMethod
+      private def with_deadline(deadline, exception)
+        loop do
+          case ret = yield
+          when :wait_writable
+            remaining_time = deadline.remaining_time or raise(exception)
+            raise(exception) if to_io.wait_writable(remaining_time).nil?
+          when :wait_readable
+            remaining_time = deadline.remaining_time or raise(exception)
+            raise(exception) if to_io.wait_readable(remaining_time).nil?
+          else
+            return ret
+          end
         end
+      rescue Errno::ETIMEDOUT
+        raise(exception)
       end
-    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
+    module ViaSelect
+      private def with_deadline(deadline, exception)
+        loop do
+          case ret = yield
+          when :wait_writable
+            remaining_time = deadline.remaining_time or raise(exception)
+            if ::IO.select(nil, [self], nil, remaining_time).nil?
+              raise(exception)
+            end
+          when :wait_readable
+            remaining_time = deadline.remaining_time or raise(exception)
+            if ::IO.select([self], nil, nil, remaining_time).nil?
+              raise(exception)
+            end
+          else
+            return ret
+          end
         end
+      rescue Errno::ETIMEDOUT
+        raise(exception)
       end
-    rescue Errno::ETIMEDOUT
-      raise(exception)
     end
+
+    private_constant(:ViaWaitMethod, :ViaIOWaitMethod, :ViaSelect)
   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.3'
+  # The current version number.
+  VERSION = '0.10.1'
 end