@nodefony/realtime 10.0.0-beta.5 → 10.0.0-beta.6

package/docs/configuration.md

@@ -281,13 +281,14 @@ regarder quand un message ne traverse pas.
 
 ## ⚙️ Le schéma, clé par clé
 
-Sept blocs, seize clés au total. Le tableau donne la vérité complète ; les sections qui suivent
+Vingt et une clés au total. Le tableau donne la vérité complète ; les sections qui suivent
 expliquent quand et pourquoi en changer.
 
 <!-- prettier-ignore -->
 | Clé | Type | Défaut | Effet |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | `false` = module chargé mais inerte : ni API d'administration, ni backplane, ni sonde, ni garde |
+| `codec` | `"json"` \| `"cbor"` | `"json"` | forme des frames sur le fil. `"cbor"` = accordé à tout client qui l'offre, les autres restent en texte avec la convention d'octets `$bytes` |
 | `backplane.driver` | `string` | `"loopback"` | nom résolu dans le registre de drivers ; inconnu → avertissement, le hub reste local |
 | `backplane.namespace` | `string?` | _absent_ → nom d'app | cloison du transport partagé ; suffixe le canal pub/sub. Motif `^[\w.-]+$` |
 | `backplane.secret` | `string?` (≥ 32) | _absent_ | scelle les messages du transport partagé (HMAC) ; identique sur tous les pods. Absent = bus ouvert + avertissement au boot |
@@ -295,9 +296,14 @@ expliquent quand et pourquoi en changer.
 | `cluster.probe.enabled` | `boolean` | `true` | branche la sonde agrégée du pod en worker de cluster. `false` = aucun minuteur, aucun IPC |
 | `slowConsumer.bytes` | `number` entier > 0 | `1048576` (1 MiB) | seuil de **comptage** des consommateurs lents dans la sonde. Observe, n'agit pas |
 | `limits.maxChannelsPerConnection` | `number > 0` \| `null` | `256` | plafond de canaux par connexion ; au-delà le `subscribe` est refusé. `null` = illimité |
+| `authenticateTimeoutMs` | `number` entier > 0 | `10000` | délai de l'authentification à la poignée de main ; dépassé, fermeture `1013` et le client revient |
+| `allowTimeoutMs` | `number` entier > 0 | `5000` | délai d'une règle d'admission `allow`, attente en file comprise ; dépassé, motif `unavailable` |
+| `maxPendingAllowsPerConnection` | `number` entier > 0 | `8` | appels d'`allow` en vol pour une connexion ; au-delà la demande attend son tour |
+| `maxPendingAllowsTotal` | `number` entier > 0 | `512` | appels d'`allow` en vol pour l'exemplaire ; au-delà `unavailable` sans appel |
 | `csrf.checkOrigin.enabled` | `boolean` | `false` | active le contrôle d'`Origin` à l'ouverture de la socket |
 | `csrf.checkOrigin.allowList` | `string[]` | `[]` | origines acceptées, **comparaison exacte**. Vide + activé = tout est refusé |
 | `csrf.checkOrigin.allowMissingOrigin` | `boolean` | `false` | accepter une ouverture sans en-tête `Origin` (clients non-navigateur) |
+| `publicOrigin` | `string` (origine nue) | aucun | où la socket est servie quand ce n'est pas l'origine de la page ; déclarée seule dans `connect-src` |
 | `clientLogs.enabled` | `boolean` | `false` | accepte les journaux du navigateur sur le canal montant `nodefony:syslog:uplink`. Surface d'écriture, fermée par défaut ; une connexion anonyme ne pousse rien |
 | `clientLogs.maxEntriesPerBatch` | `number` | `50` | entrées acceptées par lot |
 | `clientLogs.maxEntriesPerWindow` | `number` | `300` | entrées acceptées par fenêtre de débit |
@@ -325,6 +331,47 @@ inerte (`RealtimeService.init()`, `RealtimeService.ts#RealtimeService.init`).
 Le bon usage : un environnement où le temps réel n'a pas de sens (une commande CLI, un banc). Pour
 désactiver vraiment, retire le module du manifeste.
 
