tcp-client 0.6.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30592a849daf948c39b138e5f2d634761d59328f7a6eab11d45a9b069b8a747d
-  data.tar.gz: 39d0b9afe676700627a9b671c974ab5465cdb72e5ed6ec5c009add638a2b02b3
+  metadata.gz: fe13751730310529097b79992b58a5ed212ecc4119c576c04bcf7b0c4a0373c7
+  data.tar.gz: 558f73ee8e06309c8d6ca52cdc4309ceac853a9587b6891959b67f5d49c89413
 SHA512:
-  metadata.gz: d6a44381c618b1a89128499f7256bd9559dd4ea1efc5f34b82b681cfcca29f1c51b7ab47b13b513977e3276e298ec5ad02f6619f5ed36320f724e9cd192f925e
-  data.tar.gz: dfbcb8fb0e4b77770023023afbaee354e71ba4e41fe89daff9e197ce7d7a8a785e7891dbb4801651ae4702b56324d3431695e27acc781fafae9e7336db6c2c52
+  metadata.gz: a2a9d54d6de01896b83180e7e94afde9a1e2b8f62ca24c9e91d63a7c809a06286357fdecb5a3ad6fce1dceaaa50067a6f64263c83f4069d07b3ad837db138b9d
+  data.tar.gz: ac6168903ebb5c953e850fb97d80281c63b70b208335d34611f57829199e623fac3fbea85959d09d8c9ddec1edbe23ffef23cd9e5e94e788b74b0ded665dd5c2

data/.gitignore

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

data/README.md

@@ -2,33 +2,43 @@
 
 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)
+
 ## 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
 require 'tcp-client'
 
-TCPClient.configure do |cfg|
-  cfg.connect_timeout = 1 # limit connect time the server to 1 second
-  cfg.ssl_params = { ssl_version: :TLSv1_2 } # use TLS 1.2
-end
-
-TCPClient.open('www.google.com:443') do |client|
-  # next sequence should not last longer than 0.5 seconds
-  client.with_deadline(0.5) do
-    # simple HTTP get request
-    pp client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
-
-    # read "HTTP/1.1 " + 3 byte HTTP status code
-    pp client.read(12)
-  end
+# create a configuration:
+# - don't use internal buffering
+# - use TLS 1.2 or TLS 1.3
+cfg = TCPClient::Configuration.create(
+  buffered: false,
+  ssl_params: {min_version: :TLS1_2, max_version: :TLS1_3}
+)
+
+# request to Google.com:
+# - 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
 ```
 
-### Installation
+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:
 
@@ -41,13 +51,13 @@ gem 'tcp-client'
 and install it by running Bundler:
 
 ```bash
-$ bundle
+bundle
 ```
 
 To install the gem globally use:
 
 ```bash
-$ gem install tcp-client
+gem install tcp-client
 ```
 
 After that you need only a single line of code in your project to have all tools on board:

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,20 +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
 
+    #
+    # @return [Hash] containing the host and port
+    #
     def to_h
       { host: @hostname, port: @addrinfo.ip_port }
     end
 
+    # @!visibility private
     def ==(other)
       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,126 +3,285 @@
 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,
-                :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
       @connect_timeout_error = ConnectTimeoutError
       @read_timeout_error = ReadTimeoutError
       @write_timeout_error = WriteTimeoutError
+      @normalize_network_errors = false
       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 Hash === value
-          Hash[value]
-        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
 
-    def timeout=(seconds)
-      @connect_timeout = @write_timeout = @read_timeout = seconds(seconds)
+    #
+    # 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 connect_timeout=(seconds)
-      @connect_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
 
-    def read_timeout=(seconds)
-      @read_timeout = seconds(seconds)
+    #
+    # @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 write_timeout=(seconds)
-      @write_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 timeout_error=(exception)
-      raise(NotAnException, exception) unless exception_class?(exception)
-      @connect_timeout_error =
-        @read_timeout_error = @write_timeout_error = exception
+    #
+    # @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
+
+    #
+    # 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
+
+    #
+    # @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
 
-    def connect_timeout_error=(exception)
-      raise(NotAnException, exception) unless exception_class?(exception)
-      @connect_timeout_error = exception
+    #
+    # 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 read_timeout_error=(exception)
-      raise(NotAnException, exception) unless exception_class?(exception)
-      @read_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 write_timeout_error=(exception)
-      raise(NotAnException, exception) unless exception_class?(exception)
-      @write_timeout_error = exception
+    #
+    # @attribute ssl?
+    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
+    #
+    def ssl?
+      @ssl_params ? true : false
+    end
+
+    #
+    # 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=
 
+    #
+    # @return [Hash] configuration as a Hash
+    #
     def to_h
       {
         buffered: @buffered,
         keep_alive: @keep_alive,
         reverse_lookup: @reverse_lookup,
         connect_timeout: @connect_timeout,
-        read_timeout: @read_timeout,
-        write_timeout: @write_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
       }
     end
 
+    # @!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_h == other.to_h
     end
     alias eql? ==
 
+    # @!visibility private
     def equal?(other)
       self.class == other.class && self == other
     end
@@ -136,7 +295,7 @@ class TCPClient
     def set(attribute, value)
       public_send("#{attribute}=", value)
     rescue NoMethodError
-      raise(UnknownAttribute, attribute)
+      raise(UnknownAttributeError, attribute)
     end
 
     def seconds(value)

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