smart-proxy-handler

Advanced proxy management for Node.js with automatic rotation, intelligent retry, and multi-endpoint fallback.

Installation

npm install smart-proxy-handler

Features

• Automatic IP rotation (round-robin, random, weighted)
• Retry based on HTTP status codes with exponential backoff
• Multi-endpoint fallback
• Per-proxy health tracking and auto-recovery
• Periodic health checks with configurable intervals
• Full TypeScript support

Quick Start

import { ProxyHandler } from "smart-proxy-handler";

const handler = new ProxyHandler({
  proxies: [
    { host: "proxy1.example.com", port: 8080, protocol: "http" },
    { host: "proxy2.example.com", port: 8080, protocol: "http", weight: 2 },
  ],
  rotationStrategy: "weighted",
  retryConfig: {
    maxAttempts: 3,
    delay: 1000,
    backoffFactor: 2,
    retryOnStatusCodes: [429, 500, 502, 503, 504],
  },
  fallbackEndpoints: ["https://backup-api.example.com"],
  healthCheckInterval: 60000,
  onProxyFailure: (proxy, error) => {
    // handle failure
  },
  onProxySuccess: (proxy, latency) => {
    // handle success
  },
});

const response = await handler.request({
  url: "https://api.example.com/data",
  method: "GET",
  headers: { "Accept": "application/json" },
});

console.log(response.status, response.body);
console.log(`Attempts: ${response.attempts}, Latency: ${response.latency}ms`);

API

new ProxyHandler(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | proxies | ProxyConfig[] | required | List of proxy servers | | rotationStrategy | "round-robin" \| "random" \| "weighted" | "round-robin" | Proxy selection strategy | | retryConfig | Partial<RetryConfig> | see below | Retry configuration | | fallbackEndpoints | string[] | [] | Fallback URLs when all proxies fail | | healthCheckInterval | number | 0 (disabled) | Interval in ms to ping unhealthy proxies | | timeout | number | 30000 | Default request timeout in ms | | onProxyFailure | (proxy, error) => void | - | Callback on proxy failure | | onProxySuccess | (proxy, latency) => void | - | Callback on proxy success |

ProxyConfig

{
  host: string;
  port: number;
  protocol?: "http" | "https" | "socks4" | "socks5";
  auth?: { username: string; password: string };
  weight?: number; // used with "weighted" strategy
}

RetryConfig defaults

{
  maxAttempts: 3,
  delay: 1000,
  backoffFactor: 2,
  retryOnStatusCodes: [429, 500, 502, 503, 504],
  retryOnNetworkErrors: true,
}

handler.request(options)

| Option | Type | Description | |--------|------|-------------| | url | string | Target URL | | method | string | HTTP method (default: GET) | | headers | Record<string, string> | Request headers | | body | string \| Buffer | Request body | | timeout | number | Override default timeout | | skipProxy | boolean | Send request directly without proxy |

Returns a ProxyResponse:

{
  status: number;
  headers: Record<string, string>;
  body: string;
  proxy: ProxyConfig | null;
  latency: number;
  attempts: number;
}

handler.getStats()

Returns an array of ProxyStats for all registered proxies including success/failure counts, average latency, and health status.

handler.destroy()

Stops health check timers and cleans up resources. Always call this when done.

Use Cases

Web Scraping

const handler = new ProxyHandler({
  proxies: residentialProxies,
  rotationStrategy: "random",
  retryConfig: { retryOnStatusCodes: [403, 429, 503] },
});

for (const url of urls) {
  const { body } = await handler.request({ url });
  // parse body
}

Microservices with Fallback

const handler = new ProxyHandler({
  proxies: internalGatewayProxies,
  fallbackEndpoints: [
    "https://region-b.api.internal",
    "https://region-c.api.internal",
  ],
});

API Rate Limit Handling

const handler = new ProxyHandler({
  proxies: ipPool,
  retryConfig: {
    retryOnStatusCodes: [429],
    delay: 2000,
    backoffFactor: 3,
  },
});

Running Tests

npm install
npm test
npm test -- --coverage

License

MIT