Rocky

0.4.16 verified Sat Apr 25 auth: no javascript maintenance

A full-featured, middleware-oriented HTTP/S and WebSocket proxy with traffic replay, load balancing, routing, and retry/backoff. Current stable version is 0.4.16, last updated July 2020. It is built on top of http-proxy and supports both command-line and programmatic usage. Key differentiators include a hierarchical middleware layer, path-based routing with params, concurrent/sequential traffic replay, and connectivity with Connect/Express middleware. Compared to alternatives like http-proxy or http-mitm-proxy, Rocky provides a higher-level abstraction with built-in balancer and retry logic. The project is in maintenance mode; no major releases since 2020.

Common errors

error TypeError: rocky is not a function ↓

cause Using import instead of require with CommonJS module.

fix

Change to const rocky = require('rocky')

error Error: EADDRINUSE :::3000 ↓

cause Port already in use by another process.

fix

Kill the process using the port or choose a different port.

error rocky().target is not a function ↓

cause Forgot to call rocky() to create an instance; using module directly.

fix

Create an instance: const proxy = require('rocky')()

Warnings

deprecated retry feature is temporarily not available in latest Node.js versions (see README note). ↓

fix Disable retry or avoid using retry options; consider implementing retry manually.

gotcha The default export is a function that creates a new proxy instance; not a class constructor. ↓

fix Use const proxy = require('rocky')() to create an instance.

gotcha Middleware must call next() or the request hangs. Rocky does not automatically call next(). ↓

fix Ensure every middleware function ends with await next() or next() (if not async).

breaking In version 0.3.x, the proxy was created via new Rocky(), but in 0.4.x it changed to factory function. ↓

fix Use rocky() instead of new rocky()

gotcha WebSocket proxy does not support replay to multiple backends. ↓

fix Use forward only for WebSocket; replay not available.

Install

npm install rocky

yarn add rocky

pnpm add rocky

Imports

rocky
wrong
```
import rocky from 'rocky'
```
correct
```
const rocky = require('rocky')
```
CommonJS only; no ESM support. The default export is the factory function.
rocky.balancer
```
const balancer = require('rocky').balancer
```
Balancer is exposed as a property on the rocky object.

RockyMiddleware

wrong

proxy.use(middleware) without calling next()

correct

const Rocky = require('rocky'); const proxy = Rocky(); proxy.use((req, res, next) => next())

Middleware signature is (req, res, next) similar to Express; must call next() to continue.

Quickstart

Sets up a simple HTTP proxy that forwards all traffic to httpbin.org, with middleware hooks for forward and replay phases.

const rocky = require('rocky');
const proxy = rocky();

// Forward all traffic to httpbin
proxy
  .target('http://httpbin.org')
  .forward(async (req, res, next) => {
    console.log('Forward request:', req.url);
    await next();
  })
  .replay(async (req, res, next) => {
    console.log('Replay response:', res.statusCode);
    await next();
  });

proxy.listen(3000, () => {
  console.log('Rocky proxy listening on port 3000');
});

// Test: curl -x http://localhost:3000 http://httpbin.org/get