JuByteNexus Bridge-Protokoll – Vollständige technische Referenz (v1)

1. Überblick

Das JuByteNexus Bridge-Protokoll verbindet Minecraft-Proxy- und Backend-Server mit dem zentralen Nexus-Core über WebSocket (JSON). Die Implementierung besteht aus:

• Proxy-Seite: NexusVelocityPlugin (Velocity, role: PROXY)
• Backend-Seite: NexusBridgePlugin (Paper, role: BACKEND)
• Core-Seite: BridgeWsHandler + BridgeManager (Spring WebSocket-Handler)
• Gemeinsame Lib: NexusBridgeClient (Reconnect, Heartbeat, Ban-Cache, Outbox)

2. Velocity-Plugin – Proxy-Spezifisches Verhalten

2.1 Lifecycle & Initialisierung

2.2 Was Velocity UNTERSCHIEDLICH macht (vs. Paper)

2.3 Weitergeleitete Events (Bridge → Core)

2.4 Kommandos (Core → Velocity)

2.5 Ban-Cache-Enforcement

Velocity:
  1. Handshake → Core sendet "ban.sync" mit allen aktiven BAN/TEMPBAN
  2. ProxyBridgeListener registriert BanCache.activeBan() im Client
  3. Bei Login: ban check PRÜFT lokal (< 1 ms), keine Netzwerk-Latenz
  4. Live: bei "ban.created" → client kickt sofort Spieler (if online)

Besonderheit Proxy: Ban-Evasion-Schutz über IP ist möglich, kann aber nur vom Paper-Backend konfiguriert werden. Velocity hält die IP-Ban-Liste aus dem Core-Sync, kann aber nicht selbst IP-Bans erzwingen (kümmert sich um Auth nicht).

3. Core WebSocket Handler – Server-Seite

3.1 Endpoint & Connection-Lifecycle

3.2 Handshake (Bridge → Core)

Request (erste Nachricht, type: handshake):

{
  "type": "handshake",
  "id": "<uuid>",
  "data": {
    "token": "<einmal-token ODER server-key>",
    "serverName": "lobby-1",
    "bridgeType": "PAPER" | "VELOCITY" | "BUNGEE",
    "role": "BACKEND" | "PROXY",
    "version": "0.1.0",
    "gameVersion": "1.21.4",
    "capabilities": ["KICK", "BROADCAST", "CHAT_READ", "EXECUTE", "SUBSERVER_AWARE"]
  }
}

Success-Response (type: handshake.ok):

{
  "type": "handshake.ok",
  "id": "<gen>",
  "data": {
    "serverId": "<uuid>",
    "serverKey": "nxk_<base64-48-bytes>" | null,
    "coreVersion": "0.1.0"
  }
}

Error-Response (type: handshake.error):

{
  "type": "handshake.error",
  "id": "<gen>",
  "data": {
    "code": "NX-3001",
    "message": "Bridge token invalid"
  }
}

Handshake-Logik (BridgeWsHandler.handshake):

1. Hash des token berechnen: SHA-256(credential)
2. Nachschlag in GameServer.serverKeyHash → Existiert?
   • Ja: Server bekannt, re-connect, kein neuer Key.
   • Nein: ServerToken mit diesem Hash suchen, used=false?
3. Bei neuer Server aus Token:
   • Neuer Server erzeugen/update GameServer (name, type, role, version, capabilities)
   • Zufälliger 48-Byte-Key generieren → nxk_<base64> → Hash speichern
   • Token als used=true markieren
4. ConnState(serverId, BoundedMap<2000 seenIds>) erstellen und registrieren
5. Antwort mit handshake.ok senden
6. Ban-Cache-Sync: BridgeManager.sendBanSync(session) (alle aktiven BAN/TEMPBAN/MUTE + Metadaten)
7. Message-Sync: BridgeManager.sendMessagesSync(session) (Panel-editierte Texte)
8. Template-Sync: TemplateSyncBridge.sendTo(session) (Ban- & Report-Templates)
9. Event publish: server.online

4. Kompletter Nachrichtenkatalog (Beide Richtungen)

4.1 Bridge → Core (Inbound in BridgeWsHandler)

Player Events

Server Events

Link & Punishment

Scheduler & Acknowledge

4.2 Core → Bridge (Outbound aus BridgeManager & BridgeWsHandler)

Ban-Cache-Synchronisation

Player Commands

Server Lifecycle

Console Streaming

Link & Messages

Templates

5. Verbindung & Resilienz

5.1 Heartbeat-Protokoll

Client-Seite (Bridge):
  - executor.scheduleAtFixedRate(heartbeat, 10, 10, TimeUnit.SECONDS)
  - Nur gesendet wenn ready=true (nach handshake.ok)
  - Payload: playersOnline + alle optional Metriken (paper) oder leer (velocity)

Core-Seite (BridgeWsHandler):
  case "heartbeat":
    - ServerMetrics.applyHeartbeat(server, data) → setzt alle Felder (optional-safe)
    - server.setLastSeenAt(Instant.now())
    - servers.save()
    - alertService.check() → Prüft auf Offline-Anomalien

Heartbeat-Timeout: Nicht implementiert; Core nutzt lastSeenAt für Admin-UI (keine auto-Disconnect bei fehlenden Heartbeats).

5.2 Reconnect & Exponential Backoff

Fehlerfall:
  - socket = null, ready = false
  - backoffSeconds *= 2, max 30s
  - LOG.warn("Core unreachable, retrying in {delay}s")
  - Outbox.add(message) für alle outgoing Events (max 10.000 queued)

