Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt

Use this file to discover all available pages before exploring further.

RammerheadProxy extends testcafe-hammerhead’s Proxy class and is the central component of every Rammerhead deployment. It handles HTTP and WebSocket routing, manages request and upgrade pipelines, rewrites server response headers, and integrates with a session store. You create exactly one instance per process and pair it with a session store via attachToProxy.
You should not call openSession() directly on RammerheadProxy. Use a session store class (such as RammerheadSessionFileCache or RammerheadSessionMemoryStore) and call attachToProxy instead.

​
Constructor

const proxy = new RammerheadProxy(options);
The constructor starts the HTTP server immediately. There is no separate start() call.
​
logger
RammerheadLogging
default:"new RammerheadLogging({ logLevel: 'disabled' })"
Logger instance used for request traffic and internal debug messages. Defaults to a silent logger.
​
loggerGetIP
(req) => string
default:"(req) => req.socket.remoteAddress"
Function that extracts the client IP address from an incoming request. Override this when Rammerhead runs behind a reverse proxy that forwards the real IP in a header such as X-Forwarded-For.
​
bindingAddress
string
default:"\"127.0.0.1\""
Hostname or IP address the HTTP server binds to.
​
port
number
default:"8080"
Port for the primary proxy server to listen on.
​
crossDomainPort
number | null
default:"8081"
Port used to simulate cross-origin requests. Sites that inspect the Origin header require this. Set to null to disable cross-domain simulation and run a single server port, but be aware that some sites will break.
​
dontListen
boolean
default:"false"
When true, the HTTP server is created but listen() is never called. Use this when integrating with a sticky-session cluster library that manages binding externally.
​
ssl
http.ServerOptions | null
default:"null"
TLS/SSL options passed directly to Node’s https.createServer. Set to null to use plain HTTP. Provide an object with key and cert (or pfx) to enable HTTPS.
​
getServerInfo
(req) => RammerheadServerInfo
Function that returns the server info object hammerhead uses when rewriting URLs. The default implementation reads req.headers.host and detects TLS from the socket. Override this in a reverse-proxy setup where the public hostname, port, or protocol differ from what Node sees.
​
disableLocalStorageSync
boolean
default:"false"
When true, the /syncLocalStorage route returns 404 and localStorage data is never persisted to the session. Useful if you do not need cross-device localStorage sync and want to reduce server load.
​
jsCache
RammerheadJSAbstractCache
default:"new RammerheadJSMemCache(50 * 1024 * 1024)"
Cache instance used to store rewritten JavaScript. Defaults to a 50 MB in-memory LRU cache. Swap in RammerheadJSFileCache for disk-backed caching that survives restarts and can be shared across cluster workers.
​
disableHttp2
boolean
default:"false"
When true, all sessions created by this proxy disable HTTP/2 on their outgoing connections. This is set globally via global.rhDisableHttp2 so it applies to every RammerheadSession created after the proxy starts.

​
Properties

​
rewriteServerHeaders

proxy.rewriteServerHeaders
A plain object whose keys are response header names (lowercase) and whose values are transformer functions. Before writing each response, the proxy calls the matching transformer with the current header value. Returning undefined removes the header; returning a string replaces it. The default transformers:
HeaderEffect
permissions-policyReplaces sync-xhr with sync-yes so synchronous XHR is not blocked
feature-policySame replacement as permissions-policy
referrer-policyAlways set to no-referrer-when-downgrade
report-toRemoved (avoids leaking proxy endpoint to report collectors)
cross-origin-embedder-policyRemoved (allows embedding cross-origin resources)
You can add, remove, or override entries at runtime: 
// Remove the Content-Security-Policy header from all responses
proxy.rewriteServerHeaders['content-security-policy'] = () => undefined;

// Override referrer policy
proxy.rewriteServerHeaders['referrer-policy'] = () => 'no-referrer';

​
Methods

​
GET

proxy.GET(route, handler)
Registers an HTTP GET route on the proxy server.
​
route
string
required
URL path to match, e.g. '/my-endpoint'.
​
handler
StaticContent | (req, res) => void
required
Either a static content object { content: Buffer, contentType: string } or a request handler function.

​
POST

proxy.POST(route, handler)
Registers an HTTP POST route on the proxy server.
​
route
string
required
URL path to match.
​
handler
StaticContent | (req, res) => void
required
Either a static content object or a request handler function.

​
WS

