Skip to content

Latest commit

 

History

History
159 lines (113 loc) · 6.16 KB

README.src.md

File metadata and controls

159 lines (113 loc) · 6.16 KB
Raw

tcpgoon

tcpgoon

Codacy Badge Build Status Go Report Card Coverage Status License

{toc}

TL;DR

Tool to test concurrent connections towards a server listening to a TCP port

Description

  • Given a hostname, port, the number of connections (100 by default), a delay between connections (10ms by default) and an interval between stats updates to the standard output...
  • It will use goroutines to open TCP connections and try to read from them
  • The tool will exit once all connections have been dialed (successfully or not)
  • Exit status different from 0 represent executions where all connections were not established successfully, facilitating the integration in test suites.

Usage

Execution using Docker

See our public docker image and its documentation. The image is being updated continuously; you can bind to specific versions, or to the "latest" tag.

Installation

% go get github.com/dachad/tcpgoon

Help

{sample} ./_script/readme_generator_samples/help

Examples

Note: depending on the number of connections you want to open, you may need to increase the number of file descriptors your user supports

Successful execution (connections were opened as expected):

{sample} ./_script/readme_generator_samples/execution_ok

Unsuccessful execution (unable to open connections against the destination host:port):

{sample} ./_script/readme_generator_samples/execution_ko

Extra project information

Why do I want to test TCP connections?

Stressing TCP connections against a server/application facilitates the detection of bottlenecks/issues limiting the capacity of this server/application to accept/keep a specific (and potentially) large number of parallel connections. Some examples of typical (configuration) issues:

  • OS configuration (TCP backlog, network drivers buffers),
  • number of file descriptors/processes the server can use,
  • application listener properties...

These limitations may pass unnoticed in actual application-l7 stress tests, given other bottlenecks can arise earlier than these limitations, or degradation scenarios and/or special conditions may not be reproduced during the stress tests execution, but in real life (lots of connections queued because of a dependency taking longer to reply than it usually does?)

hping is not an actual option for this use case given it won't complete a 3-way handshake, so the connection will not reach the accept() syscall of your server/application or fill up your TCP backlog.

Where does the project name come from?

Goon: /ɡuːn/ noun informal; noun: goon; plural noun: goons ;
...
2.
NORTH AMERICAN
a bully or thug, especially a member of an armed or security force.
...

thegoon

Authors

Especial thanks to...

Development information

TO-DO

We do use Github issues to track bugs, improvements and feature requests. Do not hesitate to raise new ones, or solve them for us by raising PRs ;)

Project structure

This project uses a layered topology, where cmd (complemented by cmdutil) takes care of commands/flags/arguments and uses mtcpclient, which owns and knows everything about "multiple TCP connections" (including reporting), while tcpclient only cares about managing single TCP connections. tcpserver is just there as a dependency for the other packages' tests.

{godepgraph}

A shared package (debugging) is also supplied just as a basic mechanism to control debug output.

README maintenance

Do not edit README.md directly, as your changes will be lost. Consider README.src.md and the execution (requires godepgraph and Graphviz) of:

% ./_script/readme_generator

Samples injected in the readme can be found in the _script/readme_generator_samples/ directory.

Dockerhub README requires manual maintenance, bringing relevant aspects from here and adapting cmdusage (by docker run...)

Testing locally

You can use the standard go test command, or use our scripts we also run as CI.

Main tests execution:

% ./_script/test

Emulation of a travis job execution using docker (of course, it needs docker):

% COVERALLS_TOKEN="myToken" ./_script/cibuild-docker

And also emulating a travis job deployment (it publishes new binaries providing successful tests and the right credentials, unless you also use the -r flag / dry-run):

% COVERALLS_TOKEN="myToken" ./_script/cibuild-docker -d