Awesome Open Source
Awesome Open Source

Chaos HTTP Proxy

Introduce failures into HTTP requests via a proxy server. This can uncover error handling bugs in HTTP clients. Andrew Gaul at Bounce Storage [email protected] originally wrote Chaos HTTP Proxy.


Chaos HTTP Proxy can trigger many different failures:

  • change case of HTTP header name
  • Content-MD5 request corruption
  • Content-MD5 response corruption
  • client timeout, HTTP 408
  • redirects (temporary and permanent)
  • reorder response headers
  • server connection break, i.e., short read and write
  • server errors: HTTP 500, 503, and 504
  • server timeout


Users can download releases from GitHub. One can also build the project by running mvn package which produces a binary at target/chaos-http-proxy. Chaos HTTP Proxy requires Java 7 to run.


Linux and Mac OS X users can run Chaos HTTP Proxy via the executable jar:

chmod +x chaos-http-proxy
chaos-http-proxy --properties chaos-http-proxy.conf

Windows users must explicitly invoke java:

java -jar chaos-http-proxy --properties chaos-http-proxy.conf

An example using curl:

curl --fail --proxy http://localhost:1080/
curl: (22) The requested URL returned error: 500 Server Error

Configuring Failure Rates

The configuration file determines all possible results for an HTTP request. Entries take the form [response_type]=[n], where [n] is an integral value that determines the relative occurrence likelihood of each response type. For example, the following configuration gives a 1% chance of responses failing with a 500 Internal Error response:


Sample configuration

Chaos HTTP Proxy accepts configuration at invocation time via the --properties flag and at run-time via the /chaos/api endpoint:

curl --request POST --upload-file chaos-http-proxy.conf http://localhost:1080/chaos/api
curl http://localhost:1080/chaos/api


  • lacks HTTP authentication
  • lacks HTTPS support


  • Charles Web Debugging Proxy - allows interactive modification of HTTP requests and responses
  • Chaos Monkey - inspiration for Chaos HTTP Proxy
  • Hamms - designed to elicit failures in your HTTP Client, similar to httpbin
  • httpbin - HTTP Request & Response Service which can deterministically exercise HTTP functionality
  • pathod - programmable HTTP server
  • toxiproxy - A proxy to simulate network and system conditions
  • toxy - Hackable HTTP proxy to simulate server failure scenarios and unexpected network conditions
  • Vaurien - Chaos TCP Proxy


Copyright (C) 2015-2016 Bounce Storage

Licensed under the Apache License, Version 2.0

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
java (31,559
http-proxy (78
chaos (27