A production-ready proxy server with intelligent load balancing and health monitoring
A production-ready Python proxy server and pool manager with intelligent load balancing, health monitoring, and enterprise-grade features. Built for high-performance proxy rotation similar to HAProxy but specifically designed for proxy management.
/stats and /health endpointsproxy-fleet supports multiple proxy protocols. Here's a comprehensive comparison and selection guide:
| Protocol | Layer | Traffic Support | Auth | IPv6 | DNS Resolution | Speed | Security | Complexity |
|---|---|---|---|---|---|---|---|---|
| HTTP | Application | HTTP/HTTPS | Basic/Digest | Yes | Client/Proxy | Slower (parsing overhead) | Content inspection/modification | Simple |
| SOCKS4 | Session | TCP only | None | No | Client | Fast | Basic forwarding | Simple |
| SOCKS5 | Session | TCP/UDP | Multiple | Yes | Proxy | Fast | Encrypted auth support | Medium |
proxy-fleet's enhanced proxy server provides:
Current Implementation:
# Start proxy-fleet server
proxy-fleet --enhanced-proxy-server --proxy-server-port 8888
# Use proxy-fleet as HTTP proxy
curl --proxy http://127.0.0.1:8888 http://httpbin.org/ip
curl -x http://127.0.0.1:8888 https://httpbin.org/ip
# With verbose output
curl -v --proxy http://127.0.0.1:8888 http://httpbin.org/get
HTTP Proxy:
# Basic usage
curl --proxy http://proxy-server:port http://example.com
# With authentication
curl --proxy http://username:password@proxy-server:port http://example.com
# Alternative syntax
curl -x http://proxy-server:port http://example.com
SOCKS4 Proxy:
# Basic usage
curl --socks4 proxy-server:port http://example.com
# With user specification (rarely needed)
curl --socks4 username@proxy-server:port http://example.com
SOCKS5 Proxy:
# Basic usage
curl --socks5 proxy-server:port http://example.com
# With authentication
curl --socks5 username:password@proxy-server:port http://example.com
# Force hostname resolution through proxy
curl --socks5-hostname proxy-server:port http://example.com
Advanced curl Options:
# Exclude specific domains from proxy
curl --proxy http://proxy:port --noproxy localhost,127.0.0.1 http://example.com
# Show detailed connection information
curl -v --proxy http://proxy:port http://example.com
# Set proxy timeout
curl --proxy http://proxy:port --connect-timeout 30 http://example.com
pip install proxy-fleet
The enhanced proxy server is the recommended way to use proxy-fleet in production:
# 1. Validate and store some proxies
curl -sL 'https://raw.githubusercontent.com/TheSpeedX/SOCKS-List/master/socks5.txt' | proxy-fleet --test-proxy-server - --concurrent 50
# 2. Generate default configuration
proxy-fleet --generate-config
# 3. Start the enhanced proxy server
proxy-fleet --enhanced-proxy-server --proxy-server-port 8989
# 4. Test the server
curl --proxy http://127.0.0.1:8989 http://httpbin.org/ip
Key Benefits:
proxy-fleet provides comprehensive proxy management through its CLI:
# Validate proxies from file
proxy-fleet --test-proxy-server proxies.txt
# Validate from stdin with high concurrency
curl -sL 'https://raw.githubusercontent.com/TheSpeedX/SOCKS-List/master/socks5.txt' | \
proxy-fleet --test-proxy-server - --concurrent 100 --test-proxy-timeout 10 --test-proxy-type socks5
curl -sL 'https://raw.githubusercontent.com/TheSpeedX/SOCKS-List/master/socks4.txt' | \
proxy-fleet --test-proxy-server - --concurrent 100 --test-proxy-timeout 10 --test-proxy-type socks4
curl -sL 'https://raw.githubusercontent.com/TheSpeedX/SOCKS-List/master/http.txt' | \
proxy-fleet --test-proxy-server - --concurrent 100 --test-proxy-timeout 10 --test-proxy-type http
# Test with HTTP request validation
proxy-fleet --test-proxy-server proxies.txt --test-proxy-with-request 'https://httpbin.org/ip'
# Test with custom API that returns location info
# The tool will automatically extract 'country' field, or fallback to 'region' field
# Only proxies returning 2XX or 3XX status codes are considered valid
proxy-fleet --test-proxy-server proxies.txt --test-proxy-with-request 'https://myserver.com/api/location'
# Test existing proxies in storage
proxy-fleet --test-proxy-storage
# List all proxy status
proxy-fleet --list-proxy
# List only verified/valid proxies
proxy-fleet --list-proxy-verified
# List only failed/invalid proxies
proxy-fleet --list-proxy-failed
# Remove failed proxies from storage
proxy-fleet --remove-proxy-failed
# Start basic proxy server with round-robin rotation
proxy-fleet --start-proxy-server --proxy-server-port 8888
# Start with random rotation
proxy-fleet --start-proxy-server --proxy-server-rotation random
# Generate configuration file
proxy-fleet --generate-config
# Start enhanced server with default settings
proxy-fleet --enhanced-proxy-server
# Start with specific strategy and multiple workers
proxy-fleet --enhanced-proxy-server \
--proxy-server-strategy least_connections \
--proxy-server-workers 8 \
--proxy-server-host 0.0.0.0
# Start with custom configuration file
proxy-fleet --enhanced-proxy-server --proxy-server-config my_config.json
# Development mode (single process)
proxy-fleet --enhanced-proxy-server --single-process
proxy-fleet --enhanced-proxy-server --proxy-server-strategy least_connections
Routes requests to the proxy with the fewest active connections.
proxy-fleet --enhanced-proxy-server --proxy-server-strategy response_time
Routes requests to the proxy with the best average response time.
proxy-fleet --enhanced-proxy-server --proxy-server-strategy round_robin
Distributes requests evenly across all available proxies.
proxy-fleet --enhanced-proxy-server --proxy-server-strategy random
Randomly selects an available proxy for each request.
Configure proxy weights in the configuration file:
{
"load_balancing": {
"strategy": "weighted",
"strategies": {
"weighted": {
"proxy_weights": {
"fast-proxy.com:1080": 3.0,
"medium-proxy.com:1080": 2.0,
"slow-proxy.com:1080": 1.0
}
}
}
}
}
Configure primary and backup proxies:
{
"load_balancing": {
"strategy": "fail_over",
"strategies": {
"fail_over": {
"primary_proxies": ["primary1.com:1080", "primary2.com:1080"],
"backup_proxies": ["backup1.com:1080", "backup2.com:1080"]
}
}
}
}
For high-traffic production environments:
proxy-fleet --enhanced-proxy-server \
--proxy-server-workers 8 \
--proxy-server-strategy least_connections \
--proxy-server-host 0.0.0.0 \
--proxy-server-port 8888
proxy-fleet supports hot-reloading of proxy pools without server restart using API endpoints:
The most efficient and controlled way to update proxy pools:
# Force refresh proxy pool from storage (no external requests)
curl http://127.0.0.1:8888/refresh
# Force refresh with immediate health check (minimal external requests)
curl "http://127.0.0.1:8888/refresh?health_check=true"
# Check current status
curl http://127.0.0.1:8888/stats | jq .rotator_stats
Key Benefits:
For controlled proxy validation and hot-reload without overwhelming third-party services:
# 1. Start the enhanced proxy server
proxy-fleet --enhanced-proxy-server --proxy-server-port 8888
# 2. When needed, validate proxy health in a separate terminal
# This updates the proxy storage with fresh health data
proxy-fleet --test-proxy-storage --test-proxy-with-request 'https://httpbin.org/ip'
# 3. Force the running server to reload from updated storage
curl "http://127.0.0.1:8888/refresh?health_check=true"
# 4. Verify the refresh worked
curl http://127.0.0.1:8888/stats | jq .rotator_stats
For minimal automated monitoring without overloading external services:
{
"health_checks": {
"enabled": true,
"interval": 86400,
"timeout": 15,
"max_failures": 5,
"test_url": "http://httpbin.org/ip"
}
}
Note:
/refresh API for immediate updates when neededCreate a controlled refresh script for periodic validation:
#!/bin/bash
# refresh-proxies.sh - Run this manually or via cron when needed
echo "Starting proxy refresh at $(date)"
# Re-validate all proxies in storage with rate limiting
proxy-fleet --test-proxy-storage \
--test-proxy-with-request 'https://httpbin.org/ip' \
--concurrent 10 \
--test-proxy-timeout 15
# Tell running server to reload the proxy pool
result=$(curl -s "http://127.0.0.1:8888/refresh?health_check=false")
echo "Refresh result: $result"
echo "Proxy pool refreshed at $(date)"
Best Practices for External Services:
httpbin.org/ip instead of ipinfo.io for basic connectivity tests--concurrent 10 instead of 50+)/refresh API endpoint to reload without external requests/refresh API to hot-reload updated proxy data# Get real-time statistics
curl http://127.0.0.1:8888/stats | jq .
# Health check endpoint
curl http://127.0.0.1:8888/health
# Force refresh proxy pool from storage (without restarting server)
curl http://127.0.0.1:8888/refresh
# Force refresh with immediate health check
curl "http://127.0.0.1:8888/refresh?health_check=true"
# Monitor proxy performance
watch -n 1 'curl -s http://127.0.0.1:8888/stats | jq .rotator_stats.proxy_details'
{
"requests_total": 1000,
"requests_success": 950,
"requests_failed": 50,
"uptime_seconds": 3600,
"rotator_stats": {
"strategy": "least_connections",
"total_proxies": 10,
"healthy_proxies": 8,
"proxy_details": {
"proxy1.com:1080": {
"active_connections": 5,
"total_requests": 120,
"success_rate": 0.95,
"avg_response_time": 0.8,
"is_healthy": true
}
}
},
"worker_stats": {
"total_workers": 4,
"active_workers": 4
}
}
proxy-fleet --generate-config
This creates a proxy_server_config.json file with comprehensive default settings.
For production environments with conservative health checking, see proxy_server_config_production.json which includes:
httpbin.org vs third-party services){
"proxy_server": {
"host": "127.0.0.1",
"port": 8888,
"workers": 4,
"graceful_shutdown_timeout": 30,
"access_log": true
},
"load_balancing": {
"strategy": "least_connections",
"strategies": {
"weighted": {
"proxy_weights": {}
},
"fail_over": {
"primary_proxies": [],
"backup_proxies": []
}
}
},
"health_checks": {
"enabled": true,
"interval": 86400,
"timeout": 15,
"max_failures": 5,
"parallel_checks": 5,
"test_url": "http://httpbin.org/ip"
},
"circuit_breaker": {
"enabled": true,
"failure_threshold": 5,
"recovery_timeout": 300,
"half_open_max_calls": 3
},
"logging": {
"level": "INFO",
"format": "detailed",
"file": null
}
}
host: Server bind address (default: 127.0.0.1)port: Server port (default: 8888)workers: Number of worker processes (default: CPU count)graceful_shutdown_timeout: Graceful shutdown timeout in secondsaccess_log: Enable access loggingstrategy: Load balancing strategy (least_connections, round_robin, random, weighted, response_time, fail_over)strategies: Strategy-specific configurationsenabled: Enable automatic health checkinginterval: Health check interval in seconds (default: 86400 = 24 hours)timeout: Health check timeoutmax_failures: Maximum failures before marking proxy unhealthyparallel_checks: Number of parallel health checkstest_url: URL for health checks (use httpbin.org/ip for basic tests)enabled: Enable circuit breaker patternfailure_threshold: Failures before opening circuitrecovery_timeout: Time before attempting recoveryhalf_open_max_calls: Max calls in half-open statefrom proxy_fleet.cli.main import ProxyStorage
from proxy_fleet.server.enhanced_proxy_server import EnhancedHTTPProxyServer
# Initialize proxy storage
storage = ProxyStorage("./proxy_data")
# Add some proxies
storage.update_proxy_status("proxy1.com", 1080, True)
storage.update_proxy_status("proxy2.com", 1080, True)
# Start enhanced proxy server
config_file = "proxy_server_config.json"
server = EnhancedHTTPProxyServer(config_file)
await server.start()
from proxy_fleet.utils.socks_validator import SocksValidator
# Create validator with HTTP request validation
validator = SocksValidator(
timeout=10,
check_server_via_request=True,
request_url="https://httpbin.org/ip"
)
# Create validator without HTTP request validation (basic validation only)
validator = SocksValidator(timeout=10)
# Validate a proxy
result = validator.validate_socks5("proxy.example.com", 1080)
print(f"Valid: {result.is_valid}, IP: {result.ip_info}")
# Async validation
result = await validator.async_validate_socks5("proxy.example.com", 1080)
from proxy_fleet.server.enhanced_proxy_server import EnhancedProxyRotator
# Create rotator with configuration
config = {
"load_balancing": {"strategy": "least_connections"},
"health_checks": {"enabled": True, "interval": 60}
}
rotator = EnhancedProxyRotator("./proxy_data", config)
# Get next proxy
proxy_info, stats = await rotator.get_next_proxy()
print(f"Using proxy: {proxy_info['host']}:{proxy_info['port']}")
# Record request result
await rotator.record_request_result(
proxy_info['host'],
proxy_info['port'],
success=True,
response_time=0.5
)
proxy-fleet/
├── proxy_fleet/
│ ├── cli/ # Command-line interface
│ │ └── main.py # CLI implementation and ProxyStorage
│ ├── server/ # Proxy server implementations
│ │ ├── enhanced_proxy_server.py # Enhanced server with load balancing
│ │ └── proxy_server.py # Basic proxy server
│ ├── utils/ # Utility modules
│ │ ├── socks_validator.py # SOCKS proxy validation
│ │ ├── proxy_utils.py # Proxy utility functions
│ │ └── output.py # Output formatting
│ └── models/ # Data models
│ ├── proxy.py # Proxy data models
│ ├── config.py # Configuration models
│ └── task.py # Task models
├── tests/ # Test suite
│ ├── test_core.py # Core functionality tests
│ ├── integration_test_script.py # Integration tests
│ └── manual_socks_test_script.py # SOCKS validation tests
├── examples/ # Usage examples
├── proxy/ # Default proxy storage directory
└── proxy_server_config.json # Default configuration file
┌─────────────────────────────────────────────────────────────┐
│ Load Balancer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Proxy Rotator │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Strategy │ │ Health Check│ │Circuit Break│ │
│ │ Manager │ │ Manager │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Proxy Pool │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Proxy 1 │ │ Proxy 2 │ │ Proxy N │ │
│ │ + Stats │ │ + Stats │ │ + Stats │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
The enhanced proxy server is designed for high performance:
least_connections for balanced load distribution127.0.0.1 for local-only accessGET /stats - Real-time statistics and metricsGET /health - Health check endpoint for load balancersGET /refresh - Force refresh proxy pool from storage (hot-reload)GET /refresh?health_check=true - Refresh proxy pool and perform immediate health checkproxy-fleet provides comprehensive logging:
# Configure logging level
{
"logging": {
"level": "INFO",
"format": "detailed",
"file": "/var/log/proxy-fleet.log"
}
}
Easily integrate with monitoring systems:
# Prometheus-style metrics
curl http://127.0.0.1:8888/stats | jq .
# Custom monitoring
curl -s http://127.0.0.1:8888/stats | python my_monitor.py
We welcome contributions! Please see our Contributing Guide for details.
# Clone the repository
git clone https://github.com/your-org/proxy-fleet.git
cd proxy-fleet
# Install development dependencies
python dev.py install
# Run tests
python dev.py test
# Run with coverage
python dev.py test-cov
# Format code
python dev.py format
# Lint code
python dev.py lint
The project includes comprehensive test coverage:
# Run all tests
python dev.py test
# Run specific test categories
pytest tests/test_core.py -v
pytest tests/integration_test_script.py -v
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ for the proxy management community.
FAQs
A production-ready proxy server with intelligent load balancing and health monitoring
We found that proxy-fleet demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
North Korean threat actors deploy 67 malicious npm packages using the newly discovered XORIndex malware loader.
Security News
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600× faster than humans.