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

package/docs/byte-stream.md

@@ -0,0 +1,371 @@
+---
+title: "Flux d'octets — servir la sortie d'un processus, un relais ou une archive à la volée"
+navTitle: Flux d'octets
+lang: fr
+module: "@nodefony/http"
+topic: byte-stream
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    streaming,
+    flux,
+    renderstream,
+    openstream,
+    ffmpeg,
+    relais,
+    fetch,
+    http2,
+    contre-pression,
+  ]
+version: "doc"
+status: stable
+updated: 2026-11-06
+source: "src/packages/@nodefony/http/docs/byte-stream.md"
+coverageModule: http
+coverageFiles: context/http/ByteStream.ts,context/http/StreamLifecycle.ts
+---
+
+📍 [Documentation](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Flux d'octets**
+
+# Flux d'octets — servir la sortie d'un processus, un relais ou une archive à la volée
+
+> Un **robinet** plutôt qu'une **bouteille** : la réponse ne se prépare pas en entier avant de
+> partir, elle coule pendant que la source produit. La vidéo ré-emballée par ffmpeg, le corps d'un
+> `fetch()` relayé depuis une caméra, une archive construite à la volée : toute source d'octets qui
+> n'est pas un fichier du disque. Un `<video src>`, un `fetch()`, un téléchargement ou `curl` la
+> lisent comme n'importe quelle réponse HTTP. Le même code sert HTTP/1.1, HTTP/2 chiffré et h2c.
+> Chaque fait ci-dessous est ancré sur le code.
+
+## 🧠 Le modèle mental — la réponse est PRISE à l'appel, les en-têtes partent au premier octet
+
+`this.renderStream(source)` dit au framework : « cette requête, c'est moi qui la sers, avec ce flux ».
+Dès l'appel, plus rien ne peut répondre à sa place. Mais les **en-têtes ne partent qu'au premier
+morceau** de la source : tant que rien n'est sorti, une erreur de la source peut encore devenir une
+vraie page d'erreur (500, 502…), visible dans le journal d'accès — et non une réponse 200 tronquée.
+
+Le flux se termine pour l'une de cinq raisons, et la **source est toujours détruite** à la fin,
+quelle que soit la raison. C'est ce qui libère un processus fils bloqué en écriture : un simple
+`unpipe` le laisserait en pause, et ffmpeg ainsi bloqué ignore même `SIGTERM`.
+
+## 📖 Lexique
+
+- **Source** — ce qui produit les octets : un `Readable` Node (la sortie d'un processus, une archive)
+  ou un `ReadableStream` web (le `body` d'un `fetch()`).
+- **Contre-pression** — quand le client lit moins vite que la source produit, la source est mise en
+  pause jusqu'à ce que le client rattrape : la mémoire du serveur reste bornée.
+- **Source muette** — une source qui ne produit plus rien (processus figé, amont qui ne répond plus).
+- **Coupure** — la fin d'une réponse sans fin propre : le client SAIT que le corps est tronqué
+  (socket fermée en HTTP/1.1, `RST_STREAM` en HTTP/2).
+
+## Quand un flux d'octets, quand autre chose ?
+
+| Besoin                                                      | Choisir                                                     |
+| ----------------------------------------------------------- | ----------------------------------------------------------- |
+| Un fichier du disque, avec reprise (`Range`)                | `this.renderMediaStream()` / `this.renderFileDownload()`    |
+| La sortie d'un processus, un relais, une archive construite | **`this.renderStream()`** — cette page                      |
+| Des événements texte lus par `EventSource`                  | [`this.renderSse()`](sse.md)                                |
+| UNE source diffusée à N lecteurs (un producteur par pod)    | un canal temps réel (`@nodefony/realtime`), pas une réponse |
+
+`renderStream` sert **une réponse par consommateur** : dix spectateurs, dix flux, dix producteurs.
+
+## 🚀 Démarrage rapide
+
+Dans une application générée par `nodefony create app`, une action sert la sortie d'un processus.
+
+### 1. L'action
+
+```ts
+// modules/app/nodefony/controller/ExportController.ts
+import { spawn } from "node:child_process";
+import { Controller, controller, route } from "@nodefony/framework";
+import type { Context } from "@nodefony/http";
+
+@controller("/export")
+class ExportController extends Controller {
+  constructor(context: Context) {
+    super("ExportController", context);
+  }
+
+  @route("export-logs", { path: "/logs" })
+  async logs() {
+    const tar = spawn("tar", ["-cz", "-C", "var", "logs"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    try {
+      const { reason, bytes } = await this.renderStream(tar.stdout, {
+        headers: {
+          "content-type": "application/gzip",
+          "content-disposition": 'attachment; filename="logs.tar.gz"',
+        },
+      });
+      this.log(`export terminé : ${reason}, ${bytes} octets`, "INFO");
+    } finally {
+      tar.kill("SIGKILL"); // le flux est fini, quelle qu'en soit la raison
+    }
+  }
+}
+
+export default ExportController;
+```
+
+### 2. Observer
+
+```bash
+curl -sS -o logs.tar.gz -D - http://127.0.0.1:5151/export/logs
+```
+
+```text
+HTTP/1.1 200 OK
+content-type: application/gzip
+cache-control: no-cache, no-transform
+x-accel-buffering: no
+transfer-encoding: chunked
+```
+
+- Aucun `Content-Length` n'est connu : HTTP/1.1 envoie par morceaux, HTTP/2 n'annonce rien.
+- `Cache-Control: no-cache, no-transform` et `X-Accel-Buffering: no` sont posés **s'ils manquent** —
+  ni dans `headers`, ni déjà sur la réponse : un proxy inverse ne met pas le flux en tampon, et ne le
+  recompresse pas. Pour une source FINIE et rejouable (fichier, archive), `live: false` les retire.
+- Couper `curl` en route : la promesse rend `reason: "client"`, la source est détruite, `tar` reçoit
+  `EPIPE` et s'arrête.
+
+## ⚙️ L'API
+
+### `this.renderStream(source, options?)` — et `context.openStream()`
+
+`Controller.renderStream()` (`Controller.ts#Controller.renderStream`) n'est que l'habillage de
+`HttpContext.openStream()` (`HttpContext.ts#HttpContext.openStream`), comme `renderSse` l'est de
+`openSse`. Un middleware ou un relais qui n'a pas de contrôleur appelle `context.openStream()`
+directement — la requête est alors répondue : ne pas appeler la suite.
+
+| Paramètre | Type                                       | Rôle                                                             |
+| --------- | ------------------------------------------ | ---------------------------------------------------------------- |
+| `source`  | `Readable` ou `ReadableStream<Uint8Array>` | ce qui produit les octets ; jamais en mode objet (`TypeError`)   |
+| `options` | `IByteStreamOptions`                       | statut, en-têtes, délais, écouteur de fin (tableau suivant)      |
+| rend      | `Promise<IByteStreamResult>`               | `{ reason, bytes }` à la fin — la promesse ne rejette **jamais** |
+
+**La source appartient au flux dès l'appel.** Un appel qui LÈVE — réponse déjà prise (500), plafond
+par IP atteint (429), option hors bornes (`RangeError`), source en mode objet (`TypeError`) —
+détruit la source avant de lever (un flux web est annulé) : un relais `fetch` refusé ne garde pas sa
+connexion amont, un producteur enfant ne reste pas bloqué en écriture.
+
+| Option         | Rôle                                                                                                      | Défaut                                   |
+| -------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `status`       | statut de la réponse, 200 à 599                                                                           | 200                                      |
+| `headers`      | en-têtes, écrits au premier morceau ; `Content-Length` repris s'il est fourni, et TENU (ci-dessous)       | `Content-Type: application/octet-stream` |
+| `live`         | flux vivant : `no-cache` et `X-Accel-Buffering: no` par défaut ; `false` pour un fichier, une archive     | `true`                                   |
+| `idleTimeout`  | délai maximal sans un octet de la source, ms ; `0` le désarme ; coupure entre 1 et 1,25 × ce délai        | délai de réponse du serveur (30 s)       |
+| `stallTimeout` | délai maximal d'une écriture bloquée (le client ne lit plus), ms ; `false` l'éteint                       | 30 000                                   |
+| `maxDuration`  | durée de vie du flux, ms ; il est fermé ensuite                                                           | `false` — pas de borne                   |
+| `onClose`      | `(reason) => void`, appelé une fois, AVANT la fin de la requête et la résolution ; lié à la requête (ALS) | aucun                                    |
+
+**`Content-Length` est tenu.** Annoncé — dans `headers` ou déjà posé sur la réponse —, le corps
+fait exactement cette longueur (RFC 9112 §6.3 ; en HTTP/2, RFC 9113 §8.1.1 : sinon la réponse est
+malformée). Contredit dès le premier morceau : rien n'est parti, page d'erreur 500. Après : coupure,
+jamais une fin propre — un client HTTP/1.1 attendrait sinon l'octet manquant, ou lirait l'excédent
+comme le début de la réponse suivante. `HEAD` excepté : la longueur annoncée y est celle du GET.
+
+Les raisons de fin (`ByteStreamEndReason`, `ByteStream.ts#ByteStreamEndReason`) :
+
+| `reason`  | Ce qui s'est passé                                                             | Ce que voit le client     |
+| --------- | ------------------------------------------------------------------------------ | ------------------------- |
+| `end`     | la source est finie, ou le serveur a fermé le flux (`maxDuration`, révocation) | une fin propre            |
+| `client`  | le client est parti                                                            | —                         |
+| `error`   | la source a échoué                                                             | page d'erreur, ou coupure |
+| `timeout` | la source est restée muette plus de `idleTimeout`                              | 504, ou coupure           |
+| `stall`   | le client ne lisait plus depuis `stallTimeout`                                 | connexion coupée          |
+
+L'union **peut s'agrandir** : un `switch` exhaustif sur `reason` garde une branche `default`.
+
+### Relayer un autre service
+
+```ts
+@route("camera-live", { path: "/camera" })
+async camera() {
+  const r = await fetch("http://camera.local/stream", { signal: this.context.signal });
+  if (!r.ok || r.body === null) throw new HttpError("Caméra injoignable", 502);
+  return this.renderStream(r.body, {
+    headers: { "content-type": r.headers.get("content-type") ?? "application/octet-stream" },
+  });
+}
+```
+
+- Le **signal** est lu AVANT l'appel : au départ du client, le flux l'interrompt, et `fetch` ferme
+  la connexion amont (`Context._abortIfPending()`, appelé par la fin du flux).
+- Ne recopier que `content-type` : `fetch` a déjà décompressé le corps, donc `content-encoding` et
+  `content-length` de l'amont seraient faux.
+- Une erreur levée **avant** l'appel (le `throw` ci-dessus) appartient à l'action : chemin d'erreur
+  ordinaire.
+
+### `Readable.from()` — passer `{ objectMode: false }`
+
+`Readable.from([...])` crée un flux en **mode objet** par défaut, qui ne porte pas d'octets :
+`renderStream` le refuse par un `TypeError` qui donne le correctif.
+
+```ts
+return this.renderStream(Readable.from([header, body], { objectMode: false }));
+```
+
+### Même source, deux sorties — HTTP et ligne de commande
+
+`renderStream` exige une **réponse HTTP vivante** : une commande CLI n'en a pas, et n'y a donc pas
+accès. Ce que les deux partagent, c'est la **source**. On écrit le producteur une fois, puis la route
+le sert par `renderStream` et la commande le verse sur sa sortie par `pipeline` de `node:stream`, qui
+apporte la même contre-pression et détruit la source en cas d'erreur (un `| head` qui ferme tôt
+compris).
+
+```ts
+// modules/app/nodefony/src/exportLogs.ts — le producteur, écrit une fois
+import { spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+
+export function exportLogs(): ChildProcessByStdio<null, Readable, null> {
+  return spawn("tar", ["-cz", "-C", "var", "logs"], {
+    stdio: ["ignore", "pipe", "ignore"],
+    windowsHide: true,
+  });
+}
+```
+
+```ts
+// la route — GET /export/logs
+const tar = exportLogs();
+try {
+  await this.renderStream(tar.stdout, {
+    headers: { "content-type": "application/gzip" },
+  });
+} finally {
+  tar.kill("SIGKILL");
+}
+```
+
+```ts
+// la commande — nodefony app:export > logs.tar.gz
+import { pipeline } from "node:stream/promises";
+
+override async generate(): Promise<this> {
+  const tar = exportLogs();
+  try {
+    await pipeline(tar.stdout, process.stdout);
+  } finally {
+    tar.kill("SIGKILL");
+  }
+  return this;
+}
+```
+
+Une commande de module s'accompagne d'un endpoint équivalent : c'est ce patron qui le rend gratuit.
+Pour LIRE un flux d'octets, aucun client dédié n'est nécessaire — c'est une réponse HTTP
+ordinaire : `curl -N`, `wget`, `fetch()` ou `| tar xz` le consomment tels quels.
+
+## 🏗️ Architecture interne — ce que fait l'appel
+
+Le flux d'octets repose sur la **brique de cycle de vie commune au SSE**
+(`StreamLifecycle.ts#openStreamLifecycle`, non exportée) — une seule implémentation de la prise de
+la réponse, de la session, de la fermeture et des gardes, jouée par la même table de parité sur les
+deux types de flux.
+
+1. **Les options sont contrôlées** et la source web convertie (`ByteStream.ts#fromWebStream`) — sa
+   destruction ANNULE le flux web, c'est elle qui ferme l'amont d'un `fetch`.
+2. **La réponse est prise** (`context.sended`), le transport constaté, l'écoute de la fermeture posée
+   AVANT toute attente, la place du plafond par IP réservée, puis la session sauvée.
+3. **Le délai d'inactivité de la requête est désarmé** : sous une réponse prise, il ne fermait rien et
+   faussait le statut journalisé. Le flux tient son propre chien de garde — UN minuteur périodique
+   `unref` par flux, qui passe tous les quarts de `idleTimeout` et compare le compteur d'octets.
+   Aucun minuteur ni appel d'horloge par morceau : la coupure tombe entre `idleTimeout` et
+   1,25 × `idleTimeout`.
+4. **HEAD** : les en-têtes du GET, aucun corps, la source n'est jamais lue (toute route GET sert HEAD).
+5. **Au premier morceau** : les en-têtes, puis le morceau. Sous contre-pression, la source est mise en
+   pause et le minuteur `stallTimeout` armé ; il est désarmé au `drain`.
+6. **La fin passe par un seul nettoyage** (`ByteStream.ts#openByteStream`, puis
+   `StreamLifecycle.ts#StreamLifecycle.finish`) : source **détruite en premier**, écouteurs retirés,
+   minuteurs arrêtés, signal de la requête interrompu (sauf fin propre), `onClose(reason)`, fin de la
+   requête, puis résolution de la promesse.
+
+**Une erreur de la source**, selon le moment :
+
+| Moment                                    | Traitement                                                                                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| avant l'appel                             | elle appartient à l'action : chemin d'erreur ordinaire                                                        |
+| avant le premier octet (rien n'est parti) | la réponse est ROUVERTE et l'erreur confiée à `HttpKernel.onError` — même statut, même page qu'une action     |
+| après le premier octet                    | **coupure** : `destroy()` en HTTP/1.1, `RST_STREAM(INTERNAL_ERROR)` en HTTP/2 ; une entrée `ERROR` au journal |
+
+**Le journal d'accès dit qui a coupé.** Après le premier octet, le statut parti sur le fil est 200 ;
+le statut de la ligne d'accès, lui, est un fait INTERNE : **500** (ou le code d'une `HttpError`) quand
+la source échoue, **504** quand elle se tait, **499** quand le client part. Sans lui, le noyau
+journaliserait 499 (« client parti ») pour une coupure décidée par le serveur
+(`HttpKernel.createHttpContext`).
+
+En HTTP/2, la coupure passe par `stream.destroy(err)` et non `stream.close(INTERNAL_ERROR)` : ce
+dernier ferme d'abord le côté écriture, et un client qui a déjà fermé le sien lit une **fin propre**
+(mesuré : `rstCode` 0 au lieu de 2).
+
+## 📈 Coût mesuré
+
+Banc isolé (serveur Node seul, client `curl`, 256 Mo par passage, médiane de 21 passes alternées,
+deux campagnes) : `renderStream` face au plancher `source.pipe(res)` écrit à la main.
+
+| Morceaux | Débit           | CPU du serveur  |
+| -------- | --------------- | --------------- |
+| 64 Kio   | −1,7 % / −2,0 % | +1,6 % / +1,1 % |
+| 4 Kio    | −2,4 % / −0,2 % | +2,5 % / +0,1 % |
+
+Un fichier servi par `streamFile()` (`live: false`, longueur tenue) face à
+`createReadStream().pipe(res)`, même banc : débit +1,4 %, CPU +2,3 % — dans le bruit, lui aussi.
+
+Les écarts restent dans le bruit du banc. Deux choix les tiennent là : un écouteur `drain`
+**permanent** (un `once` par épisode de contre-pression coûtait un enrobage par morceau, presque
+chaque écriture de 64 Kio rendant `false` sur une socket rapide), et un minuteur de blocage
+(`stallTimeout`) créé une fois puis réarmé au reste du délai, jamais un par épisode. La trace de
+désoptimisation de V8 (`--trace-deopt`) ne cite pas `ByteStream`.
+
+## 🔐 Sécurité
+
+- **Les mêmes gardes qu'une socket WebSocket et qu'un flux SSE** : le flux compte dans
+  `wsMaxConnectionsPerIp` (un seul budget, **429** avant d'écrire quoi que ce soit — désactivé par
+  défaut), se coupe quand l'identité qui l'a ouvert est révoquée, et respecte `maxDuration`. Le
+  plafond est PAR POD, et dépend de `trustProxy` pour lire la vraie IP derrière un proxy.
+- **En-tête refusé** (fin de ligne dans une valeur) : il ne part qu'au premier morceau, depuis la
+  source — l'échec rend une page 500 ordinaire, sans en-tête injecté, et ne peut pas abattre le
+  processus.
+- **`Range` est ignoré** : la réponse est un 200, et `Accept-Ranges` n'est jamais posé (RFC 9110
+  §14.2) — un flux construit à la volée ne sait pas reprendre au milieu.
+- Le flux passe par le pipeline complet : pare-feu, CSRF et `@IsGranted` s'appliquent avant l'action.
+
+## ⚠️ Pièges (symptôme → cause → correction)
+
+| Symptôme                                              | Cause                                                                                  | Correction                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `TypeError : une source en mode objet`                | `Readable.from([...])` est en mode objet par défaut                                    | `Readable.from(chunks, { objectMode: false })`                             |
+| Un processus fils survit à un crash du processus Node | la destruction de la source n'a jamais eu lieu : le processus Node est mort avant      | supervision de l'application (cgroup, `detached: false`, `kill` au signal) |
+| Coupé au bout de 30 s alors que la source est lente   | `idleTimeout` (défaut 30 s) : la source n'a rien produit pendant ce délai              | relever `idleTimeout`, ou `0` pour une source légitimement silencieuse     |
+| Coupé derrière nginx au bout de 60 s                  | `proxy_read_timeout` (60 s) plus court que le silence de la source                     | garder `idleTimeout` SOUS ce délai, ou l'allonger sur le proxy             |
+| Le flux répond 429 sans avoir rien fait               | `wsMaxConnectionsPerIp` atteint — sockets, flux SSE et flux d'octets comptent ensemble | relever le plafond, ou fermer les connexions laissées ouvertes             |
+| `content-encoding` faux sur un relais                 | en-têtes de l'amont recopiés, alors que `fetch` a décompressé                          | ne recopier que `content-type`                                             |
+
+## 🧪 Tests & couverture
+
+| Type                   | Où                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Parité du cycle de vie | `http/streamLifecycle.test.ts` — la MÊME table jouée sur le SSE et le flux d'octets : réponse prise, départ du client en HTTP/1.1, HTTP/2 et h2c, fin propre, session, double ouverture, client lent, durée de vie                                                                                                                                                                                     |
+| Parité — unitaire      | `unit/streamLifecycleParity.test.ts` — client parti PENDANT la sauvegarde de session : flux né fermé, source détruite                                                                                                                                                                                                                                                                                  |
+| Intégration            | `http/byteStream.test.ts` — HEAD (3 transports), coupure après le premier octet (3 transports), 500 / 502 avant, source muette 504 et coupure, `idleTimeout: 0`, source déjà finie, en-tête refusé, producteur bloqué libéré, relais `fetch` ; anneau du journal relu (une seule `ERROR`, aucun « onError on closed context », statut de la ligne d'accès) ; session sauvée deux fois, écrite une fois |
+| Délais réels           | même fichier, derrière `NF_RUN_LONG_STREAM=1` (~80 s) — défaut d'`idleTimeout` (coupure entre 30 et 37,5 s, 504 au journal) et `idleTimeout: 0` tenu 40 s, au-delà du délai de socket du serveur                                                                                                                                                                                                       |
+| Gardes                 | `http/sse-guards.attack.test.ts` — plafond par IP (429, place rendue, source refusée détruite), anonyme refusé (401) et révocation, joués sur le SSE ET le flux d'octets                                                                                                                                                                                                                               |
+| Refus — unitaire       | `unit/byteStreamRefusal.test.ts` — un appel qui lève (500, 429, `RangeError`, `TypeError`) détruit la source, annule un flux web                                                                                                                                                                                                                                                                       |
+| Mémoire                | `http/memory.test.ts` — flux finis par leur source et flux abandonnés par le client : pente du tas, scopes et contextes résiduels                                                                                                                                                                                                                                                                      |
+
+Le cas du **producteur bloqué** lance un enfant `node -e` qui écrit sans fin par `fs.writeSync(1, …)`
+— une écriture bloquante, comme ffmpeg — et vérifie qu'il sort en moins de 5 s après le départ du
+client, **sans aucun `kill`** : seule la destruction de sa sortie le libère.
+
+L'avertissement « réponse non envoyée » ne peut pas tomber après un `renderStream` : l'action rend
+la promesse du résultat, un objet. Le banc qui relit le journal le garde comme filet, sans pouvoir le
+faire rougir sur ce chemin.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/http — vue du module](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Flux SSE](sse.md) — événements texte, même cycle de vie ; [Serveurs](servers.md) — HTTP/2, TLS, délais ; [Proxy inverse](reverse-proxy.md).

package/docs/cookies.md

@@ -242,7 +242,13 @@ constructeur de `Cookie` (`cookie.ts#Cookie.options`).
 ### Sérialiser : `serialize()` et `serializeWebSocket()`
 
 - `serialize()` (`cookie.ts#Cookie.serialize`) produit la **ligne `Set-Cookie`** complète (attributs dans l'ordre,
-  préfixes forcés, `Max-Age` seulement s'il est positif).
+  préfixes forcés). `Max-Age` est en **secondes entières**, arrondi vers le bas, et absent sous une
+  seconde (`cookie.ts#Cookie.getMaxAge`) : la grammaire de la RFC 6265 (§4.1.1) n'admet ni décimale
+  ni zéro, et un navigateur ignore un `Max-Age=3599.874` — le cookie deviendrait un cookie de session.
+- Le **nom**, le `Path` et le `Domain` sont vérifiés à la **pose** (`addCookie()`), par la grammaire
+  de la bibliothèque `cookie` (`cookie.ts#Cookie.assertGrammar`) : un nom porteur de `;` ou un
+  `Path` comme `/; Domain=evil.example`, qui injecterait un attribut, lève une `TypeError` à l'appel
+  plutôt qu'un en-tête faux au `writeHead`.
 - `serializeWebSocket()` (`cookie.ts#Cookie.serializeWebSocket`) produit un **objet** `IWsCookie` (mêmes invariants de sécurité)
   — utilisé quand un cookie doit être décrit hors en-tête HTTP.
 - `toString()` (`cookie.ts#Cookie.toString`) ne rend que `nom=valeurEncodée` (sans attributs).
@@ -270,11 +276,15 @@ boucle de `setHeader` (qui écraserait tout sauf le dernier). Pour expirer un co
 
 ### Parsing des cookies entrants
 
-`cookiesParser(context)` (`cookie.ts#cookiesParser`) lit l'en-tête `Cookie:` (via la bibliothèque `cookie`,
-`parser()` `cookie.ts#parser`), crée un `Cookie` par entrée et l'ajoute au contexte avec `addRequestCookie()`
+`cookiesParser(context)` (`cookie.ts#cookiesParser`) lit l'en-tête `Cookie:` (via la bibliothèque `cookie`),
+crée un `Cookie` par entrée et l'ajoute au contexte avec `addRequestCookie()`
 (`Context.ts#Context.addRequestCookie`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
 l'initialisation du contexte HTTP (`HttpContext.ts#HttpContext.constructor`) **et** WebSocket (`WebsocketContext.ts#WebsocketContext.constructor`).
 
+C'est le **seul lecteur** de l'en-tête `Cookie` : le pare-feu lui-même lit le jeton CSRF sur le contexte.
+Chaque valeur est décodée **une fois**, et une séquence `%` invalide est gardée telle quelle au lieu de
+lever (`a=50%25` donne `50%`). Un nom présent deux fois : la **première** occurrence gagne.
+
 ### Côté WebSocket — lecture oui, écriture non
 
 Les cookies **entrants** sont lus au handshake, exactement comme en HTTP (même parseur). Mais la **poignée

package/docs/index.md

@@ -68,6 +68,8 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
 | [Rate-limit](rate-limit.md) | plafonner le débit par client (429) | protéger une API d'un flood ou d'un abus |
 | [Observabilité](observabilite.md) | tracer et journaliser chaque requête | débugger en prod, corréler des logs |
 | [Canal de diagnostic](diagnostics-channel.md) | publier le cycle de chaque requête à un outil de traçage, sans monkey-patch | brancher OpenTelemetry, Datadog ou Sentry |
+| [Flux SSE](sse.md) | pousser des événements texte au navigateur sur une réponse qui ne finit pas | progression d'une tâche, réponse d'un modèle mot à mot, journal en direct |
+| [Flux d'octets](byte-stream.md) | servir la sortie d'un processus, un relais `fetch` ou une archive à la volée | ffmpeg vers un `<video>`, caméra relayée, export `tar` |
 | [Proxy inverse](reverse-proxy.md) | relayer un préfixe d'URL vers un autre serveur, sur la même origine | servir Vite en dev, adosser un service interne sans CORS |
 | [Pipeline de requête](../../../../../docs/architecture/pipeline-requete.md) | l'ordre exact des étapes, HTTP comme WS | tu débugges « pourquoi ça passe / ça bloque ici » |
 
@@ -94,6 +96,12 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
   { "icon": "📡", "title": "diagnostics-channel", "href": "diagnostics-channel.md",
     "desc": "Le TracingChannel nodefony.http.request : chaque requête HTTP et chaque handshake WebSocket publiés avec route, gabarit, module, requestId, statut réel et durée. Zéro coût sans abonné ; correspondance avec les attributs OpenTelemetry.",
     "meta": "brancher un APM sans patcher le framework" },
+  { "icon": "📻", "title": "sse", "href": "sse.md",
+    "desc": "Le flux text/event-stream : this.renderSse(), send/comment/retry/close, négociation JSON ou flux sur la même route, client NodefonySse, et les gardes d'une connexion longue (plafond par IP, révocation, lecteur bloqué).",
+    "meta": "le serveur parle, le navigateur écoute" },
+  { "icon": "🚰", "title": "byte-stream", "href": "byte-stream.md",
+    "desc": "Répondre par une source d'octets qui n'est pas un fichier : this.renderStream() sur un Readable ou un fetch().body, en-têtes au premier octet (une erreur précoce reste une vraie page 5xx), source détruite à la fin, chien de garde d'une source muette, mêmes gardes que le SSE.",
+    "meta": "un robinet, pas une bouteille" },
   { "icon": "↪️", "title": "reverse-proxy", "href": "reverse-proxy.md",
     "desc": "Relayer un préfixe d'URL vers un autre serveur sans quitter l'origine de la page : HTTP et WebSocket, en-têtes de connexion jamais transmis, X-Forwarded-* et Via posés, barrière d'hôte appliquée avant le relais. C'est par lui que Vite est servi en développement.",
     "meta": "une origine, un certificat — pas de CORS ni de contenu mixte" },

package/docs/reverse-proxy.md

@@ -140,8 +140,11 @@ Ce qui s'applique malgré tout, parce que posé à l'entrée, avant l'aiguillage
 - les **quotas** : le rate-limit par IP compte les requêtes relayées, et un upgrade WebSocket relayé
   obéit aux mêmes bornes qu'un upgrade servi (voir [WebSocket relayé](#-websocket-relayé)).
 
-La CSP à nonce de l'application, elle, n'est jamais imposée : elle casserait les pages d'un autre
-serveur, dont les scripts ne portent pas ce nonce.
+La CSP à nonce de l'application n'est jamais imposée à un préfixe relayé : elle casserait les
+pages d'un autre serveur, dont les scripts ne portent pas ce nonce. Dans l'autre sens,
+`proxy:generate` ne pose **aucune** CSP dans la configuration nginx ou haproxy qu'il rend. Écrire
+la politique au frontal plutôt que dans l'application →
+[Poser la CSP au proxy](../../security/docs/headers.md#poser-la-csp-au-proxy-nginx-ingress).
 
 ## 🚀 Démarrage rapide
 
@@ -397,6 +400,7 @@ Ce que le relais fait aux en-têtes, dans les deux sens :
 | `X-Forwarded-Prefix` : à la suite de celui d'un pair `trustProxy`     |                                                                          |
 | `Forwarded` d'un pair `trustProxy` : prolongé de ce saut, jamais créé |                                                                          |
 | prolonge `Via` ; recalcule le cadrage du corps                        |                                                                          |
+| décrémente `Max-Forwards` sur `OPTIONS` et `TRACE`                    |                                                                          |
 
 Les échecs, dans l'ordre où ils peuvent survenir (`forwardRequest()`, `forward.ts#forwardRequest`) :
 
@@ -412,6 +416,13 @@ Les échecs, dans l'ordre où ils peuvent survenir (`forwardRequest()`, `forward
 - **coupure** — si l'amont tombe APRÈS avoir commencé à répondre, la réponse au client est
   interrompue : un statut ne se rattrape pas une fois envoyé.
 
+Une requête `OPTIONS` ou `TRACE` dont `Max-Forwards` vaut `0` n'atteint pas l'amont : le
+proxy y répond lui-même, en destinataire final (RFC 9110 §7.6.2). `OPTIONS` reçoit `200` avec
+`Allow` si le montage restreint ses `methods` ; `TRACE` reçoit la requête en `message/http`, sans
+les en-têtes qui portent un secret (`Cookie`, `Authorization`, jetons, clés). Au-dessus de `0`, la
+valeur part décrémentée, plafonnée à `MAX_VIA_HOPS` ; une valeur qui n'est pas un entier part
+retirée. Les autres méthodes la relaient telle quelle.
+
 Chaque montage a son **pool keep-alive dédié**, jamais l'agent global de Node : sous
 `NODE_USE_ENV_PROXY` (poste d'entreprise), l'agent global enverrait un amont local au proxy de
 l'entreprise (`ReverseProxy.agentFor()`, `reverse-proxy.ts#ReverseProxy.agentFor`). Les pools sont fermés à l'arrêt du
@@ -444,8 +455,9 @@ une connexion à usage unique, sans recréer de pool que personne ne fermerait.
 | RFC 9110 §7.6.1         | Un intermédiaire retire les en-têtes de connexion        | Liste fixe + jetons de `Connection`, dans les deux sens (`requestHeadersFor()`, `forward.ts#requestHeadersFor`) |
 | RFC 9110 §7.6.3         | Un intermédiaire ajoute son entrée à `Via`               | Pseudonyme par processus, prolongé à l'aller et au retour (`forward.ts#requestHeadersFor`)                      |
 | RFC 9112 §6.3           | Un seul cadrage de corps ; `Transfer-Encoding` l'emporte | `Content-Length` retiré quand le corps est découpé (`bodyFramingOf()`, `forward.ts#bodyFramingOf`)              |
-| RFC 9112 §6.1           | Codage de transfert non compris → 501                    | Tout autre que `chunked` seul est refusé, jamais réétiqueté (`forward.ts#viaEntry`)                             |
+| RFC 9112 §6.1           | Codage de transfert non compris → 501                    | Tout autre que `chunked` seul est refusé, jamais réétiqueté (`forward.ts#bodyFramingOf`)                        |
 | RFC 9113 §8.2.2         | Pas d'en-tête de connexion en HTTP/2                     | Réponse refusée par la sortie h2 → 502, jamais une exception non rattrapée                                      |
+| RFC 9110 §7.6.2         | `Max-Forwards` décrémenté ; à 0, répondre soi-même       | Sur `OPTIONS`/`TRACE` seulement (`receivedMaxForwards()`, `forward.ts#receivedMaxForwards`)                     |
 | RFC 7239 §8.1           | Ne croire `Forwarded` que d'un relais de confiance       | `trustProxy` décide (`ReverseProxy.forward()`, `reverse-proxy.ts#ReverseProxy.forward`)                         |
 | RFC 7239 §4 · §6        | Chaque relais ajoute son élément ; IPv6 entre crochets   | Élément `for=…;proto=…;host=…` ajouté, valeurs non-jeton entre guillemets                                       |
 | RFC 6585 §4             | `429 Too Many Requests`                                  | Quota par IP dépassé sur un upgrade relayé, avant le `101`                                                      |

package/docs/servers.md

@@ -22,7 +22,7 @@ tags:
   ]
 version: "doc"
 status: stable
-updated: 2026-07-19
+updated: 2026-10-30
 source: "src/packages/@nodefony/http/docs/servers.md"
 coverageModule: http
 coverageFiles: servers/server-http.ts,servers/server-https.ts,servers/server-websocket.ts,certificates.ts
@@ -552,22 +552,26 @@ Depuis `http2Schema` (`config.ts#http2Schema`), appliqué seulement si défini
 Depuis `websocketSchema` (`config.ts#websocketSchema`). Les deux sections partagent la forme et les défauts ; le WSS
 lit `websocketSecure` (`config.ts#httpConfigSchema`).
 
-| Option                   | Type                | Défaut  | Effet                                                                                    |
-| ------------------------ | ------------------- | ------- | ---------------------------------------------------------------------------------------- |
-| `keepaliveInterval`      | ms                  | `20000` | Intervalle des pings — détecte les connexions zombies.                                   |
-| `keepaliveGracePeriod`   | ms                  | `10000` | Délai de grâce après un ping sans réponse avant fermeture.                               |
-| `closeTimeout`           | ms                  | `5000`  | Délai de fermeture propre avant destruction de la socket.                                |
-| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts#websocketSchema`). |
-| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts#websocketSchema`).        |
-| `perMessageDeflate`      | bool \| objet       | `false` | Compression RFC 7692. Désactivée par défaut : coût CPU/RAM + risque de _zip bomb_.       |
-| `skipUTF8Validation`     | bool                | `false` | Désactive la validation UTF-8 des frames texte (RFC 6455 §8.1). À laisser `false`.       |
-| `autoPong`               | bool                | `true`  | Répond automatiquement aux pings entrants (RFC 6455 §5.5.2-3). À laisser `true`.         |
-| `allowSynchronousEvents` | bool                | `true`  | Émet plusieurs frames d'un même chunk réseau de façon synchrone (débit vs équité).       |
-| `maxBackpressure`        | octets              | `4 MiB` | Seuil du tampon d'envoi par connexion (client lent à recevoir) — anti-OOM.               |
-| `backpressurePolicy`     | `drop` \| `close`   | `drop`  | Au-delà du seuil : sauter la frame, ou fermer le client (close 1013).                    |
+| Option                        | Type                | Défaut  | Effet                                                                                    |
+| ----------------------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `keepaliveInterval`           | ms                  | `20000` | Intervalle des pings — détecte les connexions zombies.                                   |
+| `keepaliveGracePeriod`        | ms                  | `10000` | Délai de grâce après un ping sans réponse avant fermeture.                               |
+| `closeTimeout`                | ms                  | `5000`  | Délai de fermeture propre avant destruction de la socket.                                |
+| `maxPayload`                  | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts#websocketSchema`). |
+| `allowedOrigins`              | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts#websocketSchema`).        |
+| `perMessageDeflate`           | bool \| objet       | `false` | Compression RFC 7692. Désactivée par défaut : coût CPU/RAM + risque de _zip bomb_.       |
+| `skipUTF8Validation`          | bool                | `false` | Désactive la validation UTF-8 des frames texte (RFC 6455 §8.1). À laisser `false`.       |
+| `autoPong`                    | bool                | `true`  | Répond automatiquement aux pings entrants (RFC 6455 §5.5.2-3). À laisser `true`.         |
+| `allowSynchronousEvents`      | bool                | `true`  | Émet plusieurs frames d'un même chunk réseau de façon synchrone (débit vs équité).       |
+| `maxBackpressure`             | octets              | `4 MiB` | Seuil du tampon d'envoi par connexion (client lent à recevoir) — anti-OOM.               |
+| `backpressurePolicy`          | `drop` \| `close`   | `drop`  | Au-delà du seuil : sauter la frame, ou fermer le client (close 1013).                    |
+| `backpressureCloseAfterDrops` | frames              | `1000`  | Solde de frames refusées (+1 refus, −1 envoi) qui ferme en 1013 ; `0` = jamais.          |
+| `maxFramesPerSecond`          | trames / s          | `0`     | Trames REÇUES admises par connexion ; au-delà, écartées avant décodage. `0` = coupé.     |
+| `frameRateCloseAfterRejects`  | trames              | `1000`  | Solde de trames écartées (+1 écartée, −1 admise) qui ferme en 1008 ; `0` = jamais.       |
 
 > [!WARNING]
-> `keepalive*`, `closeTimeout`, `maxBackpressure` et `backpressurePolicy` sont des **réglages
+> `keepalive*`, `closeTimeout`, `maxBackpressure`, `backpressurePolicy`,
+> `backpressureCloseAfterDrops`, `maxFramesPerSecond` et `frameRateCloseAfterRejects` sont des **réglages
 > Nodefony**, pas des options de `ws` : la bibliothèque les ignore, c'est le framework qui les
 > implémente. À l'inverse, `server`, `noServer`, `clientTracking`, `host`, `port` et `backlog` sont
 > **gérés par Nodefony** et non exposés — les forcer n'aurait pas d'effet.
@@ -952,6 +956,13 @@ descripteur et du TLS, et couvre tous les pods. Ne l'activer que sur une machine
 l'OOM — un seul lent peut plomber une diffusion générale. La politique par défaut, `drop`, saute la
 frame et garde le client connecté.
 
+Dans l'autre sens, `maxFramesPerSecond` borne le **nombre** de trames qu'une connexion envoie
+(désactivé par défaut). Le compte se fait à l'arrivée de la trame brute
+(`wsFrameRate.ts#admitFrame`) : une trame écartée ne paie ni décodage ni routage, elle est
+comptée (`frameRateRejectedTotal()`, relayé par la sonde du hub temps réel) et la connexion reste
+ouverte — jusqu'à ce que le solde de refus atteigne `frameRateCloseAfterRejects`, qui ferme en
+**1008**. Seul un flux au-delà du double de la borne fait monter ce solde ; un pic passager non.
+
 ## ⚡ Performance & mémoire
 
 Le transport est du **chemin chaud absolu** : ce qui coûte ici est multiplié par le nombre de requêtes

package/docs/session.md

@@ -469,8 +469,8 @@ timer (`gcIntervalS: 0`).
 
 ## Entités de persistance
 
-**Drizzle (SQL).** La table est décrite une seule fois en spec logique (`SESSION_TABLE_SPEC`,
-`sessionEntity.ts#SESSION_TABLE_SPEC`) et déclinée par dialecte par `buildFrameworkTable()` (`colKit.ts#buildFrameworkTable`) — mêmes **noms** de
+**Drizzle (SQL).** La table est décrite une seule fois en spec logique (`SESSION_TABLE`,
+`sessionEntity.ts#SESSION_TABLE`) et déclinée par dialecte par `defineTable()` (`colKit.ts#defineTable`) — mêmes **noms** de
 colonnes partout, donc un store dialect-agnostique.
 
 | Colonne      | Type logique | SQLite              | PostgreSQL | MySQL / MariaDB | Rôle                             |
@@ -485,7 +485,7 @@ colonnes partout, donc un store dialect-agnostique.
 
 En MySQL/MariaDB, une colonne texte indexée devient `varchar` (un `TEXT` InnoDB n'est pas indexable
 sans préfixe) et le type JSON passe par un type compatible qui tolère MariaDB, laquelle stocke le JSON
-en `LONGTEXT` (`colKit.ts#mysqlColumn`).
+en `LONGTEXT` (`colKit.mysql.ts#buildMySqlTable`).
 
 **Mongoose (MongoDB).** Schéma équivalent (`@nodefony/mongoose/nodefony/entity/sessionEntity.ts#schema`) :
 `session_id` (String, index **unique**), `Attributes`/`flashBag`/`metaBag` (Object, défaut `{}`), `user`