@rynn-k/proxy-agent
Version:
Efficient proxy rotation agent for Node.js with seamless axios integration
273 lines (211 loc) • 6.77 kB
Markdown
# @rynn-k/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
```bash
npm install @rynn-k/proxy-agent
```
## 🔧 Quick Start
### 1. Create Proxy File
Create `proxies.txt` with your proxy list:
```txt
# 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
```javascript
const ProxyAgent = require('@rynn-k/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
```javascript
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
```javascript
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.
```javascript
const response = await axios.get('https://example.com', proxy.config());
```
#### `https()`
Returns HTTPS proxy agent for manual configuration.
```javascript
const httpsAgent = proxy.https();
const response = await axios.get('https://example.com', { httpsAgent });
```
#### `http()`
Returns HTTP proxy agent for manual configuration.
```javascript
const httpAgent = proxy.http();
```
#### `test(testUrl, timeout)`
Test proxy connectivity and measure response time.
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
proxy.reload();
```
#### `destroy()`
Clean up resources and stop file watching.
```javascript
proxy.destroy();
```
## 💡 Usage Examples
### Basic Rotation
```javascript
const ProxyAgent = require('@rynn-k/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
```javascript
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
```javascript
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
```javascript
// 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