Toxiproxy-compatible API

Since 0.4.0

Toxiproxy is a common way for test suites to break the network on purpose: add latency, cut bandwidth, time out or reset connections. Cloak Proxy can serve the same HTTP API, so a suite that already drives Toxiproxy can point at Cloak Proxy instead, and you see every request it breaks in the traffic list, with what was done to it.

Each Toxiproxy proxy becomes a listener that forwards to its upstream through Cloak Proxy. Each proxy’s toxics become the faults of a failure scenario named Toxiproxy: name, so you can watch their counts and log in the Failure Scenarios window.

Turn it on

1. In Tools › Failure Scenarios…, switch on Toxiproxy API under the scenario list. Or run cloakctl toxiproxy on (add --api-port N for a port other than 8474), or ask an assistant to use the toxiproxy_api MCP tool.

2. Point your Toxiproxy client at http://127.0.0.1:8474, the address Toxiproxy uses by default.

3. Create proxies and toxics as your suite already does. Requests to a proxy’s listen address go to its upstream through Cloak Proxy.

cloakctl toxiproxy on
curl -s -X POST localhost:8474/proxies -d '{"name":"api","listen":"127.0.0.1:26380","upstream":"127.0.0.1:8080"}'
curl -s -X POST localhost:8474/proxies/api/toxics -d '{"type":"latency","attributes":{"latency":1000}}'
curl -s http://127.0.0.1:26380/health        # arrives a second late, and shows in Cloak Proxy
cloakctl toxiproxy off

The API listens on 127.0.0.1 only, and refuses requests that come from web pages (with an Origin header). Like Toxiproxy’s, it has no token. It’s off until you turn it on.

Endpoints

Request	What it does
GET /version	The version (2.9.0-cloakproxy).
GET /proxies	Every proxy, by name.
POST /proxies	Create a proxy: name, upstream (host:port), listen (default 127.0.0.1:0, which picks a free port), enabled. 409 if the name or port is taken.
POST /populate	Create several proxies (an array), replacing ones with the same names.
GET, POST, DELETE /proxies/{name}	Read, change (enabled, listen, upstream) or delete a proxy.
GET, POST /proxies/{name}/toxics	List the proxy’s toxics, or add one: type, name (default type_stream), stream, toxicity (0–1), attributes.
GET, POST, DELETE /proxies/{name}/toxics/{toxic}	Read, change (toxicity, attributes) or remove a toxic.
POST /reset	Enable every proxy and remove every toxic.

Errors come back as Toxiproxy’s do: {"error": "proxy not found", "status": 404}.

How toxics act

Toxiproxy works on raw TCP bytes. Cloak Proxy forwards HTTP and HTTPS, so each toxic acts on whole requests:

Toxic	In Cloak Proxy
latency (latency, jitter)	Delays each request by the latency plus half the jitter.
bandwidth (rate, KB/s)	Sends responses at that rate.
slicer (average_size, delay µs)	Sends responses at average_size bytes per delay.
timeout (timeout ms)	No answer; the connection closes after the timeout (0: after an hour).
reset_peer	Resets the connection.
limit_data (bytes)	Sends that many bytes of the body, then closes the connection.
slow_close (delay ms)	Delays the request by that long.
toxicity below 1	Applies to that share of requests, at random.
A disabled proxy	Resets every connection.

stream (upstream or downstream) is accepted and kept, but every toxic acts on the request and its response as a whole.

Limits

• Upstreams must be HTTP or HTTPS. An upstream on port 443, or written as an https:// URL, is HTTPS; anything else is HTTP. Databases and other TCP protocols aren’t forwarded.
• A proxy’s faults match its upstream’s host and port, so they also apply to requests that reach that upstream through Cloak Proxy’s main port.
• Deleting a proxy closes its listener; connections already open finish their current request.
• Proxies, toxics and whether the API is on are saved with your rules.

Related

Failure scenariosBreak requests on a schedule, with a log.

cloakctlThe command-line tool.

Headless and CIRun tests through Cloak Proxy.