Ultra Proxy

A high-performance, production-ready video streaming proxy built with TypeScript and Node.js. Ultra Proxy is designed to be faster, more reliable, and more feature-rich than traditional streaming proxies.

🚀 Features

• High Performance: Connection pooling, intelligent caching, and optimized HTTP client
• Scalability: Built-in clustering support for multi-core systems
• Security: Rate limiting, input validation, CORS support, and security headers
• Reliability: Robust error handling, retry mechanisms, and graceful degradation
• Monitoring: Comprehensive logging, metrics, and health checks
• Caching: Intelligent caching with TTL and size limits
• Compression: Automatic response compression for better performance
• Streaming: Efficient handling of video segments and playlists
• Docker: Production-ready Docker containerization

📋 Requirements

• Node.js 18.0.0 or higher
• npm or yarn
• Docker (optional, for containerized deployment)

🛠️ Installation

1. Clone and install dependencies:

   git clone https://github.com/friday2su/Ultra-Proxy.git
   cd ultra-proxy
   npm install

2. Build the application:

   npm run build

3. Start in development mode:

   npm run dev

4. Start in production mode:

   npm start

🐳 Docker Deployment

1. Build and run with Docker Compose:

   docker-compose up --build

2. Build manually:

   docker build -t ultra-proxy .
   docker run -p 3000:3000 ultra-proxy

⚙️ Configuration

Copy .env.example to .env and modify the values:

cp .env.example .env

Key Configuration Options:

• Server: Port, host, connection limits, timeouts
• Security: Rate limiting, CORS origins, allowed domains
• Performance: Caching, compression settings
• Logging: Log level, format, request logging
• Retry: Retry attempts and delays

📡 API Endpoints

M3U8 Proxy

GET /api/m3u8-proxy?url=<encoded_url>&headers=<encoded_headers>
GET /m3u8-proxy.m3u8?url=<encoded_url>&headers=<encoded_headers> (legacy)

TS Proxy

GET /api/ts-proxy?url=<encoded_url>&headers=<encoded_headers>
GET /ts-proxy.ts?url=<encoded_url>&headers=<encoded_headers> (legacy)

System Endpoints

GET /health          # Health check
GET /metrics         # System metrics
GET /                # API documentation

🔧 Usage Examples

Basic M3U8 Proxy

curl "http://localhost:3000/api/m3u8-proxy?url=https%3A%2F%2Fexample.com%2Fplaylist.m3u8"

With Custom Headers

curl "http://localhost:3000/api/m3u8-proxy?url=https%3A%2F%2Fexample.com%2Fplaylist.m3u8&headers=%7B%22Authorization%22%3A%22Bearer%20token%22%7D"

TS Segment Proxy

curl "http://localhost:3000/api/ts-proxy?url=https%3A%2F%2Fexample.com%2Fsegment_0.ts"

📊 Performance Features

Connection Pooling

• HTTP/HTTPS agent pooling for connection reuse
• Configurable maximum connections
• Keep-alive connections for better performance

Intelligent Caching

• In-memory caching with TTL
• Cache size limits
• Content-type aware caching
• Automatic cache invalidation

Compression

• Automatic gzip/deflate compression
• Configurable compression thresholds
• Client preference detection

Clustering

• Automatic multi-core utilization
• Worker process management
• Graceful worker restarts

🔒 Security Features

Rate Limiting

• Configurable request limits per time window
• IP-based rate limiting
• Custom rate limit rules

Input Validation

• URL validation and sanitization
• Header validation
• Request size limits

Security Headers

• XSS protection
• Content type sniffing protection
• Frame options
• Referrer policy

📈 Monitoring

Logging

• Structured JSON logging
• Request/response logging
• Performance metrics
• Error tracking

Metrics

• System resource usage
• Request statistics
• Cache performance
• Response times

Health Checks

• Application health status
• Dependency checks
• Resource utilization

🏗️ Architecture

ultra-proxy/
├── src/
│   ├── routes/          # API route handlers
│   ├── middleware/      # Express middleware
│   ├── services/        # Business logic services
│   ├── utils/          # Utility functions
│   └── types/          # TypeScript type definitions
├── logs/               # Application logs
├── dist/               # Compiled JavaScript
└── docker-compose.yml  # Docker orchestration

🧪 Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

📝 Environment Variables

Variable	Description	Default
PORT	Server port	3000
HOST	Server host	0.0.0.0
MAX_CONNECTIONS	Maximum concurrent connections	1000
CACHE_ENABLED	Enable caching	true
CACHE_TTL	Cache time-to-live (ms)	300000
RATE_LIMIT_MAX_REQUESTS	Max requests per window	1000
LOG_LEVEL	Logging level	info
COMPRESSION_ENABLED	Enable response compression	true

🚀 Production Deployment

1. Environment Setup:

   export NODE_ENV=production
   export PORT=3000
   export LOG_LEVEL=warn

2. Process Management:

   # Using PM2
   npm install -g pm2
   pm2 start dist/index.js --name ultra-proxy
   
   # Using systemd
   sudo cp ultra-proxy.service /etc/systemd/system/
   sudo systemctl enable ultra-proxy
   sudo systemctl start ultra-proxy

3. Reverse Proxy:

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://localhost:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆚 Comparison with ng-proxy

Feature	ng-proxy	Ultra Proxy
Performance	Basic	High (connection pooling, caching)
Scalability	Single-threaded	Multi-core clustering
Security	Basic	Advanced (rate limiting, validation)
Monitoring	Console logs	Structured logging + metrics
Caching	None	Intelligent caching
Error Handling	Basic	Robust with retries
Docker	Basic	Production-ready
Configuration	Environment only	Comprehensive config system

🆘 Troubleshooting

Common Issues:

1. High Memory Usage:

   • Check cache size limits
   • Monitor with /metrics endpoint
   • Adjust MAX_CONNECTIONS setting

2. Rate Limiting:

   • Check rate limit configuration
   • Monitor with logs
   • Adjust limits in .env

3. Connection Errors:

   • Verify target URLs are accessible
   • Check network connectivity
   • Review retry configuration

Debug Mode:

NODE_ENV=development npm run dev

📞 Support

• Create an issue on GitHub
• Check the logs in logs/ directory
• Use /health and /metrics endpoints for diagnostics