tcp-client 0.9.0 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20df105b07989653ac9e9c877672318e1da4eb6a5171b088b137422ff03d22db
-  data.tar.gz: 393c2bf3f983f1da7dc8e3517b0cd7b170c2cdede3c546b603def84512e93806
+  metadata.gz: 114da301d59fc9cf9c3d3bda508f4d23b5b4991877a5dc7504d4da97114f8e7f
+  data.tar.gz: 9d0815501de340b485cba157aff05097597948d023a7eca6c45a8ead3a4e3d0d
 SHA512:
-  metadata.gz: c94f0a7c51cd5b33edf0de9fb02d454e539f95b79891ad81c81adb4832829059fc34b8c3d4e141594dd0b95752807f1c32dbc9c5192914a5ec02345bb056075c
-  data.tar.gz: 1ab3ef36b1534cf697c911c5d4ce01137dc9860598daa34765521cbec48fe6698294402cf0a0b768f2c460212cb3ce9378adb12ba7e65c76f1531e7bd66a1688
+  metadata.gz: a560644d578cedccaf1e2665f518b3a6a4e225886cfc561a8b62087420d93b958ee4741d8efde3b456fa15ce24fd5ee2f6a1121b55855205ffae5abf17becf97
+  data.tar.gz: f1f0ed0b87f8ee9c9b376b6b567c45aecb204c5b3de044c97f6ba080071c3c8e70da8bca8cca2484d5ddec06df181ee4b007e9ed826045e205d77df38eefbbbd

data/.yardopts

@@ -0,0 +1,5 @@
+--readme README.md
+--title 'tcp-client Documentation'
+--charset utf-8
+--markup markdown
+'lib/**/*.rb' - 'LICENSE'

data/README.md

@@ -2,6 +2,10 @@
 
 A TCP client implementation with working timeout support.
 
