tcp-client 0.7.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 582575d6b5a66a264900141fd5010a1a80a363e15d0ca369f262889d99d932d0
-  data.tar.gz: a0c2335a50addbf5f424d869cd2931256a1334a0a075530ef3873d9065246834
+  metadata.gz: d29104bd490679a8fcb517f949e021cd1d2da263f3a60d622790bc2349faffab
+  data.tar.gz: c7ebaf4f9f83eaf68b51bc47bb91fc5be5d446ef3e80b009bc93bca9d3508ef5
 SHA512:
-  metadata.gz: b160bd656c4f6091a669cf65349e54aeaa2e7c057e0a5a3c896edf5e8ab91166a3a5cdafedfe84e4b04d5a79e0602fb2433c6ff9144e6881746f3607b8d8290b
-  data.tar.gz: 6726ebdfbc777258e62b3d915fa7e4a57f7ae514d6259ce5f0051ee649294142acf09faac490901e32083072d7a68dd4ce71fa697e0bf05c0d9556c0d57bb6a5
+  metadata.gz: 5e8c282afbefecb35973f7c563cb07782f8dd0e5df760c89d79aa42424784818c5c0e056c40139554642da8b24823aa9fbb7149e0ed7234f40cc51ea5a7a8165
+  data.tar.gz: 2281b62117529f4bbeff55e297b67f8142235772b112d30f9530113e23ab4012242d5eb2fed4e8293a40836455259d37c91403f50714f292ee6e531250e4cc76

data/.gitignore

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

data/.yardopts

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

data/README.md

@@ -2,6 +2,11 @@
 
 A TCP client implementation with working timeout support.
 
