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

package/docs/byte-stream.md

@@ -0,0 +1,406 @@
+---
+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
+
+**Le plus court : renvoyer la réponse de `fetch` telle quelle.** Une action qui renvoie une
+`Response` Web est envoyée en flux par `HttpContext.openWebResponse()`
+(`HttpContext.ts#HttpContext.openWebResponse`) — même tuyauterie que `openStream`, statut et
+en-têtes de l'amont compris :
+
+```ts
+@route("camera-live", { path: "/camera" })
+camera() {
+  return fetch("http://camera.local/stream", { signal: this.context.signal });
+}
+```
+
+Ce que ce geste court fait pour toi (`webResponse.ts#webResponseParts`) : il recopie le statut et les
+en-têtes de l'amont **sauf** `content-encoding` et `content-length` (le corps a déjà été décompressé
+par `fetch`), `set-cookie` (les cookies d'un tiers ne se posent pas sous ton domaine) et les en-têtes
+de connexion (RFC 9110 §7.6.1). Une `Response` que ton code CONSTRUIT (`new Response(…)`) garde, elle,
+tous ses en-têtes, cookies compris — `response.type` les distingue (`"default"` contre `"basic"`).
+
+**Le réglage fin : `renderStream`**, dès qu'il faut refuser un amont en erreur, choisir les en-têtes
+recopiés ou poser des délais :
+
+```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).
+   Pour ne pas lancer un producteur coûteux (ffmpeg) pour rien, passer une source VIDE en mode
+   octets : `Readable.from([])` seul est en mode objet, donc refusé (500).
+
+   ```ts
+   if (this.method === "HEAD") {
+     return this.renderStream(Readable.from([], { objectMode: false }), {
+       headers: { "content-type": "video/mp4" },
+     });
+   }
+   ```
+
+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` — ou `return fetch(…)`, qui les écarte                |
+| Requête pendue jusqu'au 408 sur `return new Response(…)` | framework antérieur à la reconnaissance de la `Response` Web                           | mettre à jour, ou `return this.renderStream(response.body, …)`                       |
+| Un cookie de l'amont n'arrive pas au navigateur          | `return fetch(…)` écarte le `set-cookie` d'une réponse RELAYÉE                         | le reposer soi-même, en connaissance de cause (`Response.ts#HttpResponse.setCookie`) |
+
+## 🧪 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    |
+| `Response` Web et flux nu renvoyés | `http/webResponse.test.ts` — `return new Response(…)` (statut, en-têtes, deux cookies, en-tête de connexion écarté), `Response.json`, réponse sans corps (204), `Response.error()` (502), `return fetch(…)` d'un amont gzip (encodage et cookies de l'amont écartés), `Readable` et `ReadableStream` nus, départ du client (source détruite / annulée) — chaque cas vu ROUGE (408) sans la reconnaissance |
+| 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/diagnostics-channel.md

@@ -167,6 +167,7 @@ seule pour l'abonné.
 | `statusCode` | fin     | statut rendu : celui de l'amont pour une requête relayée, `101` pour un handshake accepté, `null` si le client est parti |
 | `durationMs` | fin     | construction du contexte → dernier octet remis (fin du handshake en WebSocket) ; `null` si `timing.enabled: false`       |
 | `error`      | `error` | l'exception attrapée par le pipeline, `null` sinon                                                                       |
+| `rpc`        | fin     | appel RPC (gRPC, gRPC-Web, Connect) servi par la requête — `system`, `method`, `code`, `codeName` — ; `null` hors RPC    |
 
 Les champs « fin » valent `null` à `start` et `end` : c'est normal, la route et le statut ne sont
 pas encore connus. On les lit sur `asyncEnd`.
