The same chaos model in two runtimes

What it does

chaos-proxy runs as a standalone proxy process. You point your HTTP client at it instead of the real upstream, and it applies the chaos rules from a YAML config file before forwarding requests. Because it operates at the transport layer, it works for any HTTP client in any language - your app code does not need to change at all.

Examples

Minimal config

target is the upstream service chaos-proxy forwards to. port is where chaos-proxy itself listens - point your app or tests here instead of the real service.

target: "http://localhost:4000"  # upstream to forward requests to
port: 5000                       # chaos-proxy listens here
global:
  - latency: 100                 # add 100ms to every request

Route-specific chaos

Global rules apply to all traffic. Route rules layer on top, matched by HTTP method and path pattern.

target: "http://localhost:4000"
port: 5000
global:
  - failRandomly:
      rate: 0.05               # 5% of all requests return 503
      status: 503
routes:
  "GET /users/:id":
    - failNth:
        n: 3                   # every 3rd request to this route returns 500
        status: 500
  "POST /orders":
    - latencyRange:
        minMs: 500             # simulate variable upstream slowness
        maxMs: 2000

Using a preset

# start with a ready-made mobile-3g simulation
npx chaos-proxy --config presets/mobile-3g.yaml --verbose

How to use it

Run chaos-proxy alongside your app or test suite. Point your HTTP client at the proxy port instead of the real service. Because nothing in your app code changes, you can toggle chaos on and off just by changing which port you target, or by swapping configs at runtime.

npx chaos-proxy --config chaos.yaml --verbose

# was: http://localhost:4000
# now: http://localhost:5000
fetch('http://localhost:5000/users/123')

curl -X POST http://localhost:5000/reload

import { loadConfig, startServer } from 'chaos-proxy'

const server = await startServer(loadConfig('chaos.yaml'))
// run your tests against http://localhost:5000
await server.close()

Node.js vs Go - which one to use?

Both versions share the same YAML config format and middleware model, so you can switch between them without changing your config files. The difference is runtime characteristics and how you install them.

If you are already in a Node.js project, start with chaos-proxy. If you are running high-concurrency scenarios, running in a Docker container without Node.js, or testing a Go service, use chaos-proxy-go.

Shared capabilities

From the blog

• Breaking your own app (on purpose) with chaos-proxy
• Node.js vs Go performance comparison
• Developing and benchmarking the same feature in Node and Go