or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-https-proxy-agent

An HTTP(s) proxy Agent implementation for HTTPS connections that tunnels requests through proxy servers using the CONNECT method

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/https-proxy-agent@7.0.x

To install, run

npx @tessl/cli install tessl/npm-https-proxy-agent@7.0.0

index.mddocs/

HTTPS Proxy Agent

HTTPS Proxy Agent provides an HTTP Agent implementation that connects to specified HTTP or HTTPS proxy servers using the CONNECT method to establish direct TCP connections to destination servers through proxy intermediaries. It supports both HTTPS requests and WebSocket connections over proxies, making it suitable for applications that need to route secure connections through corporate or private proxy infrastructure.

Package Information

  • Package Name: https-proxy-agent
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install https-proxy-agent

Core Imports

import { HttpsProxyAgent } from "https-proxy-agent";
import type { HttpsProxyAgentOptions, ConnectResponse } from "https-proxy-agent";

For CommonJS:

const { HttpsProxyAgent } = require("https-proxy-agent");

Basic Usage

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

// Create agent with HTTP proxy
const agent = new HttpsProxyAgent('http://proxy.example.com:8080');

// Use with HTTPS requests
https.get('https://example.com', { agent }, (res) => {
  console.log('Status:', res.statusCode);
  res.pipe(process.stdout);
});

// With authentication
const authAgent = new HttpsProxyAgent('http://user:pass@proxy.example.com:8080');

// With custom headers
const customAgent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  headers: {
    'User-Agent': 'MyApp/1.0'
  }
});

Architecture

HTTPS Proxy Agent extends Node.js's Agent class from the agent-base package and implements the HTTP CONNECT method for proxy tunneling:

  • Proxy Connection: Establishes connection to proxy server using HTTP or HTTPS
  • CONNECT Tunnel: Uses HTTP CONNECT method to request proxy server to establish TCP tunnel to destination
  • TLS Upgrade: For HTTPS destinations, upgrades the tunneled connection to TLS after proxy handshake
  • Authentication: Automatically handles Basic authentication when credentials are in proxy URL
  • Error Handling: Provides detailed error information for connection failures and proxy authentication issues

Capabilities

HttpsProxyAgent Class

Main class that implements HTTP Agent functionality for proxy connections.

class HttpsProxyAgent<Uri extends string> extends Agent {
  constructor(proxy: Uri | URL, opts?: HttpsProxyAgentOptions<Uri>);
  
  static protocols: readonly ['http', 'https'];
  readonly proxy: URL;
  proxyHeaders: OutgoingHttpHeaders | (() => OutgoingHttpHeaders);
  connectOpts: net.TcpNetConnectOpts & tls.ConnectionOptions;
  
  connect(req: http.ClientRequest, opts: AgentConnectOpts): Promise<net.Socket>;
}

Constructor Parameters:

  • proxy: String URL or URL object for the proxy server. Supports http:// and https:// protocols
  • opts: Optional configuration object with proxy headers and connection options

Properties:

  • protocols: Static property indicating supported proxy protocols (['http', 'https'])
  • proxy: The parsed proxy URL
  • proxyHeaders: Headers to send with CONNECT requests (object or function)
  • connectOpts: Connection options used when connecting to proxy server

Methods:

  • connect(): Internal method called by Node.js HTTP client to establish proxy connection

Configuration Options

Options interface for customizing HttpsProxyAgent behavior.

type HttpsProxyAgentOptions<T> = ConnectOpts<T> & http.AgentOptions & {
  headers?: OutgoingHttpHeaders | (() => OutgoingHttpHeaders);
};

// Protocol-specific connection options based on proxy URL protocol
type ConnectOpts<T> = {
  http: Omit<net.TcpNetConnectOpts, 'host' | 'port'>;
  https: Omit<tls.ConnectionOptions, 'host' | 'port'>;
}[Protocol<T>];

// Extract protocol from proxy URL type
type Protocol<T> = T extends `${infer Protocol}:${infer _}` ? Protocol : never;

Configuration Properties:

  • headers: Custom headers for proxy CONNECT requests (static object or function returning headers)
  • Protocol-specific connection options (determined by proxy URL protocol):
    • For http:// proxies: net.TcpNetConnectOpts options (excluding host/port)
    • For https:// proxies: tls.ConnectionOptions options (excluding host/port)
  • Standard http.Agent options for connection pooling and timeouts

Types

Supporting types for proxy connections. Note that OutgoingHttpHeaders and AgentConnectOpts are imported from Node.js built-in modules.

// From Node.js 'http' module
interface OutgoingHttpHeaders {
  [header: string]: number | string | string[] | undefined;
}

// From 'agent-base' package
interface AgentConnectOpts {
  host: string;
  port: number;
  secureEndpoint: boolean;
  servername?: string;
}

