proxy-agent

What is proxy-agent?

The proxy-agent npm package is a module that provides an HTTP(s) proxy Agent which can be used to proxy HTTP and HTTPS requests through a specified proxy server. This is useful in scenarios where network requests need to be routed through a proxy for reasons such as security, privacy, or circumventing network restrictions.

What are proxy-agent's main functionalities?

Creating an HTTP proxy agent

This feature allows you to create an HTTP proxy agent that will route HTTP requests through the specified proxy server.

const ProxyAgent = require('proxy-agent');
const agent = new ProxyAgent('http://proxy-server.com:8080');
const http = require('http');

const requestOptions = {
  host: 'example.com',
  port: 80,
  path: '/',
  agent: agent
};

http.get(requestOptions, (res) => {
  console.log(`Got response: ${res.statusCode}`);
});

Creating an HTTPS proxy agent

This feature allows you to create an HTTPS proxy agent that will route HTTPS requests through the specified proxy server using TLS/SSL encryption.

const ProxyAgent = require('proxy-agent');
const agent = new ProxyAgent('https://proxy-server.com:443');
const https = require('https');

const requestOptions = {
  host: 'example.com',
  port: 443,
  path: '/',
  agent: agent
};

https.get(requestOptions, (res) => {
  console.log(`Got response: ${res.statusCode}`);
});

Support for different proxy protocols

The proxy-agent package supports various proxy protocols including HTTP, HTTPS, SOCKS, and PAC (Proxy Auto-Config).

const ProxyAgent = require('proxy-agent');

const httpAgent = new ProxyAgent('http://proxy-server.com:8080');
const httpsAgent = new ProxyAgent('https://proxy-server.com:443');
const socksAgent = new ProxyAgent('socks://proxy-server.com:1080');
const pacAgent = new ProxyAgent('pac+http://proxy-server.com/proxy.pac');

// Use the appropriate agent for the request protocol

Other packages similar to proxy-agent

http-proxy-agent

This package provides an HTTP agent to proxy HTTP requests. It is similar to proxy-agent but is limited to HTTP protocol only, whereas proxy-agent supports multiple protocols.

https-proxy-agent

This package provides an HTTPS agent to proxy HTTPS requests. Like http-proxy-agent, it is protocol-specific and does not offer the multi-protocol support that proxy-agent does.

socks-proxy-agent

This package is designed to provide an agent that proxies through a SOCKS proxy. It is specifically tailored for SOCKS protocol, unlike proxy-agent which handles SOCKS along with other protocols.

pac-proxy-agent

This package provides a proxy agent that can use a PAC file to determine the appropriate proxy for a given URL. It is focused on PAC file support, which is just one of the features available in proxy-agent.

README

proxy-agent

Maps proxy protocols to http.Agent implementations

This module provides an http.Agent implementation which automatically uses proxy servers based off of the various proxy-related environment variables (HTTP_PROXY, HTTPS_PROXY and NO_PROXY among others).

Which proxy is used for each HTTP request is determined by the proxy-from-env module, so check its documentation for instructions on configuring your environment variables.

An LRU cache is used so that http.Agent instances are transparently re-used for subsequent HTTP requests to the same proxy server.

The currently implemented protocol mappings are listed in the table below:

Protocol	Proxy Agent for http requests	Proxy Agent for https requests	Example
http	http-proxy-agent	https-proxy-agent	http://proxy-server-over-tcp.com:3128
https	http-proxy-agent	https-proxy-agent	https://proxy-server-over-tls.com:3129
socks(v5)	socks-proxy-agent	socks-proxy-agent	socks://username:[e-mail]:9050 (username & password are optional)
socks5	socks-proxy-agent	socks-proxy-agent	socks5://username:[e-mail]:9050 (username & password are optional)
socks4	socks-proxy-agent	socks-proxy-agent	socks4://some-socks-proxy.com:9050
pac-*	pac-proxy-agent	pac-proxy-agent	pac+http://www.example.com/proxy.pac

Example

import * as https from 'https';
import { ProxyAgent } from 'proxy-agent';

// The correct proxy `Agent` implementation to use will be determined
// via the `http_proxy` / `https_proxy` / `no_proxy` / etc. env vars
const agent = new ProxyAgent();

// The rest works just like any other normal HTTP request
https.get('https://jsonip.com', { agent }, (res) => {
  console.log(res.statusCode, res.headers);
  res.pipe(process.stdout);
});

API

new ProxyAgent(options?: ProxyAgentOptions)

Creates an http.Agent instance which relies on the various proxy-related environment variables. An LRU cache is used, so the same http.Agent instance will be returned if identical args are passed in.