tcp-client 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14f787ad4e8e06910bfebf67755ae7142183df4c4fb090edce84aae7d497a2b6
-  data.tar.gz: 6349bea2eac6bac053c724e0c6a162b1fe99502e94cf1c6734854d97f194f37a
+  metadata.gz: 20df105b07989653ac9e9c877672318e1da4eb6a5171b088b137422ff03d22db
+  data.tar.gz: 393c2bf3f983f1da7dc8e3517b0cd7b170c2cdede3c546b603def84512e93806
 SHA512:
-  metadata.gz: b53fafbf091a67a329832663c058b4e8243b36a779f8bc52cc7f37de556ad0aa016245e0a059489b972e6afaccfea7d26a63a735686d5f50d88036a2f4ecaca1
-  data.tar.gz: 4a6ff368e221073c5addfab51e31df1b094ee3f69e09ebe3f38d6d552ebc761b14c552a1a2cd90dcfd148b1ba34ebb1b2e3abfcea9622ded8413870f21a60285
+  metadata.gz: c94f0a7c51cd5b33edf0de9fb02d454e539f95b79891ad81c81adb4832829059fc34b8c3d4e141594dd0b95752807f1c32dbc9c5192914a5ec02345bb056075c
+  data.tar.gz: 1ab3ef36b1534cf697c911c5d4ce01137dc9860598daa34765521cbec48fe6698294402cf0a0b768f2c460212cb3ce9378adb12ba7e65c76f1531e7bd66a1688

data/.gitignore

@@ -1,4 +1,6 @@
-local/
 tmp/
 pkg/
+local/
+doc/
+.yardoc/
 gems.locked

data/README.md

