Reverse HTTP Client

1.3.0 · abandoned · verified Wed Apr 22

reverse-http is a JavaScript client library designed to establish a reverse HTTP connection to a server that supports the Reverse HTTP (PTTH/1.0) draft specification. This unique protocol allows an outbound HTTP connection from a client to act as a server, receiving incoming HTTP requests from the remote endpoint. The library is currently at version 1.3.0 and explicitly requires a Node.js runtime of version 0.12 or higher. Given the extremely old engine requirement, it is effectively unmaintained for modern Node.js environments and does not follow a current release cadence. Its primary differentiator is its specific implementation of the niche PTTH/1.0 protocol, offering a way for clients behind restrictive firewalls or NATs to expose services.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use the CommonJS `require()` function in an ECMAScript Module (ESM) context in a modern Node.js project.

fix For ESM projects, use `import reverseHttp from 'reverse-http';`. If the file is part of a CommonJS module, ensure `type: 'module'` is not set in `package.json` or the file uses `.cjs` extension.
```
TypeError: reverseHttp is not a function
```
cause Incorrectly importing the CommonJS default export using named ESM import syntax (e.g., `import { reverseHttp } from 'reverse-http';`).

fix Use a default ESM import: `import reverseHttp from 'reverse-http';`. CommonJS modules export a single value that becomes the default export when imported via ESM.
```
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE (or similar SSL/TLS errors)
```
cause The very old Node.js version targeted by this package might use outdated or insecure TLS protocols and cipher suites, leading to handshake failures with modern servers that enforce stricter security policies.

fix This issue is often a symptom of the package's fundamental incompatibility with modern environments. There is no direct fix for this package's core. You would need to move to a maintained library or explicitly, and insecurely, disable certificate verification (`rejectUnauthorized: false`), which is strongly discouraged for production.

Warnings

breaking The package explicitly targets Node.js version `>= 0.12`. This extremely old engine requirement means it is highly likely to be incompatible with modern Node.js versions (e.g., v16, v18, v20+) due to significant changes in core APIs, dependency updates, and underlying system libraries.
Fix: This package is fundamentally designed for old Node.js runtimes. Running it on modern Node.js versions will likely lead to errors. Consider finding an alternative or using an old, insecure Node.js environment at your own risk.
gotcha The library implements the 'Reverse HTTP' (PTTH/1.0) draft specification, which is a niche and potentially unmaintained protocol. This may lead to interoperability issues with contemporary HTTP servers or load balancers, and a lack of community support.
Fix: Ensure that the server you are connecting to explicitly supports the PTTH/1.0 protocol. For new projects, consider modern alternatives like WebSockets for bidirectional communication.
gotcha This package does not ship with TypeScript type definitions. When used in a TypeScript project, you will either need to create manual declaration files (`.d.ts`) or use `any` types, which reduces type safety.
Fix: Create a `reverse-http.d.ts` file with basic type declarations, for example: `declare module 'reverse-http';` or more detailed definitions if needed. Alternatively, use `@ts-ignore` or `any` for untyped imports.
gotcha When using the `tls: true` option, the underlying Node.js 0.12 TLS implementation and its associated OpenSSL libraries are severely out of date. This could expose applications to known cryptographic vulnerabilities, compromising connection security and potentially making it impossible to connect to modern, secure servers.
Fix: Avoid using this package for secure communications if running on older Node.js versions. If using a modern Node.js version, compatibility issues will likely arise before TLS problems. Modern secure communication requires a actively maintained library.

Install

npm install reverse-http npm
yarn add reverse-http yarn
pnpm add reverse-http pnpm

Imports

reverseHttp
```
const reverseHttp = require('reverse-http')
```
This package is a CommonJS module, and `require()` is the officially supported and intended way to import it, especially given its age and Node.js 0.12 target.
reverseHttp (ESM default import)
wrong:
```
import { reverseHttp } from 'reverse-http'
```
correct:
```
import reverseHttp from 'reverse-http'
```
When importing a CommonJS module into an ECMAScript Module (ESM) context, the `module.exports` object becomes the default export. Named imports will generally fail.
ReverseServer (instance)
wrong:
```
import { ReverseServer } from 'reverse-http'
```
correct:
```
const server = reverseHttp(opts)
```
The `ReverseServer` class is returned as an instance from the `reverseHttp` function call; it is not directly exported from the module for standalone import.

Quickstart

Demonstrates establishing a reverse HTTP connection and handling an incoming request that arrives back through the tunnel.

const reverseHttp = require('reverse-http')

const opts = {
  hostname: 'example.com',
  path: '/foo'
}

// Open an HTTP connection to example.com and accept reverse HTTP
// requests back to this machine. This effectively turns the client
// into a server for requests coming back through the established tunnel.
reverseHttp(opts, function (req, res) {
  console.log('Incoming request:', req.method, req.url)

  res.writeHead(201, {
    'Content-Type': 'text/plain',
    'Content-Length': 11
  })

  res.end('Hello World')
})

view raw JSON →