feat(#9): add examples

.editorconfig

@@ -8,13 +8,5 @@ end_of_line = lf
 trim_trailing_whitespace = true
 insert_final_newline = true
 
-[Makefile]
-charset = utf-8
-indent_style = tabs
-indent_size = 2
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true
-
 [*.sh]
 insert_final_newline = false

README.md

@@ -1,58 +1,71 @@
-# toxy [![Build Status](https://api.travis-ci.org/h2non/toxy.svg?branch=master&style=flat)](https://travis-ci.org/h2non/toxy) [![Code Climate](https://codeclimate.com/github/h2non/toxy/badges/gpa.svg)](https://codeclimate.com/github/h2non/toxy) [![NPM](https://img.shields.io/npm/v/toxy.svg)](https://www.npmjs.org/package/toxy)
-
-<!--
-![Downloads](https://img.shields.io/npm/dm/toxy.svg)
--->
+# toxy [![Build Status](https://api.travis-ci.org/h2non/toxy.svg?branch=master&style=flat)](https://travis-ci.org/h2non/toxy) [![Code Climate](https://codeclimate.com/github/h2non/toxy/badges/gpa.svg)](https://codeclimate.com/github/h2non/toxy) [![NPM](https://img.shields.io/npm/v/toxy.svg)](https://www.npmjs.org/package/toxy) ![Stability](http://img.shields.io/badge/stability-beta-orange.svg?style=flat)
 
 <img align="right" height="180" src="http://s8.postimg.org/ikc9jxllh/toxic.jpg" />
 
-Pluggable and hackable HTTP proxy to simulate multiple server failures and unexpected conditions.
-Built for [node.js](http://nodejs.org)/[io.js](https://iojs.org).
+**toxy** is a hackable HTTP proxy to simulate server failure scenarios and unexpected conditions. It was mainly designed to be useful for fuzz/evil testing purposes in fault tolerant and resilient systems.
+A common use case scenario will be in a service-oriented distributed architecture, acting as intermediate proxy between services.
 
-toxy provides a simple and fluent [programmatic API](#programmatic-api),
-extending the featured [API](https://github.com/h2non/rocky#programmatic-api) of [rocky](https://github.com/h2non/rocky).
+Runs in [node.js](http://nodejs.org)/[io.js](https://iojs.org). `toxy` is compatible with [connect](https://github.com/senchalabs/connect)/[express](http://expressjs.com), and it was built on top of [rocky](https://github.com/h2non/rocky), a full-featured and middleware-oriented HTTP/S proxy.
 
 Requires node.js +0.12 or io.js +1.6
 
 **This is a work in progress**
 
-## Built-in poisons
+## Contents
 
-- [x] [Delay](#delay)
-- [x] [Timeout](#timeout)
-- [x] [Inject response](#inject-response)
-- [x] [Bandwidth](#bandwidth)
-- [x] [Rate limit](#rate-limit)
-- [x] [Slow read](#slow-read)
-- [x] [Slow open](#slow-open)
-- [x] [Slow close](#slow-close)
-- [x] [Throttle](#throttle)
-- [x] [Abort connection](#abort-connection)
+- [Features](#features)
+- Introduction
+  - How it works
+  - Concepts
+  - Middleware layer
+- Usage
+  - Installation
+  - Configuration
+  - Examples
+- Poisons
+  - Built-in poisons
+  - How to write poisons
+- Rules
+  - Built-in rules
+  - How to write rules
+- Programmatic API
+- [License](#license)
 
-## Built-in rules
+## Features
 
-- [x] [Random](#random)
-- [x] [Method](#method)
-- [x] [Headers](#headers)
-- [x] [Content Type](#content-type)
-- [ ] [Query params](#query-params)
-- [ ] [Body](#body)
+- Full-featured HTTP/S proxy (backed by [http-proxy](https://github.com/nodejistu/node-http-proxy))
+- Hackable and featured programmatic API
+- Easily augmentable via middleware (based on connect/express middleware)
+- Compatible with connect/express
+- Built-in
+- Pluggable poisons
+-
+- Runs as standalone HTTP proxy
 
-<!--
-## How it works
+## Introduction
 
-```
+### Motivation
 
-```
--->
+### Concepts
+
+### How it works
+
+### Middleware layer
 
-## Installation
+
+## Usage
+
+### Installation
 
 ```
 npm install toxy
 ```
 
-## Examples
+### Configuration
+
+### Examples
+
+See [examples/](https://github.com/h2non/toxy/blob/examples) directory for more featured examples
 
 ```js
 var toxy = require('toxy')
@@ -69,9 +82,32 @@ proxy
 
 ## Poisons
 
-#### Delay
+### Built-in poisons
 
-#### Timeout
+- [x] [Latency](#latency)
+- [x] [Inject response](#inject-response)
+- [x] [Bandwidth](#bandwidth)
+- [x] [Rate limit](#rate-limit)
+- [x] [Slow read](#slow-read)
+- [x] [Slow open](#slow-open)
+- [x] [Slow close](#slow-close)
+- [x] [Throttle](#throttle)
+- [x] [Abort connection](#abort-connection)
+- [x] [Timeout](#timeout)
+
+## Rules
+
+### Built-in rules
+
+- [x] [Random](#random)
+- [x] [Method](#method)
+- [x] [Headers](#headers)
+- [x] [Content Type](#content-type)
+- [ ] [Body](#body)
+
+## Poisons
+
+#### Latency
 
 #### Inject response
 
@@ -89,6 +125,8 @@ proxy
 
 #### Abort connection
 
+#### Timeout
+
 ## Rules
 
 #### Random
@@ -103,15 +141,12 @@ proxy
 
 #### Body
 
-
 ## Programmatic API
 
 ### rocky([ options ])
 
 #### Options
 
-See
-
 ## License
 
 MIT - Tomas Aparicio

examples/balancer.js

@@ -0,0 +1,14 @@
+const toxy = require('..')
+const poisons = toxy.poisons
+
+const proxy = toxy()
+
+proxy
+  .balance(['http://httpbin.org', 'http://httpbin.org'])
+
+proxy
+  .all('/*')
+  .poison(poisons.latency(1000))
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/bandwidth-limit.js

@@ -0,0 +1,16 @@
+const toxy = require('..')
+
+const proxy = toxy()
+const rules = proxy.rules
+const poisons = proxy.poisons
+
+proxy
+  .forward('http://httpbin.org')
+  .poison(poisons.bandwidth({ bps: 1024 }))
+  .withRule(rules.method('GET'))
+  .withRule(rules.probability(90))
+
+proxy.all('/*')
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/express.js

@@ -0,0 +1,16 @@
+const express = require('express')
+const toxy = require('..')
+
+const proxy = toxy()
+
+proxy.forward('http://httpbin.org')
+proxy.all('/*')
+
+proxy.poison(toxy.poisons.latency(1000))
+proxy.poison(toxy.poisons.bandwidth({ bps: 1024 }))
+
+const app = express()
+app.use(proxy.middleware())
+
+app.listen(3000)
+console.log('Server listening on port:', 3000)

examples/featured.js

@@ -0,0 +1,39 @@
+const toxy = require('..')
+
+const proxy = toxy()
+const rules = proxy.rules
+const poisons = proxy.poisons
+
+proxy
+  .forward('http://httpbin.org')
+  .rule(rules.probability(50))
+  .poison(poisons.slowOpen({ delay: 500 }))
+
+var route = proxy.get('/*')
+
+route
+  .poison(poisons.latency({ jitter: 1000 }))
+
+route
+  .poison(poisons.inject({ code: 502, body: 'Error!', headers: { 'X-Toxy-Poison': 'error' } }))
+  .withRule(rules.probability(25))
+
+route
+  .poison(poisons.slowClose({ delay: 1000 }))
+  .withRule(rules.probability(20))
+
+route
+  .poison(poisons.rateLimit({ limit: 2, threshold: 5000 }))
+  .withRule(rules.probability(20))
+
+route
+  .poison(poisons.slowRead({ bps: 100 }))
+  .withRule(rules.probability(35))
+
+route
+  .poison(poisons.abort())
+  .poisonRule(rules.probability(5)) // does the same as withRule()
+  .poisonRule(rules.method('GET'))
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/inject-error.js

@@ -0,0 +1,20 @@
+const toxy = require('..')
+
+const proxy = toxy()
+const rules = proxy.rules
+const poisons = proxy.poisons
+
+proxy
+  .forward('http://httpbin.org')
+  .poison(poisons.inject({
+    code: 503,
+    body: '{"error": "toxy injected error"}',
+    headers: {'Content-Type': 'application/json'}
+  }))
+  .withRule(rules.method('GET'))
+  .withRule(rules.probability(50))
+
+proxy.all('/*')
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/latency.js

@@ -0,0 +1,16 @@
+const toxy = require('..')
+
+const proxy = toxy()
+const rules = proxy.rules
+const poisons = proxy.poisons
+
+proxy
+  .forward('http://httpbin.org')
+  .poison(poisons.latency({ jitter: 1000 }))
+  .withRule(rules.method('GET'))
+  .withRule(rules.probability(50))
+
+proxy.all('/*')
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/middleware.js

@@ -0,0 +1,19 @@
+const toxy = require('..')
+const poisons = toxy.poisons
+
+const proxy = toxy()
+
+proxy
+  .forward('http://httpbin.org')
+
+proxy.use(function (req, res, next) {
+  // mad science here...
+  next()
+})
+
+proxy
+  .all('/*')
+  .poison(poisons.latency(1000))
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/rate-limit.js

@@ -0,0 +1,16 @@
+const toxy = require('..')
+
+const proxy = toxy()
+const rules = proxy.rules
+const poisons = proxy.poisons
+
+proxy
+  .forward('http://httpbin.org')
+  .poison(poisons.rateLimit({ limit: 2, threshold: 5000 }))
+  .withRule(rules.method('GET'))
+  .withRule(rules.probability(90))
+
+proxy.all('/*')
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)

examples/routes.js

@@ -0,0 +1,32 @@
+const toxy = require('..')
+const poisons = toxy.poisons
+const rules = toxy.rules
+
+const proxy = toxy()
+
+proxy
+  .forward('http://httpbin.org')
+  .poison(poisons.latency(1000))
+  .rule(rules.method('GET'))
+
+proxy
+  .get('/ip')
+  .poison(poisons.rateLimit({ limit: 1, threshold: 5000 }))
+
+proxy
+  .get('/get')
+  .poison(poisons.abort())
+
+proxy
+  .get('/image/*')
+  .poison(poisons.bandwidth({ bps: 1024 }))
+
+proxy
+  .post('/post')
+  .poison(poisons.slowRead({ bps: 1024 }))
+
+proxy
+  .all('/*')
+
+proxy.listen(3000)
+console.log('Server listening on port:', 3000)