Helios

Ultra-fast, production-grade L7 reverse proxy and load balancer - simple, extensible, and reliable.

Overview

Helios is a modern, production-grade reverse proxy and load balancer for microservices. It combines intelligent routing (Round Robin, Least Connections, Weighted, IP Hash), active/passive health checks, low-overhead WebSocket/TLS termination, runtime control via the Admin API, and a pluggable middleware system delivering high throughput, low latency, and effortless operations.

Features

• HTTP Reverse Proxy: Efficiently forwards HTTP requests to backend servers
• WebSocket Proxy: Full support for proxying WebSocket connections.
• TLS/SSL Termination: Secures traffic by terminating TLS connections.
• Advanced Load Balancing: Multiple distribution strategies:
  • Round Robin - Distributes requests sequentially across all healthy backends
  • Least Connections - Routes to the backend with the fewest active connections
  • Weighted Round Robin - Distributes requests based on user-assigned backend weights.
  • IP Hash - Ensures requests from the same client IP are routed to the same backend.
• Intelligent Health Monitoring:
  • Passive health checks - Detects failures from regular traffic patterns
  • Active health checks - Proactively monitors backend health with periodic requests
• Request Rate Limiting: Token bucket algorithm to prevent abuse and ensure fair usage
• Circuit Breaker Pattern: Prevents cascading failures by temporarily blocking requests to unhealthy services
• Metrics and Monitoring:
  • Real-time metrics collection and exposure
  • Health status endpoints
  • Backend performance monitoring
  • Request/response statistics
• Configuration: Simple YAML-based configuration
• Performance: Low memory footprint and high throughput
• Reliability: Automatic failover when backends become unhealthy
• Admin API: Runtime backend management, strategy switching, and JSON metrics/health
• Structured Logging: Configurable JSON or text logs with request/trace identifiers
• Plugin Middleware: Configurable middleware chain (built-ins: logging, headers)

Architecture

graph TD
    Client([Client]) -->|HTTP Request| RateLimit[Rate Limiter]
    
    subgraph "Helios Load Balancer"
        RateLimit --> CircuitBreaker[Circuit Breaker]
        CircuitBreaker --> Helios[Helios Proxy]
        Helios --> LoadBalancer[Load Balancing Strategy]
        Helios --> HealthChecker[Health Checker]
        Helios --> MetricsCollector[Metrics Collector]
        
        subgraph "Health Monitoring"
            HealthChecker --> PassiveChecks[Passive Health Checks]
            HealthChecker --> ActiveChecks[Active Health Checks]
        end
        
        subgraph "Load Balancing Strategies"
            LoadBalancer --> RoundRobin[Round Robin]
            LoadBalancer --> LeastConn[Least Connections]
            LoadBalancer --> WeightedRR[Weighted Round Robin]
            LoadBalancer --> IPHash[IP Hash]
        end
        
        subgraph "Monitoring & Metrics"
            MetricsCollector --> MetricsAPI[Metrics API :9090]
            MetricsCollector --> HealthAPI[Health API :9090]
        end
    end
    
    Helios -->|Forward Request| Backend1[Backend Server 1]
    Helios -->|Forward Request| Backend2[Backend Server 2]
    Helios -->|Forward Request| Backend3[Backend Server 3]
    
    ActiveChecks -.->|Health Probe| Backend1
    ActiveChecks -.->|Health Probe| Backend2
    ActiveChecks -.->|Health Probe| Backend3
    
    Backend1 -->|Response| Helios
    Backend2 -->|Response| Helios
    Backend3 -->|Response| Helios
    
    Helios -->|HTTP Response| Client
    
    MetricsAPI -.->|Monitoring Data| Monitoring[Monitoring System]
    HealthAPI -.->|Health Status| Monitoring

Loading

Getting Started

Prerequisites

• Go 1.18 or higher
• Git (for cloning the repository)

Installation

From Source

1. Clone the repository:

   git clone https://github.com/0xReLogic/Helios.git
   cd Helios

2. Build the project:

   go build -o helios.exe ./cmd/helios

3. Run Helios:

   ./helios.exe

Using Pre-built Binaries

1. Download the latest release from the Releases page
2. Extract the archive
3. Run the executable:

   ./helios.exe

Running Test Backends

For testing purposes, Helios includes simple backend servers:

# Build the backend server
go build -o backend.exe ./cmd/backend

# Run multiple backend servers
./backend.exe --port=8081 --id=1
./backend.exe --port=8082 --id=2
./backend.exe --port=8083 --id=3

On Windows, you can use the provided batch script:

start_backends.bat

Configuration

Helios is configured via helios.yaml:

server:
  port: 8080
  tls:
    enabled: true
    certFile: "certs/cert.pem"
    keyFile: "certs/key.pem"

