balance

module
v0.0.0-...-07b3874 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 21, 2025 License: Apache-2.0

README

Balance Logo

Balance

⚖️ A High-Performance Load Balancer Written in Go

CI Go Report Card codecov Go Version

Distribute traffic efficiently with intelligent load balancing algorithms

Features • Installation • Quick Start • Documentation • Contributing

🚀 Features

Balance is a production-ready load balancer that offers:

🎯 Load Balancing Algorithms
  • Round Robin - Distribute requests evenly across all servers
  • Weighted Round Robin - Assign different weights to servers based on capacity
  • Least Connections - Route to server with fewest active connections
  • Weighted Least Connections - Combine connection count with server weights
  • Consistent Hashing - Session persistence through hash-based routing
  • Bounded Consistent Hashing - Consistent hashing with configurable virtual nodes
  • Session Affinity - Sticky sessions based on client IP or cookies
🏥 Health Checking

  • Active Health Checks - Periodic probing of backend servers

    • Configurable intervals and timeouts
    • HTTP/TCP health check support
    • Worker pool-based concurrent checking
    • Automatic unhealthy node removal

  • Passive Health Checks - Monitor real traffic patterns

    • Failure tracking and circuit breaking
    • Configurable failure thresholds
    • Automatic recovery mechanisms
    • Time-bucketed failure analysis
🔒 Security Features
  • Rate Limiting - Token bucket algorithm for request throttling
  • IP Whitelisting/Blacklisting - Control access by IP address
  • TLS/SSL Support - Secure connections with certificate management
  • Security Manager - Centralized security policy enforcement
🌐 Protocol Support
  • HTTP/HTTPS - Full HTTP reverse proxy with header manipulation
  • TCP - Raw TCP connection forwarding
  • HTTP/2 - Modern protocol support
⚙️ Advanced Features
  • Dynamic Configuration - YAML-based configuration with hot reload support
  • Connection Pooling - Efficient connection reuse
  • Graceful Shutdown - Clean termination without dropping connections
  • Metrics & Monitoring - Built-in observability
  • Cross-Platform - Linux, macOS, Windows support

📋 Table of Contents

📦 Installation

Using Go Install
go install github.com/utkarsh5026/balance/cmd/balance@latest
Build from Source
# Clone the repository
git clone https://github.com/utkarsh5026/balance.git
cd balance

# Build using Makefile
make build

# Or build manually
go build -o balance ./cmd/balance
Pre-built Binaries

Download the latest release for your platform from the Releases page.

🚀 Quick Start

1. Create a Configuration File

Create a config.yaml file:

mode: http
listen: :8080

balance:
  strategy: round-robin
  nodes:
    - address: localhost:8081
      weight: 1
    - address: localhost:8082
      weight: 2
    - address: localhost:8083
      weight: 1

health:
  active:
    enabled: true
    interval: 10s
    timeout: 5s
    unhealthy_threshold: 3
  passive:
    enabled: true
    max_failures: 5
    failure_window: 60s
2. Run Balance
./balance -config config.yaml
3. Test It Out
# Send requests to your load balancer
curl http://localhost:8080

# Requests will be distributed across your backend servers

⚙️ Configuration

Balance uses YAML configuration files. Here's a comprehensive example:

# Server mode: "http" or "tcp"
mode: http

# Address to listen on
listen: :8080

# Load balancing configuration
balance:
  strategy: weighted-round-robin  # round-robin, least-connections, consistent-hash, etc.

  # Backend nodes
  nodes:
    - address: backend1:8081
      weight: 3
      max_connections: 1000
    - address: backend2:8082
      weight: 2
      max_connections: 500
    - address: backend3:8083
      weight: 1
      max_connections: 250

  # Session affinity (optional)
  affinity:
    enabled: true
    cookie_name: BALANCEID
    ttl: 3600s

# Health check configuration
health:
  active:
    enabled: true
    interval: 10s
    timeout: 5s
    healthy_threshold: 2
    unhealthy_threshold: 3
    path: /health          # For HTTP health checks

  passive:
    enabled: true
    max_failures: 5
    failure_window: 60s
    recovery_time: 30s