@@ -30,7 +30,7 @@ TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
 end
 ```
 
-### Installation
+## Installation
 
 Use [Bundler](http://gembundler.com/) to use TCPClient in your own project:
 

data/lib/tcp-client/address.rb

@@ -3,9 +3,44 @@
 require 'socket'
 
 class TCPClient
+  #
+  # The address used by a TCPClient
+  #
   class Address
-    attr_reader :hostname, :addrinfo
+    #
+    # @return [String] the host name
+    #
+    attr_reader :hostname
 
+    #
+    # @return [Addrinfo] the address info
+    #
+    attr_reader :addrinfo
+
+    #
+    # 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
+    #
+    # @overload initialize(address)
+    #   Used to create a copy
+    #
+    #   @param address [Address]
+    #
+    # @overload initialize(addrinfo)
+    #
+    #   @param addrinfo [Addrinfo] containing the addressed host and port
+    #
+    # @overload initialize(port)
+    #   Adresses the port on the local machine.
+    #
+    #   @param port [Integer] the addressed port
+    #
     def initialize(addr)
       case addr
       when self.class
@@ -20,24 +55,28 @@ class TCPClient
       @addrinfo.freeze
     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}"
     end
 
-    def to_hash
+    #
+    # @return [Hash] containing the host and port
+    #
+    def to_h
       { host: @hostname, port: @addrinfo.ip_port }
     end
 
-    def to_h(*args)
-      args.empty? ? to_hash : to_hash.slice(*args)
-    end
-
+    # @!visibility private
     def ==(other)
-      to_hash == other.to_hash
+      to_h == other.to_h
     end
     alias eql? ==
 
+    # @!visibility private
     def equal?(other)
       self.class == other.class && self == other
     end

data/lib/tcp-client/configuration.rb

@@ -3,25 +3,59 @@
 require_relative 'errors'
 
 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
+  # 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.
+    #
+    #   @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}
+    #
+    #   @return [Configuration] the initialized configuration
+    #
     def self.create(options = {})
-      ret = new(options)
-      yield(ret) if block_given?
-      ret
-    end
-
-    attr_reader :buffered,
-                :keep_alive,
-                :reverse_lookup,
-                :normalize_network_errors,
-                :connect_timeout,
-                :read_timeout,
-                :write_timeout,
-                :connect_timeout_error,
-                :read_timeout_error,
-                :write_timeout_error
-    attr_accessor :ssl_params
+      cfg = new(options)
+      yield(cfg) if block_given?
+      cfg
+    end
 
+    #
+    # Intializes the instance with given options.
+    #
+    # @param options [Hash]
+    # @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 [Numeric] :connect_timeout, see {#connect_timeout}
+    # @option options [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 [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}
+    #
     def initialize(options = {})
       @buffered = @keep_alive = @reverse_lookup = true
       self.timeout = @ssl_params = nil
@@ -32,84 +66,188 @@ class TCPClient
       options.each_pair { |attribute, value| set(attribute, value) }
     end
 
-    def freeze
-      @ssl_params.freeze
-      super
-    end
-
-    def initialize_copy(_org)
-      super
-      @ssl_params = Hash[@ssl_params] if @ssl_params
-      self
-    end
-
-    def ssl?
-      @ssl_params ? true : false
-    end
-
-    def ssl=(value)
-      @ssl_params =
-        if value.respond_to?(:to_hash)
-          Hash[value.to_hash]
-        else
-          value ? {} : nil
-        end
-    end
+    #
+    # Enables/disables use of Socket-level buffers.
+    #
+    # @return [true] if the connection is allowed to use internal buffers (default)
+    # @return [false] if buffering is not allowed
+    #
+    attr_reader :buffered
 
     def buffered=(value)
       @buffered = value ? true : false
     end
 
+    #
+    # 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
+    #
+    attr_reader :keep_alive
+
     def keep_alive=(value)
       @keep_alive = value ? true : false
     end
 
+    #
+    # 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
+    #
+    attr_reader :reverse_lookup
+
     def reverse_lookup=(value)
       @reverse_lookup = value ? true : false
     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)
+    #
+    attr_reader :normalize_network_errors
+
     def normalize_network_errors=(value)
       @normalize_network_errors = value ? true : false
     end
 
-    def timeout=(seconds)
-      @connect_timeout = @write_timeout = @read_timeout = seconds(seconds)
+    #
+    # @attribute [w] timeout
+    # Shorthand to set timeout value for connect, read and write at once or to disable any timeout monitoring
+    #
+    # @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
+    #
+    def timeout=(value)
+      @connect_timeout = @write_timeout = @read_timeout = seconds(value)
+    end
+
+    #
+    # @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
     end
 
-    def connect_timeout=(seconds)
-      @connect_timeout = seconds(seconds)
+    #
+    # Configures 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)
+    #
+    attr_reader :connect_timeout
+
+    def connect_timeout=(value)
+      @connect_timeout = seconds(value)
     end
 
-    def read_timeout=(seconds)
-      @read_timeout = seconds(seconds)
+    #
+    # @return [Class] exception class raised if a {TCPClient#connect} timed out
+    # @raise [NotAnExceptionError] if given argument is not an Exception class
+    #
+    attr_reader :connect_timeout_error
+
+    def connect_timeout_error=(value)
+      raise(NotAnExceptionError, value) unless exception_class?(value)
+      @connect_timeout_error = value
     end
 
-    def write_timeout=(seconds)
-      @write_timeout = seconds(seconds)
+    #
+    # Configures maximum time in seconds to finish a {TCPClient#read}.
+    #
+    # @return [Numeric] maximum time in seconds to finish a {TCPClient#read} request
+    # @return [nil] if the read time should not be checked (default)
+    #
+    attr_reader :read_timeout
+
+    def read_timeout=(value)
+      @read_timeout = seconds(value)
     end
 
-    def timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @connect_timeout_error =
-        @read_timeout_error = @write_timeout_error = exception
+    #
+    # @return [Class] exception class raised if a {TCPClient#read} timed out
+    # @raise [NotAnExceptionError] if given argument is not an Exception class
+    #
+    attr_reader :read_timeout_error
+
+    def read_timeout_error=(value)
+      raise(NotAnExceptionError, value) unless exception_class?(value)
+      @read_timeout_error = value
+    end
+
+    #
+    # Configures maximum time in seconds to finish a {TCPClient#write}.
+    #
+    # @return [Numeric] maximum time in seconds to finish a {TCPClient#write} request
+    # @return [nil] if the write time should not be checked (default)
+    #
+    attr_reader :write_timeout
+
+    def write_timeout=(value)
+      @write_timeout = seconds(value)
     end
 
-    def connect_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @connect_timeout_error = exception
+    #
+    # @return [Class] exception class raised if a {TCPClient#write} timed out
+    # @raise [NotAnExceptionError] if given argument is not an Exception class
+    #
+    attr_reader :write_timeout_error
+
+    def write_timeout_error=(value)
+      raise(NotAnExceptionError, value) unless exception_class?(value)
+      @write_timeout_error = value
     end
 
-    def read_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @read_timeout_error = exception
+    #
+    # @attribute ssl?
+    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
+    #
+    def ssl?
+      @ssl_params ? true : false
     end
 
-    def write_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @write_timeout_error = exception
+    #
+    # Configures the SSL parameters used to initialize a SSL context.
+    #
+    # @return [Hash<Symbol, Object>] SSL parameters for the SSL context
+    # @return [nil] if no SSL should be used (default)
+    #
+    attr_reader :ssl_params
+
+    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
     end
+    alias ssl= ssl_params=
 
-    def to_hash
+    #
+    # @return [Hash] configuration as a Hash
+    #
+    def to_h
       {
         buffered: @buffered,
         keep_alive: @keep_alive,
@@ -124,15 +262,26 @@ class TCPClient
       }
     end
 
-    def to_h(*args)
-      args.empty? ? to_hash : to_hash.slice(*args)
+    # @!visibility private
+    def freeze
+      @ssl_params.freeze
+      super
+    end
+
+    # @!visibility private
+    def initialize_copy(_org)
+      super
+      @ssl_params = Hash[@ssl_params] if @ssl_params
+      self
     end
 
+    # @!visibility private
     def ==(other)
-      to_hash == other.to_hash
+      to_h == other.to_h
     end
     alias eql? ==
 
+    # @!visibility private
     def equal?(other)
       self.class == other.class && self == other
     end

data/lib/tcp-client/default_configuration.rb

@@ -6,14 +6,36 @@ class TCPClient
   @default_configuration = Configuration.new
 
   class << self
+    #
+    # @return [Configuration] used by default if no dedicated configuration was specified
+    #
     attr_reader :default_configuration
 
+    #
+    # Configure the default configuration which is used if no dedicated
+    # configuration was specified.
+    #
+    # @example
+    #   TCPClient.configure do |cfg|
+    #     cfg.buffered = false
+    #     cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
+    #   end
+    #
+    # @param options [Hash] see {Configuration#initialize} for details
+    #
+    # @yieldparam cfg {Configuration} the new configuration
+    #
+    # @return [Configuration] the new default configuration
+    #
     def configure(options = {}, &block)
       @default_configuration = Configuration.create(options, &block)
     end
   end
 
   class Configuration
+    #
+    # @return [Configuration] used by default if no dedicated configuration was specified
+    #
     def self.default
       TCPClient.default_configuration
     end

data/lib/tcp-client/errors.rb

@@ -1,78 +1,139 @@
 # frozen_string_literal: true
 
 class TCPClient
+  #
+  # Raised when a SSL connection should be establshed but the OpenSSL gem is not available.
+  #
   class NoOpenSSLError < RuntimeError
     def initialize
       super('OpenSSL is not available')
     end
   end
 
+  #
+  # Raised when a method requires a callback block but no such block is specified.
+  #
   class NoBlockGivenError < ArgumentError
     def initialize
       super('no block given')
     end
   end
 
+  #
+  # Raised when a an invalid timeout value was specified.
+  #
   class InvalidDeadLineError < ArgumentError
     def initialize(timeout)
       super("invalid deadline - #{timeout}")
     end
   end
 
+  #
+  # Raised by {Configuration} when an undefined attribute should  be set.
+  #
   class UnknownAttributeError < ArgumentError
     def initialize(attribute)
       super("unknown attribute - #{attribute}")
     end
   end
 
+  #
+  # Raised when a given timeout exception parameter is not an exception class.
+  #
   class NotAnExceptionError < TypeError
     def initialize(object)
       super("exception class required - #{object.inspect}")
     end
   end
 
-  NetworkError = Class.new(StandardError)
+  #
+  # Base exception class for all network related errors.
+  #
+  # 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.
+  #
+  class NetworkError < StandardError
+  end
 
+  #
+  # Raised when a {TCPClient} instance should read/write from/to the network but is not connected.
+  #
   class NotConnectedError < NetworkError
     def initialize
       super('client not connected')
     end
   end
 
+  #
+  # Base exception class for a detected timeout.
+  #
+  # 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.
+    # @overload initialize
+    # @overload initialize(message)
+    #
+    # @param message [String, #to_s] the error message
+    #
     def initialize(message = nil)
       super(message || "unable to #{action} in time")
     end
 
+    #
+    # @return [Symbol] the action which timed out
+    #
     def action
       :process
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.connect} timed out.
+  #
   class ConnectTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:connect+
+    #
     def action
       :connect
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.read} timed out.
+  #
   class ReadTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:read+
+    #
     def action
       :read
     end
   end
 
+  #
+  # Raised by default whenever a {TCPClient.write} timed out.
+  #
   class WriteTimeoutError < TimeoutError
+    #
+    # @return [Symbol] the action which timed out: +:write+
+    #
     def action
       :write
     end
   end
 
-  NoOpenSSL = NoOpenSSLError
-  NoBlockGiven = NoBlockGivenError
-  InvalidDeadLine = InvalidDeadLineError
-  UnknownAttribute = UnknownAttributeError
-  NotAnException = NotAnExceptionError
-  NotConnected = NotConnectedError
+  NoOpenSSL = NoOpenSSLError # @!visibility private
+  NoBlockGiven = NoBlockGivenError # @!visibility private
+  InvalidDeadLine = InvalidDeadLineError # @!visibility private
+  UnknownAttribute = UnknownAttributeError # @!visibility private
+  NotAnException = NotAnExceptionError # @!visibility private
+  NotConnected = NotConnectedError # @!visibility private
   deprecate_constant(
     :NoOpenSSL,
     :NoBlockGiven,

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-module IOWithDeadlineMixin
+# @!visibility private
+module IOWithDeadlineMixin # :nodoc:
   def self.included(mod)
     methods = mod.instance_methods
     if methods.index(:wait_writable) && methods.index(:wait_readable)

data/lib/tcp-client/version.rb

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

data/lib/tcp-client.rb

@@ -9,7 +9,43 @@ require_relative 'tcp-client/configuration'
 require_relative 'tcp-client/default_configuration'
 require_relative 'tcp-client/version'
 
+#
+# Client class to communicate with a server via TCP w/o SSL.
+#
+# All connect/read/write actions can be monitored to ensure that all actions
+# terminate before given time limits - or raise an exception.
+#
+# @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"
+#
+#
 class TCPClient
+  #
+  # Creates a new instance which is connected to the server on the given
+  # address and uses the given or the {.default_configuration}.
+  #
+  # 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
+  # closed.
+  #
+  # 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
+  #
+  # @see #connect
+  #
   def self.open(address, configuration = nil)
     client = new
     client.connect(Address.new(address), configuration)
@@ -18,6 +54,28 @@ class TCPClient
     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.
+  #
+  # 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.
+  #
+  # @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
+  #
+  # @yieldparam client [TCPClient] the connected client
+  # @yieldreturn [Object] any result
+  #
+  # @return [Object] the block result
+  #
+  # @see #with_deadline
+  #
   def self.with_deadline(timeout, address, configuration = nil)
     client = nil
     raise(NoBlockGivenError) unless block_given?
@@ -30,12 +88,49 @@ class TCPClient
     client&.close
   end
 
-  attr_reader :address, :configuration
+  #
+  # @return [Address] the address used for this client
+  #
+  attr_reader :address
 
+  #
+  # @return [Configuration] the configuration used by this client.
+  #
+  attr_reader :configuration
+
+  #
+  # @attribute [r] closed?
+  # @return [Boolean] true when the connection is closed, false when connected
+  #
+  def closed?
+    @socket.nil? || @socket.closed?
+  end
+
+  #
+  # @return [String] the currently used address as text.
+  #
+  # @see Address#to_s
+  #
   def to_s
     @address&.to_s || ''
   end
 
+  #
+  # 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.
+  #
+  # @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+.
+  #
+  # @return [self]
+  #
+  # @raise {NoOpenSSLError} if SSL should be used but OpenSSL is not avail
+  #
   def connect(address, configuration = nil, timeout: nil, exception: nil)
     close if @socket
     raise(NoOpenSSLError) if configuration.ssl? && !defined?(SSLSocket)
@@ -45,6 +140,11 @@ class TCPClient
     self
   end
 
+  #
+  # Close the current connection.
+  #
+  # @return [self]
+  #
   def close
     @socket&.close
     self
@@ -54,10 +154,27 @@ class TCPClient
     @socket = @deadline = nil
   end
 
-  def closed?
-    @socket.nil? || @socket.closed?
-  end
-
+  #
+  # Executes a block with a given overall timeout.
+  #
+  # 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.
+  #
+  # @example - ensure to send a welcome message and receive a 64 byte answer from server
+  #   answer = client.with_deadline(2.5) do
+  #     client.write('Helo')
+  #     client.read(64)
+  #   end
+  #
+  # @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
+  #
+  # @raise [NoBlockGivenError] if the block is missing
+  #
   def with_deadline(timeout)
     previous_deadline = @deadline
     raise(NoBlockGivenError) unless block_given?
@@ -68,6 +185,17 @@ class TCPClient
     @deadline = previous_deadline
   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
+  #
   def read(nbytes = nil, timeout: nil, exception: nil)
     raise(NotConnectedError) if closed?
     deadline = create_deadline(timeout, configuration.read_timeout)
@@ -78,18 +206,34 @@ class TCPClient
     end
   end
 
-  def write(*msg, timeout: nil, exception: nil)
+  #
+  # 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+.
+  #
+  # @return [Integer] bytes written
+  #
+  # @raise [NotConnectedError] if {#connect} was not called before
+  #
+  def write(*messages, timeout: nil, exception: nil)
     raise(NotConnectedError) if closed?
     deadline = create_deadline(timeout, configuration.write_timeout)
-    return stem_errors { @socket.write(*msg) } unless deadline.valid?
+    return stem_errors { @socket.write(*messages) } unless deadline.valid?
     exception ||= configuration.write_timeout_error
     stem_errors(exception) do
-      msg.sum do |chunk|
+      messages.sum do |chunk|
         @socket.write_with_deadline(chunk.b, deadline, exception)
       end
     end
   end
 
+  #
+  # Flush all internal buffers (write all through).
+  #
+  # @return [self]
+  #
   def flush
     stem_errors { @socket&.flush }
     self

data/rakefile.rb

@@ -3,11 +3,11 @@
 require 'rake/clean'
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 $stdout.sync = $stderr.sync = true
 
-CLOBBER << 'prj'
-
+CLOBBER << 'prj' << 'doc'
 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

@@ -91,25 +91,12 @@ RSpec.describe TCPClient::Address do
     end
   end
 
-  describe '#to_hash' do
-    subject(:address) { TCPClient::Address.new('localhost:42') }
-
-    it 'returns itself as an Hash' do
-      expect(address.to_hash).to eq(host: 'localhost', port: 42)
-    end
-  end
-
   describe '#to_h' do
     subject(:address) { TCPClient::Address.new('localhost:42') }
 
     it 'returns itself as an Hash' do
       expect(address.to_h).to eq(host: 'localhost', port: 42)
     end
-
-    it 'allows to specify the keys the result should contain' do
-      expect(address.to_h(:port)).to eq(port: 42)
-      expect(address.to_h(:host)).to eq(host: 'localhost')
-    end
   end
 
   describe 'comparison' do

data/spec/tcp-client/configuration_spec.rb

@@ -157,39 +157,6 @@ RSpec.describe TCPClient::Configuration do
     end
   end
 
-  describe '#to_hash' do
-    subject(:configuration) do
-      TCPClient::Configuration.new(
-        buffered: false,
-        connect_timeout: 1,
-        read_timeout: 2,
-        write_timeout: 3,
-        ssl: {
-          min_version: :TLS1_2,
-          max_version: :TLS1_3
-        }
-      )
-    end
-
-    it 'returns itself as an Hash' do
-      expect(configuration.to_hash).to eq(
-        buffered: false,
-        keep_alive: true,
-        reverse_lookup: true,
-        connect_timeout: 1,
-        connect_timeout_error: TCPClient::ConnectTimeoutError,
-        read_timeout: 2,
-        read_timeout_error: TCPClient::ReadTimeoutError,
-        write_timeout: 3,
-        write_timeout_error: TCPClient::WriteTimeoutError,
-        ssl_params: {
-          min_version: :TLS1_2,
-          max_version: :TLS1_3
-        }
-      )
-    end
-  end
-
   describe '#to_h' do
     subject(:configuration) do
       TCPClient::Configuration.new(
@@ -221,12 +188,6 @@ RSpec.describe TCPClient::Configuration do
         }
       )
     end
-
-    it 'allows to specify the keys the result should contain' do
-      expect(
-        configuration.to_h(:keep_alive, :read_timeout, :write_timeout)
-      ).to eq(keep_alive: true, read_timeout: 2, write_timeout: 3)
-    end
   end
 
   describe '#dup' do

data/tcp-client.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'yard'
 
   all_files = Dir.chdir(__dir__) { `git ls-files -z`.split(0.chr) }
   spec.test_files = all_files.grep(%r{^spec/})

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-12 00:00:00.000000000 Z
+date: 2021-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   This Gem implements a TCP client with (optional) SSL support.
   It is an easy to use, versatile configurable client that can correctly