@nodefony/devkit 10.0.0-beta.5 → 10.0.0-beta.7

package/skills/nodefony-add-grpc-service/scripts/call.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Appelle une méthode gRPC d'une application Nodefony, en protocole Connect
+ * (JSON sur HTTP) — la preuve qu'un service répond, sans `curl` ni guillemets.
+ *
+ * `curl -d '{"name":"Ada"}'` ne passe ni dans cmd.exe ni dans Windows PowerShell,
+ * et `grpcurl` n'est pas installé partout. Ce script n'emploie que `fetch` de
+ * Node : il marche à l'identique sur les trois plateformes, et il rend le CODE
+ * gRPC du refus (`unauthenticated`, `permission_denied`…), pas seulement un
+ * statut HTTP.
+ *
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-add-grpc-service/scripts/call.mjs greet.v1.GreetService/Greet --field name=Ada
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-add-grpc-service/scripts/call.mjs greet.v1.GreetService/Greet --file body.json
+ * `@option` --field - un champ du message, `nom=valeur` (répétable ; la valeur est une chaîne)
+ * `@option` --file - le message entier, lu dans un fichier JSON
+ * `@option` --header - un en-tête, `nom=valeur` (répétable), par exemple `authorization=Bearer …`
+ * `@option` --url - l'adresse de l'application (défaut http://127.0.0.1:5151)
+ * `@option` --json - la réponse brute, sérialisée, pour rechaîner
+ * `@requires` l'application démarrée
+ * `@output` le statut HTTP, puis le message reçu ou le code gRPC du refus
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** L'adresse d'une application de développement, sans TLS. */
+const DEFAULT_URL = "http://127.0.0.1:5151";
+
+/** Une méthode gRPC : `paquet.Service/Méthode`, sans barre de tête. */
+const METHOD_RE = /^[A-Za-z_][\w.]*\.[A-Za-z_]\w*\/[A-Za-z_]\w*$/u;
+
+const USAGE = `
+Appelle une méthode gRPC d'une application Nodefony, en Connect (JSON sur HTTP).
+
+  call.mjs <paquet.Service/Méthode> [--field nom=valeur]...   le message, champ par champ
+  call.mjs <paquet.Service/Méthode> --file message.json       le message, depuis un fichier
+  call.mjs ... --header authorization=Bearer <jeton>          un en-tête (répétable)
+  call.mjs ... --url http://127.0.0.1:5151                    l'application visée
+  call.mjs ... --json                                         la réponse brute
+
+Codes de sortie : 0 réponse · 1 refus ou erreur gRPC · 64 mauvais usage · 69 application injoignable
+`.trim();
+
+/**
+ * Coupe `nom=valeur` au PREMIER `=` : une valeur peut en contenir (jeton base64).
+ *
+ * @param {string} pair - la paire saisie.
+ * @returns {[string, string] | null} le nom et la valeur, ou `null` si la forme est fausse.
+ */
+const splitPair = (pair) => {
+  const at = pair.indexOf("=");
+  if (at <= 0) return null;
+  return [pair.slice(0, at), pair.slice(at + 1)];
+};
+
+/**
+ * Lit la ligne de commande.
+ *
+ * @param {string[]} argv - les arguments, sans `node` ni le script.
+ * @returns {{ method: string, url: string, body: Record<string, unknown>, headers: Record<string, string>, json: boolean } | { error: string }}
+ *   la demande, ou l'erreur d'usage à afficher.
+ */
+export function parseArgs(argv) {
+  let method = null;
+  let url = DEFAULT_URL;
+  let json = false;
+  let file = null;
+  const fields = Object.create(null);
+  const headers = Object.create(null);
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (
+      arg === "--field" ||
+      arg === "--header" ||
+      arg === "--url" ||
+      arg === "--file"
+    ) {
+      const value = argv[++i];
+      if (value === undefined) return { error: `${arg} attend une valeur` };
+      if (arg === "--url") url = value;
+      else if (arg === "--file") file = value;
+      else {
+        const pair = splitPair(value);
+        if (pair === null)
+          return { error: `${arg} attend nom=valeur, reçu « ${value} »` };
+        (arg === "--field" ? fields : headers)[pair[0]] = pair[1];
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) return { error: `option inconnue : ${arg}` };
+    if (method !== null)
+      return { error: `une seule méthode par appel (reçu « ${arg} »)` };
+    method = arg.replace(/^\/+/u, "");
+  }
+  if (method === null) return { error: "la méthode à appeler manque" };
+  if (!METHOD_RE.test(method)) {
+    return {
+      error: `méthode « ${method} » : la forme est paquet.Service/Méthode, comme greet.v1.GreetService/Greet`,
+    };
+  }
+  let body = fields;
+  if (file !== null) {
+    if (Object.keys(fields).length !== 0)
+      return { error: "--file et --field s'excluent" };
+    try {
+      body = JSON.parse(readFileSync(file, "utf8"));
+    } catch (e) {
+      return {
+        error: `--file ${file} : ${e instanceof Error ? e.message : String(e)}`,
+      };
+    }
+  }
+  return { method, url: url.replace(/\/+$/u, ""), body, headers, json };
+}
+
+/**
+ * Envoie l'appel Connect unaire et lit la réponse.
+ *
+ * @param {{ method: string, url: string, body: unknown, headers: Record<string, string> }} request - la demande.
+ * @returns {Promise<{ status: number, payload: unknown }>} le statut HTTP et le corps décodé (texte brut s'il n'est pas JSON).
+ */
+export async function callConnect(request) {
+  const response = await fetch(`${request.url}/${request.method}`, {
+    method: "POST",
+    headers: {
+      ...request.headers,
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+    },
+    body: JSON.stringify(request.body),
+  });
+  const text = await response.text();
+  let payload = text;
+  try {
+    payload = text === "" ? {} : JSON.parse(text);
+  } catch {
+    // corps non JSON (une page d'erreur HTML) : rendu tel quel
+  }
+  return { status: response.status, payload };
+}
+
+/**
+ * Le code gRPC d'un refus Connect (`{"code":"unauthenticated"}`), ou `null`.
+ *
+ * @param {unknown} payload - le corps décodé.
+ * @returns {string | null} le code textuel.
+ */
+const connectCode = (payload) =>
+  payload !== null &&
+  typeof payload === "object" &&
+  "code" in payload &&
+  typeof payload.code === "string"
+    ? payload.code
+    : null;
+
+/**
+ * Exécute la commande.
+ *
+ * @param {string[]} argv - les arguments.
+ * @returns {Promise<number>} le code de sortie.
+ */
+export async function main(argv) {
+  const request = parseArgs(argv);
+  if ("error" in request) {
+    process.stderr.write(`${request.error}\n\n${USAGE}\n`);
+    return 64;
+  }
+  let result;
+  try {
+    result = await callConnect(request);
+  } catch (e) {
+    const cause =
+      e instanceof Error && e.cause instanceof Error
+        ? e.cause.message
+        : String(e);
+    process.stderr.write(
+      `L'application ne répond pas sur ${request.url} (${cause}).\n` +
+        "Démarre-la : npx nodefony development — puis relance l'appel.\n",
+    );
+    return 69;
+  }
+  const { status, payload } = result;
+  if (request.json) {
+    process.stdout.write(`${JSON.stringify({ status, payload })}\n`);
+  } else if (status === 200) {
+    process.stdout.write(
+      `HTTP 200 · ${request.method}\n${JSON.stringify(payload, null, 2)}\n`,
+    );
+  } else {
+    const code = connectCode(payload);
+    process.stdout.write(
+      code === null
+        ? `HTTP ${status} · ${request.method} — pas une réponse gRPC :\n${typeof payload === "string" ? payload : JSON.stringify(payload, null, 2)}\n`
+        : `HTTP ${status} · ${request.method} — refus gRPC « ${code} »${
+            typeof payload === "object" &&
+            payload !== null &&
+            "message" in payload
+              ? ` : ${String(payload.message)}`
+              : ""
+          }\n`,
+    );
+  }
+  return status === 200 ? 0 : 1;
+}
+
+// Exécuté directement (et non importé par son test) : rendre le code. Chemins
+// RÉELS des deux côtés — lancé par un lien (`/var/…` sous macOS), la
+// comparaison brute échouait et le script ne faisait rien.
+if (
+  process.argv[1] !== undefined &&
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/nodefony-add-realtime-binary/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: nodefony-add-realtime-binary
+metadata:
+  version: 1.1.0
+description: >
+  Fait passer des octets sur la socket Nodefony — mesures de capteurs, image, audio, état de
+  jeu compact, document partagé — par le codec CBOR négocié et un `Uint8Array` dans la charge
+  d'un canal, sous les mêmes gardes que le texte, au lieu de base64, d'un en-tête binaire maison
+  ou d'un WebSocket brut. Dit QUAND le binaire gagne et quand il perd, chiffres mesurés à
+  l'appui, comment représenter la donnée (tableau typé, bits tassés, réduction côté serveur), et
+  ce qui rate sans un message. À charger AVANT de mettre des octets, un tableau typé ou un flux
+  audio/vidéo dans un canal, ou de choisir un codec. Le canal lui-même relève de
+  `nodefony-add-realtime-channel`.
+  Déclencheurs : "envoyer des octets", "binaire", "données binaires", "CBOR",
+  "Uint8Array", "Float32Array", "tableau typé", "base64", "envoyer une image", "audio sur la
+  socket", "flux de capteurs", "trames trop grosses", "réduire la bande passante", "mes octets
+  arrivent en objet", "$bytes", "codec", "onRealtimeBinary".
+---
+
+# add-realtime-binary — des octets dans un canal, sous les mêmes gardes
+
+> 🧭 **Arrivé ici directement ? Charge aussi `nodefony-dev`** (la conduite commune) et
+> `nodefony-add-realtime-channel` (le canal qui porte les octets). Cette page ne couvre QUE les
+> octets.
+>
+> Pages installées — **exécute, puis lis** :
+>
+> ```bash
+> node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs --open cbor
+> node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs codec octets
+> ```
+>
+> `nodefony/docs/cbor.md` (le codec, ses mesures), `nodefony/docs/client.md` (« Choisir le codec
+> de trame »), `@nodefony/realtime/docs/protocole.md` (« Des octets dans la charge »),
+> `@nodefony/realtime/docs/configuration.md` (clé `codec`).
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; historique = `git log`.
+> Chaque bloc de code est un EXTRAIT d'un fichier exécuté — la démo binaire de l'application
+> générée (marqueur `excerpt`) : un test refuse qu'il en diverge.
+
+## 1. Quel besoin → quelle voie
+
+| Tu veux faire passer…                                      | La voie                                                                                                  |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| des octets qui appartiennent à un canal (le cas normal)    | `codec: "cbor"` côté serveur + `Uint8Array` dans la charge + `publish` / `on(canal)` (§4, §5)            |
+| des séries numériques denses (mesures, positions, spectre) | `toLittleEndianBytes(série)` à l'envoi, `fromLittleEndianBytes(octets, Int16Array)` à l'arrivée (§2, §6) |
+| beaucoup de petites valeurs booléennes ou bornées          | des bits tassés dans un `Uint8Array` (§2)                                                                |
+| un fichier, une image lourde, une pièce jointe             | une route HTTP (`POST` multipart, flux) — jamais la socket ; puis un message qui la cite                 |
+| un protocole binaire entièrement à toi, sans canal         | le flux brut `onRealtimeBinary()` / `onBinary()` — HORS des gardes (§7)                                  |
+| des objets ordinaires (texte, nombres, statuts)            | rien : reste en JSON, le défaut. CBOR y est plus lent (§2)                                               |
+
+**N'invente jamais d'en-tête binaire maison** (`[n° de canal][charge]`), ni base64 dans une chaîne :
+le premier contourne toutes les gardes et se maintient des deux côtés ; le second coûte un tiers
+d'octets en plus et un décodage des milliers de fois plus lent (§2).
+
+## 2. Décider avec les mesures — le binaire gagne SUR LES OCTETS, et seulement là
+
+Mesures du framework sur trames réelles (Node 26, médiane de 7 séries, mêmes données en JSON avec
+octets en base64 et en CBOR). Le détail, avec conditions et sources : [`references/mesures.md`](references/mesures.md).
+
+| Charge                                  | Taille JSON → CBOR          | Décodage JSON → CBOR | Verdict               |
+| --------------------------------------- | --------------------------- | -------------------- | --------------------- |
+| 64 Ko d'octets                          | 87 452 o → 65 582 o (−25 %) | 541 µs → 0,9 µs      | **CBOR, sans débat**  |
+| 1 Mo d'octets                           | 1,40 Mo → 1,05 Mo (−25 %)   | 9 488 µs → 1 µs      | **CBOR, sans débat**  |
+| 4 Ko d'octets, réception navigateur     | −25 %                       | 26 454 ns → 792 ns   | **CBOR**              |
+| objet de supervision (nombres, statuts) | 1 541 o → 1 172 o (−24 %)   | 7,9 µs → 11,1 µs     | CBOR plus LENT à lire |
+| objet de santé d'une socket             | 1 526 o → 1 256 o (−18 %)   | 9,5 µs → 18,2 µs     | CBOR plus LENT à lire |
+
+D'où les règles :
+
+- **Le serveur passe en `codec: "cbor"` dès que des octets circulent** — sans lui, un `Uint8Array`
+  part en `{"0":1,"1":2,…}` sans un message (§9). Le navigateur qui OFFRE le codec en profite ; celui
+  qui ne l'offre pas reçoit quand même des `Uint8Array` (convention `$bytes` en texte).
+- **N'offre le codec que si des octets circulent** : sur des objets ordinaires, `JSON.parse` est
+  natif au moteur et plus rapide ; le codec pèse ~5,5 Ko compressés à télécharger. CBOR n'est
+  jamais le défaut.
+- 🔴 **Seul `Uint8Array` voyage en octets.** Un `Int16Array`, un `Float32Array`, une `DataView` ou
+  un `ArrayBuffer` posé tel quel dans la charge est **refusé** par le codec binaire (`cbor`, ou
+  `$bytes` côté texte) : le navigateur lève à `publish`, le serveur ne livre pas la trame et le
+  journalise une fois. Le message nomme le geste. Une série de 16 à 64 bits (`Int16Array`,
+  `Float32Array`, `Float64Array`, `Uint32Array`…) passe par les aides du framework, exportées par
+  `nodefony` ET `nodefony/client` : `toLittleEndianBytes(série)` écrit le boutisme (vue sans
+  copie sur une machine petit-boutiste), `fromLittleEndianBytes(octets, Int16Array)` relit et
+  réaligne la vue reçue — qui peut commencer à un décalage impair. Ne recode pas ces deux boucles.
+- **Des octets ne gagnent pas par nature — mesure ta donnée.** 1 024 compteurs écrits en `u32`
+  (4 096 octets) pèsent 4 114 o en CBOR contre 3 128 o en JSON, où de petits entiers s'écrivent
+  court. Choisis la largeur la plus ÉTROITE qui tient la plage (16 bits plutôt que 32), ou garde des
+  nombres.
+- **Tasse les booléens et les petites valeurs** : 1 000 tirs d'une mesure en bits tassés = 142 o,
+  contre 2 025 o en JSON.
+- **Réduis côté serveur avant de publier** : une fenêtre de capteur résumée (min, max, moyenne)
+  par période = 176 o en CBOR contre 307 o en JSON — et c'est la cadence du serveur, pas celle du
+  capteur, qui fixe le débit (`nodefony-add-realtime-channel`, « état ou événement »).
+- **La bande passante d'un écran JSON se gagne par la donnée, pas par le codec** : réduction côté
+  serveur et cadence adaptative (skill `nodefony-add-realtime-channel`, sa page « production », §5). CBOR y gagnerait
+  ~20 % d'octets et y perdrait en temps de lecture.
+
+## 3. Le modèle — une trame comme les autres
+
+- Une trame qui porte des octets est une **notification JSON-RPC ordinaire** dont la charge est, ou
+  contient, un `Uint8Array`. Il n'y a pas de seconde grammaire.
+- Le **codec** ne dit que la forme sur le fil : en CBOR, les octets voyagent tels quels ; sur une
+  connexion restée en texte, sous la convention `{"$bytes":"<base64url>"}`, que le client relit en
+  `Uint8Array` sans rien importer.
+- Le codec se **négocie** par connexion : le navigateur l'offre, le serveur choisit et l'annonce
+  dans `realtime:welcome`. Un client qui ne l'offre pas reste en texte — rien ne casse. Un canal
+  suivi par des connexions CBOR et texte paie un encodage par codec, jamais un par abonné.
+- Parce que c'est la même trame, les octets d'un canal passent par **les mêmes gardes** que le
+  texte : politique du canal, rôles, audit, sonde.
+
+## 4. Mise en place — une ligne par côté
+
+Serveur (`nodefony.config.ts`) : `use("@nodefony/realtime", { codec: "cbor" })` — la variable
+`NF_REALTIME_CODEC` le surcharge.
+
+| Serveur                  | Navigateur offre CBOR | Fil retenu | Octets reçus en              |
+| ------------------------ | --------------------- | ---------- | ---------------------------- |
+| `codec: "cbor"`          | oui                   | CBOR       | `Uint8Array`                 |
+| `codec: "cbor"`          | non                   | texte      | `Uint8Array` (via `$bytes`)  |
+| `codec: "json"` (défaut) | oui ou non            | texte      | 🔴 objet déformé `{"0":1,…}` |
+
+Navigateur — le codec est une **OFFRE**, faite à la création de la socket (`CBOR_FRAME_CODEC`, de
+`nodefony/cbor`). La démo binaire ouvre ainsi la sienne :
+
+<!-- excerpt: demo/front/frontend/src/binary/binaryClient.ts.tpl -->
+
+```ts
+export function openBinary(
+  cbor: boolean,
+  transport?: RealtimeTransportFactory,
+) {
+  return NodefonySocket.fromContract<BinaryContract>(
+    {
+      url: BINARY_SOCKET,
+      autoReconnect: false,
+      codec: cbor ? nodefonyCbor.CBOR_FRAME_CODEC : undefined,
+    },
+    transport,
+  );
+}
+```
+
+Avec `NodefonySocket.shared({ url, codec })`, l'offre ne compte qu'à la **PREMIÈRE** création pour
+cette adresse : une seconde demande rend l'instance existante, réglages compris (§9). Importe le
+codec depuis `nodefony/cbor` seulement dans les pages qui en ont besoin : il reste hors du paquet
+client tant qu'on ne l'importe pas.
+
+## 5. Publier et recevoir
+
+Le serveur met un `Uint8Array` DANS la charge, et publie comme d'habitude — ici la fabrique d'un
+canal de la démo, qui tourne au premier abonné et s'arrête au départ du dernier :
+
+<!-- excerpt: demo/server/nodefony/controllers/BinaryController.ts.tpl -->
+
+```ts
+  @RealtimeChannel(VIBRATION_CHANNEL)
+  vibrationChannel(
+    _channel: string,
+    publish: ContractRealtimePublish<BinaryContract>,
+  ): () => void {
+    let seq = 0;
+    const timer = setInterval(() => {
+      seq += 1;
+      // Petit-boutiste écrit EXPLICITEMENT : la page lira de même, quelle
+      // que soit la machine qui l'exécute.
+      const samples = new Uint8Array(VIBRATION_SAMPLES * 2);
+      const view = new DataView(samples.buffer);
+```
+
+Hors d'une fabrique (service, tâche, minuteur) : `getRealtimeHub().publish(canal, { seq, samples })`.
+Côté navigateur, rien ne change : `socket.subscribe(canal)` puis `socket.on(canal, h)` — la charge
+reçue porte un `Uint8Array`.
+
+- `subscribe(canal)` prend **un seul argument** ; le handler se pose par `on(canal, handler)`.
+- Une charge est un objet, un tableau, des octets, ou absente — jamais un scalaire
+  (`publish("c", 42)` lève une `TypeError` qui nomme le canal).
+- Un `Buffer` de Node est un `Uint8Array` : il part en octets, jamais en `{type:"Buffer",data:[…]}`.
+- Une `Date` revient en chaîne et un `bigint` est refusé — exactement comme en JSON.
+- **Écris l'ordre des octets EXPLICITEMENT** (`setInt16(i, v, true)` : petit-boutiste) : la page
+  doit lire de même, quelle que soit la machine.
+
+**Le client pousse des octets** — même règle dans l'autre sens : un `Uint8Array` dans les paramètres
+(`socket.request(action, { bytes })` vers une action, `socket.emit(nom, { samples })` vers une
+entrée `@RealtimeInbound`). Côté serveur, **valide la forme avant d'y toucher** : la démo binaire
+reçoit le dessin de la page par l'action `binary:digest`, dont le schéma
+`z.strictObject({ bytes: z.instanceof(Uint8Array) })` refuse tout ce qui n'est pas un `Uint8Array`
+— un objet forgé ne passe pas pour des octets. Borne la longueur avant d'allouer. Un script Node
+(passerelle de sonde) offre le codec comme le navigateur, à la création de sa socket.
+
+## 6. Lire des octets sans se tromper
+
+- **Une série homogène se relit par `fromLittleEndianBytes(octets, Int16Array)`** (`nodefony/client`) :
+  elle vérifie la longueur, recopie si la vue est mal alignée, retourne les octets sur une machine
+  gros-boutiste. La boucle `DataView` ci-dessous ne sert qu'à un format MIXTE (champs de tailles
+  différentes dans les mêmes octets).
+- **`DataView` : passe la tranche entière.** Un `Buffer` de Node — et une vue décodée — ne commence
+  pas à 0 dans son tampon : `new DataView(data.buffer)` lit des octets qui ne sont pas les tiens.
+
+<!-- excerpt: demo/front/frontend/src/binary/binaryClient.ts.tpl -->
+
+```ts
+export function readSamples(bytes: Uint8Array): Int16Array {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const samples = new Int16Array(bytes.byteLength / 2);
+  for (let i = 0; i < samples.length; i += 1) {
+    samples[i] = view.getInt16(i * 2, true);
+  }
+  return samples;
+}
+```
+
+- Écris ton décodeur sur `Uint8Array` : il sert tel quel dans le navigateur et côté serveur.
+- Si tu appelles toi-même `decodeCbor()` sur un tampon que tu réutilises ensuite, **copie** les
+  octets décodés à garder (`slice()`) : ce sont des vues sur ce tampon.
+- Ne fais jamais confiance à des octets reçus : borne les longueurs avant d'allouer.
+
+## 7. Canal ou flux brut ?
+
+🔴 **Le flux brut est HORS des gardes.** Une trame reçue par `onRealtimeBinary(data)` ne passe ni
+par le verrou de frame ni par les politiques d'action et de canal : seule la connexion a franchi
+l'origine, l'authentification et le pare-feu. Si tu l'emploies, **toute décision d'accès est à toi**
+— lis l'identité par `RequestContext.getAuthenticatedUser()` et refuse explicitement.
+
+🔴 **Le flux brut n'existe pas sur une connexion CBOR** : toute trame binaire y est une frame du
+codec. `onRealtimeBinary()` n'y est jamais appelée ; `sendBinaryToClient()` (serveur) et `socket.sendBinary()` (navigateur) rendent
+`false`.
+
+Il n'a plus de raison de performance : un canal CBOR décode 1 Mo en ~1 µs. **Préfère un canal +
+`Uint8Array`** — même politique, mêmes gardes, même bus entre serveurs.
+
+## 8. Le piège du `$bytes` forgé
+
+Quand le serveur a `codec: "cbor"` et qu'une connexion est restée en texte, un objet de la forme
+**exacte** `{ $bytes: "<chaîne>" }` (seule clé, valeur chaîne) est réservé aux octets. L'encodeur
+**refuse** d'en envoyer un qui ne vient pas d'octets : un client texte le relirait en octets, un
+client CBOR en objet. La démo le montre — seul, il lève une `TypeError` à la ligne fautive ; avec
+une seconde clé, il part (et c'est le schéma du serveur qui refuse ce qui n'est pas un
+`Uint8Array`) :
+
+<!-- excerpt: demo/front/frontend/src/binary/binaryClient.ts.tpl -->
+
+```ts
+const forged = extraKey
+  ? { $bytes: "AQID", note: "deux clés" }
+  : { $bytes: "AQID" };
+await socket.request("binary:digest", { bytes: forged });
+```
+
+- Navigateur : `emit` / `publish` / `request` **lèvent** à la ligne fautive.
+- Serveur : la publication n'atteint pas les abonnés texte, une ligne `ERROR` par publication. Un
+  tel objet **conservé** (état renvoyé à chaque abonné) est refusé à chaque envoi : renomme la clé.
+- Avec `codec: "json"`, `$bytes` est une clé comme une autre : la règle ne s'applique pas.
+
+## 9. Plusieurs serveurs, bornes, et ce qui arrive SANS message
+
+- **Plusieurs serveurs** : deux conditions, sinon une partie des écrans reçoit autre chose — le
+  canal est DIFFUSÉ (`@RealtimeBroadcast`, skill `nodefony-add-realtime-channel`), et `codec:
+"cbor"` est réglé À L'IDENTIQUE sur chaque serveur (un serveur resté en JSON déforme en
+  silence les octets qu'il sert).
+- **Bus** : les octets traversent `redis` et `cluster` **intacts**, scellés comme le texte si
+  `backplane.secret` est posé. Mesuré sur Redis, charge de 16 Ko : −25 % d'octets, +30 % de débit,
+  −11 % de latence médiane — pour +15 à 30 % de CPU par message. Le bus IPC de `nodefony cluster`
+  passe en sérialisation avancée tout seul (~1 µs par saut).
+- **Taille d'une trame entrante** : bornée par `websocket.maxPayload` de `@nodefony/http` (1 Mio
+  par défaut) ; au-delà, la socket se ferme en `1009`. Un besoin plus gros est un fichier : route
+  HTTP. Ne relève la borne qu'en connaissance de cause (toute l'application en hérite).
+- **Débit** : un flux audio (~50 trames/s) doit passer sous `maxFramesPerSecond` si tu l'actives.
+- **Serveur resté en `codec: "json"`** : un `Uint8Array` part en `{"0":1,"1":2,…}` — aucune erreur.
+  Le piège n°1 : vérifier la clé `codec` avant tout autre diagnostic.
+- **`codec` passé à un `shared()` qui n'est pas le premier** : l'instance existante revient,
+  réglages compris ; la connexion reste en texte (un avertissement hors production seulement).
+- **`sendBinary()` sur un transport fermé** : rend `false`, compté dans `framesUnsent`, sans notice.
+- **Ne déduis jamais le codec de l'en-tête `Sec-WebSocket-Protocol`** renvoyé au handshake : seule
+  `socket.codec` fait foi.
+- Un message d'erreur ou une notice qui parle d'octets : sa cause et ton geste sont dans
+  [`references/messages.md`](references/messages.md).
+
+## 10. Prouver
+
+- `socket.codec` vaut `"nodefony.jsonrpc.cbor.v1"` une fois l'accueil reçu ;
+  `"nodefony.jsonrpc.v1"` = texte.
+- Compteurs côté navigateur : `socket.binaryFramesDiscarded`, `socket.malformedFramesDiscarded`
+  doivent rester à 0.
+- Un test publie un `Uint8Array` sur un canal et vérifie que l'abonné reçoit un `Uint8Array`
+  **identique** (`instanceof Uint8Array` et mêmes octets) — sous CBOR ET sous texte.
+- Une décision de représentation (tableau typé, bits tassés, réduction) se **mesure** sur TA donnée
+  : compare la taille de la trame encodée par `encodeCbor` (`nodefony/cbor`) et par `JSON.stringify`
+  — le spectre en `u32` a montré que l'intuition peut perdre.
+- Pour lire le fil à l'œil dans l'inspecteur réseau : `NF_REALTIME_CODEC=json` remet le serveur en
+  texte. Exception de débogage : la taille des trames et la contre-pression changent, aucune mesure
+  prise ainsi ne vaut pour la production.
+
+## 11. Voisins
+
+| Besoin                                                | Skill                           |
+| ----------------------------------------------------- | ------------------------------- |
+| Le canal qui porte les octets : le créer, le protéger | `nodefony-add-realtime-channel` |
+| Un fichier, une pièce jointe, un flux HTTP            | `nodefony-add-crud`             |
+| Un service gRPC (protobuf, autre usage que la socket) | `nodefony-add-grpc-service`     |
+| Voir l'écran, lire les trames depuis la page          | `nodefony-browser`              |
+| Une trame qui n'arrive plus, une socket qui se ferme  | `nodefony-troubleshoot`         |