proxy.WS(route, handler, websocketOptions?)
Registers a WebSocket route. Rammerhead handles the upgrade internally and passes the established WebSocket connection to your handler.
​
route
string | RegExp
required
Path or pattern to match. String routes use exact matching; RegExp routes use .test().
​
handler
(ws: WebSocket, req: IncomingMessage) => void
required
Called once the WebSocket handshake completes. ws is the client connection.
​
websocketOptions
object
default:"{}"
Options forwarded to new WebSocket.Server(...). noServer: true is always applied automatically.
​
returns
WebSocket.Server
The underlying ws server instance for the route.
Throws TypeError if a route with the same path is already registered.

​
unregisterWS

proxy.unregisterWS(route)
Removes a previously registered WebSocket route.
​
route
string | RegExp
required
The same route value passed to WS().
Throws TypeError if the route does not exist.

​
getWSRoute

proxy.getWSRoute(path, doDelete?)
Looks up a registered WebSocket route by path string.
​
path
string
required
URL path to look up.
​
doDelete
boolean
default:"false"
When true, the matched route is removed from the registry after being returned.
​
returns
{ route, handler, wsServer } | null
The route descriptor, or null if no match is found.

​
addToOnRequestPipeline

proxy.addToOnRequestPipeline(onRequest, beginning?)
Adds a handler to the request pipeline. Handlers run in order for every HTTP request (and for WebSocket upgrade requests that hammerhead re-routes through _onRequest). Return true from a handler to stop processing and prevent the request from reaching hammerhead.
​
onRequest
async (req, res, serverInfo, isRoute, isWebsocket) => boolean | void
required
Handler function. Receives:
  • req — http.IncomingMessage
  • res — http.ServerResponse (or stream.Duplex for WebSocket upgrades)
  • serverInfo — ServerInfo computed by getServerInfo
  • isRoute — true if the path matches a registered GET/POST/WS route
  • isWebsocket — true if the request is a WebSocket upgrade
​
beginning
boolean
default:"false"
When true, the handler is prepended to the pipeline so it runs before existing handlers. When false (default), it is appended.
The beginning parameter has inverted semantics in the source: passing true calls push (appends to the end), while passing false (the default) calls unshift (prepends to the front). This means handlers added with beginning: false (the default) actually execute first, and handlers added with beginning: true execute last. Verify the order of your pipeline handlers against this behavior.

​
addToOnUpgradePipeline

proxy.addToOnUpgradePipeline(onUpgrade, beginning?)
Adds a handler to the WebSocket upgrade pipeline. This is the only way to intercept the raw head buffer during a WebSocket upgrade, since hammerhead does not forward it through _onRequest.
​
onUpgrade
async (req, socket, head, serverInfo, isRoute) => boolean | void
required
Handler function. Receives:
  • req — http.IncomingMessage
  • socket — stream.Duplex
  • head — Buffer with any data received after the upgrade headers
  • serverInfo — ServerInfo
  • isRoute — true if the path matches a registered route
​
beginning
boolean
default:"false"
Same prepend/append semantics as addToOnRequestPipeline.

​
checkIsRoute

proxy.checkIsRoute(req)
Returns true if the request matches any registered GET, POST, or WS route.
​
req
http.IncomingMessage | RegExp
required
When passed an IncomingMessage, matches against HTTP routes and WebSocket routes by URL path. When passed a RegExp, checks WebSocket routes only.
​
returns
boolean
true if any matching route is found.

​
close

proxy.close()
Shuts down the proxy server and closes the session store. Calls the parent Proxy.close() and then proxy.openSessions.close().

​
Complete example

const {
  RammerheadProxy,
  RammerheadSessionFileCache,
  RammerheadLogging,
  RammerheadJSFileCache
} = require('rammerhead');

const logger = new RammerheadLogging({ logLevel: 'info' });

const proxy = new RammerheadProxy({
  port: 8080,
  crossDomainPort: 8081,
  bindingAddress: '0.0.0.0',
  logger,
  loggerGetIP: (req) => req.headers['x-forwarded-for'] || req.socket.remoteAddress,
  jsCache: new RammerheadJSFileCache('./js-cache', 200 * 1024 * 1024, 10000, false),
  ssl: null
});

// Add a custom response header
proxy.rewriteServerHeaders['x-proxied-by'] = () => 'rammerhead';

// Attach a session store
const store = new RammerheadSessionFileCache({ saveDirectory: './sessions', logger });
store.attachToProxy(proxy);

// Register a health-check endpoint
proxy.GET('/health', (req, res) => {
  res.end('ok');
});

// Register a WebSocket echo route
proxy.WS('/echo', (ws) => {
  ws.on('message', (msg) => ws.send(msg));
});

Build docs developers (and LLMs) love

Get started for freeTalk to us