tcp-client 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 582575d6b5a66a264900141fd5010a1a80a363e15d0ca369f262889d99d932d0
-  data.tar.gz: a0c2335a50addbf5f424d869cd2931256a1334a0a075530ef3873d9065246834
+  metadata.gz: 14f787ad4e8e06910bfebf67755ae7142183df4c4fb090edce84aae7d497a2b6
+  data.tar.gz: 6349bea2eac6bac053c724e0c6a162b1fe99502e94cf1c6734854d97f194f37a
 SHA512:
-  metadata.gz: b160bd656c4f6091a669cf65349e54aeaa2e7c057e0a5a3c896edf5e8ab91166a3a5cdafedfe84e4b04d5a79e0602fb2433c6ff9144e6881746f3607b8d8290b
-  data.tar.gz: 6726ebdfbc777258e62b3d915fa7e4a57f7ae514d6259ce5f0051ee649294142acf09faac490901e32083072d7a68dd4ce71fa697e0bf05c0d9556c0d57bb6a5
+  metadata.gz: b53fafbf091a67a329832663c058b4e8243b36a779f8bc52cc7f37de556ad0aa016245e0a059489b972e6afaccfea7d26a63a735686d5f50d88036a2f4ecaca1
+  data.tar.gz: 4a6ff368e221073c5addfab51e31df1b094ee3f69e09ebe3f38d6d552ebc761b14c552a1a2cd90dcfd148b1ba34ebb1b2e3abfcea9622ded8413870f21a60285

data/README.md

