Repository files navigation

A Rust port ofToxiproxy server, which is a TCP proxy to simulate network and system conditions for chaos and resiliency testing.

Noxious is fully compatible with Toxiproxy with the same REST API, so you can use the Toxiproxy CLI and all the existingclient libraries for Toxiproxy with noxious.

An async Rust client library callednoxious-client is also available to interact with Noxious or Toxiproxy.

Also check out ARCHITECTURE.md for implementation details.

Noxious server is available onDocker Hub andGitHub Packages for AMD64 and ARM. You can also find the executables for linux/amd64 in theReleases page.

Alternatively, you can build Noxious from source withcargo. Run thecargo build --release command and the executable will be available at./target/release/noxious-server.

You can runnoxious-server --help to get the list of arguments. By default the API server listens on port8474. This can be changed by providing the--port command line argument. You can provide a JSON config file that declares an array of proxies to be created on startup with the--config ./path/to/file.json argument.

For an extensive guide on how to use the Toxiproxy clients, please visit theToxiproxy GitHub repository.

When running in Docker, you will need to make sure that Noxious can reach the services that you are testing, and you can reach the ports that Noxious exposes for these services. You can use docker-compose, host networking or a bridge network, as described below.

Suppose you have a web service running in themyserver container, connected to networkmy-net, listening on port8000:

docker network create -d bridge my-netdocker run --name myserver --rm -p 8000:8000 --network=my-net myimage:latest

You can start Noxious with a command like:

docker run --name noxious \           --rm \           -p 8474:8474 \           -p 8001:8001 \           --network=my-net \           oguzbilgener/noxious

You can create the proxy by using one of theclients or the toxiproxy-cli, or by using cURL:

curl --request POST \  --url http://localhost:8474/proxies \  --header'Content-Type: application/json' \  --data'{    "name": "myserver",    "listen": "0.0.0.0:8001",    "upstream": "myserver:8000",    "enabled": true}'

Now you should be able to access your server via Noxious athttp://localhost:8001, or athttp://noxious:8001 from another container within the same Docker network.

You can add a latency toxic to simulate a bad network condition:

curl --request POST \  --url http://localhost:8474/proxies/myserver/toxics \  --header'Content-Type: application/json' \  --data'{"name": "myserver_latency","type":"latency","toxicity": 1,"direction": "upstream","attributes": {"latency": 200,"jitter": 50}}'

In addition to the initial JSON config, you can use the CLI or the REST API clients to create proxies:

toxiproxy-cli create test_redis -l localhost:26379 -u localhost:6379

You can add toxics using the client libraries, or via the CLI:

toxiproxy-cli toxic add test_redis -t latency -a latency=1000

See theToxiproxy README for the full documentation of toxics.

Licensed under either of Apache License, Version 2.0 or MIT license at your option.