+### `codec` — la forme des frames sur le fil
+
+Le codec ne change pas ce qu'une frame **dit**, seulement la forme qu'elle prend sur le fil : c'est
+toujours du JSON-RPC 2.0, écrit en texte ou en CBOR (ADR-0022 §2). Le défaut `"json"` est le bon
+réglage tant que les charges sont des objets ordinaires. Passe à `"cbor"` dès que des **octets**
+circulent dans un canal (document partagé, série de mesures, audio) :
+
+```ts ignore
+// nodefony.config.ts
+use("@nodefony/realtime", { codec: "cbor" });
+```
+
+Ce que le serveur fait alors, connexion par connexion (`frameCodecNegotiation.ts#negotiateFrameCodec`) :
+
+| Le client…                                                   | Fil retenu                                      | Les octets d'une charge                                               |
+| ------------------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------- |
+| offre `nodefony.jsonrpc.cbor.v1` (`codec: CBOR_FRAME_CODEC`) | CBOR, annoncé dans `realtime:welcome` (`codec`) | chaîne d'octets native, sans base64                                   |
+| n'offre rien (client ancien, autre langage, `curl`)          | JSON-RPC texte                                  | `{"$bytes":"<base64url>"}`, annoncé par le champ `bytes` de l'accueil |
+
+Aucun client ne casse : celui qui ne connaît pas CBOR reste en texte et reçoit les mêmes données.
+Un canal suivi par les deux sortes de connexions paie **un encodage par codec**, jamais un par
+abonné (`RealtimeHub.ts#ChannelFrame`).
+
+Quatre conséquences à connaître avant d'activer :
+
+- **Le flux binaire brut ne sert plus les connexions CBOR.** Sur une telle connexion, toute trame
+  binaire est une frame du codec : `onRealtimeBinary()` n'y est jamais appelée et
+  `sendBinaryToClient()` n'y écrit rien. Il ne sert plus que les connexions restées en texte.
+- **Un objet applicatif de la forme exacte `{"$bytes": "<chaîne>"}` est refusé** à l'envoi vers une
+  connexion texte : le client le relirait en octets. La règle est détaillée dans
+  [Protocole](./protocole.md#des-octets-dans-la-charge--une-frame-comme-les-autres).
+- **Le REST du plan d'administration prend la même convention.** Une réponse `GET
+/nodefony/<module>/api/*` passe par le codec des connexions texte et porte l'en-tête
+  `x-nodefony-bytes: $bytes` (`AdminApiController.ts#AdminApiController.dispatch`). Un client la
+  relit par `textCodecForMarker(response.headers.get(BYTES_MARKER_HEADER))`, exporté par
+  `nodefony` : des octets y reviennent à l'identique, que la valeur arrive par `fetch` ou par la
+  socket. Sans l'en-tête, le corps est du JSON natif.
+- **`NF_REALTIME_CODEC=json` remet le fil en texte** pour le lire dans l'inspecteur réseau du
+  navigateur. C'est une exception de débogage : en texte, la taille des trames et la contre-pression
+  changent, donc une mesure prise ainsi ne vaut pas pour la production.
+
 ### `backplane.driver` — qui relaie les publications
 
 C'est **le** réglage du module. Le champ est une chaîne libre et non une énumération, volontairement :
@@ -382,8 +429,15 @@ déploiement, passe-le par `NF_REALTIME_BACKPLANE_SECRET` (secret k8s, variable
 a la précédence sur la configuration, et un secret n'a rien à faire dans un fichier versionné.
 
 Sans secret, rien ne casse : le transport reste ouvert et le démarrage l'annonce en avertissement.
-La bonne façon de vérifier que le scellement fonctionne est le compteur `ingressRejectedTotal` de la
-sonde de santé — il reste à zéro en régime normal.
+La bonne façon de vérifier que le scellement fonctionne est le compteur `sealRejectedTotal` de la
+sonde de santé : il compte les messages reçus dont le sceau ne se vérifie pas, et reste à zéro en
+régime normal. Chaque refus est aussi journalisé — le premier, puis un sur cent.
+
+> [!WARNING]
+> **Changer le secret, c'est couper le fan-out entre les deux générations.** Pendant une rotation, les
+> exemplaires qui n'ont pas encore le même secret se refusent leurs messages : `sealRejectedTotal`
+> monte sur chacun d'eux jusqu'à ce que tous portent le nouveau. Un second secret accepté en
+> lecture, pour une rotation sans coupure, viendra dans une version 10.x.
 
 > [!NOTE]
 > Le driver `cluster` (IPC entre les workers d'un même pod) n'a pas besoin de secret : ce canal ne
@@ -484,6 +538,43 @@ les clients — un tableau de bord interne qui compose des dizaines de flux, par
 > Le plafond est **par connexion**, pas global. Cent connexions à 256 canaux restent possibles :
 > c'est une garde contre un client abusif, pas contre une charge légitime mal dimensionnée.
 
+### Les délais et plafonds de l'admission — quand la base ne répond plus
+
+Deux moments demandent une réponse à l'extérieur du processus : l'**authentification** à la poignée
+de main (relire une session, vérifier une clé distante) et la règle d'**admission** `allow` d'un canal
+(lire une appartenance en base). Quand la base ralentit ou tombe, ces quatre clés décident de ce que
+le serveur retient, et de ce qu'il rend au client. Elles sont appliquées par
+`AdmissionBudget` (`admissionBudget.ts#AdmissionBudget`), posées par `RealtimeService.init()`
+(`RealtimeService.ts#RealtimeService.init`).
+
+<!-- prettier-ignore -->
+| Clé | Défaut | Ce qui se passe au-delà | Pourquoi ce défaut |
+| --- | --- | --- | --- |
+| `authenticateTimeoutMs` | `10000` | la socket est fermée en `1013` « try again later » ; le client recule puis revient ; une identité arrivée après coup est ignorée | l'authentification relit souvent une session en base ou une clé distante ; 10 s couvrent une base chargée, et au-delà retenir la connexion ne l'authentifierait pas plus vite — elle occuperait seulement une place |
+| `allowTimeoutMs` | `5000` | l'abonné reçoit `realtime:denied` motif `unavailable` et réessaie ; un verdict tardif est ignoré, jamais une admission | une lecture saine répond en millisecondes ; 5 s couvrent une base chargée sans laisser un écran vide au-delà de ce qu'un humain attend |
+| `maxPendingAllowsPerConnection` | `8` | la demande d'abonnement **attend son tour** — jamais refusée | assez pour ouvrir plusieurs canaux en parallèle, assez peu pour qu'une connexion ne monopolise pas le pool de la base (souvent 10) ; refuser casserait le rejeu au `welcome`, qui renvoie tous les canaux d'un coup |
+| `maxPendingAllowsTotal` | `512` | `unavailable` sans appeler la règle | à ce niveau la base est déjà l'étranglement : empiler davantage d'appels n'admettrait personne plus vite, et retarderait la reprise |
+
+Deux comportements ne se règlent pas, et c'est voulu : le **coupe-circuit** (50 délais dépassés en
+5 s suspendent les appels pendant 5 s, avec un `retryAfterMs` rendu au client) et le **réessai
+client** (trois au plus, recul exponentiel à gigue complète). Exposés en réglage, ils
+deviendraient le premier levier tourné pendant un incident — exactement le moment où ils
+protègent la base.
+
+```typescript
+// nodefony.config.ts — une base lente, assumée : on attend plus, on retient moins
+use("@nodefony/realtime", {
+  authenticateTimeoutMs: 15_000,
+  allowTimeoutMs: 8000,
+  maxPendingAllowsTotal: 256,
+});
+```
+
+Les quatre clés refusent `0`, un nombre négatif ou non entier, et tout délai au-delà de
+`2 147 483 647` ms : `setTimeout` ramènerait ce délai à 1 ms, et chaque appel échouerait aussitôt.
+Le comportement vu par l'abonné : [`securite.md`](./securite.md) ; les compteurs qui disent quand
+ces bornes travaillent : [`observabilite.md`](./observabilite.md).
+
 ### `csrf.checkOrigin` — qui a le droit d'ouvrir la socket
 
 Trois clés qui forment une seule politique, appliquée à l'ouverture de la connexion
@@ -515,6 +606,31 @@ non-navigateur pouvant toujours forger l'en-tête — appartient à [Sécurité]
 > vérifier. Et `allowMissingOrigin: true` sans authentificateur fort rouvre exactement la brèche que
 > le contrôle ferme.
 
+### `publicOrigin` — une socket servie sur une autre origine
+
+La politique de contenu que pose `@nodefony/security` autorise les connexions vers l'origine de la
+page seulement (`connect-src 'self'`). Une socket servie au même endroit que la page — le cas
+courant, une adresse relative — passe sans rien régler.
+
+Une socket servie **ailleurs** (un autre domaine, un autre port) serait bloquée par le navigateur.
+Tu ne l'écris pas dans la politique : tu dis au module où elle est servie, et il s'y déclare
+lui-même au démarrage (`RealtimeService.ts#RealtimeService.init`).
+
+```ts
+use("@nodefony/realtime", {
+  publicOrigin: "wss://rt.example.com",
+});
+```
+
+La valeur est une **origine nue** : schéma, hôte, port facultatif — ni chemin, ni joker. Une valeur
+qui n'en est pas une arrête le démarrage en nommant la clé. `https://rt.example.com` est accepté et
+déclaré `wss://rt.example.com` : c'est cette forme qui couvre la socket ET le même hôte en
+`https:` (`publicOrigin.ts#realtimeConnectSource`).
+
+Deux clés, deux questions : `publicOrigin` dit où la socket **est** ; `csrf.checkOrigin.allowList`
+dit quelles pages ont le droit de l'**ouvrir**. Une socket sur un autre domaine a souvent besoin
+des deux.
+
 ## 🔌 Choisir le driver de backplane — trois situations
 
 Le choix ne se déduit pas d'un tableau de performances : il se déduit de **ta topologie de
@@ -684,7 +800,7 @@ Le détail du contrat, de l'anti-écho et du cycle de vie d'un driver est dans
 
 ## ⚙️ Variables d'environnement et précédence
 
-Six variables influent sur le module. Trois lui sont propres, les autres viennent du cœur ou du
+Neuf variables influent sur le module. Six lui sont propres, les autres viennent du cœur ou du
 mode cluster. Les trois premières décrivent un **déploiement** — le fond de panier auquel ce
 processus se raccorde — et c'est pour cela qu'elles ne vivent pas dans un fichier versionné.
 
@@ -693,6 +809,8 @@ processus se raccorde — et c'est pour cela qu'elles ne vivent pas dans un fich
 | `NF_REALTIME_DRIVER`              | ce module              | remplace `backplane.driver` — nom libre, un pilote inconnu est signalé     |
 | `NF_REALTIME_BACKPLANE_NAMESPACE` | ce module              | remplace `backplane.namespace` — sépare deux déploiements de la même app   |
 | `NF_REALTIME_BACKPLANE_SECRET`    | ce module              | remplace `backplane.secret` — scelle le transport partagé (≥ 32 car.)      |
+| `NF_REALTIME_CODEC`               | ce module              | remplace `codec` — `json` remet le fil en texte, pour déboguer seulement   |
+| `NF_REALTIME_PUBLIC_ORIGIN`       | ce module              | remplace `publicOrigin` — où la socket est servie, propre au déploiement   |
 | `NF__REALTIME__<CHEMIN>`          | mécanisme du cœur      | remplace n'importe quelle clé, par son chemin. Ex. `NF__REALTIME__ENABLED` |
 | `NF_CLUSTER`                      | posée par le lancement | à `1`, le driver `cluster` s'active en worker. Ne la pose pas à la main    |
 | `NF_CLUSTER_PROBE`                | ce module              | à `0`, coupe la sonde de pod même si `cluster.probe.enabled` est vrai      |
@@ -702,14 +820,14 @@ L'ordre de recouvrement, du plus faible au plus fort :
 
 1. **Les valeurs d'usine du schéma** — ce que tu obtiens sans rien écrire.
 2. **La configuration de l'application** — ton `use("@nodefony/realtime", { … })`.
-3. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`** et
-   **`NF_REALTIME_BACKPLANE_SECRET`** — posées par le Kernel après la fusion et **avant** la
+3. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`**,
+   **`NF_REALTIME_BACKPLANE_SECRET`**, **`NF_REALTIME_CODEC`** et **`NF_REALTIME_PUBLIC_ORIGIN`** — posées par le Kernel après la fusion et **avant** la
    validation Zod (`applyEnvShortcuts`, `Kernel.ts#Kernel.applyEnvConfigOverrides`) : une valeur fausse **arrête le démarrage** en nommant la
    variable (un secret de moins de 32 caractères, un espace de noms qui contient `:`). Chacune
    accepte aussi sa forme `<NOM>_FILE` (secret monté par Docker ou Kubernetes).
 4. **`NF__REALTIME__<CHEMIN>`** — même moment, même validation. Un chemin introuvable produit un
    avertissement avec une suggestion, jamais une clé fantôme. Viser le **même** champ qu'une des
-   trois variables ci-dessus est une ambiguïté : refusée en production, et en développement
+   quatre variables ci-dessus est une ambiguïté : refusée en production, et en développement
    `NF__…` l'emporte avec un avertissement qui nomme les deux.
 
 Le mécanisme générique mérite d'être connu : le double tiret bas sépare les niveaux, les segments
@@ -782,16 +900,18 @@ Trois endroits, par ordre de fiabilité décroissante.
 
 ## ⚠️ Pièges
 
-| Symptôme                                                                            | Cause                                                                                                  | Correction                                                                                 |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                          | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                           |
-| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles        | déclarer le module ; vérifier que Redis répond                                             |
-| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal       | poser un namespace explicite et distinct par environnement                                 |
-| Le démarrage échoue avec `clé inconnue : …`                                         | clé absente du schéma strict (faute de frappe, ou clé retirée)                                         | corriger ou retirer la clé que nomme le message                                            |
-| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                         | cette clé ne pilote que le **comptage** de la sonde                                                    | régler `websocketSecure.maxBackpressure` / `.backpressureCloseAfterDrops` (@nodefony/http) |
-| Toutes les connexions tombent en `4003` après activation du contrôle d'origine      | `allowList` vide, ou origine non identique au caractère près (port, schéma, sous-domaine)              | inscrire l'origine exacte ; un client non-navigateur relève de `allowMissingOrigin`        |
-| `enabled: false` posé « pour désactiver », et la garde d'origine ne s'applique plus | le service devient inerte et ne pose plus les politiques sur le hub                                    | retirer le module du manifeste plutôt que l'éteindre                                       |
-| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts#RealtimeHub`) | vérifier le motif de refus `realtime:denied` côté client                                   |
+| Symptôme                                                                            | Cause                                                                                                  | Correction                                                                                                                            |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                          | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                                                                      |
+| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles        | déclarer le module ; vérifier que Redis répond                                                                                        |
+| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal       | poser un namespace explicite et distinct par environnement                                                                            |
+| Le démarrage échoue avec `clé inconnue : …`                                         | clé absente du schéma strict (faute de frappe, ou clé retirée)                                         | corriger ou retirer la clé que nomme le message                                                                                       |
+| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                         | cette clé ne pilote que le **comptage** de la sonde                                                    | régler `websocketSecure.maxBackpressure` / `.backpressureCloseAfterDrops` (@nodefony/http)                                            |
+| Toutes les connexions tombent en `4003` après activation du contrôle d'origine      | `allowList` vide, ou origine non identique au caractère près (port, schéma, sous-domaine)              | inscrire l'origine exacte ; un client non-navigateur relève de `allowMissingOrigin`                                                   |
+| `enabled: false` posé « pour désactiver », et la garde d'origine ne s'applique plus | le service devient inerte et ne pose plus les politiques sur le hub                                    | retirer le module du manifeste plutôt que l'éteindre                                                                                  |
+| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts#RealtimeHub`) | vérifier le motif de refus `realtime:denied` côté client                                                                              |
+| `codec: "cbor"` posé, et `onRealtimeBinary()` ne reçoit plus rien                   | sur une connexion CBOR, toute trame binaire est une frame du codec (ADR-0022 §2)                       | publier les octets dans un canal ; le flux brut ne sert que les connexions texte                                                      |
+| `codec: "cbor"` posé, et le navigateur reste en texte                               | le client n'a pas offert le codec : `codec: CBOR_FRAME_CODEC` absent, ou passé après la 1ʳᵉ création   | l'offrir à la PREMIÈRE création de la socket ([client](../../../../nodefony/docs/client.md#choisir-le-codec-de-trame--texte-ou-cbor)) |
 
 ## 🧪 Tests & couverture