docs/api/Websocket Events

Websocket Events

WebSocket Events & Telemetrie

Neben den klassischen Webhooks für serverseitige Benachrichtigungen bietet KiroCloud native WebSocket-Verbindungen an. Diese sind ideal, um auf einer Website oder in einem Dashboard Live-Updates (wie CPU-Auslastung oder Konsolenausgaben eines Bots) in Echtzeit darzustellen.

Die WebSocket-API ist direkt unter /ws/ verfügbar. Im Gegensatz zur HTTP-API wird zur Authentifizierung der JWT-Token im Query-String ?token=... oder per Cookie übergeben.

1. Dashboard WebSocket (Bot-Telemetrie)

Dieser Endpunkt liefert Live-Daten für einen spezifischen Bot. Das ist nützlich, wenn du ein eigenes Web-Interface für deine Discord Bots bauen möchtest, in dem die User die Live-Konsole ihres Bots sehen können.

Endpunkt:wss://api.kirocloud.de/ws/dashboard?botId=DEINE_BOT_ID&token=DEIN_API_TOKEN

Unterstützte Events

Wenn du dich verbindest, erhältst du sofort ein subscribed Event sowie die Log-Historie (falls vorhanden). Danach pusht der Server bei Änderungen folgende Events:

bot:status - Wird gesendet, wenn der Bot online, offline oder abgestürzt ist.
bot:log - Jede neue Konsolenausgabe (stdout/stderr) des Bots.
bot:stats - Echtzeit CPU- und RAM-Auslastung des Bots (wird i.d.R. im Sekundentakt gepusht).
bot:log_history - Ein Array der letzten Log-Einträge, direkt nach der Verbindung gesendet.

Beispiel: Implementierung im Frontend (JavaScript)

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="UTF-8">
  <title>KiroBot Live Konsole</title>
  <style>
    body { background: #111; color: #0f0; font-family: monospace; padding: 20px; }
    #console { white-space: pre-wrap; }
  </style>
</head>
<body>
  <h2>Live Konsole</h2>
  <div id="console"></div>

  <script>
    const BOT_ID = '1234567890';
    // HINWEIS: Niemals den API-Key dauerhaft im Frontend hardcoden!
    // Nutze Cookies oder einen Backend-Proxy in Produktion.
    const TOKEN = 'DEIN_API_KEY'; 

    const ws = new WebSocket(`wss://api.kirocloud.de/ws/dashboard?botId=${BOT_ID}&token=${TOKEN}`);

    const consoleDiv = document.getElementById('console');

    ws.onmessage = (event) => {
      try {
        const payload = JSON.parse(event.data);
        
        switch (payload.event) {
          case 'subscribed':
            console.log('Erfolgreich mit dem Websocket verbunden!');
            break;

          case 'bot:log_history':
            // Initialer Log-Dump
            payload.data.forEach(logLine => {
              consoleDiv.textContent += logLine + '\n';
            });
            break;

          case 'bot:log':
            // Neue, einzelne Log-Zeile
            consoleDiv.textContent += payload.data + '\n';
            window.scrollTo(0, document.body.scrollHeight);
            break;

          case 'bot:status':
            consoleDiv.textContent += `[SYSTEM] Bot Status geändert zu: ${payload.data.status}\n`;
            break;

          case 'bot:stats':
            // payload.data enthält z.B. { cpu: 2.5, memory: 120 }
            document.title = `RAM: ${payload.data.memory}MB`;
            break;
        }
      } catch (err) {
        // Fallback falls die Daten mal kein JSON sind
        consoleDiv.textContent += event.data + '\n';
      }
    };

    ws.onerror = (error) => {
      console.error('WebSocket Error:', error);
      consoleDiv.textContent += `[WS ERROR] Verbindung fehlgeschlagen.\n`;
    };

    ws.onclose = () => {
      consoleDiv.textContent += `[WS CLOSED] Verbindung getrennt.\n`;
    };
  </script>
</body>
</html>

2. Admin WebSocket (System-Events)

Dieser Endpunkt erfordert Administrator-Rechte (admin oder owner). Er pusht globale Ereignisse über die gesamte Plattform (wie Server-Statistiken oder das Anlegen neuer Nutzer).

Endpunkt:wss://api.kirocloud.de/ws/admin?token=DEIN_ADMIN_TOKEN

Implementierung im Backend (Node.js)

Oftmals baut man für Admin-Aufgaben kein HTML-Frontend, sondern bindet den WebSocket in einem Backend-Service oder Überwachungstool (z.B. einem zentralen Logger) ein. Dafür kannst du in Node.js die ws-Bibliothek nutzen.

// npm install ws
import WebSocket from 'ws';

const ADMIN_TOKEN = 'DEIN_API_KEY';
const ws = new WebSocket(`wss://api.kirocloud.de/ws/admin?token=${ADMIN_TOKEN}`);

ws.on('open', () => {
  console.log('Mit KiroCloud Admin WebSocket verbunden!');
});

ws.on('message', (data) => {
  const payload = JSON.parse(data.toString());
  
  if (payload.event === 'init') {
    console.log('Authentifizierung erfolgreich.');
  } else {
    console.log(`[GLOBAL EVENT] ${payload.event}`, payload.data);
  }
});

ws.on('close', (code, reason) => {
  console.log(`Verbindung geschlossen (${code}):`, reason.toString());
});

ws.on('error', (err) => {
  console.error('WebSocket Fehler:', err.message);
});

Fehlerbehebung (Statuscodes)

Sollte die WebSocket-Verbindung sofort nach dem Öffnen wieder geschlossen werden, prüfe den Close Code:

1008 Policy Violation: Dies bedeutet meistens invalid token (Token ist falsch/abgelaufen) oder forbidden (Der API-Schlüssel hat keine Berechtigung für diesen Endpunkt / ist kein Admin).
1008 Policy Violation mit token+botId required: Du hast vergessen, den Parameter botId an die Dashboard-URL anzuhängen.