Kairos-rs

A production-ready HTTP gateway and reverse proxy built with Rust, featuring a modern web-based admin interface and pioneering AI-powered routing capabilities. The future of intelligent API gateways!

What it actually does (right now)

Kairos-rs is a production-ready multi-protocol gateway with modern web UI that: - ✅ HTTP/HTTPS: Routes incoming HTTP requests to backend services based on path patterns - ✅ WebSocket: Real-time bidirectional communication with connection upgrading and message forwarding - ✅ FTP: File Transfer Protocol support with HTTP API wrappers for list/download/upload operations - ✅ DNS: DNS query forwarding with response caching and load balancing across DNS servers - ✅ Supports dynamic path parameters (e.g., /users/{id} → /users/123) - ✅ JWT Authentication - Validate bearer tokens with configurable claims and required fields - ✅ Advanced rate limiting - Per-route limits with multiple algorithms (fixed window, sliding window, token bucket) - ✅ Circuit breaker pattern - Automatic failure detection and recovery with per-backend isolation - ✅ Load Balancing - 5 strategies (round-robin, least connections, random, weighted, IP hash) - ✅ Retry Logic - Exponential backoff with configurable policies and retryable status codes - ✅ Route Management API - Dynamic CRUD operations for routes via REST endpoints - ✅ Hot-Reload API - Manual configuration reload and status endpoints - ✅ Security features - CORS policies, request size limits, security headers - ✅ Observability - Prometheus metrics, structured logging, health checks - ✅ Configuration hot-reload - Update routes without service restart - ✅ Web Admin UI - Modern Leptos-based interface with real-time dashboard and metrics - ✅ Real-time Metrics - WebSocket-based live updates for system performance and traffic - ✅ Configuration Management - Complete UI for JWT, rate limiting, CORS, metrics, and server settings - ✅ Advanced Metrics Dashboard - 5 specialized views with performance insights and error analysis - ✅ Request/Response Transformation - Header manipulation, path rewriting, query parameter transformation - ✅ Historical Metrics - Time-series data storage with configurable retention and aggregation - ✅ Modular Architecture - Workspace with separate crates for gateway, UI, CLI, and client

Current status: Production-ready multi-protocol gateway supporting HTTP, WebSocket, FTP, and DNS with comprehensive security, reliability, load balancing, request/response transformation, and web-based management interface.

sequenceDiagram
    participant Client
    participant Gateway as API Gateway

(Actix-web)
    participant Auth as Auth Service
    participant Cache as Redis Cache
    participant AI as AI Orchestrator
    participant Provider as AI Provider

(OpenAI/Claude)
    participant DB as Database

    Client->>Gateway: POST /api/v1/chat/completions
    Gateway->>Auth: Validate API Key
    Auth-->>Gateway: ✓ Authorized

    Gateway->>Gateway: Rate Limit Check
    Gateway->>Cache: Check cached response

    alt Cache Hit
        Cache-->>Gateway: Return cached result
        Gateway-->>Client: 200 OK (from cache)
    else Cache Miss
        Cache-->>Gateway: Not found
        Gateway->>AI: Process AI Request

        AI->>AI: Select Provider

(load balance)
        AI->>Provider: HTTP Request

(with retry logic)
        Provider-->>AI: AI Response

        AI->>Cache: Store response
        AI->>DB: Log request metadata
        AI->>Gateway: Return result

        Gateway-->>Client: 200 OK (streamed)
    end

    Gateway->>DB: Log analytics (async)

Protocol Support

Kairos-rs now supports multiple protocols beyond HTTP:

See MULTI_PROTOCOL_GUIDE.md for detailed protocol documentation and examples.

Quick Start

Option 1: Using Docker (Recommended)

# Pull the latest multi-platform image (supports AMD64 and ARM64)
docker pull ghcr.io/danielsarmiento04/kairos-rs:latest

# Run with your config.json
docker run -d \
  -p 5900:5900 \
  -v $(pwd)/config.json:/app/config.json:ro \
  -e RUST_LOG=info \
  ghcr.io/danielsarmiento04/kairos-rs:latest

# Or use a specific version
docker pull ghcr.io/danielsarmiento04/kairos-rs:0.2.10

