nexus-proxy-pub

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #go #android #machine-learning #docker #macos #java #kubernetes #security #open-source

nexus-proxy-pub

(★ 20)

No description available.

nexus-proxy-pub Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nexus-Proxy

High-performance multi-provider proxy gateway written in Rust. Routes proxy requests through upstream residential proxy providers (IPRoyal, Bright Data, NetNut, etc.) with intelligent session management, load balancing, and comprehensive monitoring.

## Features

- **Multi-Provider Support**: Route through multiple upstream proxy providers
- **Session Management**: Sticky sessions with consistent hashing, rotating sessions
- **Country Routing**: Route requests to specific countries via `-cc-XX` suffix
- **Plan-Based Routing**: Different proxy plans on different ports (SOLVE:1000, SCALE:2000, OPUS:3000, MOBILE:4000)
- **Traffic Multiplier System (TMS)**: Per-user bandwidth tracking and limiting
- **Prometheus Metrics**: Comprehensive metrics for monitoring
- **High Concurrency**: Handles 20k+ concurrent connections with proper backpressure
- **Handshake Semaphore**: Prevents upstream provider overload by limiting concurrent handshakes

## Architecture

```
┌─────────────┐      ┌──────────────┐      ┌────────────────┐
│   Clients   │ ───► │  Nexus-Proxy │ ───► │ Upstream Proxy │
│             │      │  (Rust/Tokio)│      │ (IPRoyal etc.) │
└─────────────┘      └──────────────┘      └────────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  PostgreSQL  │
                     │  (Users/Plans)│
                     └──────────────┘
```

## Critical Performance Insight

**The Handshake Semaphore** (v4.4) is critical for stability under high load:

```rust
// The semaphore covers the ENTIRE handshake phase:
// TCP Connect → CONNECT send → Wait for TTFB (first byte)
const MAX_CONCURRENT_HANDSHAKES: usize = 1000;
```

Without this, thousands of connections pile up waiting for upstream response, causing timeout storms.

## Prerequisites

- Rust 1.70+ with Cargo
- PostgreSQL 14+
- An upstream proxy provider account (IPRoyal, Bright Data, etc.)

## Quick Start

### 1. Clone and Build

```bash
git clone <repository>
cd nexus-proxy
cargo build --release
```

### 2. Database Setup

```bash
# Create database and user
sudo -u postgres psql << 'EOF'
CREATE DATABASE nexus_proxy;
CREATE USER nexus_proxy WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE nexus_proxy TO nexus_proxy;
EOF

# Run migrations
psql -U nexus_proxy -d nexus_proxy -f migrations/001_initial_schema.sql
psql -U nexus_proxy -d nexus_proxy -f migrations/002_providers_plans.sql
# ... run all migrations in order
```

### 3. Configuration

Copy and edit the example files:

```bash
cp config.example.json config.json
cp env.example .env
```

Edit `config.json` with your upstream proxy credentials:

```json
{
  "id": "SCALE",
  "name": "Scale Plan",
  "port": 2000,
  "upstream_proxies": [
    {
      "countries": ["US", "CA", "GB"],
      "upstream_addr": "geo.iproyal.com:12321",
      "username": "your_iproyal_username",
      "password": "your_iproyal_password",
      "probability": 1.0
    }
  ]
}
```

Edit `.env`:

```bash
DATABASE_URL=postgres://nexus_proxy:your_password@localhost:5432/nexus_proxy
RUST_LOG=nexus_proxy=info,rocket=warn
CONFIG_PATH=config.json
```

### 4. Run

```bash
# Development
cargo run --release

# Production (with systemd)
sudo cp nexus-proxy.service.example /etc/systemd/system/nexus-proxy.service
# Edit the service file with your paths and credentials
sudo systemctl daemon-reload
sudo systemctl enable nexus-proxy
sudo systemctl start nexus-proxy
```

## Usage

### Proxy Authentication

```
username: {user}-cc-{COUNTRY}
password: {user_password}
```

Examples:
```bash
# US proxy
curl -x http://myuser-cc-US:mypassword@localhost:2000 https://api.ipify.org

# Sticky session (same IP)
curl -x http://myuser-cc-US-session-abc123:mypassword@localhost:2000 https://api.ipify.org

# Rotating session (new IP each request)
curl -x http://myuser-cc-US:mypassword@localhost:2000 https://api.ipify.org
```

### API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/metrics` | GET | Prometheus metrics |
| `/api/users` | GET | List all users |
| `/api/users/{username}` | GET | Get user details |
| `/api/admin/users` | POST | Create user |
| `/api/admin/reload` | POST | Reload configuration |

## Configuration Reference

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `RUST_LOG` | Logging level | `info` |
| `CONFIG_PATH` | Path to config.json | `config.json` |

### Tuning Parameters (src/proxy.rs)

```rust
const MAX_CONCURRENT_HANDSHAKES: usize = 1000;  // Concurrent upstream handshakes
const HANDSHAKE_ACQUIRE_TIMEOUT_SECS: u64 = 5;  // Queue timeout
const TCP_CONNECT_TIMEOUT_SECS: u64 = 5;        // TCP connect timeout
const UPSTREAM_READ_TIMEOUT_SECS: u64 = 10;     // TTFB timeout
```

### Kernel Tuning (recommended for production)

```bash
# /etc/sysctl.conf
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15
net.ipv4.ip_local_port_range = 1024 65535
net.core.rmem_max = 268435456
net.core.wmem_max = 268435456
```

## Monitoring

### Real-time OS Monitoring

```bash
./os_signal_monitor.sh localhost 180 3
```

Shows:
- TX/RX bandwidth (Mbps)
- Kernel drops, softnet drops
- File descriptors, socket states
- TTFB (Time to First Byte)
- Error types (reset/timeout/503)

### Key Prometheus Metrics

| Metric | Description |
|--------|-------------|
| `nexus_proxy_semaphore_permits_in_use` | Active handshakes |
| `nexus_proxy_provider_ttfb_seconds` | Time to first byte histogram |
| `nexus_proxy_provider_errors_by_type_total` | Errors by type |
| `nexus_proxy_requests_completed_total` | Request completion |

## Troubleshooting

### High Latency Under Load

1. Check `nexus_proxy_semaphore_permits_in_use` - if consistently at max, increase `MAX_CONCURRENT_HANDSHAKES`
2. Check `upstream_read_timeout` errors - indicates upstream provider overload
3. Check TTFB metrics - high p99 indicates upstream slowness

### Connection Timeouts

1. Verify upstream proxy credentials
2. Check network connectivity to upstream
3. Review `UPSTREAM_READ_TIMEOUT_SECS` setting

### "Too many open files"

1. Increase `LimitNOFILE` in systemd service
2. Apply kernel tuning parameters

## Project Structure

```
nexus-proxy/
├── src/
│   ├── main.rs           # Entry point, runtime setup
│   ├── proxy.rs          # Core proxy logic, handshake semaphore
│   ├── metrics.rs        # Prometheus metrics
│   ├── config.rs         # Configuration parsing
│   ├── cache/            # In-memory caching
│   ├── data/             # Database layer
│   ├── api/              # REST API endpoints
│   └── models/           # Data models
├── migrations/           # SQL migrations
├── config.example.json   # Example configuration
├── env.example           # Example environment
└── os_signal_monitor.sh  # Monitoring script
```

## License

## Support

For issues or questions, contact the development team.

nexus-proxy-pub

nexus-proxy-pub Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

nexus-proxy-pub

nexus-proxy-pub Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README