Extensions for JavaScript HTTP libraries to support sending and receiving custom proxy headers during HTTPS CONNECT tunneling.
When making HTTPS requests through a proxy, the connection is established via a CONNECT tunnel. During this process:
-
Sending headers to the proxy - Most JavaScript HTTP libraries don't provide a way to send custom headers (like
X-ProxyMesh-Country) to the proxy server during the CONNECT handshake. -
Receiving headers from the proxy - The proxy's response headers from the CONNECT request are typically discarded, making it impossible to read custom headers (like
X-ProxyMesh-IP) that the proxy sends back.
This library solves both problems for popular JavaScript HTTP libraries.
| Library | Module | Use Case |
|---|---|---|
| axios | axios-proxy |
Most popular HTTP client |
| node-fetch | node-fetch-proxy |
Fetch API for Node.js |
| got | got-proxy |
Human-friendly HTTP client |
| undici | undici-proxy |
Fast HTTP client (Node.js core) |
| superagent | superagent-proxy |
Flexible HTTP client |
npm install javascript-proxy-headersThen install the HTTP library you want to use (e.g., npm install axios).
Note: This package has no dependencies by default - install only what you need.
import { createProxyAxios } from 'javascript-proxy-headers/axios';
const client = createProxyAxios({
proxy: 'http://user:pass@proxy.example.com:8080',
proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
});
const response = await client.get('https://httpbin.org/ip');
// Proxy headers are merged into response.headers
console.log(response.headers['x-proxymesh-ip']);import { proxyFetch } from 'javascript-proxy-headers/node-fetch';
const response = await proxyFetch('https://httpbin.org/ip', {
proxy: 'http://user:pass@proxy.example.com:8080',
proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
});
// Proxy headers available on response
console.log(response.proxyHeaders.get('x-proxymesh-ip'));import { createProxyGot } from 'javascript-proxy-headers/got';
const client = createProxyGot({
proxy: 'http://user:pass@proxy.example.com:8080',
proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
});
const response = await client('https://httpbin.org/ip');
console.log(response.headers['x-proxymesh-ip']);import { request } from 'javascript-proxy-headers/undici';
const { statusCode, headers, body, proxyHeaders } = await request(
'https://httpbin.org/ip',
{
proxy: 'http://user:pass@proxy.example.com:8080',
proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
}
);
console.log(proxyHeaders.get('x-proxymesh-ip'));For direct control, use the core ProxyHeadersAgent:
import { ProxyHeadersAgent } from 'javascript-proxy-headers';
import https from 'https';
const agent = new ProxyHeadersAgent('http://proxy.example.com:8080', {
proxyHeaders: { 'X-ProxyMesh-Country': 'US' },
onProxyConnect: (headers) => {
console.log('Proxy IP:', headers.get('x-proxymesh-ip'));
}
});
https.get('https://httpbin.org/ip', { agent }, (res) => {
// Handle response
});A test harness is included to verify proxy header functionality:
# Set your proxy
export PROXY_URL='http://user:pass@proxy.example.com:8080'
# Test all modules
npm test
# Test specific module
npm test axios- Node.js >= 18.0.0
- One or more supported HTTP libraries
- python-proxy-headers - Same functionality for Python
- proxy-examples - Example code for using proxies
Created by ProxyMesh to help our customers use custom headers to control proxy behavior. Works with any proxy that supports custom headers.
MIT License