Socket temps réel — un canal, une enveloppe, un contrat pour les deux bouts
accepted
Summary. Nodefony’s real-time socket serves chats, dashboards, games, sensors and agents through one JSON-RPC 2.0 peer shared by browser and server, and its protocol had to be settled before the 10.0 wire format froze. This ADR fixes what could not change later: the unit is the channel (a named stream with a shared producer), there is a single JSON-RPC 2.0 envelope, and codecs are only its serialization, negotiated once per connection — JSON text (
nodefony.jsonrpc.v1) by default, binary CBOR (RFC 8949,nodefony.jsonrpc.cbor.v1) as an opt-in, announced in the welcome frame. Whatever the codec, an application receives what JSON would deliver, withUint8Arraybytes kept intact, so a JSON client and a CBOR client on the same channel see the same data. One type-only contract, declared once, types both ends, and private channels, backpressure and resume are specified so that later additions stay non-breaking.
Le comment — grammaire des trames, négociation du codec, reconnexion — se lit dans le guide Protocole de la socket et, pour le binaire, dans Codec CBOR ; cet ADR porte le pourquoi.
Statut#
Accepté le 2026-10-29. Les §1 à §5 ont été validés décision par décision ; les §6 à §10, tous
« rupture si différé : NON », sont acceptés en bloc, après une revue d’architecture qui a jugé les
trois ADR du temps réel sans les contester (catalogue scenarios/temps-reel.md). Ce qui viendrait
les contredire s’ajoute en 10.x, sans rupture.
Les mentions « ouvert », « reste », « à prouver » décrivent l’état à la date de la décision ; le code livré en 10.0 les a soldées (voir les guides).
- Amendé le 2026-10-30 par la revue du gel : le même moule type socket, SSE et webhook (§4), et
la décision 1 du §6 est tranchée sur la forme d’
allowet son délai. - Précisé le 2026-11-09 (§6, décision 1 quater) : une politique de lecture et une politique d’écriture par nom de canal.
- Précisé le 2026-11-11 par ADR-0026 (D12) : le codec protobuf de la socket n’arrive pas avec le chantier gRPC (§2, lignes datées).
- Précisé par ADR-0025 (P1) : la présence d’un canal, d’abord laissée à l’application (§6), est portée par le framework.
Ce document porte sur la socket. Le socle commun aux livraisons est
ADR-0021, dont les décisions S1 à S9 font foi ici ;
les webhooks sont ADR-0023. Les huit décisions de gel
du protocole sont déjà prises (commit 1df6614c1) : reprises, jamais rediscutées. Le média
(capture, codec audio) relève d’un ADR à part : rien ici ne le recouvre.
Contexte#
La socket de Nodefony est un pair JSON-RPC 2.0 partagé entre navigateur et serveur
(src/nodefony/src/realtime/JsonRpcPeer.ts#JsonRpcPeer), des canaux servis par un hub
(src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub) et un client
dans le cœur (src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket). Elle sert une
discussion, un tableau de bord, un jeu, un éditeur partagé, des capteurs, des notifications, un
flux de média, et des agents — sans être taillée pour aucun. Chaque décision ci-dessous porte
trois usages hétérogènes, dont un sans agent ni IA et un sans média (règle des trois usages, ADR-0021).
Cinq évolutions touchent son protocole dans le même jalon : binaire routé, admission par identité, abonnés identifiables, transcription, voix. Après 10.0, un changement de ce qu’une application reçoit est une rupture même à types identiques (politique de compatibilité). Ce document décide ce qui fermerait une porte s’il était décidé plus tard, et laisse additif tout le reste.
Constaté au code (lecture seule, aucun test lancé) : octets en Uint8Array des deux côtés
(src/nodefony/src/realtime/IRealtimeTransport.ts#RealtimeFrameData), request hors du contrat
commun (src/nodefony/src/realtime/IRealtimeSocket.ts#IRealtimeSocket), code partagé compilé sans
Node ni DOM (src/nodefony/tsconfig.shared.json). Aucun sous-protocole annoncé
(src/nodefony/src/client/realtime/BrowserWsTransport.ts#BrowserWsTransport.connect), aucun
codec branché sur le pair, aucune notification realtime:closed, aucun curseur d’abonnement.
Décision#
1. Le canal, pas la room#
Décision (validée le 2026-10-28) : l’unité de la socket est le canal : un flux nommé dont le producteur
est partagé, démarré au premier abonné et libéré au dernier
(src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.subscribe).
Une room — une liste de diffusion tenue par le serveur, qui ne sait rien de ce qui produit —
s’obtient en ajoutant au canal une admission par identité (un prédicat) et un abonnement
décidé par le serveur. L’inverse ne se construit pas : une liste de diffusion n’a pas de
producteur. L’événement reste (canal, charge) nue (S1), sans identifiant du socle (S2), sans
propriétaire (S7).
- Usages : un tableau de bord (un producteur, N lecteurs), une partie de jeu (producteur partagé et membres), un flux de capteur (un producteur, aucun membre).
- Écarté : la room comme primitive ; un producteur par connexion (un seul usage connu, quand la règle en demande trois).
- Rupture si différé après 10.0 : NON, parce que l’admission par identité et les abonnés identifiables n’ajoutent qu’un membre optionnel et des notifications neuves (décisions de gel 5 et 8).
2. L’enveloppe JSON-RPC 2.0 et ses codecs#
Décision (validée le 2026-10-29, en deux temps : le principe, puis le calendrier des codecs) : une seule enveloppe, JSON-RPC 2.0, et des codecs qui n’en sont que la
sérialisation, choisie une fois par connexion. Repris des décisions de gel : sans sous-protocole, le format est
celui d’aujourd’hui — JSON-RPC texte, nommé v1 — pour toute la série 10 (décision 1) ; le
codec effectif se lit dans realtime:welcome par un champ optionnel (absent = texte), jamais
dans l’écho du handshake, et le défaut d’écho de ws ne change pas en 10.x (décision 2). Ajouté :
-
IFrameCodecdans le code partagé :encode(frame): string | Uint8Array,decode(data: string | Uint8Array): unknown, unprotocol. Par frame il remplaceJSON.stringify/JSON.parse: aucun appel de plus ; le codec JSON est ces deux appels natifs. Un codec n’est éligible que s’il compile soustsconfig.shared.json— niBuffer, ni DOM — et borne longueur et profondeur d’une trame hostile (RFC 8949 §10). -
Trois noms versionnés :
nodefony.jsonrpc.v1,nodefony.jsonrpc.cbor.v1(RFC 8949),nodefony.jsonrpc.protobuf.v1. Le client les offre (RFC 6455 §1.9), le serveur lit la liste au handshake (src/packages/@nodefony/realtime/nodefony/interfaces/IRealtimeHandshake.ts#IRealtimeHandshake) et annonce son choix dans l’accueil. Une enveloppe qui change =v2ajouté,v1gardé. -
L’accueil est toujours une trame texte
v1, qui porte le codec choisi ; les frames suivantes l’emploient. Un serveur sans le branchement du codec n’émet pas ce champ, un client qui l’a reste donc en texte : le déploiement progressif tient malgré l’écho dews, qui renvoie le premier sous-protocole offert (constaté surws8.22, la version qu’installe@nodefony/http— le cœur ne l’a qu’en dépendance de développement). -
Protobuf : une enveloppe
.protofixe fournie par Nodefony (id,method,error,params: bytes,result: bytes) ; la charge est encodée par le message que le contrat déclare pour cette méthode ; sans schéma, la charge passe en CBOR dans lesbytes. Bibliothèque :@bufbuild/protobuf, la seule que le framework aurait si le chantier gRPC (ADR-0026) aboutit. Elle n’est aujourd’hui dans l’arbre que par le module de test et l’outillage de build (npm ls @bufbuild/protobuf) : aucun paquet publié ne l’installe, l’ajouter serait une dépendance neuve pour chaque application. -
Calendrier. Les trois noms sont réservés dès 10.0. Activation (revue du 2026-10-29, une fois le codec CBOR écrit au cœur — remplace « optionnel, chargé par la seule application qui l’active », dont le motif était d’éviter une dépendance npm, disparue) : CBOR s’active par la configuration seule, sans paquet à installer, et son code ne pèse que là où il est activé — rien dans le bundle d’une application qui ne l’active pas (
.size-budgets.json). Côté navigateur : l’optioncodecdeNodefonySocket, avecCBOR_FRAME_CODECimporté denodefony/cbor(seul sous-chemin qui le contient). Côté serveur : une clé de la configuration du module temps réel, posée par le lot serveur du binaire routé, qui charge le codec au démarrage. Le paquet de base (nodefony,nodefony/client) ne contient que le codec JSON. Les codecs vivent dans le pair PARTAGÉ (JsonRpcPeer, §4 ligne (i)). Le codec CBOR est écrit, au cœur (src/nodefony/src/realtime/codec/, sous-cheminnodefony/cbor, hors denodefonyet denodefony/client) ; son branchement —IFrameCodec, offre du sous-protocole par le client, choix annoncé dans l’accueil — revient au lot du binaire routé, visé pour la publication de 10.0 : le binaire temps réel est la capacité stratégique du framework (décision du 2026-10-30), et ce lot ne se reporte pas pour tenir le calendrier. Il passe après le contrat typé (§4), qui le type, et les travaux qui fermeraient une porte gardent la priorité d’ordre ; s’il glissait malgré tout, rien ne casse — un serveur sans branchement n’émet pas le champ de codec. Protobuf n’arrive qu’avec le chantier gRPC : un seul usage connu d’ici là (règle des trois usages), et une dépendance que gRPC rendra de toute façon nécessaire ; son enveloppe ci-dessus est une intention, pas un engagement. Précisé le 2026-11-11 par ADR-0026 (D12) : le chantier gRPC n’amène protobuf qu’en pair FACULTATIF de@nodefony/httpet@nodefony/framework, jamais au cœur ni dansnodefony/client. Le codec protobuf de la socket n’en découle donc pas : il attend un usage à lui. -
JSON est la référence de tous les codecs (remplace la règle « refus à l’encodage », décision du 2026-10-29, après le banc) : quel que soit le codec, on reçoit ce que
JSON.stringifypuisJSON.parserendraient — uneDatedevient sa chaîne ISO,NaNdevientnull,Map/Setdeviennent{}. Seule exception, les octets : unUint8Arrayreste unUint8Array(S8 ; base64 sous convention dans le codec JSON). Ainsi une connexion se rejoue en texte sans qu’une ligne métier bouge, et un client CBOR et un client JSON abonnés au même canal reçoivent la même chose — le relais entre exemplaires, en JSON (S6), l’imposait déjà.- Les autres conteneurs d’octets sont REFUSÉS : un tableau
typé autre que
Uint8Array, uneDataViewou unArrayBufferpartirait en{"0":…}ou en{}— contenu perdu sans un mot. Le codec CBOR et le codec JSON à octets lèvent à l’émission, avec un message qui nomme le geste (codec/binaryView.ts#unsupportedBinaryMessage, règle unique) ; côté serveur la trame n’est pas livrée et le pair le journalise une fois. Aucun format neuf : le profil reste « JSON + octets ». Le codec JSON par défaut, qui ne parcourt rien, reste tel queJSON.stringifyle rend — comme pour unUint8Array. Normes et antériorités : la RFC 8746 définit des étiquettes CBOR pour les tableaux typés (64 à 87) ; les transporter étendrait le profil gelé — amendement à écrire s’il est demandé, pas un correctif. - Le type le montre : le contrat type la valeur REÇUE par un
Jsonify<T>(à écrire, absent du dépôt) —debut: Dateà l’émission devientdebut: stringà la réception, visible dans l’éditeur, sans coût d’exécution. C’est la forme courante des bibliothèques d’appel typé de bout en bout : le type reçu est celui que JSON rend. - Chaque codec est aligné et le prouve : un test par codec rend, pour chaque valeur du banc
(
NaN,Infinity,undefineden tableau,Date,Map,Set,-0,bigint), exactement ce que rend JSON —bigintcompris, que JSON refuse. Protobuf suit sa correspondance JSON canonique. - Le développement prévient : une valeur que JSON transforme (
Date,NaN,Map…) donne un avertissement UNE fois par méthode ou canal — presque toujours un oubli. Rien en production. - Écarté : tout refuser (un parcours par message, et une rupture pour les applications qui
publient une
Dateaujourd’hui) ; tout transporter par un JSON enrichi (format maison que ni un client d’un autre langage ni le relais ne lisent). Précédent du modèle commun : les routeurs de messagerie qui traduisent entre clients JSON, CBOR et MessagePack.
- Les autres conteneurs d’octets sont REFUSÉS : un tableau
typé autre que
-
Les octets dans le codec JSON — activés, jamais payés par défaut. Décision (validée le 2026-10-31, après la mesure du §9) : la convention déclarée est
{"$bytes":"<base64url sans bourrage>"}(alphabet RFC 4648 §5, celui de la conversion CBOR → JSON de RFC 8949 §6.1), réanimée enUint8Arrayà la réception ; le marqueur doit être SEUL dans son objet, sinon l’objet reste applicatif. Émettre la convention exige de DÉTECTER les octets, donc un parcours de la charge : mesuré +27 % (charge minuscule) à +35 % (sonde de console) surnotify, +20 % surinbound(.claude/skills/nodefony-load-test/scripts/micro/micro-realtime-frame-ab.mjs, 2 × 15 runs, deux passages de même signe). Le parcours n’est donc armé que si l’application active un codec binaire côté serveur (l’activation qu’exige déjà le calendrier ci-dessus). Sans activation, le codec JSON reste les deux appels natifs — « aucun appel de plus » tient — et des octets imbriqués y arrivent déformés comme avant le binaire routé, l’application prévenue une fois. Code :src/nodefony/src/realtime/jsonFrameCodec.ts, gardé parsrc/nodefony/src/tests/jsonFrameCodec.test.ts.- Écarté : parcours toujours armé (chaque application paierait ~30 % par trame texte pour un
service que la plupart n’emploient pas) ; codec JSON sans convention (contredit la décision
du 2026-10-29 : le client texte rend un
Uint8Array). - Un marqueur FORGÉ est refusé à l’émission (validé le 2026-11-01). Un objet
applicatif qui a la forme exacte du marqueur (seule clé, valeur chaîne) sans venir d’octets —
carte texte envoyée par un client CBOR,
paramsrelayés tels quels par l’application — serait relu en octets par un abonné texte, ou ferait jeter la trame entière si sa chaîne n’est pas du base64url, pendant qu’un abonné CBOR recevrait l’objet. Le codec à convention lève donc sur cet objet, en nommant sa clé et sans recopier la valeur ; la diffusion mutualisée laisse UN abonné dire l’échec (src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#ChannelFrame.claimFailure), jamais une ligne de journal et un encodage par abonné. Coût sur le chemin normal : unincludessur le texte produit, motif$bytesSANS guillemets (avec, V8 bascule sur une recherche à table reconstruite à chaque appel) — mesuré +12 % à l’encodage d’une trame de 80 octets, +0,5 % à 11 Ko, et −19 % / −6 % au décodage, qui portait le motif à guillemets. Gardé parsrc/nodefony/src/tests/jsonFrameCodec.test.tsetsrc/packages/@nodefony/realtime/nodefony/tests/integration/realtimeCodec.e2e.test.ts.- Écarté : échapper l’objet sous une clé dédiée (
{"$escape": …}) — fidèle, mais un second marqueur sur un fil gelé, et incompatible avec le reviver deJSON.parse, qui travaille des feuilles vers la racine.
- Écarté : échapper l’objet sous une clé dédiée (
- Écarté : parcours toujours armé (chaque application paierait ~30 % par trame texte pour un
service que la plupart n’emploient pas) ; codec JSON sans convention (contredit la décision
du 2026-10-29 : le client texte rend un
-
Trois précisions de câblage (validées le 2026-11-01) :
- le champ de
realtime:welcomequi porte le codec retenu s’appellecodec, et sa valeur est exactementIFrameCodec.protocol(src/nodefony/src/realtime/frameCodecNegotiation.ts#adoptFrameCodec) ; absent, la connexion reste en texte ; - le serveur renvoie dans le handshake le sous-protocole qu’il a CHOISI (RFC 6455 §4.2.2 :
« the subprotocol the server is ready to use »), jamais le premier offert — défaut de
ws8.22 sanshandleProtocols(protocols.values().next().value), qui ferait dire àsocket.protocoldu navigateurnodefony.jsonrpc.cbor.v1sur une connexion restée en texte. Additif : le client lit toujours le codec dans l’accueil, jamais dans cet écho ; - sous codec binaire, toute trame binaire est une frame du codec : le flux brut
(
NodefonySocket.onBinary/sendBinary,RealtimeController.onRealtimeBinary) est refusé avec une notice et ne sert que les connexions texte. Des octets passent par les canaux, qui ont les portes B1 à B4 (§3).
- le champ de
-
Le client texte prend la convention sur ANNONCE du serveur (validé le 2026-11-01). Un serveur qui a activé un codec binaire émet
$bytessur ses connexions texte ; il le dit dansrealtime:welcomepar le champbytes(valeurIFrameCodec.bytesMarker,"$bytes"; la valeur nomme la convention, une autre serait ignorée par le client actuel), et le client passe alors au JSON à convention sans avoir rien importé (src/nodefony/src/realtime/frameCodecNegotiation.ts#adoptFrameCodec). Un codec texte choisi par l’application est gardé ; un marqueur inconnu laisse le JSON natif. Coût : le codec à convention et le base64url entrent dans le paquet client, mesuré +0,57 Ko gzip (esbuild minifié) ; aucun coût par trame tant que le serveur n’annonce rien.- Écarté : réanimer
$bytespar défaut au décodage — sur le fil d’un serveur sans codec, un objet applicatif{"$bytes": …}deviendrait des octets, ou ferait jeter la trame entière si sa chaîne n’est pas du base64url (preuve :src/nodefony/src/tests/jsonFrameCodec.test.ts, « réanimer par défaut altérerait le fil ») ; exporter le codec à convention et laisser la page l’importer — sûr, mais le serveur sait ce que la page devrait deviner.
- Écarté : réanimer
-
Débogage par décodage à l’observation, jamais en changeant le fil : le traceur WS (
src/packages/@nodefony/http/nodefony/src/context/websocket/wsLogContent.ts#formatWsLogContent), Studio et la barre de debug affichent une trame binaire décodée ; coût nul en production, où le traceur est fermé. Un interrupteur de développement forcenodefony.jsonrpc.v1pour lire le fil brut dans le navigateur — une exception, pas la voie normale, car passer en texte change les conditions (taille, contre-pression). -
Usages : une discussion (JSON, lisible), un document partagé (CBOR, octets sans base64), un jeu à état figé (protobuf, un schéma par message).
-
Écarté : MessagePack au socle (pas une norme IETF ; enfichable si un écosystème le réclame) ; BSON (stockage) ; un schéma obligatoire pour l’enveloppe ; un décodeur CBOR maison avant le banc. Le choix est sorti d’un banc contre
JSON.parsenatif (fait, ci-dessous) — et aucune bibliothèque ne l’a passé : le codec retenu est le NÔTRE (« Retenu » ci-dessous). Le banc a mesuré octets, µs par frame, poids dans.size-budgets.json— sur des critères écrits d’avance : objets ordinaires sans conversion par frame, aucunBuffer(le client est un navigateur), aucun module natif obligatoire (Windows), CBOR standard sans extension propriétaire (un pair d’un autre langage doit pouvoir lire), alignement sur la référence JSON. Candidats :cbor-x,cborg, et@levischuck/tiny-cboren référence seulement — installé par@nodefony/security(@simplewebauthn/server), mais il ne rend que desMap, jamais un objet ordinaire, ce qui coûterait une conversion par frame. Une richesse de types (Date,Set,bigint) n’est pas un critère : la référence JSON ci-dessus la ramène à ce que JSON rend. -
Banc fait (2026-10-29) — Node 26.13, macOS x64, médiane de 5 ; 14 types (entiers, flottants, booléens, textes ASCII/unicode/8 Ko, tableaux, imbrications, binaire de 64 o à 1 Mo) et 9 valeurs hors modèle. L’accélérateur C++
cbor-extractdecbor-x(vérifié actif) n’apporte rien, parfois moins (texte 8 Ko décodé 4,0 µs contre 2,6 µs). Sur un message ordinaire, JSON encode 2 à 4 fois plus vite que CBOR, qui gagne 30 à 45 % d’octets : CBOR ne devient jamais le défaut. Sur le binaire, CBOR décode une vue sans copie : 64 Ko en 1,2 µs contre 91 µs en JSON base64, 1 Mo en 1,2 µs contre 1,97 ms. Le banc a aussi révélé que le codec JSON transforme (NaN→null,Date→ chaîne,Map/Set→{}) quandcbor-xgarde tout : d’où la référence JSON ci-dessus. -
Retenu : un codec CBOR propre à Nodefony (décision du 2026-10-29), dans le code partagé
src/nodefony/src/realtime/codec/— isomorphe, sans dépendance, sanseval. Aucune bibliothèque ne tenait les deux exigences à la fois :cbor-x(la plus rapide) ne peut pas s’aligner sur JSON sans parcourir chaque message (aucun crochet sur les nombres ; une extension pourDatevaut pour tout le process), appellenew Function('')au chargement (violation sous notre CSP), et tire un module natif optionnel à script d’installation ;cborg(stricte, alignable par sestypeEncoders) encode 4 à 5 fois plus lentement et copie chaque chaîne d’octets (1 Mo décodé en 545 µs contre 1,6 µs).
Le prototype mesuré : encodeur qui suit l’algorithme de
JSON.stringify(ECMA-262SerializeJSONProperty), donc aligné par construction (13/13 valeurs piégées), au niveau decbor-xà l’encodage (50 objets : 51 µs contre 53 µs ;cborg225 µs) ; décodeur restreint au modèle (JSON + octets ; étiquettes refusées), 10/10 messages hostiles refusés proprement, binaire en vue sans copie, à 1,2-1,5 fois decbor-xsur les objets, 2 à 340 fois plus rapide quecborg. Exigences du codec livré : conformité RFC 8949 (sérialisation préférée §4.1, flottants au plus court, longueurs indéfinies acceptées au décodage, clés en double et UTF-8 invalide refusés, bornes §10), vecteurs des appendices A et F en tests, chaque garde vue rouge. Témoins du banc (micro-cbor-codec.mjs) :cbor-xetcborg, références de mesure, jamais des dépendances. Ces deux bibliothèques ne sont que des références de banc (micro-cbor-codec.mjs), jamais des dépendances. -
Rupture si différé après 10.0 : NON, parce que les décisions de gel 1 et 2 rendent tout codec additif. Ce qui serait une rupture, et qui est écrit : le nom
v1et la lecture du codec dans l’accueil — un format renommé ou un codec déduit de l’écho changerait le fil d’un client déjà déployé.
3. Le binaire, routé par canal, par les mêmes portes que le texte#
Décision (validée le 2026-10-29) : une trame binaire routée n’est pas une seconde grammaire : c’est une
notification JSON-RPC dont la charge est, ou contient, un Uint8Array (S8), et le codec dit
comment il la porte — chaîne d’octets native en CBOR (type majeur 2), bytes en protobuf, base64
sous une convention déclarée pour le codec JSON. Elle passe donc par les mêmes portes que le
texte, sans seconde implémentation : verrou de trame
(src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.runAuthorizer,
B1), politique de canal (#RealtimeHub.probeChannel, #RealtimeHub.subscribeClient, B2), audit
des refus (B3), sonde (#RealtimeHub.recordInbound, B4 — membres optionnels, décision de gel 8,
vocabulaire S9). Le crochet brut
src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.onRealtimeBinary
reste hors du verrou pour toute la série, identité par RequestContext (décision de gel 3) :
il sert un protocole binaire écrit par l’application, sans canal.
- Usages : un capteur qui pousse des mesures compactées, un document partagé qui diffuse ses deltas binaires, la voix.
- Écarté : une trame binaire à en-tête maison sous le codec texte — une seconde grammaire, donc un second verrou et une seconde sonde, qui divergent en silence.
- Constaté au code : contre-pression sortante et
maxPayloadcouvrent déjà le binaire (src/packages/@nodefony/realtime/nodefony/src/transport/WsConnectionTransport.ts#WsConnectionTransport.sendBinary,src/packages/@nodefony/http/nodefony/config/config.ts#websocketSchema) ; B1 à B4 sont contournés parce que le binaire va droit au crochet (#RealtimeController.receiveBinary). À prouver avec le binaire routé : chaque porte vue rouge en la débranchant ; unUint8Arrayintact par le pilote Redis, supposé corrompu (S8). - Rupture si différé après 10.0 : NON, parce que le chemin routé n’existe pas encore et que le crochet brut est gelé par la décision de gel 3.
4. L’isomorphisme — le transport l’est, le contrat doit l’être#
Décision (validée le 2026-10-29) : fermer les cinq trous d’isomorphisme relevés au cadrage, dont deux le sont déjà.
| Trou | État constaté | Geste |
|---|---|---|
| (i) binaire asymétrique | fermé (gel) : Uint8Array des deux côtés, vue sans copie |
binaire routé : routage et codecs dans le pair partagé, jamais dans RealtimeController ni NodefonySocket |
(ii) request promis sans être tenu |
fermé (gel) : hors d’IRealtimeSocket ; src/packages/@nodefony/realtime/nodefony/src/server/ServerRealtimeSocket.ts#ServerRealtimeSocket.request reste, @deprecated, retrait à la majeure suivante |
rien |
| (iii) réception serveur non typée | ouvert : src/packages/@nodefony/realtime/nodefony/interfaces/IRealtimeController.ts#RealtimeInboundHandler prend params: unknown ; RealtimeController<Emit, Actions> sans Listen |
contrat typé |
| (iv) actions non vérifiées | ouvert : #RealtimeController.realtimeActions rend Record<string, RpcActionHandler>, #RealtimeController.realtimeChannels rend string[], src/packages/@nodefony/realtime/nodefony/decorators/realtimeDecorators.ts#RealtimeAction prend un nom libre |
contrat typé, surface opt-in (décision de gel 6) |
| (v) inversion Emit/Listen à la main | ouvert : la convention vit en commentaire (src/nodefony/src/realtime/RealtimeEventMap.ts#EventsMap) |
contrat typé |
Forme du contrat unique. Contraintes : coût d’exécution nul (génériques effacés, JS bâti
identique) ; un générique ne s’ajoute qu’en fin et avec défaut (décision de gel 6) ;
NodefonySocket<Emit, Listen, Actions>, ServerRealtimeSocket<Emit, Listen, Actions> et
RealtimeController<Emit, Actions> gardent leur ordre. Les deux options, vues de l’application.
Option A — troisième générique Listen et types utilitaires. Chaque côté dérive ses trois
cartes d’un contrat par des types nommés qui portent la direction.
interface ChatContract extends IRealtimeContract {
// déclaré une fois, code partagé
serverToClient: { "chat:room": { from: string; text: string } };
clientToServer: { "chat:typing": { on: boolean } };
serverMethods: { "chat:send": { in: { text: string }; out: { id: string } } };
}
// navigateur
const socket = new NodefonySocket<
ClientEmit<ChatContract>,
ClientListen<ChatContract>,
ContractActions<ChatContract>
>({ url });
// serveur — `Listen` ajouté en 3ᵉ, défaut `DefaultEventsMap`
class ChatRt extends RealtimeController<
ServerEmit<ChatContract>,
ContractActions<ChatContract>,
ServerListen<ChatContract>
> {
@RealtimeAction("chat:send") send(p: { text: string }): { id: string } {
/* … */
}
}
Ferme (iii). Ne ferme (iv) que si le décorateur connaît le contrat, ce qu’un MethodDecorator
ne peut pas : il ne voit pas les génériques de la classe. Ne ferme pas (v) : la direction est
encore écrite par l’application, à chaque site, dans le bon ordre.
Option B — générique de contrat, par une fabrique. Le contrat est déclaré une fois ; une fabrique en dérive les deux classes et les décorateurs. La direction vit dans la fabrique.
const chat = defineRealtimeContract<ChatContract>(); // une allocation, au chargement
// navigateur
const socket = new chat.Socket({ url }); // NodefonySocket<ClientEmit, ClientListen, Actions>
socket.on("chat:room", (m) => m.text); // typé
// serveur
class ChatRt extends chat.Controller {
// RealtimeController<ServerEmit, Actions, ServerListen>
@chat.RealtimeAction("chat:send") // nom contraint, signature vérifiée
send(p: { text: string }): { id: string } {
/* … */
}
protected override realtimeInbound() {
// clés et params contraints par clientToServer
return {
"chat:typing": (p, reply) => {
/* p: { on: boolean } */
},
};
}
}
Deux autres formes d’un générique de contrat sont écartées : un quatrième générique positionnel (il obligerait à écrire les trois défauts devant lui) et une surcharge du premier générique par un type conditionnel (elle réécrit toutes les signatures publiées, et un contrat passé sans marque serait lu comme une carte de trois canaux).
Décision (validée le 2026-10-29) : le moule du contrat. Le framework livre un
moule générique, IRealtimeContract, et ne déclare aucun contrat métier : chaque application
écrit le sien (ChatContract ci-dessus n’est qu’un exemple d’application), une fois, dans un
fichier partagé par ses deux côtés. Le moule a quatre clés, toutes facultatives (un tableau de
bord ne déclare que serverToClient) :
interface IRealtimeContract {
serverToClient?: EventsMap; // événements poussés par le serveur
clientToServer?: EventsMap; // événements envoyés par le client
serverMethods?: ActionsMap; // méthodes du serveur : le client appelle, le serveur répond
clientMethods?: ActionsMap; // méthodes du client : le serveur appelle, le client répond
}
- Deux clés de méthodes, pas une. Les appels circulent dans les deux sens :
src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.request(le serveur répond) etsrc/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.requestClient(le client répond, par#NodefonySocket.register). Aujourd’hui le client range les deux sous le MÊME génériqueActions; une clé uniqueactionsaurait reconduit ce mélange. - « Méthode », pas « action ». Une méthode appartient à qui l’implémente — une seule lecture
possible, quand
serverActionsse lit « ce que le serveur demande » OU « ce qu’il offre ». C’est le vocabulaire déjà publié :src/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeWelcome(methods),#NodefonySocket.serverMethods, et la norme JSON-RPC 2.0 (method). Le mot « action » reste dans l’API publiée (@RealtimeAction,ActionsMap,realtimeActions()), non renommée : la doc pose « une action est une méthode JSON-RPC exposée par le serveur ». - « Client », pas « navigateur » :
NodefonySockettourne aussi dans un script ou un serveur. - Hors du contrat : ce que le framework possède déjà — l’identité et le welcome, le message entre serveurs (§2).
- À éprouver au code : les canaux à motif (
`user:${string}`) comme clés ; la lecture de#RemoveIndexSignaturedit qu’ils passent, aucun test ne le prouve encore. - Formes voisines constatées ailleurs : deux cartes d’événements nommées par direction (forme
courante des sockets typées), canaux à opérations
send/receive(AsyncAPI). Ce qui distingue ce moule : la direction est calculée d’une déclaration unique, jamais réécrite.
Décision (validée le 2026-10-30, revue du gel) : le MÊME moule type les trois
livraisons. serverToClient type aussi le flux SSE d’un canal et l’émission d’un webhook : une
application écrit un contrat, et ses trois livraisons le lisent. Aucune carte par livraison
(sse?, webhooks?) : elle réécrirait ce que S1 d’ADR-0021 pose déjà, un événement
(canal, charge) pour toutes.
- Webhook :
type= le canal. Aucun champ n’est ajouté au corps figé{ id, timestamp, type, data }(ADR-0023 W1, S-rt-22). - Flux SSE : un flux d’un contrat dit lequel il est — multiplexé (
event:= le canal, plusieurs canaux sur une connexion) ou un flux = un canal (event:absent). Les deux formes se lisent sur la même carte. - Flux hors contrat :
renderSse()sans paramètre de type reste valide et le reste toute la série. La porte MCP écrit du JSON-RPC brut endata:, sans canal (src/packages/@nodefony/ai/nodefony/mcp/gate.ts, S-rt-66) : ce n’est pas un canal, et rien ne l’oblige à le devenir. - Le type n’est pas une validation. La garde de canal (politique,
allow) s’applique aux trois livraisons ; un type ne protège rien à l’exécution. - Le code suit en 10.x par génériques à défaut
(
src/packages/@nodefony/framework/nodefony/src/Controller.ts#Controller.renderSse,src/packages/@nodefony/http/nodefony/src/context/http/SseStream.ts) : ajouter un générique AVEC défaut ne casse rien. Seule la forme se fige ici. - Usages : une mesure de capteur typée une fois, lue par la socket du tableau de bord, le flux SSE d’un écran et le webhook d’alerte vers le SI ; une commande typée une fois, poussée à l’écran et au SI ; une tâche d’agent typée une fois, suivie sur la socket et notifiée en webhook A2A.
- Rupture si différé : OUI pour la forme du moule : une carte par livraison ajoutée après 10.0 changerait le moule que les applications ont écrit. NON pour le reste : générique en fin, avec défaut.
Décision (validée le 2026-10-29) : un contrat fait de types, une porte par côté.
L’exemple de l’option B ci-dessous sort chat.Socket et chat.Controller d’un MÊME objet : le
fichier partagé importerait alors @nodefony/realtime, et le navigateur qui l’importe tirerait le
code serveur dans son paquet (budget de nodefony/client dépassé, ou build cassé sur un node:)
— défaut invisible à un test de types, révélé au premier build d’une application. Donc :
// shared/chat.ts — UNIQUEMENT des types : 0 octet compilé, aucun import de code possible
export interface ChatContract extends IRealtimeContract {
/* … */
}
// navigateur — porte du client (nodefony/client)
const socket = NodefonySocket.fromContract<ChatContract>({ url });
// serveur — porte du serveur (@nodefony/realtime)
const chat = defineRealtimeContract<ChatContract>(); // { Controller, RealtimeAction }
- Pourquoi une porte côté client :
NodefonySocketprend trois génériques (envoi, écoute, méthodes), l’application déclare UN contrat. Écrire la conversion à chaquenewrouvrirait l’inversion à la main ; réutiliser le premier générique est écarté ci-dessous. La porte est unnewtypé, sans allocation de plus. - Les noms (
fromContract,defineRealtimeContract) ne sont PAS décidés : ils se fixent au code, signatures sous les yeux. Un nom dit ce qu’on obtient ; « contrat » désigne la déclaration de l’application, pas une technique.
Décision (tranchée le 2026-10-29) : ce que j’envoie =
ce que j’ai déclaré, ce que je reçois = ce que JSON en fait. Jsonify<T> (§2) s’applique aux
QUATRE points de réception, des deux côtés ; le type déclaré, tel quel, à chaque point d’émission.
| Qui reçoit | Quoi | Type reçu |
|---|---|---|
le client, on(…) |
serverToClient |
Jsonify<T> |
| le serveur, entrée d’un canal | clientToServer |
Jsonify<T> |
| qui IMPLÉMENTE une méthode (serveur ou client) | ses in |
Jsonify<T> |
qui APPELLE une méthode (request, requestClient) |
son out |
Jsonify<T> |
- Exemple :
serverToClient: { meeting: { start: Date } }—socket.on("meeting", (m) => m.start.getTime())compile aujourd’hui et plante au navigateur ; avec la règle,m.starteststringet l’éditeur le souligne. Même mensonge, côté serveur, poursend(p: { start: Date }). - Exception (§2, S8) :
Uint8ArrayresteUint8Array. - Pourquoi les quatre d’un coup : ne poser
Jsonifyqu’auon()du client obligerait à l’ajouter après 10.0 aux trois autres — le type des paramètres d’une méthode décorée changerait, nouvelles erreurs de compilation chez les applications. La règle survit à tout codec futur : protobuf suit sa correspondance JSON canonique (§2). - Coût d’exécution nul (types effacés).
Jsonify<T>s’écrit danssrc/nodefony/src/realtime/RealtimeEventMap.ts, à côté de#ContractParams, avec un test de types par ligne du tableau, et une profondeur bornée (un type récursif sans borne ralentit le compilateur sur les charges profondes). - Le codec ne change pas le type reçu : déjà acquis par « JSON est la référence de tous les
codecs » (§2) — un client CBOR et un client JSON reçoivent le même
Jsonify<T>.
Décision (validée le 2026-10-29) : l’option B, bâtie sur les génériques de
l’option A, une porte par côté. Le chat.Socket de l’exemple de l’option B n’existe pas : la
décision « un contrat fait de types » le remplace par la porte du client, et la fabrique du
serveur ne rend que Controller et RealtimeAction. Listen s’ajoute en
troisième position de RealtimeController avec défaut (nécessaire aux deux options) ; les types
utilitaires existent déjà en partie (src/nodefony/src/realtime/RealtimeEventMap.ts#ContractParams,
#TypedRpcActionHandler) ; la fabrique est la surface opt-in que le gel réserve à la vérification
des actions, et la seule voie par laquelle un décorateur connaît les noms du contrat. Un
contrôleur non paramétré reste permissif sur les deux voies (cas « rétro-compat » de
src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeSharedContract.types.test.ts, à
garder vert tel quel). Le pair reste rangé sous son contrat effacé sur la connexion et relu par
src/nodefony/src/realtime/JsonRpcPeer.ts#JsonRpcPeer.requestAs : la fabrique ne le
re-paramètre pas.
- Usages : une discussion (deux sens), un jeu (entrées client typées), un tableau de bord
(canaux serveur seuls —
clientToServerpeut rester vide). - Rupture si différé après 10.0 : NON, parce que tout est générique en fin avec défaut, ou fabrique opt-in. (ii) était la rupture, et elle est faite.
- Reste au code : soldé par la décision suivante.
Décision (tranchée le 2026-10-31) :
deux portes à NOMS FIGÉS, sans fabrique. Elle remplace l’emballage « fabrique » des décisions
ci-dessus (defineRealtimeContract<C>() → { Controller, RealtimeAction }) ; le fond — un
contrat fait de types, une porte par côté, la direction CALCULÉE et jamais réécrite — ne bouge pas.
// shared/chat.ts — types seuls
export interface ChatContract extends IRealtimeContract {
/* … */
}
// navigateur — porte du client (nodefony/client)
const socket = NodefonySocket.fromContract<ChatContract>({ url });
// serveur — porte du serveur (@nodefony/realtime)
@RealtimePolicy({ "chat:send": { roles: ["ROLE_USER"] } })
class ChatRt extends ContractRealtimeController<ChatContract> {
protected realtimeActions() {
return { "chat:send": (p: { text: string }) => ({ id: store(p.text) }) };
}
}
- Pourquoi des noms figés. Un décorateur se reconnaît à son nom.
@chat.RealtimePolicyen donnait un par application (@chat.,@orders.…) : ungrepne le trouve plus, la doc ne peut plus montrer une forme unique, et un agent ne le recopie pas. - Le contrat s’écrit UNE fois côté serveur, sur
extends.src/packages/@nodefony/realtime/nodefony/src/server/ContractRealtimeController.ts#ContractRealtimeControllerporte une étiquette de TYPE (declare readonly [contractType]?: C, aucun octet émis) quesrc/packages/@nodefony/realtime/nodefony/decorators/realtimeDecorators.ts#RealtimePolicyLIT sur la classe décorée : un nom hors contrat ne compile pas, et l’erreur le nomme (notInContract). Sur un contrôleur sans contrat, le même décorateur accepte tout nom. - (iv) se ferme par
realtimeActions()abstraite et COMPLÈTE, typée parserverMethods. Un décorateur ne voit jamais la classe entière : c’est la seule construction qui fait d’une méthode OUBLIÉE une erreur de compilation (§10, garde-fou 2). Un contrat sansserverMethodsn’a rien à écrire :ContractRealtimeController<C>est un constructeur typé qui rend la forme STRICTE (ContractRealtimeControllerStrict, table abstraite) quandCdéclare des méthodes, et le SOCLE (ContractRealtimeControllerBase, table vide héritée) sinon — une sous-classe vide de plus à l’exécution, rien d’autre. Les entrées client (realtimeInbound()) restent facultatives canal par canal : accepter une entrée est une permission, pas une promesse. - La table sert SEULE les méthodes d’un contrat — règle de perf. Lui ajouter
@RealtimeActionpour porter une politique fabriquait, à chaque connexion, un handler aussitôt écrasé par la table (RealtimeController.ts#RealtimeController.onHandshakefusionne{ ...décorés, ...table }), ajoutait un appel par requête, et court-circuitait l’injection des paramètres décorés (@Body). La politique se pose donc sur la classe, par@RealtimePolicy, écrite une fois à la définition de la classe : rien par connexion. - Canaux à motif prouvés comme clés (
`user:${string}`), et admis comme motif de politique (user:*). - Côté client, les noms de canaux restent ouverts (canaux dynamiques, de plateforme) :
publish/onacceptent tout nom, la charge d’un nom déclaré est typée. L’inversion se garde sur les cartes que la porte dérive (ContractClientEmit≠ContractClientListen) et côté serveur. - SSE :
Controller.ts#Controller.renderSseprend la carte en générique EN FIN avec défaut (renderSse<ContractServerEmit<C>>()) ; flux multiplexé (send(data, { event })) ou un flux = un canal (carte d’un canal,send(data)). Sans paramètre, le flux reste libre (porte MCP). - Les trois limites du contrat, tranchées par une revue contradictoire (sur le chat de référence,
messages privés compris ; décisions tranchées le 2026-10-31, la page de référence validée le même
jour). Règle de méthode qui en sort : une API se juge à la LIGNE que le développeur écrit pour
le cas courant, la mécanique vient après.
- Diffusion (D2) : une seule forme, partout — contrôleur, service, tâche, boucle de jeu :
getRealtimeHub<C>().publish(canal, charge), par SURCHARGE : sans paramètre, le hub entier (RealtimeHub), libre comme avant ; avec,IContractRealtimeHub<C>— mêmes méthodes, seulpublishtypé. Même objet hub, aucune conversion, JS émis identique : une interface à signature de MÉTHODE queRealtimeHubsatisfait par bivariance — prouvé au compilateur ; la charge estEventPayload<…> & object, si bien qu’une charge scalaire, refusée à l’exécution parsrc/nodefony/src/realtime/payload.ts#isRealtimePayload, l’est désormais à la compilation. Écarté : unthis.broadcastpropre au contrôleur (deux formes pour un geste). - Fabriques (D7) :
ContractRealtimePublish<C>type lepublishreçu par@RealtimeChannelET par la surchargecreateRealtimeChannel— la fonction reçue reste la forme libre, que le type contractuel admet. - Nommage de la porte : trois mots, trois sens, sans
recouvrement.
Contract…<C>= la même chose que sa forme libre, lue à travers le contrat ENTIER (ContractRealtimeController,ContractRealtimePublish,IContractRealtimeHub,ContractRealtimeMethodHandlers, et au cœurContract{Server,Client}{Emit,Listen,Actions}).Typed…<…>= la version typée d’un type libre par ses types DIRECTS (charge, réponse, carte, clé :TypedRpcActionHandler,TypedRealtimeInboundHandler).…Of<X>= LECTURE du X porté par un nom ou une classe (RealtimeContractOf,ConfigOf). Les noms neufs du client (type rendu parfromContract, hooks) suivent la même règle. - Actions (D4) : le type d’une action du pont vient du SCHÉMA de sa route, seule source —
celle que le serveur valide (
src/packages/@nodefony/framework/nodefony/src/routeSchema.ts#IRouteSchema). Le contrat la RÉFÉRENCE par une clé additiveserverRoutes("POST /chat/send": { body: typeof SendBody; result: … }, import de type seul) ; un contrôle au démarrage refuse une entrée sans route montée de même méthode et même schéma. Les méthodes du client prennent le nom du verbe HTTP que la route déclare —get,post(et les autres verbes si le pont les sert) — et la clé d’idempotence se pose seule ;requestetmutatesont renommés avant 10.0 stable (pré-versions, semver 2.0 §9). Écarté : faire desenduneserverMethods— elle perdrait la re-validation d’identité à chaque appel,@Idempotentet la validation, que le pont porte (RealtimeController.ts#RealtimeController.invokeApiRequest) ; recopier la forme du corps dans le contrat (deux sources). Décision (validée le 2026-11-02) : une route à paramètre de chemin se déclare par son GABARIT — la clé est le chemin de la route,"GET /chat/messages/{id}"— et s’appelle en le nommant (chat.get("/chat/messages/{id}", { params: { id } })) ; la socket le remplit (src/nodefony/src/runtime/routePath.ts#fillRoutePath), chaque valeur encodée pour SON segment, et refuse une valeur manquante, vide,.ou..(la normalisation la résoudrait).params= entrée du schémaparamsde la route, sinon les{noms}du gabarit. Seuls des segments{nom}entiers se déclarent (routePath.ts#isSimpleRouteTemplate, refus au démarrage) ; une contrainte passe parrequirements. Une seule lecture de la forme simple au cœur (routePathParams, partagée avec le catalogue d’administration), confrontée au Router parsrc/packages/@nodefony/framework/nodefony/tests/unit/routePathParity.test.ts. Écarté : appeler par l’URL concrète typée par un motif ("GET /m/${string}") — une clé en motif échappe àContractRouteSchemas, et le contrôle au démarrage se taisait (constaté à la compilation). Corollaire : le pont route le chemin dans la forme que HTTP lui donne (parseRequestTarget,@nodefony/http), sinon/x/divergeait d’une porte à l’autre. - Lecture côté navigateur (D3) : les hooks React et Vue prennent la socket typée
(
useNodefonyChannelData(chat, "chat:presence", initial)) ; nom et charge déduits, plus de<T>écrit par le lecteur. Studio, premier consommateur, porte son contrat partagé et supprime son miroirHealthPayload. - Canal ou route — la règle enseignée : le canal porte les FLUX (diffusés, éphémères, attribués par l’identité de la connexion, §6) ; la route porte les GESTES qui changent un état (identité revérifiée, droits, validation, idempotence, réponse, appelable en HTTP).
- Page de référence du chat :
src/packages/@nodefony/realtime/docs/cookbook-chat.md.
- Diffusion (D2) : une seule forme, partout — contrôleur, service, tâche, boucle de jeu :
- Webhook : l’émission applicative n’existe pas encore (ADR-0023 W3, en 10.1). Elle se
typera par la même carte
ContractServerEmit<C>— exigence que portera l’émission applicative (ADR-0023 W3). - Preuves :
src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeSharedContract.types.test.ts(chaque@ts-expect-errorvu mordre), un consommateur compilé contre les tarballs, et le JS bâti deRealtimeControlleridentique avant/après (types effacés).
5. Contre-pression et bornes#
Décision (validée le 2026-10-29) : une règle, trois endroits. Sortante serveur :
src/packages/@nodefony/http/nodefony/src/context/websocket/wsBackpressure.ts#decideSend reste
l’unique arbitre — jeter au-delà du seuil, fermer 1013 sur un solde de refus — texte et binaire.
C1, sortante client : la même règle sur WebSocket.bufferedAmount du navigateur (voir
la décision C1 ci-dessous). C2, débit entrant par connexion : le patron du canal des
journaux (src/packages/@nodefony/realtime/nodefony/src/server/syslogUplink.ts#SyslogUplinkHandlerOptions
— fenêtre par connexion, compteur alloué paresseusement) généralisé au transport, dans
@nodefony/http à côté de maxPayload ; au-delà, trame écartée et comptée, puis fermeture
1008 sur un solde, calqué sur backpressureCloseAfterDrops. Les deux naissent désactivées
en 10.x (décision de gel 7).
Décision C1 (validée le 2026-10-29) : décider au cœur, agir de chaque côté.
#decideSend n’est PAS pure : elle tient ses compteurs sur la socket (_nfDrops,
_nfDropStreak, par un ws as unknown as IBackpressureSocket) et ferme elle-même en 1013. Or
un navigateur refuse ce code : WebSocket.close(code) n’admet que 1000 et 3000-4999, sinon
il lève InvalidAccessError (WHATWG WebSockets) — déplacée telle quelle, la fonction planterait
au moment de fermer. Donc :
- le code partagé (
src/nodefony/src/realtime/) ne porte que la décision pure : file d’envoi, seuil, politique et solde de refus en entrée →send/drop/closeet le solde suivant en sortie ; aucun effet de bord, aucune écriture sur la socket ; - chaque côté agit : le serveur garde ses compteurs et ferme en
1013, comportement inchangé ;NodefonySockettient son solde dans son propre état et ferme par un code privé neuf rangé danssrc/nodefony/src/realtime/closeCodes.ts, puis sa reconnexion prend le relais ; - le
as unknown asdisparaît avec la sortie des compteurs ; - désactivée côté client pendant toute la série 10 ; la règle reste UNE, puisqu’elle est écrite une fois.
// navigateur, 30 emit("move") par seconde, le réseau cale dans un tunnel :
// sans C1 → 300 coups périmés en file au bout de 10 s, partis en rafale à la sortie ;
// avec C1 → au-delà du seuil, les coups sont jetés et comptés, puis la socket se ferme
// et se reconnecte si le solde de refus ne redescend pas.
Décision C2 (validée le 2026-10-29) : compter les trames avant de les décoder.
Exemple : un capteur pousse 5 000 petites trames par seconde sur une connexion ; chacune passe
maxPayload, qui borne la TAILLE et pas le NOMBRE, et chacune est décodée, routée, autorisée.
-
On compte des trames, pas des octets — une addition ; les octets restent bornés par
maxPayload× trames. -
Le compte se fait à l’arrivée de la trame BRUTE, à côté de
maxPayload, avant tout codec : une trame jetée ne coûte niJSON.parseni décodage CBOR. -
Fenêtre et compteur par connexion, créés au premier usage ; borne à
0(désactivée) = un seul test, aucune lecture d’horloge, aucune allocation. -
Au-delà du seuil : trame écartée et comptée (compteur exposé par la sonde) ; fermeture
1008sur un solde de refus, jamais au premier dépassement — une reconnexion qui rejoue ses abonnements est une rafale légitime. -
Texte et binaire, même règle.
-
Désactivée pendant toute la série 10 (opt-in, config
@nodefony/http). Une activation par défaut est un changement de comportement, donc une majeure : elle ne peut venir qu’en 11.0, avec un seuil documenté qui laisse passer un flux audio de 50 trames/s avec marge. Aucun travail prévu d’ici là. -
Usages : un tableau de bord diffusé à N lecteurs dont un lent, un jeu sur réseau mobile qui pousse ses coups (C1), un capteur qui émet trop vite (C2).
-
Écarté : une copie de
decideSendcôté client gardée par un test de comparaison (la décision pure partagée suffit) ; un déplacement dedecideSendtelle quelle (effets de bord,1013refusé par le navigateur) ; une fermeture immédiate pour C2 (un pic passager n’est pas une attaque) ; un compte en octets pour C2 (maxPayloadles borne déjà). -
Rupture si différé après 10.0 : NON, parce que les bornes neuves naissent désactivées et que la décision partagée est interne. Activer un défaut est en revanche une rupture (un flux audio de 50 trames/s couperait) : réservé à 11.0, aucun travail prévu d’ici là.
6. Les canaux privés#
Décision (acceptée le 2026-10-29) :
-
Décision 1 (validée le 2026-10-29 ; (a) et (d) tranchés le 2026-10-30 par la revue du gel ; (b), ©, (e) à l’écriture du code) : admission demandée une fois, réponse retenue.
allow— flèche(channel, who: ISubscriberIdentity)ou classe@injectableimplémentantIChannelAdmission(ADR-0021 §S10 bis) ;whoest l’identité d’admission commune aux trois livraisons, une donnée plate et non le jeton (ADR-0021 §S10) —, membre optionnel desrc/nodefony/src/realtime/channelAdmission.ts#IChannelPolicy, évalué APRÈSauthenticated/roles/scopes.- Appelé une seule fois, au
subscribe: un salon privé ou une invitation par courriel vivent en base, et l’abonnement est un chemin rare — une requête y est normale. - La réponse est retenue sur la connexion (registre sink ↔ connexion des abonnés identifiables, alloué au
subscribe). Une trame entrante sur un canal àallowne rappelle JAMAISallow: elle exige que CETTE connexion y soit admise, en une lecture. Écrire sur un canal àallowsuppose donc de s’y être abonné — sans rupture,allowétant neuf. (Constaté : aujourd’hui la branche « inbound » desrc/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#buildFrameAuthorizerréévalue la politique à CHAQUE trame, sans exiger l’abonnement.) - L’accueil n’appelle pas
allow: il annonce sur la politique fixe — autant de requêtes que de canaux par connexion, sinon, et un motif ne s’énumère pas ;src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.probeChannelle pose déjà : le verrou protège, pas l’annonce. allowqui lève = refusforbidden, détail hors production. Un délai dépassé ou une saturation = motifunavailable, que le client réessaie (ADR-0021 §S10 bis point 3 ; tranché le 2026-10-30 par la revue du gel).- Prix assumé : une réponse retenue ne se périme pas seule — un membre retiré reste abonné
jusqu’à son éjection explicite (
realtime:closed { reason: "evicted" }). - Le nom :
allow(pasadmit, qui ne se devine pas). Une liste de membres est une façon d’écrireallow, pas une primitive (S7). - Tranché le 2026-10-30 par la revue du gel : (a) l’accès aux services — PAS de troisième
argument :
allowest une flèche(channel, who)OU une classe@injectablequi implémenteIChannelAdmission, résolue au démarrage du noyau (ADR-0021 §S10 bis point 1) ; (d) le délai — la clérealtime.allowTimeoutMs, son défaut fixé à l’écriture du code, et le motifunavailableau dépassement. Reste à l’écriture du code, sans rupture : (b) le miroir structurel deIChannelPolicydanssrc/packages/@nodefony/security/nodefony/src/realtime/realtimeContracts.ts— un test compare les deux formes ; © la gardeisChannelPolicydes décorateurs accepte une fonction ET une classe, distinguées par la métadonnée@injectable; (e) ce que montre une introspection des politiques (une fonction ne se sérialise pas ; une classe se montre par son nom).
- Appelé une seule fois, au
-
Décision 1 bis (validée le 2026-10-29) : autoriser une fois à l’entrée, pour TOUS les canaux. Une trame entrante sur un canal où CETTE connexion a déjà été acceptée ne refait aucun contrôle de politique : une lecture, « admise ? ». La décision 1 en est le cas particulier où l’entrée est le
subscribe.- Constaté :
src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.runAuthorizerappelle le verrou à CHAQUE trame, qui réévalue la politique entière (etgetRoles()des jetons recopie le tableau des rôles à chaque appel). Mesuré (.claude/skills/nodefony-load-test/scripts/micro/micro-frame-authorizer.mjs, médiane de 7, côté contrôleur, hors décodage réseau) : le verrou ajoute +24 % à la trame sur un canal libre et +35 % sur un canal à rôles ; un verdict retenu (prototype) ramène l’écart à +9 %. - Où : la mémoire vit dans realtime, au point d’appel du verrou (
#runAuthorizer) ;@nodefony/securityreste le seul juge et son contrat ne change pas. Elle est attachée à la connexion,nulljusqu’à sa première trame entrante, libérée à la fermeture. - Portée : les trames entrantes sur un canal déclaré (
@RealtimeInbound, nom exact ou motif). Les autres trames —subscribe, méthodes,api.request— passent par le verrou comme aujourd’hui : elles sont rares, rien à gagner. - Garde-fou 1 — seuls les noms connus se retiennent. Un nom sans gestionnaire n’entre
jamais en mémoire. Un motif (
room:*) admet une infinité de noms : la mémoire d’une connexion est bornée (plafond fixé au code) ; au-delà, la trame est contrôlée sans être retenue — le comportement d’aujourd’hui, jamais pire. Sans cette borne, un client qui écrit surroom:1…room:1000000remplit la mémoire du pod. - Garde-fou 2 — seul le « oui » se retient. Un refus est réévalué et audité à chaque trame, comme aujourd’hui ; c’est le décompte des trames de C2 (§5) qui borne un client qui insiste.
- Garde-fou 3 — un compteur de version des politiques. Toute (ré)inscription d’une politique au hub l’incrémente ; un verdict retenu porte la version de son calcul, et une version périmée le fait recalculer. Coût : une comparaison d’entiers.
- L’identité : un verdict retenu suppose une identité fixe pour la vie de la connexion.
C’est le cas aujourd’hui — un changement d’identité ferme la connexion
(
src/nodefony/src/realtime/closeCodes.ts#IDENTITY_REFRESH_CLOSE_CODE, 4005), et la mémoire meurt avec elle. À prouver au code : aucun chemin ne change le jeton d’une connexion ouverte sans la fermer. - Usage qui la motive : un flux à haute fréquence — les déplacements d’un jeu, 60 coups par seconde et par joueur — où l’autorisation se paie une fois par canal et par connexion, plus à chaque coup. Le reste du coût d’un tel flux tient au décodage (binaire routé, §3) et aux coups périmés (C1, §5), pas à l’autorisation.
- Rupture : NON. Politiques et identité étant fixes pour la vie d’une connexion, les verdicts sont identiques ; un test le prouve sur une matrice (canal libre, rôles, scopes, motif, refus, politique réinscrite).
- Critère de validation : un banc de bout en bout (vrai serveur, vrais clients WebSocket, flux de déplacements sur un canal à rôles), verrou par trame contre verdict retenu, en paires alternées.
- Constaté :
-
Décision 1 ter (validée le 2026-10-30) : tout se calcule à l’ouverture, jamais sur la route de la trame. Généralise la décision 1 bis : le verdict retenu n’est plus une optimisation, c’est la règle. Trois moments, et trois seulement :
- À l’ouverture (poignée de main), une fois — tout ce qui dépend de l’identité : identité
gelée, rôles DÉPLIÉS par la hiérarchie en un ensemble figé, scopes, émetteur. À la
reconnexion, les canaux reviennent par le rejeu des
subscribe(une trame de contrôle par canal,src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions) : chacun suit le moment 2 ; rien n’est admis à l’accueil, et le rejeu attend son tour au-delà du plafond d’appels d’allowen vol (ADR-0021 §S10 bis point 3). - À l’entrée sur un canal, une fois par canal et par connexion — le nom d’un canal n’arrive
qu’avec son
subscribe(trame de contrôle, rare) : politique complète puisallow(asynchrone), évalués HORS du verrou des trames, sans bloquer le pipeline de la connexion ; le verdict est posé sur la connexion. - Sur la trame de données, aucun calcul — un canal sans politique ne coûte rien, un canal à politique coûte une lecture (« cette connexion est-elle admise ? ») : ni boucle sur des règles, ni balayage de chaîne, ni copie de tableau, ni parcours de hiérarchie.
- Constaté, contraire à la règle (à corriger avec l’admission par identité) : toute trame dont
methodest une chaîne —ping,unsubscribe, une action — entre danssrc/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#authorizeChannel, qui boucle sur les règles système et balaye deux fois le nom (:health,:stats) ; sur un canal à rôles,satisfiesrecopie les rôles (src/packages/@nodefony/security/nodefony/src/realtime/UserRealtimeToken.ts#UserRealtimeToken.getRoles) et parcourt la hiérarchie à CHAQUE trame. Mesuré (décision 1 bis) : +24 % à +35 % par trame. - Verrou de procédure — le verrou des trames est la pièce la plus sensible du temps réel.
Toute modification de
src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#FrameAuthorizer, deframeAuthorizer.ts#buildFrameAuthorizer, deRealtimeHub.ts#RealtimeHub.runAuthorizerou du branchementbeforeDispatchexige, AVANT le commit : (1) une relecture du diff par le mainteneur ; (2) une campagne d’attaque sur le verrou, menace d’abord ; (3) le micro-bancmicro-frame-authorizer.mjsavant et après, médiane de 7 ; (4) le gate mémoire. Jamais d’awaitdans le verrou ;allowne s’y insère jamais. - Gardé par : un test prouve qu’une trame
pingne consulte ni les règles système ni le résolveur de politiques ; un test prouve qu’une trame sur un canal admis ne lit nigetRoles()ni la hiérarchie ; la matrice de la décision 1 bis rend les mêmes verdicts.
- À l’ouverture (poignée de main), une fois — tout ce qui dépend de l’identité : identité
gelée, rôles DÉPLIÉS par la hiérarchie en un ensemble figé, scopes, émetteur. À la
reconnexion, les canaux reviennent par le rejeu des
-
Décision 1 quater (validée le 2026-11-09) : une politique de LECTURE et une politique d’ÉCRITURE par nom — chacune s’applique telle qu’elle est déclarée.
- Constaté :
@RealtimeChannel(nom, p)et@RealtimeInbound(nom, q)écrivaient la même case du registre des politiques (une seule métadonnée par nom) ; la seconde déclaration effaçait la première sans un mot, selon l’ordre des méthodes. Une règle de sécurité déclarée pouvait donc ne s’appliquer nulle part, et « tout le monde lit, seuls les connectés écrivent » n’était pas exprimable. - La règle :
subscribeexige la LECTURE (@RealtimeChannel) ; une trame entrante — notification sur un canal plein-duplex ou requête d’action — exige la LECTURE et l’ÉCRITURE (@RealtimeInbound,@RealtimeAction). L’écriture n’est donc jamais moins stricte que la lecture : le motif « on ne pousse pas sur un canal protégé » tient toujours. - Héritage, indépendant de l’ordre des méthodes : une lecture absente hérite de l’écriture
explicite (une application qui ne garde que
@RealtimeInboundreste protégée en lecture) ; une action sans politique explicite hérite de ce que son nom EXACT déclare ; s’il ne déclare rien, le défaut FERMÉ (#DEFAULT_ACTION_POLICY) devient son écriture — un motif de lecture public (orders:*ouvert) s’y ajoute sans l’ouvrir.@RealtimePolicy({ nom: p })pose les deux sortes. Deux classes qui déclarent des sortes DIFFÉRENTES d’un même nom se complètent. - Plus d’écrasement silencieux : deux déclarations explicites non équivalentes d’une même
sorte, dans une même classe ou entre deux classes, refusent le démarrage en nommant le canal et
les classes. Une sous-classe qui redéclare son parent le surcharge.
allowreste une règle de lecture : posé sur une écriture distincte de la lecture, il refuse le démarrage. - Précédence — la lecture appartient, l’écriture descend (
channelPolicyResolution.ts#resolveDeclaredPolicies) : la LECTURE d’un nom appartient à la déclaration la plus spécifique qui déclare quelque chose sur lui (nom exact, puis motif au littéral le plus long) — déclarée, ou héritée de sa propre écriture ; l’ÉCRITURE vient de la plus spécifique qui déclare une écriture, motifs compris. L’écriture s’ajoute à la lecture, elle ne peut que durcir : une écriture de famille (mix:*réservée) n’est plus perdue sur un nom exact qui ne déclare que sa lecture (attaque A3 de la campagne red-team). La lecture, elle, ne descend pas : une commandetask:startdéclarée sous une familletask:*àallowne devient pas un canal à membres, et une écriture exacte ne voit pas sa lecture s’ouvrir par un motif plus général. Écarté : résoudre chaque sorte séparément — vu rouge sur trois cas d’usage documentés, et ouvrant une lecture au moment de la mise à jour. - Canal personnel : un nom
user:…garde sa politique intégrée (son canal seulement) tant qu’aucune déclaration ne VISEuser:(nom exact, ou motif dont le littéral commence paruser:) — un motif attrape-tout (*) ne la retire plus (attaque K1, antérieure à cette décision). - Coût : la vue fusionnée de chaque nom exact est recalculée à chaque inscription (à
froid) ; une trame sur un nom exact reste UNE lecture de
Map. Le plancher système balaye les conventions:health/:statsde:en:(frameAuthorizer.ts#reservedConventionAt) au lieu de chaque position : verrou seul −42 % sur un canal libre, −32 % sur un canal à rôles (micro-frame-authorizer.mjs, médiane de 15, code d’avant cette décision en référence). allown’admet plus d’office l’écriture : la première trame entrante d’un canal àallowexige l’abonnement puis passe le verrou (lecture et écriture), et son verdict est retenu comme celui de tout canal entrant (décision 1 bis). Sans quoi l’admission contournerait l’écriture.- Garde de version : aucun paquet ne lie
@nodefony/realtimeà@nodefony/security. Un juge qui ne sait pas juger l’écriture face à un hub qui en porte une distincte refuse le démarrage, plutôt que de laisser l’écriture ouverte. - Écarté — interdire le doublon sans séparer : la faille se fermait, mais la limite d’usage devenait officielle et obligeait à recoder à la main une règle de sécurité.
- Rupture : de comportement, pas de signature. Seul change le code qui déclare les DEUX
sortes, différentes — c’est-à-dire celui dont une règle n’était pas appliquée. L’écriture n’y
devient jamais plus permissive ; la lecture devient celle qui est écrite. Annoncée au changelog
(
Changed). - Gardé par :
src/packages/@nodefony/realtime/nodefony/tests/unit/channelPolicySplit.test.ts(vu rouge sur le code d’avant),…/tests/unit/channelPolicy.attack.test.ts(39 attaques de la red-team), et des mutations basculées une à une (chacune vue rouge).
- Constaté :
-
Abonnés identifiables : le registre d’un canal associe chaque sink à sa connexion, alloué au
subscribeseulement ; le fan-out reste une boucle sans allocation. API serveur : ce qui désigne une connexion (lister, abonner d’office, éjecter une connexion) est local au pod ; ce qui désigne un nom (fermer un canal, éjecter un utilisateur) traverse les pods (décision 4). Il porte aussi la marque « admise » de la décision 1 : abonner d’office la pose, éjecter et fermer la retirent. -
Décision 2 (validée le 2026-10-29) : abonnement imposé —
allowreste la seule source de vérité. Exemple : la recherche de partie place quatre joueurs dansroom:42.- La politique fixe passe par la même sonde que l’accueil
(
#RealtimeHub.probeChannel, synchrone) ; sur un canal àallow, l’abonnement imposé appelleallowensuite. L’API serveur est donc async — chemin rare, une requête par membre imposé, rien sur le chemin des trames. Refus deallow= pas d’abonnement, rendu à l’appelant (jamais un abonnement qui contourneallow). - Pourquoi pas de contournement : le client rejoue ses abonnements à chaque reconnexion
(
src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions), et ce rejeu passe parallow. Un membre imposé queallowne connaît pas serait éjecté à la première coupure réseau — un défaut qu’on ne voit qu’en production, sur mobile. Conséquence pour l’application : elle écrit l’appartenance là oùallowla lit. - Le client est notifié :
realtime:subscribed { channel, imposed: true }— champ optionnel ajouté àsrc/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeSubscribed, pas de notification neuve. Le marqueur est nécessaire : aujourd’hui#NodefonySocket.ingestSubscribedIGNORE un acquittement pour un canal qu’il ne suit pas (le cas d’ununsubscribecroisé avec l’acquittement), et doit continuer. Avecimposed, le client inscrit le canal dans ses abonnements (un consommateur) : il le rejoue donc à la reconnexion, et seson(channel, …)reçoivent les messages comme pour tout canal. Le client peut s’en désabonner : quitter reste son droit. - Sans
allow, rien ne change : la politique fixe décide seule, à l’imposition comme au rejeu. - Connexion fermée pendant l’
await allow: réponse jetée, aucune marque (même règle que lesubscribe). - Locale au pod en 10.x : on n’impose qu’à une connexion servie par ce pod ; l’ordre ne
traverse pas le backplane (S6). Un client ancien qui ignore
imposedreçoit les messages mais ne rejoue pas : dégradé, pas cassé — d’où l’ajout sans rupture. - Usages hétérogènes : la recherche de partie d’un jeu, l’appelé d’un appel, le flux d’une tâche d’agent auquel le serveur abonne le demandeur, l’attribution d’une conversation de support à un conseiller.
- La politique fixe passe par la même sonde que l’accueil
(
-
Décision 3 (validée le 2026-10-29) : fermeture — éjecter coupe, seul
allowexclut.realtime:closed { channel, reason }(S4), motif fermé —ended(le canal est terminé) ouevicted(cette connexion en est retirée) — déclarée à côté desrc/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeDenied. Le client retire l’abonnement et ne le rejoue pas ;RealtimeDeniedReasonne bouge pas (décision de gel 5).- Ne pas rejouer est une politesse du client, pas une protection : une page rechargée ou
un client hostile refait
subscribe. Sur un canal àallow, l’éjecté revient si l’application n’a pas retiré l’appartenance là oùallowla lit ; sur un canal sansallow, la politique fixe le laisse rentrer — éjecter n’y exclut personne. - D’où la règle, écrite dans le TSDoc de l’action « éjecter » et dans la page publique :
éjecter coupe la connexion du canal, seul
allowexclut. Exclure d’un canal sansallow, c’est lui en donner un. - Le pendant pour
endedest déjà écrit par ADR-0021 S4 : la fabrique d’un canal terminé rendnull, et qui refaitsubscribereçoitrealtime:denied { reason: "unknown" }. Seulallowexclut une personne ; seule la fabrique clôt un canal. - Éjecter retire la marque « admise » et le verdict retenu de la connexion pour ce canal
(décision 1 bis) ;
endedles retire de toutes les connexions du canal. - Contraintes relevées au code (revue du 2026-10-29) :
- Serveur : une connexion tient ses canaux dans
ctx.__nfRealtime.channels, etsrc/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.startChannelrépond « déjà suivi » sans rouvrir quand le nom y est. Éjecter en retirant le seul sink du hub laisserait l’entrée : lesubscribesuivant serait acquitté sans rien rouvrir — abonné fantôme, qui ne reçoit plus rien — et le plafond par connexion compterait un canal mort. L’éjection passe donc par le MÊME chemin que#RealtimeController.stopChannel(hub ET état de connexion), jamais un second. - Client :
src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.ingestDeniedgarde le canal refusé dans ses abonnements (il est rejoué à la reconnexion — utile quand l’identité change).realtime:closedfait l’inverse, et ne doit donc pas le recopier : retirer l’entrée quel que soit le nombre de consommateurs locaux (un hook et un magasin partagent un seul abonnement), rejeter les attentes d’acquittement, et émettre un événement local (comme__denied__) pour que l’écran cesse de se croire abonné. - Un composant qui se remonte rappelle
subscribe: c’est attendu, et c’estallowqui tranche — conforme à la règle ci-dessus.
- Serveur : une connexion tient ses canaux dans
- Écarté : une liste noire dans le framework — seconde source de vérité, locale au pod,
perdue au redémarrage, divergente de
allowen silence.
- Ne pas rejouer est une politesse du client, pas une protection : une page rechargée ou
un client hostile refait
-
Décision 4 (validée le 2026-10-29) : ce qui traverse le backplane — les publications, et des ordres qui ne font qu’ENLEVER.
- Publications :
{ channel, payload, originId }des seuls canaux déclarés diffusables (S6,#RealtimeHub.markBroadcastChannel). Un message venu du bus n’atteint que des abonnés déjà admis sur leur pod. Ni politiques, ni acquittements ne traversent ; les membres, seulement sur les canaux de présence (ADR-0025 P2), comptés par identité, jamais leurs connexions. - Ordres par NOM — traversent : fermer un canal (
ended) et éjecter un utilisateur par son identifiant. Sans eux, une fin de partie ou une modération décidée sur le pod B laisse ouverts les abonnés du pod A — un défaut qui marche en développement et une fois sur N en production. Chaque pod applique l’ordre à SES connexions, par le chemin unique de la décision 3. - Ordres par CONNEXION — restent locaux : abonner d’office, éjecter une connexion. Une
connexion n’existe que dans le pod qui l’a acceptée ; une connexion inconnue de ce pod rend
false, jamais un no-op muet. - Transport : un message ordinaire du backplane (
IBackplane.publish), sur un canal de contrôle INTERNE au hub, l’ordre danspayload— l’enveloppe ne gagne aucun champ (S6) etsrc/packages/@nodefony/realtime/nodefony/interfaces/IBackplane.ts#IBackplaneaucune méthode : tout driver, y compris écrit par un tiers (Kafka, NATS), le transporte sans le savoir. Ce canal ne passe PAS par#RealtimeHub.markBroadcastChannel, qui refuse à raison l’espace réservé (injection dans tous les pods) : il a sa branche dédiée à l’entrée, AVANT le contrôle par préfixe (#RealtimeHub.#admitFromBackplane), qui n’accepte qu’une liste fermée d’ordres de forme vérifiée (src/packages/@nodefony/realtime/nodefony/src/backplane/controlOrder.ts#readControlOrder, même garde à l’émission) ; tout autre contenu, et tout ordre visant un canal de la plateforme, est rejeté et compté (ingressRejectedTotal) — sauf un TYPE d’ordre inconnu de cette version, compté dansingressUnknownDiscardedTotal(ADR-0025). Son nom vient de la table du cœur (PLATFORM_BUS_CHANNELS.control) ; il n’est jamais diffusé aux abonnés locaux. Livré. - Pourquoi c’est sûr : un ordre ne fait qu’enlever — seul
allowfait entrer. Il est scellé comme toute publication : sur un bus partagé, le secret du bus (NF_REALTIME_BACKPLANE_SECRET) pose un HMAC sur origine, canal et charge (src/packages/@nodefony/realtime/nodefony/src/backplane/envelope.ts#sealBackplaneEnvelope, ADR-0021 S6) ; un ordre forgé sans le secret est rejeté. Sans secret, qui écrit sur le bus peut couper des abonnés, jamais en admettre. - Le rejeu change de portée — à écrire dans le TSDoc du sceau. Le sceau assume aujourd’hui
le rejeu hors portée, parce qu’un message rejoué ne fait que rediffuser une charge déjà
diffusée (
envelope.ts#SEAL_FIELD). Un ordre rejoué, lui, recoupe : un « fermerroom:42» capté puis republié plus tard couperait une partie rouverte. L’effet reste soustractif (jamais d’admission) ; un anti-rejeu par horloge reste écarté (horloges des pods non alignées, comme au sceau). La parade dépend de l’ordre (amendé le 2026-11-02, après revue contradictoire) :- Une fin vise un canal qui porte son identifiant d’instance (
room:42:<partie>, S4) : rejouée, elle ne désigne plus rien de vivant. - Une éjection vise
(canal, compte). Rejouée sur un canal DURABLE (chat:general), elle recoupe le compte à chaque réadmission : déni ciblé, sans le secret, qu’aucun compteur ne voit (S-rt-48). Risque accepté en 10.0, borné par trois faits : l’effet reste une coupure, jamais une admission ; il exige d’écrire sur le bus ; changer le secret rend caduques les ordres déjà captés. La page d’exploitation l’écrit : bus privé exigé. - La parade est réservée sans rupture. La forme vérifiée de l’ordre d’éjection accepte
dès 10.0 un champ optionnel
generation(entier ; absent = toutes les générations). Un exemplaire qui ne sait pas s’en servir l’ignore et éjecte toutes les générations — plus large, jamais moins. En 10.x, une génération d’appartenance lue parallowet augmentée à chaque réadmission l’alimentera : rejoué, l’ordre viserait une génération morte. Sans horloge et sans mémoire des ordres déjà vus. - Écartés : un identifiant d’admission frappé par le pod — les admissions sont locales, le
modérateur ne nommerait que l’onglet qu’il voit et les autres onglets du compte (S-rt-4)
resteraient servis ; la génération dès 10.0 — elle élargit le contrat d’
allow, publié avec 10.0 (ADR-0021 S10 bis), et ferait porter à chaque application un compteur que le cas courant n’emploie pas.
- Une fin vise un canal qui porte son identifiant d’instance (
- Ce que le contrat suffit à porter : « au plus une fois, ordre par émetteur, aucun entre
pairs » (ADR-0021 S5, et l’en-tête de
IBackplane.ts). Un ordre qui enlève le supporte : reçu deux fois = appliqué une fois ; perdu ou en retard = une coupure tardive ; venu d’un autre pair qu’une publication = au pire un message de trop à l’éjecté. Un pod démarré après l’ordre ne le connaît pas : pour une éjection, c’estallow, qui lit l’état partagé, qui le rattrape ; pour une fin (ended), c’est la fabrique du canal qui rendnullà un canal terminé (ADR-0021 S4) — la même règle que pour un client ancien qui rejoue. - Exigences d’un driver, à écrire dans le TSDoc de
IBackplane: chaque pod reçoit TOUT (un groupe de lecteurs par pod pour un journal partitionné — un groupe partagé répartirait les messages en silence) ; l’ordre par émetteur de S5 tenu (journal partitionné : une clé par émetteur,originId, jamais par canal) ; aucun rejeu au démarrage (lire à partir du dernier message) ; aucune attente de regroupement à l’émission ; un ordre de contrôle jamais jeté pour faire place aux publications (voie hors quota de la file d’envoi ; un ordre que le bus refuse se compte,controlLostTotal, et s’annonce) ; le sceau appliqué (sealBackplaneEnvelope, mutualisé pour les drivers tiers) ; sa dépendance npm vit dans le driver, jamais au cœur. - Suite de conformité exportée (
@nodefony/realtime/testing) : diffusion à tous les pairs, ordre par émetteur, pas de rejeu au démarrage, sceau vérifié (message non scellé ou mal scellé refusé quand un secret est posé), ordres de contrôle transportés, y compris sous une rafale qui sature la file d’envoi, espace réservé injecté refusé. Les drivers livrés qui ont des pairs (cluster, Redis) la passent —loopback, sans pair, n’a rien à y prouver ; un driver tiers s’y prouve. Une définition du contrat, pas une par driver. Livré :src/packages/@nodefony/realtime/nodefony/testing/backplaneConformance.ts#runBackplaneConformance, lanceur de tests passé par l’appelant ; le sceau exporté pour les drivers tiers (sealBackplaneEnvelope,openBackplaneEnvelopedans@nodefony/realtime). Vue rouge sur trois faux drivers (diffusion à un seul pair, rejeu au démarrage, secret ignoré) ; elle a trouvé un défaut du drivercluster: arrêté, il livrait encore à un handler reposé. - Preuve : fermeture et éjection par utilisateur à DEUX pods, bus de cluster ET Redis — le
banc Redis saute sans
NF_REDIS_TEST_URL, et la CI doit l’exercer (un saut compte vert).
- Publications :
-
Cas
transcript:<id>en multi-pod : l’audio arrive sur un pod, l’abonné au texte peut être ailleurs. Décision : préfixetranscript:déclaré diffusable et prédicatallowsur le motiftranscript:*— la charge traverse, l’admission se rejoue sur chaque pod. L’affinité de pod est une option de déploiement, pas une règle. La fermeture traverse les pods par l’ordre de contrôle de la décision 4. À prouver : un éjecté sur le pod A, abonné sur le pod B, n’est pas servi par B. -
Usages : une notification
user:42(sans média, sans agent), un salon fermé de jeu ou de collaboration, un appel. -
Écarté : un propriétaire dans l’événement (S7) ; une appartenance sur le bus (elle étendrait l’enveloppe, S6) ; une seconde voie d’application du prédicat dans realtime — sans
@nodefony/security, rien n’est refusé et un avertissement le dit (src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeUnenforcedPolicy.attack.test.ts). -
Rupture si différé après 10.0 : NON, parce que membre optionnel, notification neuve et API neuve sont additifs. Écrire maintenant « appartenance locale, ordres par nom diffusés » évite qu’une application s’appuie sur une portée cluster qu’on ne tient pas (S5).
Décision (validée le 2026-10-31, revue contradictoire) : livrer à une identité est une brique du framework (D1). Le développeur écrit son chat — contrat, actions, base, historique, salons ; le framework garantit qu’un message adressé à une personne n’atteint qu’elle, sur tous ses onglets et tous les pods. La présence d’un canal, d’abord laissée à l’application par cette décision, est portée par le framework depuis ADR-0025 (P1).
- Surface :
getRealtimeHub<C>().publishToUser(id, charge)côté serveur,socket.onUser(handler)côté navigateur — rien à déclarer. - Mécanique, écrite une fois : le canal
user:<id>(ADR-0021 §S10,idstable) ; une politique INTÉGRÉE — connexion authentifiée, admission par égalité de chaîne avec l’iddu demandeur, jamais par découpage ; une fabrique intégrée ; le préfixe déclaré diffusable par le framework. Le verrou passant avant la fabrique et l’admission ne lisant que l’identité du demandeur,user:999(inexistant) etuser:bob(pas le sien) reçoivent le MÊME refus : ni oracle d’existence, ni oracle de présence. - Jamais d’abonnement d’office : l’onglet s’abonne quand son écran écoute. Mesuré sur le hub
(10 000 canaux, trois passes) : 494 octets par onglet abonné, envoi ~60 ns (~185 ns nom
construit) — une application qui ne s’en sert pas paie zéro.
Script :
.claude/skills/nodefony-load-test/scripts/micro/micro-user-channel.mjs. - Usages qui la justifient (socle : ≥ 3 hétérogènes) : notifier l’utilisateur 42 (S-rt-31), trois onglets (S-rt-4), alerte machine à un opérateur, inventaire privé d’un joueur, message privé.
- Réservée aux COMPTES : un visiteur anonyme n’a pas d’identifiant qui survive à une reconnexion ;
le chat de support anonyme passe par un salon privé de l’application (
support:<id>+allow). - Écartés : l’assemblage à la main par chaque application (une dizaine de lignes, chaque oubli
silencieux) ; un canal par paire
dm:<a>:<b>(tri canonique, découpage d’un:, croissance en n²) ; un registre identité → connexions (notifyUser) — oracle de présence, annuaire, et hors canal il casse l’enveloppe figée (S6) ou devient un canal déguisé ; l’abonnement d’office. - Les canaux de l’APPLICATION restent opt-in (
@RealtimeBroadcast) : certains sont propres à un pod par nature (forage de Studio). L’oubli devient visible : compteurlocalOnlyTotalquand un bus est configuré, préfixes diffusés listés au démarrage (D5). - Elle s’appuie sur
RealtimeIdentity.id, l’identité d’admission.
Décision (validée le 2026-10-31) : le handler d’entrée reçoit l’identité.
@RealtimeInbound et realtimeInbound() reçoivent who (la même identité d’admission que
allow) en troisième argument, sans allocation par trame. Un flux attribué à haute fréquence —
frappe en cours, coups d’un joueur, mesures d’une sonde — passe ainsi par le canal, l’auteur pris
au serveur et non déclaré par le client. Limite écrite : identité figée au handshake, coupée au
tick de révocation ; un geste qui change un état passe par une route.
Précision (validée le 2026-11-14) : la frappe d’un salon PRIVÉ parmi plusieurs passe
par une route. Une entrée de canal est appelée par son nom EXACT (chat:typing), jamais par la
famille de salons (chat:room:*) : elle reçoit le salon visé en paramètre, et rien ne prouve que
l’émetteur y est admis — sans contrôle, n’importe quel connecté injecte « Untel écrit » dans un
salon privé. Le contrôle d’appartenance coûte alors autant dans l’entrée que dans une route, sans
les garanties de la route (identité revérifiée, schéma, @IsGranted). D’où la règle :
| Cas | Le signal de frappe passe par |
|---|---|
| un salon UNIQUE, ou un canal sans appartenance | une entrée de canal (@RealtimeInbound, auteur pris au serveur) |
| plusieurs salons dont certains PRIVÉS | une route appelée sur la socket (socket.post), qui vérifie l’admission |
C’est la forme du chat de la démo (ChatController.ts.tpl, route demo-chat-typing) et la règle
enseignée par le skill livré nodefony-add-realtime-channel (« Route ou entrée de canal ? »). Écarté
pour l’instant : exposer au gestionnaire d’entrée « cette connexion est-elle admise sur ce canal ? »
(la marque existe par connexion) — cela rendrait l’entrée par salon sûre et gratuite, mais aucun
besoin mesuré ne le justifie aujourd’hui ; un ajout additif reste possible.
7. La reprise côté socket#
Décision (acceptée le 2026-10-29) : aujourd’hui, la reconnexion rejoue chaque abonnement au welcome
(src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions), sans
curseur ; la fabrique est rejouée au premier abonné. Demain (10.2, S3) : subscribe { channel, since? }. Le curseur est par abonné alors que la fabrique est partagée et
appelée une fois : il l’atteint par un retour élargi — à côté du dispose d’aujourd’hui, un objet
{ dispose, resume?(since, reply) }, où reply ne pousse qu’à cette connexion. La fabrique
décide : la suite depuis le curseur, l’état courant, ou rien. Sans curseur, rien ne change.
- Constaté par lecture : un serveur 10.0 ignore un champ inconnu dans
paramsd’unsubscribe—src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#channelParamne lit quechannel,src/nodefony/src/jsonrpc/index.ts#classifyJsonRpcFramene juge pasparams,src/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#authorizeChannelne lit que le canal. C’est la condition de S3 ; elle se prouve par le contrôle de compatibilité entre versions (section 10). - À écrire dans
src/packages/@nodefony/realtime/docs/protocole.md, qui ne le dit pas : la reconnexion (rejeu auwelcome, acquittement, curseur) et la fin de flux (realtime:closed). - Conséquence de §6 décision 1 : le rejeu rappelle
allowpour chaque canal qui le déclare — un exemplaire qui redémarre provoque N clients × M canaux appels en rafale. Prix normal d’« une fois par abonnement », écrit dans le TSDoc d’allowavec sa parade (cache court côté application) ; prouvé par les tests de l’admission. - Usages : une discussion reprise au dernier message vu, une courbe au dernier point, des notifications manquées.
- Écarté : « l’instantané puis la suite » comme règle (un choix de protocole, S3) ; un curseur passé à la fabrique partagée par son premier appel (il ne servirait que le premier abonné).
- Rupture si différé après 10.0 : NON, parce que paramètre optionnel et retour élargi d’un rappel implémenté par l’application sont additifs.
8. La voix, au niveau transport seulement#
Décision (acceptée le 2026-10-29) : un flux binaire à sens unique va sur un canal binaire de la socket (section 3) : la transcription y suffit, la latence y compte moins. Une conversation dans les deux sens choisit entre WebSocket et WebRTC par la mesure, selon un critère nommé une fois ici : latence de bout en bout mesurée, comportement sur réseau mobile, annulation d’écho haut-parleur ouvert. Opus par WebCodecs sur la socket et les options Opus de WebRTC sont deux couches distinctes. Capture, contraintes micro, codec audio, découpage en trames et détection de parole appartiennent à l’ADR média.
- Usages d’un flux binaire à sens unique : une dictée, la télémétrie d’un capteur, la synchronisation d’un document.
- Écarté : décider WebRTC ou WebSocket ici, sans mesure.
- Rupture si différé après 10.0 : NON, parce que tout vit sous des sous-chemins neufs.
9. La règle d’admission perf d’une évolution#
Décision (acceptée le 2026-10-29) : rien n’entre sur le chemin d’une frame sans trois preuves, dans l’ordre :
(1) le JS bâti du chemin chaud comparé à la référence HEAD, bâtie hors de l’arbre par
git archive — jamais en copiant le dist courant ; (2) le banc A/B
.claude/skills/nodefony-load-test/scripts/micro/micro-realtime-frame-ab.mjs, chemins inbound,
notify, binary (et publish, à ajouter avant les abonnés identifiables), --runs 15, verdict sur deux passages
de même signe ; (3) le gate mémoire (cd src/packages/@nodefony/http && npm run test:memory,
ligne [retention] WS JSON-RPC peer round-trips, référence 0,29 Ko/itération).
Chiffres dans le commit si l’écart dépasse 5 %. Un générique effacé ne paie rien ; une vue sans
copie, une allocation à l’abonnement, un codec remplaçant JSON.parse se mesurent.
- Rupture si différé après 10.0 : NON — une méthode, pas une surface.
10. Les garde-fous — condition d’admission de toute évolution#
Décision (acceptée le 2026-10-29) : les cinq contrôles ci-dessous, chacun vu rouge une fois.
| # | Contrôle | État | Qui le lance |
|---|---|---|---|
| 1 | compilation neutre du code partagé (lib: ["ES2022"], types: []) |
livré : src/nodefony/tsconfig.shared.json, vu rouge sur Blob puis Buffer |
npm run typecheck du cœur |
| 2 | contrat vérifié dans les deux sens | livré : realtimeSharedContract.types.test.ts — action manquante, forme fausse, entrée mal lue, canal hors Emit, inversion, nom de politique hors contrat, SSE — chacune un @ts-expect-error vu mordre |
npm run typecheck du paquet (tsconfig.tests.json) |
| 3 | suite de conformité unique d’IRealtimeSocket, contre les deux implémentations |
livré : src/packages/@nodefony/realtime/nodefony/tests/helpers/socketConformance.ts#describeSocketConformance, jouée contre NodefonySocket (câble en boucle) et ServerRealtimeSocket ; vue rouge sur chacune |
npm test du paquet realtime |
| 4 | fixtures d’octets dorées : accueil, requête, réponse, erreur, notification, trame à octets, par codec — et l’enveloppe backplane, trois champs plus sceau (src/packages/@nodefony/realtime/nodefony/src/backplane/envelope.ts#sealBackplaneEnvelope) |
livré dans Node : src/nodefony/src/tests/frameGolden.test.ts (3 codecs) et src/packages/@nodefony/realtime/nodefony/tests/unit/backplaneEnvelopeGolden.test.ts, références sous fixtures/golden/, vues rouges sur une mutation symétrique ; dans un vrai navigateur : lot distinct. Un octet changé = rupture de fil déclarée, fixtures régénérées (-u) dans le même commit |
npm test du cœur et du paquet realtime ; navigateur : lot distinct |
| 5 | compatibilité entre versions : client de la dernière version publiée ↔ serveur courant, et l’inverse | livré : scripts/release/compat.mjs, banc src/packages/@nodefony/realtime/nodefony/tests/compat/crossVersion.compat.test.ts ; référence lue sur npm (scripts/release/release-core.mjs#referenceDeCompat) ; vu rouge dans les deux sens. Rupture face à une référence en pré-version : acceptée et annoncée (semver §9) ; face à une stable : bloque (scripts/release/release-core.mjs#verdictCompat). Le serveur garde v1 tant qu’il est annoncé |
npm run release:compat — job compat de release.yml, dont publier dépend |
Gardé aussi : src/packages/@nodefony/realtime/tsconfig.json compile le serveur sans
le DOM (lib: ["ESNext"], types: ["node"]) — un window y rougit au npm run typecheck du
paquet ; seul tsconfig.tests.json le réintroduit, ses tests important le client navigateur. Une
rupture de fil suit la politique de l’API : majeure, et une version de sous-protocole de plus.
- Rupture si différé après 10.0 : NON — mais sans le contrôle 5 une rupture de fil ne se verrait pas, et le contrôle 4 fixe les octets que la série 10 promet.
Normes#
| Norme | Ce qu’elle tranche ici |
|---|---|
| RFC 6455 §1.9, §4.2.2, §11.5 | le serveur choisit un sous-protocole parmi ceux offerts, ou aucun ; un nom se préfixe par un domaine, enregistrable à l’IANA — d’où nodefony.jsonrpc.*.v1 |
| RFC 6455 §4.1 | le client doit échouer si le serveur répond un sous-protocole non offert : l’écho de ws ne viole rien, et ne décide rien (section 2) |
| RFC 6455 §5.6, §7.4.1 | une trame binaire est « arbitrary binary data whose interpretation is solely up to the application layer » — le routage par canal est une décision applicative ; 1008 politique (C2), 1009 trop gros (maxPayload), 1013 réessayer (contre-pression) |
| JSON-RPC 2.0 §1, §4.1, §5.1 | « transport agnostic » : une enveloppe, trois codecs ; une notification est une requête sans id (le canal) ; codes réservés, plage serveur -32000 à -32099 (refus du verrou) |
| RFC 8949 §3.1, §8, §10 | type majeur 2 = octets sans base64 ; la notation diagnostique « is not meant to be parsed » — observation, jamais le fil ; longueurs et imbrication hostiles : borner avant d’allouer |
Contrôle de non-blocage — A2A#
Une liaison A2A personnalisée sur WebSocket peut-elle se bâtir sur la socket sans que la socket la connaisse ? Lu dans A2A 1.0.1 §5.8 et §12 (figé hors ligne).
| Ce que la liaison doit fournir | Par quoi, sans rien ajouter à la socket |
|---|---|
| une URI versionnée par rupture (§5.8) | le sous-protocole versionné ou l’URL de l’endpoint — choix du contrôleur consommateur |
| opérations, résultats, erreurs équivalents (§12.1, §12.4) | des actions JSON-RPC d’un RealtimeController ; erreurs = objets JSON-RPC |
| paramètres de service sans en-têtes (§12.3) | un champ de params, nommé par la liaison |
| flux, ordre, reconnexion, fin (§12.5) | canaux ; ordre S5 ; rejeu et curseur (section 7) ; realtime:closed (S4) |
| authentification (§12.6) | handshake, authentificateur, verrou de trame — déjà là |
Pas empêché. Seul écart, documentaire : docs/protocole.md doit écrire la reconnexion et la
fin de flux (section 7). Aucun vocabulaire d’A2A n’entre dans la socket.
Alternatives écartées#
- Une room comme primitive (1) : sans producteur, elle ne couvre pas le canal.
- MessagePack, BSON, un décodeur maison avant le banc (2).
- Un format binaire à en-tête maison (3) : une seconde grammaire, donc un second verrou.
- Un quatrième générique positionnel, ou un premier générique surchargé (4).
- Deux copies de
decideSend(5) : deux règles qui divergent en silence. - L’appartenance sur le bus (6) : elle étendrait l’enveloppe figée (S6).
- Le curseur passé à la fabrique partagée (7) : il ne servirait que le premier abonné.
Conséquences#
- Engagements de la série 10, au même titre que les décisions de gel : le nom
v1, la lecture du codec dans l’accueil, l’accueil toujours en texte, le crochet brut hors verrou, les bornes neuves désactivées, l’appartenance locale au pod, les ordres par nom (fermer, éjecter un utilisateur) diffusés par un message ordinaire du backplane, sans méthode neuve surIBackplane. - Le contrat typé livre la forme figée d’
IRealtimeContractau cœur (§4 : quatre clés,Jsonify<T>aux quatre points de réception, socket + SSE + webhook),Listenen troisième générique deRealtimeControlleravec défaut, les types utilitaires etdefineRealtimeContract; le lot du binaire routé BRANCHE le codec CBOR déjà écrit et publié (src/nodefony/src/realtime/codec/,nodefony/cbor) parIFrameCodec, les trois noms de sous-protocole et le routage par canal ; l’admission par identité et les abonnés identifiables, les canaux privés ; les garde-fous, les contrôles 2 à 5. - Preuves à apporter : B1 à B4 vus rouges en débranchant ; un
Uint8Arrayintact par le pilote Redis (S8) ; un champ inconnu danssubscribeignoré par un serveur publié (contrôle 5) ; un éjecté sur un pod non servi par un autre ; le codec CBOR maison branché sur le pair, octets intacts sans copie au décodage ; le poids du moteur protobuf dansnodefony/clientface à.size-budgets.json(avec le codec protobuf de la socket, le jour où il a un usage — §2 ; le chantier gRPC ne l’amène pas au client, ADR-0026 D12). - Reste à décider : un tsconfig neutre pour le serveur du paquet realtime (section 10).
docs/protocole.mdécrit la reconnexion et la fin de flux avant qu’un protocole tiers s’y appuie.
Références#
- ADR-0021 — le socle (S1 à S9) · ADR-0023 — les webhooks · ADR-0007 — le client isomorphe
- RFC 6455, The WebSocket Protocol — https://www.rfc-editor.org/rfc/rfc6455
- JSON-RPC 2.0 — https://www.jsonrpc.org/specification
- RFC 8949, CBOR — https://www.rfc-editor.org/rfc/rfc8949
- Protobuf, correspondance JSON canonique — https://protobuf.dev/programming-guides/json/
- A2A 1.0.1 — https://a2a-protocol.org/v1.0.0/specification (§5.8, §12)
- Politique de compatibilité
- Décisions de gel du protocole — commit
1df6614c1