tcp-client 0.9.3 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75811fed2b0735c2cac6a4e9671e138df88e6b8ada2be03a0d86b4b83b37b863
-  data.tar.gz: 9c715081912711178a0038d9af9832cf6c45e2620c2cff6dad899565de86be02
+  metadata.gz: 114da301d59fc9cf9c3d3bda508f4d23b5b4991877a5dc7504d4da97114f8e7f
+  data.tar.gz: 9d0815501de340b485cba157aff05097597948d023a7eca6c45a8ead3a4e3d0d
 SHA512:
-  metadata.gz: d2842f5bd4fa2806c15bb94d6c1da9a897be40959a5db9033f404f1c980648a997daee0d49ad1fb75e4cf680644f72dfb04e880eb0c9e9ba9207d6ee3dd75240
-  data.tar.gz: 174878bab1414b1ef49bd67a1f296d21e463bd7d817442340192aace8af88e56d941b647ad43ff0ed5126e2c2ab16e0159c0467dd7a08289d93c423ca520e2cb
+  metadata.gz: a560644d578cedccaf1e2665f518b3a6a4e225886cfc561a8b62087420d93b958ee4741d8efde3b456fa15ce24fd5ee2f6a1121b55855205ffae5abf17becf97
+  data.tar.gz: f1f0ed0b87f8ee9c9b376b6b567c45aecb204c5b3de044c97f6ba080071c3c8e70da8bca8cca2484d5ddec06df181ee4b007e9ed826045e205d77df38eefbbbd

data/lib/tcp-client/address.rb

@@ -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 [Hash<Symbol,Object>] see {#initialize} for details
+    #
+    # @return [Configuration] the initialized configuration
     #
     def self.create(options = {})
       configuration = new(options)
@@ -43,18 +39,19 @@ class TCPClient
     #
     # 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 [Hash<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}
@@ -75,9 +72,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] wheter the connection is allowed to use internal buffers
+    #   (default) or not
     #
     attr_reader :buffered
 
@@ -88,9 +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
 
@@ -101,9 +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
 
@@ -120,7 +114,8 @@ class TCPClient
     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 [nil] if no SSL should be used (default)
@@ -161,7 +156,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 +184,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 +212,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
@@ -244,9 +239,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 wich 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 +266,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] wheter all network exceptions should be raised as
+    #   {NetworkError}, or not (default)
     #
     attr_reader :normalize_network_errors
 

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/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
@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class TCPClient
-  VERSION = '0.9.3'
+  VERSION = '0.9.4'
 end

data/lib/tcp-client.rb

@@ -30,6 +30,14 @@ 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
@@ -38,15 +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 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
   #
@@ -59,8 +62,8 @@ class TCPClient
   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
@@ -68,19 +71,18 @@ class TCPClient
   #
   # This can be used to create an ad-hoc connection which is garanteed 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
   #
@@ -110,7 +112,7 @@ class TCPClient
 
   #
   # @!parse attr_reader :closed?
-  # @return [Boolean] true when the connection is closed, false when connected
+  # @return [Boolean] wheter the connection is closed
   #
   def closed?
     @socket.nil? || @socket.closed?
@@ -133,21 +135,19 @@ class TCPClient
   #
   # Establishes a new connection to a 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]
   #
@@ -165,7 +165,7 @@ class TCPClient
   end
 
   #
-  # Flush all internal buffers (write all through).
+  # Flushes all internal buffers (write all through).
   #
   # @return [self]
   #
@@ -182,8 +182,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
   #
@@ -211,7 +211,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,7 +228,6 @@ class TCPClient
   #   {#write} calls within the block
   #
   # @yieldparam client [TCPClient] self
-  # @yieldreturn [Object] any result
   #
   # @return [Object] the block`s result
   #
@@ -245,16 +244,16 @@ 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
   #

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.9.4
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-07 00:00:00.000000000 Z
+date: 2021-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler