HTTP/HTTPS Proxy Agent for Node.js

Common errors

• Error: self signed certificate in certificate chain

  cause Attempting to connect to an HTTPS proxy that uses a self-signed or untrusted TLS certificate without providing the necessary CA certificates.
  fix Add the proxy's certificate(s) to the `proxyConnectOptions.ca` array, or configure Node.js to trust the certificate globally (less secure).

• ERR_INVALID_URL: Invalid URL

  cause The `proxy` URL string provided to the agent constructor is malformed or uses an unsupported protocol scheme.
  fix Ensure the `proxy` option is a valid URL string, including the protocol (e.g., `http://`, `https://`), host, and port, like `http://localhost:8080`.

Warnings

• breaking hpagent v1.0.0 dropped support for Node.js versions older than 14. Users on Node.js < 14 must upgrade their runtime or remain on hpagent v0.x.
  Fix: Upgrade your Node.js runtime to version 14 or higher.
• gotcha Choosing the correct agent (HttpProxyAgent vs. HttpsProxyAgent) is crucial. The selection depends on *both* the proxy's protocol and the target server's protocol. Incorrect selection will lead to connection errors.
  Fix: Consult the package documentation table to determine the appropriate agent based on your proxy and target server types.
• gotcha Proxy authentication requires careful handling. Basic authentication can be embedded directly in the proxy URL (e.g., `http://user:pwd@host:port`) or provided via custom `Proxy-Authorization` headers within `proxyConnectOptions.headers`. Misconfigured or missing credentials will result in authentication failures.
  Fix: Ensure the proxy URL contains correct credentials or provide them in `proxyConnectOptions.headers`. Remember that username/password are not URL-encoded by hpagent itself since v1.0.0.
• gotcha When connecting to an HTTPS proxy that uses a self-signed or otherwise untrusted TLS certificate, you must provide the proxy's certificate(s) via the `proxyConnectOptions.ca` array to prevent TLS handshake errors.
  Fix: Supply the proxy's certificate chain in `proxyConnectOptions.ca` (e.g., `ca: [fs.readFileSync('custom-proxy-cert.pem')]`).

Install

• npm install hpagent npm
• yarn add hpagent yarn
• pnpm add hpagent pnpm

Imports

• HttpProxyAgent
  wrong:

  const HttpProxyAgent = require('hpagent').HttpProxyAgent

  correct:

  import { HttpProxyAgent } from 'hpagent'

  CommonJS `require` syntax is `const { HttpProxyAgent } = require('hpagent')`
• HttpsProxyAgent
  wrong:

  const HttpsProxyAgent = require('hpagent').HttpsProxyAgent

  correct:

  import { HttpsProxyAgent } from 'hpagent'

  CommonJS `require` syntax is `const { HttpsProxyAgent } = require('hpagent')`
• HttpProxyAgentOptions

  import type { HttpProxyAgentOptions } from 'hpagent'

  Type import for configuring HttpProxyAgent instances.

Quickstart

Demonstrates how to create and use an HttpProxyAgent with basic authentication for an HTTP request via Node.js's built-in http module. This code uses environment variables for sensitive data and target host/port, making it runnable and adaptable.

import http from 'node:http';
import { HttpProxyAgent } from 'hpagent';

const PROXY_USER = process.env.PROXY_USERNAME ?? 'user';
const PROXY_PASS = process.env.PROXY_PASSWORD ?? 'pwd';
const PROXY_HOST = process.env.PROXY_HOST ?? 'localhost';
const PROXY_PORT = process.env.PROXY_PORT ?? '8080';
const TARGET_HOST = process.env.TARGET_HOST ?? 'localhost';
const TARGET_PORT = process.env.TARGET_PORT ?? '9200';

const agent = new HttpProxyAgent({
  keepAlive: true,
  keepAliveMsecs: 1000,
  maxSockets: 256,
  maxFreeSockets: 256,
  proxy: `http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}`
});

http.get(`http://${TARGET_HOST}:${TARGET_PORT}`, { agent })
    .on('response', (res) => {
        console.log(`STATUS: ${res.statusCode}`);
        console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
        res.setEncoding('utf8');
        res.on('data', (chunk) => {
            console.log(`BODY: ${chunk}`);
        });
        res.on('end', () => {
            console.log('No more data in response.');
        });
    })
    .on('error', (e) => {
        console.error(`problem with request: ${e.message}`);
    })
    .end();