{"id":19749469,"url":"https://github.com/reidmorrison/net_tcp_client","last_synced_at":"2025-04-07T07:18:07.026Z","repository":{"id":4797386,"uuid":"5950333","full_name":"reidmorrison/net_tcp_client","owner":"reidmorrison","description":"Net::TCPClient is a TCP Socket Client with automated failover, load balancing, retries and built-in timeouts.","archived":false,"fork":false,"pushed_at":"2024-03-22T08:06:31.000Z","size":211,"stargazers_count":49,"open_issues_count":4,"forks_count":21,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-31T06:04:49.871Z","etag":null,"topics":["ruby","socket-io-client","ssl","tcp","tcp-client"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reidmorrison.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-09-25T13:24:23.000Z","updated_at":"2024-09-25T09:45:48.000Z","dependencies_parsed_at":"2024-06-18T19:58:43.159Z","dependency_job_id":null,"html_url":"https://github.com/reidmorrison/net_tcp_client","commit_stats":null,"previous_names":["clarityservices/resilient_socket"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reidmorrison%2Fnet_tcp_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reidmorrison%2Fnet_tcp_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reidmorrison%2Fnet_tcp_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reidmorrison%2Fnet_tcp_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reidmorrison","download_url":"https://codeload.github.com/reidmorrison/net_tcp_client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608160,"owners_count":20965953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","socket-io-client","ssl","tcp","tcp-client"],"created_at":"2024-11-12T02:26:38.247Z","updated_at":"2025-04-07T07:18:07.007Z","avatar_url":"https://github.com/reidmorrison.png","language":"Ruby","readme":"# net_tcp_client\n[![Gem Version](https://img.shields.io/gem/v/net_tcp_client.svg)](https://rubygems.org/gems/net_tcp_client) [![Build Status](https://github.com/reidmorrison/net_tcp_client/workflows/build/badge.svg)](https://github.com/reidmorrison/net_tcp_client/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/net_tcp_client.svg)](https://rubygems.org/gems/net_tcp_client) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)\n\nNet::TCPClient is a TCP Socket Client with automated failover, load balancing, retries and built-in timeouts.\n\n* https://github.com/reidmorrison/net_tcp_client\n\n## Introduction\n\nNet::TCPClient implements high availability and resilience features that many developers wish was\nalready included in the standard Ruby libraries.\n\nAnother important feature is that the _connect_ and _read_ API's use timeout's to\nprevent a network issue from \"hanging\" the client program.\n\n## Features\n\n* Automated failover to another server.\n* Load balancing across multiple servers.\n* SSL and non-ssl connections.\n* Connect Timeout.\n* Read Timeout.\n* Write Timeout.\n* Fails over / load balances across all servers under a single DNS entry.\n* Logging.\n    * Optional trace level logging of all data sent or received.\n* Uses non blocking timeouts, instead of using threads such as used by the Timeout class.\n* Additional exceptions to distinguish between connection failures and timeouts.\n* Handshake callbacks.\n    * After a new connection has been established callbacks can be used\n      for handshakes such as authentication before data is sent.\n\n### Example\n\n~~~ruby\nrequire 'net/tcp_client'\n\nNet::TCPClient.connect(server: 'mydomain:3300') do |client|\n  client.write('Update the database')\n  response = client.read(20)\n  puts \"Received: #{response}\"\nend\n~~~\n\nEnable SSL encryption:\n\n~~~ruby\nrequire 'net/tcp_client'\n\nNet::TCPClient.connect(server: 'mydomain:3300', ssl: true) do |client|\n  client.write('Update the database')\n  response = client.read(20)\n  puts \"Received: #{response}\"\nend\n~~~\n\n## High Availability\n\nNet::TCPClient automatically tries each server in turn, should it fail to connect, or\nif the connection is lost the next server is tried immediately.\n\nNet::TCPClient detects DNS entries that have multiple IP Addresses associated with them and\nadds each of the ip addresses for the single DNS name to the list of servers to try to connect to.\n\nIf a server is unavailable, cannot connect, or the connection is lost, the next server is immediately\ntried. Once all servers have been exhausted, it will keep trying to connect, starting with the\nfirst server again.\n\nWhen a connection is first established, and every time a connection is lost, Net::TCPClient\nuses connection policies to determine which server to connect to.\n\n## Load Balancing\n\nUsing the connection policies client TCP connections can be balanced across multiple servers.\n\n## Connection Policies\n\n#### Ordered\n\nServers are tried in the order they were supplied.\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600']\n)\n~~~\n\nThe servers will tried in the following order:\n`server1`, `server2`, `server3`\n\n`:ordered` is the default, but can be explicitly defined follows:\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600'],\n  policy:  :ordered\n)\n~~~\n\n#### Random\n\nServers are tried in a Random order.\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600'],\n  policy:  :random\n)\n~~~\n\nNo server is tried again until all of the others have been tried first.\n\nExample run, the servers could be tried in the following order:\n`server3`, `server1`, `server2`\n\n#### Custom defined order\n\nSupply your own custom order / load balancing algorithm for connecting to servers:\n\nExample:\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600'],\n  policy:  -\u003e addresses, count do\n    # Return nil after the last address has been tried so that retry logic can take over\n    if count \u003c= address.size\n      addresses.sample\n    end\n  end\n)\n~~~\n\nThe above example returns addresses in random order without checking if a host name has been used before.\n\nIt is important to check the count so that once all servers have been tried, it should return nil so that\nthe retry logic can take over. Otherwise it will constantly try to connect to the servers without\nthe retry delays etc.\n\nExample run, the servers could be tried in the following order:\n`server3`, `server1`, `server3`\n\n### Automatic Retry\n\nIf a connection cannot be established to any servers in the list Net::TCPClient will retry from the\nfirst server. This retry behavior can be controlled using the following options:\n\n* `connect_retry_count` [Integer]\n    * Number of times to retry connecting when a connection fails\n    * Default: 10\n\n* `connect_retry_interval` [Float]\n    * Number of seconds between connection retry attempts after the first failed attempt\n    * Default: 0.5\n\n* `retry_count` [Integer]\n    * Number of times to retry when calling #retry_on_connection_failure\n    * This is independent of :connect_retry_count which still applies with\n    * connection failures. This retry controls upto how many times to retry the\n    * supplied block should a connection failure occur during the block\n    * Default: 3\n\n#### Note\n\nA server will only be retried again using the retry controls above once all other servers in the\nlist have been exhausted.\n\nThis means that if a connection is lost to a server that it will try to connect to a different server,\nnot the same server unless it is the only server in the list.\n\n## Tuning\n\nIf there are multiple servers in the list it is important to keep the `connect_timeout` low otherwise\nit can take a long time to find the next available server.\n\n## Retry on connection loss\n\nTo transparently handle when a connection is lost after it has been established\nwrap calls that can be retried with `retry_on_connection_failure`.\n\n~~~ruby\nNet::TCPClient.connect(\n  server:                 'localhost:3300',\n  connect_retry_interval: 0.1,\n  connect_retry_count:    5\n) do |client|\n  # If the connection is lost, create a new one and retry the write\n  client.retry_on_connection_failure do\n    client.write('How many users available?')\n    response = client.read(20)\n    puts \"Received: #{response}\"\n  end\nend\n~~~\n\nIf the connection is lost during either the `write` or the `read` above the\nentire block will be re-tried once the connection has been re-stablished.\n\n## Callbacks\n\nAny time a connection has been established a callback can be called to handle activities such as:\n\n* Initialize per connection session sequence numbers.\n* Pass authentication information to the server.\n* Perform a handshake with the server.\n\n#### Authentication example:\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600'],\n  on_connect: -\u003e do |client|\n    client.write('My username and password')\n    result = client.read(2)\n    raise \"Authentication failed\" if result != 'OK'\n  end\n)\n~~~\n\n#### Per connection sequence number example:\n\n~~~ruby\ntcp_client = Net::TCPClient.new(\n  servers: ['server1:3300', 'server2:3300', 'server3:3600'],\n  on_connect: -\u003e do |client|\n    # Set the sequence number to 0\n    client.user_data = 0\n  end\n)\n\ntcp_client.retry_on_connection_failure do\n  # Write with the sequence number\n  tcp_client.write(\"#{tcp_client.user_data} hello\")\n  result = tcp_client.receive(30)\n\n  # Increment sequence number after every call to the server\n  tcp_client.user_data += 1\nend\n~~~\n\n## Project Status\n\n### Production Ready\n\nNet::TCPClient is actively being used in a high performance, highly concurrent\nproduction environments. The resilient capabilities of Net::TCPClient are put to the\ntest on a daily basis, including connections over the internet between remote data centers.\n\n## Installation\n\n    gem install net_tcp_client\n\nTo enable logging add [Semantic Logger](https://logger.rocketjob.io/):\n\n    gem install semantic_logger\n\nOr, add the following lines to you `Gemfile`:\n\n~~~ruby\ngem 'semantic_logger'\ngem 'net_tcp_client'\n~~~\n\nTo configure a stand-alone application for Semantic Logger:\n\n~~~ruby\nrequire 'semantic_logger'\n\n# Set the global default log level\nSemanticLogger.default_level = :trace\n\n# Log to a file, and use the colorized formatter\nSemanticLogger.add_appender(file_name: 'development.log', formatter: :color)\n~~~\n\nIf running Rails, see: [Semantic Logger Rails](https://logger.rocketjob.io/rails.html)\n\n### Support\n\nJoin the [Gitter chat session](https://gitter.im/rocketjob/support) if you have any questions.\n\nIssues / bugs can be reported via [Github issues](https://github.com/reidmorrison/net_tcp_client/issues).\n\n### Upgrading to V2\n\nThe following breaking changes have been made with V2:\n* The Connection timeout default is now 10 seconds, was 30 seconds.\n* To enable logging, add gem semantic_logger.\n    * The :logger option has been removed.\n* Deprecated option and attribute :server_selector has been removed.\n\n### Upgrading from ResilientSocket ![](https://img.shields.io/gem/dt/resilient_socket.svg)\n\nResilientSocket::TCPClient has been renamed to Net::TCPClient.\nThe API is exactly the same, just with a new namespace. Please upgrade to the new\n`net_tcp_client` gem and replace all occurrences of `ResilientSocket::TCPClient`\nwith `Net::TCPClient` in your code.\n\n## Supports\n\nTested and supported on the following Ruby platforms:\n- Ruby 2.1, 2.2, 2.3 and above\n- JRuby 1.7.23, 9.0 and above\n- Rubinius 2.5 and above\n\nThere is a soft dependency on [Semantic Logger](https://github.com/reidmorrison/semantic_logger). It will use SemanticLogger only if\nit is already available, otherwise any other standard Ruby logger can be used.\n\n### Note\n\nBe sure to place the `semantic_logger` gem dependency before `net_tcp_client` in your Gemfile.\n\n## Author\n\n[Reid Morrison](https://github.com/reidmorrison)\n\n[Contributors](https://github.com/reidmorrison/net_tcp_client/graphs/contributors)\n\n## Versioning\n\nThis project uses [Semantic Versioning](https://semver.org/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freidmorrison%2Fnet_tcp_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freidmorrison%2Fnet_tcp_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freidmorrison%2Fnet_tcp_client/lists"}