ChaosProxy

Stop testing your applications under perfect localhost conditions.

A lightweight, high-performance reverse proxy written in Go, designed to intentionally inject network latency, jitter, and packet loss into HTTP traffic.

ChaosProxy acts as a deliberate network saboteur, allowing you to observe how your frontends, mobile apps, or backend microservices actually behave when network conditions degrade in the real world.

Quick Start

You can pull and run ChaosProxy instantly without needing Go installed on your machine, using Docker.

Use the following command to retrieve the package: docker pull ghcr.io/dmx3377/chaos-proxy:latest

The following command starts the proxy in front of a target API, forcing a 500ms delay with 200ms of jitter on every request and a 10% random connection drop rate:

docker run -p 8080:8080 \
  -e LATENCY_MS=500 \
  -e JITTER_MS=200 \
  -e DROP_RATE_PERCENT=10 \
  -e TARGET_URL="https://example.com" \
  dmx3377/chaos-proxy

Dynamic Configuration (Hot Reload)

ChaosProxy features an administrative endpoint that allows you to change chaos levels on the fly without restarting the container.

Endpoint: POST /sandbox/inject

Example of updating chaos levels via curl:

curl -X POST http://localhost:8080/sandbox/inject \
  -H "Content-Type: application/json" \
  -d '{
    "latency_ms": 200,
    "jitter_ms": 500,
    "drop_rate_percent": 5,
    "target_header": "X-Chaos-Test"
  }'

Environment Configurations

Configure ChaosProxy at runtime using these environment variables:

Variable	Description	Default
TARGET_URL	The upstream server to forward traffic to	https://httpbin.org
PORT	The internal port the proxy listens on inside the container	8080
LATENCY_MS	Artificial base delay added to requests (in milliseconds)	0
JITTER_MS	Randomized additional delay (0 to JITTER_MS) added to base latency	0
DROP_RATE_PERCENT	Percentage chance (0-100) that a request is dropped with an HTTP 504	0
TARGET_HEADER	If set, chaos only applies to requests with this header set to true (e.g. X-Chaos-Test: true)	(empty)

---

Development

Build Locally

docker build -t chaos-proxy .

Run Local Unit Tests

go test -v

---

License

This project is licensed under the Boost Software License.