+- Gem: [rubygems.org](https://rubygems.org/gems/tcp-client)
+- Source: [github.com](https://github.com/mblumtritt/tcp-client)
+- Help: [rubydoc.info](https://rubydoc.info/github/mblumtritt/tcp-client/main/index)
+
 ## Description
 
 This Gem implements a TCP client with (optional) SSL support. It is an easy to use, versatile configurable client that can correctly handle time limits. Unlike other implementations, this client respects predefined/configurable time limits for each method (`connect`, `read`, `write`). Deadlines for a sequence of read/write actions can also be monitored.
@@ -30,6 +34,8 @@ TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
 end
 ```
 
+For more samples see [the samples dir](https://github.com/mblumtritt/tcp-client/tree/main/sample)
+
 ## Installation
 
 Use [Bundler](http://gembundler.com/) to use TCPClient in your own project:

data/gems.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
-source('https://rubygems.org') { gemspec }
+source 'https://rubygems.org'
+gemspec

data/lib/tcp-client/address.rb

@@ -21,24 +21,31 @@ class TCPClient
     # Initializes an address
     # @overload initialize(addr)
     #   The addr can be specified as
-    #   - a valid named address containing the port like +my.host.test:80+
-    #   - a valid TCPv4 address like +142.250.181.206:80+
-    #   - a valid TCPv6 address like +[2001:16b8:5093:3500:ad77:abe6:eb88:47b6]:80+
     #
-    #   @param addr [String] address string
+    #     - a valid named address containing the port like "my.host.test:80"
+    #     - a valid TCPv4 address like "142.250.181.206:80"
+    #     - a valid TCPv6 address like
+    #       "[2001:16b8:5093:3500:ad77:abe6:eb88:47b6]:80"
     #
-    # @overload initialize(address)
-    #   Used to create a copy
+    #   @example create an Address instance with a host name and port
+    #     Address.new('www.google.com:80')
+    #
+    #   @param addr [String] address containing host and port name
     #
-    #   @param address [Address]
     #
     # @overload initialize(addrinfo)
     #
+    #   @example create an Address with an Addrinfo
+    #     Address.new(Addrinfo.tcp('www.google.com', 'http'))
+    #
     #   @param addrinfo [Addrinfo] containing the addressed host and port
     #
     # @overload initialize(port)
     #   Adresses the port on the local machine.
     #
+    #   @example create an Address for localhost on port 80
+    #     Address.new(80)
+    #
     #   @param port [Integer] the addressed port
     #
     def initialize(addr)
@@ -56,18 +63,27 @@ class TCPClient
     end
 
     #
-    # @return [String] text representation of self as "<host>:<port>"
+    # @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
@@ -89,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
 
@@ -102,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,55 +6,56 @@ 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 initialize a new configuration.
+    # Shorthand to create a new configuration.
     #
+    # @overload create()
     #   @example
     #     config = TCPClient::Configuration.create do |cfg|
     #       cfg.buffered = false
     #       cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
     #     end
     #
-    #   @yieldparam cfg {Configuration}
+    #   @yieldparam configuration {Configuration}
     #
-    #   @return [Configuration] the initialized configuration
+    # @overload create(options)
+    #   @example
+    #     config = TCPClient::Configuration.create(buffered: false)
+    #
+    #   @param options [Hash<Symbol,Object>] see {#initialize} for details
+    #
+    # @return [Configuration] the initialized configuration
     #
     def self.create(options = {})
-      cfg = new(options)
-      yield(cfg) if block_given?
-      cfg
+      configuration = new(options)
+      yield(configuration) if block_given?
+      configuration
     end
 
     #
     # Intializes the instance with given options.
     #
-    # @param options [Hash]
+    # @param options [Hash<Symbol,Object>]
     # @option options [Boolean] :buffered, see {#buffered}
     # @option options [Boolean] :keep_alive, see {#keep_alive}
     # @option options [Boolean] :reverse_lookup, see {#reverse_lookup}
-    # @option options [Boolean] :normalize_network_errors, see {#normalize_network_errors}
+    # @option options [Hash<Symbol, Object>] :ssl_params, see {#ssl_params}
     # @option options [Numeric] :connect_timeout, see {#connect_timeout}
-    # @option options [Exception] :connect_timeout_error, see {#connect_timeout_error}
+    # @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 {#write_timeout_error}
-    # @option options [Hash<Symbol, Object>] :ssl_params, see {#ssl_params}
+    # @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
@@ -66,11 +67,13 @@ class TCPClient
       options.each_pair { |attribute, value| set(attribute, value) }
     end
 
+    # @!group Instance Attributes Socket Level
+
     #
-    # Enables/disables use of Socket-level buffers.
+    # 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] wheter the connection is allowed to use internal buffers
+    #   (default) or not
     #
     attr_reader :buffered
 
@@ -81,8 +84,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] wheter the connection is allowed to use keep alive
+    #   signals (default) or not
     #
     attr_reader :keep_alive
 
@@ -93,8 +96,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] wheter the connection is allowed to lookup the address
+    #   (default) or not
     #
     attr_reader :reverse_lookup
 
@@ -103,55 +106,45 @@ class TCPClient
     end
 
     #
-    # Enables/disables if network exceptions should be raised as {NetworkError}.
-    #
-    # @return [true] if all network exceptions should be raised as {NetworkError}
-    # @return [false] if socket/system errors should not be normalzed (default)
+    # @!parse attr_reader :ssl?
+    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
     #
-    attr_reader :normalize_network_errors
-
-    def normalize_network_errors=(value)
-      @normalize_network_errors = value ? true : false
+    def ssl?
+      @ssl_params ? true : false
     end
 
     #
-    # @attribute [w] timeout
-    # Shorthand to set timeout value for connect, read and write at once or to disable any timeout monitoring
+    # Parameters used to initialize a SSL context. SSL/TLS will only be used if
+    # this attribute is not `nil`.
     #
-    # @return [Numeric] maximum time in seconds for any action
-    # @return [nil] if all timeout monitoring should be disabled (default)
-    #
-    # @see #connect_timeout
-    # @see #read_timeout
-    # @see #write_timeout
+    # @return [Hash<Symbol, Object>] SSL parameters for the SSL context
+    # @return [nil] if no SSL should be used (default)
     #
-    def timeout=(value)
-      @connect_timeout = @write_timeout = @read_timeout = seconds(value)
-    end
+    attr_reader :ssl_params
 
-    #
-    # @attribute [w] timeout_error
-    # Shorthand to configure exception class raised when connect, read or write exceeded the configured timeout
-    #
-    # @return [Class] exception class raised
-    #
-    # @raise [NotAnExceptionError] if given argument is not an Exception class
-    #
-    # @see #connect_timeout_error
-    # @see #read_timeout_error
-    # @see #write_timeout_error
-    #
-    def timeout_error=(value)
-      raise(NotAnExceptionError, value) unless exception_class?(value)
-      @connect_timeout_error =
-        @read_timeout_error = @write_timeout_error = value
+    def ssl_params=(value)
+      @ssl_params =
+        if value.respond_to?(:to_hash)
+          Hash[value.to_hash]
+        elsif value.respond_to?(:to_h)
+          value.nil? ? nil : Hash[value.to_h]
+        else
+          value ? {} : nil
+        end
     end
+    alias ssl= ssl_params=
+
+    # @!endgroup
+
+    # @!group Instance Attributes Timeout Monitoring
 
     #
-    # Configures maximum time in seconds to establish a connection.
+    # The maximum time in seconds to establish a connection.
     #
-    # @return [Numeric] maximum time in seconds to establish a connection
-    # @return [nil] if the connect time should not be checked (default)
+    # @return [Numeric] maximum time in seconds
+    # @return [nil] if the connect time should not be monitored (default)
+    #
+    # @see TCPClient#connect
     #
     attr_reader :connect_timeout
 
@@ -160,7 +153,10 @@ class TCPClient
     end
 
     #
-    # @return [Class] exception class raised if a {TCPClient#connect} timed out
+    # The exception class which will be raised if {TCPClient#connect} can not
+    # be finished in time.
+    #
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :connect_timeout_error
@@ -171,10 +167,12 @@ class TCPClient
     end
 
     #
-    # Configures maximum time in seconds to finish a {TCPClient#read}.
+    # The maximum time in seconds to read from a connection.
     #
-    # @return [Numeric] maximum time in seconds to finish a {TCPClient#read} request
-    # @return [nil] if the read time should not be checked (default)
+    # @return [Numeric] maximum time in seconds
+    # @return [nil] if the read time should not be monitored (default)
+    #
+    # @see TCPClient#read
     #
     attr_reader :read_timeout
 
@@ -183,7 +181,10 @@ class TCPClient
     end
 
     #
-    # @return [Class] exception class raised if a {TCPClient#read} timed out
+    # The exception class which will be raised if {TCPClient#read} can not be
+    # finished in time.
+    #
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :read_timeout_error
@@ -194,10 +195,12 @@ class TCPClient
     end
 
     #
-    # Configures maximum time in seconds to finish a {TCPClient#write}.
+    # The maximum time in seconds to write to a connection.
     #
-    # @return [Numeric] maximum time in seconds to finish a {TCPClient#write} request
-    # @return [nil] if the write time should not be checked (default)
+    # @return [Numeric] maximum time in seconds
+    # @return [nil] if the write time should not be monitored (default)
+    #
+    # @see TCPClient#write
     #
     attr_reader :write_timeout
 
@@ -206,7 +209,10 @@ class TCPClient
     end
 
     #
-    # @return [Class] exception class raised if a {TCPClient#write} timed out
+    # The exception class which will be raised if {TCPClient#write} can not be
+    # finished in time.
+    #
+    # @return [Class<Exception>] exception class raised
     # @raise [NotAnExceptionError] if given argument is not an Exception class
     #
     attr_reader :write_timeout_error
@@ -217,48 +223,78 @@ class TCPClient
     end
 
     #
-    # @attribute ssl?
-    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
+    # @attribute [w] timeout
+    # Shorthand to set maximum time in seconds for all timeout monitoring.
     #
-    def ssl?
-      @ssl_params ? true : false
+    # @return [Numeric] maximum time in seconds for any actwion
+    # @return [nil] if all timeout monitoring should be disabled (default)
+    #
+    # @see #connect_timeout
+    # @see #read_timeout
+    # @see #write_timeout
+    #
+    def timeout=(value)
+      @connect_timeout = @write_timeout = @read_timeout = seconds(value)
     end
 
     #
-    # Configures the SSL parameters used to initialize a SSL context.
+    # @attribute [w] timeout_error
+    # Shorthand to set the exception class wich will by raised by any reached
+    # timeout.
     #
-    # @return [Hash<Symbol, Object>] SSL parameters for the SSL context
-    # @return [nil] if no SSL should be used (default)
+    # @return [Class<Exception>] exception class raised
     #
-    attr_reader :ssl_params
+    # @raise [NotAnExceptionError] if given argument is not an Exception class
+    #
+    # @see #connect_timeout_error
+    # @see #read_timeout_error
+    # @see #write_timeout_error
+    #
+    def timeout_error=(value)
+      raise(NotAnExceptionError, value) unless exception_class?(value)
+      @connect_timeout_error =
+        @read_timeout_error = @write_timeout_error = value
+    end
 
-    def ssl_params=(value)
-      @ssl_params =
-        if value.respond_to?(:to_hash)
-          Hash[value.to_hash]
-        elsif value.respond_to?(:to_h)
-          Hash[value.to_h]
-        else
-          value ? {} : nil
-        end
+    # @!endgroup
+
+    #
+    # Enables/disables if network exceptions should be raised as {NetworkError}.
+    #
+    # This allows to handle all network/socket related exceptions like
+    # `SocketError`, `OpenSSL::SSL::SSLError`, `IOError`, etc. in a uniform
+    # 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
+    #   {NetworkError}, or not (default)
+    #
+    attr_reader :normalize_network_errors
+
+    def normalize_network_errors=(value)
+      @normalize_network_errors = value ? true : false
     end
-    alias ssl= ssl_params=
 
     #
-    # @return [Hash] configuration as a Hash
+    # Convert `self` to a Hash containing all attributes.
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    # @see #initialize
     #
     def to_h
       {
         buffered: @buffered,
         keep_alive: @keep_alive,
         reverse_lookup: @reverse_lookup,
+        ssl_params: @ssl_params,
         connect_timeout: @connect_timeout,
         connect_timeout_error: @connect_timeout_error,
         read_timeout: @read_timeout,
         read_timeout_error: @read_timeout_error,
         write_timeout: @write_timeout,
         write_timeout_error: @write_timeout_error,
-        ssl_params: @ssl_params
+        normalize_network_errors: @normalize_network_errors
       }
     end
 

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

@@ -7,13 +7,17 @@ class TCPClient
 
   class << self
     #
-    # @return [Configuration] used by default if no dedicated configuration was specified
+    # The default configuration.
+    # This is used by default if no dedicated configuration was specified to
+    # {.open} or {#connect}.
+    #
+    # @return [Configuration]
     #
     attr_reader :default_configuration
 
     #
-    # Configure the default configuration which is used if no dedicated
-    # configuration was specified.
+    # Configure the {.default_configuration} which is used if no dedicated
+    # configuration was specified to {.open} or {#connect}.
     #
     # @example
     #   TCPClient.configure do |cfg|
@@ -33,11 +37,19 @@ class TCPClient
   end
 
   class Configuration
-    #
-    # @return [Configuration] used by default if no dedicated configuration was specified
-    #
-    def self.default
-      TCPClient.default_configuration
+    class << self
+      #
+      # @!parse attr_reader :default
+      # @return [Configuration] used by default if no dedicated configuration
+      # was specified
+      #
+      # @see TCPClient.open
+      # @see TCPClient.with_deadline
+      # @see TCPClient#connect
+      #
+      def default
+        TCPClient.default_configuration
+      end
     end
   end
 end

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 establshed 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 atttribute
+    #
     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/version.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
 class TCPClient
-  #
-  # The current gem version.
-  #
-  VERSION = '0.9.0'
+  VERSION = '0.9.4'
 end

data/lib/tcp-client.rb

@@ -15,7 +15,7 @@ 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
+# @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)
@@ -26,7 +26,17 @@ require_relative 'tcp-client/version'
 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.
@@ -36,13 +46,10 @@ class TCPClient
   # If no block is giiven 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
   #
@@ -55,24 +62,29 @@ class TCPClient
   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.
+  #
+  # It ensures to close the connection when the block execution ends and returns
+  # the block`s result.
   #
   # 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.
+  # 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 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 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
   #
@@ -89,89 +101,135 @@ 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] wheter 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 [self]
   #
-  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 given `address`.
   #
-  # 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.
+  # It accepts a connection-specific `configuration` or uses the
+  # {.default_configuration}.
   #
-  # @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+.
+  # 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
+  #   {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]
   #
   # @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
-    raise(NoOpenSSLError) if configuration.ssl? && !defined?(SSLSocket)
     @address = Address.new(address)
     @configuration = (configuration || Configuration.default).dup
+    raise(NoOpenSSLError) if @configuration.ssl? && !defined?(SSLSocket)
     @socket = create_socket(timeout, exception)
     self
   end
 
   #
-  # Close the current connection.
+  # Flushes all internal buffers (write all through).
   #
   # @return [self]
   #
-  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
+
+  #
+  # @return [String] the currently used address as text.
   #
-  # 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.
+  # @see Address#to_s
   #
-  # @example - ensure to send a welcome message and receive a 64 byte answer from server
+  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,32 +244,16 @@ class TCPClient
   end
 
   #
-  # Read the given nbytes or the next available buffer from 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+.
-  #
-  # @return [String] buffer read
-  #
-  # @raise [NotConnectedError] if {#connect} was not called before
+  # Writes the given `messages` to the server.
   #
-  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
-
+  # The optional `timeout` and `exception` parameters allow to override the
+  # `write_timeout` and `write_timeout_error` values of the used
+  # {#configuration}.
   #
-  # 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
   #
@@ -229,16 +271,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)
@@ -277,4 +309,5 @@ class TCPClient
     ].tap do |errors|
       errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
     end.freeze