package/skills/nodefony-add-realtime-binary/references/messages.md

@@ -0,0 +1,20 @@
+# Chaque message, sa cause, ton geste — des octets qui ne passent pas
+
+> Chargé depuis `SKILL.md` quand un message d'erreur ou une notice parle d'octets, de CBOR, de
+> `$bytes` ou de trame binaire. Les textes entre guillemets sont recopiés du code (un test du
+> framework refuse qu'ils en divergent) ; `<…>` marque une partie variable.
+
+| Où                                                 | Message                                                                                      | Cause                                                                                                                                | Geste                                                                        |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| exception (navigateur) / journal `ERROR` (serveur) | `codec JSON : objet {"$bytes": …} non issu d'octets`                                         | objet applicatif de la forme exacte du marqueur, vers une connexion texte                                                            | envoyer un vrai `Uint8Array`, ou renommer / ajouter une clé                  |
+| journal `ERROR` serveur                            | `rpc <action> : réponse non encodable`                                                       | une `@RealtimeAction` a rendu une valeur que le codec refuse (`$bytes` forgé, cycle, `bigint`) ; le client reçoit `-32603` générique | corriger la valeur rendue                                                    |
+| exception                                          | `Impossible d'encoder un BigInt — JSON.stringify le refuse aussi`                            | `bigint` dans la charge, sous CBOR                                                                                                   | convertir en chaîne ou en nombre                                             |
+| exception                                          | `Impossible d'encoder une structure circulaire — JSON.stringify la refuse aussi`             | cycle dans la charge                                                                                                                 | aplatir la donnée                                                            |
+| notice navigateur (`-32700`)                       | `Trame binaire écartée : en JSON-RPC texte elle n'a pas de canal`                            | le serveur écrit du binaire brut sur une connexion texte sans `onBinary()`                                                           | lire par `onBinary()`, ou passer par un canal + CBOR                         |
+| notice navigateur (`-32700`)                       | `Trame illisible écartée : elle ne se décode pas en <protocole>`                             | trame que le codec ne décode pas                                                                                                     | côté serveur : chercher qui écrit hors du codec                              |
+| notice navigateur                                  | `Codec « <protocole> » annoncé sans avoir été offert : la connexion reste en JSON-RPC texte` | serveur qui annonce un codec que ce client n'a pas offert                                                                            | mettre client et serveur à la même version                                   |
+| notice navigateur                                  | `Flux binaire brut indisponible sous <protocole>`                                            | `onBinary()` / `sendBinary()` sur une connexion CBOR                                                                                 | publier les octets sur un canal                                              |
+| journal `WARNING` serveur, une fois par connexion  | `WS realtime : trame binaire reçue et écartée`                                               | binaire brut reçu sur une connexion texte, sans `onRealtimeBinary()`                                                                 | passer par un canal + CBOR, ou surcharger `onRealtimeBinary()` (hors gardes) |
+| journal `WARNING` serveur, une fois par connexion  | `WS realtime : sendBinaryToClient refusé`                                                    | `sendBinaryToClient()` sur une connexion CBOR                                                                                        | publier les octets sur un canal                                              |
+| journal `WARNING` serveur, une fois par nature     | `WS realtime : trame binaire illisible pour <protocole> reçue et écartée`                    | trame CBOR malformée ou tronquée ; **aucune réponse** n'est renvoyée (pas d'oracle pour un fuzzer), connexion conservée              | côté client : chercher qui écrit hors du codec                               |
+| exception (`CborError`)                            | `CBOR refusé à l'octet <n> : <raison>`                                                       | `decodeCbor()` appelé par l'application sur des octets invalides ; `err.offset` dit où                                               | valider la source ; ne jamais faire confiance à des octets reçus             |

