repository·main·Indexed 41 days ago
https://github.com/delvedor/hpagentA Node.js library providing HttpProxyAgent and HttpsProxyAgent for working with proxies while maintaining persistent keep-alive connections. Version 1.2.0 supports custom proxy CONNECT request options, basic authentication via proxy URLs, and integration with HTTP libraries such as got, needle, node-fetch, and simple-get.
Select the appropriate agent based on your proxy type and the target server's protocol:
| Agent | Proxy Type | Server Type |
|---|---|---|
HttpProxyAgent | HTTP | HTTP |
HttpProxyAgent | HTTPS | HTTP |
HttpsProxyAgent | HTTP | HTTPS |
HttpsProxyAgent | HTTPS | HTTPS |
The following examples demonstrate how to pass an hpagent instance to common HTTP libraries:
Pass the agent inside an agent object using the http key:
got('http://localhost:9200', {
agent: {
http: new HttpProxyAgent({
keepAlive: true,
proxy: 'http://localhost:8080'
})
}
})Pass the agent directly in the options object:
needle('get', 'http://localhost:9200', {
agent: new HttpProxyAgent({
keepAlive: true,
proxy: 'http://localhost:8080'
})
})Pass the agent directly in the fetch options:
fetch('http://localhost:9200', {
agent: new HttpProxyAgent({
keepAlive: true,
proxy: 'http://localhost:8080'
})
})Pass the agent in the request object passed to .concat():
sget.concat({
url: 'http://localhost:9200',
agent: new HttpProxyAgent({
keepAlive: true,
proxy: 'https://localhost:8080'
})
}, function (err, response, data) {
// handle the response
})Install the hpagent package using npm to use HTTP and HTTPS agents that support proxies and connection keep-alive.
npm install hpagentUse the proxyConnectOptions option to pass custom settings specifically for the proxy CONNECT request. This is useful for providing custom headers (like Proxy-Authorization) or TLS options (like ca certificates) for the connection to the proxy itself.
const fs = require('fs')
const http = require('http')
const { HttpProxyAgent } = require('hpagent')
const agent = new HttpProxyAgent({
keepAlive: true,
keepAliveMsecs: 1000,
maxSockets: 256,
maxFreeSockets: 256,
proxy: 'https://localhost:8080',
proxyConnectOptions: {
headers: {
'Proxy-Authorization': 'Basic YWxhZGRpbjpvcGVuc2VzYW1l',
},
ca: [ fs.readFileSync('custom-proxy-cert.pem') ]
}
})
http.get('http://localhost:9200', { agent })
.on('response', console.log)
.end()Instantiate an agent by passing options identical to Node.js core's http(s) agent, plus a required proxy option containing the proxy URL.
To use basic authentication with your proxy, include the credentials directly in the proxy URL (e.g., http://user:pwd@localhost:8080).
const http = require('http')
const { HttpProxyAgent } = require('hpagent')
const agent = new HttpProxyAgent({
keepAlive: true,
keepAliveMsecs: 1000,
maxSockets: 256,
maxFreeSockets: 256,
proxy: 'http://user:pwd@localhost:8080'
})
http.get('http://localhost:9200', { agent })
.on('response', console.log)
.end()The hpagent package provides two primary classes for managing HTTP and HTTPS proxy connections: HttpProxyAgent and HttpsProxyAgent. These classes are exported from the ESM entrypoint and can be used to create proxy agents compatible with various Node.js HTTP clients.
To use them, import the specific class you need from hpagent.
import { HttpProxyAgent, HttpsProxyAgent } from 'hpagent';The ProxyAgentRequestOptions interface allows you to customize the settings for the connection made to the proxy server itself. Supported keys include:
ca: (Optional) An array of strings representing CA certificates.headers: (Optional) An Object containing custom headers to be sent to the proxy.rejectUnauthorized: (Optional) A boolean indicating whether to verify the proxy's SSL certificate (defaults to standard Node.js behavior).HttpsProxyAgent class is used to create an agent for handling HTTPS proxy connections. It is intended to be passed as the agent option in HTTPS client requests to route traffic through a specified proxy.The HttpsProxyAgent class extends https.Agent and is used to route HTTPS requests through a proxy. It manages the TLS handshake by establishing a connection through the proxy tunnel and then performing the secure handshake.
| Option | Type | Description |
|---|---|---|
proxy | string or URL | The proxy URL (e.g., http://user:pass@host:port). If a string, it is parsed into a URL object. |
proxyRequestOptions | Object | Additional options passed to the proxy request (e.g., custom headers). |
...opts | Object | Any standard https.Agent options (e.g., keepAlive). |
const { HttpsProxyAgent } = require('hpagent');
const agent = new HttpsProxyAgent({
proxy: 'http://my-proxy.com:8080',
keepAlive: true
});
// Use the agent in an https.request call
// https.get({ host: 'example.com', agent }, (res) => { ... });HttpProxyAgent class is used to create an agent for handling HTTP proxy connections. It is intended to be passed as the agent option in HTTP client requests to route traffic through a specified proxy.The HttpProxyAgent class extends http.Agent and allows you to route HTTP requests through a proxy. It handles the CONNECT method required to establish a tunnel through the proxy.
| Option | Type | Description |
|---|---|---|
proxy | string or URL | The proxy URL (e.g., http://user:pass@host:port). If a string, it is parsed into a URL object. |
proxyRequestOptions | Object | Additional options passed to the proxy request (e.g., custom headers). |
...opts | Object | Any standard http.Agent options (e.g., keepAlive). |
const { HttpProxyAgent } = require('hpagent');
const agent = new HttpProxyAgent({
proxy: 'http://my-proxy.com:8080',
keepAlive: true
});
// Use the agent in an http.request call
// http.get({ host: 'example.com', agent }, (res) => { ... });The HttpsProxyAgentOptions interface defines the configuration for an HttpsProxyAgent. It extends the standard https.AgentOptions and adds the following keys:
proxy: (Required) A string or URL representing the proxy server address.proxyRequestOptions: (Optional) A ProxyAgentRequestOptions object used to configure the connection to the proxy server.