+- Gem: [rubygems.org](https://rubygems.org/gems/tcp-client)
+- Source: [github.com](https://github.com/mblumtritt/tcp-client)
+- Help: [rubydoc.info](https://rubydoc.info/github/mblumtritt/tcp-client/main/index)
+
+
 ## Description
 
 This Gem implements a TCP client with (optional) SSL support. It is an easy to use, versatile configurable client that can correctly handle time limits. Unlike other implementations, this client respects predefined/configurable time limits for each method (`connect`, `read`, `write`). Deadlines for a sequence of read/write actions can also be monitored.
@@ -11,24 +16,28 @@ This Gem implements a TCP client with (optional) SSL support. It is an easy to u
 ```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 +50,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/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

@@ -3,9 +3,51 @@
 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"
+    #
+    #   @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
+    #
+    #
+    # @overload initialize(addrinfo)
+    #
+    #   @example create an Address with an Addrinfo
+    #     Address.new(Addrinfo.tcp('www.google.com', 'http'))
+    #
+    #   @param addrinfo [Addrinfo] containing the addressed host and port
+    #
+    # @overload initialize(port)
+    #   Adresses the port on the local machine.
+    #
+    #   @example create an Address for localhost on port 80
+    #     Address.new(80)
+    #
+    #   @param port [Integer] the addressed port
+    #
     def initialize(addr)
       case addr
       when self.class
@@ -20,20 +62,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,326 @@
 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 create a new configuration within a code block.
+    #
+    #   @example
+    #     config = TCPClient::Configuration.create do |cfg|
+    #       cfg.buffered = false
+    #       cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
+    #     end
+    #
+    #   @yieldparam configuration {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
+      configuration = new(options)
+      yield(configuration) if block_given?
+      configuration
+    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 [Hash<Symbol, Object>] :ssl_params, see {#ssl_params}
+    # @option options [Numeric] :connect_timeout, see {#connect_timeout}
+    # @option options [Exception] :connect_timeout_error, see
+    #   {#connect_timeout_error}
+    # @option options [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 [Boolean] :normalize_network_errors, see
+    #   {#normalize_network_errors}
+    #
+    #
     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
+    # @!group Instance Attributes Socket Level
+
+    #
+    # 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
+    #
+    attr_reader :buffered
+
+    def buffered=(value)
+      @buffered = value ? true : false
     end
 
-    def initialize_copy(_org)
-      super
-      @ssl_params = Hash[@ssl_params] if @ssl_params
-      self
+    #
+    # 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
 
+    #
+    # @!parse attr_reader :ssl?
+    # @return [Boolean] wheter SSL is configured, see {#ssl_params}
+    #
     def ssl?
       @ssl_params ? true : false
     end
 
-    def ssl=(value)
+    #
+    # 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 Hash === value
-          Hash[value]
+        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 buffered=(value)
-      @buffered = value ? true : false
+    # @!endgroup
+
+    # @!group Instance Attributes Timeout Monitoring
+
+    #
+    # The 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)
+    #
+    # @see TCPClient#connect
+    #
+    attr_reader :connect_timeout
+
+    def connect_timeout=(value)
+      @connect_timeout = seconds(value)
     end
 
-    def keep_alive=(value)
-      @keep_alive = value ? true : false
+    #
+    # The exception class which will be raised if {TCPClient#connect} can not
+    # be finished in time.
+    #
+    # @return [Class] exception class raised
+    # @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 reverse_lookup=(value)
-      @reverse_lookup = value ? true : false
+    #
+    # 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)
+    #
+    # @see TCPClient#read
+    #
+    attr_reader :read_timeout
+
+    def read_timeout=(value)
+      @read_timeout = seconds(value)
     end
 
-    def timeout=(seconds)
-      @connect_timeout = @write_timeout = @read_timeout = seconds(seconds)
+    #
+    # The exception class which will be raised if {TCPClient#read} can not be
+    # finished in time.
+    #
+    # @return [Class] exception class raised
+    # @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=(seconds)
-      @connect_timeout = seconds(seconds)
+    #
+    # The maximum time in seconds to write to a connection.
+    #
+    # @return [Numeric] maximum time in seconds
+    # @return [nil] if the write time should not be monitored (default)
+    #
+    # @see TCPClient#write
+    #
+    attr_reader :write_timeout
+
+    def write_timeout=(value)
+      @write_timeout = seconds(value)
     end
 
-    def read_timeout=(seconds)
-      @read_timeout = seconds(seconds)
+    #
+    # The exception class which will be raised if {TCPClient#write} can not be
+    # finished in time.
+    #
+    # @return [Class] exception class raised
+    # @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=(seconds)
-      @write_timeout = seconds(seconds)
+    #
+    # @attribute [w] timeout
+    # Shorthand to set maximum time in seconds for all timeut monitoring.
+    #
+    # @return [Numeric] maximum time in seconds for any actwion
+    # @return [nil] if all timeout monitoring should be disabled (default)
+    #
+    # @see #connect_timeout
+    # @see #read_timeout
+    # @see #write_timeout
+    #
+    def timeout=(value)
+      @connect_timeout = @write_timeout = @read_timeout = seconds(value)
     end
 
-    def timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
+    #
+    # @attribute [w] timeout_error
+    # Shorthand to set the exception class wich will by raised by any timeut.
+    #
+    # @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 = exception
+        @read_timeout_error = @write_timeout_error = value
     end
 
-    def connect_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @connect_timeout_error = exception
-    end
+    # @!endgroup
 
-    def read_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @read_timeout_error = exception
-    end
+    #
+    # 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 [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 write_timeout_error=(exception)
-      raise(NotAnExceptionError, exception) unless exception_class?(exception)
-      @write_timeout_error = exception
+    def normalize_network_errors=(value)
+      @normalize_network_errors = value ? true : false
     end
 
+    #
+    # Convert `self` to a Hash containing all attributes.
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    # @see #initialize
+    #
     def to_h
       {
         buffered: @buffered,
         keep_alive: @keep_alive,
         reverse_lookup: @reverse_lookup,
+        ssl_params: @ssl_params,
         connect_timeout: @connect_timeout,
-        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
+        normalize_network_errors: @normalize_network_errors
       }
     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

data/lib/tcp-client/default_configuration.rb

@@ -6,16 +6,50 @@ class TCPClient
   @default_configuration = Configuration.new
 
   class << self
+    #
+    # 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 to {.open} or {#connect}.
+    #
+    # @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
-    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