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

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, with Uint8Array bytes 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).

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).

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é :

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.

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
}

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.

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 }

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>

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.

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) }) };
  }
}

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 :

// 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.

6. Les canaux privés#

Décision (acceptée le 2026-10-29) :

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).

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.

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.

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.

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.

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#

Conséquences#

Références#