tcp-client 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e88146d7f1f966d6c9e7dce6a876c17dca7383ee88eb76a8e5caf36076a03720
-  data.tar.gz: 493d8cbf748789df4efd0301679082023c140f23dbc2a3d52ccfcf8d71a4a1b4
+  metadata.gz: 3c5d814647f45ebfc5a5d43b6b0ae208092c36493bdc839c7e4e722c3ff4b1f0
+  data.tar.gz: 6187b371bb275f0cc88c63091dce51e91f45b79c5257580f881616433c581345
 SHA512:
-  metadata.gz: 070ba42a0a185a67ae1ac4d1912220ab0aa297a6cdc4147d3afaf8593129f3b25da2ecad7a8569651c6d54dd1ba11c7705ebf8bcc1def2d525388025b45d12b3
-  data.tar.gz: 4c34127d89744a537d5b64c578ac4c1e2121c27e9412208f7c0abcf74999bb1e85c1c246bebfea83401c8caaf4c472daee7ff5e599989632076784881131b3ea
+  metadata.gz: c48c0b4b0b9f14545895ae489f27d2a75a2c400598a342b553f8e7bbace7f2b4d9d9874f70e85ff40fe3ff4c59e2ea1973e8f324aceacb2705c7982fb1ebb772
+  data.tar.gz: 9c8259dcb4b9b351224627f08a84041d2d8bdf543233d0cefc2b14ed265d67a4b7a2b128bfe75fa4fd8a6b44bab527bb81a815a1edeefafcd85a4733d0064087

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
@@ -41,7 +41,7 @@ class TCPClient
       #
       # @!parse attr_reader :default
       # @return [Configuration] used by default if no dedicated configuration
-      # was specified
+      #   was specified
       #
       # @see TCPClient.open
       # @see TCPClient.with_deadline

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

@@ -1,87 +1,80 @@
 # frozen_string_literal: true
 
-# @!visibility private
-module IOWithDeadlineMixin # :nodoc:
-  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)
+class TCPClient
+  module IOWithDeadlineMixin
+    def self.included(mod)
+      methods = mod.instance_methods
+      return if methods.index(:wait_writable) && methods.index(:wait_readable)
+      mod.include(methods.index(:to_io) ? WaitWithIO : WaitWithSelect)
     end
-  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
-      close
-      break
+    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?
+      @read_buffer ||= ''.b
+      while @read_buffer.bytesize < nbytes
+        read = fetch_next(deadline, exception) and next @read_buffer << read
+        close
+        break
+      end
+      fetch_slice(nbytes)
     end
-    fetch_buffer_slice(nbytes)
-  end
 
-  def readto_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
-      close
-      break
+    def read_to_with_deadline(sep, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      @read_buffer ||= ''.b
+      while @read_buffer.index(sep).nil?
+        read = fetch_next(deadline, exception) and next @read_buffer << read
+        close
+        break
+      end
+      index = @read_buffer.index(sep)
+      return fetch_slice(index + sep.bytesize) if index
+      result = @read_buffer
+      @read_buffer = nil
+      result
     end
-    index = @buf.index(sep) and return fetch_buffer_slice(index + sep.bytesize)
-    result = @buf
-    @buf = nil
-    result
-  end
 
-  def write_with_deadline(data, deadline, exception)
-    raise(exception) unless deadline.remaining_time
-    return 0 if (size = data.bytesize).zero?
-    result = 0
-    loop do
-      written =
-        with_deadline(deadline, exception) do
-          write_nonblock(data, exception: false)
-        end
-      (result += written) >= size and return result
-      data = data.byteslice(written, data.bytesize - written)
+    def write_with_deadline(data, deadline, exception)
+      raise(exception) unless deadline.remaining_time
+      return 0 if (size = data.bytesize).zero?
+      result = 0
+      loop do
+        written =
+          with_deadline(deadline, exception) do
+            write_nonblock(data, exception: false)
+          end
+        (result += written) >= size and return result
+        data = data.byteslice(written, data.bytesize - written)
+      end
     end
-  end
 
-  private
+    private
 
-  def fetch_avail(deadline, exception)
-    if @buf.nil?
-      result = fetch_next(deadline, exception) and return result
-      close
-      return ''.b
+    def fetch_avail(deadline, exception)
+      if (result = @read_buffer || fetch_next(deadline, exception)).nil?
+        close
+        return ''.b
+      end
+      @read_buffer = nil
+      result
     end
-    result = @buf
-    @buf = 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)
-    result
-  end
+    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
 
-  def fetch_next(deadline, exception)
-    with_deadline(deadline, exception) do
-      read_nonblock(65_536, exception: false)
+    def fetch_next(deadline, exception)
+      with_deadline(deadline, exception) do
+        read_nonblock(65_536, exception: false)
+      end
     end
-  end
 
-  module ViaWaitMethod
-    private def with_deadline(deadline, exception)
+    def with_deadline(deadline, exception)
       loop do
         case ret = yield
         when :wait_writable
@@ -97,45 +90,29 @@ module IOWithDeadlineMixin # :nodoc:
     rescue Errno::ETIMEDOUT
       raise(exception)
     end
-  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
+    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
-    rescue Errno::ETIMEDOUT
-      raise(exception)
     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)
-          raise(exception) if ::IO.select(nil, [self], nil, remaining_time).nil?
-        when :wait_readable
-          remaining_time = deadline.remaining_time or raise(exception)
-          raise(exception) if ::IO.select([self], nil, nil, remaining_time).nil?
-        else
-          return ret
-        end
+    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
-    rescue Errno::ETIMEDOUT
-      raise(exception)
     end
+
+    private_constant(:WaitWithIO, :WaitWithSelect)
   end
 
-  private_constant(:ViaWaitMethod, :ViaIOWaitMethod, :ViaSelect)
+  private_constant(:IOWithDeadlineMixin)
 end

data/lib/tcp-client/ssl_socket.rb

@@ -30,7 +30,7 @@ class TCPClient
       ::OpenSSL::SSL::SSLContext.new.tap do |ctx|
         ctx.set_params(ssl_params)
         ctx.session_cache_mode = CONTEXT_CACHE_MODE
-        ctx.session_new_cb = proc { |_, sess| @new_session = sess }
+        ctx.session_new_cb = proc { |_, session| @new_session = session }
       end
     end
 

data/lib/tcp-client/version.rb

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

data/lib/tcp-client.rb

@@ -13,7 +13,7 @@ require_relative 'tcp-client/version'
 # Client class to communicate with a server via TCP w/o SSL.
 #
 # All connect/read/write actions can be monitored to ensure that all actions
-# terminate before given time limits - or raise an exception.
+# terminate before given time limit - or raise an exception.
 #
 # @example request to Google.com and limit network interactions to 1.5 seconds
 #   # create a configuration to use at least TLS 1.2
@@ -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.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-09 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,8 @@ 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 +35,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:
@@ -129,14 +57,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+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/.yardopts

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

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)