+  private_constant(:NETWORK_ERRORS)
 end

data/rakefile.rb

@@ -6,8 +6,7 @@ require 'rspec/core/rake_task'
 require 'yard'
 
 $stdout.sync = $stderr.sync = true
-
-CLOBBER << 'prj' << 'doc'
+CLOBBER << 'prj' << 'doc' << '.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/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

@@ -82,7 +82,7 @@ RSpec.describe TCPClient::Configuration do
         expect(configuration.keep_alive).to be false
       end
 
-      it 'allows to configure reverse address lokup' do
+      it 'allows to configure reverse address lookup' do
         expect(configuration.reverse_lookup).to be false
       end
 
@@ -148,7 +148,7 @@ RSpec.describe TCPClient::Configuration do
       end
     end
 
-    context 'with invalid attribte' do
+    context 'with invalid attribute' do
       it 'raises an error' do
         expect { TCPClient::Configuration.new(invalid: :value) }.to raise_error(
           TCPClient::UnknownAttributeError
@@ -182,6 +182,7 @@ RSpec.describe TCPClient::Configuration do
         read_timeout_error: TCPClient::ReadTimeoutError,
         write_timeout: 3,
         write_timeout_error: TCPClient::WriteTimeoutError,
+        normalize_network_errors: false,
         ssl_params: {
           min_version: :TLS1_2,
           max_version: :TLS1_3
@@ -232,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
@@ -253,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

data/tcp-client.gemspec

@@ -5,12 +5,11 @@ require_relative './lib/tcp-client/version'
 Gem::Specification.new do |spec|
   spec.name = 'tcp-client'
   spec.version = TCPClient::VERSION
-  spec.author = 'Mike Blumtritt'
-
   spec.required_ruby_version = '>= 2.7.0'
 
+  spec.author = 'Mike Blumtritt'
   spec.summary = 'A TCP client implementation with working timeout support.'
-  spec.description = <<~DESCRIPTION
+  spec.description = <<~description
     This Gem implements a TCP client with (optional) SSL support.
     It is an easy to use, versatile configurable client that can correctly
     handle time limits.
@@ -18,13 +17,15 @@ Gem::Specification.new do |spec|
     predefined/configurable time limits for each method
     (`connect`, `read`, `write`). Deadlines for a sequence of read/write
     actions can also be monitored.
-  DESCRIPTION
+  description
+
   spec.homepage = 'https://github.com/mblumtritt/tcp-client'
   spec.license = 'BSD-3-Clause'
-
-  spec.metadata['source_code_uri'] = 'https://github.com/mblumtritt/tcp-client'
-  spec.metadata['bug_tracker_uri'] =
-    'https://github.com/mblumtritt/tcp-client/issues'
+  spec.metadata.merge!(
+    'source_code_uri' => 'https://github.com/mblumtritt/tcp-client',
+    'bug_tracker_uri' => 'https://github.com/mblumtritt/tcp-client/issues',
+    'documentation_uri' => 'https://rubydoc.info/github/mblumtritt/tcp-client'
+  )
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
@@ -34,6 +35,5 @@ Gem::Specification.new do |spec|
   all_files = Dir.chdir(__dir__) { `git ls-files -z`.split(0.chr) }
   spec.test_files = all_files.grep(%r{^spec/})
   spec.files = all_files - spec.test_files
-
   spec.extra_rdoc_files = %w[README.md LICENSE]
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.4
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-01 00:00:00.000000000 Z
+date: 2021-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -82,6 +82,7 @@ extra_rdoc_files:
 - LICENSE
 files:
 - ".gitignore"
+- ".yardopts"
 - LICENSE
 - README.md
 - gems.rb
@@ -112,6 +113,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/mblumtritt/tcp-client
   bug_tracker_uri: https://github.com/mblumtritt/tcp-client/issues
+  documentation_uri: https://rubydoc.info/github/mblumtritt/tcp-client
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -127,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.28
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: A TCP client implementation with working timeout support.