Serverkonfiguration

Minimales Beispiel

Configuration config = new Configuration();
config.setHostname("127.0.0.1");
config.setPort(9092);
config.setContext("/socket.io");
config.setTransports(Transport.POLLING, Transport.WEBSOCKET);
config.setStoreFactory(new RedisStoreFactory(redissonClient));

Standardeinstellungen funktionieren für die meisten Anwendungsfälle; zusätzliche Überschreibungen sind unten aufgeführt.

Für Verbindungs-Authentifizierung prüfen hier.

Netzwerk & Bindung

Eigenschaft	Typ	Standard	Beschreibung
hostname	String	null	Bind-Adresse. Wenn nicht gesetzt, bindet an 0.0.0.0 / ::0
port	int	-1	Server-Port (muss gesetzt werden)
context	String	/socket.io	Socket.IO-Kontextpfad

config.setHostname("0.0.0.0");
config.setPort(9092);
config.setContext("/socket.io");

---

Threading-Modell

Eigenschaft	Typ	Standard	Hinweise
bossThreads	int	0	CPU * 2 wenn der Wert auf 0 gesetzt ist
workerThreads	int	0	CPU * 2 wenn der Wert auf 0 gesetzt ist

config.setBossThreads(2);
config.setWorkerThreads(16);

Boss- vs. Worker-Threads Boss-Threads akzeptieren Verbindungen; Worker-Threads übernehmen alle I/O-Aufgaben. Füge Boss-Threads nur hinzu, um die Verbindungsannahmerate; verwende 1 für die meisten Fälle. Skaliere Worker-Threads für Durchsatz—zu viele verursachen Context-Switching.

---

Transport-Konfiguration

Eigenschaft	Typ	Standard	Beschreibung
transports	List<Transport>	WEBSOCKET, POLLING	Aktivierte Transporte
transportType	TransportType	AUTO	Native IO-Auswahl (EPOLL / KQUEUE / IO_URING / NIO)
upgradeTimeout	int (ms)	10000	Timeout für Upgrade von Polling → WebSocket

config.setTransports(Transport.WEBSOCKET);
config.setTransportType(TransportType.EPOLL);

Im AUTO-Transportmodus wählt socketio4j beim Start automatisch den bestmöglichen verfügbaren Transport in folgender Reihenfolge aus: IO_URING → EPOLL → KQUEUE → NIO.

Wenn der ausgewählte Transport auf der aktuellen Plattform nicht verfügbar ist, fällt socketio4j sicher auf NIO zurück ohne den Start fehlschlagen zu lassen.

---

Heartbeat & Timeouts

Eigenschaft	Standard	Beschreibung
pingInterval	25000 ms	Ping-Intervall
pingTimeout	60000 ms	Ping-Timeout (0 deaktiviert)
firstDataTimeout	5000 ms	Verhindert stille Kanalangriffe

ℹ️ Ping-Intervall vs. Ping-Timeout pingInterval definiert, wie oft der Server Heartbeat-Pings sendet, um die Verbindung am Leben zu erhalten (NAT-Keep-Alive). pingTimeout definiert, wie lange der Server wartet ohne ein Pong bevor der Client als getrennt betrachtet wird.

Kurz gesagt: interval = wie oft geprüft wird, timeout = wie lange gewartet wird, bevor aufgegeben wird.

config.setPingInterval(20000);
config.setPingTimeout(60000);
config.setFirstDataTimeout(5000);

NAT-Timeout & Keep-Alive-Hinweis pingInterval muss kürzer als typische NAT-Leerlauf-Timeouts sein (normalerweise 30–60s), um Verbindungen hinter Routern und Mobilfunknetzen am Leben zu erhalten.

Niedrigere Werte verbessern die NAT-Überlebensfähigkeit und die schnellere Erkennung toter Peers, aber erhöhen Netzwerk- und CPU-Overhead. Höhere Werte reduzieren den Overhead, bergen jedoch das Risiko von stillen Verbindungen bei NATs und Load Balancern.

---

Payload- & Frame-Limits

