tcp-client 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe13751730310529097b79992b58a5ed212ecc4119c576c04bcf7b0c4a0373c7
-  data.tar.gz: 558f73ee8e06309c8d6ca52cdc4309ceac853a9587b6891959b67f5d49c89413
+  metadata.gz: e88146d7f1f966d6c9e7dce6a876c17dca7383ee88eb76a8e5caf36076a03720
+  data.tar.gz: 493d8cbf748789df4efd0301679082023c140f23dbc2a3d52ccfcf8d71a4a1b4
 SHA512:
-  metadata.gz: a2a9d54d6de01896b83180e7e94afde9a1e2b8f62ca24c9e91d63a7c809a06286357fdecb5a3ad6fce1dceaaa50067a6f64263c83f4069d07b3ad837db138b9d
-  data.tar.gz: ac6168903ebb5c953e850fb97d80281c63b70b208335d34611f57829199e623fac3fbea85959d09d8c9ddec1edbe23ffef23cd9e5e94e788b74b0ded665dd5c2
+  metadata.gz: 070ba42a0a185a67ae1ac4d1912220ab0aa297a6cdc4147d3afaf8593129f3b25da2ecad7a8569651c6d54dd1ba11c7705ebf8bcc1def2d525388025b45d12b3
+  data.tar.gz: 4c34127d89744a537d5b64c578ac4c1e2121c27e9412208f7c0abcf74999bb1e85c1c246bebfea83401c8caaf4c472daee7ff5e599989632076784881131b3ea

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,16 +2,14 @@
 
 A TCP client implementation with working timeout support.
 
-[![Gem Version](https://badge.fury.io/rb/tcp-client.svg)](https://badge.fury.io/rb/tcp-client)
+- 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.
 
-## Help
-
-The latest help can be found at [rubydoc.info](https://rubydoc.info/github/mblumtritt/tcp-client/main/index)
-
 ## Sample
 
 ```ruby
@@ -29,11 +27,14 @@ cfg = TCPClient::Configuration.create(
 # - limit all network interactions to 1.5 seconds
 # - use the Configuration cfg
 # - send a simple HTTP get request
-# - read 12 byte: "HTTP/1.1 " + 3 byte HTTP status code
-TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
-  client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") # >= 40
-  client.read(12) # => "HTTP/1.1 200"
-end
+# - read the returned message and headers
+response =
+  TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
+    client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") #=> 40
+    client.readline("\r\n\r\n") #=> see response
+  end
+
+puts(response)
 ```
 
 For more samples see [the samples dir](https://github.com/mblumtritt/tcp-client/tree/main/sample)

data/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,23 +21,30 @@ 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.
+    #   Addresses the port on the local machine.
+    #
+    #   @example create an Address for localhost on port 80
+    #     Address.new(80)
     #
     #   @param port [Integer] the addressed port
     #
@@ -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,55 @@ 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 [{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.
+    # Initializes the instance with given options.
     #
-    # @param options [Hash]
+    # @param options [{Symbol => Object}]
     # @option options [Boolean] :buffered, see {#buffered}
     # @option options [Boolean] :keep_alive, see {#keep_alive}
     # @option options [Boolean] :reverse_lookup, see {#reverse_lookup}
-    # @option options [Boolean] :normalize_network_errors, see {#normalize_network_errors}
+    # @option options [{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 +66,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] whether the connection is allowed to use internal
+    #   buffers (default) or not
     #
     attr_reader :buffered
 
@@ -81,8 +83,8 @@ class TCPClient
     #
     # Enables/disables use of Socket-level keep alive handling.
     #
-    # @return [true] if the connection is allowed to use keep alive signals (default)
-    # @return [false] if the connection should not check keep alive
+    # @return [Boolean] whether the connection is allowed to use keep alive
+    #   signals (default) or not
     #
     attr_reader :keep_alive
 
@@ -93,8 +95,8 @@ class TCPClient
     #
     # Enables/disables address lookup.
     #
-    # @return [true] if the connection is allowed to lookup the address (default)
-    # @return [false] if the address lookup is not required
+    # @return [Boolean] whether the connection is allowed to lookup the address
+    #   (default) or not
     #
     attr_reader :reverse_lookup
 
@@ -103,55 +105,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] whether 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
-    #
-    # @return [Numeric] maximum time in seconds for any action
-    # @return [nil] if all timeout monitoring should be disabled (default)
+    # Parameters used to initialize a SSL context. SSL/TLS will only be used if
+    # this attribute is not `nil`.
     #
-    # @see #connect_timeout
-    # @see #read_timeout
-    # @see #write_timeout
+    # @return [{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
+
+    #
+    # The maximum time in seconds to establish a connection.
     #
-    # Configures maximum time in seconds to establish a connection.
+    # @return [Numeric] maximum time in seconds
+    # @return [nil] if the connect time should not be monitored (default)
     #
-    # @return [Numeric] maximum time in seconds to establish a connection
-    # @return [nil] if the connect time should not be checked (default)
+    # @see TCPClient#connect
     #
     attr_reader :connect_timeout
 
@@ -160,7 +152,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 +166,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
+    # @return [nil] if the read time should not be monitored (default)
     #
-    # @return [Numeric] maximum time in seconds to finish a {TCPClient#read} request
-    # @return [nil] if the read time should not be checked (default)
+    # @see TCPClient#read
     #
     attr_reader :read_timeout
 
@@ -183,7 +180,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 +194,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 +208,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 +222,76 @@ 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 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
 
     #
-    # Configures the SSL parameters used to initialize a SSL context.
+    # @attribute [w] timeout_error
+    # Shorthand to set the exception class which 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] whether 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
+    # @return [{Symbol => Object}] Hash containing all attributes
+    #
+    # @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