Nodefony 10.0.2
Framework Node.js fullstack — HTTP & WebSocket, même contexte

Présence répartie d'un canal temps réel — portée par le canal lui-même

accepted

Summary. “Who is in this room?” used to be answered per process only: once an application ran as several instances, each one saw nothing but its own connections, and every application had to rebuild heartbeats, crash detection and multi-tab counting by hand. This ADR makes presence a framework feature, enabled per channel with presence: true and carried by the channel itself — being admitted to a channel is what grants its presence, with no second channel to open and no global identity registry. Between instances it travels as batched, sequence-numbered changes plus a heartbeat of a few dozen bytes, so the idle cost follows the number of instances, never the number of channels or members. For a user it means one policy key on the server and one hook in the browser (useNodefonyPresence) that yields a list consistent within one heartbeat interval, exact departures by default and an optional grace period.

Le « comment » est dans les guides — cookbook du chat, étape 3 « présence et frappe en cours » et client, « Qui est là — la présence d’un canal » ; cet ADR porte le « pourquoi ».

Statut#

Accepté (2026-11-10), en vigueur : aucun autre ADR ne le remplace. Il rouvre la décision D1 d’ADR-0022 (la présence passe de l’application au framework, voir P1) et s’appuie sur les garanties de livraison et les compteurs d’ADR-0021. Chaque décision porte sa ligne datée : P1 a été arrêtée d’abord, P2 à P5 après une revue contradictoire (§ « Comment P2 à P5 ont été tranchés »). Jugé contre le catalogue scenarios/temps-reel.md, scénarios S-rt-84 à S-rt-110. L’architecture temps réel est gelée : la surface neuve ne se code qu’une fois cet ADR accepté, puis entre dans la fixture frozenSurface.

Décision (2026-11-10) : l’ADR est accepté en entier, P2 à P5 compris, sur la synthèse de la revue contradictoire. Le code reste conditionné à la revue finale côte à côte d’ADR-0021, 0022 et 0025.

Revue finale (2026-11-10) : la revue côte à côte des trois ADR a rendu dix-sept constats, chacun vérifié au code ; ce texte les intègre EN PLACE. Ce qui a changé : la preuve de vie passe hors quota sur son propre canal ; le bus perdu se constate par l’écho de sa propre preuve de vie ; numéros seq / prev / last au lieu d’une version unique ; incarnation entière bornée ; forme du lot entre pods prête pour l’état ; demande d’état qui nomme ses canaux ; aucun verbe client neuf (subscribe suffit) ; unnamed au lieu d’anonymous ; compteurs nommés ; règle d’application pure, partagée par le navigateur et le pod ; budgets séparés en invariants testés et mesures de banc.

Confrontation aux normes (2026-11-10) : cet ADR avait été écrit sans consulter les normes de présence. Trois relectures indépendantes l’ont confronté à XMPP (RFC 6121, XEP-0045), à SIP / PIDF (RFC 2778, 3856, 3863, 4479, 5262, 5263, 6665) et à l’état de l’art réparti (SWIM, Lifeguard, la spécification Matrix, et les implémentations existantes de suivi de présence et d’appartenance à un cluster) ; chaque citation décisive a été recontrôlée dans le texte source. Aucune décision de fond n’est contredite. Les trous qu’elles ont révélés sont comblés EN PLACE : la liste ne consomme pas de version ; la borne serveur de renvoi de la liste est retirée ; la réponse d’état porte last, s’applique d’un bloc, et une demande ciblée reçoit toujours une réponse ; la preuve de vie annonce son intervalle ; l’oubli résiste au gel du récepteur ; la vue cliente connaît l’état « non synchronisée » ; le champ partial ; la forme par identité { tabs, states? } ; le départ d’un pod arrêté proprement et la grâce. Source par source : § « Normes et antériorités ».

Contexte#