Nach reconnect (handshake.ok):
  - backoffSeconds = 1 (reset)
  - Outbox.drain() → alle ausstehend Events flushen (FIFO)
  - Ban-Cache neu synced

Duplikat-Deduplizierung: Jede Nachricht hat eindeutige id. Core-Seite speichert seenIds pro Connection in BoundedMap<2000> (LRU). Bei Replay (z.B. retried message) wird duplikat ignoriert.

5.3 Offline-Verhalten (Cache)

6. Authentifizierung & Sicherheit

6.1 Token vs. Server-Key

6.2 Hash & Verifikation

handshake(data):
  credential = data.token
  credentialHash = SHA-256(credential)
  
  if (findByServerKeyHash(credentialHash)) → known server
  else if (findByTokenHashAndUsedFalse(credentialHash)) → new server
    token.used = true
    newServerKey = "nxk_" + Base64(random 48 bytes)
    sendResponse(handshake.ok, serverKey)
  else → credentials invalid
    sendResponse(handshake.error, NX-3001)
    close()

Kanal-Sicherheit: WebSocket über wss:// (TLS) empfohlen; credentials im data Feld unverschlüsselt (kein HTTP-Body-Encryption notwendig bei TLS).

7. Nachrichtenformat & Frame-Struktur

7.1 Allgemeine Nachricht

{
  "type": "<string>",
  "id": "<uuid oder custom-id>",
  "data": {
    ...
  }
}

• type: Nachrichten-Typ (z.B. player.join, command.kick, handshake)
• id: Eindeutige Frame-ID für Dedup. Bei Commands: echoed in command.ack. Optional für fire-and-forget Events.
• data: Payload als Objekt/Array/String, varies by type.

7.2 Message-ID Semantik

8. Fehlerbehandlung & Edge Cases

8.1 Fehler-Szenarien

8.2 Duplikat-Handling

Scenario: Bridge sendet player.join, dann Verbindung bricht und Reconnect spielt Outbox ab.

Client (Bridge):
  1. Send "player.join" id=abc123
  2. Disconnect
  3. Reconnect + handshake.ok
  4. Outbox.drain() → resend "player.join" id=abc123

Server (Core):
  1. Receive "player.join" id=abc123 → seenIds.add(abc123) ✓
  2. Disconnect
  3. Reconnect, new session, new seenIds = empty
  4. Receive "player.join" id=abc123 → seenIds.add(abc123) ✓
    (Pro Session, also nicht global duplikat-safe über Sessions hinweg)

Implication: Idempotenz auf Core-Seite nur pro Session. Wenn Backend über 2 Sessions versucht, selbe Event zweimal zu senden (nach brutaler Neubindung), wird es twice processed. Aktuell akzeptiert (spieler 2x join, dann quit).

9. Capability-System

Bridges berichten ihre Fähigkeiten im Handshake; Core prüft vor Kommando-Dispatch.

Velocity-Defaults: ["KICK", "BROADCAST", "SUBSERVER_AWARE"]
Paper-Defaults: ["KICK", "BROADCAST", "CHAT_READ", "EXECUTE"]

10. Performance & Skalierung

10.1 Latenz-Profile

10.2 Memory-Footprint

11. Konfiguration (Bridge-Seite)

11.1 Velocity: plugins/jubyte-nexus-bridge/nexus-bridge.properties

core-url=ws://localhost:8080/bridge/ws
server-name=proxy-1
token=<generated-from-acp>
server-key=nxk_<generated-on-first-handshake>

11.2 Paper: plugins/JuByteNexusBridge/config.yml

core-url: ws://localhost:8080/bridge/ws
server-name: server-1
token: ""
server-key: ""

Flow nach Token-Handshake:

1. ACP generiert Token, Admin gibt Token in Bridge ein
2. Bridge: token=<token>
3. Erstes Handshake → Core antwortet mit serverKey
4. BridgeListener.onServerKeyIssued(key) speichert persistent
5. Nächstes Handshake: token=<leer>, nutzt server-key stattdessen

12. Integrationen & Dependencies

12.1 Core-Seitig

12.2 Bridge-Seitig (Paper)

13. Testing & Debugging

13.1 Logging

Bridge-Seite:

nexus.bridge Logger (System.Logger)
  - WARN: "Core unreachable (…), retrying in 30s"
  - ERROR: "Core rejected handshake: NX-3001 — check the bridge token!"
  - INFO: "Ban cache synced: 42 entries"

Core-Seite:

org.springframework.web.socket → TRACE
  - Inbound frame (type=handshake, id=abc)
  - Outbound frame (type=ban.created, id=xyz)

13.2 Mock-Tests

NexusBridgeClient-Test:

BridgeConfig config = new BridgeConfig("ws://…", "test", "PAPER", "BACKEND", "0.1.0", "1.21", 
    List.of("KICK", "BROADCAST"), "token", "");
NexusBridgeClient client = new NexusBridgeClient(() -> config, listener, () -> 5);
// Manuell BridgeMessage.of("handshake.ok", ...) auf listener → ready.get() = true

14. Zusammenfassung: Differenzen Velocity vs. Paper

15. Referenz: Alle Message-Type Strings (Canonical List)

Inbound (Bridge → Core)

handshake
player.join
player.quit
player.chat
player.report
player.device
player.inventory
players.sync
vault.groups
heartbeat
link.request
punishment.request
punishment.revoke
chatlog.request
command.ack
console.line

Outbound (Core → Bridge)

handshake.ok
handshake.error
ban.sync
ban.created
ban.revoked
command.kick
command.teleport
command.setrank
command.message
command.broadcast
command.execute
server.power
console.subscribe
console.unsubscribe
link.code
messages.sync
templates.sync