Pluggable, full featured and middleware-oriented HTTP/S proxy with versatile routing layer, traffic interceptor and replay to multiple backends, built-in balancer, hierarchical configuration and more. Built for node.js/io.js. Compatible with connect/express.

rocky can be fluently used programmatically or via command-line interface.

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

Requires node.js +0.12 or io.js +1.6

• Features
• When rocky could be useful?
• Installation
  • Standalone binaries
• Introduction
  • Motivation
  • Design
  • Stability
  • Versions
  • How does it work?
• Middleware layer
  • Hierarchies
  • Types of middleware
  • Middleware flow
  • Middleware API
  • Third-party middleware
• Command-line
  • Examples
  • Configuration
  • Configuration file
• Programmatic API
  • Usage
  • Documentation
  • Supported events
• Special thanks

• Full-featured HTTP/S proxy (backed by http-proxy)
• Replay traffic to multiple backends (concurrently or sequentially)
• Intercept HTTP requests and responses and modify them on the fly
• Easily integrable with connect/express via middleware
• Full-featured built-in router with params matching
• Built-in load balancer
• Nested configuration per global/route and forward/replay phases
• Hierarchial middleware layer (based on connect-style middleware)
• Able to run as standalone HTTP/S server
• Compatible with most of the existing connect/express middleware
• Versatible programmatic control for dynamic configurations with zero-downtime
• Fluent, elegant and evented programmatic API
• Simple command-line interface with declarative configuration file

• As HTTP proxy for service migrations (e.g: APIs)
• Replaying traffic to one or multiple backends
• As reverse proxy to forward traffic to a specified server.
• As HTTP traffic interceptor 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 HTTP load balancer with full programmatic control
• As embedded HTTP proxy in your node.js app
• As static response HTTP server
• As HTTP cache or log server
• As SSL terminator proxy
• For A/B testing
• As intermediate test server intercepting and generating random/fake responses
• And whatever a programmatic HTTP proxy can be useful to

npm install rocky --save

For command-line interface usage, install it as global package:

npm install -g rocky

• linux-x64
• darwin-x64

Packaged using nar. Shipped with node.js 0.12.7

chmod +x rocky-0.2.1-linux-x64.nar

./rocky-0.2.1-linux-x64.nar exec --port 3000 --config rocky.toml

Migrating systems if not a trivial thing, and it's even more complex if we're talking about production systems that require high availability. Taking care of consistency and public interface contract should be a premise in most cases.

rocky was initially created to become an useful tool for assisting during a backend migration strategy, however it could be useful for many other scenarios.

rocky design is driven by keeping versatility and extensibility in mind. The main goal is to remain it with a small core and codebase, hosting just the proper responsability and necessary built-in features, and making more efforts providing ways for extensibility. That level extensibility can be covered via its middleware layer, which is the core and more powerful feature of rocky.

The relevant difference between the middleware layer and a common event bus (which is very common in asynchronous programming) is the control flow capability. Via the middleware you can completely rely on a consistent control flow when performing some actiong with the HTTP traffic flow, continuing or stoping it accordingly. This approach allows you to plug in intermediate jobs with custom logic beetwen different stages of the HTTP flow live cycle.

rocky is relative young but production focused package. Version 0.1.x was wrote during my free time in less than 10 days (mostly at night during the weekend), therefore it could be considered in beta stage.

Version 0.2.x introduced significant improvements such as a more consistent API and a new hierarchical middleware layer. This version is focused on stability and production use, however it's only recommended to use it in non-hostile environments for now.

• 0.1.x - First version. Initially released at 25.06.2015. Beta
• 0.2.x - Released at 07.07.2015. Production-focused version.

rocky can be useful in multiple scenarios, but a common and representative use case scenario could be the following:

         |==============|
         | The Internet |
         |==============|
               ||||
         |==============|
         |  HTTP proxy  |
         |~~~~~~~~~~~~~~|
         | Rocky Router |
         |~~~~~~~~~~~~~~|
         |  Middleware  |
         |==============|
            ||      |
  (duplex) //        \ (one-way)
          //          \
         //            \
   /----------\   /----------\    /----------\
   |  target  |   | replay 1 | -> | replay 2 | (*N)
   \----------/   \----------/    \----------/