« Qui est dans ce salon ? » est la base d’un chat, d’un salon de jeu, d’un tableau partagé ou d’un poste de supervision. Le framework n’y répond que pour le processus courant : les membres d’un canal sont ceux de CE pod (src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.channelMembers), et une connexion n’existe que dans la mémoire du processus qui l’a acceptée (src/packages/@nodefony/realtime/nodefony/interfaces/IRealtimeConnection.ts#IRealtimeConnection). Dès que l’application tourne en plusieurs exemplaires (pods, nodefony cluster -w N), chacun ne voit que ses propres connexions.

Bien faire demande trois mécanismes que chaque application réécrirait :

  1. un pod qui meurt n’annonce pas ses départs — il faut republier à intervalle fixe, et oublier un pod muet ;
  2. le bus livre au plus une fois — ces mêmes republications réparent un départ perdu et rattrapent un pod qui démarre en retard ;
  3. une personne a plusieurs onglets, parfois sur deux pods — la présence se compte par identité, les anonymes se comptent sans être nommés.

Le cookbook du module l’avait lui-même réécrite fausse avant cette décision (src/packages/@nodefony/realtime/docs/cookbook-chat.md, § « Étape 3 » : un Set par processus publié toutes les 5 s, que chaque pod écrasait chez l’autre derrière un bus).

Décisions#

P1 — Le framework porte la présence, sur le canal lui-même#

Décision (2026-11-10) : la présence est une brique du framework, activée canal par canal. Elle voyage sur le canal qu’elle décrit : être admis dans room:42 donne sa présence, aucun second canal (room:42:presence) n’est à ouvrir.

Comment P2 à P5 ont été tranchés#

Ces décisions ont été instruites par une revue contradictoire, avec la performance du temps réel pour premier critère. Elle a ajouté S-rt-100 à S-rt-104 et fait réécrire quatre cas ; chaque constat retenu ci-dessous a été vérifié au code. La règle qui a départagé : au repos, le coût est proportionnel au nombre de pods ; en rafale, au nombre de fenêtres — jamais au nombre de canaux, de membres ou d’abonnés.

P2 — Entre pods : un canal de plateforme dédié, des changements groupés, une preuve de vie de quelques octets#

Décision (2026-11-10, après revue contradictoire) :

P2 bis — Vers le navigateur : liste partagée, changements regroupés, version#

Décision (2026-11-10, après revue contradictoire) :

P3 — Activation et API : une clé de la politique du canal#

Décision (2026-11-10, après revue contradictoire) :

@RealtimeChannel("room:*", { allow: RoomAdmission, presence: true })

P4 — L’état d’un présent : la forme en 10.0, l’écriture ensuite#

Décision (2026-11-10, après revue contradictoire) :

P5 — Les départs : exacts par défaut, grâce sur option#

Décision (2026-11-10, après revue contradictoire) :

Ce qu’on ne promet pas#

Budgets — critères de fin#

Deux natures, deux preuves. Les invariants sont des tests à horloge simulée (un compte exact, pas une mesure) ; les mesures passent au banc (.claude/skills/nodefony-load-test/scripts/micro/micro-presence.mjs : hub seul, bus en mémoire avec le vrai sceau, un processus par mesure, variantes alternées, médiane ; octets et mémoire refusés au-delà de 3 % de dispersion, temps indicatifs — un A/B ne conclut que sur des séries séparées : la variance entre processus d’une opération de ~100 ns est propre au moteur, 5 à 40 %, bimodale), plus le gate mémoire de @nodefony/http.

Grandeur Budget Preuve
Trames de présence par client et par canal ≤ 5/s, front montant compris, hors resynchronisation invariant
Bus au repos, 1 000 contre 100 000 canaux octets égaux (indépendants du nombre de canaux) invariant
Bus au repos, canal sans présence 0 message, aucun minuteur, aucune structure invariant
Encodages de liste complète, 250 abonnés en 2 s ≤ 1 par fenêtre et par codec (compteur lisible) invariant
Premier abonné d’un pod (S-rt-99) liste complète en ≤ 2 fenêtres de 50 ms après la demande ; latence réelle au banc multi-pods invariant
Récepteur gelé 20 s ; bus revenu après une coupure plus longue que le délai d’oubli aucun pair vivant oublié invariant
Deux pods d’intervalles différents (déploiement progressif) aucun oubli d’un pod vivant invariant
250 abonnés successifs d’un canal 0 trou de version chez les abonnés déjà présents invariant
Réponse d’état en n parts, une part perdue vue inchangée, trou maintenu puis redemandé invariant
Demande ciblée à un pod sans présent sur le canal 1 réponse vide invariant
Liste complète jetée par la contre-pression, puis subscribe répété liste reçue invariant
Arrêt propre d’un pod présents retirés chez les pairs en ≤ 1 fenêtre, sans attendre le délai d’oubli invariant
Preuve de vie ≤ 280 o par message au pire (originId de 48 caractères, compteurs à leur maximum, secret posé) ; mesuré 249 o, 262 o la finale mesure
Octets de présence par client (S-rt-87 : 1 000 membres, 30 mouvements/s, identifiant de 36 caractères) ≤ 2 Ko/s, compte seul au-delà du seuil ; mesuré 1 788 o/s mesure
Salon qui oscille autour du seuil (999 ↔ 1 000, S-rt-87) aucune liste nommée pendant l’oscillation (hystérésis, P2 bis) invariant
Mémoire par présent distant (tas après GC forcé, 100 000 présents ; état de 128 o) ≤ 160 o sans état, ≤ 320 o avec ; mesuré 75 o sans état (« avec » : aucun état ne se pose en 10.0, P4) mesure

Les budgets de cette table étaient des estimations ; le micro-banc les a mesurés. Celui de la preuve de vie (200 o) ne pouvait pas tenir : enveloppe scellée, nom du canal et charge font 249 o avec un originId de 48 caractères. Il est corrigé à 280 o au pire plutôt que d’abréger les champs : ce que le budget garantit — un bus au repos minime (~50 o/s par pod) et indépendant du nombre de canaux — tient, et abréger aurait gagné 25 o pour un format illisible au débogage, juste avant d’être figé.

Scénarios jugés#

S-rt-84 à S-rt-110 (scenarios/temps-reel.md). Plateformes : sans objet — ni chemin, ni processus enfant ; un minuteur unref se comporte à l’identique sur les trois systèmes.

Normes et antériorités#

Notre protocole n’est interopérable ni avec XMPP ni avec SIP : un écart de FORMAT n’est pas une faute. Ce qui compte, ce sont les problèmes que ces normes ont appris à résoudre. Les paragraphes cités renvoient aux textes publiés des RFC (IETF), de XEP-0045 (XSF) et de la spécification Matrix.

Source Ce que la présence reprend Où elle s’écarte, et pourquoi
XEP-0045 (XMPP, salons) — le cas le plus proche : la présence d’un SALON Être dans le salon donne la présence (§5.1.1) ; liste complète à l’entrée (§7.2.2) ; une seconde demande d’entrée = resynchronisation complète (§17.3) ; plusieurs sessions d’une identité (§7.2.8) ; ce qui fait autorité vient du service (§17.3) ; salon semi-anonyme (§4.2) → seuil 0 ; codes de départ 307 / 332 / 333 → motif futur Une trame members atomique au lieu de N présences et d’une auto-présence finale ; pas de pseudo libre (§14.6, usurpation) ; aucune option « identités visibles aux seuls modérateurs » en 10.0
RFC 6121 (XMPP, présence) Le serveur fabrique le départ d’un présent mort (§4.5.2) ; la presence probe (§4.3) = demande d’état ; réponse déterministe (§4.3.2) ; la présence porte la disponibilité, le reste passe ailleurs (§4.4.1) Battement systématique au lieu d’un sondage facultatif (§4.3.1, MAY) : notre bus ne garantit rien ; vocabulaire show fermé non repris
RFC 2778 / 4479 (modèle) Observateur et présent, fetch (RFC 2778 §2.1) ; personne → services / appareils (RFC 4479 §3) = identité → onglets Observateur non listé : côté serveur seulement
RFC 3863 / 5262 / 5263 (PIDF, présence partielle) Liste complète ou changements dans le même canal (RFC 5262 §1) ; liste quand les changements pèsent plus (§4) ; trois issues d’un numéro (RFC 5263 §4.5) = applied / gap / stale ; identifiant de chaque entrée (RFC 3863 §4.1.2) → référence d’onglet Version par CANAL et non par abonnement (une trame encodée pour tous) : la liste ne consomme donc pas de numéro
RFC 6665 / 3856 (notification SIP) État initial à l’abonnement (§4.2.1.2) ; un changement ignoré mais son numéro retenu (§5.3.2) ; durée annoncée qui fait foi (§3.1.1) → interval ; débit maximal des notifications (§5.4.10) → 250 ms ; état neutre avant la première notification (§4.1.2.4) → ready ; agrégation par le serveur, jamais par l’abonné (RFC 3856 §6.9) Pas d’acquittement par notification : prev / last révèlent la perte que l’acquittement révélait
SWIM / Lifeguard (détection de panne) Battement à compteur ; le récepteur lent est la première cause de faux positifs (Lifeguard) → réarmement des délais Tous les pods se battent le cœur (charge quadratique, négligeable à quelques dizaines de pods, à rejuger au-delà de quelques centaines) ; « incarnation » au sens d’une vie, pas du compteur de réfutation
État de l’art des suivis de présence répartis (implémentations étudiées) Incarnation tirée de l’horloge ; délai d’oubli ≥ 2 intervalles, refusé au démarrage ; lots ; liste complète puis différences = members / changes ; plusieurs entrées par clé, chacune identifiée ; état « en attente de synchro » ; gigue du premier battement ; grâce au départ, liste poussée à l’abonnement, compte seul pour les grands ensembles Pas de CRDT (chaque pod est seul auteur de ses présents : une chaîne seq suffit) ; vue des seuls canaux servis (S-rt-100) ; un seul palier d’oubli ; lots à 50 ms plutôt qu’à l’échelle de la seconde ; départs annoncés à l’arrêt et grâce à 0 par défaut (P5)
Spécification Matrix (présence) Durées relatives, jamais d’heure absolue entre serveurs Aucune fédération : la présence ne sort pas du cluster

Vocabulaire : on garde les noms de l’ADR. Équivalences à citer dans la documentation — présent = occupant (XEP-0045) ; demande d’état = fetch / probe ; members / changes = full / partial presence (RFC 5262) ; stale est le mot de RFC 3856 §9.4 ; preuve de vie = heartbeat.

Passerelle XMPP ou SIP : possible, et à garder possible. Le modèle étant celui des normes, une passerelle se traduit concept par concept : abonnement = entrée dans un salon / SUBSCRIBE ; members / changes + version = liste des occupants puis présences / NOTIFY complet puis partiel ; demande d’état = probe / fetch ; identité → { tabs } = sessions d’un occupant / personne → appareils. Elle vivrait dans un module à part, consommateur de la présence comme toute application ; le cœur ne parle aucun de ces protocoles. Ce qui lui manque, tout ADDITIF : un abonnement serveur aux CHANGEMENTS de présence (hub.presence() ne fait que lire), le motif d’un départ (codes 307 / 332 / 333), l’état (P4). Les présents unnamed n’y apparaîtraient pas un par un — XMPP exige un pseudo par occupant : voulu, ils ne sont jamais nommés. Toute évolution qui rendrait l’une de ces traductions impossible se juge contre ce paragraphe.

Alternatives écartées#

Conséquences#