@@ -188,6 +189,43 @@ Pour qui écrit un plugin OTel, la table des attributs du span serveur (conventi
 Un **4xx sans exception** ne publie pas `error` : pour un span serveur, OTel demande de laisser le
 statut d'un 4xx non renseigné. C'est à l'abonné de classer un statut ; `statusCode` est là pour ça.
 
+### Un appel RPC — gRPC, gRPC-Web, Connect
+
+Un appel gRPC répond le plus souvent en HTTP 200 : son résultat voyage dans le trailer
+`grpc-status`. `statusCode` reste le statut HTTP, vrai sur le fil ; le résultat de l'appel est dans
+`rpc`, une COPIE de quatre champs, fixée au `close` de la réponse :
+
+| Champ      | Contenu                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------ |
+| `system`   | protocole parlé sur le fil : `grpc`, `grpc-web` ou `connect`                               |
+| `method`   | `paquet.Service/Méthode`, tiré de la route                                                 |
+| `code`     | code de l'appel (0 à 16) ; `null` si l'appel n'a jamais commencé (refusé par le transport) |
+| `codeName` | son nom (`OK`, `UNAVAILABLE`…), `null` avec lui                                            |
+
+Le code est celui que lit le client, à une course près : quand l'échéance du client expire, sa
+coupure et le minuteur du serveur se croisent, et le serveur publie 4 ou 1. Une réponse que le
+serveur n'a pas terminée vaut 1 `CANCELLED` — le client est parti, comme le statut 499 —, sauf une
+fin qu'il a lui-même posée (échéance 4, identité révoquée 16). Un refus de l'adaptateur avant le
+gestionnaire (message trop grand, encodage inconnu) porte son code. Une exception devient `error` :
+un appel en erreur publie UN `error`. Rien n'est publié par message d'un flux : un flux est un span,
+de l'ouverture au `close`.
+
+Correspondance avec les conventions RPC d'OpenTelemetry :
+
+| Attribut OTel              | Champ                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------- |
+| nom du span                | `rpc.method`                                                                                    |
+| `rpc.method`               | `rpc.method`                                                                                    |
+| `rpc.system.name`          | `grpc` (convention stable) ou `connectrpc` (convention en développement) — au choix de l'abonné |
+| `rpc.status_code`          | `rpc.codeName`                                                                                  |
+| `error.type`               | dérivé de `error`, sinon `rpc.codeName` pour un code d'erreur                                   |
+| `rpc.server.call.duration` | `durationMs / 1000` — même horloge que le span                                                  |
+
+Un code est une erreur du serveur — statut du span en erreur — pour 2, 4, 12, 13, 14 et 15 ; les
+autres codes non nuls sont des refus ou des échecs du client. La ligne d'accès suit la même règle
+pour sa gravité, et ajoute `RPC : <méthode> <NOM>` au statut HTTP. `traceparent` voyage dans les
+métadonnées gRPC, qui sont des en-têtes HTTP : la propagation W3C existante les lit.
+
 ## La séquence, sortie par sortie
 
 | Situation                               | Événements publiés                                    | `statusCode`         |
@@ -240,6 +278,9 @@ pas — ou on se désabonne (`channel.unsubscribe(subscribers)`).
 - **Conventions sémantiques HTTP d'OpenTelemetry** — `http.route` exige un gabarit de faible
   cardinalité, d'où `routePath` ; la durée de `http.server.request.duration` doit égaler celle du
   span serveur, d'où une seule horloge.
+- **Conventions sémantiques RPC d'OpenTelemetry** (`docs/rpc/rpc-spans.md`, `grpc.md`,
+  `connect-rpc.md`, `rpc-metrics.md`) — nom du span = `rpc.method`, jamais une valeur inventée ;
+  codes d'erreur du serveur gRPC (« SHOULD be considered errors ») ; durée sur l'horloge du span.
 
 ## Sécurité
 
@@ -261,11 +302,14 @@ Mesuré au micro-banc (Node 26, médiane de 7 passages) :
 | ----------------------------- | ------------------------------------------------------------------------------------- |
 | Personne n'écoute (le défaut) | une lecture de `hasSubscribers` (~1,6 ns), un champ `null` sur le contexte (8 octets) |
 | Un abonné                     | un objet de message, l'appel des abonnés, l'entrée dans les stores liés               |
+| Un appel RPC, avec un abonné  | une copie de quatre champs (`rpc`), à la fin — rien par message d'un flux             |
 
 `diagnostics_channel.hasSubscribers("nom")` coûterait ~41 ns : la garde lit donc le
 `TracingChannel` gardé en mémoire de module, jamais une recherche par nom. Le gate mémoire
 (`npm run test:memory`) est vert **sans** abonné et **avec** un abonné armé : le message ne retient
-ni contexte ni scope.
+ni contexte ni scope. Un abonné peut le garder après la fin de la requête : son `error` ne
+retient pas davantage la requête — une `HttpError` lit le contexte à sa construction et n'en garde
+aucune référence.
 
 ## Pièges
 

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`                                                      |