// Proxy CONNECT response structure
interface ConnectResponse {
  statusCode: number;
  statusText: string;
  headers: IncomingHttpHeaders;
}

// From Node.js 'http' module
interface IncomingHttpHeaders {
  [header: string]: string | string[] | undefined;
}

Usage Examples

WebSocket Connections

import WebSocket from 'ws';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080');
const socket = new WebSocket('wss://echo.websocket.org', { agent });

socket.on('open', () => {
  console.log('WebSocket connected through proxy');
  socket.send('Hello World');
});

socket.on('message', (data) => {
  console.log('Received:', data.toString());
  socket.close();
});

Dynamic Headers

import { HttpsProxyAgent } from 'https-proxy-agent';

let requestCount = 0;

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  headers: () => ({
    'X-Request-ID': `req-${++requestCount}`,
    'X-Client-Name': 'MyApp'
  })
});

// Each request will have incrementing request ID

HTTPS Proxy with Self-Signed Certificate

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('https://proxy.example.com:8443', {
  rejectUnauthorized: false,  // Accept self-signed certificates
  headers: {
    'Proxy-Authorization': 'Bearer token123'
  }
});

Connection Pooling

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  keepAlive: true,
  keepAliveMsecs: 30000,
  maxSockets: 10,
  maxFreeSockets: 3
});

// Reuse connections for better performance

Events

Agent Events

The HttpsProxyAgent emits events during proxy connection establishment:

  • 'proxyConnect': Emitted when proxy CONNECT handshake completes successfully
    • Parameters: (connectResponse, clientRequest)
    • connectResponse: Object with { statusCode: number, statusText: string, headers: IncomingHttpHeaders }
    • clientRequest: The originating HTTP client request

Request Events

HTTP ClientRequest objects emit proxy-related events:

  • 'proxyConnect': Emitted on the request when proxy connection is established
    • Parameters: (connectResponse)
    • connectResponse: Same object structure as agent event
import * as https from 'https';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080');

agent.on('proxyConnect', (connectResponse, req) => {
  console.log('Proxy connected:', connectResponse.statusCode);
  console.log('Status text:', connectResponse.statusText);
});

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

req.on('proxyConnect', (connectResponse) => {
  console.log('Request proxy connected:', connectResponse.statusCode);
});

Error Handling

Constructor Errors

  • Invalid proxy URL: Throws when provided proxy URL is invalid or empty
  • Protocol errors: Throws for unsupported proxy protocols
try {
  const agent = new HttpsProxyAgent('');  // Throws error
} catch (error) {
  console.error('Invalid proxy URL:', error.message);
}

Connection Errors

  • Connection refused: When proxy server is unreachable
  • Authentication failures: When proxy returns non-200 status codes
  • Timeout errors: When connection to proxy times out
  • TLS errors: When HTTPS proxy has certificate issues
import * as https from 'https';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://unreachable-proxy:8080');

const req = https.get('https://example.com', { agent }, (res) => {
  // This won't be called if proxy connection fails
});

req.on('error', (error) => {
  if (error.code === 'ECONNREFUSED') {
    console.error('Proxy server unreachable');
  } else if (error.code === 'ENOTFOUND') {
    console.error('Proxy server not found');
  } else {
    console.error('Request error:', error.message);
  }
});

Proxy Authentication

The agent automatically handles Basic authentication when credentials are included in the proxy URL:

// Authentication automatically handled
const agent = new HttpsProxyAgent('http://username:password@proxy.example.com:8080');

// Manual authentication headers
const agent2 = new HttpsProxyAgent('http://proxy.example.com:8080', {
  headers: {
    'Proxy-Authorization': 'Basic ' + Buffer.from('username:password').toString('base64')
  }
});

Common Use Cases

Corporate Proxies

import { HttpsProxyAgent } from 'https-proxy-agent';

// Corporate proxy with authentication
const agent = new HttpsProxyAgent(process.env.HTTPS_PROXY || 'http://proxy.corp.com:8080', {
  headers: {
    'User-Agent': 'Corporate App v1.0'
  }
});

Development and Testing

import { HttpsProxyAgent } from 'https-proxy-agent';

// Debug proxy for inspecting traffic
const debugAgent = new HttpsProxyAgent('http://localhost:8888', {
  headers: () => ({
    'X-Debug-Session': Date.now().toString()
  })
});

Load Balancing Through Multiple Proxies

import { HttpsProxyAgent } from 'https-proxy-agent';

const proxies = [
  'http://proxy1.example.com:8080',
  'http://proxy2.example.com:8080',
  'http://proxy3.example.com:8080'
];

let currentProxy = 0;

function getAgent() {
  const proxyUrl = proxies[currentProxy++ % proxies.length];
  return new HttpsProxyAgent(proxyUrl);
}

// Use different proxy for each request
const agent = getAgent();