One of the more powerful features in rocky is its build-in middleware layer. rocky was designed with a main core idea: augment by default.

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).

rocky supports multiple middleware hierarchies:

• global - Dispached on every incoming request matched by the router
• route - Dispached only per route scope

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 intrinsicly 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:

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

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

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

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

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 (Global)
↓    ---------------------  ↓
↓            |||            ↓
↓           /   \           ↓
↓         /       \         ↓
↓       /           \       ↓
↓ [ Forward ]    [ Replay ] ↓ --> Dispatch both middleware in separated flows (Global, Route)
↓      \             /      ↓
↓       \           /       ↓
↓        \         /        ↓
↓    -------------------    ↓
↓    | HTTP dispatcher |    ↓ --> Send requests over the network (concurrently or sequentially)
↓    -------------------    ↓

Middleware behavior and interface are the same like connect/express, so you can create middleware as you already know with the notation function(req, res, next)

rocky exposes as a sort of inversion of control in every http.ClientRequest object the following fields:

• req.rocky object
  • .options object - Expose the configuration options for the current request.
  • .proxy Rocky - Expose the rocky instance. Use only for hacking purposes!
  • .route Route - Expose 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.

This provides you way to extend or modify specific values from the middleware layer without having side-effects, for instance replacing the server target URL, like in the following example:

rocky()
  .get('/users/:name')
  .forward('https://old.server.net')
  .use(function (req, res, next) {
    if (req.param.name === 'admin') {
      // Overwrite the target URL only for this user
      req.rocky.options.target = 'https://new.server.net'
    }
    next()
  })

