or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

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