Temps réel Socket.IO

Le backend embarque un serveur Socket.IO 4 attaché au même serveur HTTP que l'API, donc sur le même port (PORT, 2053 par défaut). Il diffuse l'annonce du gagnant et les crédits d'EtherPoints, compte les personnes présentes dans la salle d'attente du tirage et relaie le chat en direct. Les événements sont typés dans backend/src/types/socket.types.ts. Côté clients, la connexion est gérée par le hook useSocket du web et du mobile (voir Temps réel et Temps réel et notifications).

#Connexion et authentification

Le serveur accepte les origines de corsOrigins (FRONTEND_URL et CORS_ORIGINS), avec les méthodes GET et POST et les identifiants. Le chemin est celui par défaut de Socket.IO, /socket.io/. Le web s'y connecte avec NEXT_PUBLIC_WS_URL (http://localhost:2053 dans la stack Docker).

Le middleware socketAuthMiddleware cherche un jeton dans handshake.auth.token, puis dans l'en-tête Authorization: Bearer ... de la poignée de main.

import { io } from 'socket.io-client';

const socket = io('http://localhost:2053', { auth: { token: sessionToken } });
socket.on('connect', () => socket.emit('draw:join', currentRoundId));
socket.on('draw:winner', (winner) => console.log(winner.winnerWallet));

La vérification est faite une seule fois, à la connexion. Un jeton révoqué ou expiré pendant la session ne déconnecte pas le socket. Le rôle n'est utilisé par aucun gestionnaire : un invité et un administrateur ont exactement les mêmes possibilités.

#Salles

Socket.IO met chaque socket dans une salle à son nom. Le backend n'utilise qu'un type de salle supplémentaire : draw:<roundId>, la salle d'attente d'un tour.

sequenceDiagram
    participant A as "Citoyen A"
    participant S as "Serveur Socket.IO"
    participant B as "Citoyen B"
    A->>S: draw:join roundId
    S->>A: draw:waiting-room active true, onlineUsers 1
    B->>S: draw:join roundId
    S->>A: draw:waiting-room onlineUsers 2
    S->>B: draw:waiting-room onlineUsers 2
    B->>S: draw:leave roundId
    S->>A: draw:waiting-room onlineUsers 1

Le web et le mobile rejoignent la salle avec l'identifiant round.id (UUID en base) renvoyé par GET /lottery/status. roundId n'est pas validé : n'importe quelle chaîne crée une salle. Le compteur est celui du process : avec plusieurs instances de l'API, chacune compte ses propres sockets.

#Salle d'attente du tirage

La salle d'attente combine deux sources. Le calcul de la fenêtre est fait par l'API REST : GET /lottery/status renvoie remainingSeconds et inWaitingRoom, vrai pendant les 600 dernières secondes d'un tour OPEN. Le temps réel ne fournit que la présence (draw:waiting-room) et le résultat (draw:winner). L'événement draw:countdown, déclaré dans les types, n'est jamais émis : les clients calculent le compte à rebours eux-mêmes à partir de remainingSeconds.

À la fin du tour, en mode onchain, le keeper demande le tirage ; l'indexeur reçoit ensuite WinnerPicked et diffuse draw:winner. Les clients affichent l'annonce et invalident leurs caches (Lottery, Wallet, Admin sur le web). Voir Tirage et versement de la cagnotte.

#Chat en direct

{ "id": "6a1f0c2e-7b3d-4e58-9f60-1a2b3c4d5e6f", "senderWallet": "0x8b3f...6a08", "message": "Bonne chance à tous !", "timestamp": "2026-11-11T19:59:12.004Z" }

Un invité apparaît sous l'adresse 0xGues...0000. L'adresse affichée est celle du jeton au moment de la connexion.

#Relais depuis le worker

Les événements produits par l'indexeur doivent atteindre les navigateurs, même quand l'indexeur tourne dans le process worker, qui n'a pas de serveur Socket.IO. emitSocketEvent(event, payload) résout ce cas.

flowchart LR
    A["lotteryIndexer dans le worker"] --> B{"Serveur Socket.IO dans ce process ?"}
    B -- oui --> C["io.emit local"]
    B -- non --> D["PUBLISH sur le canal Redis"]
    D --> E["Abonné startSocketEventBridge dans l'API"]
    E --> F{"Événement autorisé ?"}
    F -- "draw:winner ou points:awarded" --> C2["io.emit dans l'API"]
    F -- autre --> G["ignoré"]

Si Redis est absent, l'événement émis par le worker est perdu (journalisé en warn). Quand l'API tourne avec RUN_WORKERS=true, l'indexeur est dans le même process et émet directement. Le service loterie en mode simulé et le tirage simulé appellent io.emit sans passer par ce relais.

Le serveur n'utilise pas d'adaptateur Redis de Socket.IO : avec plusieurs instances de l'API, un io.emit n'atteint que les clients de l'instance émettrice. Le relais Redis contourne ce problème pour les événements venant du worker, puisque chaque instance de l'API est abonnée et réémet ; il ne le fait pas pour les messages du chat ni pour les compteurs de salle.

#Référence des événements

#Du serveur vers les clients

#Des clients vers le serveur

#Types des données

Définis dans backend/src/types/socket.types.ts :

export interface LiveDrawCountdownEvent {
  roundId: string;
  contractRoundId: number;
  remainingSeconds: number;
  inWaitingRoom: boolean;
  participantsCount: number;
  prizePool: number;
}

export interface LiveDrawStartedEvent {
  roundId: string;
  contractRoundId: number;
  chainlinkRequestId: string;
  timestamp: string;
}

export interface LiveDrawWinnerEvent {
  roundId: string;
  contractRoundId: number;
  winnerWallet: string;
  prizePool: number;
  vrfProofHash: string;
  timestamp: string;
}

export interface ChatMessagePayload {
  id: string;
  senderWallet: string;
  message: string;
  emoji?: string;
  timestamp: string;
}

Le guide Ajouter un événement temps réel décrit les étapes pour en déclarer un nouveau, y compris son ajout à la liste des événements relayés.