Configuration du serveur

Exemple minimal

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));

Les valeurs par défaut conviennent pour la plupart des cas d'utilisation ; des remplacements supplémentaires sont listés ci‑dessous.

Pour la vérification d'authentification de la connexion ici.

Réseau et liaison

Propriété	Type	Par défaut	Description
nom d'hôte	Chaîne	null	Adresse de liaison. Si non définie, se lie à 0.0.0.0 / ::0
port	int	-1	Port du serveur (doit être défini)
contexte	Chaîne	/socket.io	Chemin de contexte Socket.IO

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

---

Modèle de threads

Propriété	Type	Par défaut	Remarques
bossThreads	int	0	CPU * 2 lorsque la valeur est 0
workerThreads	int	0	CPU * 2 lorsque la valeur est 0

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

Threads Boss vs Worker Les threads boss acceptent les connexions ; les threads worker gèrent tout l'I/O. Ajouter des threads boss seulement pour augmenter le taux d'acceptation des connexions; utiliser 1 pour la plupart des cas. Augmentez les threads worker pour le débit — trop nombreux causent des changements de contexte.

---

Configuration des transports

Propriété	Type	Par défaut	Description
transports	List<Transport>	WEBSOCKET, POLLING	Transports activés
transportType	TransportType	AUTO	Sélection d'E/S native (EPOLL / KQUEUE / IO_URING / NIO)
upgradeTimeout	int (ms)	10000	Délai d'attente pour la mise à niveau Polling → WebSocket

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

En mode de transport AUTO, socketio4j sélectionne automatiquement le meilleur transport disponible au démarrage dans l'ordre suivant : IO_URING → EPOLL → KQUEUE → NIO.

Si le transport sélectionné n'est pas disponible sur la plateforme actuelle, socketio4j retombe en toute sécurité sur NIO sans échouer au démarrage.

---

Heartbeat et délais

Propriété	Par défaut	Description
pingInterval	25000 ms	Intervalle de ping
pingTimeout	60000 ms	Délai d'attente du ping (0 désactive)
firstDataTimeout	5000 ms	Prévient les attaques de canaux silencieux

ℹ️ Intervalle de ping vs délai de ping pingInterval définit la fréquence à laquelle le serveur envoie des pings de heartbeat pour maintenir la connexion (keep-alive NAT). pingTimeout définit combien de temps le serveur attend sans un pong avant de considérer le client comme déconnecté.

En bref : intervalle = à quelle fréquence vérifier, timeout = combien de temps attendre avant d'abandonner.

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

Indice sur le délai NAT et le keep-alive pingInterval doit être plus court que les délais d'inactivité NAT typiques (généralement 30–60s) pour maintenir les connexions en vie derrière des routeurs et des réseaux mobiles.

Des valeurs plus basses améliorent la survivabilité NAT et la détection plus rapide des pairs morts, mais augmentent la charge réseau et CPU. Des valeurs plus élevées réduisent la charge, mais risquent des déconnexions silencieuses sur les NAT et les équilibreurs de charge.

---

Limites de charge utile et de trame

Propriété	Par défaut	Description
maxHttpContentLength	64 Ko	Taille maximale de la requête HTTP
maxFramePayloadLength	64 Ko	Taille maximale de la trame WebSocket

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

---

CORS et comportement HTTP

Propriété	Par défaut	Description
enableCors	true	Activer CORS
origin	null	Access-Control-Allow-Origin
allowHeaders	null	Access-Control-Allow-Headers
addVersionHeader	true	Ajoute Server en‑tête
allowCustomRequests	false	Autoriser les requêtes non Socket.IO

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

---

Compression

Propriété	Par défaut	Description
httpCompression	true	GZIP / Deflate
websocketCompression	true	permessage-deflate

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

---

Gestion du buffer et des ACK

Propriété	Par défaut	Description
preferDirectBuffer	true	Utiliser les buffers directs Netty
ackMode	AUTO_SUCCESS_ONLY	Comportement Auto-ACK

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

Comportement des ACK

• Les ACK sont envoyés au plus une fois et uniquement si demandé

• Ack manuel supprime toujours l'auto-ack

• AUTO → acquitte toujours automatiquement avec [] (même en cas d'exception)

• AUTO_SUCCESS_ONLY → acquitte automatiquement avec [] uniquement en cas de succès

• MANUEL → le développeur est entièrement responsable de l'envoi de l'ack

---

Session et sécurité

Propriété	Par défaut	Description
randomSession	false	Randomiser les IDs de session
needClientAuth	false	Authentification TLS du client

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

---

Sérialisation JSON

Propriété	Par défaut	Description
jsonSupport	Détecté automatiquement	Basé sur Jackson par défaut

config.setJsonSupport(new JacksonJsonSupport());

---

Autorisation

Propriété	Par défaut	Description
authorizationListener	Autoriser tout	Autorisation de la poignée de main

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

---

Gestion des exceptions

Propriété	Par défaut	Description
exceptionListener	DefaultExceptionListener	Hook d'exception global

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

---

Stockage / Clustering

config.setStoreFactory(new RedisStoreFactory(redissonClient));

Veuillez vérifier Adaptateurs Page pour une explication détaillée.

---

SSL / TLS

SocketSslConfig ssl = new SocketSslConfig();
ssl.setKeyStore("keystore.jks");
ssl.setKeyStorePassword("changeit");
/**
//n'utilisé que dans les scénarios mTLS/zero-trust, pas d'habitude pour wss
ssl.setTrustStore("truststore.jks");
ssl.setTrustStorePassword("changeit");
*/
config.setSocketSslConfig(ssl);

---

Ajustement du décodeur HTTP

Propriété	Par défaut
maxInitialLineLength	Valeur par défaut de Netty
maxHeaderSize	Valeur par défaut de Netty
maxChunkSize	Valeur par défaut de Netty

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

---

📌 Astuce : La configuration est clonée en interne pour l'immuabilité. Traitez-la comme écrite une fois avant le démarrage du serveur.