With Docker Compose:

services:
  kairos-gateway:
    image: ghcr.io/danielsarmiento04/kairos-rs:latest
    container_name: kairos-gateway
    restart: unless-stopped
    ports:
      - "5900:5900"
    volumes:
      - ./config.json:/app/config.json:ro
    environment:
      - RUST_LOG=info
      - KAIROS_HOST=0.0.0.0
      - KAIROS_PORT=5900

Debugging containers:

# The image uses distroless:debug with busybox shell
docker exec -it kairos-gateway sh

Option 2: Build from Source

1. Clone and Build

git clone https://github.com/DanielSarmiento04/kairos-rs.git
cd kairos-rs
cargo run --bin kairos-gateway

Gateway starts on http://localhost:5900

2. Start Web Admin UI (Optional)

# Install cargo-leptos (one-time)
cargo install cargo-leptos

# Start UI in development mode
cd crates/kairos-ui
cargo leptos serve

Admin UI available at http://localhost:3000

3. Configure Routes

Create a config.json file with advanced features:

{
  "version": 1,
  "jwt_secret": "your-secret-key-here",
  "rate_limit": {
    "algorithm": "token_bucket",
    "requests_per_second": 100,
    "burst_size": 10
  },
  "routers": [
    {
      "external_path": "/cats/{id}",
      "internal_path": "/{id}",
      "methods": ["GET"],
      "auth_required": false,
      "backends": [
        {"host": "https://http.cat", "port": 443, "weight": 1}
      ],
      "load_balancing_strategy": "round_robin"
    },
    {
      "external_path": "/api/users/{id}",
      "internal_path": "/v1/user/{id}",
      "methods": ["GET", "POST"],
      "auth_required": true,
      "backends": [
        {"host": "http://api1.example.com", "port": 8080, "weight": 3},
        {"host": "http://api2.example.com", "port": 8080, "weight": 2},
        {"host": "http://api3.example.com", "port": 8080, "weight": 1}
      ],
      "load_balancing_strategy": "weighted",
      "retry_config": {
        "max_retries": 3,
        "initial_backoff_ms": 100,
        "max_backoff_ms": 5000,
        "backoff_multiplier": 2.0,
        "retryable_status_codes": [502, 503, 504]
      }
    }
  ]
}

3. Test It

HTTP Endpoints

# Public endpoint (no auth required)
curl http://localhost:5900/cats/200

# Secure endpoint (requires JWT)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://localhost:5900/api/secure/123

WebSocket Connection

# Install wscat
npm install -g wscat

# Connect to WebSocket route
wscat -c "ws://localhost:5900/ws/chat"

Or use the Admin UI at http://localhost:3000 to: - View real-time metrics and dashboard - Monitor health status - See request/response statistics - Track circuit breaker status

4. WebSocket Configuration Example

Add to your config.json:

{
  "routers": [
    {
      "protocol": "websocket",
      "backends": [
        {
          "host": "ws://localhost",
          "port": 3000,
          "weight": 1
        }
      ],
      "external_path": "/ws/chat",
      "internal_path": "/ws",
      "methods": ["GET"],
      "auth_required": false
    }
  ]
}

📖 See WEBSOCKET_GUIDE.md for comprehensive WebSocket documentation.

How Dynamic Routing Works

// Example route configuration
{
  "external_path": "/api/users/{user_id}/posts/{post_id}",
  "internal_path": "/users/{user_id}/posts/{post_id}"
}

// Request: GET /api/users/123/posts/456
// Forwards to: GET /users/123/posts/456

The route matcher: - Uses regex for pattern matching - Supports unlimited path parameters - Falls back to static routes for better performance

Current Architecture

                           ┌─────────────────┐
                           │   Web Admin UI  │
                           │  (Leptos 0.8)   │
                           │  Port: 3000     │
                           └────────┬────────┘
                                    │ HTTP
┌─────────────┐    HTTP    ┌───────▼─────────┐    HTTP    ┌─────────────┐
│   Client    │ ────────▶  │  Kairos Gateway │ ────────▶  │  Backend    │
│             │            │   Port: 5900    │            │  Service    │
└─────────────┘            └─────────┬───────┘            └─────────────┘
                                     │
                              ┌──────┴───────┐
                              │ Config.json  │
                              │   Routes     │ 
                              │     JWT      │
                              │ Rate Limits  │
                              └──────────────┘

