Toxy - Hackable HTTP Proxy for Resiliency Testing and Simulated Network Conditions

Toxy is a hackable HTTP proxy to simulate server failure scenarios, systems resiliency testing and unexpected network conditions, built for node.js.

It was mainly designed for failure resistance testing, when Toxy becomes particularly useful in order to cover fault tolerance and resiliency capabilities of a system, especially in disruption-tolerant networks and service-oriented architectures, where Toxy may act as MitM proxy among services in order to inject failure.

Toxy allows you to plug in poisons, optionally filtered by rules, which essentially can intercept and alter the HTTP flow as you need, performing multiple evil actions in the middle of that process, such as limiting the bandwidth, delaying network packets, injecting network jitter latency or replying with a custom error or status code. It operates only at L7 (application level).

It can be fluently used programmatically or via HTTP API. It was built on top of rocky, a full-featured middleware-oriented HTTP proxy, and it's also pluggable in connect/express as standard middleware.

Features:

Full-featured HTTP/S proxy (backed by rocky and HTTP-proxy)
Hackable and elegant programmatic API (inspired on connect/express)
Admin HTTP API for external management and dynamic configuration
Featured built-in router with nested configuration
Hierarchical and composable poisoning with rule-based filtering
Hierarchical middleware layer (both global and route scopes)
Easily augmentable via middleware (based on connect/express middleware)
Supports both incoming and outgoing traffic poisoning
Built-in poisons (bandwidth, error, abort, latency, slow read...)
Rule-based poisoning (probabilistic, HTTP method, headers, body...)
Supports third-party poisons and rules
Built-in balancer and traffic interceptor via middleware
Inherits API and features from rocky
Compatible with connect/express (and most of their middleware)
Able to run as standalone HTTP proxy

There're some other similar solutions like toxy in the market, but most of them do not provide a proper programmatic control and usually are not easy to hack, configure or are directly closed to extensibility.

Furthermore, the majority of those solutions only operates at TCP L3 level stack instead of providing high-level abstractions to cover common requirements in the specific domain and nature of the HTTP L7 protocol, like Toxy tries to provide.

Toxy brings a powerful hackable and extensible solution with a convenient abstraction, but without losing a proper low-level interface capabilities to deal with HTTP protocol primitives easily.

Toxy was designed based on the rules of composition, simplicity and extensibility. Via its built-in hierarchical domain specific middleware layer you can easily augment Toxy features to your own needs.

Concepts:

Toxy introduces two directives: poisons and rules.

Poisons are the specific logic which infects an incoming or outgoing HTTP transaction (e.g: injecting a latency, replying with an error). One HTTP transaction can be poisoned by one or multiple poisons, and those poisons can be also configured to infect both global or route level traffic.

Rules are a kind of match validation filters that inspects an HTTP request/response in order to determine, given a certain rules, if the HTTP transaction should be poisoned or not (e.g: if headers matches, query params, method, body...). Rules can be reused and applied to both incoming and outgoing traffic flows, including different scopes: global, route or poison level.

How It Works:

↓  ( Incoming request )  ↓
 ↓          |||           ↓
 ↓    +-------------+     ↓
 ↓    | Toxy Router |     ↓ -> Match the incoming request
 ↓    +-------------+     ↓
 ↓          |||           ↓
 ↓ +--------------------+ ↓
 ↓ |   Incoming phase   | ↓ -> The proxy receives the request from the client
 ↓ |~~~~~~~~~~~~~~~~~~~~| ↓
 ↓ |  ----------------  | ↓
 ↓ |  |  Exec Rules  |  | ↓ -> Apply configured rules for the incoming request
 ↓ |  ----------------  | ↓
 ↓ |        |||         | ↓
 ↓ |  ----------------  | ↓
 ↓ |  | Exec Poisons |  | ↓ -> If all rules passed, then poison the HTTP flow
 ↓ |  ----------------  | ↓
 ↓ +~~~~~~~~~~~~~~~~~~~~+ ↓
 ↓        /      \        ↓
 ↓        \      /        ↓
 ↓ +--------------------+ ↓
 ↓ |  HTTP dispatcher   | ↓ -> Forward the HTTP traffic to the target server, either 
 ↓ +--------------------+ ↓     poisoned or not
 ↓        /      \        ↓
 ↓        \      /        ↓
 ↓ +--------------------+ ↓
 ↓ |   Outgoing phase   | ↓ -> Receives response from target server
 ↓ |~~~~~~~~~~~~~~~~~~~~| ↓
 ↓ |  ----------------  | ↓
 ↓ |  |  Exec Rules  |  | ↓ -> Apply configured rules for the outgoing request
 ↓ |  ----------------  | ↓
 ↓ |        |||         | ↓
 ↓ |  ----------------  | ↓
 ↓ |  | Exec Poisons |  | ↓ -> If all rules passed, then poison the HTTP flow before 
 ↓ |  ----------------  | ↓     send it to the client
 ↓ +~~~~~~~~~~~~~~~~~~~~+ ↓
 ↓          |||           ↓
 ↓ ( Send to the client ) ↓ -> Finally, send the request to the client,
                                either poisoned or not