backends:
  - name: "server1"
    address: "http://localhost:8081"
    weight: 5
  - name: "server2"
    address: "http://localhost:8082"
    weight: 2
  - name: "server3"
    address: "http://localhost:8083"
    weight: 1

load_balancer:
  strategy: "round_robin"  # Options: "round_robin", "least_connections", "weighted_round_robin", "ip_hash"
  
health_checks:
  active:
    enabled: true
    interval: 5   # Interval in seconds
    timeout: 3    # Timeout in seconds  
    path: "/health"
  passive:
    enabled: true
    unhealthy_threshold: 10  # Number of failures before marking as unhealthy
    unhealthy_timeout: 15    # Time in seconds to keep backend unhealthy

rate_limit:
  enabled: true            # Disabled by default
  max_tokens: 100          # Maximum tokens in bucket
  refill_rate_seconds: 1   # Refill rate in seconds

circuit_breaker:
  enabled: true
  max_requests: 100        # Max requests in half-open state
  interval_seconds: 30     # Time window for failure counting
  timeout_seconds: 15      # Time to wait before moving from open to half-open
  failure_threshold: 50    # Number of failures to open circuit
  success_threshold: 10    # Number of successes to close circuit

admin_api:
  enabled: true
  port: 9091
  auth_token: "change-me"

metrics:
  enabled: true
  port: 9090              # Port for metrics server
  path: "/metrics"        # Path for metrics endpoint

logging:
  level: "info"           # debug, info, warn, error
  format: "text"          # text (default) or json
  include_caller: true    # include caller information in logs
  request_id:
    enabled: true
    header: "X-Request-ID"
  trace:
    enabled: true
    header: "X-Trace-ID"

plugins:
  enabled: true
  chain:
    - name: logging
    - name: headers
      config:
        set:
          X-App: Helios
        request_set:
          X-From: LB

Quick Start

Logging Configuration

Helios emits structured logs using zerolog for efficient structured logging. Configure verbosity, output format, and observability headers via the logging block:

• level – Supported values: debug, info, warn, error (default info).
• format – text (default) for console readability or json for machine-friendly ingestion.
• include_caller – When true, adds caller information to log entries.
• request_id – Enables automatic generation and propagation of a request identifier. The value is attached to responses and forwarded to backends using the configured header (default X-Request-ID).
• trace – Propagates distributed trace identifiers (default header X-Trace-ID) and includes them in every log entry.

Each HTTP request is logged with latency, status code, backend target, and associated request/trace identifiers, simplifying correlation across services.

Verifying request & trace propagation

1. Start one or more sample backends:

   go run ./cmd/backend --port=8081 --id=server1

2. In a second terminal, run the load balancer (it picks up helios.yaml):

   go run ./cmd/helios

3. Issue a request and optionally provide your own trace identifier:

   curl -H "X-Trace-ID: trace_demo" http://localhost:8080/api/users

4. Observe the terminal output. With the default text format you will see entries similar to:

   time=2025-10-02T10:30:00Z level=info request_id=req_abc123 trace_id=trace_demo method=GET path=/api/users status=200 latency_ms=45 backend=server1 message="request completed"
   

5. To compare against JSON logs, change logging.format to json, restart Helios, and repeat step 3—the output will be emitted as structured JSON for side-by-side comparison.

Build and Run

git clone https://github.com/0xReLogic/Helios.git
cd Helios
go build -o helios ./cmd/helios
./helios

Basic Configuration (helios.yaml)

server:
  port: 8080

backends:
  - name: "server1"
    address: "http://localhost:8081"
    weight: 5
  - name: "server2"
    address: "http://localhost:8082"
    weight: 2
  - name: "server3"
    address: "http://localhost:8083"
    weight: 1

load_balancer:
  strategy: "round_robin"  # round_robin, least_connections, weighted_round_robin, ip_hash

health_checks:
  active:
    enabled: true
    interval: 5
    timeout: 3
    path: "/health"
  
circuit_breaker:
  enabled: true
  failure_threshold: 50

metrics:
  enabled: true
  port: 9090

Test Backends

go build -o backend ./cmd/backend
./backend --port=8081 --id=1 &
./backend --port=8082 --id=2 &
./backend --port=8083 --id=3 &

Monitoring & Management

Metrics Endpoint

Access real-time metrics at http://localhost:9090/metrics (Prometheus format)

Admin API

• Runtime backend management
• Strategy switching
• Health status monitoring
• JWT-protected endpoints

Health Checks

• Active: Periodic backend health verification
• Passive: Request-based health tracking
• Circuit breaker: Automatic failure isolation

Documentation

• Plugin Development Guide - Learn how to create custom plugins
  • Example plugins: internal/plugins/examples

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

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

---

Contributors

Thanks to all the amazing people who have contributed to Helios!