@nexon.js/proxy-agent

Efficient proxy rotation agent for Node.js with seamless axios integration. Supports both authenticated and non-authenticated proxies with automatic rotation, health checking, and comprehensive error handling.

🚀 Features

✅ Smart Proxy Rotation - Sequential or random proxy selection
✅ Multiple Auth Types - Support for authenticated and non-authenticated proxies
✅ Axios Integration - Drop-in replacement for axios HTTP/HTTPS agents
✅ Auto Validation - Built-in IP and port validation
✅ Health Checking - Test proxy connectivity and response times
✅ Auto Reload - Dynamic proxy file reloading
✅ Multiple Formats - Flexible proxy file format support
✅ TypeScript Ready - Full TypeScript definitions included
✅ Zero Dependencies - Only requires https-proxy-agent and http-proxy-agent

📦 Installation

npm install @nexon.js/proxy-agent

🔧 Quick Start

1. Create Proxy File

Create proxies.txt with your proxy list:

# Basic proxies (ip:port)
192.168.1.1:8080
10.0.0.1:3128

# Authenticated proxies (ip:port:username:password)  
192.168.1.2:8080:user123:pass456
proxy.example.com:3128:myuser:mypass

# Protocol-specific (protocol:ip:port)
http:192.168.1.3:8080
https:secure-proxy.com:8080

# Authenticated with protocol (protocol:ip:port:username:password)
http:192.168.1.4:8080:user:pass

2. Basic Usage

const ProxyAgent = require('@nexon.js/proxy-agent');
const axios = require('axios');

// Initialize proxy agent
const proxy = new ProxyAgent('./proxies.txt');

// Use with axios
const response = await axios.get('https://httpbin.org/ip', proxy.config());
console.log('Your IP:', response.data.origin);

3. Advanced Configuration

const proxy = new ProxyAgent('./proxies.txt', {
  random: true,        // Random proxy selection (default: false)
  log: true,          // Enable logging (default: true)  
  autoReload: true,   // Auto-reload on file change (default: false)
  encoding: 'utf-8'   // File encoding (default: 'utf-8')
});

📖 API Documentation

Constructor

new ProxyAgent(proxyFilePath, options)

Parameters:

proxyFilePath (string): Path to proxy file (default: 'proxies.txt')
options (object): Configuration options

Options:

random (boolean): Use random proxy selection instead of sequential
log (boolean): Enable/disable logging
autoReload (boolean): Auto-reload proxy file on changes
encoding (string): File encoding for reading proxy file

Methods

`config()`

Returns axios configuration object with proxy agents configured.

const response = await axios.get('https://example.com', proxy.config());

`https()`

Returns HTTPS proxy agent for manual configuration.

const httpsAgent = proxy.https();
const response = await axios.get('https://example.com', { httpsAgent });

`http()`

Returns HTTP proxy agent for manual configuration.

const httpAgent = proxy.http();

`test(testUrl, timeout)`

Test proxy connectivity and measure response time.

const result = await proxy.test('https://httpbin.org/ip', 5000);
console.log(result);
// { success: true, proxy: '192.168.1.1:8080', time: 245, data: {...} }

`list()`

Get information about all loaded proxies.

const proxies = proxy.list();
console.log(proxies);
// [{ index: 0, ip: '192.168.1.1', port: 8080, hasAuth: false, protocol: 'http' }]

`stats()`

Get proxy agent statistics.

const stats = proxy.stats();
console.log(stats);
// {
//   total: 10,
//   auth: 5,
//   noAuth: 5,
//   current: 2,
//   random: false,
//   file: '/path/to/proxies.txt',
//   autoReload: false
// }

`reload()`

Manually reload proxies from file.

proxy.reload();

`destroy()`

Clean up resources and stop file watching.

proxy.destroy();

💡 Usage Examples

Basic Rotation

const ProxyAgent = require('@nexon.js/proxy-agent');
const axios = require('axios');

const proxy = new ProxyAgent('./proxies.txt');

// Each request uses the next proxy in rotation
for (let i = 0; i < 5; i++) {
  try {
    const response = await axios.get('https://httpbin.org/ip', proxy.config());
    console.log(`Request ${i + 1}:`, response.data.origin);
  } catch (error) {
    console.error(`Request ${i + 1} failed:`, error.message);
  }
}

Error Handling & Retry

async function robustRequest(url, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await axios.get(url, {
        ...proxy.config(),
        timeout: 10000
      });
      return response.data;
    } catch (error) {
      console.log(`Attempt ${attempt} failed:`, error.message);

      if (attempt === maxRetries) {
        throw new Error(`All ${maxRetries} attempts failed`);
      }

      // Wait before retry with different proxy
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
}

// Usage
try {
  const data = await robustRequest('https://api.example.com/data');
  console.log(data);
} catch (error) {
  console.error('Request failed after all retries:', error.message);
}

Axios Instance Integration

const axiosWithProxy = axios.create({
  timeout: 15000,
  headers: {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
  }
});

// Add proxy rotation to every request
axiosWithProxy.interceptors.request.use(config => {
  const proxyConfig = proxy.config();
  config.httpsAgent = proxyConfig.httpsAgent;
  config.httpAgent = proxyConfig.httpAgent;
  config.proxy = false;
  return config;
});

// Now all requests automatically use rotating proxies
const response = await axiosWithProxy.get('https://api.example.com/data');

Health Checking

// Test all proxies and filter working ones
const proxy = new ProxyAgent('./proxies.txt');
const workingProxies = [];

for (const proxy of proxy.list()) {
  const result = await proxy.test();
  if (result.success) {
    workingProxies.push({
      ...proxy,
      responseTime: result.time
    });
    console.log(`✅ ${proxy.ip}:${proxy.port} - ${result.time}ms`);
  } else {
    console.log(`❌ ${proxy.ip}:${proxy.port} - ${result.error}`);
  }
}

console.log(`Found ${workingProxies.length} working proxies`);

🔧 Proxy File Formats

The library supports multiple proxy formats:

`txt

Basic format (ip:port)

192.168.1.1:8080 proxy.example.com:3128

With authentication (ip:port:username:password)

192.168.1.2:8080:user123:password123 proxy.example.com:3128

Package detail