Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/h2non/rocky
Full-featured, middleware-oriented, programmatic HTTP and WebSocket proxy for node.js (deprecated)
https://github.com/h2non/rocky
balancer forward forward-proxy gateway http-proxy microservice middleware proxy replay replay-requests
Last synced: 7 days ago
JSON representation
Full-featured, middleware-oriented, programmatic HTTP and WebSocket proxy for node.js (deprecated)
- Host: GitHub
- URL: https://github.com/h2non/rocky
- Owner: h2non
- License: mit
- Archived: true
- Created: 2015-06-19T12:28:47.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-04-21T13:41:24.000Z (over 3 years ago)
- Last Synced: 2024-05-09T23:53:27.803Z (6 months ago)
- Topics: balancer, forward, forward-proxy, gateway, http-proxy, microservice, middleware, proxy, replay, replay-requests
- Language: JavaScript
- Homepage:
- Size: 496 KB
- Stars: 371
- Watchers: 10
- Forks: 28
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list-microservice - rocky - featured, middleware-oriented, programmatic HTTP and WebSocket proxy for node.js (proxy)
README
# rocky [](https://travis-ci.org/h2non/rocky) [](https://codeclimate.com/github/h2non/rocky) [](https://www.npmjs.org/package/rocky) [](http://standardjs.com) [](http://jsdocs.herokuapp.com/github.com/h2non/rocky)
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](#features).
Built for [node.js](http://nodejs.org)/[io.js](https://iojs.org).
**rocky** can be fluently used [programmatically](#programmatic-api) or via [command-line](#command-line) interface.
It's framework agnostic, but you can optionally plug in with [connect](https://github.com/senchalabs/connect)/[express](http://expressjs.com) apps.
To get started, take a look to [how does it work](#how-does-it-work), [basic usage](#usage), [middleware layer](#middleware-layer) and [examples](/examples).
**Note**: `retry` feature is temporary not available in latest `node.js` versions.
## Contents
- [Features](#features)
- [When rocky can be useful?](#when-rocky-can-be-useful)
- [Installation](#installation)
- [Benchmark](#benchmark)
- [About](#about)
- [Versions](#versions)
- [How does it work?](#how-does-it-work)
- [Projects using rocky](#projects-using-rocky)
- [Middleware layer](#middleware-layer)
- [Hierarchies](#hierarchies)
- [Types of middleware](#types-of-middleware)
- [Middleware flow](#middleware-flow)
- [Middleware API](#middleware-api)
- [Third-party middleware](#third-party-middleware)
- [Command-line](#command-line)
- [Installation](#installation-1)
- [Usage](#usage)
- [Examples](#examples)
- [Configuration file](#configuration-file)
- [Programmatic API](#programmatic-api)
- [Usage](#usage)
- [Configuration](#configuration)
- [Documentation](#rocky-options-)
- [Supported events](#events)
- [Special thanks](#special-thanks)
## Features
- Full-featured HTTP/S proxy (backed by [http-proxy](https://github.com/nodejitsu/node-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](#programmatic-api)
- Provides a [command-line interface](https://github.com/h2non/rocky-cli) with declarative [configuration file](#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](http://microservices.io/patterns/apigateway.html)
- 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](https://github.com/h2non/toxy))
- As intermediate test server intercepting and generating random/fake responses
- And whatever a programmatic HTTP proxy can be useful to
## Installation
```bash
npm install rocky --save
```
## Benchmark
See [benchmark/README.md](https://github.com/h2non/rocky/tree/master/benchmark#results) for detailed benchmark results.
## About
### Versions
- [**0.1.x**](https://github.com/h2non/rocky/tree/v0.1.x) - First version. Initially released at `25.06.2015`. Beta
- [**0.2.x**](https://github.com/h2non/rocky/tree/v0.2.x) - Released at `07.07.2015`. Major features and stability improvements.
- [**0.3.x**](https://github.com/h2non/rocky/tree/v0.3.x) - Released at `24.07.2015`. Production-focused version.
- [**0.4.x**](https://github.com/h2non/rocky/tree/master) - 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](https://github.com/h2non/toxy) - Hackable HTTP proxy to simulate server failures and network conditions.
- [balboa](https://github.com/h2non/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](https://github.com/h2non/rocky/blob/master/examples/express.js) 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)
↓ ------------------- ↓
```
### Middleware API
Middleware layer behaves and has the same interface as connect/express.
In other words, you can create or use middleware as you already know with the typical notation `function(req, res, next)`
As a kind of inversion of control, `rocky` exposes a tiny API in every `http.ClientRequest` passed via the middleware layer:
##### Request
- **req.rocky** `object`
- **.options** `object` - Exposes the [configuration](#configuration) options for the current request.
- **.proxy** `Rocky` - Exposes the rocky instance. Use only for hacking purposes!
- **.route** `Route` - Exposes the current running route. Only available in `route` type middleware
- **req.stopReplay** `boolean` - Optional field internally checked by `rocky` to stop the request replay process.
##### Response
- **res.rocky** `object`
- **.options** `object` - Exposes the [configuration](#configuration) options for the current request.
- **.proxy** `Rocky` - Exposes the rocky instance. Use only for hacking purposes!
- **.route** `Route` - Exposes the current running route. Only available in `route` type middleware
Example replacing the target server URL:
```js
rocky()
.get('/users/:name')
.forward('http://old.server.net')
.use(function (req, res, next) {
if (req.params.name === 'admin') {
// Overwrite the target URL only for this user
req.rocky.options.target = 'http://new.server.net'
}
next()
})
```
### Third-party middleware
- [**consul**](https://github.com/h2non/rocky-consul) - Dynamic service discovery and balancing using Consul
- [**vhost**](https://github.com/h2non/rocky-vhost) - vhost based proxy routing for rocky
- [**version**](https://github.com/h2non/rocky-version) - HTTP API version based routing (uses [http-version](https://github.com/h2non/http-version))
Note that you can use any other existent middleware plug in `rocky` as part of your connect/express app.
Additionally, `rocky` provides some [built-in middleware functions](#rockymiddleware-1) that you can plug in different types of middleware.
## Command-line
### Installation
For command-line usage, you must install [`rocky-cli`](https://github.com/h2non/rocky-cli)
```
npm install -g rocky-cli
```
### Usage
```bash
Start rocky HTTP proxy server
Usage: rocky [options]
Options:
--help, -h Show help [boolean]
--config, -c File path to TOML config file
--port, -p rocky HTTP server port
--forward, -f Default forward server URL
--replay, -r Define a replay server URL
--route, -t Define one or multiple routes, separated by commas
--key, -k Path to SSL key file
--cert, -e Path to SSL certificate file
--secure, -s Enable SSL certification validation
--balance, -b Define server URLs to balance between, separated by commas
--mute, -m Disable HTTP traffic log in stdout [boolean]
--debug, -d Enable debug mode [boolean]
-v, --version Show version number [boolean]
Examples:
rocky -c rocky.toml \
-f http://127.0.0.1:9000 \
-r http://127.0.0.1
```
#### Examples
Passing the config file:
```
rocky --config rocky.toml --port 8080
```
Reading config from `stdin`:
```
cat rocky.toml | rocky --port 8080
```
Transparent `rocky.toml` file discovery in current and higher directories:
```
rocky --port 8080
```
Alternatively `rocky` can find the config file passing the `ROCKY_CONFIG` environment variable:
```
ROCKY_CONFIG=path/to/rocky.toml rocky --port 8080
```
Or for simple configurations you can setup a proxy without a config file, defining the routes via flag:
```
rocky --port --forward http://server --route "/download/*, /images/*, /*"
```
### Configuration file
Default configuration file name: `rocky.toml`
The configuration file must be declared in [TOML](https://github.com/toml-lang/toml) language
```toml
port = 8080
forward = "http://google.com"
replay = ["http://duckduckgo.com"]
[ssl]
cert = "server.crt"
key = "server.key"
["/users/:id"]
method = "all"
forward = "http://new.server"
["/oauth"]
method = "all"
forward = "http://auth.server"
["/*"]
method = "GET"
forward = "http://old.server"
["/download/:file"]
method = "GET"
timeout = 5000
balance = ["http://1.file.server", "http://2.file.server"]
["/photo/:name"]
method = "GET"
replayAfterForward = true
[[replay]]
target = "http://old.server"
forwardHost = true
[[replay]]
target = "http://backup.server"
```
## Programmatic API
### Usage
Example using [Express](http://expressjs.com)
```js
var rocky = require('rocky')
var express = require('express')
// Set up the express server
var app = express()
// Set up the rocky proxy
var proxy = rocky()
// Default proxy config
proxy
.forward('http://new.server')
.replay('http://old.server')
.replay('http://log.server')
.options({ forwardHost: true })
// Configure the routes to forward/replay
proxy
.get('/users/:id')
proxy
.get('/download/:file')
.balance(['http://1.file.server', 'http://2.file.server'])
// Plug in the rocky middleware
app.use(proxy.middleware())
// Old route (won't be called since it will be intercepted by rocky)
app.get('/users/:id', function () { /* ... */ })
app.listen(3000)
```
Example using the built-in HTTP server
```js
var rocky = require('rocky')
var proxy = rocky()
// Default proxy config
proxy
.forward('http://new.server')
.replay('http://old.server', { replayOriginalBody: true })
.options({ forwardHost: true })
.on('proxy:error', function (err) {
console.error('Error:', err)
})
.on('proxyReq', function (proxyReq, req, res, opts) {
console.log('Proxy request:', req.url, 'to', opts.target)
})
.on('proxyRes', function (proxyRes, req, res) {
console.log('Proxy response:', req.url, 'with status', res.statusCode)
})
// Configure the routes to forward/replay
proxy
.get('/users/:id')
// Overwrite the path
.toPath('/profile/:id', { id: '0123' })
// Add custom headers
.headers({
'Authorization': 'Bearer 0123456789'
})
proxy
.get('/search')
// Overwrite the forward URL for this route
.forward('http://another.server')
// Use a custom middleware for validation purposes
.use(function (req, res, next) {
if (req.headers['Authorization'] !== 'Bearer 012345678') {
res.statusCode = 401
return res.end()
}
next()
})
// Intercept and transform the response body before sending it to the client
.transformResponseBody(function (req, res, next) {
// Get the body buffer and parse it (assuming it's a JSON)
var body = JSON.parse(res.body.toString())
// Compose the new body
var newBody = JSON.stringify({ salutation: 'hello ' + body.hello })
// Send the new body in the request
next(null, newBody)
})
proxy.listen(3000)
```
For more usage cases, take a look to the [examples](/examples)
### Configuration
**Supported configuration params**:
- **forward** `string` - Default forward URL
- **debug** `boolean` - Enable debug mode. Default `false`
- **target** `string` - ` - Optional replay server URLs. You can use the `replay()` method to configure it
- **ws** `boolean` - Enable WebSocket proxy mode.
- **balance** `array` - Define the URLs to balance. Via API you should use the `balance()` method
- **timeout** `number` - Timeout for request socket
- **proxyTimeout** `number` - Timeout for proxy request socket
- **retry** `object` - Enable retry/backoff logic for forward/replay traffic. See [allowed params](https://github.com/tim-kos/node-retry#retrytimeoutsoptions). Default: `null`
- **replayRetry** `object` - Enable retry logic for replay traffic with custom options. Default: `null`
- **agent** `object` - object to be passed to http(s).request. See node.js [`https`](https://nodejs.org/api/https.html#https_class_https_agent) docs
- **ssl** `object` - object to be passed to https.createServer()
- **cert** `string` - Path to SSL certificate file
- **key** `string` - Path to SSL key file
- **ws** `boolean` - true/false, if you want to proxy websockets
- **xfwd** `boolean` - true/false, adds x-forward headers
- **secure** `boolean` - true/false, verify SSL certificate
- **toProxy** `boolean` - true/false, explicitly specify if we are proxying to another proxy
- **prependPath** `boolean` - true/false, Default: true - specify whether you want to prepend the target's path to the proxy path
- **ignorePath** `boolean` - true/false, Default: false - specify whether you want to ignore the proxy path of the incoming request
- **localAddress** `boolean` -