hpagent

library1.2.0jsnpmunverified

hpagent is a Node.js library providing HttpProxyAgent and HttpsProxyAgent classes designed to facilitate HTTP and HTTPS requests through proxy servers while leveraging connection keep-alive mechanisms. Currently at version 1.2.0, it maintains an active development status with periodic releases introducing features and bug fixes, such as strict TypeScript support and improved proxy handling. A key differentiator is its ability to serve as a drop-in replacement for Node.js's native `http` and `https` agents, offering robust proxy configuration options, including basic authentication via URL or custom headers, and the ability to pass specific options for the proxy CONNECT request. The library explicitly demonstrates compatibility with popular userland HTTP clients like `got`, `needle`, `node-fetch`, and `simple-get`, and ships with TypeScript type definitions, making it suitable for modern Node.js applications (Node.js >=14 is required since v1.0.0).

http-networking serialization

npm install hpagent

github ↗package ↗

INSTALL

IMPORT

SIG · HPAGENT

hpagent

http-networkingjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

HttpProxyAgent

✓ import { HttpProxyAgent } from 'hpagent'

✗ const HttpProxyAgent = require('hpagent').HttpProxyAgent

CommonJS `require` syntax is `const { HttpProxyAgent } = require('hpagent')`

HttpsProxyAgent

✓ import { HttpsProxyAgent } from 'hpagent'

✗ const HttpsProxyAgent = require('hpagent').HttpsProxyAgent

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

HttpProxyAgentOptions

✓ import type { HttpProxyAgentOptions } from 'hpagent'

Type import for configuring HttpProxyAgent instances.

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();

Debug

Known issues

breakinghpagent 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.

affects: >=1.0.0

gotchaChoosing 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.

affects: >=0.1.0

gotchaProxy 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.

affects: >=0.1.0

gotchaWhen 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')]`).

affects: >=0.1.0

Errors

Common errors & fixes

Error: self signed certificate in certificate chain

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

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`.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/delvedor/hpagent ↗

packagehttps://www.npmjs.com/package/hpagent ↗