@@ -11,20 +11,22 @@ 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
 ```
 
@@ -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

@@ -25,12 +25,16 @@ class TCPClient
       "#{@hostname}:#{@addrinfo.ip_port}"
     end
 
-    def to_h
+    def to_hash
       { host: @hostname, port: @addrinfo.ip_port }
     end
 
+    def to_h(*args)
+      args.empty? ? to_hash : to_hash.slice(*args)
+    end
+
     def ==(other)
-      to_h == other.to_h
+      to_hash == other.to_hash
     end
     alias eql? ==
 

data/lib/tcp-client/configuration.rb

@@ -13,6 +13,7 @@ class TCPClient
     attr_reader :buffered,
                 :keep_alive,
                 :reverse_lookup,
+                :normalize_network_errors,
                 :connect_timeout,
                 :read_timeout,
                 :write_timeout,
@@ -27,6 +28,7 @@ class TCPClient
       @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
 
@@ -47,8 +49,8 @@ class TCPClient
 
     def ssl=(value)
       @ssl_params =
-        if Hash === value
-          Hash[value]
+        if value.respond_to?(:to_hash)
+          Hash[value.to_hash]
         else
           value ? {} : nil
         end
@@ -66,6 +68,10 @@ class TCPClient
       @reverse_lookup = value ? true : false
     end
 
+    def normalize_network_errors=(value)
+      @normalize_network_errors = value ? true : false
+    end
+
     def timeout=(seconds)
       @connect_timeout = @write_timeout = @read_timeout = seconds(seconds)
     end
@@ -103,23 +109,27 @@ class TCPClient
       @write_timeout_error = exception
     end
 
-    def to_h
+    def to_hash
       {
         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
 
+    def to_h(*args)
+      args.empty? ? to_hash : to_hash.slice(*args)
+    end
+
     def ==(other)
-      to_h == other.to_h
+      to_hash == other.to_hash
     end
     alias eql? ==
 

data/lib/tcp-client/errors.rb

@@ -31,13 +31,15 @@ class TCPClient
     end
   end
 
-  class NotConnectedError < IOError
+  NetworkError = Class.new(StandardError)
+
+  class NotConnectedError < NetworkError
     def initialize
       super('client not connected')
     end
   end
 
-  class TimeoutError < IOError
+  class TimeoutError < NetworkError
     def initialize(message = nil)
       super(message || "unable to #{action} in time")
     end

data/lib/tcp-client/ssl_socket.rb

@@ -18,6 +18,7 @@ class TCPClient
       super(socket, create_context(ssl_params))
       self.sync_close = true
       self.hostname = address.hostname
+      check_new_session if @new_session
       deadline.valid? ? connect_with_deadline(deadline, exception) : connect
       post_connection_check(address.hostname) if should_verify?(ssl_params)
     end
@@ -25,7 +26,19 @@ class TCPClient
     private
 
     def create_context(ssl_params)
-      OpenSSL::SSL::SSLContext.new.tap { |ctx| ctx.set_params(ssl_params) }
+      @new_session = nil
+      ::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 }
+      end
+    end
+
+    def check_new_session
+      time = @new_session.time.to_f + @new_session.timeout
+      if Process.clock_gettime(Process::CLOCK_REALTIME) < time
+        self.session = @new_session
+      end
     end
 
     def connect_with_deadline(deadline, exception)
@@ -33,9 +46,13 @@ class TCPClient
     end
 
     def should_verify?(ssl_params)
-      ssl_params[:verify_mode] != OpenSSL::SSL::VERIFY_NONE &&
+      ssl_params[:verify_mode] != ::OpenSSL::SSL::VERIFY_NONE &&
         context.verify_hostname
     end
+
+    CONTEXT_CACHE_MODE =
+      ::OpenSSL::SSL::SSLContext::SESSION_CACHE_CLIENT |
+        ::OpenSSL::SSL::SSLContext::SESSION_CACHE_NO_INTERNAL_STORE
   end
 
   private_constant(:SSLSocket)

data/lib/tcp-client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class TCPClient
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

data/lib/tcp-client.rb

@@ -10,7 +10,7 @@ require_relative 'tcp-client/default_configuration'
 require_relative 'tcp-client/version'
 
 class TCPClient
-  def self.open(address, configuration = Configuration.default)
+  def self.open(address, configuration = nil)
     client = new
     client.connect(Address.new(address), configuration)
     block_given? ? yield(client) : client
@@ -18,11 +18,7 @@ class TCPClient
     client.close if block_given?
   end
 
-  def self.with_deadline(
-    timeout,
-    address,
-    configuration = Configuration.default
-  )
+  def self.with_deadline(timeout, address, configuration = nil)
     client = nil
     raise(NoBlockGivenError) unless block_given?
     address = Address.new(address)
@@ -36,19 +32,15 @@ class TCPClient
 
   attr_reader :address, :configuration
 
-  def initialize
-    @socket = @address = @deadline = @configuration = nil
-  end
-
   def to_s
     @address&.to_s || ''
   end
 
-  def connect(address, configuration, timeout: nil, exception: nil)
+  def connect(address, configuration = nil, timeout: nil, exception: nil)
     close if @socket
     raise(NoOpenSSLError) if configuration.ssl? && !defined?(SSLSocket)
     @address = Address.new(address)
-    @configuration = configuration.dup.freeze
+    @configuration = (configuration || Configuration.default).dup
     @socket = create_socket(timeout, exception)
     self
   end
@@ -56,7 +48,7 @@ class TCPClient
   def close
     @socket&.close
     self
-  rescue IOError
+  rescue *NETWORK_ERRORS
     self
   ensure
     @socket = @deadline = nil
@@ -79,23 +71,27 @@ class TCPClient
   def read(nbytes = nil, timeout: nil, exception: nil)
     raise(NotConnectedError) if closed?
     deadline = create_deadline(timeout, configuration.read_timeout)
-    return @socket.read(nbytes) unless deadline.valid?
+    return stem_errors { @socket.read(nbytes) } unless deadline.valid?
     exception ||= configuration.read_timeout_error
-    @socket.read_with_deadline(nbytes, deadline, exception)
+    stem_errors(exception) do
+      @socket.read_with_deadline(nbytes, deadline, exception)
+    end
   end
 
   def write(*msg, timeout: nil, exception: nil)
     raise(NotConnectedError) if closed?
     deadline = create_deadline(timeout, configuration.write_timeout)
-    return @socket.write(*msg) unless deadline.valid?
+    return stem_errors { @socket.write(*msg) } unless deadline.valid?
     exception ||= configuration.write_timeout_error
-    msg.sum do |chunk|
-      @socket.write_with_deadline(chunk.b, deadline, exception)
+    stem_errors(exception) do
+      msg.sum do |chunk|
+        @socket.write_with_deadline(chunk.b, deadline, exception)
+      end
     end
   end
 
   def flush
-    @socket&.flush
+    stem_errors { @socket&.flush }
     self
   end
 
@@ -108,8 +104,33 @@ class TCPClient
   def create_socket(timeout, exception)
     deadline = create_deadline(timeout, configuration.connect_timeout)
     exception ||= configuration.connect_timeout_error
-    @socket = TCPSocket.new(address, configuration, deadline, exception)
-    return @socket unless configuration.ssl?
-    SSLSocket.new(@socket, address, configuration, deadline, exception)
+    stem_errors(exception) do
+      @socket = TCPSocket.new(address, configuration, deadline, exception)
+      return @socket unless configuration.ssl?
+      SSLSocket.new(@socket, address, configuration, deadline, exception)
+    end
   end
+
+  def stem_errors(except = nil)
+    yield
+  rescue *NETWORK_ERRORS => e
+    raise unless configuration.normalize_network_errors
+    (except && e.is_a?(except)) ? raise : raise(NetworkError, e)
+  end
+
+  NETWORK_ERRORS =
+    [
+      Errno::EADDRNOTAVAIL,
+      Errno::ECONNABORTED,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::EINVAL,
+      Errno::ENETUNREACH,
+      Errno::EPIPE,
+      IOError,
+      SocketError
+    ].tap do |errors|
+      errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
+    end.freeze
 end

data/rakefile.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require 'rake/clean'
-require 'rake/testtask'
 require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 $stdout.sync = $stderr.sync = true
 
@@ -10,7 +10,4 @@ CLOBBER << 'prj'
 
 task(:default) { exec('rake --tasks') }
 
-Rake::TestTask.new(:test) do |task|
-  task.pattern = 'test/**/*_test.rb'
-  task.warning = task.verbose = true
-end
+RSpec::Core::RakeTask.new { |task| task.ruby_opts = %w[-w] }

data/sample/google_ssl.rb

@@ -2,23 +2,24 @@
 
 require_relative '../lib/tcp-client'
 
-# create a configuration.
-# - use TLS 1.2
+# create a configuration:
 # - don't use internal buffering
+# - use TLS 1.2 or TLS 1.3
 cfg =
   TCPClient::Configuration.create(
     buffered: false,
     ssl_params: {
-      ssl_version: :TLSv1_2
+      min_version: :TLS1_2,
+      max_version: :TLS1_3
     }
   )
 
-# request to Google:
-# - limit all interactions to 0.5 seconds
+# 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(0.5, 'www.google.com:443', cfg) do |client|
+TCPClient.with_deadline(1.5, 'www.google.com:443', cfg) do |client|
   p client.write("GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n")
   p client.read(12)
 end

data/spec/helper.rb

@@ -0,0 +1,12 @@
+# 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

data/spec/tcp-client/address_spec.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative '../helper'
+
+RSpec.describe TCPClient::Address do
+  describe '.new' do
+    context 'when called with an Integer parameter' do
+      subject(:address) { TCPClient::Address.new(42) }
+
+      it 'points to the given port on localhost' do
+        expect(address.hostname).to eq 'localhost'
+        expect(address.to_s).to eq 'localhost:42'
+        expect(address.addrinfo.ip_port).to be 42
+      end
+
+      it 'uses IPv6' do
+        expect(address.addrinfo.ip?).to be true
+        expect(address.addrinfo.ipv6?).to be true
+        expect(address.addrinfo.ipv4?).to be false
+      end
+    end
+
+    context 'when called with an Addrinfo' do
+      subject(:address) { TCPClient::Address.new(addrinfo) }
+      let(:addrinfo) { Addrinfo.tcp('::1', 42) }
+
+      it 'uses the given Addrinfo' do
+        expect(address.addrinfo).to eq addrinfo
+      end
+
+      it 'points to the given host and port' do
+        expect(address.hostname).to eq addrinfo.getnameinfo[0]
+        expect(address.addrinfo.ip_port).to be 42
+      end
+
+      it 'uses IPv6' do
+        expect(address.addrinfo.ip?).to be true
+        expect(address.addrinfo.ipv6?).to be true
+        expect(address.addrinfo.ipv4?).to be false
+      end
+    end
+
+    context 'when called with a String' do
+      context 'when a host name and port is provided' do
+        subject(:address) { TCPClient::Address.new('localhost:42') }
+
+        it 'points to the given host and port' do
+          expect(address.hostname).to eq 'localhost'
+          expect(address.to_s).to eq 'localhost:42'
+          expect(address.addrinfo.ip_port).to be 42
+        end
+
+        it 'uses IPv6' do
+          expect(address.addrinfo.ip?).to be true
+          expect(address.addrinfo.ipv6?).to be true
+          expect(address.addrinfo.ipv4?).to be false
+        end
+      end
+
+      context 'when only a port is provided' do
+        subject(:address) { TCPClient::Address.new(':21') }
+
+        it 'points to the given port on localhost' do
+          expect(address.hostname).to eq ''
+          expect(address.to_s).to eq ':21'
+          expect(address.addrinfo.ip_port).to be 21
+        end
+
+        it 'uses IPv4' do
+          expect(address.addrinfo.ip?).to be true
+          expect(address.addrinfo.ipv6?).to be false
+          expect(address.addrinfo.ipv4?).to be true
+        end
+      end
+
+      context 'when an IPv6 address is provided' do
+        subject(:address) { TCPClient::Address.new('[::1]:42') }
+
+        it 'points to the given port on localhost' do
+          expect(address.hostname).to eq '::1'
+          expect(address.to_s).to eq '[::1]:42'
+          expect(address.addrinfo.ip_port).to be 42
+        end
+
+        it 'uses IPv6' do
+          expect(address.addrinfo.ip?).to be true
+          expect(address.addrinfo.ipv6?).to be true
+          expect(address.addrinfo.ipv4?).to be false
+        end
+      end
+    end
+  end
+
+  describe '#to_hash' do
+    subject(:address) { TCPClient::Address.new('localhost:42') }
+
+    it 'returns itself as an Hash' do
+      expect(address.to_hash).to eq(host: 'localhost', port: 42)
+    end
+  end
+
+  describe '#to_h' do
+    subject(:address) { TCPClient::Address.new('localhost:42') }
+
+    it 'returns itself as an Hash' do
+      expect(address.to_h).to eq(host: 'localhost', port: 42)
+    end
+
+    it 'allows to specify the keys the result should contain' do
+      expect(address.to_h(:port)).to eq(port: 42)
+      expect(address.to_h(:host)).to eq(host: 'localhost')
+    end
+  end
+
+  describe 'comparison' do
+    context 'comparing two equal instances' do
+      let(:address_a) { TCPClient::Address.new('localhost:42') }
+      let(:address_b) { TCPClient::Address.new('localhost:42') }
+
+      it 'compares to equal' do
+        expect(address_a).to eq address_b
+      end
+
+      context 'using the == opperator' do
+        it 'compares to equal' do
+          expect(address_a == address_b).to be true
+        end
+      end
+
+      context 'using the === opperator' do
+        it 'compares to equal' do
+          expect(address_a === address_b).to be true
+        end
+      end
+    end
+
+    context 'comparing two non-equal instances' do
+      let(:address_a) { TCPClient::Address.new('localhost:42') }
+      let(:address_b) { TCPClient::Address.new('localhost:21') }
+
+      it 'compares not to equal' do
+        expect(address_a).not_to eq address_b
+      end
+
+      context 'using the == opperator' do
+        it 'compares not to equal' do
+          expect(address_a == address_b).to be false
+        end
+      end
+
+      context 'using the === opperator' do
+        it 'compares not to equal' do
+          expect(address_a === address_b).to be false
+        end
+      end
+    end
+  end
+end