go-balancer

README

Go Load Balancer

A high-performance, production-ready HTTP load balancer written in Go. Features multiple load balancing strategies, health checking, metrics, and more.

✨ Features

• Multiple Load Balancing Strategies

  • Round Robin
  • Least Connections
  • Random
  • Weighted Round Robin
  • IP Hash

• Sticky Sessions (Session Affinity)

  • Cookie-based sticky sessions
  • IP hash-based sticky sessions
  • Configurable session TTL
  • Automatic session cleanup

• Health Checking

  • Automatic backend health monitoring
  • Configurable check intervals
  • Automatic failure detection and recovery

• Production Ready

  • Reverse proxy with proper request forwarding
  • Graceful shutdown
  • Request/response logging
  • Error handling and recovery
  • CORS support
  • Rate limiting

• Metrics & Monitoring

  • Real-time statistics endpoint
  • Request tracking
  • Connection monitoring
  • Response time measurement
  • Success rate calculation
  • Session statistics

• Easy Deployment

  • Docker support
  • Docker Compose for full stack
  • Command-line configuration
  • Minimal dependencies

📦 Installation

# Clone the repository
git clone https://github.com/TaiTitans/go-balancer.git
cd go-balancer

# Install dependencies
go mod download

# Build
go build -o go-balancer cmd/main.go

🚀 Quick Start

Start Backend Servers

# Terminal 1
cd examples/backend-server
go run main.go -port 8081 -name "Backend-1"

# Terminal 2
go run main.go -port 8082 -name "Backend-2"

# Terminal 3
go run main.go -port 8083 -name "Backend-3"

Start Load Balancer

# Terminal 4
go run cmd/main.go \
  -port 8080 \
  -backends "http://localhost:8081,http://localhost:8082,http://localhost:8083" \
  -strategy roundrobin

Test It

# Send requests
curl http://localhost:8080

# View statistics
curl http://localhost:8080/stats

# Health check
curl http://localhost:8080/health

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Test
curl http://localhost:8080

📖 Usage

Command Line Options

go-balancer [options]

Options:
  -port int
        Load balancer port (default 8080)
  -backends string
        Comma-separated list of backend URLs
        (default "http://localhost:8081,http://localhost:8082,http://localhost:8083")
  -strategy string
        Load balancing strategy: roundrobin, leastconnections, random
        (default "roundrobin")
  -health-interval duration
        Health check interval (default 10s)
  -health-timeout duration
        Health check timeout (default 5s)
  -sticky-session bool
        Enable sticky sessions (default false)
  -sticky-mode string
        Sticky session mode: cookie, iphash (default "cookie")
  -sticky-cookie string
        Cookie name for sticky sessions (default "BALANCER_SESSION_ID")
  -sticky-ttl duration
        Sticky session TTL (default 30m)

Sticky Sessions Example

# Enable cookie-based sticky sessions
go run cmd/main.go \
  -port 8080 \
  -backends "http://localhost:8081,http://localhost:8082,http://localhost:8083" \
  -strategy roundrobin \
  -sticky-session=true \
  -sticky-mode=cookie \
  -sticky-ttl=1h

# Enable IP hash sticky sessions
go run cmd/main.go \
  -port 8080 \
  -backends "http://localhost:8081,http://localhost:8082,http://localhost:8083" \
  -strategy leastconnections \
  -sticky-session=true \
  -sticky-mode=iphash

Programmatic Usage

package main

import (
    "context"
    "time"

    "github.com/TaiTitans/go-balancer/balancer"
    "github.com/TaiTitans/go-balancer/strategy"
)

func main() {
    config := balancer.Config{
        BackendURLs: []string{
            "http://localhost:8081",
            "http://localhost:8082",
            "http://localhost:8083",
        },
        Strategy:            strategy.NewRoundRobin(),
        HealthCheckInterval: 10 * time.Second,
        HealthCheckTimeout:  5 * time.Second,
    }

    lb, err := balancer.NewLoadBalancer(config)
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    lb.Start(ctx)

    // Use lb as http.Handler
    http.ListenAndServe(":8080", lb)
}