package/skills/nodefony-add-realtime-binary/references/mesures.md

@@ -0,0 +1,59 @@
+# Les mesures du binaire — de quoi décider, avec leurs conditions
+
+> Chargé depuis `SKILL.md` §2 quand une décision de codec ou de représentation se discute. Toutes
+> les valeurs viennent des bancs du framework (Node 26) ; une valeur sans ses conditions ne vaut
+> rien — elles sont donc écrites à côté. Les pages installées qui portent une partie de ces
+> chiffres : `nodefony/docs/cbor.md` (« Performance & mémoire »), `nodefony/docs/client.md`
+> (« Choisir le codec de trame »). **Une mesure de ce tableau ne remplace pas la tienne** : ta
+> donnée a sa forme, mesure-la (`SKILL.md` §10).
+
+## 1. Codec : JSON (octets en base64) contre CBOR — trames réelles, médiane de 7 séries
+
+| Charge                                  | Taille JSON → CBOR                | Décodage JSON → CBOR | Lecture                                |
+| --------------------------------------- | --------------------------------- | -------------------- | -------------------------------------- |
+| 64 Ko d'octets                          | 87 452 o → 65 582 o (−25 %)       | 541 µs → 0,9 µs      | CBOR écrase JSON                       |
+| 1 Mo d'octets                           | 1 398 174 o → 1 048 622 o (−25 %) | 9 488 µs → 1 µs      | CBOR écrase JSON                       |
+| 4 Ko d'octets, réception navigateur     | −25 % d'octets                    | 26 454 ns → 792 ns   | ≈ 33× plus rapide                      |
+| objet de supervision (nombres, statuts) | 1 541 o → 1 172 o (−24 %)         | 7,9 µs → 11,1 µs     | CBOR plus court, mais plus lent à lire |
+| objet de santé d'une socket             | 1 526 o → 1 256 o (−18 %)         | 9,5 µs → 18,2 µs     | CBOR plus court, mais plus lent à lire |
+| message de chat (salon)                 | 115 o → 89 o                      | —                    | gain de taille faible sur du texte     |
+| notification privée de chat             | 183 o → 150 o                     | —                    | idem                                   |
+
+Le codec CBOR pèse environ 5,5 Ko compressés côté navigateur (sous-chemin `nodefony/cbor`, chargé
+seulement par les pages qui l'importent). Un accélérateur natif de décodage CBOR a été essayé : il
+n'apportait rien face à `JSON.parse` natif sur les objets, et CBOR pur suffit sur les octets.
+
+## 2. Représentation de la donnée — la forme compte plus que le codec
+
+🔴 Seul `Uint8Array` voyage en octets : un `Int16Array` ou un `Float32Array` posé tel quel est
+refusé par le codec binaire. Toutes les lignes ci-dessous publient des OCTETS (écrits par `DataView`).
+
+| Donnée                                         | Comparaison                          | Lecture                                                                      |
+| ---------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------- |
+| 1 024 compteurs écrits en `u32` (octets)       | 4 114 o (CBOR) contre 3 128 o (JSON) | **le binaire PERD** : petits entiers courts en texte, `u32` = 4 octets fixes |
+| 1 000 tirs d'une mesure, bits tassés           | 142 o contre 2 025 o (JSON)          | tasser gagne d'un ordre de grandeur                                          |
+| comptes agrégés d'une mesure                   | 30 o                                 | publier l'agrégat, pas la matière brute                                      |
+| fenêtre de capteur réduite (min, max, moyenne) | 176 o (CBOR) contre 307 o (JSON)     | réduire côté serveur, publier à la cadence du serveur                        |
+
+## 3. Le bus entre serveurs
+
+| Bus                                      | Condition                 | CBOR contre JSON + base64                                                                                                                  |
+| ---------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Redis scellé                             | charge de 16 Ko, médianes | −25 % d'octets, +30 % de débit, −11 % de latence médiane, +15 à 30 % de CPU par message (ramasse-miettes : un tampon hors tas par message) |
+| IPC de `nodefony cluster` (« advanced ») | maître + ouvriers         | −23 % de débit à 64 o, ×2,2 à 64 Ko ; ~1 µs par saut — retenu partout, sans écart développement / production                               |
+
+## 4. Le coût du binaire pour qui ne s'en sert pas
+
+- Le chemin binaire n'est armé QUE si un codec binaire est configuré : un parcours armé en
+  permanence coûtait +20 à +35 % sur le chemin texte, il a été écarté.
+- Une application qui ne publie pas d'octets ne paie rien de plus (contrôle au premier niveau
+  seulement, sans codec).
+
+## 5. Bornes en vigueur
+
+| Borne                                             | Valeur           | Effet au dépassement                       |
+| ------------------------------------------------- | ---------------- | ------------------------------------------ |
+| `websocket.maxPayload` (`@nodefony/http`)         | 1 Mio par défaut | fermeture `1009` de la socket              |
+| `maxFramesPerSecond` (`@nodefony/http`)           | `0` = désactivé  | refus comptés, puis fermeture sur un solde |
+| `backpressureCloseAfterDrops` (serveur et client) | 1 000            | fermeture (`1013` serveur, `4007` client)  |
+| `maxBufferedAmount` (navigateur)                  | `0` = désactivé  | envois en trop jetés, comptés              |