• consul - Dynamic service discovery and balancing using Consul
• vhost - vhost based proxy routing for rocky
• version - HTTP API version based routing (uses 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 that you can plug in different types of middleware.

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 https://127.0.0.1:9000 \
  -r https://127.0.0.1

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 https://server --route "/download/*, /images/*, /*"

Supported params

• forward string - Default forward URL
• debug boolean - Enable debug mode. Default false
• target string - <url string to be parsed with the url module
• replay array<string|object> - Optional replay server URLs. You can use the replay() method to configure it
• balance array<url> - Define the URLs to balance. Via API you should use the balance() method
• replayAfterForward boolean - Replay the request only after the forward request ends successfully. Default false
• timeout number - Timeout for request socket
• proxyTimeout number - Timeout for proxy request socket
• agent object - object to be passed to http(s).request. See node.js https 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 - <Local interface string to bind for outgoing connections
• changeOrigin boolean - <true/false, Default: false - changes the origin of the host header to the target URL
• auth boolean - Basic authentication i.e. 'user:password' to compute an Authorization header.
• hostRewrite boolean - rewrites the location hostname on (301/302/307/308) redirects, Default: null.
• autoRewrite boolean - rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
• protocolRewrite boolean - rewrites the location protocol on (301/302/307/308) redirects to 'http' or 'https'. Default: null.
• forwardOriginalBody boolean - Only valid for forward request. Forward the original body instead of the transformed one.
• replayOriginalBody boolean - Only valid for replay request. Forward the original body instead of the transformed one.
• router object - Specific router params
  • strict boolean - When false trailing slashes are optional (default: false)
  • caseSensitive boolean - When true the routing will be case sensitive. (default: false)
  • mergeParams boolean - When true any req.params passed to the router will be merged into the router's req.params. (default: false)

Default configuration file name: rocky.toml

The configuration file must be declared in TOML language

port = 8080
forward = "https://google.com"
replay = ["https://duckduckgo.com"]
[ssl]
cert = "server.crt"
key  = "server.key"
[/users/:id]
method = "all"
forward = "https://new.server"
[/oauth]
method = "all"
forward = "https://auth.server"
[/*]
method = "GET"
forward = "https://old.server"
[/download/:file]
method = "GET"
timeout = 5000
balance = ["https://1.file.server", "https://2.file.server"]
[/photo/:name]
method = "GET"
replayAfterForward = true
[[replay]]
  target = "https://old.server"
  forwardHost = true
[[replay]]
  target = "https://backup.server"

Example using Express

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('https://new.server')
  .replay('https://old.server')
  .replay('https://log.server')
  .options({ forwardHost: true })
// Configure the routes to forward/replay
proxy
  .get('/users/:id')
proxy
  .get('/download/:file')
  .balance(['https://1.file.server', 'https://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

var rocky = require('rocky')
var proxy = rocky()
// Default proxy config
proxy
  .forward('https://new.server')
  .replay('https://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')
  // Add custom headers
  .headers({
    'Authorization': 'Bearer 0123456789'
  })
proxy
  .get('/search')
  // Overwrite the forward URL for this route
  .forward('https://another.server')
  // Use a custom middleware for validation purposes
  .use(function (req, res, next) {
    if (req.headers['Autorization'] !== '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 at the examples

Creates a new rocky instance with the given options.

You can pass any of the allowed params at configuration level and any supported http-proxy options

Aliases: target, forwardTo

Define a default target URL to forward the request

Alias: replayTo

Add a server URL to replay the incoming request

opts param provide specific replay options, overwritting the parent options.

Define/overwrite rocky server options. You can pass any of the supported options by http-proxy.

Use the given middleware to handle all http methods on the given path, defaulting to the root path.

Alias: param()

Maps the specified path parameter name to a specialized param-capturing middleware. The middleware stack is the same as .use().

Use a middleware for all the incoming traffic in the HTTP replay phase. This middleware stack can be useful to differ between forward/replay traffic, applying separated flows of middleware.

Use a middleware for all the incoming traffic only for the HTTP request forward phase. For most cases you will only use .use(), but for particular modifications only for the forwarded traffic, this middleware can be useful.

Use a custom middleware for a specific phase. Supported phase names are: forward, 'replay'.

This method is used internally, however it's also public since it could be useful for dynamic middleware configurations instead of using the shortcut methods such as: useReplay or useForward.

Define a set of URLs to balance between with a simple round-robin like scheduler.

Subscribe to a proxy event. See support events here

Remove an event by its handler function. See support events here

Remove an event by its handler function. See support events here

Remove all the subscribers to the given event. See support events here

Return: Function(req, res, next)

Return a connect/express compatible middleware

Raw HTTP request/response handler.

Starts a HTTP proxy server in the given port

Close the HTTP proxy server, if exists. Shortcut to rocky#server.close(cb)

Return: Route

Add a route handler for the given path for all HTTP methods

Return: Route

Configure a new route the given path with GET method

Return: Route

Configure a new route the given path with POST method

Return: Route

Configure a new route the given path with PUT method

Return: Route

Configure a new route the given path with DELETE method

Return: Route

Configure a new route the given path with PATCH method

Return: Route

Configure a new route the given path with HEAD method

Internal router instance

HTTP/HTTPS server instance. Only present if listen() was called starting the built-in server.

Aliases: target, forwardTo

Overwrite forward server for the current route.

Alias: replyTo

Overwrite replay servers for the current route.

opts param provide specific replay options, overwritting the parent options.

Define a set of URLs to balance between with a simple round-robin like scheduler. urls param must be an array of strings.

Shortcut method to intercept and reply the incoming request. If used, body param must be a string or buffer

Overwrite the request path, defining additional optional params.

Define or overwrite request headers for the current route.

Overwrite the Host header value when forward the request.

Redirect the incoming request for the current route.

Intercept and cache in a buffer the request payload data. Body will be exposed in req.body.

Note: use it only for small payloads

Alias: transformRequestBody()

This method implements a non-instrusive native http.IncommingMessage stream wrapper that allow you to intercept and transform the request body received from the client before sending it to the target server.

The middleware argument must a function which accepts the following arguments: function(req, res, next) The filter arguments is optional and it can be a string, regexp or function(req) which should return boolean if the request passes the filter. The default check value by string or regexp test is the Content-Type header.

In the middleware function must call the next function, which accepts the following arguments: err, newBody, encoding You can see an usage example here.

Caution: using this middleware could generate in some scenarios negative performance side-effects, since the whole payload data will be buffered in the heap until it's finished. Don't use it if you need to handle large payloads.

The body will be exposed as raw Buffer or String on both properties body and originalBody in http.ClientRequest:

rocky
  .post('/users')
  .transformRequest(function (req, res, next) {
    // Get the body buffer and parse it (assuming it's a JSON)
    var body = JSON.parse(req.body.toString())
    // Compose the new body
    var newBody = JSON.stringify({ salutation: 'hello ' + body.hello })
    // Set the new body
    next(null, newBody, 'utf8')
  }, function (req) {
    // Custom filter
    return /application\/json/i.test(req.headers['content-type'])
  })

Alias: transformResponseBody()

This method implements a non-instrusive native http.RequestResponse stream wrapper that allow you to intercept and transform the response body received from the target server before sending it to the client.

The middleware argument must a function which accepts the following arguments: function(req, res, next) The filter arguments is optional and it can be a string, regexp or function(res) which should return boolean if the request passes the filter. The default check value by string or regexp test is the Content-Type header.

In the middleware function must call the next function, which accepts the following arguments: err, newBody, encoding You can see an usage example here.

Caution: using this middleware could generate in some scenarios negative performance side-effects since the whole payload data will be buffered in the heap until it's finished. Don't use it if you need to handle large payloads.

The body will be exposed as raw Buffer or String on both properties body and originalBody in http.ClientResponse:

rocky
  .post('/users')
  .transformResponse(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 })
    // Set the new body
    next(null, newBody, 'utf8')
  }, function (res) {
    // Custom filter
    return /application\/json/i.test(res.getHeader('content-type'))
  })

Overwrite default proxy options for the current route. You can pass any supported option by http-proxy

Use a middleware for the incoming traffic for the current route for both replay/forward phases.

Use a middleware for current route incoming traffic in the HTTP replay phase. This middleware stack can be useful to differ between forward/replay traffic, applying separated flows of middleware.

Use a middleware for current route incoming traffic only for the HTTP request forward phase. For most cases you will only use .use(), but for particular modifications only for the forwarded traffic, this middleware can be useful.

This method is used internally, however it's also public since it could be useful for dynamic middleware configurations instead of using the shortcut methods such as: useReplay or useForward.

Subscribes to a specific event for the given route. Useful to incercept the status or modify the options on-the-fly

• proxyReq opts, proxyReq, req, res - Fired when the request forward starts
• proxyRes opts, proxyRes, req, res - Fired when the target server respond
• proxy:error err, req, res - Fired when the proxy request fails
• route:error err, req, res - Fired when cannot forward/replay the request or middleware error
• replay:start params, opts, req - Fired before a replay request starts
• replay:error opts, err, req, res - Fired when a replay request fails
• replay:end params, opts, req - Fired when a replay request ends
• replay:stop params, opts, req - Fired when a replay request process is stopped
• server:error err, req, res - Fired on server middleware error. Only available if running as standalone HTTP server
• route:missing req, res - Fired on missing route. Only available if running as standalone HTTP server

For more information about events, see the events fired by http-proxy

Subscribes to a specific event for the given route, and unsubscribes after dispatched

Remove an event by its handler function in the current route

Create a standalone rocky server with the given config options. See the supported config fields

var config = {
  'forward': 'https://google.com',
  '/search': {
    method: 'GET',
    forward: 'https://duckduckgo.com'
    replay: ['https://bing.com', 'https://yahoo.com']
  },
  '/users/:id': {
    method: 'all'
  },
  '/*': {
    method: 'all',
    forward: 'https://bing.com'
  }
}
rocky.create(config)

Expose the built-in internal middleware functions.

You can reuse them as standard middleware in diferent ways, like this:

rocky()
  .all('/*')
  .use(rocky.middleware.headers({
    'Authorization': 'Bearer 0123456789'
  }))
  .useReplay(rocky.middleware.host('replay.server.net'))

Intercept and optionally transform/replace the request body before forward it to the target server.

See rocky#transformRequestBody for more details.

Intercept and optionally transform/replace the response body from the server before send it to the client.

See rocky#transformResponseBody for more details.

Overrites the request URL path of the incoming request before forward/replay it.

Add/extend custom headers to the incoming request before forward/replay it.

Overwrite the Host header before forwarding/replaying the request. Useful for some scenarios (e.g Heroku).

Shortcut method to reply the intercepted request from the middleware, with optional headers and body data.

Shortcut method to redirect the current request.

Accessor for the http-proxy API

Current rocky package semver

• http-proxy package creators and maintainers
• router package creators and maintainers

MIT - Tomas Aparicio