Skip to content

lekhrocks/router-service

BranchesTags

Repository files navigation

Router Service - Production-Ready Load Balancer

A sophisticated, production-ready load balancer service built with Spring Boot that provides advanced request routing, load balancing strategies, and real-time monitoring with enterprise-grade reliability features.

📋 Table of Contents

🚀 Quick Start

Prerequisites

  • Java 21+
  • Gradle 8.14+
  • Docker (optional)

1. Clone and Build

git clone <repository>
cd router-service
./gradlew build

2. Start the Service

./gradlew bootRun

3. Access the Dashboard

# Open login page
open http://localhost:8080/login.html

# Login with default credentials
# Username: admin
# Password: admin123

# Or access dashboard directly (will redirect to login)
open http://localhost:8080/dashboard.html

4. Test the Service

# Generate test traffic
curl -H "Host: api.example.com" http://localhost:8080/v1/users
curl -H "Host: api.example.com" http://localhost:8080/v1/orders

🔐 Default Credentials

  • Username: admin
  • Password: admin123

⚠️ Remember to change these in production!

✨ Key Features

🔧 Core Functionality

  • Advanced Routing: Regex-based host and path pattern matching
  • Load Balancing: Round Robin, Random, Least Connections, Weighted Round Robin
  • Health Checks: Automatic backend health monitoring
  • Request Proxying: Full HTTP request/response forwarding
  • Real-time Metrics: WebSocket-based metrics streaming
  • Configuration Management: JSON-based routing configuration

🛡️ Reliability & Resilience

  • Circuit Breaker Pattern: Automatic failure detection and recovery
  • Rate Limiting: Token bucket algorithm for request throttling
  • Retry Logic: Configurable retry policies with exponential backoff
  • Graceful Degradation: Fallback mechanisms for service failures

📊 Monitoring & Observability

  • Professional Dashboard: Modern, responsive web interface
  • Real-time Metrics: Request counts, latency percentiles, error rates
  • Health Status: Backend availability monitoring
  • Circuit Breaker Status: State monitoring and manual reset
  • WebSocket Streaming: Live metrics via WebSocket connection
  • Prometheus Integration: Metrics export for monitoring systems

🔒 Security

  • Authentication: Basic authentication for dashboard access
  • Role-Based Access: ADMIN role required for management features
  • Session Management: Persistent login with secure logout
  • Security Headers: HSTS, frame options, content type protection
  • Input Validation: Comprehensive request validation

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP Client   │───▶│  Router Service  │───▶│   Backend 1     │
└─────────────────┘    │                 │    └─────────────────┘
                       │ ┌─────────────┐ │
                       │ │Rate Limiter │ │    ┌─────────────────┐
                       │ └─────────────┘ │───▶│   Backend 2     │
                       │ ┌─────────────┐ │    └─────────────────┘
                       │ │Circuit      │ │
                       │ │Breaker      │ │    ┌─────────────────┐
                       │ └─────────────┘ │───▶│   Backend 3     │
                       │ ┌─────────────┐ │    └─────────────────┘
                       │ │Health Check │ │
                       │ └─────────────┘ │
                       └─────────────────┘

⚙️ Configuration

Routing Rules Configuration

Create a config/routes.json file:

[
  {
    "hostPattern": "api\\.example\\.com",
    "pathPattern": "/v1/users(/.*)?",
    "backends": [
      "http://10.0.0.5:8080",
      "http://10.0.0.6:8080"
    ],
    "loadBalancingStrategy": "ROUND_ROBIN",
    "timeoutSeconds": 30,
    "healthCheckEnabled": true,
    "healthCheckPath": "/health",
    "circuitBreakerEnabled": true,
    "circuitBreakerFailureThreshold": 5,
    "circuitBreakerResetTimeoutSeconds": 60,
    "rateLimitingEnabled": true,
    "rateLimitMaxTokens": 100,
    "rateLimitTokensPerSecond": 10.0,
    "retryEnabled": true,
    "maxRetries": 3,
    "retryDelayMs": 1000
  }
]

Application Properties

# Application Configuration
spring.application.name=router-service
server.port=8080

# Router Configuration
router.config.path=config/routes.json
router.health-check.interval=30000
router.health-check.timeout=5000

# Circuit Breaker Configuration
router.circuit-breaker.default-failure-threshold=5
router.circuit-breaker.default-reset-timeout=60000

# Rate Limiting Configuration
router.rate-limit.default-max-tokens=100
router.rate-limit.default-tokens-per-second=10.0

# Logging Configuration
logging.level.com.example.router=INFO
logging.file.name=logs/router-service.log
logging.file.max-size=100MB
logging.file.max-history=30

