WebSocket API

Real-time communication between agents, API, and clients using WebSocket protocol.

Connection

Agent Connection

const ws = new WebSocket('wss://api.arcadiumpanel.com/ws/agent');

ws.on('open', () => {
  ws.send(JSON.stringify({
    event: 'auth',
    data: {
      token: 'agent_token_...',
      machineId: 'mch_123',
      version: '0.4.18'
    }
  }));
});

Client Connection

Dashboard clients connect for real-time updates:

const ws = new WebSocket('wss://api.arcadiumpanel.com/ws/client');

ws.on('open', () => {
  ws.send(JSON.stringify({
    event: 'auth',
    data: {
      token: 'user_token_...'
    }
  }));
});

Message Format

All messages use JSON format:

{
  event: string;
  data: any;
  timestamp?: number;
  id?: string; // For request-response pattern
}

Agent Events

Authentication

Client → Server:

{
  "event": "auth",
  "data": {
    "token": "agent_token_...",
    "machineId": "mch_123",
    "version": "0.4.18"
  }
}

Server → Client:

{
  "event": "authenticated",
  "data": {
    "machineId": "mch_123",
    "clusterId": "clu_abc"
  }
}

Heartbeat

Agents send periodic heartbeat with basic metrics:

Client → Server (every 30s):

{
  "event": "heartbeat",
  "data": {
    "machineId": "mch_123",
    "timestamp": 1641823200,
    "cpu": 45.2,
    "memory": 8192,
    "uptime": 86400
  }
}

Metrics

Detailed metrics sent every 5 minutes:

{
  "event": "metrics",
  "data": {
    "machineId": "mch_123",
    "cpu": {
      "cores": 8,
      "usage": [45.2, 32.1, 67.8, ...],
      "average": 48.3
    },
    "memory": {
      "total": 16384,
      "used": 8192,
      "free": 8192
    },
    "disk": [...],
    "network": {...}
  }
}

Server Status

Server state changes are reported immediately:

{
  "event": "server:status",
  "data": {
    "serverId": "srv_xyz",
    "status": "online",
    "players": 12,
    "maxPlayers": 50
  }
}

Commands

Server → Client (command request):

{
  "event": "command",
  "data": {
    "id": "cmd_123",
    "type": "server:start",
    "serverId": "srv_xyz"
  }
}

Client → Server (command response):

{
  "event": "command:response",
  "data": {
    "id": "cmd_123",
    "success": true,
    "result": {
      "status": "starting",
      "pid": 12345
    }
  }
}

Client Events

Dashboard clients receive real-time updates:

Server Updates

{
  "event": "server:updated",
  "data": {
    "serverId": "srv_xyz",
    "status": "online",
    "players": 15
  }
}

Player Events

{
  "event": "player:joined",
  "data": {
    "serverId": "srv_xyz",
    "player": {
      "id": "ply_123",
      "username": "PlayerOne",
      "steamId": "76561198012345678"
    }
  }
}

Notifications

{
  "event": "notification",
  "data": {
    "type": "info",
    "message": "Server ARK-Island restarted",
    "clusterId": "clu_abc"
  }
}

Connection Management

Reconnection

Clients should implement exponential backoff:

let reconnectDelay = 1000;
const maxDelay = 30000;

function connect() {
  const ws = new WebSocket(url);
  
  ws.on('close', () => {
    setTimeout(() => {
      reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
      connect();
    }, reconnectDelay);
  });
  
  ws.on('open', () => {
    reconnectDelay = 1000; // Reset on successful connection
  });
}

Ping/Pong

WebSocket ping/pong keeps connection alive:

• Server sends ping every 30 seconds
• Client must respond with pong
• Connection closed if no pong received

Security

Authentication

All connections must authenticate within 10 seconds:

1. Connect to WebSocket
2. Send auth event with token
3. Wait for authenticated response
4. Connection closed if auth fails

Token Validation

• Tokens validated on every connection
• Expired tokens rejected
• Invalid tokens result in immediate disconnect

Error Handling

Error Events

{
  "event": "error",
  "data": {
    "code": "AUTH_FAILED",
    "message": "Invalid token",
    "timestamp": 1641823200
  }
}

Common Error Codes

Code	Description
AUTH_FAILED	Authentication failed
AUTH_TIMEOUT	No auth within 10 seconds
INVALID_MESSAGE	Malformed JSON
COMMAND_FAILED	Command execution failed
RATE_LIMIT	Too many messages

Best Practices

Message Handling

• Always validate message format
• Handle unknown event types gracefully
• Log unexpected messages for debugging

Resource Management

• Close connections when not needed
• Implement proper cleanup on disconnect
• Avoid excessive message frequency

Error Recovery

• Implement reconnection logic
• Queue messages during disconnect
• Resend on reconnection

Next Steps

• Authentication
• API Endpoints