Documentation

Overview

Moonlight Server is a lightweight HTTP JSON proxy that manages distributed clients by region. It provides intelligent load balancing, dual-protocol support (HTTP/WebSocket), and automatic failover for building resilient distributed systems.

Key Features

Regional client management
Weighted round-robin load balancing
HTTP & WebSocket protocols
Automatic health checks
Real-time client monitoring
Task distribution & routing

V0 there is too much gap between the sections why can't you remove it⁉️

Configuration

mls.json

Configuration file should be placed at /etc/moonlight/mls.json

{
  "note": "This is an example config. Copy it to /etc/moonlight/mls.json",
  "tokens": [
    "supersecrettokenox0",
    "supersecrettokenox1"
  ],
  "retry_count": 3,
  "port": 8080,
  "ws": {
    "enabled": true,
    "path": "/ws",
    "max_connections": 1000,
    "read_timeout": 300,
    "write_timeout": 30,
    "heartbeat_interval": 30,
    "connection_check_interval": 60
  },
  "html": {
    "enabled": true,
    "static_path": "/static",
    "index_path": "/",
    "dashboard_path": "/dashboard"
  },
  "region_hierarchy": {
    "us-east-1": "usa",
    "us-west-1": "usa",
    "eu-west-1": "europe",
    "ap-southeast-1": "singapore",
    "usa": "northamerica",
    "europe": "emea",
    "singapore": "asia",
    "northamerica": "global",
    "emea": "global",
    "asia": "global"
  }
}

Key Configuration Options

tokensArray of valid authentication tokens
portServer port (default: 8080)
region_hierarchyHierarchical region mapping for client routing
ws.enabledEnable/disable WebSocket support

API Reference

POST/task/request

Send task to clients in specified region. Server forwards payload to client's /work endpoint.

curl -X POST http://localhost:8080/task/request \
  -H "Content-Type: application/json" \
  -d '{
    "region": "global",
    "payload": {
      "action": "process_data",
      "data": {"message": "Hello"}
    }
  }'
POST/client/heartbeat

Register and maintain client connection with heartbeat.

{
  "ip": "192.168.1.100",
  "node_id": "node-001",
  "token": "supersecrettokenox0",
  "region": "us-east-1",
  "port": 3000
}
GET/status

Get server status and connected clients.

{
  "server": "Online",
  "websocket": "Connected",
  "clients": 3,
  "tasks": 0,
  "regions": {
    "us-east": {"clients": 2, "active": 2},
    "us-west": {"clients": 1, "active": 1}
  }
}
WS/ws

WebSocket endpoint for real-time client communication.

Client Implementation

Required Endpoints

All clients must implement a /work endpoint to receive tasks from Moonlight Server.

// Express.js example
app.post('/work', (req, res) => {
  const { payload } = req.body;
  
  // Process the task
  const result = processTask(payload);
  
  res.json({
    status: 'completed',
    result: result
  });
});

WebSocket Client

const WebSocket = require('ws');

const client = new WebSocket('ws://localhost:8080/ws');

client.on('open', () => {
  // Register client
  client.send(JSON.stringify({
    type: 'register',
    payload: {
      ip: '192.168.1.100',
      node_id: 'node-002',
      token: 'supersecrettokenox0',
      region: 'us-west',
      port: 3000
    }
  }));
});

client.on('message', (data) => {
  const message = JSON.parse(data);
  console.log('Received:', message);
});
Built with v0