{"id":17250,"library":"hpagent","title":"HTTP/HTTPS Proxy Agent for Node.js","description":"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).","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/delvedor/hpagent","tags":["javascript","agent","http","https","secure","proxy","alive","keep-alive","typescript"],"install":[{"cmd":"npm install hpagent","lang":"bash","label":"npm"},{"cmd":"yarn add hpagent","lang":"bash","label":"yarn"},{"cmd":"pnpm add hpagent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` syntax is `const { HttpProxyAgent } = require('hpagent')`","wrong":"const HttpProxyAgent = require('hpagent').HttpProxyAgent","symbol":"HttpProxyAgent","correct":"import { HttpProxyAgent } from 'hpagent'"},{"note":"CommonJS `require` syntax is `const { HttpsProxyAgent } = require('hpagent')`","wrong":"const HttpsProxyAgent = require('hpagent').HttpsProxyAgent","symbol":"HttpsProxyAgent","correct":"import { HttpsProxyAgent } from 'hpagent'"},{"note":"Type import for configuring HttpProxyAgent instances.","symbol":"HttpProxyAgentOptions","correct":"import type { HttpProxyAgentOptions } from 'hpagent'"}],"quickstart":{"code":"import http from 'node:http';\nimport { HttpProxyAgent } from 'hpagent';\n\nconst PROXY_USER = process.env.PROXY_USERNAME ?? 'user';\nconst PROXY_PASS = process.env.PROXY_PASSWORD ?? 'pwd';\nconst PROXY_HOST = process.env.PROXY_HOST ?? 'localhost';\nconst PROXY_PORT = process.env.PROXY_PORT ?? '8080';\nconst TARGET_HOST = process.env.TARGET_HOST ?? 'localhost';\nconst TARGET_PORT = process.env.TARGET_PORT ?? '9200';\n\nconst agent = new HttpProxyAgent({\n  keepAlive: true,\n  keepAliveMsecs: 1000,\n  maxSockets: 256,\n  maxFreeSockets: 256,\n  proxy: `http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}`\n});\n\nhttp.get(`http://${TARGET_HOST}:${TARGET_PORT}`, { agent })\n    .on('response', (res) => {\n        console.log(`STATUS: ${res.statusCode}`);\n        console.log(`HEADERS: ${JSON.stringify(res.headers)}`);\n        res.setEncoding('utf8');\n        res.on('data', (chunk) => {\n            console.log(`BODY: ${chunk}`);\n        });\n        res.on('end', () => {\n            console.log('No more data in response.');\n        });\n    })\n    .on('error', (e) => {\n        console.error(`problem with request: ${e.message}`);\n    })\n    .end();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or higher.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Consult the package documentation table to determine the appropriate agent based on your proxy and target server types.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Supply the proxy's certificate chain in `proxyConnectOptions.ca` (e.g., `ca: [fs.readFileSync('custom-proxy-cert.pem')]`).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add the proxy's certificate(s) to the `proxyConnectOptions.ca` array, or configure Node.js to trust the certificate globally (less secure).","cause":"Attempting to connect to an HTTPS proxy that uses a self-signed or untrusted TLS certificate without providing the necessary CA certificates.","error":"Error: self signed certificate in certificate chain"},{"fix":"Ensure the `proxy` option is a valid URL string, including the protocol (e.g., `http://`, `https://`), host, and port, like `http://localhost:8080`.","cause":"The `proxy` URL string provided to the agent constructor is malformed or uses an unsupported protocol scheme.","error":"ERR_INVALID_URL: Invalid URL"}],"ecosystem":"npm","meta_description":null}