Temps réel, reprise et attente d’un résultat
Le serveur décide qui reçoit quoi. Le client traduit ensuite les événements en mises à jour du cache. Le polling sert de secours quand aucun événement n’arrive. Les ajouts décrits ici sont implémentés et en attente de publication.
Contrat partagé
import {
defineRooms,
defineTopics,
type TopicsOf,
} from "@sia-ui/realtime-server";
export const rooms = defineRooms({
user: (id: string) => `user:${id}`,
task: (id: string) => `task:${id}`,
});
export const topics = defineTopics<{
"task.updated": { id: string; done: boolean };
}>();
export type Topics = TopicsOf<typeof topics>;Le contrat contrôle les clés et charges utiles à la compilation. Il n’analyse pas les données entrantes : leur validation runtime appartient à l’application. Les contrats n’importent ni Socket.IO, ni Redis, ni NestJS.
Passerelle côté serveur
import { createRealtimeGateway } from "@sia-ui/realtime-server";
const gateway = createRealtimeGateway({
server: io, // serveur Socket.IO fourni par l'application
topics,
authenticate: async (handshake) => authenticateHandshake(handshake),
rooms: (principal) => [rooms.user(principal.id)],
authorizeJoin: (principal, room) => canWatchRoom(principal, room),
onError: (error) => logger.error(error),
});
await gateway.publisher.publish(rooms.task("42"), "task.updated", {
id: "42",
done: true,
});authenticateHandshake et canWatchRoom sont les fonctions métier du projet. Le principal doit posséder un id non vide. Une connexion rejetée est fermée, sans recevoir de publication. Les salons implicites sont attribués par le serveur ; un client ne peut pas les quitter. Les autres jointures passent par authorizeJoin. Les messages sia:join et sia:leave reçoivent un accusé ok ou un code de refus, sans exposer les erreurs internes. Chaque socket est limité à 100 salons par défaut.
gateway.publisher se transmet comme port aux services métier ; noopPublisher<Topics>() remplace ce port dans leurs tests. gateway.dispose() désabonne le broker, ferme les connexions possédées et retire les écouteurs. presence(room) décrit les principaux connectés à cette instance, dédupliqués par identifiant.
Exemple NestJS, sans dépendance NestJS dans le paquet
Dans une gateway NestJS, exposer un namespace /realtime et créer la passerelle dans afterInit(server) avec le serveur Socket.IO reçu. Dans onModuleDestroy(), appeler gateway.dispose(). Exporter un provider REALTIME_PUBLISHER depuis le module ; les services injectent ce token plutôt que la gateway ou Socket.IO.
@WebSocketGateway({ namespace: "/realtime" })
export class EventsGateway implements OnGatewayInit, OnModuleDestroy {
constructor(
private readonly auth: AppAuth,
private readonly policy: RoomPolicy,
) {}
private gateway?: ReturnType<typeof createRealtimeGateway<Principal, Topics>>;
afterInit(server: Server) {
this.gateway = createRealtimeGateway<Principal, Topics>({
server,
authenticate: (h) => this.auth.authenticate(h),
rooms: (p) => [rooms.user(p.id)],
authorizeJoin: (p, room) => this.policy.canJoin(p, room),
});
}
// auth et policy sont des services injectés du projet.
async publish<K extends keyof Topics & string>(
room: string,
topic: K,
payload: Topics[K],
) {
if (!this.gateway) throw new Error("Passerelle non initialisée");
await this.gateway.publisher.publish(room, topic, payload);
}
onModuleDestroy() {
this.gateway?.dispose();
}
}Le module rend le port injectable :
@Module({
providers: [
EventsGateway,
AppAuth,
RoomPolicy,
{ provide: "REALTIME_PUBLISHER", useExisting: EventsGateway },
],
exports: ["REALTIME_PUBLISHER"],
})
export class RealtimeModule {}Les imports NestJS/Socket.IO et les types Principal/Topics sont fournis par l’application. La méthode publish peut être exposée par un provider via useExisting. L’authentification vérifie un jeton et les droits réels ; un salon demandé ne constitue jamais une preuve d’autorisation.
Salons et cache côté client
const socket = io("/realtime", {
auth: (callback) => callback({ token: session.accessToken() }),
});
const source = socketIoSource(socket);
const binding = createRealtimeBinding<Topics>({
source,
cache: queryClient,
on: {
"task.updated": (event, { invalidate }) => invalidate(["task", event.id]),
},
refetchOnRoomResync: (room) => [["room", room]],
});
// Dans React : source et binding restent stables entre les rendus.
useRealtimeRoom(source, rooms.task(taskId));
useEffect(() => binding.start(), [binding]);L’auth en fonction relit le jeton à chaque tentative de connexion. Elle ne renouvelle pas elle-même un jeton expiré : le store de session du projet doit le faire. Avec un socket déjà connecté, actualiser son authentification puis reconnecter lorsque nécessaire.
source.join(room) rend un nettoyage synchrone. Plusieurs vues peuvent suivre le même salon : le départ réseau n’est envoyé qu’à la dernière libération. Les refus et délais d’accusé sont observables avec onRoomError ; le hook rend cette erreur. Le client rejoint ses salons à la reconnexion. source.dispose() retire ses propres écouteurs et salons, sans déconnecter un socket dont l’application reste propriétaire.
Reprise, plusieurs instances et limites
Chaque publication possède un identifiant opaque, un horodatage et un numéro de séquence par instance émettrice, pas un compteur global distribué. Le client retient son curseur par salon et filtre les doublons d’une reprise par abonnement. Le serveur vérifie l’autorisation avant de rejouer les événements manqués. La reprise automatique concerne les salons suivis par source.join ou useRealtimeRoom. Pour les seuls salons implicites non suivis explicitement, garder une politique refetchOnReconnect adaptée aux requêtes de l’application. Les nouveaux événements attendent la fin de la reprise ; son tampon est borné à 1 000 événements par salon et un dépassement déclenche une resynchronisation.
Le journal mémoire par défaut est borné à 1 000 salons et 100 événements par salon. Un curseur expiré, inconnu ou absent après une coupure déclenche la resynchronisation du salon ; refetchOnRoomResync choisit uniquement les clés concernées. Les anciens refetchOnReconnect restent disponibles comme politique de rechargement globale.
Pour plusieurs instances, injecter Fanout avec publish(event) et subscribe(listener) => unsubscribe. L’adaptateur Redis ou autre appartient au projet et doit être prêt avant la passerelle. Les messages reçus du broker ne sont pas republiés en boucle. Pour la reprise après redémarrage, injecter aussi un ReplayStore partagé et durable ; un simple Pub/Sub ne conserve pas l’historique. Les callbacks du broker et le journal ne remplacent pas un outbox transactionnel.
throttlePerKey(publish, { intervalMs }) limite chaque clé indépendamment. Les appels intermédiaires partagent la promesse de la dernière valeur de la fenêtre. flush() attend les envois et vide la file ; cancel() abandonne les valeurs encore en attente. Les erreurs restent dans les promesses retournées. Ne pas ignorer ces promesses.
SSE et environnements sans EventSource
eventSourceSource(stream) prend une instance fournie par l’application. Il faut un EventSource web ou un polyfill compatible ; il n’est pas supposé exister dans tous les runtimes. Le paquet n’installe pas de polyfill. Le nettoyage restaure les callbacks préexistants et retire les abonnements ; la fermeture du flux reste à son propriétaire.
fetchStreamSource(url, { headers, signal }) est une alternative quand fetch, ReadableStream et TextDecoder existent. Elle accepte l’authentification par header, parse les événements nommés et JSON, reprend avec Last-Event-ID et ferme ses ressources avec dispose(). Une réponse 204 arrête définitivement la reprise. Les erreurs réseau réessayent ; les tampons et événements sont bornés à 1 Mio par défaut.
Côté serveur, createSseServer() adapte la passerelle : connect({ id, handshake, send, close }) écrit des frames SSE et rend une session. L’application configure Content-Type: text/event-stream, les heartbeats et le nettoyage HTTP. Les opérations de salons passent par session.request('sia:join', { room, cursor }) depuis une route de contrôle authentifiée et liée à cette session. SSE n’est pas bidirectionnel : ne pas exposer une route permettant de contrôler une autre session. L’adaptateur est indépendant de Node/Express/NestJS ; le framework fournit la réponse HTTP.
Attendre un résultat terminal
const result = await pollUntil((signal) => api.read(taskId, { signal }), {
isDone: (task) => task.done,
intervalMs: 1000,
backoff: 1.5,
maxIntervalMs: 10000,
timeoutMs: 120000,
signal: controller.signal,
});Une erreur de requête termine l’attente ; les retries d’erreurs HTTP relèvent du client d’API. L’échéance borne aussi une requête qui ignore le signal. Une seule réponse est attendue à la fois par la boucle. Une fonction ignorant son signal peut poursuivre son propre travail après annulation ; lui transmettre le signal HTTP.
const visibility = useMemo(() => documentVisibilitySource(document), []);
const state = usePollUntil((signal) => readTask(taskId, signal), {
key: taskId,
isDone: (task) => task.done,
visibility,
subscribe: taskEvents.subscribe, // abonnement stable et filtré sur la tâche
});usePollUntil rend idle, polling, paused, success ou error, avec data. La visibilité est injectable : le hook headless ne dépend ni du DOM ni d’une plateforme native. Le temps passé en arrière-plan compte dans le timeout. Un événement final termine l’attente et annule la requête en cours. Changer key démarre une nouvelle attente ; les callbacks inline de lecture et de validation ne la relancent pas.