UniverselWebSocketServer

Présentation

UniverselWebSocketServer est une extension de WebSocketServer (librairie ws) visant à fournir un serveur WebSocket robuste, universel et tolérant, intégrant nativement :

• un système de heartbeat (détection de clients morts),
• une compatibilité ping/pong protocolaire ou applicative,
• un filtrage sécurisé des messages,
• une abstraction des événements message utilisateur,
• une gestion automatique du cycle de vie.

Cette classe est pensée pour des environnements Node.js nécessitant des connexions WebSocket longues durées, stables et supervisées.

---

Objectifs

• Détecter et fermer automatiquement les connexions mortes
• Supporter des clients WebSocket hétérogènes
• Sécuriser la réception des messages
• Offrir une API compatible avec ws
• Éviter les conflits entre protocoles ping/pong et messages applicatifs

---

Dépendances

import { WebSocketServer, WebSocket, ServerOptions } from "ws";

---

Types exposés

UniverselWebSocket

export type UniverselWebSocket = WebSocket & {
  isAlive: boolean;
};

Ajoute un état interne permettant le suivi du heartbeat.

---

OptionUniverselWebSocketServer

type OptionUniverselWebSocketServer = ServerOptions & {
  pingPongProtocol?: boolean;
  heartbeat?: boolean;
  heartbeatInterval?: number;
};

Options supplémentaires

Option	Description
heartbeat	Active le système de heartbeat
heartbeatInterval	Intervalle de ping (ms, défaut 30000)
pingPongProtocol	Utilise ping/pong WebSocket natif ou messages texte

---

Initialisation

const wss = new UniverselWebSocketServer({
  port: 8080,
  heartbeat: true,
  heartbeatInterval: 30000,
  pingPongProtocol: true
});

---

Système de heartbeat

Principe

Le serveur envoie périodiquement des ping à chaque client connecté :

• si le client répond → connexion conservée
• si le client ne répond pas → connexion terminée

---

Implémentation

• isAlive est mis à false avant chaque ping
• un pong remet isAlive à true
• si isAlive === false au cycle suivant → terminate()

Conseil

Cela permet d’éviter les connexions fantômes causées par des coupures réseau.

---

Ping / Pong universel

Modes supportés

Mode	Comportement
Protocolaire	ws.ping() / ws.pong()
Applicatif	Messages "ping" / "pong"

pingPongProtocol: true  // protocole WebSocket
pingPongProtocol: false // messages texte

---

Raison

Certains clients (navigateurs, libs custom) ne supportent pas correctement les frames ping/pong. Ce mode hybride garantit une interopérabilité maximale.

---

Gestion sécurisée des messages

Interception des messages

• Les messages "ping" / "pong" sont traités en interne

• Les autres messages sont :

  • émis via safeMessage
  • relayés aux listeners utilisateur

---

Événement safeMessage

ws.on("safeMessage", (data) => {
  // message applicatif garanti sans ping/pong
});

---

Isolation des listeners utilisateur

Les handlers message ajoutés par l’utilisateur sont capturés et appelés manuellement après filtrage.

Cela évite :

• la double gestion des ping/pong
• les effets de bord
• les erreurs côté application

---

Surcharge contrôlée de ws.on

ws.on = (event, listener) => {
  if (event === "message") {
    userMessageListeners.push(listener);
    return ws;
  }
  return origOn(event, listener);
};

Avertissement

Cette interception est volontaire et fait partie du design de la classe.

---

Cycle de vie

Connexion

• initialisation du heartbeat
• configuration ping/pong
• mise en place du filtre de messages

---

Fermeture du serveur

this.on("close", () => {
  clearInterval(this.heartbeatInterval);
});

Nettoyage automatique des ressources.

---

Exemple d’utilisation

const wss = new UniverselWebSocketServer({
  port: 8080,
  heartbeat: true
});

wss.on("connection", (ws: UniverselWebSocket) => {
  ws.on("safeMessage", (data) => {
    console.log("Message reçu:", data.toString());
  });

  ws.on("message", (data) => {
    // Listener utilisateur standard
  });
});

---

Bonnes pratiques

• Activer le heartbeat en production
• Ajuster l’intervalle selon la charge réseau
• Utiliser safeMessage pour la logique métier
• Éviter de traiter ping/pong côté application
• Monitorer les fermetures de connexions

---

Limites connues

• Fonctionne uniquement avec la librairie ws
• Pas de support natif TLS (délégué à ws)
• Pas de gestion de backpressure avancée

---

Conclusion

UniverselWebSocketServer apporte une surcouche fiable et pragmatique à WebSocketServer, adaptée aux environnements réels et hétérogènes. Il améliore la stabilité, la sécurité et la lisibilité du code sans modifier l’API fondamentale de WebSocket.