@nodefony/http 10.0.0-beta.2 → 10.0.0-beta.4

package/docs/sse.md

@@ -0,0 +1,287 @@
+---
+title: "Flux d'événements serveur (SSE) — pousser au navigateur sur une réponse qui ne finit pas"
+navTitle: Flux SSE
+lang: fr
+module: "@nodefony/http"
+topic: sse
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    sse,
+    server-sent-events,
+    event-stream,
+    eventsource,
+    streaming,
+    http2,
+    temps-réel,
+    mcp,
+    last-event-id,
+  ]
+version: "doc"
+status: stable
+updated: 2026-10-08
+source: "src/packages/@nodefony/http/docs/sse.md"
+coverageModule: http
+coverageFiles: context/http/SseStream.ts
+---
+
+📍 [Documentation](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Flux SSE**
+
+# Flux d'événements serveur (SSE) — pousser au navigateur sur une réponse qui ne finit pas
+
+> Une **radio** plutôt qu'un **téléphone** : le serveur parle, le navigateur écoute, et la
+> conversation ne va que dans un sens. Une action ouvre une réponse HTTP qu'elle ne referme pas, et y
+> écrit des événements au fil de l'eau — la progression d'une tâche, la réponse d'un modèle de
+> langage qui s'écrit mot à mot, une notification. Le même code sert HTTP/1.1 et HTTP/2. Chaque fait
+> ci-dessous est ancré sur le code.
+
+## 🧠 Le modèle mental — un FORMAT de réponse, pas une méthode
+
+SSE n'est pas une route d'un genre particulier : c'est ce que l'action **décide de répondre**. La
+route reste un `GET` ou un `POST` ordinaire ; à l'exécution, l'action appelle `this.renderSse()` au
+lieu de rendre un objet, et la réponse devient un flux `text/event-stream`. Un même `POST` peut donc
+répondre en JSON à un client classique et en flux à un client qui le demande par `Accept` — c'est
+ce que fait une porte MCP.
+
+## 📖 Lexique
+
+- **SSE** — _Server-Sent Events_ : le format `text/event-stream` normalisé par le standard HTML
+  (WHATWG §9.2). Il n'a pas de RFC.
+- **Événement** — un bloc de lignes `event:`, `id:`, `data:` clos par une ligne vide.
+- **`Last-Event-ID`** — l'en-tête qu'un client renvoie en se reconnectant, pour reprendre après le
+  dernier identifiant reçu.
+- **Battement de cœur** — un commentaire (`:`) envoyé à intervalle régulier : ignoré par le client,
+  il empêche un proxy de couper une connexion qu'il croirait muette.
+
+## Qu'est-ce qu'un flux SSE, et quand le préférer au WebSocket ?
+
+| Besoin                                                        | Choisir                                    |
+| ------------------------------------------------------------- | ------------------------------------------ |
+| Le serveur pousse, le client écoute (progression, journal)    | **SSE**                                    |
+| La réponse d'une requête arrive par morceaux (modèle, export) | **SSE** sur le `POST` de la requête        |
+| Un réseau d'entreprise bloque WebSocket                       | **SSE** — c'est une réponse HTTP ordinaire |
+| Échange dans les deux sens, canaux, temps réel partagé        | **WebSocket** (`NodefonySocket`)           |
+
+> [!NOTE]
+> En HTTP/1.1, un navigateur n'ouvre qu'environ six connexions par origine : six onglets chacun
+> abonné à un flux, et les requêtes suivantes attendent leur tour (WHATWG §9.2.7). En HTTP/2, un
+> flux SSE n'est qu'un flux du multiplexage de la connexion.
+>
+> Ce plafond vaut pour l'origine que **voit le navigateur**. Derrière nginx, HAProxy ou un
+> ingress qui termine le TLS, cette origine est le proxy : c'est **lui** qui doit servir HTTP/2,
+> et `proxy:generate` le pose déjà (`http2 on`, `generateProxyConfig.ts#nginxServerBlock`). Nodefony reçoit
+> alors du HTTP/1.1 (`proxy_http_version 1.1`, `generateProxyConfig.ts#nginxServerBlock`) — y activer HTTP/2
+> n'y change rien. Sans proxy, c'est Nodefony qui sert HTTP/2.
+>
+> De chaque côté du proxy, un flux est une connexion qui se tait entre deux événements. Le
+> battement (`SSE_HEARTBEAT_MS`, 15 s, `SseStream.ts#SSE_HEARTBEAT_MS`) la garde vivante ; le délai
+> d'inactivité généré (300 s au moins) en tient vingt. Le seul piège réel : une action qui éteint
+> le battement (`heartbeat: false`) et se tait plus longtemps que ce délai se fait couper par le
+> proxy. Le guide [reverse-proxy](../../../../../docs/guides/reverse-proxy.md) détaille le reste.
+
+## 🚀 Démarrage rapide
+
+Dans une application générée par `nodefony create app`, une action pousse trois étapes puis ferme.
+
+### 1. L'action
+
+```ts
+// modules/app/nodefony/controller/ProgressController.ts
+import { Controller, controller, route } from "@nodefony/framework";
+import type { Context } from "@nodefony/http";
+
+@controller("/progress")
+class ProgressController extends Controller {
+  constructor(context: Context) {
+    super("ProgressController", context);
+  }
+
+  @route("progress-run", { path: "/run" })
+  async run() {
+    const sse = await this.renderSse();
+    for (const step of ["lecture", "calcul", "écriture"]) {
+      await sse.send({ step }, { event: "step" });
+    }
+    return sse.close();
+  }
+}
+
+export default ProgressController;
+```
+
+### 2. Le client
+
+```ts
+// frontend — la classe se lit comme EventSource
+import { NodefonySse } from "nodefony/client";
+
+const sse = new NodefonySse("/progress/run");
+sse.addEventListener("step", (e) => {
+  console.log(JSON.parse((e as MessageEvent<string>).data));
+});
+sse.addEventListener("error", () => sse.close()); // fin du flux : ne pas reconnecter
+```
+
+### 3. Observer
+
+```bash
+curl -sN -H 'Accept: text/event-stream' http://127.0.0.1:5151/progress/run
+```
+
+```text
+event: step
+data: {"step":"lecture"}
+
+event: step
+data: {"step":"calcul"}
+
+event: step
+data: {"step":"écriture"}
+```
+
+- Les en-têtes partent dès `renderSse()` : `Content-Type: text/event-stream; charset=utf-8`,
+  `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no` (`openSseStream()`,
+  `SseStream.ts#openSseStream`). Ce dernier demande à un proxy de type nginx de ne pas garder le
+  flux en tampon. À travers le frontal que génère `nodefony proxy:generate nginx`, chaque
+  événement arrive à son émission — mesuré par le scénario `edge` du banc de publication. La même
+  mesure, en-tête retiré, reste étalée sur nginx 1.30 : l'en-tête n'y est pas ce qui tient le
+  flux, il protège les proxys qui retiennent.
+- `await sse.send()` freine l'action si le client lit lentement — c'est la contre-pression.
+
+## ⚙️ Les deux bouts de l'API
+
+### Côté serveur — `this.renderSse()` et l'objet `SseStream`
+
+| Membre                          | Rôle                                                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `this.renderSse(options?)`      | ouvre le flux (`Controller.renderSse()`, `Controller.ts#Controller.renderSse`) ; lève sur WebSocket               |
+| `this.acceptsSse()`             | le client a-t-il demandé `text/event-stream` ? (`Controller.acceptsSse()`, `Controller.ts#Controller.acceptsSse`) |
+| `sse.send(data, { event, id })` | un événement ; texte tel quel, objet en JSON (`SseStream.send()`, `SseStream.ts#SseStream.send`)                  |
+| `sse.comment(text)`             | un commentaire, ignoré par le client                                                                              |
+| `sse.retry(ms)`                 | impose le délai de reconnexion du client                                                                          |
+| `sse.onClose(fn)`               | appelé à la fermeture, quel que soit le bout qui ferme (`SseStream.onClose()`, `SseStream.ts#SseStream.onClose`)  |
+| `sse.close()`                   | termine la requête, idempotent (`SseStream.close()`, `SseStream.ts#SseStream.close`)                              |
+| `sse.closed`                    | le flux est-il fermé — à tester dans une boucle longue                                                            |
+
+Options de `renderSse()` :
+
+| Option          | Rôle                                                                                  | Défaut                            |
+| --------------- | ------------------------------------------------------------------------------------- | --------------------------------- |
+| `heartbeat`     | période du battement (commentaire `:`), ms ; `false` l'éteint                         | 15 000 (`SSE_HEARTBEAT_MS`)       |
+| `retry`         | délai `retry:` envoyé à l'ouverture                                                   | aucun                             |
+| `stallTimeout`  | délai maximal d'une écriture bloquée (le client ne lit plus) avant coupure ; `false`  | 30 000 (`SSE_STALL_TIMEOUT_MS`)   |
+| `maxEventBytes` | taille maximale d'un événement, octets UTF-8 ; au-delà `send()` lève une `RangeError` | 1 048 576 (`SSE_MAX_EVENT_BYTES`) |
+| `maxDuration`   | durée de vie du flux, ms ; il est fermé ensuite et `EventSource` se reconnecte        | `false` — pas de borne            |
+
+Un délai hors de 1 à 2^31-1 ms est refusé à l'ouverture (`RangeError`) : au-delà, Node ramène un
+minuteur à 1 ms.
+
+### Même route, deux réponses — la négociation
+
+```ts
+@route("tasks-run", { path: "/tasks", requirements: { methods: ["POST"] } })
+async runTask() {
+  if (!this.acceptsSse()) return { status: "accepted" }; // JSON
+  const sse = await this.renderSse();
+  await sse.send({ status: "running" });
+  return sse.close();
+}
+```
+
+`acceptsEventStream()` (`SseStream.ts#acceptsEventStream`) ne retient `text/event-stream` que **nommé** avec un
+poids non nul : `*/*` ne suffit pas — un client qui ne nomme pas le flux ne sait pas le lire —, et
+`q=0` est un refus (RFC 9110 §12.4.2).
+
+### Côté client — `NodefonySse`
+
+`NodefonySse` (`NodefonySse.ts#NodefonySse`) reprend le vocabulaire d'`EventSource` — `onopen`,
+`onmessage`, `onerror`, `addEventListener(type)`, `readyState`, `lastEventId`, `close()`,
+reconnexion avec `Last-Event-ID` — et ajoute ce que le natif refuse : `method`, `headers` (un
+`Authorization: Bearer`), `body`. Il est bâti sur `fetch`, donc tourne aussi sous Node, où
+`EventSource` reste expérimental.
+
+| Réponse du serveur                          | Ce que fait le client                                                               |
+| ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 200 `text/event-stream`                     | `OPEN`, événements                                                                  |
+| fin du flux, coupure réseau                 | `error`, puis reconnexion après le délai `retry:`, plus une gigue jusqu'à sa moitié |
+| aucune réponse dans `connectTimeout` (10 s) | `error`, puis reconnexion — jamais figé en `CONNECTING`                             |
+| autre statut (204 compris), autre type      | `error`, `CLOSED`, **sans** reconnexion (WHATWG §9.2.3)                             |
+| événement au-delà de `maxEventSize` (4 Mi)  | `CLOSED` sans reconnexion                                                           |
+
+L'analyseur du format est `SseParser` (`SseParser.ts#SseParser`), exporté par `nodefony/client` : c'est
+le même qui relit le flux dans les tests du serveur.
+
+## 🏗️ Architecture interne — ce que fait l'ouverture
+
+1. **La réponse est prise** (`context.sended`) : plus rien ne peut répondre à la place du flux.
+2. **La session est sauvée** s'il y en a une — ses cookies partent avec les en-têtes.
+3. **Le transport se constate** : flux HTTP/2, ou réponse HTTP/1.1 ; ni l'un ni l'autre → 500,
+   avant d'avoir rien écrit (`startSseStream()`, `SseStream.ts#startSseStream`).
+4. **Les en-têtes partent** — `respond()` en HTTP/2, `flushHeaders()` en HTTP/1.1 — et le délai
+   d'inactivité de la requête est **désarmé** : sans cela, le flux vivant prendrait un 408 au bout
+   de 30 s.
+5. **Le battement démarre** sur un minuteur `unref()`.
+
+La fin, quel que soit le bout qui ferme, passe par **un seul** nettoyage (`SseStream.ts#SseStream.send`) :
+minuteur arrêté, écouteurs `close` et `drain` retirés, attente de `drain` libérée, puis les
+écouteurs `onClose`.
+
+## 🔐 Sécurité
+
+- **Injection de flux** : `event` et `id` sont refusés s'ils contiennent CR, LF ou NUL
+  (`singleLine()`, `SseStream.ts#singleLine`) — une valeur venue d'un utilisateur ne peut pas clore
+  l'événement pour en forger un autre. Les `data` sur plusieurs lignes sont découpés en autant de
+  champs, jamais recopiés tels quels.
+- **Client** : un serveur qui n'envoie jamais de fin de ligne ferait grossir la mémoire du client
+  sans limite — `maxEventSize` (4 Mi par défaut) ferme la connexion.
+- Le flux passe par le pipeline complet : pare-feu, CSRF et `@IsGranted` s'appliquent avant
+  l'action, comme pour toute route.
+- **Les mêmes gardes qu'une socket WebSocket** — un attaquant prend le transport le plus faible :
+  - **plafond de connexions par IP** : `wsMaxConnectionsPerIp` compte les sockets WebSocket ET les
+    flux SSE, **un seul budget** (sinon N sockets plus N flux doubleraient le plafond). Au-delà, le
+    flux répond **429** avant d'écrire un octet de flux. Désactivé par défaut, comme pour le
+    WebSocket : en cloud, le plafond vit à l'ingress.
+  - **révocation** : un flux ouvert par une identité authentifiée est re-validé toutes les 30 s
+    (`REVOCATION_REVALIDATE_MS`) par la même règle que les sockets — session détruite ou passée à un
+    autre compte, jeton expiré ou annulé — et fermé si elle est morte. Une identité vivante ne
+    perd jamais son flux ; un anonyme n'est jamais re-validé.
+  - **lecteur bloqué** : le délai d'inactivité étant désarmé, `stallTimeout` le remplace — une
+    écriture qui attend un `drain` plus de 30 s coupe la connexion. Un client inactif mais qui lit
+    n'est jamais concerné : le minuteur ne s'arme que sous contre-pression.
+  - **taille d'un événement** : `maxEventBytes` refuse un événement démesuré avant de le mettre en
+    mémoire d'écriture ; le flux reste ouvert.
+
+## ⚠️ Pièges (symptôme → cause → correction)
+
+| Symptôme                                          | Cause                                                                                         | Correction                                                                    |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Le flux n'apparaît qu'en entier, à la fin         | un proxy (nginx) le met en tampon                                                             | `X-Accel-Buffering: no` est posé ; vérifier un `proxy_buffering on` explicite |
+| Le serveur ne voit jamais le client partir        | fermeture écoutée sur la REQUÊTE : en HTTP/1.1 elle a déjà émis `close` (corps lu, Node ≥ 16) | `sse.onClose()` — la fermeture est lue sur la RÉPONSE                         |
+| `error` en boucle côté client après la fin voulue | une fin de flux est une coupure pour `EventSource` : il reconnecte                            | `close()` dans `onerror`, ou répondre 204 pour dire « fini »                  |
+| Six onglets, et le site ne répond plus            | plafond de connexions HTTP/1.1 du navigateur envers l'origine qu'il voit                      | faire servir HTTP/2 par le proxy — ou par Nodefony s'il n'y a pas de proxy    |
+| Un flux muet coupé au bout de quelques minutes    | `heartbeat: false`, et un silence plus long que le délai d'inactivité du proxy                | garder le battement, ou allonger ce délai sur le proxy                        |
+| Le flux répond 429 sans avoir rien fait           | `wsMaxConnectionsPerIp` atteint — sockets WebSocket et flux SSE de l'IP comptent ensemble     | relever le plafond, ou fermer les connexions laissées ouvertes                |
+| `RangeError` à `send()`, le flux continue         | événement plus gros que `maxEventBytes`                                                       | découper la donnée, ou relever `maxEventBytes` pour ce flux                   |
+
+## 🧪 Tests & couverture
+
+| Type                 | Où                                                                                                                                                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unitaires — format   | `src/nodefony/src/tests/SseParser.test.ts` — une règle de WHATWG §9.2.5-9.2.6 par cas, borne de taille                                                                                                                            |
+| Unitaires — client   | `src/nodefony/src/tests/NodefonySse.test.ts` — serveur `node:http` réel : ordre, `POST` + `Authorization`, reconnexion `Last-Event-ID`, 204, mauvais type, flux sans fin                                                          |
+| Unitaires — `Accept` | `unit/acceptsEventStream.test.ts`                                                                                                                                                                                                 |
+| Intégration          | `http/sse.test.ts` — serveur de développement, HTTP/1.1 ET HTTP/2 : événements dans l'ordre, en-têtes, départ du client vu (et pas avant) en `GET` et en `POST` avec corps, battement, négociation, `NodefonySse` de bout en bout |
+| Mémoire              | `http/memory.test.ts` — flux fermés par le serveur et flux abandonnés par le client : pente du tas, scopes et contextes résiduels                                                                                                 |
+
+Ces suites ont été vues échouer en débranchant le câblage : fin de ligne coupée entre deux morceaux,
+`id` contenant NUL, `Last-Event-ID` retiré, 204 reconnecté, borne de taille ignorée, poids `q=0`
+accepté, et fermeture écoutée sur la requête.
+
+Ce qui **manque** : aucun banc de débit (événements par seconde) ; la contre-pression n'est pas
+éprouvée sur un client réellement lent ; un flux en HTTP/3 n'existe pas (Node ne sert pas HTTP/3).
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/http — vue du module](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Serveurs](servers.md) — HTTP/2, TLS, délais ; [Proxy inverse](reverse-proxy.md).