🎯 Load Balancing Strategies

Round Robin

Distributes requests evenly across all healthy backends in a circular order.

strategy := strategy.NewRoundRobin()

Least Connections

Routes requests to the backend with the fewest active connections.

strategy := strategy.NewLeastConnections()

Random

Randomly selects a healthy backend for each request.

strategy := strategy.NewRandom()

Weighted Round Robin

Distributes requests based on backend weights.

weights := map[*backend.Backend]int{
    backend1: 3,  // 3x more requests
    backend2: 2,
    backend3: 1,
}
strategy := strategy.NewWeightedRoundRobin(weights)

📊 Statistics Endpoint

Access /stats to view load balancer statistics:

╔════════════════════════════════════════╗
║   Load Balancer Statistics             ║
╚════════════════════════════════════════╝

Strategy:         RoundRobin
Uptime:           1h23m45s
Total Backends:   3
Alive Backends:   3
Total Requests:   15234
Failed Requests:  12
Success Rate:     99.92%
Active Connections: 5

Sticky Sessions:
  Mode:           cookie
  Active Sessions: 42
  TTL:            30m0s
  Cookie Name:    BALANCER_SESSION_ID

Backend Details:
════════════════════════════════════════

[1] http://localhost:8081
    Status:       ✓ Healthy
    Connections:  2
    Response Time: 15ms
    Fail Count:   0

[2] http://localhost:8082
    Status:       ✓ Healthy
    Connections:  1
    Response Time: 12ms
    Fail Count:   0

[3] http://localhost:8083
    Status:       ✓ Healthy
    Connections:  2
    Response Time: 18ms
    Fail Count:   0

🧪 Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./backend
go test ./strategy
go test ./balancer

# Benchmark
go test -bench=. ./...

📁 Project Structure

go-balancer/
├── backend/          # Backend server management
├── balancer/         # Main load balancer logic
├── cmd/              # Main application entry point
├── config/           # Configuration management
├── examples/         # Example applications
│   ├── backend-server/
│   └── simple/
├── healthcheck/      # Health checking logic
├── middleware/       # HTTP middleware
├── session/          # Sticky session management
├── strategy/         # Load balancing strategies
├── Dockerfile        # Docker configuration
├── docker-compose.yml
├── go.mod
├── go.sum
├── LICENSE
├── Makefile
└── README.md

🔧 Configuration

Environment Variables

export BACKEND_URLS="http://localhost:8081,http://localhost:8082"
export LB_STRATEGY="leastconnections"
export LB_PORT="8080"
export HEALTH_CHECK_INTERVAL="10s"
export STICKY_SESSION="true"
export STICKY_MODE="cookie"

Configuration File

See config.example.yaml for a complete example.

server:
  port: 8080
  readTimeout: 15s
  writeTimeout: 15s

backends:
  - url: http://localhost:8081
    weight: 3
  - url: http://localhost:8082
    weight: 2
  ],
  "healthCheck": {
    "interval": "10s",
    "timeout": "5s"
  },
  "strategy": {
    "type": "roundrobin"
  },
  "stickySession": {
    "enabled": true,
    "mode": "cookie",
    "cookieName": "BALANCER_SESSION_ID",
    "ttl": "30m"
  }
}

📚 Documentation

• API Documentation
• Deployment Guide
• Sticky Sessions Guide

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Inspired by production load balancers like NGINX and HAProxy
• Built with Go's powerful net/http and httputil packages
• Thanks to the Go community for excellent documentation

📧 Contact

TaiTitans - @TaiTitans

Project Link: https://github.com/TaiTitans/go-balancer

---

Roadmap

• Circuit breaker pattern
• Rate limiting

Made with ❤️ using Go