Registry / http-networking / proxy-test-server

proxy-test-server

JSON →
library1.0.0jsnpmunverified

proxy-test-server is a lightweight Node.js module designed to create a simple HTTP proxy server, primarily for testing proxied connections. It specifically handles HTTP `CONNECT` requests, enabling clients to establish a tunnel through the proxy to a destination server, such as for HTTPS traffic. It does not provide full HTTP proxying (e.g., modifying HTTP headers directly) but focuses on the `CONNECT` method for transparent tunneling. The package is currently at version 1.0.0 and appears to be in a maintenance state, with no active development or a defined release cadence, indicating a stable but minimally evolving codebase. Its key differentiator is its straightforward, minimal implementation for verifying basic proxy connectivity, rather than offering advanced features like mocking, traffic inspection, or support for multiple proxy protocols (SOCKS, HTTPS) found in more comprehensive proxy tools like Mockttp or Check-Proxy.

npm install proxy-test-server
INSTALL
IMPORT
SIG · PROXY-TEST-SERVER
P
proxy-test-server
http-networkingjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpConnectProxy
const HttpConnectProxy = require('proxy-test-server');
import HttpConnectProxy from 'proxy-test-server';
This library is primarily CommonJS. Direct ESM import might not work without transpilation or Node.js's `--experimental-vm-modules` flag and `"type": "module"` in package.json, and even then, its structure might not align for default imports.
HttpConnectProxy instance
const proxy = new (require('proxy-test-server'))();
const { HttpConnectProxy } = require('proxy-test-server'); // if not explicitly exported named
The `require` statement directly returns the `HttpConnectProxy` constructor, so it should be instantiated directly after requiring.
Event Listener (connect)
proxy.on('connect', (port, host, socket) => { /* ... */ });
proxy.connect((port, host, socket) => { /* ... */ });
The proxy server emits a 'connect' event when a client successfully establishes a tunnel through it. Ensure you are using the event emitter pattern (`.on`) and not trying to call a method named `connect`.

Demonstrates how to initialize and start an HTTP CONNECT proxy server, listen for incoming connections, log proxy activity, and handle common errors like port conflicts. Includes instructions for testing with curl.

const HttpConnectProxy = require('proxy-test-server'); const proxy = new HttpConnectProxy(); const PORT = process.env.PROXY_PORT ? parseInt(process.env.PROXY_PORT) : 9999; proxy.listen(PORT, function () { console.log(`HTTP CONNECT Proxy Server Listening on port ${PORT}`); }); proxy.on('connect', function (port, host, socket) { const time = new Date().toISOString().substr(0, 19).replace('T', ''); console.log(`[%s] From %s to %s:%s`, time, socket.remoteAddress, host, port); socket.on('error', (err) => console.error(`Socket error for ${socket.remoteAddress}:`, err.message)); }); proxy.on('error', (err) => { console.error('Proxy server error:', err.message); if (err.code === 'EADDRINUSE') { console.error(`Port ${PORT} is already in use. Try a different port or stop the conflicting process.`); } }); console.log('To test, run: curl -i -x http://127.0.0.1:9999 https://google.com'); // Or if using a different port: console.log(`To test, run: curl -i -x http://127.0.0.1:${PORT} https://google.com`); // To stop the server gracefully process.on('SIGINT', () => { console.log('\nShutting down proxy server...'); proxy.close(() => { console.log('Proxy server closed.'); process.exit(0); }); });
Debug
Known issues
breakingThis library explicitly supports only HTTP CONNECT requests, which are used for tunneling. It does not natively support direct HTTP proxying (e.g., for GET/POST requests that don't initiate a tunnel). Attempts to send non-CONNECT HTTP requests directly to this proxy will likely fail.
fix
Ensure your client is configured to use the proxy for CONNECT requests (e.g., HTTPS requests) or use a different proxy library for full HTTP proxying.
affects: >=1.0.0
gotchaRunning an open proxy without proper access control can expose your system to significant security risks, allowing unauthorized parties to route traffic through your machine. This could lead to abuse, legal issues, or network compromise.
fix
Implement strict IP-based access control, authentication, or ensure the proxy is only accessible within a secure, controlled testing environment. Do not expose this server to the public internet.
affects: >=1.0.0
gotchaDue to the library's age and `require` usage, it is primarily designed for CommonJS environments. Integrating it directly into modern ESM-only Node.js projects may require special handling or transpilation.
fix
For ESM projects, consider using a dynamic `import()` or ensuring your project configuration (e.g., `package.json` `type`) correctly handles interoperability between CommonJS and ESM. Alternatively, use a modern proxy library with explicit ESM support.
affects: >=1.0.0
gotchaProxy connections often fail due to local firewall rules, antivirus software, or network misconfigurations blocking the proxy's port or outgoing connections.
fix
Verify that no local software or network devices are blocking the port the proxy is listening on, or the outgoing connections from the proxy. Temporarily disable firewalls or add explicit allow rules for the proxy process and port.
affects: >=1.0.0
Errors
Common errors & fixes
Error: listen EADDRINUSE :::9999
The specified port (e.g., 9999) is already in use by another application on your system.
fix
Choose a different port for your proxy server that is not currently in use, or stop the process that is occupying the desired port.
Error: listen EACCES
Your application does not have the necessary permissions to bind to the specified port, typically ports below 1024 on Linux/macOS.
fix
Use a port number greater than 1024, or run your Node.js application with elevated privileges (e.g., `sudo node your_script.js`), though the latter is generally not recommended for production.
curl: (5) Could not resolve proxy: 127.0.0.1
The client attempting to connect to the proxy (e.g., curl) cannot resolve the proxy's hostname or IP address, or the proxy server is not running.
fix
Ensure the proxy server is running and listening on the correct IP address and port. Verify that there are no typos in the proxy address provided to the client. Check network connectivity between client and proxy.
curl: (56) Received HTTP code 500 from proxy after CONNECT
The proxy server encountered an internal error while trying to establish a tunnel or connect to the destination server (e.g., Google.com in the example).
fix
Check the proxy server's console output for specific error messages (e.g., from `proxy.on('error')` or `socket.on('error')` listeners). This could indicate issues with the proxy's outbound network connectivity or an unhandled error in its internal logic.
TypeError: HttpConnectProxy is not a constructor
This usually occurs when using `import HttpConnectProxy from 'proxy-test-server'` in an ESM context, where the CommonJS `module.exports` (which is the constructor) is not correctly interpreted as the default export.
fix
If in a CommonJS context, use `const HttpConnectProxy = require('proxy-test-server');`. If in an ESM context, you might need to adjust your `import` statement or Node.js configuration to properly handle CommonJS module interoperability, or consider dynamically importing it.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
Resources
proxy-test-server — npm install proxy-test-server · libregistry