net_tcp_client

Net::TCPClient is a TCP Socket Client with built-in timeouts, retries, and logging

Introduction

Net::TCPClient implements resilience features that many developers wish was already included in the standard Ruby libraries.

With so many "client" libraries to servers such us memcache, MongoDB, Redis, etc. their focus is on the communication formats and messaging interactions. As a result adding resilience is usually an after thought.

More importantly the way that each client implements connection failure handling varies dramatically. The purpose of this library is to extract the best of all the socket error handling out there and create a consistent way of dealing with connection failures.

Another important feature is that the connect and read API's use timeout's to prevent a network issue from "hanging" the client program.

Net::TCPClient API

Net::TCPClient is a drop in replacement for TCPSocket when used as a client.

The initializer is the only deviation since it accepts several new options that support automatic failover, re-connect and messaging retries.

Example

Connect to a server at address localhost, and on port 3300.

Specify a custom retry interval and retry counts during connection.

require 'net/tcp_client'

Net::TCPClient.connect(
  server:                 'localhost:3300',
  connect_retry_interval: 0.1,
  connect_retry_count:    5
) do |client|
  # If the connection is lost, create a new one and retry the send
  client.retry_on_connection_failure do
    client.send('Update the database')
  end
  response = client.read(20)
  puts "Received: #{response}"
end

Project Status

Production Ready

Net::TCPClient is actively being used in a high performance, highly concurrent production environments. The resilient capabilities of Net::TCPClient are put to the test on a daily basis, including connections over the internet between remote data centers.

Installation

gem install net_tcp_client

Although not required, it is recommended to use Semantic Logger for logging purposes:

gem install semantic_logger

Or, add the following lines to you Gemfile:

    gem 'semantic_logger'
    gem 'net_tcp_client'

To configure a stand-alone application for Semantic Logger:

require 'semantic_logger'

# Set the global default log level
SemanticLogger.default_level = :trace

# Log to a file, and use the colorized formatter
SemanticLogger.add_appender('development.log', &SemanticLogger::Appender::Base.colorized_formatter)

If running Rails, see: Semantic Logger Rails

Without Semantic Logger present a Ruby logger can be passed into Net::TCPClient.

Upgrading from ResilientSocket

ResilientSocket::TCPClient has been renamed to Net::TCPClient. The API is exactly the same, just with a new namespace. Please upgrade to the new net_tcp_client gem and replace all occurrences of ResilientSocket::TCPClient with Net::TCPClient in your code.

Supports

Tested and supported on the following Ruby platforms:

  • Ruby 1.9.3, 2.0, 2.1, 2.2 and above
  • JRuby 1.7, 9.0 and above
  • Rubinius 2.5 and above

There is a soft dependency on Semantic Logger. It will use SemanticLogger only if it is already available, otherwise any other standard Ruby logger can be used.

Note

Be sure to place the semantic_logger gem dependency before net_tcp_client in your Gemfile.

Versioning

This project adheres to Semantic Versioning.

Author

Reid Morrison

Versioning

This project uses Semantic Versioning.