Proxy Support

Rezo supports routing requests through HTTP, HTTPS, SOCKS4, and SOCKS5 proxies. You can set a proxy at the instance level or per-request, with full support for authentication credentials.

Quick Start

Pass a proxy URL string to any request:

import { Rezo } from 'rezo';

const rezo = new Rezo();

const response = await rezo.get('https://httpbin.org/ip', {
  proxy: 'http://proxy.example.com:8080'
});

console.log(response.data);

Proxy Protocols

Rezo supports four proxy protocols:

Proxy URL String

The simplest way to configure a proxy is with a URL string:

// HTTP proxy
await rezo.get(url, { proxy: 'http://proxy.example.com:3128' });

// SOCKS5 proxy
await rezo.get(url, { proxy: 'socks5://proxy.example.com:1080' });

// With authentication in the URL
await rezo.get(url, { proxy: 'http://user:password@proxy.example.com:3128' });

Proxy Options Object

For more control, pass a ProxyOptions object:

await rezo.get('https://httpbin.org/ip', {
  proxy: {
    protocol: 'http',
    host: 'proxy.example.com',
    port: 8080
  }
});

With Authentication

await rezo.get('https://httpbin.org/ip', {
  proxy: {
    protocol: 'socks5',
    host: 'proxy.example.com',
    port: 1080,
    auth: {
      username: 'myuser',
      password: 'mypassword'
    }
  }
});

Instance-Level Proxy

Set a default proxy for all requests from a Rezo instance:

const rezo = new Rezo({
  proxy: 'http://proxy.example.com:8080'
});

// All requests use the proxy
await rezo.get('https://api.example.com/data');
await rezo.post('https://api.example.com/submit', { foo: 'bar' });

You can override or disable the instance proxy on individual requests:

const rezo = new Rezo({
  proxy: 'http://default-proxy.example.com:8080'
});

// Use a different proxy for this request
await rezo.get('https://api.example.com/data', {
  proxy: 'socks5://special-proxy.example.com:1080'
});

SOCKS5 Proxies

SOCKS5 proxies are commonly used for tunneling traffic, including Tor:

// Standard SOCKS5 proxy
await rezo.get('https://httpbin.org/ip', {
  proxy: 'socks5://127.0.0.1:1080'
});

// SOCKS5 with authentication
await rezo.get('https://httpbin.org/ip', {
  proxy: {
    protocol: 'socks5',
    host: '127.0.0.1',
    port: 1080,
    auth: {
      username: 'proxyuser',
      password: 'proxypass'
    }
  }
});

Tor Example

Route traffic through the Tor network using its default SOCKS5 interface:

const rezo = new Rezo({
  proxy: 'socks5://127.0.0.1:9050'
});

// Check your Tor exit IP
const response = await rezo.get('https://check.torproject.org/api/ip');
console.log('Tor exit IP:', response.data.IP);

// Browse .onion services
const onion = await rezo.get('http://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion');

SOCKS4 Proxies

SOCKS4 proxies work similarly but do not support authentication or DNS resolution through the proxy:

await rezo.get('https://httpbin.org/ip', {
  proxy: 'socks4://proxy.example.com:1080'
});

TLS Verification with Proxies

When connecting through HTTPS proxies to HTTPS destinations, you may need to control certificate verification:

await rezo.get('https://internal-api.corp.example.com/data', {
  proxy: 'https://corporate-proxy.example.com:8443',
  rejectUnauthorized: false // Skip certificate verification (development only)
});

Warning: Disabling rejectUnauthorized in production creates a security risk. Only use this for development or when connecting to internal services with self-signed certificates.

Proxy String Parsing

Rezo accepts proxy strings in several formats and parses them automatically:

// Standard URL format
'http://proxy.example.com:8080'

// With credentials
'http://user:pass@proxy.example.com:8080'

// SOCKS5 with credentials
'socks5://user:pass@127.0.0.1:1080'

// Host:port:user:pass format
'proxy.example.com:8080:user:pass'

// Host:port format
'proxy.example.com:8080'

Combining with ProxyManager

For advanced use cases involving proxy rotation, health monitoring, and pool management, see the ProxyManager documentation. ProxyManager automatically selects proxies for each request and can be combined with the per-request proxy option:

import { Rezo, ProxyManager } from 'rezo';

const rezo = new Rezo({
  proxyManager: new ProxyManager({
    rotation: 'random',
    proxies: [
      'http://proxy1.example.com:8080',
      'http://proxy2.example.com:8080',
      'socks5://proxy3.example.com:1080'
    ]
  })
});

// ProxyManager automatically selects a proxy for each request
await rezo.get('https://api.example.com/data');

// Bypass ProxyManager for a specific request
await rezo.get('https://internal.example.com/health', {
  useProxyManager: false
});