Proxy Agent

import { ProxyAgent, proxies } from "proxy-agent";
import type { ProxyAgentOptions } from "proxy-agent";

const { ProxyAgent, proxies } = require("proxy-agent");

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

/**
 * Uses the appropriate Agent subclass based off of the "proxy"
 * environment variables that are currently set.
 * An LRU cache is used, to prevent unnecessary creation of proxy
 * http.Agent instances.
 */
class ProxyAgent extends Agent {
  constructor(opts?: ProxyAgentOptions);
  
  /** Cache for Agent instances */
  cache: LRUCache<string, Agent>;
  
  /** Stored connection options */
  connectOpts?: ProxyAgentOptions;
  
  /** Default HTTP agent for non-proxy requests */
  httpAgent: http.Agent;
  
  /** Default HTTPS agent for non-proxy requests */
  httpsAgent: http.Agent;
  
  /** Function to determine proxy for given URL */
  getProxyForUrl: GetProxyForUrlCallback;
  
  /**
   * Main connection method that selects appropriate agent based on proxy configuration
   * @param req - The HTTP request
   * @param opts - Connection options from agent-base
   * @returns Promise resolving to the appropriate agent for the request
   */
  connect(req: http.ClientRequest, opts: AgentConnectOpts): Promise<http.Agent>;
  
  /**
   * Destroys all cached agents and cleans up resources
   */
  destroy(): void;
}

import { ProxyAgent } from 'proxy-agent';

// Basic usage with environment variables
const agent = new ProxyAgent();

// With custom options
const agent = new ProxyAgent({
  keepAlive: true,
  timeout: 5000,
  rejectUnauthorized: false
});

// With custom proxy resolution
const agent = new ProxyAgent({
  getProxyForUrl: (url, req) => {
    // Custom logic to determine proxy
    return 'http://my-proxy.com:8080';
  }
});

// Access the cache
console.log(`Current cache size: ${agent.cache.size}`);

// Cleanup when done
agent.destroy();

interface ProxyAgentOptions extends 
  HttpProxyAgentOptions<''>,
  HttpsProxyAgentOptions<''>,
  SocksProxyAgentOptions,
  PacProxyAgentOptions<''> {
  
  /**
   * Default http.Agent instance to use when no proxy is
   * configured for a request. Defaults to a new http.Agent()
   * instance with the proxy agent options passed in.
   */
  httpAgent?: http.Agent;
  
  /**
   * Default https.Agent instance to use when no proxy is
   * configured for a request. Defaults to a new https.Agent()
   * instance with the proxy agent options passed in.
   */
  httpsAgent?: http.Agent;
  
  /**
   * A callback for dynamic provision of proxy for url.
   * Defaults to standard proxy environment variables,
   * see https://www.npmjs.com/package/proxy-from-env for details
   */
  getProxyForUrl?: GetProxyForUrlCallback;
}

/**
 * Function type for custom proxy URL resolution
 * @param url - The target URL being requested
 * @param req - The HTTP client request object
 * @returns Proxy URL string, or empty string for no proxy, or Promise resolving to same
 */
interface GetProxyForUrlCallback {
  (url: string, req: http.ClientRequest): string | Promise<string>;
}

/**
 * Exported constant mapping proxy protocols to agent constructors
 * [0] = constructor for HTTP requests
 * [1] = constructor for HTTPS/WebSocket requests
 */
export const proxies: {
  [P in ValidProtocol]: [
    () => Promise<AgentConstructor>,
    () => Promise<AgentConstructor>
  ];
};

type ValidProtocol = 
  | 'http'     // HTTP proxy: http://proxy-server.com:3128
  | 'https'    // HTTPS proxy: https://proxy-server.com:3129
  | 'socks'    // SOCKS5 proxy: socks://username:password@proxy.com:9050
  | 'socks4'   // SOCKS4 proxy: socks4://proxy.com:9050
  | 'socks4a'  // SOCKS4A proxy: socks4a://proxy.com:9050
  | 'socks5'   // SOCKS5 proxy: socks5://username:password@proxy.com:9050
  | 'socks5h'  // SOCKS5 with hostname resolution: socks5h://proxy.com:9050
  | 'pac+data' // PAC with data URL: pac+data:application/x-ns-proxy-autoconfig;base64,...
  | 'pac+file' // PAC with file URL: pac+file:///path/to/proxy.pac
  | 'pac+ftp'  // PAC with FTP URL: pac+ftp://server/proxy.pac
  | 'pac+http' // PAC with HTTP URL: pac+http://server/proxy.pac
  | 'pac+https'; // PAC with HTTPS URL: pac+https://server/proxy.pac

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://secure-proxy.company.com:8443
export NO_PROXY=localhost,127.0.0.1,.company.com

// Re-exported from dependencies for convenience
import type { Agent, AgentConnectOpts } from 'agent-base';
import type { PacProxyAgentOptions } from 'pac-proxy-agent';
import type { HttpProxyAgentOptions } from 'http-proxy-agent';
import type { HttpsProxyAgentOptions } from 'https-proxy-agent';
import type { SocksProxyAgentOptions } from 'socks-proxy-agent';

/**
 * Constructor type for proxy agent implementations
 */
interface AgentConstructor {
  new (proxy: string, proxyAgentOptions?: ProxyAgentOptions): Agent;
}

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

const agent = new ProxyAgent();

const request = https.get('https://api.example.com', { agent }, (res) => {
  // Handle response
});

request.on('error', (err) => {
  if (err.message.includes('Unsupported protocol')) {
    console.error('Invalid proxy configuration:', err.message);
  } else {
    console.error('Request failed:', err.message);
  }
});