HotRouter 🚀

A dynamic HTTP reverse proxy with WebSocket support that allows runtime configuration management through a REST API.

Features

• ✅ HTTP and WebSocket reverse proxy
• ✅ Runtime configuration management
• ✅ Host-based routing (virtual hosts)
• ✅ Wildcard pattern support (*.example.com, api.*.com, **.subdomain.com)
• ✅ Token-based authentication
• ✅ Auto-cleanup of stale routes
• ✅ Debug logging with colors
• ✅ Graceful shutdown
• ✅ RESTful API for route management

Installation

git clone https://github.com/sammwyy/HotRouter
cd hotrouter
go mod tidy
go build -o hotrouter

Usage

Basic Usage

# Start HotRouter with required secret token
./hotrouter --secret mySecretToken123

# Start with custom ports
./hotrouter --port 8000 --dashport 9000 --secret mySecretToken123

# Enable debug mode and custom auto-cleanup time
./hotrouter --secret mySecretToken123 --debug --autoclean 30m

Command Line Arguments

• -p, --port: Port for the proxy server (default: 80)
• -d, --dashport: Port for the dashboard API (default: 8080)
• -s, --secret: Secret token for API authentication (required)
• --debug: Enable debug logging
• --autoclean: Auto-clean inactive routes after duration (default: 1h, use 0 to disable)

API Usage

All API endpoints require authentication using Bearer token:

Authorization: Bearer <your-secret-token>

Add/Update Route

Add or update a route configuration:

# Exact host match
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer mySecretToken123" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "api.example.com",
    "target": "http://192.168.1.100:3000"
  }'

# Wildcard patterns
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer mySecretToken123" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "*.example.com",
    "target": "http://192.168.1.100:3000"
  }'

Get All Routes

Retrieve all configured routes:

curl -X GET http://localhost:8080/routes \
  -H "Authorization: Bearer mySecretToken123"

Get Specific Route

Retrieve a specific route by host:

curl -X GET "http://localhost:8080/routes?host=api.example.com" \
  -H "Authorization: Bearer mySecretToken123"

Delete Route

Delete a route configuration:

curl -X DELETE "http://localhost:8080/routes?host=api.example.com" \
  -H "Authorization: Bearer mySecretToken123"

Wildcard Patterns

HotRouter supports flexible wildcard patterns for host matching:

Single Part Wildcard (*)

Matches exactly one domain part:

• *.example.com → matches api.example.com, www.example.com, but NOT sub.api.example.com
• api.*.com → matches api.test.com, api.prod.com
• *.test.* → matches api.test.com, www.test.org

Multi-Part Wildcard (**)

Matches zero or more domain parts:

• **.example.com → matches example.com, api.example.com, sub.api.example.com
• api.**.com → matches api.com, api.test.com, api.test.prod.com
• server1.** → matches server1.test.local, server1.prod.example.com

Pattern Examples

# Match all subdomains of example.com
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "*.example.com", "target": "http://192.168.1.100:3000"}'

# Match any API subdomain
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "api.*.*", "target": "http://192.168.1.101:8000"}'

# Match any nested subdomain of test.local
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "**.test.local", "target": "http://192.168.1.102:4000"}'

# Match specific server with any domain structure
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "server1.**", "target": "http://192.168.1.103:5000"}'

Matching Priority

1. Exact matches have highest priority
2. Wildcard patterns are matched in the order they were added
3. More specific patterns should be added before general ones

Examples

Example 1: Basic Web Application

# Start HotRouter
./hotrouter --secret myToken --debug

# Configure route for a web app
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "webapp.local",
    "target": "http://127.0.0.1:3000"
  }'

# Now requests to webapp.local will be proxied to 127.0.0.1:3000

Example 2: WebSocket Application

# Configure route for a WebSocket server
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "chat.local",
    "target": "http://127.0.0.1:4000"
  }'

# WebSocket connections to ws://chat.local will be proxied to ws://127.0.0.1:4000

Example 3: Multiple Services

# API service
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "api.myapp.com", "target": "http://192.168.1.10:8000"}'

# Frontend service
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "myapp.com", "target": "http://192.168.1.11:3000"}'

# Admin panel
curl -X POST http://localhost:8080/routes \
  -H "Authorization: Bearer myToken" \
  -H "Content-Type: application/json" \
  -d '{"host": "admin.myapp.com", "target": "http://192.168.1.12:4000"}'

Features Details

Auto-Cleanup

Routes that haven't received requests for the specified duration will be automatically removed:

• Default: 1 hour
• Configurable via --autoclean flag
• Set to 0 to disable auto-cleanup
• Cleanup runs every half of the auto-cleanup interval

Debug Mode

When enabled with --debug, you'll see detailed logs:

• Route additions/deletions
• Proxy requests (HTTP and WebSocket)
• Auto-cleanup operations
• Connection errors

WebSocket Support

HotRouter automatically detects WebSocket upgrade requests and handles the proxying of WebSocket connections transparently. No additional configuration is needed.

Graceful Shutdown

HotRouter handles SIGINT and SIGTERM signals gracefully:

• Stops accepting new connections
• Allows existing connections to complete
• Shuts down within 10 seconds maximum

Response Format

Success Response

{
  "status": "success",
  "message": "Route added"
}

Route Information

{
  "host": "api.example.com",
  "target": "http://192.168.1.100:3000",
  "last_access": "2023-12-01T10:30:00Z"
}

Error Response

{
  "error": "Route not found"
}

License

MIT License