# Security configuration
security:
  rate_limit:
    enabled: true
    requests_per_second: 100
    burst: 200

  ip_filter:
    enabled: true
    whitelist:
      - 192.168.1.0/24
      - 10.0.0.0/8
    blacklist:
      - 203.0.113.0/24

# TLS configuration (optional)
tls:
  enabled: true
  cert_file: /path/to/cert.pem
  key_file: /path/to/key.pem
  min_version: TLS12
Configuration Examples

Check the config/examples/ directory for more configuration examples:

🎯 Load Balancing Algorithms

Round Robin

Distributes requests evenly across all healthy backend servers.

balance:
  strategy: round-robin

Best for: Servers with similar capacity and uniform request patterns.

Weighted Round Robin

Routes requests based on assigned weights, sending more traffic to higher-capacity servers.

balance:
  strategy: weighted-round-robin
  nodes:
    - address: powerful-server:8080
      weight: 5
    - address: standard-server:8080
      weight: 1

Best for: Heterogeneous server configurations.

Least Connections

Routes to the server with the fewest active connections.

balance:
  strategy: least-connections

Best for: Long-lived connections or varying request durations.

Consistent Hashing

Uses consistent hashing for session persistence and cache efficiency.

balance:
  strategy: consistent-hash
  hash_key: client_ip  # or cookie, header, etc.
  virtual_nodes: 150

Best for: Stateful applications and caching scenarios.

Session Affinity

Binds client sessions to specific backend servers.

balance:
  strategy: round-robin  # Base strategy
  affinity:
    enabled: true
    cookie_name: SESSION_ID
    ttl: 3600s

Best for: Applications requiring session state.

🏥 Health Checking

Active Health Checks

Balance periodically probes backend servers to verify availability.

health:
  active:
    enabled: true
    interval: 10s              # Check every 10 seconds
    timeout: 5s                # Timeout after 5 seconds
    healthy_threshold: 2       # 2 successes to mark healthy
    unhealthy_threshold: 3     # 3 failures to mark unhealthy
    path: /health              # HTTP path to check
    expected_status: 200       # Expected HTTP status

Features:

  • 🔄 Concurrent health checking with worker pools
  • 📊 Configurable thresholds
  • 🚦 Automatic node state management
  • ⚡ Non-blocking health checks
Passive Health Checks

Monitors real traffic to detect failures.

health:
  passive:
    enabled: true
    max_failures: 5            # Max failures before marking unhealthy
    failure_window: 60s        # Time window for failure counting
    recovery_time: 30s         # Time before retry

Features:

  • 🎯 Real-time failure detection
  • 📈 Time-bucketed failure tracking
  • 🔁 Automatic recovery
  • 💡 Circuit breaker pattern

🔒 Security

Rate Limiting

Protect your backend from overload with token bucket rate limiting.

security:
  rate_limit:
    enabled: true
    requests_per_second: 100   # Sustained rate
    burst: 200                 # Burst capacity
IP Filtering

Control access with IP whitelists and blacklists.

security:
  ip_filter:
    enabled: true
    whitelist:
      - 192.168.1.0/24
      - 10.0.0.0/8
    blacklist:
      - 198.51.100.0/24
TLS/SSL

Secure connections with TLS termination.

tls:
  enabled: true
  cert_file: /path/to/cert.pem
  key_file: /path/to/key.pem
  min_version: TLS12
  cipher_suites:
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

💻 Development

Prerequisites
  • Go 1.25.1 or higher
  • Make (optional, for using Makefile)
Development Setup
# Clone the repository
git clone https://github.com/utkarsh5026/balance.git
cd balance

# Install development tools
make install-tools

# Run tests
make test

# Run with race detector
make test-race

# Check code quality
make check

# Run security scans
make security
Makefile Commands

Balance includes a comprehensive Makefile for development:

make help              # Show all available commands
make build             # Build the binary
make test              # Run all tests
make run               # Run with example config
make ci                # Run full CI pipeline locally
make pre-commit        # Pre-commit checks
make security          # Security scans

See MAKEFILE_GUIDE.md for detailed documentation.

Running Tests
# All tests with coverage
make test

# Short tests (skip integration)
make test-short

# Integration tests only
make test-integration

# Benchmarks
make bench

# Coverage report
make coverage
Code Quality
# Format code
make fmt

# Run linters
make lint

# Static analysis
make staticcheck

# All quality checks
make check

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Balance                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │   Security   │    │    Router    │    │    Health    │ │
│  │   Manager    │───▶│              │◀───│   Checker    │ │
│  └──────────────┘    └──────────────┘    └──────────────┘ │
│         │                    │                    │         │
│         │                    │                    │         │
│  ┌──────▼────────────────────▼────────────────────▼──────┐ │
│  │              Load Balancer Engine                      │ │
│  │  ┌────────────────────────────────────────────────┐   │ │
│  │  │  Strategy: RR / LeastConn / Hash / Affinity    │   │ │
│  │  └────────────────────────────────────────────────┘   │ │
│  └────────────────────────────────────────────────────────┘ │
│                           │                                  │
│         ┌─────────────────┼─────────────────┐               │
│         │                 │                 │               │
│  ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐      │
│  │  Backend 1  │   │  Backend 2  │   │  Backend 3  │      │
│  │  (Healthy)  │   │  (Healthy)  │   │ (Unhealthy) │      │
│  └─────────────┘   └─────────────┘   └─────────────┘      │
└─────────────────────────────────────────────────────────────┘
Key Components
  • Router - Request routing and distribution
  • Load Balancer - Algorithm implementation
  • Health Checker - Active and passive health monitoring
  • Security Manager - Rate limiting and IP filtering
  • Connection Pool - Efficient connection management
  • Node Manager - Backend server lifecycle management

⚡ Benchmarks

Performance benchmarks on a standard development machine:

goos: windows
goarch: amd64
pkg: github.com/utkarsh5026/balance/pkg/balance

BenchmarkRoundRobin-8           1000000    1045 ns/op    0 B/op    0 allocs/op
BenchmarkWeightedRR-8            500000    2134 ns/op   16 B/op    1 allocs/op
BenchmarkLeastConn-8             300000    3876 ns/op   32 B/op    2 allocs/op
BenchmarkConsistentHash-8        200000    6542 ns/op   64 B/op    3 allocs/op

Run benchmarks locally:

make bench

🗺️ Roadmap

Balance is under active development. Planned features:

v0.2.0 (Next Release)
  • 📊 Prometheus metrics exporter
  • 🔍 Enhanced observability and tracing
  • 🌐 gRPC support
  • 📝 Access logging with rotation
  • 🔄 Dynamic backend registration/removal
v0.3.0
  • 🎛️ Admin API for runtime configuration
  • 📈 Real-time dashboard
  • 🐳 Kubernetes service discovery
  • 🔐 OAuth2/OIDC authentication
  • 🌍 Geo-routing capabilities
Future
  • WebSocket support
  • Layer 4 (TCP/UDP) load balancing enhancements
  • Machine learning-based routing
  • Multi-region support
  • Plugin system for custom algorithms

See ROADMAP.md for detailed plans.

📊 Status

⚠️ Development Status: Balance is currently in active development and not yet recommended for production use. APIs may change between versions.

Current Version: v0.1.0-alpha Go Version: 1.25.1 License: MIT

What's Working

✅ All load balancing algorithms ✅ Active and passive health checks ✅ Security features (rate limiting, IP filtering) ✅ HTTP and TCP modes ✅ TLS support ✅ Configuration management

In Progress

🚧 Metrics and monitoring 🚧 Admin API 🚧 Documentation completion 🚧 Production hardening

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

How to Contribute
  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (make test)
  5. Run CI locally (make ci)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request
Development Workflow
# Before committing
make pre-commit

# Before pushing
make pre-push

# Run full CI pipeline
make ci
Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with ❤️ using Go
  • Inspired by industry-standard load balancers (HAProxy, NGINX)
  • Thanks to all contributors

📞 Contact & Support

⭐ Star History

If you find Balance useful, please consider giving it a star! ⭐

Made with ⚖️ by utkarsh5026

Star History Chart

Directories

Path Synopsis
cmd
balance command
pkg
balance
conf
health
node
proxy
router
security
transport

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.