tcp-client 0.10.1 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02440fe17a1480ba18bec8b6918cea6420a065d997c423a6602e165e0f316564
-  data.tar.gz: 73e315f2c80a2f0f1cf0cb57b24f2f2cd45e10caffebd83dd47510ea85de1f25
+  metadata.gz: 4665e444c265a00de59f416c23db910d3ed7a96fc62ba6bf966c4e14b6564a9e
+  data.tar.gz: 04c8e56bd884b61d5f5219233aa6bdfd7d2ce89c0f5892deebe27029e436ec4b
 SHA512:
-  metadata.gz: bb22bb974aacd8cfc9d4a1ebcc66393172ec949db8038ecbc37c1a4187bb8a1d703206625f25fb7dba5e336217d2de31475220aa4147bc20df26a5deff7bd7b7
-  data.tar.gz: 0fd048dda8d10ba76659276cd7f5c09e1fba73560d482a5cbbb35ba6db034192137552531dcd294d45a50a10a211839b318015d0546ded7df28c8f55246fe7fd
+  metadata.gz: a40b4af0dbe5c65c3a52b0250206ab31442c7efd34df1916293a60299ef87f73d0bb0e3cc0ab4bd5ad4d5a401035fb7f9939f60fc0ef1873a945663387253221
+  data.tar.gz: e4333df6c2ca755f8054bd6bee511835ae20965b1784c613f21545e4fc999f8e8b52da8d5c389528a473b779e1a9b5c87348474599daf47356e7081820da535d

data/README.md

@@ -1,6 +1,6 @@
 # TCPClient
 
