{"id":29054164,"url":"https://github.com/paahaad/load-balancer","last_synced_at":"2025-06-27T02:06:24.468Z","repository":{"id":300664116,"uuid":"1006756766","full_name":"paahaad/load-balancer","owner":"paahaad","description":"A high-performance HTTP load balancer implemented in Rust with multiple load balancing algorithms, health checking, and real-time monitoring.","archived":false,"fork":false,"pushed_at":"2025-06-23T00:32:15.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-23T01:19:50.984Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paahaad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T23:58:55.000Z","updated_at":"2025-06-23T00:32:18.000Z","dependencies_parsed_at":"2025-06-23T01:20:06.821Z","dependency_job_id":"b3a95c90-f9cf-427e-9508-477b3b0e97d6","html_url":"https://github.com/paahaad/load-balancer","commit_stats":null,"previous_names":["paahaad/load-balancer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paahaad/load-balancer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paahaad%2Fload-balancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paahaad%2Fload-balancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paahaad%2Fload-balancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paahaad%2Fload-balancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paahaad","download_url":"https://codeload.github.com/paahaad/load-balancer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paahaad%2Fload-balancer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262175237,"owners_count":23270420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T02:06:23.749Z","updated_at":"2025-06-27T02:06:24.460Z","avatar_url":"https://github.com/paahaad.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Load Balancer\n\nA high-performance HTTP load balancer implemented in Rust with multiple load balancing algorithms, health checking, and real-time monitoring.\n\n## Demo\nhttps://github.com/user-attachments/assets/79d51ed8-fb67-4af8-97f5-923e64d76be6\n\n\n\nUploading loom.mp4…\n\n\n\n## 🎯 **Features Implemented**\n\n### **Core Functionality**\n- **HTTP Request Forwarding**: Full HTTP request/response proxying\n- **Multiple Load Balancing Algorithms**:\n  - Round Robin (default)\n  - Least Connections\n  - Random\n  - Weighted Round Robin\n- **Health Checking**: Automatic backend monitoring with configurable intervals\n- **Connection Tracking**: Real-time active connection counting\n\n### **Advanced Features**\n- **Monitoring Endpoints**:\n  - `/lb-health` - Load balancer health status\n  - `/lb-stats` - Detailed statistics and metrics\n- **Custom Headers**: Adds `X-Forwarded-By` and `X-Backend-Server` headers\n- **Command-Line Interface**: Full CLI with help and configuration options\n- **Structured Logging**: Comprehensive logging with tracing\n- **Error Handling**: Graceful handling of backend failures\n\n### **Performance \u0026 Reliability**\n- **Async/Await**: High-performance concurrent request handling\n- **Thread-Safe**: Safe concurrent access to shared state\n- **Automatic Failover**: Removes unhealthy backends from rotation\n- **Auto-Recovery**: Re-enables backends when they become healthy\n\n## Quick Start\n\n### 1. Build the project\n\n```bash\ncargo build --release\n```\n\n### 2. Start test backend servers\n\n```bash\n# Terminal 1 - Backend server on port 3001\nPORT=3001 cargo run --bin test_server\n\n# Terminal 2 - Backend server on port 3002  \nPORT=3002 cargo run --bin test_server\n\n# Terminal 3 - Backend server on port 3003\nPORT=3003 cargo run --bin test_server\n```\n\n### 3. Start the load balancer\n\n```bash\n# Terminal 4 - Load balancer on port 8080\ncargo run --bin load_balancer\n```\n\n### 4. Test the load balancer\n\n```bash\n# Send requests to see load balancing in action\ncurl http://localhost:8080/\n\n# Check load balancer health\ncurl http://localhost:8080/lb-health\n\n# View statistics\ncurl http://localhost:8080/lb-stats\n```\n\n## Configuration\n\n### Command Line Options\n\n```bash\ncargo run --bin load_balancer -- --help\n```\n\n```\nOptions:\n  -p, --port \u003cPORT\u003e                        Port to listen on [default: 8080]\n  -b, --backends \u003cBACKENDS\u003e                Backend server addresses (comma-separated) [default: 127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003]\n  -a, --algorithm \u003cALGORITHM\u003e              Load balancing algorithm [default: round_robin]\n      --health-check-interval \u003cHEALTH_CHECK_INTERVAL\u003e  Health check interval in seconds [default: 30]\n  -h, --help                               Print help\n  -V, --version                            Print version\n```\n\n### Examples\n\n```bash\n# Use least connections algorithm\ncargo run --bin load_balancer -- --algorithm least_connections\n\n# Custom backends and port\ncargo run --bin load_balancer -- --port 9000 --backends \"192.168.1.10:8001,192.168.1.11:8001,192.168.1.12:8001\"\n\n# Random algorithm with frequent health checks\ncargo run --bin load_balancer -- --algorithm random --health-check-interval 10\n```\n\n## Load Balancing Algorithms\n\n### 1. Round Robin (round_robin)\nDistributes requests evenly across all healthy backends in sequential order.\n\n### 2. Least Connections (least_connections)\nRoutes requests to the backend server with the fewest active connections.\n\n### 3. Random (random)\nRandomly selects a healthy backend server for each request.\n\n### 4. Weighted Round Robin (weighted_round_robin)\nSimilar to round robin but considers server weights (currently all servers have equal weight).\n\n## Monitoring Endpoints\n\n### Health Check: `/lb-health`\nReturns the health status of the load balancer and all backend servers.\n\n```json\n{\n  \"status\": \"ok\",\n  \"healthy_backends\": 3,\n  \"total_backends\": 3,\n  \"backends\": [\n    {\n      \"address\": \"127.0.0.1:3001\",\n      \"healthy\": true,\n      \"connections\": 0,\n      \"response_time_ms\": 1\n    }\n  ]\n}\n```\n\n### Statistics: `/lb-stats`\nProvides detailed statistics about the load balancer and backend servers.\n\n```json\n{\n  \"algorithm\": \"RoundRobin\",\n  \"backends\": [\n    {\n      \"address\": \"127.0.0.1:3001\",\n      \"healthy\": true,\n      \"connections\": 2,\n      \"weight\": 1,\n      \"response_time_ms\": 5,\n      \"last_health_check\": 15\n    }\n  ]\n}\n```\n\n## Request Headers\n\nThe load balancer adds the following headers to forwarded requests:\n\n- `X-Forwarded-By: rust-load-balancer` - Identifies the load balancer\n- `X-Backend-Server: \u003cbackend_address\u003e` - Shows which backend handled the request\n\n## Health Checking\n\n- Health checks are performed on the `/health` endpoint of each backend server\n- Configurable interval (default: 30 seconds)\n- Automatic failover when backends become unhealthy\n- Backends are automatically re-enabled when they recover\n\n## Backend Server Requirements\n\nBackend servers should:\n\n1. **Health Endpoint:** Respond to `GET /health` with HTTP 200 for healthy status\n2. **HTTP Protocol:** Support standard HTTP requests and responses\n3. **Port Binding:** Listen on the configured IP address and port\n\n## 🧪 **Test Infrastructure**\n- **Test Server**: Simple backend server for testing (`test_server.rs`)\n- **Multiple Binaries**: Separate binaries for load balancer and test server\n- **JSON Responses**: Structured responses for easy testing\n\n## Development\n\n### Testing\n\n```bash\n# Run tests\ncargo test\n\n# Check for linting issues\ncargo clippy\n\n# Format code\ncargo fmt\n```\n\n### Architecture\n\nThe load balancer is built using:\n\n- **Hyper:** High-performance HTTP server and client\n- **Tokio:** Async runtime for concurrent request handling\n- **Tracing:** Structured logging and diagnostics\n- **Clap:** Command-line argument parsing\n- **Serde:** JSON serialization for monitoring endpoints\n\n## Performance\n\nThe load balancer is designed for high performance:\n\n- Async/await for concurrent request handling\n- Minimal memory allocation during request forwarding\n- Lock-free operation for request routing (minimal mutex usage)\n- Efficient health checking without blocking request processing\n\n## 🚀 **Production Ready**\n\nThis load balancer is production-ready with enterprise-level features:\n\n- **High Performance**: Built with Rust's zero-cost abstractions\n- **Memory Safety**: Rust's ownership system prevents common bugs\n- **Concurrent**: Async/await for handling thousands of concurrent requests\n- **Observable**: Comprehensive logging and monitoring endpoints\n- **Configurable**: CLI-based configuration for deployment flexibility\n- **Resilient**: Automatic failover and recovery mechanisms\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaahaad%2Fload-balancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaahaad%2Fload-balancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaahaad%2Fload-balancer/lists"}