Flux d'événements serveur (SSE) — pousser au navigateur sur une réponse qui ne finit pas

stable@nodefony/httpmis à jour 2026-10-08

📍 Documentation › @nodefony/http › 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 ?#

ℹ️ 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 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#

// 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#

// 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#

curl -sN -H 'Accept: text/event-stream' http://127.0.0.1:5151/progress/run

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#

Options de renderSse() :

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#

@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.

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)#

🧪 Tests & couverture#

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 · Toute la documentation
• 🧭 Pages sœurs : Serveurs — HTTP/2, TLS, délais ; Proxy inverse.