ConnX is a high-performance, lightweight HTTP reverse proxy and load balancer written in Go. It leverages the gnet framework for efficient network operations and provides features like health checking and round-robin load balancing.

• High-performance HTTP reverse proxy
• Round-robin load balancing
• Active health checking of backend servers
• Configuration via YAML file
• Real-time backend server status monitoring
• Request and error statistics tracking
• Customizable timeouts and intervals

# Clone the repository
git clone https://github.com/ODudek/ConnX.git
cd ConnX

# Start with Docker Compose (includes example backends)
docker-compose up -d

# Test the setup
curl http://localhost:8080
curl http://localhost:8080/metrics

Download the latest release from GitHub Releases:

# Linux
wget https://github.com/ODudek/ConnX/releases/latest/download/connx-linux-amd64
chmod +x connx-linux-amd64
./connx-linux-amd64 -config=config.yaml

# macOS
wget https://github.com/ODudek/ConnX/releases/latest/download/connx-darwin-amd64
chmod +x connx-darwin-amd64
./connx-darwin-amd64 -config=config.yaml

git clone https://github.com/ODudek/ConnX.git
cd ConnX
make build
./bin/proxy -config=configs/config.yaml

Create a config.yaml file with the following structure:

server:
  port: 8080
  host: "0.0.0.0"

backends:
  - "http://backend1:8080"
  - "http://backend2:8080"
  - "http://backend3:8080"

healthCheck:
  interval: 30  # seconds
  timeout: 5    # seconds

ConnX exposes Prometheus-compatible metrics at /metrics:

curl http://localhost:8080/metrics

• connx_requests_total - Total HTTP requests by method and status
• connx_errors_total - Total error count
• connx_response_time_seconds - Response time statistics (avg, p95, p99)
• connx_backend_up - Backend health status (1=up, 0=down)
• connx_active_connections - Current active connections
• connx_uptime_seconds - Server uptime
• connx_requests_per_second - Current requests per second

# Run with default config
./connx

# Run with custom config
./connx -config=/path/to/config.yaml

# Docker
docker run -p 8080:8080 -v $(pwd)/config.yaml:/app/configs/config.yaml odudek/connx:latest

See configs/examples/ for various configuration examples:

• basic.yaml - Minimal setup
• production.yaml - Production-ready configuration
• development.yaml - Development environment
• monitoring.yaml - With Prometheus integration

If not specified in the config file, the following default values are used:

• Server port: 8080
• Server host: "0.0.0.0"
• Health check interval: 30 seconds
• Health check timeout: 5 seconds

This project uses GitHub Actions for Continuous Integration and Deployment:

• Runs tests
• Performs linting using golangci-lint
• Builds the application
• Runs on every push to main and pull requests

• Triggered by tags starting with 'v'
• Creates releases with binaries for multiple platforms
• Builds and pushes Docker images to Docker Hub
• Generates release notes automatically

Latest images are available on Docker Hub:

docker pull odudek/connx:latest

ConnX consists of several key components:

• Proxy Server: Handles incoming connections and forwards requests to backends
• Server Pool: Manages the collection of backend servers
• Health Checker: Monitors backend server health
• Load Balancer: Distributes requests across healthy backends

ConnX is built with performance in mind:

• Uses gnet for efficient network operations
• Implements connection pooling
• Minimizes memory allocations
• Supports multicore processing

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

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

# Install dependencies
go mod download

# Run tests
make test

# Run linting
golangci-lint run

# Build
make build

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

• 📖 Documentation
• 🐛 Report Issues
• 💡 Feature Requests
• 💬 Discussions

• gnet - High-performance, lightweight, non-blocking, event-driven networking framework
• All contributors who help make ConnX better