rezo 1.0.3 → 1.0.4

package/README.md

@@ -63,6 +63,7 @@ Rezo is a production-ready HTTP client library engineered for Node.js 22+ and un
 - [Advanced Usage](#advanced-usage)
   - [Cookie Management](#cookie-management)
   - [Proxy Configuration](#proxy-configuration)
+  - [Proxy Manager](#proxy-manager)
   - [Streaming](#streaming)
   - [File Downloads](#file-downloads)
   - [File Uploads](#file-uploads)
@@ -776,6 +777,266 @@ interface ProxyConfig {
 }
 ```
 
+### Proxy Manager
+
+Rezo includes a powerful Proxy Manager for enterprise scenarios requiring proxy rotation, health monitoring, and intelligent failover. The Proxy Manager automatically rotates through a pool of proxies, tracks their health, and removes failing proxies from circulation.
+
+#### Basic Usage
+
+```typescript
+import rezo, { ProxyManager } from 'rezo';
+
+// Create a proxy manager with a pool of proxies
+const proxyManager = new ProxyManager({
+  proxies: [
+    { protocol: 'http', host: 'proxy1.example.com', port: 8080 },
+    { protocol: 'http', host: 'proxy2.example.com', port: 8080 },
+    { protocol: 'socks5', host: 'proxy3.example.com', port: 1080 }
+  ]
+});
+
+// Create client with proxy manager
+const client = rezo.create({
+  proxyManager
+});
+
+// Requests automatically rotate through available proxies
+await client.get('https://api.example.com/data');
+```
+
+#### Rotation Strategies
+
+```typescript
+import { ProxyManager } from 'rezo';
+
+// Random rotation (default) - randomly selects from available proxies
+const randomManager = new ProxyManager({
+  proxies: [...],
+  rotationStrategy: 'random'
+});
+
+// Sequential rotation - cycles through proxies in order
+const sequentialManager = new ProxyManager({
+  proxies: [...],
+  rotationStrategy: 'sequential'
+});
+
+// Per-proxy limit - switches after N requests per proxy
+const limitManager = new ProxyManager({
+  proxies: [...],
+  rotationStrategy: 'per-proxy-limit',
+  perProxyLimit: 100  // Switch after 100 requests
+});
+```
+
+#### URL Filtering (Whitelist/Blacklist)
+
+Control which URLs use the proxy manager with glob patterns or regular expressions:
+
+```typescript
+import { ProxyManager } from 'rezo';
+
+const proxyManager = new ProxyManager({
+  proxies: [...],
+  
+  // Only use proxies for these URL patterns (glob or regex)
+  whitelist: [
+    '*.example.com',           // Glob pattern
+    'https://api.service.io/*',
+    /^https:\/\/secure\./      // Regex pattern
+  ],
+  
+  // Never use proxies for these URLs
+  blacklist: [
+    '*.internal.company.com',
+    'https://localhost/*'
+  ]
+});
+
+const client = rezo.create({ proxyManager });
+
+// Uses proxy (matches whitelist)
+await client.get('https://api.example.com/data');
+
+// Direct connection (matches blacklist)
+await client.get('https://app.internal.company.com/status');
+```
+
+#### Health Monitoring & Failover
+
+The Proxy Manager automatically tracks proxy health and removes failing proxies:
+
+```typescript
+import { ProxyManager } from 'rezo';
+
+const proxyManager = new ProxyManager({
+  proxies: [...],
+  
+  // Mark proxy as dead after 5 consecutive failures
+  maxFailures: 5,
+  
+  // Re-enable dead proxies after 5 minutes cooldown
+  cooldownPeriod: 5 * 60 * 1000,
+  
+  // Fail request if no proxies available (vs direct connection)
+  failWithoutProxy: true
+});
+
+// Check proxy pool status
+const status = proxyManager.getStatus();
+console.log('Active proxies:', status.active);
+console.log('Disabled proxies:', status.disabled);
+console.log('Total proxies:', status.total);
+
+// Check if proxies are available
+if (proxyManager.hasAvailableProxies()) {
+  await client.get('https://api.example.com/data');
+}
+
+// Reset all proxy states (re-enable all)
+proxyManager.reset();
+```
+
+#### Lifecycle Hooks
+
+Monitor and react to proxy events with lifecycle hooks:
+
+```typescript
+import { ProxyManager } from 'rezo';
+
+const proxyManager = new ProxyManager({
+  proxies: [...],
+  
+  hooks: {
+    // Called before selecting a proxy
+    beforeProxySelect: (url) => {
+      console.log('Selecting proxy for:', url);
+    },
+    
+    // Called after proxy selection
+    afterProxySelect: (proxy, url) => {
+      console.log('Selected:', proxy.host);
+    },
+    
+    // Called before reporting a proxy error
+    beforeProxyError: (proxy, error) => {
+      console.log('Proxy failed:', proxy.host, error.message);
+    },
+    
+    // Called after error is recorded
+    afterProxyError: (proxy, error, failureCount) => {
+      console.log('Failure count:', failureCount);
+    },
+    
+    // Called when proxy is disabled
+    afterProxyDisable: (proxy, reason) => {
+      console.log('Proxy disabled:', proxy.host, reason);
+    },
+    
+    // Called when proxy is re-enabled
+    afterProxyEnable: (proxy) => {
+      console.log('Proxy re-enabled:', proxy.host);
+    },
+    
+    // Called after rotation occurs
+    afterProxyRotate: (oldProxy, newProxy) => {
+      console.log('Rotated from', oldProxy?.host, 'to', newProxy.host);
+    }
+  }
+});
+```
+
+#### Instance-Level Hooks
+
+You can also add proxy hooks at the instance level:
+
+```typescript
+import rezo, { ProxyManager } from 'rezo';
+
+const proxyManager = new ProxyManager({ proxies: [...] });
+
+const client = rezo.create({
+  proxyManager,
+  hooks: {
+    afterProxySelect: (proxy, url) => {
+      console.log('Request will use proxy:', proxy.host);
+    },
+    afterProxyDisable: (proxy) => {
+      // Alert monitoring system
+      alertMonitoring('Proxy disabled', proxy.host);
+    }
+  }
+});
+```
+
+#### Manual Proxy Control
+
+Override Proxy Manager for specific requests:
+
+```typescript
+import rezo, { ProxyManager } from 'rezo';
+
+const proxyManager = new ProxyManager({ proxies: [...] });
+const client = rezo.create({ proxyManager });
+
+// Use a specific proxy (bypasses Proxy Manager)
+await client.get('https://api.example.com/data', {
+  proxy: {
+    protocol: 'http',
+    host: 'specific-proxy.example.com',
+    port: 8080
+  }
+});
+
+// Direct connection (bypasses Proxy Manager)
+await client.get('https://api.example.com/data', {
+  useProxyManager: false
+});
+```
+
+#### Proxy Manager Configuration
+
+```typescript
+interface ProxyManagerConfig {
+  // Array of proxy configurations
+  proxies: ProxyConfig[];
+  
+  // Rotation strategy: 'random' | 'sequential' | 'per-proxy-limit'
+  rotationStrategy?: string;
+  
+  // Requests per proxy before rotation (for 'per-proxy-limit')
+  perProxyLimit?: number;
+  
+  // URL patterns to use with proxies (glob or regex)
+  whitelist?: (string | RegExp)[];
+  
+  // URL patterns to bypass proxies (glob or regex)
+  blacklist?: (string | RegExp)[];
+  
+  // Consecutive failures before disabling proxy
+  maxFailures?: number;
+  
+  // Milliseconds before re-enabling disabled proxy
+  cooldownPeriod?: number;
+  
+  // Throw error if no proxy available (vs direct connection)
+  failWithoutProxy?: boolean;
+  
+  // Lifecycle hooks
+  hooks?: ProxyManagerHooks;
+}
+```
+
+#### Adapter Support
+
+| Adapter | Proxy Manager Support |
+|---------|----------------------|
+| HTTP | Full support |
+| HTTP/2 | Full support |
+| cURL | Full support |
+| Fetch | Not supported (browser security) |
+| React Native | Not supported (platform limitations) |
+
 ### Streaming
 
 Rezo provides powerful streaming capabilities for handling large data efficiently.

package/dist/adapters/curl.cjs

@@ -974,11 +974,27 @@ async function executeRequest(options, defaultOptions, jar) {
   if (!options.responseType) {
     options.responseType = "auto";
   }
-  const d_options = await getDefaultConfig(defaultOptions);
+  const d_options = await getDefaultConfig(defaultOptions, defaultOptions._proxyManager);
   const configResult = prepareHTTPOptions(options, jar, { defaultOptions: d_options });
   const config = configResult.config;
   const originalRequest = configResult.fetchOptions;
+  const { proxyManager } = configResult;
   const perform = new RezoPerformance;
+  let selectedProxy = null;
+  if (proxyManager) {
+    const requestUrl = typeof originalRequest.url === "string" ? originalRequest.url : originalRequest.url?.toString() || "";
+    selectedProxy = proxyManager.next(requestUrl);
+    if (selectedProxy) {
+      originalRequest.proxy = {
+        protocol: selectedProxy.protocol,
+        host: selectedProxy.host,
+        port: selectedProxy.port,
+        auth: selectedProxy.auth
+      };
+    } else if (proxyManager.config.failWithoutProxy) {
+      throw new RezoError("No proxy available: All proxies exhausted or URL did not match whitelist/blacklist", config, "UNQ_NO_PROXY_AVAILABLE", originalRequest);
+    }
+  }
   const isStream = options._isStream;
   const isDownload = options._isDownload || !!options.fileName || !!options.saveTo;
   const isUpload = options._isUpload;
@@ -999,11 +1015,38 @@ async function executeRequest(options, defaultOptions, jar) {
   if (eventEmitter) {
     eventEmitter.emit("initiated");
   }
+  if (proxyManager && selectedProxy) {
+    if (streamResponse) {
+      streamResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      streamResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    } else if (downloadResponse) {
+      downloadResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      downloadResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    } else if (uploadResponse) {
+      uploadResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      uploadResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    }
+  }
   const executor = new CurlExecutor;
   try {
     const result = await executor.execute(config, originalRequest, streamResponse, downloadResponse, uploadResponse);
     if (!streamResponse && !downloadResponse && !uploadResponse) {
       const response = result;
+      if (proxyManager && selectedProxy) {
+        proxyManager.reportSuccess(selectedProxy);
+      }
       if (config.retry && response.status >= 400) {
         const maxRetries = config.retry.maxRetries || 0;
         const statusCodes = config.retry.statusCodes || [408, 429, 500, 502, 503, 504];
@@ -1021,6 +1064,9 @@ async function executeRequest(options, defaultOptions, jar) {
     }
     return result;
   } catch (error) {
+    if (proxyManager && selectedProxy) {
+      proxyManager.reportFailure(selectedProxy, error);
+    }
     if (error instanceof RezoError) {
       throw error;
     }

package/dist/adapters/curl.js

@@ -974,11 +974,27 @@ export async function executeRequest(options, defaultOptions, jar) {
   if (!options.responseType) {
     options.responseType = "auto";
   }
-  const d_options = await getDefaultConfig(defaultOptions);
+  const d_options = await getDefaultConfig(defaultOptions, defaultOptions._proxyManager);
   const configResult = prepareHTTPOptions(options, jar, { defaultOptions: d_options });
   const config = configResult.config;
   const originalRequest = configResult.fetchOptions;
+  const { proxyManager } = configResult;
   const perform = new RezoPerformance;
+  let selectedProxy = null;
+  if (proxyManager) {
+    const requestUrl = typeof originalRequest.url === "string" ? originalRequest.url : originalRequest.url?.toString() || "";
+    selectedProxy = proxyManager.next(requestUrl);
+    if (selectedProxy) {
+      originalRequest.proxy = {
+        protocol: selectedProxy.protocol,
+        host: selectedProxy.host,
+        port: selectedProxy.port,
+        auth: selectedProxy.auth
+      };
+    } else if (proxyManager.config.failWithoutProxy) {
+      throw new RezoError("No proxy available: All proxies exhausted or URL did not match whitelist/blacklist", config, "UNQ_NO_PROXY_AVAILABLE", originalRequest);
+    }
+  }
   const isStream = options._isStream;
   const isDownload = options._isDownload || !!options.fileName || !!options.saveTo;
   const isUpload = options._isUpload;
@@ -999,11 +1015,38 @@ export async function executeRequest(options, defaultOptions, jar) {
   if (eventEmitter) {
     eventEmitter.emit("initiated");
   }
+  if (proxyManager && selectedProxy) {
+    if (streamResponse) {
+      streamResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      streamResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    } else if (downloadResponse) {
+      downloadResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      downloadResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    } else if (uploadResponse) {
+      uploadResponse.on("finish", () => {
+        proxyManager.reportSuccess(selectedProxy);
+      });
+      uploadResponse.on("error", (err) => {
+        proxyManager.reportFailure(selectedProxy, err);
+      });
+    }
+  }
   const executor = new CurlExecutor;
   try {
     const result = await executor.execute(config, originalRequest, streamResponse, downloadResponse, uploadResponse);
     if (!streamResponse && !downloadResponse && !uploadResponse) {
       const response = result;
+      if (proxyManager && selectedProxy) {
+        proxyManager.reportSuccess(selectedProxy);
+      }
       if (config.retry && response.status >= 400) {
         const maxRetries = config.retry.maxRetries || 0;
         const statusCodes = config.retry.statusCodes || [408, 429, 500, 502, 503, 504];
@@ -1021,6 +1064,9 @@ export async function executeRequest(options, defaultOptions, jar) {
     }
     return result;
   } catch (error) {
+    if (proxyManager && selectedProxy) {
+      proxyManager.reportFailure(selectedProxy, error);
+    }
     if (error instanceof RezoError) {
       throw error;
     }

package/dist/adapters/entries/curl.cjs

@@ -1,4 +1,31 @@
-const _mod_w60egr = require('../curl.cjs');
-exports.executeCurlRequest = _mod_w60egr.executeRequest;;
-const _mod_jk2wno = require('../http.cjs');
-exports.executeHttpRequest = _mod_jk2wno.executeRequest;;
+const { executeRequest } = require('../curl.cjs');
+const { setGlobalAdapter, createRezoInstance, Rezo } = require('../../core/rezo.cjs');
+const { RezoError, RezoErrorCode } = require('../../errors/rezo-error.cjs');
+const { RezoHeaders } = require('../../utils/headers.cjs');
+const { RezoFormData } = require('../../utils/form-data.cjs');
+const { RezoCookieJar } = require('../../utils/cookies.cjs');
+const { createDefaultHooks, mergeHooks } = require('../../core/hooks.cjs');
+const packageJson = require("../../../package.json");
+
+exports.Rezo = Rezo;
+exports.RezoError = RezoError;
+exports.RezoErrorCode = RezoErrorCode;
+exports.RezoHeaders = RezoHeaders;
+exports.RezoFormData = RezoFormData;
+exports.RezoCookieJar = RezoCookieJar;
+exports.createDefaultHooks = createDefaultHooks;
+exports.mergeHooks = mergeHooks;
+const isRezoError = exports.isRezoError = RezoError.isRezoError;
+const Cancel = exports.Cancel = RezoError;
+const CancelToken = exports.CancelToken = AbortController;
+const isCancel = exports.isCancel = (error) => {
+  return error instanceof RezoError && error.code === "ECONNABORTED";
+};
+const all = exports.all = Promise.all.bind(Promise);
+const spread = exports.spread = (callback) => (array) => callback(...array);
+const VERSION = exports.VERSION = packageJson.version;
+setGlobalAdapter(executeRequest);
+const rezo = createRezoInstance(executeRequest);
+
+exports.default = rezo;
+module.exports = Object.assign(rezo, exports);