rocky

<img align="right" height="160" src="http://s22.postimg.org/f0jmde7o1/rocky.jpg" />

A multipurpose, full-featured, middleware-oriented and hackable HTTP/S and WebSocket proxy with powerful built-in features such as versatile routing layer, traffic interceptor and replay to multiple backends, built-in balancer, traffic retry/backoff logic, hierarchical configuration, among others. Built for node.js/io.js.

rocky can be fluently used programmatically or via command-line interface. It's framework agnostic, but you can optionally plug in with connect/express apps.

To get started, take a look to how does it work, basic usage, middleware layer and examples.

Note: retry feature is temporary not available in latest node.js versions.

Contents

• Features
• When rocky can be useful?
• Installation
• Benchmark
• About
  • Versions
  • How does it work?
  • Projects using rocky
• Middleware layer
  • Hierarchies
  • Types of middleware
  • Middleware flow
  • Middleware API
  • Third-party middleware
• Command-line
  • Installation
  • Usage
  • Examples
  • Configuration file
• Programmatic API
  • Usage
  • Configuration
  • Documentation
  • Supported events
• Special thanks

Features

• Full-featured HTTP/S proxy (backed by http-proxy)
• Supports WebSocket protocol proxy (replay not supported yet)
• Able to replay traffic to multiple backends (concurrently or sequentially)
• Able to intercept HTTP requests and responses and modify them on-the-fly
• Featured built-in path based router with params matching
• Built-in load balancer
• Built-in HTTP traffic retry/backoff
• Nested configuration per global/route scopes and forward/replay phases
• Hierarchical middleware layer supporting different HTTP traffic flow phases
• Easily integrable with connect/express via middleware
• Able to run as standalone HTTP/S server (no connect/express, uses http module)
• Compatible with most of the existent connect/express middleware
• Powerful programmatic control supporting dynamic configurations and zero-downtime
• Supports both concurrent and sequential HTTP traffic flow modes
• Small hackable core designed for extensibility
• Fluent, elegant and evented programmatic API
• Provides a command-line interface with declarative configuration file
• Handles properly gzip responses, especially when intercepting payloads

When rocky can be useful?

• As intermediate proxy for service migrations (e.g: APIs)
• Replaying traffic to one or multiple backends
• As reverse proxy to forward traffic to one o multiple servers.
• As Man-in-the-Middle proxy intercepting and transforming the request/response on-the-fly
• As intermediate HTTP proxy adapter for external services integrations
• As HTTP API gateway
• As standard reverse HTTP proxy with dynamic routing
• As security proxy layer
• As dynamic HTTP load balancer with programmatic control
• As embedded HTTP proxy in your node.js app
• As HTTP cache or log server
• As SSL terminator proxy
• As HTTP proxy for performance testing
• As traditional forward HTTP proxy (e.g: Squid)
• For HTTP session manipulation and debugging
• For HTTP traffic recording and inspection
• For A/B testing
• For fuzz testing (see toxy)
• As intermediate test server intercepting and generating random/fake responses
• And whatever a programmatic HTTP proxy can be useful to

Installation

npm install rocky --save

Benchmark

See benchmark/README.md for detailed benchmark results.

About

Versions

• 0.1.x - First version. Initially released at 25.06.2015. Beta
• 0.2.x - Released at 07.07.2015. Major features and stability improvements.
• 0.3.x - Released at 24.07.2015. Production-focused version.
• 0.4.x - Released at 02.10.2015. Introduces WebSocket support and other minor features. Stable & actively maintained. Recommended version.

How does it work?

         |==============|
         | HTTP clients |
         |==============|
               ||||
         |==============|
         |  HTTP proxy  |   ->  Via the built-in HTTP server or via connect/express
         |~~~~~~~~~~~~~~|
         | Rocky Router |   ->  The built-in featured router matches the proper route
         |~~~~~~~~~~~~~~|
         |  Middleware  |   ->  Dispatch the hierarchical middleware layer
         |==============|
            ||      |
  (duplex) //        \ (one-way)
         //            \
   /----------\   /----------\    /----------\
   |  target  |   | replay 1 | -> | replay 2 | (*N)
   \----------/   \----------/    \----------/

Projects using rocky

• toxy - Hackable HTTP proxy to simulate server failures and network conditions.
• balboa - Simple, hackable HTTP forward proxy.

Open an issue or send a PR to add your project!

Middleware layer

One of the most powerful features in rocky is its build-in domain specific middleware, based on connect/express middleware.

The middleware layer provides a simple and consistent way to augment the proxy functionality very easily, allowing you to attach third-party middleware (also known as plugins) to cover specific tasks which acts between different phases of the proxy, for instance handling incoming/outgoing traffic.

rocky middleware layer has the same interface as connect/express middleware, and it's mostly compatible with existent middleware (see express example).

Hierarchies

rocky supports multiple middleware hierarchies:

• global - Dispatched on every incoming request matched by the router
• route - Dispatched only at route scope

Types of middleware

rocky introduces multiple types of middleware layers based on the same interface and behavior of connect/express middleware. This was introduced in order to achieve in a more responsive way multiple traffic flows in the specific scope and behavior nature of a programmatic HTTP proxy with traffic replay.

Those flows are intrinsically correlated but might be handled in a completely different way. The goal is to allowing you to handle them accordingly, acting in the middle of those phases to augment some functionality or react to some event with better accuracy.

Supported types of middleware:

router

• Scope: global
• Description: Dispatched on every matched route.
• Notation: .use([path], function (req, res, next))

forward

• Scope: global, route
• Description: Dispatched before forwarding an incoming request.
• Notation: .useForward(function (req, res, next))

replay

• Scope: global, route
• Description: Dispatched before starting each replay request.
• Notation: .useReplay(function (req, res, next))

response

• Scope: global, route
• Description: Dispatched on server response. Only applicable in forward traffic.
• Notation: .useResponse(function (req, res, next))

param

• Scope: global
• Description: Dispatched on every matched param on any route.
• Notation: .useParam(function (req, res, next))

Middleware flow

Middleware functions are always executed in FIFO order. The following diagram represents the internal incoming request flow and how the different middleware layers are involved on it:

↓    ( Incoming request )   ↓
↓            |||            ↓
↓      ----------------     ↓
↓      |    Router    |     ↓ --> Match a route, dispatching its middleware if required
↓      ----------------     ↓
↓            |||            ↓
↓   ---------------------   ↓
↓   | Global middleware |   ↓ --> Dispatch on every incoming request (router, param)
↓   ---------------------   ↓
↓            |||            ↓
↓           /   \           ↓
↓         /       \         ↓
↓       /           \       ↓
↓ [ Forward ]    [ Replay ] ↓ --> Dispatch both middleware in separated flows (route forward and replay)
↓      \             /      ↓
↓       \           /       ↓
↓        \         /        ↓
↓    -------------------    ↓
↓    | HTTP dispatcher |    ↓ --> Send requests over the network (concurrently or sequentially)
↓    -------------------    ↓