tcp-client 0.5.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f36e18e6865766292ff44adf5cd46244e8944049f524553ba4168725454a2d0b
-  data.tar.gz: abd4ec63f48c1be4e73922aaed7702bdacebe398e6cda13887fcd2efaa62818c
+  metadata.gz: 20df105b07989653ac9e9c877672318e1da4eb6a5171b088b137422ff03d22db
+  data.tar.gz: 393c2bf3f983f1da7dc8e3517b0cd7b170c2cdede3c546b603def84512e93806
 SHA512:
-  metadata.gz: 11b5302d3da2d0d46f35fb2370177916b1044b659b1f62bdbf0a30c39581844dd425487a6c94300b4a7afcf25eafef5828a6ef04cb0ff9bcae4fff01a9a312bb
-  data.tar.gz: 54b3505c1eb90565e0a80dab5c92a394883b74cf3bb975ed83df4c1affbad15e9acbfcee7ec3d0a5bb79c1486fa46fbfbd958fc9e43106b9a97dc22411c84335
+  metadata.gz: c94f0a7c51cd5b33edf0de9fb02d454e539f95b79891ad81c81adb4832829059fc34b8c3d4e141594dd0b95752807f1c32dbc9c5192914a5ec02345bb056075c
+  data.tar.gz: 1ab3ef36b1534cf697c911c5d4ce01137dc9860598daa34765521cbec48fe6698294402cf0a0b768f2c460212cb3ce9378adb12ba7e65c76f1531e7bd66a1688

data/.gitignore

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

data/README.md

@@ -11,24 +11,26 @@ 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
+## Installation
 
 Use [Bundler](http://gembundler.com/) to use TCPClient in your own project:
 
@@ -41,13 +43,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/deadline.rb

@@ -29,4 +29,6 @@ class TCPClient
       end
     end
   end
+
+  private_constant(:Deadline)
 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