Architecture Components:

Workspace Structure:

kairos-rs/
├── crates/
│   ├── kairos-rs/        # Core library (models, routing logic)
│   ├── kairos-gateway/   # Gateway binary (HTTP server)
│   ├── kairos-ui/        # Web admin interface (Leptos SSR)
│   ├── kairos-cli/       # Command-line interface
│   └── kairos-client/    # Rust client library

Core Features:

• Route matcher with compiled regex patterns
• JWT authentication with configurable claims validation
• Advanced rate limiting (token bucket, sliding window, fixed window)
• Circuit breaker for automatic failure handling
• Request/Response transformation - Header manipulation, path rewriting, query parameters
• Historical metrics storage - Time-series data with retention policies and aggregation
• HTTP client with connection pooling (reqwest)
• Prometheus metrics endpoint
• Structured logging and health checks
• Real-time web dashboard with metrics visualization
• Server-side rendering with client hydration for optimal performance

Configuration

Full Configuration Example with Load Balancing & Retry Logic

{
  "version": 1,
  "jwt_secret": "your-256-bit-secret-key-here",
  "rate_limit": {
    "algorithm": "token_bucket",
    "requests_per_second": 100,
    "burst_size": 50
  },
  "routers": [
    {
      "external_path": "/api/v1/users/{id}",
      "internal_path": "/users/{id}",
      "methods": ["GET", "PUT", "DELETE"],
      "auth_required": true,
      "backends": [
        {"host": "http://backend1.example.com", "port": 8080, "weight": 2, "health_check_path": "/health"},
        {"host": "http://backend2.example.com", "port": 8080, "weight": 1, "health_check_path": "/health"}
      ],
      "load_balancing_strategy": "weighted",
      "retry_config": {
        "max_retries": 3,
        "initial_backoff_ms": 100,
        "max_backoff_ms": 5000,
        "backoff_multiplier": 2.0,
        "retryable_status_codes": [502, 503, 504]
      }
    },
    {
      "external_path": "/public/status",
      "internal_path": "/health",
      "methods": ["GET"],
      "auth_required": false,
      "backends": [
        {"host": "https://public-api.com", "port": 443}
      ],
      "load_balancing_strategy": "round_robin"
    }
  ]
}

Load Balancing Strategies

Kairos-rs supports 5 load balancing strategies:

1. Round Robin (round_robin) - Distributes requests evenly in circular order
2. Best for: Backends with similar capacity
3. Pros: Simple, stateless, fair distribution

4. Cons: Doesn't consider backend load

5. Least Connections (least_connections) - Routes to backend with fewest active connections

6. Best for: Backends with varying capacity or long-running requests
7. Pros: Adapts to backend load automatically

8. Cons: Requires connection tracking overhead

9. Random (random) - Randomly selects a backend

10. Best for: Simple setups, testing
11. Pros: Zero state, no lock contention

12. Cons: May cause uneven distribution with few requests

13. Weighted (weighted) - Distributes based on backend weights

14. Best for: Backends with different capacities
15. Pros: Fine-grained control over distribution

16. Cons: Requires manual weight configuration

17. IP Hash (ip_hash) - Routes based on client IP address

18. Best for: Session affinity, sticky sessions
19. Pros: Consistent routing for same client
20. Cons: May cause imbalance with few clients

Retry Configuration

Configure exponential backoff retry logic per route:

"retry_config": {
  "max_retries": 3,              // Maximum retry attempts
  "initial_backoff_ms": 100,     // Initial delay in milliseconds
  "max_backoff_ms": 5000,        // Maximum backoff delay
  "backoff_multiplier": 2.0,     // Multiplier for exponential backoff
  "retryable_status_codes": [502, 503, 504]  // Which HTTP status codes to retry
}

Request/Response Transformation (NEW in v0.2.12)

Transform requests and responses on-the-fly with powerful transformation rules:

Request Transformation

```json "request_transformation": { "headers": [ { "actio