{"id":47277734,"url":"https://github.com/openloadbalancer/olb","last_synced_at":"2026-04-16T12:00:39.406Z","repository":{"id":344487712,"uuid":"1181212128","full_name":"OpenLoadBalancer/olb","owner":"OpenLoadBalancer","description":"High-performance zero-dependency L4/L7 load balancer written in Go. Single binary with Web UI, clustering, MCP/AI integration. 8.5K RPS, 39 E2E tests.","archived":false,"fork":false,"pushed_at":"2026-04-10T20:12:45.000Z","size":13146,"stargazers_count":18,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T22:11:18.323Z","etag":null,"topics":["acme","clustering","go","golang","l4","l7","load-balancer","mcp","raft","rate-limiting","reverse-proxy","tls","waf","web-ui","zero-dependency"],"latest_commit_sha":null,"homepage":"https://openloadbalancer.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenLoadBalancer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":"DCO","cla":null},"funding":{"github":["openloadbalancer"],"open_collective":"openloadbalancer"}},"created_at":"2026-03-13T21:45:38.000Z","updated_at":"2026-04-10T20:12:50.000Z","dependencies_parsed_at":"2026-03-15T09:03:34.730Z","dependency_job_id":"2eb62289-829d-48d9-bdcb-277abd693a17","html_url":"https://github.com/OpenLoadBalancer/olb","commit_stats":null,"previous_names":["ersinkoc/openloadbalancer","openloadbalancer/olb"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/OpenLoadBalancer/olb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLoadBalancer%2Folb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLoadBalancer%2Folb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLoadBalancer%2Folb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLoadBalancer%2Folb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenLoadBalancer","download_url":"https://codeload.github.com/OpenLoadBalancer/olb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLoadBalancer%2Folb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31884929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["acme","clustering","go","golang","l4","l7","load-balancer","mcp","raft","rate-limiting","reverse-proxy","tls","waf","web-ui","zero-dependency"],"created_at":"2026-03-15T19:52:25.187Z","updated_at":"2026-04-16T12:00:39.398Z","avatar_url":"https://github.com/OpenLoadBalancer.png","language":"Go","readme":"# OpenLoadBalancer\n\n\u003e **Minimal-dependency L4/L7 load balancer for any backend.** One binary. Written in pure Go.\n\u003e Only stdlib + golang.org/x/{crypto,net,text} — no external frameworks.\n\u003e Works with Node.js, Python, Java, Go, Rust, .NET, PHP — anything that speaks HTTP or TCP.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"olb.jpeg\" alt=\"OpenLoadBalancer\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://openloadbalancer.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/web-openloadbalancer.dev-blue\" alt=\"Website\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/openloadbalancer/olb/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/openloadbalancer/olb\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://golang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-1.26+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"./\"\u003e\u003cimg src=\"https://img.shields.io/badge/coverage-95.3%25-brightgreen\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"./\"\u003e\u003cimg src=\"https://img.shields.io/badge/deps-3_(x/crypto,x/net,x/text)-orange\" alt=\"Minimal Deps\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\ncurl -sSL https://openloadbalancer.dev/install.sh | sh\n```\n\nCreate `olb.yaml` (or run `olb setup` for an interactive wizard):\n\n```yaml\nadmin:\n  address: \"127.0.0.1:8081\"\n\nlisteners:\n  - name: http\n    address: \":80\"\n    routes:\n      - path: /\n        pool: web\n\npools:\n  - name: web\n    algorithm: round_robin\n    backends:\n      - address: \"10.0.1.10:8080\"\n      - address: \"10.0.1.11:8080\"\n    health_check:\n      type: http\n      path: /health\n      interval: 10s\n```\n\n```bash\nolb start --config olb.yaml\n```\n\nThat's it. HTTP proxy on `:80`, admin API on `:8081`, health checks every 10s, round-robin across two backends.\n\n## Install\n\n```bash\n# Linux / macOS\ncurl -sSL https://openloadbalancer.dev/install.sh | sh\n\n# Windows (PowerShell)\nirm https://openloadbalancer.dev/install.ps1 | iex\n\n# Docker (GHCR)\ndocker pull ghcr.io/openloadbalancer/olb:latest\ndocker run -d -p 80:80 -p 8081:8081 \\\n  -v ./olb.yaml:/etc/olb/configs/olb.yaml \\\n  ghcr.io/openloadbalancer/olb:latest\n\n# Homebrew\nbrew tap openloadbalancer/olb \u0026\u0026 brew install olb\n\n# Build from source\ngit clone https://github.com/openloadbalancer/olb.git \u0026\u0026 cd olb \u0026\u0026 make build\n```\n\nRequires Go 1.26+. Only stdlib + golang.org/x/{crypto,net,text}.\n\n## Features\n\n**Proxy:** HTTP/HTTPS, WebSocket, gRPC, SSE, TCP (L4), UDP (L4), SNI routing, PROXY protocol v1/v2, Request Shadowing/Mirroring\n\n**Load Balancing:** 16 algorithms — Round Robin, Weighted RR, Least Connections, Weighted Least Connections, Least Response Time, Weighted Least Response Time, IP Hash, Consistent Hash (Ketama), Maglev, Ring Hash, Power of Two, Random, Weighted Random, Rendezvous Hash, Peak EWMA, Sticky Sessions\n\n**Geo-DNS Routing:** Geographic location-based traffic routing (country, region, city)\n\n**Security:** TLS termination + SNI, ACME/Let's Encrypt, mTLS, OCSP stapling, 6-layer WAF (IP ACL, rate limiting, request sanitizer, detection engine with SQLi/XSS/path traversal/CMDi/XXE/SSRF, bot detection with JA3 fingerprinting, response protection with security headers + data masking), circuit breaker\n\n**Middleware:** 16 components — Recovery, body limit, WAF (6-layer pipeline), IP filter, real IP, request ID, timeout, rate limit, circuit breaker, CORS, headers, compression (gzip), retry, cache, metrics, access log\n\n**Observability:** Web UI dashboard (8 pages), TUI (`olb top`), Prometheus metrics, structured JSON logging, admin REST API (15+ endpoints), Grafana dashboard\n\n**Operations:** Hot config reload (SIGHUP or API), Raft clustering + SWIM gossip, service discovery (Static/DNS/Consul/Docker/File), MCP server for AI integration, plugin system, 30+ CLI commands, distributed rate limiting, request shadowing/mirroring\n\n## MCP Integration (AI-Powered Management)\n\nOpenLoadBalancer includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that enables AI agents (Claude, GPT, Copilot) to monitor, diagnose, and manage the load balancer.\n\n### Transport\n- **SSE** (Server-Sent Events): `GET /sse` for streaming + `POST /message` for commands — MCP spec compliant\n- **HTTP POST**: `POST /mcp` for simple request/response (backwards compatible)\n- **Stdio**: Line-delimited JSON-RPC over stdin/stdout for local CLI tools\n\n### Authentication\n```yaml\nadmin:\n  mcp_address: \":8082\"\n  mcp_token: \"your-secret-token\"   # Bearer token auth\n  mcp_audit: true                   # Log all tool calls\n```\n\n### 17 MCP Tools\n\n| Category | Tools |\n|----------|-------|\n| **Metrics** | `olb_query_metrics` — RPS, latency, error rates, connections |\n| **Backends** | `olb_list_backends`, `olb_modify_backend` — Add, remove, drain, enable/disable |\n| **Routes** | `olb_modify_route` — Add, update, remove routes with traffic splitting |\n| **Diagnostics** | `olb_diagnose` — Automated error/latency/capacity/health analysis |\n| **Config** | `olb_get_config`, `olb_get_logs`, `olb_cluster_status` |\n| **WAF** | `waf_status`, `waf_add_whitelist`, `waf_add_blacklist`, `waf_remove_whitelist`, `waf_remove_blacklist`, `waf_list_rules`, `waf_get_stats`, `waf_get_top_blocked_ips`, `waf_get_attack_timeline` |\n\n### Connect from Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"olb\": {\n      \"url\": \"http://localhost:8082/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secret-token\"\n      }\n    }\n  }\n}\n```\n\n## Performance\n\nBenchmarked on AMD Ryzen 9 9950X3D:\n\n| Metric | Result |\n|--------|--------|\n| Peak RPS | **15,480** (10 concurrent, round_robin) |\n| Proxy overhead | **137µs** (direct: 87µs → proxied: 223µs) |\n| RoundRobin.Next | **3.5 ns/op**, 0 allocs |\n| Middleware overhead | **\u003c 3%** (full stack vs none) |\n| WAF overhead (6-layer) | **~35μs** per request, **\u003c 3%** at proxy scale |\n| Binary size | **~13 MB** |\n| P99 latency (50 conc.) | **22ms** |\n| Success rate | **100%** across all tests |\n\n\u003cdetails\u003e\n\u003csummary\u003eAlgorithm comparison (1000 req, 50 concurrent)\u003c/summary\u003e\n\n| Algorithm | RPS | Avg Latency | Distribution |\n|-----------|-----|-------------|-------------|\n| random | 12,913 | 3.5ms | 32/34/34% |\n| maglev | 11,597 | 3.8ms | 68/2/30% |\n| ip_hash | 11,062 | 4.0ms | 75/12/13% |\n| power_of_two | 10,708 | 4.0ms | 34/33/33% |\n| least_connections | 10,119 | 4.4ms | 33/33/34% |\n| consistent_hash | 8,897 | 4.6ms | 0/0/100% |\n| weighted_rr | 8,042 | 5.6ms | 33/33/34% |\n| round_robin | 7,320 | 6.3ms | 35/33/32% |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFull benchmark report\u003c/summary\u003e\n\nSee [docs/benchmark-report.md](docs/benchmark-report.md) for the complete report including concurrency scaling, backend latency impact, and middleware overhead measurements.\n\n\u003c/details\u003e\n\n## E2E Verified\n\n56+ end-to-end tests across 70 packages with 95.3% coverage:\n\n| Category | Verified |\n|----------|----------|\n| **Proxy** | HTTP, HTTPS/TLS, WebSocket, SSE, TCP, UDP |\n| **Algorithms** | RR, WRR, LC, IPHash, CH, Maglev, P2C, Random, RingHash |\n| **Middleware** | Rate limit (429), CORS, gzip (98% reduction), WAF 6-layer (SQLi/XSS/CMDi/path traversal → 403, rate limit → 429, monitor mode, security headers, bot detection, IP ACL, data masking), IP filter, circuit breaker, cache (HIT/MISS), headers, retry |\n| **Operations** | Health check (down/recovery), config reload, weighted distribution, session affinity, graceful failover (0 downtime) |\n| **Infra** | Admin API, Web UI, Prometheus, MCP server, multiple listeners |\n| **Performance** | 15K RPS, 137µs proxy overhead, 100% success rate |\n\n## Algorithms\n\n| Algorithm | Config Name | Use Case |\n|-----------|------------|----------|\n| Round Robin | `round_robin` | Default, equal backends |\n| Weighted Round Robin | `weighted_round_robin` | Unequal backend capacity |\n| Least Connections | `least_connections` | Long-lived connections |\n| Least Response Time | `least_response_time` | Latency-sensitive |\n| IP Hash | `ip_hash` | Session affinity by IP |\n| Consistent Hash | `consistent_hash` | Cache locality |\n| Maglev | `maglev` | Google-style hashing |\n| Ring Hash | `ring_hash` | Consistent with vnodes |\n| Power of Two | `power_of_two` | Balanced random |\n| Random | `random` | Simple, no state |\n\n## Configuration\n\nSupports **YAML**, **JSON**, **TOML**, and **HCL** with `${ENV_VAR}` substitution.\n\n```yaml\nadmin:\n  address: \"127.0.0.1:8081\"\n\nmiddleware:\n  rate_limit:\n    enabled: true\n    requests_per_second: 1000\n  cors:\n    enabled: true\n    allowed_origins: [\"*\"]\n  compression:\n    enabled: true\n\nwaf:\n  enabled: true\n  mode: enforce\n  detection:\n    enabled: true\n    threshold: {block: 50, log: 25}\n  bot_detection: {enabled: true, mode: monitor}\n  response:\n    security_headers: {enabled: true}\n\nlisteners:\n  - name: http\n    address: \":8080\"\n    routes:\n      - path: /api\n        pool: api-pool\n      - path: /\n        pool: web-pool\n\npools:\n  - name: web-pool\n    algorithm: round_robin\n    backends:\n      - address: \"10.0.1.10:8080\"\n      - address: \"10.0.1.11:8080\"\n    health_check:\n      type: http\n      path: /health\n      interval: 5s\n\n  - name: api-pool\n    algorithm: least_connections\n    backends:\n      - address: \"10.0.2.10:8080\"\n        weight: 3\n      - address: \"10.0.2.11:8080\"\n        weight: 2\n```\n\nSee [docs/configuration.md](docs/configuration.md) for all options.\n\n### Geo-DNS Routing Example\n\n```yaml\ngeodns:\n  enabled: true\n  default_pool: default-pool\n  rules:\n    - id: us-traffic\n      country: US\n      pool: us-pool\n      fallback: default-pool\n    - id: eu-traffic\n      country: EU\n      pool: eu-pool\n    - id: asia-traffic\n      country: JP\n      region: Tokyo\n      pool: asia-pool\n```\n\n### Request Shadowing Example\n\n```yaml\nshadow:\n  enabled: true\n  percentage: 10.0  # Mirror 10% of traffic\n  copy_headers: true\n  copy_body: false\n  timeout: 30s\n  targets:\n    - pool: staging-pool\n      percentage: 100.0\n```\n\n### Distributed Rate Limiting Example\n\n```yaml\nwaf:\n  enabled: true\n  rate_limit:\n    enabled: true\n    store:\n      type: redis\n      address: \"localhost:6379\"\n      database: 0\n    rules:\n      - id: per-ip\n        scope: ip\n        limit: 1000\n        window: 1m\n```\n\n## CLI\n\n```bash\nolb setup                            # Interactive config wizard\nolb start --config olb.yaml         # Start proxy\nolb stop                             # Graceful shutdown\nolb reload                           # Hot-reload config\nolb status                           # Server status\nolb top                              # Live TUI dashboard\nolb backend list                     # List backends\nolb backend drain web-pool 10.0.1.10:8080\nolb health show                      # Health check status\nolb config validate olb.yaml         # Validate config\nolb cluster status                   # Cluster info\n```\n\n## Architecture\n\n```\n                    ┌─────────────────────────────────────────────────┐\n                    │              OpenLoadBalancer                    │\n  Clients ─────────┤                                                  │\n  HTTP/S, WS,      │  Listeners → Middleware → Router → Balancer → Backends\n  gRPC, TCP, UDP   │  (L4/L7)     (16 types)   (trie)   (16 algos)  │\n                    │                                                  │\n                    │  WAF (6 layers) │ TLS │ Cluster │ MCP │ Web UI  │\n                    │  GeoDNS │ Shadow │ Discovery │ Prometheus      │\n                    └─────────────────────────────────────────────────┘\n```\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/tutorials/getting-started.md) | Step-by-step tutorial |\n| [Configuration](docs/configuration.md) | All config options |\n| [Production Deployment](docs/production-deployment.md) | Production deployment guide |\n| [Troubleshooting](docs/troubleshooting.md) | Troubleshooting playbook |\n| [Migration Guide](docs/migration-guide.md) | Migrate from NGINX/HAProxy/Traefik |\n| [Algorithms](docs/algorithms.md) | Algorithm details |\n| [API Reference](docs/api/openapi.yaml) | OpenAPI/Swagger spec |\n| [Clustering](docs/clustering.md) | Multi-node setup |\n| [WAF](docs/waf.md) | Web Application Firewall (6-layer defense) |\n| [MCP / AI](docs/mcp.md) | AI integration |\n| [Benchmarks](docs/benchmark-report.md) | Performance data |\n| [Specification](docs/SPECIFICATION.md) | Technical spec |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Key rules:\n\n1. **Minimal external deps** — stdlib + golang.org/x/{crypto,net,text} only\n2. **Tests required** — 85% coverage, don't lower it\n3. **All features wired** — no dead code in engine.go\n4. **gofmt + go vet** — CI enforced\n\n## License\n\nApache 2.0 — [LICENSE](LICENSE)\n","funding_links":["https://github.com/sponsors/openloadbalancer","https://opencollective.com/openloadbalancer"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenloadbalancer%2Folb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenloadbalancer%2Folb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenloadbalancer%2Folb/lists"}