HTTP Proxy to SOCKS Converter (CLI)

1.1.4 · abandoned · verified Wed Apr 22

http-proxy-to-socks (hpts) is a command-line interface (CLI) tool for Node.js designed to convert a SOCKS proxy into an HTTP proxy. This utility is particularly useful in environments where applications or clients only support HTTP proxy configurations, but the available upstream proxy is SOCKS-based. It operates by launching a local HTTP proxy server that intercepts HTTP requests and transparently forwards them through a user-specified SOCKS proxy. The package is currently at version 1.1.4, with its last update approximately six years ago, indicating it is likely in an abandoned or unmaintained state. While it fulfills a specific niche, users should be aware of its age and lack of recent updates. Key differentiators include its simplicity and direct command-line utility for this specific proxy conversion task, contrasting with more comprehensive proxy agents or libraries that might offer programmatic integration.

Common errors

```
Error: listen EADDRINUSE: address already in use :::8080
```
cause The specified HTTP proxy port (`-p`) is already in use by another application on the system.

fix Choose a different, available port for the HTTP proxy. For example, `hpts -s 127.0.0.1:1080 -p 8081`.
```
Error: connect ECONNREFUSED 127.0.0.1:1080 - Local (0.0.0.0:xxxx)
```
cause The `hpts` tool failed to connect to the specified SOCKS proxy. This usually means the SOCKS proxy server is not running, is listening on a different address/port, or a firewall is blocking the connection.

fix Ensure your SOCKS proxy (e.g., `socks://127.0.0.1:1080`) is running and accessible from where `hpts` is executed. Double-check the host and port in the `-s` argument for typos. Check local firewall settings.
```
hpts: command not found
```
cause The `http-proxy-to-socks` package was not installed globally, or its binary path is not in the system's PATH environment variable.

fix Install the package globally using `npm install -g http-proxy-to-socks`. If it's still not found, verify npm's global bin directory is in your system's PATH.

Warnings

gotcha The `http-proxy-to-socks` package is solely a command-line interface (CLI) tool. It is not designed to be imported or used programmatically as a library within another Node.js application. Attempts to `require()` or `import` its modules will fail as it does not expose a public API. Users must install it globally or call its executable via `child_process`.
Fix: Use `npm install -g http-proxy-to-socks` and then execute the `hpts` command directly from the terminal or through `child_process.exec`/`spawn` in Node.js applications.
deprecated The package has not been updated in approximately six years (since version 1.1.4). This indicates it is likely unmaintained or abandoned. While its core functionality may still work, it might not receive security patches, bug fixes, or updates for modern Node.js versions or evolving proxy standards.
Fix: Evaluate newer, actively maintained alternatives like `socks-proxy-agent` or `https-socks-proxy` if programmatic integration is needed, or explore other CLI-based proxy conversion tools if maintenance is a concern. For critical systems, consider the risks of using unmaintained software.
gotcha It is crucial to ensure that the specified SOCKS proxy (`-s`) is actively running and accessible at the provided host and port before starting `hpts`. If the SOCKS proxy is unavailable or misconfigured, `hpts` will not be able to establish its HTTP proxy service correctly, leading to connection failures for clients using the HTTP proxy.
Fix: Verify your SOCKS proxy server status and configuration (e.g., `socks://127.0.0.1:1080`) before launching `hpts`. Check firewall rules and network connectivity between `hpts` and the SOCKS server.

Install

npm install http-proxy-to-socks npm
yarn add http-proxy-to-socks yarn
pnpm add http-proxy-to-socks pnpm

Imports

hpts (CLI command)
wrong:
```
import { hpts } from 'http-proxy-to-socks'
```
correct:
```
npm install -g http-proxy-to-socks
hpts -s <SOCKS_HOST>:<SOCKS_PORT> -p <HTTP_PROXY_PORT>
```
This package is a command-line interface (CLI) tool, not a library for programmatic import. Its primary usage is via the `hpts` command after global installation. Attempting to `import` or `require` modules directly from the package will result in errors as no public API is exposed.

Quickstart

This quickstart demonstrates how to programmatically execute the `hpts` command-line tool using Node.js's `child_process` module to set up an HTTP proxy on port 8080, forwarding traffic through a SOCKS proxy running on 127.0.0.1:1080. It simulates typical CLI usage for integration or testing.

import { exec } from 'child_process';

const socksHost = '127.0.0.1'; // Replace with your SOCKS proxy host
const socksPort = 1080;      // Replace with your SOCKS proxy port
const httpProxyPort = 8080;  // Port for the HTTP proxy hpts will create

const command = `hpts -s ${socksHost}:${socksPort} -p ${httpProxyPort}`;

console.log(`Starting http-proxy-to-socks: ${command}`);

const hptsProcess = exec(command, (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    return;
  }
  if (stdout) console.log(`stdout: ${stdout}`);
  if (stderr) console.error(`stderr: ${stderr}`);
});

hptsProcess.stdout.on('data', (data) => {
  console.log(`hpts output: ${data.toString().trim()}`);
});

hptsProcess.stderr.on('data', (data) => {
  console.error(`hpts error: ${data.toString().trim()}`);
});

// Keep the process alive for a few seconds to demonstrate. In a real app,
// you'd manage its lifecycle more robustly or run it as a daemon.
setTimeout(() => {
  console.log('Stopping hpts process...');
  hptsProcess.kill();
}, 10000); // Stop after 10 seconds for demonstration

view raw JSON →