Eigenschaft	Standard	Beschreibung
maxHttpContentLength	64 KB	Maximale HTTP-Anfragegröße
maxFramePayloadLength	64 KB	Maximale WebSocket-Frame-Größe

config.setMaxHttpContentLength(256 * 1024);
config.setMaxFramePayloadLength(256 * 1024);

---

CORS & HTTP-Verhalten

Eigenschaft	Standard	Beschreibung
enableCors	true	CORS aktivieren
origin	null	Access-Control-Allow-Origin
allowHeaders	null	Access-Control-Allow-Headers
addVersionHeader	true	Fügt hinzu Server Header
allowCustomRequests	false	Erlaube Nicht-Socket.IO-Anfragen

config.setEnableCors(true);
config.setOrigin("https://example.com");
config.setAllowHeaders("Authorization,Content-Type");

---

Kompression

Eigenschaft	Standard	Beschreibung
httpCompression	true	GZIP / Deflate
websocketCompression	true	permessage-deflate

config.setHttpCompression(true);
config.setWebsocketCompression(true);

---

Puffer- & ACK-Verarbeitung

Eigenschaft	Standard	Beschreibung
preferDirectBuffer	true	Verwende Netty Direct-Buffers
ackMode	AUTO_SUCCESS_ONLY	Auto-ACK-Verhalten

config.setPreferDirectBuffer(true);
config.setAckMode(AckMode.AUTO);

Ack-Verhalten

• Acks werden gesendet höchstens einmal und nur wenn angefordert

• Manuelles Ack unterdrückt immer Auto-Ack

• AUTO → bestätigt immer automatisch mit [] (auch bei Ausnahme)

• AUTO_SUCCESS_ONLY → bestätigt automatisch mit [] nur bei Erfolg

• MANUAL → der Entwickler ist voll verantwortlich für das Senden des Acks

---

Sitzung & Sicherheit

Eigenschaft	Standard	Beschreibung
randomSession	false	Session-IDs randomisieren
needClientAuth	false	TLS-Client-Authentifizierung

config.setRandomSession(true);
config.setNeedClientAuth(true);

---

JSON-Serialisierung

Eigenschaft	Standard	Beschreibung
jsonSupport	Automatisch erkannt	Standardmäßig Jackson-basiert

config.setJsonSupport(new JacksonJsonSupport());

---

Autorisierung

Eigenschaft	Standard	Beschreibung
authorizationListener	Erlaube alle	Handshake-Autorisierung

config.setAuthorizationListener(data -> {
    return AuthorizationResult.SUCCESS;
});

---

Fehlerbehandlung

Eigenschaft	Standard	Beschreibung
exceptionListener	DefaultExceptionListener	Globaler Ausnahme-Hook

config.setExceptionListener(new ExceptionListener() {
    @Override
    public void onEventException(Exception e, Object... args) {
        log.error("Socket.IO error", e);
    }
});

---

Speicher / Clustering

config.setStoreFactory(new RedisStoreFactory(redissonClient));

Bitte prüfen Adapter Seite für detaillierte Erklärung.

---

SSL / TLS

SocketSslConfig ssl = new SocketSslConfig();
ssl.setKeyStore("keystore.jks");
ssl.setKeyStorePassword("changeit");
/**
//wird nur verwendet, wenn mTLS/Zero-Trust-Szenarien vorliegen, normalerweise nicht für wss
ssl.setTrustStore("truststore.jks");
ssl.setTrustStorePassword("changeit");
*/
config.setSocketSslConfig(ssl);

---

HTTP-Decoder-Tuning

Eigenschaft	Standard
maxInitialLineLength	Netty-Standard
maxHeaderSize	Netty-Standard
maxChunkSize	Netty-Standard

HttpRequestDecoderConfiguration http = new HttpRequestDecoderConfiguration();
http.setMaxHeaderSize(16 * 1024);
config.setHttpRequestDecoderConfiguration(http);

---

📌 Tipp: Die Konfiguration wird intern zur Unveränderlichkeit geklont. Behandle sie als einmalig beschreibbar vor dem Serverstart.