-A TCP client implementation with working timeout support.
+Use your TCP connections with working timeout.
 
 - Gem: [rubygems.org](https://rubygems.org/gems/tcp-client)
 - Source: [github.com](https://github.com/mblumtritt/tcp-client)
@@ -8,7 +8,8 @@ A TCP client implementation with working timeout support.
 
 ## 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.
+This gem implements a customizable TCP client class that gives you control over time limits. You can set time limits for individual read or write calls or set a deadline for entire call sequences.
+It has a very small footprint, no dependencies and is easily useable.
 
 ## Sample
 
@@ -37,7 +38,7 @@ response =
 puts(response)
 ```
 
-For more samples see [the samples dir](https://github.com/mblumtritt/tcp-client/tree/main/sample)
+For more samples see [the examples dir](https://github.com/mblumtritt/tcp-client/tree/main/examples)
 
 ## Installation
 
@@ -61,7 +62,7 @@ To install the gem globally use:
 gem install tcp-client
 ```
 
-After that you need only a single line of code in your project to have all tools on board:
+After that you need only a single line of code in your project to have it on board:
 
 ```ruby
 require 'tcp-client'

data/lib/tcp-client/configuration.rb

@@ -30,40 +30,25 @@ class TCPClient
     #
     # @return [Configuration] the initialized configuration
     #
-    def self.create(options = {})
+    def self.create(options = nil)
       configuration = new(options)
       yield(configuration) if block_given?
       configuration
     end
 
     #
-    # Initializes the instance with given options.
+    # Initializes and optionally configures the instance with given options.
     #
-    # @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 [{Symbol => Object}] :ssl_params, see {#ssl_params}
-    # @option options [Numeric] :connect_timeout, see {#connect_timeout}
-    # @option options [Class<Exception>] :connect_timeout_error, see
-    #   {#connect_timeout_error}
-    # @option options [Numeric] :read_timeout, see {#read_timeout}
-    # @option options [Class<Exception>] :read_timeout_error, see
-    #   {#read_timeout_error}
-    # @option options [Numeric] :write_timeout, see {#write_timeout}
-    # @option options [Class<Exception>] :write_timeout_error, see
-    #   {#write_timeout_error}
-    # @option options [Boolean] :normalize_network_errors, see
-    #   {#normalize_network_errors}
+    # @see #configure
     #
-    def initialize(options = {})
+    def initialize(options = nil)
       @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) }
+      configure(options) if options
     end
 
     # @!group Instance Attributes Socket Level
@@ -257,6 +242,8 @@ class TCPClient
 
     # @!endgroup
 
+    # @!group Other Instance Attributes
+
     #
     # Enables/disables if network exceptions should be raised as {NetworkError}.
     #
@@ -274,10 +261,12 @@ class TCPClient
       @normalize_network_errors = value ? true : false
     end
 
+    # @!endgroup
+
     #
     # @return [{Symbol => Object}] Hash containing all attributes
     #
-    # @see #initialize
+    # @see #configure
     #
     def to_h
       {
@@ -295,6 +284,33 @@ class TCPClient
       }
     end
 
+    #
+    # Configures the instance with given 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 [{Symbol => Object}] :ssl_params, see {#ssl_params}
+    # @option options [Numeric] :connect_timeout, see {#connect_timeout}
+    # @option options [Class<Exception>] :connect_timeout_error, see
+    #   {#connect_timeout_error}
+    # @option options [Numeric] :read_timeout, see {#read_timeout}
+    # @option options [Class<Exception>] :read_timeout_error, see
+    #   {#read_timeout_error}
+    # @option options [Numeric] :write_timeout, see {#write_timeout}
+    # @option options [Class<Exception>] :write_timeout_error, see
+    #   {#write_timeout_error}
+    # @option options [Boolean] :normalize_network_errors, see
+    #   {#normalize_network_errors}
+    #
+    # @return [Configuration] self
+    #
+    def configure(options)
+      options.each_pair { |attribute, value| set(attribute, value) }
+      self
+    end
+
     # @!visibility private
     def freeze
       @ssl_params.freeze

data/lib/tcp-client/default_configuration.rb

@@ -25,13 +25,13 @@ class TCPClient
     #     cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
     #   end
     #
-    # @param options [Hash] see {Configuration#initialize} for details
+    # @param options [Hash] see {Configuration#configure} for details
     #
     # @yieldparam cfg {Configuration} the new configuration
     #
     # @return [Configuration] the new default configuration
     #
-    def configure(options = {}, &block)
+    def configure(options = nil, &block)
       @default_configuration = Configuration.create(options, &block)
     end
   end

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

@@ -4,40 +4,35 @@ class TCPClient
   module IOWithDeadlineMixin
     def self.included(mod)
       methods = mod.instance_methods
-      if methods.index(:wait_writable) && methods.index(:wait_readable)
-        mod.include(ViaWaitMethod)
-      elsif methods.index(:to_io)
-        mod.include(ViaIOWaitMethod)
-      else
-        mod.include(ViaSelect)
-      end
+      return if methods.index(:wait_writable) && methods.index(:wait_readable)
+      mod.include(methods.index(:to_io) ? WaitWithIO : WaitWithSelect)
     end
 
     def read_with_deadline(nbytes, deadline, exception)
       raise(exception) unless deadline.remaining_time
       return fetch_avail(deadline, exception) if nbytes.nil?
       return ''.b if nbytes.zero?
-      @buf ||= ''.b
-      while @buf.bytesize < nbytes
-        read = fetch_next(deadline, exception) and next @buf << read
+      @read_buffer ||= ''.b
+      while @read_buffer.bytesize < nbytes
+        read = fetch_next(deadline, exception) and next @read_buffer << read
         close
         break
       end
-      fetch_buffer_slice(nbytes)
+      fetch_slice(nbytes)
     end
 
-    def readto_with_deadline(sep, deadline, exception)
+    def read_to_with_deadline(sep, deadline, exception)
       raise(exception) unless deadline.remaining_time
-      @buf ||= ''.b
-      while (index = @buf.index(sep)).nil?
-        read = fetch_next(deadline, exception) and next @buf << read
+      @read_buffer ||= ''.b
+      while @read_buffer.index(sep).nil?
+        read = fetch_next(deadline, exception) and next @read_buffer << read
         close
         break
       end
-      index = @buf.index(sep)
-      return fetch_buffer_slice(index + sep.bytesize) if index
-      result = @buf
-      @buf = nil
+      index = @read_buffer.index(sep)
+      return fetch_slice(index + sep.bytesize) if index
+      result = @read_buffer
+      @read_buffer = nil
       result
     end
 
@@ -58,20 +53,18 @@ class TCPClient
     private
 
     def fetch_avail(deadline, exception)
-      if @buf.nil?
-        result = fetch_next(deadline, exception) and return result
+      if (result = @read_buffer || fetch_next(deadline, exception)).nil?
         close
         return ''.b
       end
-      result = @buf
-      @buf = nil
+      @read_buffer = nil
       result
     end
 
-    def fetch_buffer_slice(size)
-      result = @buf.byteslice(0, size)
-      rest = @buf.bytesize - result.bytesize
-      @buf = rest.zero? ? nil : @buf.byteslice(size, rest)
+    def fetch_slice(size)
+      result = @read_buffer.byteslice(0, size)
+      rest = @read_buffer.bytesize - result.bytesize
+      @read_buffer = rest.zero? ? nil : @read_buffer.byteslice(size, rest)
       result
     end
 
@@ -81,68 +74,44 @@ class TCPClient
       end
     end
 
-    module ViaWaitMethod
-      private def with_deadline(deadline, exception)
-        loop do
-          case ret = yield
-          when :wait_writable
-            remaining_time = deadline.remaining_time or raise(exception)
-            raise(exception) if wait_writable(remaining_time).nil?
-          when :wait_readable
-            remaining_time = deadline.remaining_time or raise(exception)
-            raise(exception) if wait_readable(remaining_time).nil?
-          else
-            return ret
-          end
+    def with_deadline(deadline, exception)
+      loop do
+        case ret = yield
+        when :wait_writable
+          remaining_time = deadline.remaining_time or raise(exception)
+          raise(exception) if wait_writable(remaining_time).nil?
+        when :wait_readable
+          remaining_time = deadline.remaining_time or raise(exception)
+          raise(exception) if wait_readable(remaining_time).nil?
+        else
+          return ret
         end
-      rescue Errno::ETIMEDOUT
-        raise(exception)
       end
+    rescue Errno::ETIMEDOUT
+      raise(exception)
     end
 
-    module ViaIOWaitMethod
-      private def with_deadline(deadline, exception)
-        loop do
-          case ret = yield
-          when :wait_writable
-            remaining_time = deadline.remaining_time or raise(exception)
-            raise(exception) if to_io.wait_writable(remaining_time).nil?
-          when :wait_readable
-            remaining_time = deadline.remaining_time or raise(exception)
-            raise(exception) if to_io.wait_readable(remaining_time).nil?
-          else
-            return ret
-          end
-        end
-      rescue Errno::ETIMEDOUT
-        raise(exception)
+    module WaitWithIO
+      def wait_writable(remaining_time)
+        to_io.wait_writable(remaining_time)
+      end
+
+      def wait_readable(remaining_time)
+        to_io.wait_readable(remaining_time)
       end
     end
 
-    module ViaSelect
-      private def with_deadline(deadline, exception)
-        loop do
-          case ret = yield
-          when :wait_writable
-            remaining_time = deadline.remaining_time or raise(exception)
-            if ::IO.select(nil, [self], nil, remaining_time).nil?
-              raise(exception)
-            end
-          when :wait_readable
-            remaining_time = deadline.remaining_time or raise(exception)
-            if ::IO.select([self], nil, nil, remaining_time).nil?
-              raise(exception)
-            end
-          else
-            return ret
-          end
-        end
-      rescue Errno::ETIMEDOUT
-        raise(exception)
+    module WaitWithSelect
+      def wait_writable(remaining_time)
+        ::IO.select(nil, [self], nil, remaining_time)
+      end
+
+      def wait_readable(remaining_time)
+        ::IO.select([self], nil, nil, remaining_time)
       end
     end
 
-    private_constant(:ViaWaitMethod, :ViaIOWaitMethod, :ViaSelect)
+    private_constant(:WaitWithIO, :WaitWithSelect)
   end
 
   private_constant(:IOWithDeadlineMixin)

data/lib/tcp-client/version.rb

@@ -2,5 +2,5 @@
 
 class TCPClient
   # The current version number.
-  VERSION = '0.10.1'
+  VERSION = '0.11.2'
 end

data/lib/tcp-client.rb

@@ -231,7 +231,7 @@ class TCPClient
     exception ||= configuration.read_timeout_error
     line =
       stem_errors(exception) do
-        @socket.readto_with_deadline(separator, deadline, exception)
+        @socket.read_to_with_deadline(separator, deadline, exception)
       end
     chomp ? line.chomp : line
   end
@@ -344,7 +344,8 @@ class TCPClient
       IOError,
       SocketError
     ].tap do |errors|
-      errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
-    end.freeze
+        errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
+      end
+      .freeze
   private_constant(:NETWORK_ERRORS)
 end

metadata

@@ -1,79 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: tcp-client
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.2
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-12 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  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'
-- !ruby/object:Gem::Dependency
-  name: rake
-  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'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  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'
-- !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'
+date: 2022-07-30 00:00:00.000000000 Z
+dependencies: []
 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.
+  This gem implements a customizable TCP client class that gives you control
+  over time limits. You can set time limits for individual read or write calls
+  or set a deadline for entire call sequences.
+  It has a very small footprint, no dependencies and is easily useable.
 email:
 executables: []
 extensions: []
@@ -81,11 +22,9 @@ extra_rdoc_files:
 - README.md
 - LICENSE
 files:
-- ".gitignore"
 - ".yardopts"
 - LICENSE
 - README.md
-- gems.rb
 - lib/tcp-client.rb
 - lib/tcp-client/address.rb
 - lib/tcp-client/configuration.rb
@@ -97,23 +36,13 @@ files:
 - lib/tcp-client/tcp_socket.rb
 - lib/tcp-client/version.rb
 - lib/tcp_client.rb
-- rakefile.rb
-- sample/google.rb
-- sample/google_ssl.rb
-- spec/helper.rb
-- spec/tcp-client/address_spec.rb
-- spec/tcp-client/configuration_spec.rb
-- spec/tcp-client/default_configuration_spec.rb
-- spec/tcp-client/version_spec.rb
-- spec/tcp_client_spec.rb
-- tcp-client.gemspec
 homepage: https://github.com/mblumtritt/tcp-client
 licenses:
 - BSD-3-Clause
 metadata:
   source_code_uri: https://github.com/mblumtritt/tcp-client
   bug_tracker_uri: https://github.com/mblumtritt/tcp-client/issues
-  documentation_uri: https://rubydoc.info/github/mblumtritt/tcp-client
+  documentation_uri: https://rubydoc.info/gems/tcp-client
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -132,11 +61,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: A TCP client implementation with working timeout support.
-test_files:
-- spec/helper.rb
-- spec/tcp-client/address_spec.rb
-- spec/tcp-client/configuration_spec.rb
-- spec/tcp-client/default_configuration_spec.rb
-- spec/tcp-client/version_spec.rb
-- spec/tcp_client_spec.rb
+summary: Use your TCP connections with working timeout.
+test_files: []

data/.gitignore

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

data/gems.rb

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-gemspec

data/rakefile.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require 'rake/clean'
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'yard'
-
-$stdout.sync = $stderr.sync = true
-
-CLEAN << 'prj' << 'doc'
-
-CLOBBER << '.yardoc'
-
-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/sample/google.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/tcp-client'
-
-# global configuration.
-# - 0.5 seconds to connect the server
-# - 0.25 seconds to write a single data junk
-# - 0.25 seconds to read some bytes
-TCPClient.configure do |cfg|
-  cfg.connect_timeout = 0.5
-  cfg.write_timeout = 0.25
-  cfg.read_timeout = 0.25
-end
-
-# request to Google:
-# - send a simple HTTP get request
-# - read 12 byte: "HTTP/1.1 " + 3 byte HTTP status code
-TCPClient.open('www.google.com:80') do |client|
-  p client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
-  p client.read(12)
-end

data/sample/google_ssl.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/tcp-client'
-
-# 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 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)

data/spec/helper.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require 'rspec/core'
-require_relative '../lib/tcp-client'
-
-$stdout.sync = $stderr.sync = true
-
-RSpec.configure do |config|
-  config.disable_monkey_patching!
-  config.warnings = true
-  config.order = :random
-end