A lightweight (1 file), dynamic reverse proxy server with live configuration reloading capabilities. The code can be copied around easily and is good at maintaining long-lived sessions like WebSockets to subdaemons while other upstreams may be restarting like view servers.

lightymux is a lightweight, efficient reverse proxy server written in Go that allows for dynamic configuration updates without requiring server restarts. It's designed to handle HTTP traffic routing with real-time configuration changes, making it ideal for development environments and production systems that require flexible routing rules.

• Live configuration reloading with file watching
• Support for HTTP/HTTPS proxy targets
• Static file and directory serving
• Request/Response header modification
• Configurable timeouts and retries
• Comprehensive logging options
• Graceful shutdown support
• Health check endpoint
• Environment variable configuration

go get github.com/presbrey/lightymux

Or clone the repository and build from source:

git clone https://github.com/presbrey/lightymux.git
cd lightymux
go build

• HTTP_ADDR: HTTP listen address (default: ""), overrides config file listen and port settings
• READ_TIMEOUT: Read timeout duration (default: 30s)
• WRITE_TIMEOUT: Write timeout duration (default: 30s)
• IDLE_TIMEOUT: Idle timeout duration (default: 60s)
• PROXY_TIMEOUT: Proxy timeout duration (default: 60s)

The configuration file uses YAML format with top-level server settings and routes. See example.yml for a complete configuration example.

# Server settings
listen: 0.0.0.0      # Bind address (default: 0.0.0.0)
port: 8080           # Port to listen on
health: /health      # Health check endpoint path

# Logging settings
log:
  requests: true     # Log incoming requests (default: false)
  responses: false   # Log outgoing responses (default: false)
  errors: true       # Log proxy errors (default: true)
  verbose: false     # Enable verbose logging (default: false)
  file: ""           # Log to file instead of stderr

# Routes
routes:
  /api:
    target: http://api.example.com
    rules:
      - request:
          headers:
            X-API-Key: secret-key
      - response:
          headers:
            Access-Control-Allow-Origin: "*"

  /static:
    target: /var/www/static

  /files:
    target: /path/to/files

Routes can include a hostname prefix to route traffic based on the Host header:

routes:
  # Host-specific routes (matched first)
  api.example.com/v1/:
    target: http://api-v1-backend:8080
  api.example.com/v2/:
    target: http://api-v2-backend:8080
  
  # Wildcard route (fallback for any host)
  /api/:
    target: http://default-backend:8080

Route format: hostname/path or just /path for wildcard (all hosts).

Priority order:

1. Host-specific exact match (api.example.com/users)
2. Host-specific prefix match (api.example.com/users/)
3. Wildcard exact match (/users)
4. Wildcard prefix match (/users/)

Routes can be configured for:

• Remote HTTP/HTTPS endpoints
• Local directories (static file serving)
• Single files

You can modify request and response headers for each route using three operations:

• header-add: Add values to existing headers (supports multiple values)
• header-set: Set headers to specific values, replacing any existing ones
• header-del: Remove headers completely

Example:

/api:
  target: http://api.example.com
  rules:
    - request:
        headers:
          header-add:
            Accept: ["application/json", "text/plain"]
            X-Custom: ["value1", "value2"]
          header-set:
            Authorization: "Bearer token123"
            Content-Type: "application/json"
          header-del:
            - "X-Old-Header"
            - "X-Deprecated"
    - response:
        headers:
          header-add:
            Access-Control-Allow-Methods: ["GET", "POST", "OPTIONS"]
          header-set:
            Access-Control-Allow-Origin: "*"
            Cache-Control: "max-age=3600"
          header-del:
            - "X-Internal-Header"

In this example:

• Request modifications:
  • Adds multiple values to Accept and X-Custom headers
  • Sets Authorization and Content-Type headers to specific values
  • Removes X-Old-Header and X-Deprecated headers
• Response modifications:
  • Adds multiple CORS methods
  • Sets CORS origin and caching headers
  • Removes an internal header

Basic usage:

lightymux [config_file]

Example with environment variables:

HTTP_ADDR=:8080 VERBOSE=true LOG_REQUESTS=true lightymux config.yaml

The configuration file is watched for changes and automatically reloaded when modified.

1. Create a configuration file config.yaml:

/api:
  target: http://localhost:3000
  rules:
    - response:
        headers:
          Access-Control-Allow-Origin: "*"

/static:
  target: /var/www/static

/docs:
  target: http://localhost:8080

2. Start the proxy:

lightymux config.yaml

3. The proxy will now:
   • Forward /api/* to http://localhost:3000/* with CORS headers
   • Serve static files from /var/www/static at /static/*
   • Forward /docs/* to http://localhost:8080/*

See LICENSE file for details.