# Actuator Configuration
management.endpoints.web.exposure.include=health,info,metrics,prometheus
management.metrics.export.prometheus.enabled=true

🔐 Security

Authentication & Authorization

The router service implements multi-layered security with:

  • Basic Authentication: Username/password with BCrypt encoding
  • Role-Based Access: ADMIN role required for management features
  • Session Management: Persistent login with secure logout
  • Protected Endpoints: Dashboard, management API, WebSocket, actuator

Security Configuration

# Default credentials
spring.security.user.name=admin
spring.security.user.password=admin123

# Dashboard security
dashboard.security.enabled=true
dashboard.security.allowed-origins=*

# Session management
server.servlet.session.timeout=3600s
server.servlet.session.cookie.http-only=true

Protected Resources

Resource Authentication Authorization Description
/dashboard.html ✅ Required ADMIN Role Main dashboard interface
/api/management/** ✅ Required ADMIN Role Management API endpoints
/ws/metrics ✅ Required ADMIN Role WebSocket metrics stream
/actuator/** ✅ Required ADMIN Role Application monitoring
/login.html ❌ Public None Login page
/actuator/health ❌ Public None Health check endpoint
/v1/**, /api/** ❌ Public None Router endpoints

Security Headers

X-Frame-Options: DENY                    # Clickjacking protection
X-Content-Type-Options: nosniff          # MIME type sniffing protection
Strict-Transport-Security: max-age=31536000 # HSTS for HTTPS enforcement

📊 Dashboard

Access the Dashboard

  1. Login Page: http://localhost:8080/login.html 🔐
  2. Dashboard: http://localhost:8080/dashboard.html 🎨
  3. Default Credentials: admin / admin123

Dashboard Features

📈 Real-time Visualizations

  • Latency Trends Chart: Time-series latency data with multiple rule tracking
  • Request Volume Chart: Bar chart showing request counts over time
  • Interactive Legends: Click to show/hide data series
  • Responsive Design: Works on desktop, tablet, and mobile

📊 Performance Metrics

  • Total Requests: Real-time request count across all rules
  • Average Latency: Response time metrics with P95/P99 percentiles
  • Error Rate: Percentage of failed requests
  • System Status: Backend health, circuit breakers, rate limiters

🔧 Interactive Controls

  • Auto-refresh: Configurable automatic updates (5-second intervals)
  • Manual Refresh: Instant data refresh button
  • Circuit Breaker Reset: Bulk and individual reset functionality
  • Connection Status: WebSocket connection indicator

📋 Data Tables

  • Routing Rules Table: All configured rules with status indicators
  • Circuit Breakers Table: Backend failure states with reset actions
  • Status Badges: Color-coded indicators (success/warning/danger)

Dashboard Screenshots

┌─────────────────────────────────────────────────────────────┐
│ 🚀 Router Service Dashboard                                 │
├─────────────────────────────────────────────────────────────┤
│ Service: Online | Backends: 3/5 Healthy | CB: Normal       │
├─────────────────────────────────────────────────────────────┤
│ [Refresh] [Reset CB] [Auto Refresh]                         │
├─────────────────────────────────────────────────────────────┤
│ 📊 Performance Metrics    │ 🏥 System Status               │
│ Total Requests: 1,234    │ Healthy Backends: 3            │
│ Avg Latency: 45.2ms      │ Open Circuit Breakers: 0       │
│ P95 Latency: 120.5ms     │ Active Rate Limiters: 5        │
│ Error Rate: 0.1%         │ Total Rules: 6                 │
├─────────────────────────────────────────────────────────────┤
│ 📈 Latency Trends         │ 📊 Request Volume              │
│ [Interactive Chart]       │ [Bar Chart]                   │
├─────────────────────────────────────────────────────────────┤
│ 📋 Routing Rules          │ 🛡️ Circuit Breakers           │
│ [Data Table]              │ [Data Table with Actions]     │
└─────────────────────────────────────────────────────────────┘

🐳 Deployment

Docker Deployment

Build and Run

# Build Docker image
docker build -t router-service .

# Run with Docker
docker run -p 8080:8080 -v $(pwd)/config:/app/config router-service

Docker Compose (with monitoring)

# Start full stack with monitoring
docker-compose up -d

# Access services
# Router Service: http://localhost:8080
# Prometheus: http://localhost:9090
# Grafana: http://localhost:3000 (admin/admin)

Production Deployment

Environment Variables

# Required for production
export ADMIN_USERNAME=your_admin_username
export ADMIN_PASSWORD=your_secure_password
export DASHBOARD_SECURITY_ENABLED=true

# Optional security enhancements
export SERVER_SSL_ENABLED=true
export SERVER_SSL_KEY_STORE=/path/to/keystore.p12
export SERVER_SSL_KEY_STORE_PASSWORD=your_keystore_password

JVM Performance Tuning

# Production JVM options
JAVA_OPTS="-Xms4g -Xmx8g \
    -XX:+UseG1GC \
    -XX:MaxGCPauseMillis=200 \
    -XX:+UseStringDeduplication \
    -XX:+UseContainerSupport \
    -XX:MaxRAMPercentage=75.0"

🧪 Testing

Run Tests

./gradlew test

Test Coverage

  • Load balancing strategies
  • Circuit breaker functionality
  • Rate limiting algorithms
  • String parsing and pattern matching
  • Health check functionality
  • Request routing and proxying
  • Management API endpoints
  • Retry logic and error handling

Integration Testing

# Start test backends
docker-compose up backend1 backend2 backend3

# Run integration tests
./gradlew integrationTest

📈 Performance

High-Throughput Configuration

For handling 1 million requests, use the high-performance configuration:

{
  "rateLimitMaxTokens": 50000,
  "rateLimitTokensPerSecond": 5000.0,
  "timeoutSeconds": 10,
  "retryDelayMs": 100,
  "maxRetries": 2
}

Performance Optimization

JVM Configuration

# Production JVM options
JAVA_OPTS="-Xms4g -Xmx8g -XX:+UseG1GC -XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0"

Server Configuration

# High-performance server settings
server.tomcat.threads.max=1000
server.tomcat.threads.min-spare=100
server.tomcat.max-connections=10000
server.tomcat.accept-count=500

Load Testing

# Install wrk (load testing tool)
brew install wrk  # macOS
# or
sudo apt-get install wrk  # Ubuntu

# Run load test
wrk -t12 -c400 -d30s http://localhost:8080/v1/users

🔧 Troubleshooting

Common Issues

1. Dashboard Not Loading

# Check if service is running
curl http://localhost:8080/api/management/health

# Verify dashboard file exists
ls -la src/main/resources/static/dashboard.html

# Check browser console for WebSocket errors

2. WebSocket Connection Failed

# Test WebSocket endpoint
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: test" \
     http://localhost:8080/ws/metrics

3. Circuit Breaker Open

# Check circuit breaker status
curl http://localhost:8080/api/management/circuit-breakers

# Reset circuit breaker
curl -X POST http://localhost:8080/api/management/circuit-breakers/{backend}/reset

4. Rate Limit Exceeded

# Check rate limiter status
curl http://localhost:8080/api/management/rate-limiters

Log Analysis

# Monitor application logs
tail -f logs/router-service.log

# Search for errors
grep ERROR logs/router-service.log

# Monitor circuit breaker events
grep "Circuit breaker" logs/router-service.log

Performance Issues

High Latency

  1. Check backend health: /api/management/health
  2. Review circuit breaker states: /api/management/circuit-breakers
  3. Monitor rate limiting: /api/management/rate-limiters
  4. Check JVM memory usage
  5. Review network connectivity

High Memory Usage

  1. Check for memory leaks in latency buffers
  2. Review JVM heap settings
  3. Monitor garbage collection
  4. Check for large request bodies

📚 API Reference

Management Endpoints

Endpoint Method Description Authentication
/api/management/rules GET List all routing rules Required
/api/management/health GET Backend health status Required
/api/management/metrics GET Current metrics Required
/api/management/status GET Overall system status Required
/api/management/circuit-breakers GET Circuit breaker states Required
/api/management/circuit-breakers/{backend}/reset POST Reset circuit breaker Required

Router Endpoints

Endpoint Method Description Authentication
/v1/** ALL Route requests to backends Not Required
/api/** ALL Route requests to backends Not Required
/admin/** ALL Route requests to backends Not Required

Health Check Endpoints

Endpoint Method Description Authentication
/actuator/health GET Application health Not Required
/actuator/info GET Application info Not Required

🔮 Future Enhancements

  • JWT Token Authentication: Replace basic auth with JWT
  • OAuth2 Integration: SSO with external providers
  • Multi-Factor Authentication: 2FA support
  • API Key Management: Secure API key handling
  • Weighted Load Balancing: Support for backend weights
  • SSL/TLS Termination: HTTPS support
  • Request/Response Transformation: Header and body modification
  • Service Discovery: Integration with Consul, Eureka
  • Distributed Tracing: OpenTelemetry integration
  • Advanced Metrics: Custom business metrics
  • Configuration Hot Reload: Dynamic configuration updates
  • Multi-Region Support: Geographic load balancing

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Update documentation
  6. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

For support and questions:

Router Service - Production-ready load balancer with advanced routing, monitoring, and security features. 🚀

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages