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

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
@@ -428,7 +428,7 @@ souvent **moins** de requêtes par seconde qu'en HTTP/1.1. Le choix se fait sur
 
 | Forme du trafic                              | h2c ?         | Pourquoi                                                                                                                                                                          |
 | -------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| gRPC                                         | **requis**    | gRPC n'existe qu'en HTTP/2.                                                                                                                                                       |
+| gRPC natif derrière le proxy                 | **requis**    | gRPC n'existe qu'en HTTP/2 ; gRPC-Web et Connect passent aussi en HTTP/1.1 — voir [gRPC](../../framework/docs/grpc.md).                                                           |
 | Beaucoup de flux longs (SSE) par pod         | **oui**       | En HTTP/1.1, chaque flux occupe une connexion du proxy ; en h2c, ils partagent quelques connexions.                                                                               |
 | En-têtes lourds et répétés (cookies, jetons) | probable      | HPACK les compresse d'une requête à l'autre.                                                                                                                                      |
 | REST classique, petites réponses             | **mesurer**   | Souvent neutre, parfois perdant.                                                                                                                                                  |
@@ -473,9 +473,9 @@ automatiquement un éventuel décalage de port.
   le battement de cœur (`server-websocket.ts#Websocket.createServer`).
 - **Keep-alive** armé à la création (`startHeartbeat()`, `server-websocket.ts#Websocket.createServer`) et par connexion
   (`trackPong()`, `http-kernel.ts#HttpKernel.handleWebsocket`, juste après l'acceptation du handshake).
-- **Arrêt** : il s'inscrit en tête des écouteurs de terminaison
-  (`prependOnceListener`, `server-websocket.ts#Websocket.createServer`) — l'ordre
-  compte, voir la section Arrêt gracieux.
+- **Arrêt** : il s'inscrit à l'étape « congé » de l'arrêt du trafic
+  (`addShutdownStep("dismiss")`, `server-websocket.ts#Websocket.createServer`), attendue avant le
+  drain HTTP — voir la section Arrêt gracieux.
 
 ### `server-websocket-secure` — WebSocket sur TLS
 
@@ -522,16 +522,16 @@ Défauts matérialisés dans `defaultAppConfig` (`src/nodefony/src/config/defaul
 Table dérivée de `httpServerSchema` (`config.ts#httpServerSchema`) ; la section `https` reprend les mêmes clés et en
 ajoute une (`httpsServerSchema`, `config.ts#httpsServerSchema`).
 
-| Option                       | Type  | Défaut  | Effet                                                                            |
-| ---------------------------- | ----- | ------- | -------------------------------------------------------------------------------- |
-| `maxHeadersCount`            | int   | `2000`  | Nombre maximum d'en-têtes par requête — anti _header flooding_.                  |
-| `keepAliveTimeout`           | ms    | `5000`  | Délai de réutilisation de la socket TCP entre deux requêtes.                     |
-| `timeout`                    | ms    | `30000` | Timeout global de socket, aligné sur `responseTimeout`. `0` = désactivé.         |
-| `requestTimeout`             | ms    | `30000` | Délai de réception de la requête complète — **anti slow-loris**.                 |
-| `responseTimeout`            | ms    | `30000` | Délai d'envoi de la réponse complète (couche pipeline).                          |
-| `shutdownTimeout`            | ms    | `5000`  | Drain au shutdown avant destruction forcée. Garder < grâce orchestrateur.        |
-| `headers`                    | objet | `null`  | En-têtes ajoutés à toutes les réponses.                                          |
-| `rejectUnauthorized` (https) | bool  | `false` | Rejette les certificats invalides. `false` en dev (auto-signés), `true` en prod. |
+| Option                       | Type  | Défaut  | Effet                                                                                                                                                                                                   |
+| ---------------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxHeadersCount`            | int   | `2000`  | Nombre maximum d'en-têtes par requête — anti _header flooding_.                                                                                                                                         |
+| `keepAliveTimeout`           | ms    | `5000`  | Délai de réutilisation de la socket TCP entre deux requêtes.                                                                                                                                            |
+| `timeout`                    | ms    | `30000` | Timeout global de socket, aligné sur `responseTimeout`. En HTTP/2 (5152, h2c), une connexion inactive au-delà de ce délai est fermée par GOAWAY ; les flux en cours vont à leur terme. `0` = désactivé. |
+| `requestTimeout`             | ms    | `30000` | Délai de réception de la requête complète — **anti slow-loris**, en HTTP/1.1 (Node) comme en HTTP/2 (framework : 408, puis flux fermé). `0` le désactive.                                               |
+| `responseTimeout`            | ms    | `30000` | Délai d'inactivité d'une action (couche pipeline) : au-delà, 503 et `ctx.signal` annulé. Réglable par route (`responseTimeout` d'une option de route).                                                  |
+| `shutdownTimeout`            | ms    | `5000`  | Drain au shutdown avant destruction forcée. Garder < grâce orchestrateur.                                                                                                                               |
+| `headers`                    | objet | `null`  | En-têtes ajoutés à toutes les réponses.                                                                                                                                                                 |
+| `rejectUnauthorized` (https) | bool  | `false` | Rejette les certificats invalides. `false` en dev (auto-signés), `true` en prod.                                                                                                                        |
 
 Ces deux sections sont **permissives** (`z.looseObject`) : toute option supplémentaire de
 `http.Server` / `net.Server` / TLS (`insecureHTTPParser`, `ciphers`, `minVersion`…) est transmise telle
@@ -552,22 +552,27 @@ 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`.                |
+| `maxPendingAutoPongs`         | entier ≥ 0          | `60`    | Pongs en attente au-delà desquels la connexion est coupée — anti-DoS mémoire. `0` = sans borne. |
+| `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.
@@ -851,7 +856,9 @@ serveurs (HTTP et HTTPS) servent ces chemins — un kubelet configuré en `schem
 ## Arrêt gracieux — la séquence du SIGTERM
 
 Un arrêt brutal coupe les requêtes en vol : à chaque mise à jour progressive, des utilisateurs voient
-une erreur. L'arrêt de Nodefony est une **séquence ordonnée**, et l'ordre est le cœur du sujet.
+une erreur. L'arrêt de Nodefony est une **séquence ordonnée**, et l'ordre est le cœur du sujet. Il
+est écrit dans **une seule fonction**, `http-kernel.ts#HttpKernel.drainTraffic`, l'écouteur `onDrain` du
+module (ADR-0027) : les serveurs s'y inscrivent à leur création, ils n'écoutent pas le noyau.
 
 ```mermaid
 sequenceDiagram
@@ -860,21 +867,22 @@ sequenceDiagram
   participant W as server-websocket
   participant H as server-http / https
   O->>K: SIGTERM
-  K->>K: readyz → 503 (+ shutdownDelay)
+  K->>K: isTerminating → readyz 503 (+ shutdownDelay)
   Note over K: le load balancer retire le pod
-  K->>W: onTerminate (prepend)
+  K->>W: onDrain — étape « congé »
   W->>W: close 1001 « Going Away » à chaque client
-  Note over W: fenêtre ~300 ms
-  K->>H: onTerminate (once)
+  Note over W: fenêtre ~300 ms, fin des flux longs en même temps
+  K->>H: onDrain — étape « drain », serveurs ensemble
   H->>H: drain — in-flight terminées, sockets idle fermées
   Note over H: destruction forcée après shutdownTimeout
+  K->>K: onTerminate — sessions, base, Redis (dernier inscrit d'abord)
   K->>O: exit 0
 ```
 
-**Étape 1 — la disponibilité bascule en premier.** L'écouteur est posé à `onPostReady` pour être
-inséré **en tête** et donc s'exécuter **en premier** (`http-kernel.ts#HttpKernel.init`). `readyz` répond `503`, le
-load balancer cesse d'envoyer du trafic, et `shutdownDelay` laisse à cette information le temps de se
-propager.
+**Étape 1 — la disponibilité bascule en premier.** Le noyau pose `kernel.isTerminating` avant toute
+phase d'arrêt (`Kernel.ts#Kernel.isTerminating`), y compris pour un arrêt reçu pendant le démarrage :
+`readyz` répond `503`, le load balancer cesse d'envoyer du trafic, et `shutdownDelay` (attendu si le
+pod a été annoncé disponible) laisse à cette information le temps de se propager.
 
 **Étape 2 — les clients WebSocket sont prévenus.** `Websocket.terminate()` (`server-websocket.ts#Websocket.terminate`)
 envoie un message applicatif puis une **frame Close 1001 « Going Away »** (`server-websocket.ts#Websocket.terminate`).
@@ -891,11 +899,16 @@ indiscernable d'une panne réseau. Avec 1001, le client sait qu'il doit simpleme
   fermées.
 
 Ce qui reste au-delà de `shutdownTimeout` (défaut `5000` ms, `serverShutdown.ts#DEFAULT_SHUTDOWN_TIMEOUT`)
-est détruit.
+est détruit. Les serveurs (HTTP, HTTPS, h2c) se drainent **ensemble** : ports distincts, aucune
+dépendance — l'arrêt dure un `shutdownTimeout`, pas un par serveur.
+
+**Étape 4 — les ressources sont libérées.** Une fois plus aucune requête en vol, `onTerminate` ferme
+le stockage des sessions, les pools du proxy inverse, les connexions aux bases et à Redis — du
+dernier inscrit au premier.
 
 > [!IMPORTANT]
-> L'ordre WS-avant-HTTP n'est pas cosmétique. Les serveurs WebSocket s'inscrivent en
-> `prependOnceListener` (`server-websocket.ts#Websocket.createServer`), les serveurs HTTP en `once`
+> L'ordre WS-avant-HTTP n'est pas cosmétique. `drainTraffic` attend la fin de l'étape « congé »
+> (`server-websocket.ts#Websocket.createServer`) avant de lancer l'étape « drain »
 > (`server-http.ts#ServerHttp.createServer`). Inversé, le drain détruirait les sockets déjà upgradées **sans** frame
 > Close : retour du 1006 pour tous les clients temps réel.
 
@@ -914,8 +927,12 @@ transport.
 Dès qu'un écouteur `clientError` est attaché, **Node cesse de fermer la socket automatiquement**. Un
 écouteur naïf (« je journalise et je passe ») transforme donc une requête malformée en **fuite de
 socket et de descripteur de fichier** — c'est-à-dire un vecteur de déni de service. Nodefony répond et
-ferme explicitement (`handleClientError()`, `clientError.ts#handleClientError`) : `431` si les en-têtes débordent
-(RFC 6585 §5), `400` sinon (`clientError.ts#handleClientError`), et rien du tout si la socket est déjà morte.
+ferme explicitement (`clientError.ts#handleClientError`), avec la réponse que Node aurait donnée sans
+écouteur : `431` si les en-têtes débordent (RFC 6585 §5) ou `414` si c'est la cible (RFC 9112 §3),
+`413` si les extensions de chunk débordent, `408` si la réception dépasse `requestTimeout`
+(RFC 9110 §15.5.9), `400` sinon. Rien n'est écrit si la socket est déjà morte — ni si une réponse en
+vol a déjà envoyé ses en-têtes : une ligne de statut écrite après elle corromprait ce que lit le
+client ; la socket est alors détruite, comme le fait Node.
 
 ### Connexions WebSocket zombies
 
@@ -952,6 +969,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`

package/docs/sse.md

@@ -23,7 +23,7 @@ status: stable
 updated: 2026-10-08
 source: "src/packages/@nodefony/http/docs/sse.md"
 coverageModule: http
-coverageFiles: context/http/SseStream.ts
+coverageFiles: context/http/SseStream.ts,context/http/StreamLifecycle.ts
 ---
 
 📍 [Documentation](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Flux SSE**
@@ -153,16 +153,16 @@ data: {"step":"écriture"}
 
 ### 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                                                            |
+| 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 ; des octets (`Uint8Array`, `Buffer`) lèvent un `TypeError` : les encoder soi-même (base64) (`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()` :
 
@@ -214,18 +214,25 @@ le même qui relit le flux dans les tests du serveur.
 
 ## 🏗️ Architecture interne — ce que fait l'ouverture
 
+L'ouverture repose sur le **cycle de vie commun aux réponses en flux**
+(`StreamLifecycle.ts#openStreamLifecycle`, non exporté) — la même brique sert le [flux d'octets](byte-stream.md) :
+
 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
+2. **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.
+3. **La fermeture de la réponse est écoutée AVANT toute attente** : un client parti pendant la
+   sauvegarde de la session est vu, et le flux naît fermé (`closed`) sans rien écrire. Un client
+   déjà parti ne prend pas de place dans le plafond par IP.
+4. **La session est sauvée** s'il y en a une — ses cookies partent avec les en-têtes.
+5. **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()`.
+   de 30 s (`SseStream.ts#startSseStream`).
+6. **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`.
+La fin, quel que soit le bout qui ferme, passe par **un seul** nettoyage
+(`StreamLifecycle.ts#StreamLifecycle.finish`) : écouteur `close` retiré, minuteurs de durée de vie et
+de blocage arrêtés, sortie du registre de révocation, puis le nettoyage propre au SSE (battement,
+écouteur `drain`, attente libérée), puis les écouteurs `onClose`.
 
 ## 🔐 Sécurité
 

package/docs/upload.md

@@ -297,6 +297,30 @@ du calque de configuration — une application peut les changer pour une requêt
 sont lus au moment de lire le corps (`Request.readBodyLimits()`), donc un calque posé après ce moment
 (au pare-feu, dans un contrôleur) n'agit pas. Détail : [configuration](../../../../../docs/guides/configuration.md).
 
+### Par route — l'option `upload`
+
+Une route règle ses propres bornes d'envoi, sans toucher à celles des autres : un dépôt de vidéos
+relève `maxFileSize`, un avatar l'abaisse. Chaque clé déclarée remplace celle de la configuration,
+**dans les deux sens** ; une clé absente garde la valeur de la configuration
+(`framework/nodefony/src/Route.ts#RouteOptions.upload`).
+
+```ts ignore
+// un avatar : 256 Kio au plus, un seul fichier, son empreinte calculée pendant le flux
+@Post("/avatar", { upload: { maxFileSize: 262_144, maxFiles: 1, hashAlgorithm: "sha256" } })
+async avatar(@UploadedFile() file: IUploadedFile | undefined) {
+  return { size: file?.size ?? 0, sha256: file?.hash ?? null };
+}
+```
+
+- **Le fichier trop gros est coupé PENDANT son flux** (413) : la route est résolue avant la lecture
+  du corps, ses bornes s'appliquent donc à busboy comme celles de la configuration — jamais un
+  fichier écrit en entier puis refusé (`context/http/Request.ts#HttpRequest.readBodyLimits`).
+- **Une route sans l'option ne paie rien** : aucune fusion, aucune allocation.
+- **Validée à la déclaration** (`framework/nodefony/decorators/routerDecorators.ts#checkedUpload`) :
+  entiers ≥ 1, empreinte connue, aucune clé inconnue — une faute de frappe (`maxFilesize`) laisserait
+  sinon la route sur la borne de l'application. `uploadDir` et `encoding` restent ceux de la
+  configuration. Exclue avec `bodyStream: true`, dont le corps n'est jamais lu par le pipeline.
+
 ### Fichiers multipart — `upload.*`
 
 Table dérivée de `uploadSchema` (`config/config.ts#uploadSchema`). Toutes les bornes sont `runtimeMutable`.
@@ -342,15 +366,15 @@ Les décorateurs `@UploadedFile` / `@UploadedFiles` sont des fabriques de param
 Chaque entrée de `files` est un `UploadedFile` (`service/upload/upload-service.ts#UploadedFile`), déjà écrit
 sur disque. Ses membres utiles :
 
-| Membre                   | Ce qu'il donne                                                          | Ancrage                                                                           |
-| ------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `filename`               | Nom **d'origine** déclaré par le client (métadonnée, jamais le chemin). | `realName()` (`service/upload/upload-service.ts#UploadedFile.realName`)           |
-| `size`                   | Taille réellement écrite (octets).                                      | `getSize()` (`service/upload/upload-service.ts#UploadedFile.getSize`)             |
-| `prettySize`             | Taille lisible (`« 1.2 MB »`).                                          | `getPrettySize()` (`service/upload/upload-service.ts#UploadedFile.getPrettySize`) |
-| `mimeType`               | Type MIME déclaré (`image/png`…), sinon deviné de l'extension.          | `getMimeType()` (`service/upload/upload-service.ts#UploadedFile.getMimeType`)     |
-| `hash` / `hashAlgorithm` | Empreinte d'intégrité si `upload.hashAlgorithm` est réglé.              | `interfaces/IUpload.ts#IUploadedFile.hashAlgorithm`                               |
-| `moveAsync(target)`      | Déplace le temp — **non bloquant, recommandé** dans le pipeline.        | `moveAsync()` (`service/upload/upload-service.ts#UploadedFile.moveAsync`)         |
-| `move(target)`           | Variante **synchrone** (compat) — bloque l'event-loop.                  | `move()` (`service/upload/upload-service.ts#UploadedFile.move`)                   |
+| Membre                   | Ce qu'il donne                                                                                                                                                              | Ancrage                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `filename`               | Nom **d'origine** déclaré par le client (métadonnée, jamais le chemin).                                                                                                     | `realName()` (`service/upload/upload-service.ts#UploadedFile.realName`)           |
+| `size`                   | Taille réellement écrite (octets).                                                                                                                                          | `getSize()` (`service/upload/upload-service.ts#UploadedFile.getSize`)             |
+| `prettySize`             | Taille lisible (`« 1.2 MB »`).                                                                                                                                              | `getPrettySize()` (`service/upload/upload-service.ts#UploadedFile.getPrettySize`) |
+| `mimeType`               | Type MIME déclaré (`image/png`…), sinon deviné de l'extension ; `false` si ni l'un ni l'autre. Déclaratif : jamais une preuve du contenu.                                   | `getMimeType()` (`service/upload/upload-service.ts#UploadedFile.getMimeType`)     |
+| `hash` / `hashAlgorithm` | Empreinte d'intégrité si `upload.hashAlgorithm` est réglé.                                                                                                                  | `interfaces/IUpload.ts#IUploadedFile.hashAlgorithm`                               |
+| `moveAsync(target)`      | Déplace le temp — **non bloquant, recommandé** dans le pipeline. Rend le `FileClass` de la destination (sans nom d'origine ni empreinte : ils restent sur le fichier reçu). | `moveAsync()` (`service/upload/upload-service.ts#UploadedFile.moveAsync`)         |
+| `move(target)`           | Variante **synchrone** (compat) — bloque l'event-loop.                                                                                                                      | `move()` (`service/upload/upload-service.ts#UploadedFile.move`)                   |
 
 `move`/`moveAsync` acceptent un **fichier cible** ou un **dossier existant** : sur un dossier, la
 destination est bâtie avec `filename` — d'où l'avertissement de sécurité ci-dessous.
@@ -429,6 +453,7 @@ pipeline : `npm run test:memory` (skill `nodefony-check-memory-health`).
 | `@Body()` est vide sur un upload de fichier             | Les fichiers vont dans `files`, **pas** dans `body`                               | Lire les fichiers avec `@UploadedFiles()` / `this.files` ; `@Body()` = champs texte                                         |
 | Un `POST` JSON de 1,5 Mo est refusé en `413`            | `maxBodySize` vaut **1 MiB** par défaut                                           | Augmenter `maxBodySize` (pas `upload.maxFileSize`)                                                                          |
 | Un gros fichier passe alors que `maxBodySize` est petit | Le multipart **n'écoute pas** `maxBodySize`                                       | Régler `upload.maxFileSize` / `maxTotalFileSize`                                                                            |
+| Un avatar de 2 Go remplit le disque avant d'être refusé | La borne de l'application (500 Mo) vaut pour toutes les routes                    | Option de route `upload: { maxFileSize }` — coupé pendant le flux                                                           |
 | `413` sur upload sans message clair                     | Une borne busboy atteinte en streaming (fichier, cumul, nombre)                   | Vérifier les bornes `upload.*` — 413 émis sur `stream.on("limit")` (`context/http/Request.ts#HttpRequest.enforceBodyLimit`) |
 | Un fichier écrit `../../etc/…` après un `move`          | `move(dossier)` utilise le nom **client** (`upload-service.ts#UploadedFile.move`) | Passer une cible complète, ou `path.basename(file.filename)`                                                                |
 | Des fichiers temporaires s'accumulent dans `uploadDir`  | Le contrôleur ne déplace jamais le temp                                           | Appeler `moveAsync()` (ou purger l'ancien temp par TTL)                                                                     |
@@ -441,14 +466,15 @@ pipeline : `npm run test:memory` (skill `nodefony-check-memory-health`).
 Les chiffres exacts vivent dans la carte de tests de cette page (régénérée depuis vitest, jamais figés
 dans le Markdown).
 
-| Type                        | Où                                                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| Unitaires — `UploadedFile`  | `unit/UploadedFile.test.ts` — `create()` async, `move`/`moveAsync`, `mimeType`, `realName`                          |
-| Unitaires — `@Body` stream  | `framework` `unit/BodyStream.test.ts` — `@Body({ stream })`, `resolveParamArg`, `routeExpectsBodyStream`            |
-| Intégration — multipart     | `http/upload.test.ts` — upload simple, multi-fichiers, mime non-octet, champ + fichier, `413` par fichier et cumulé |
-| Intégration — content-types | `http/body-content-types.test.ts` — JSON, urlencoded, `@Body("champ")`, XML → `body`                                |
-| Intégration — bornes        | `http/body-limit.test.ts` — sous la limite `200`, `Content-Length` > 1 MiB → `413`, chunked > 1 MiB refusé          |
-| Intégration — flux brut     | `integration/bodyStream.test.ts` — `@Body({ stream })` bout-en-bout (TLS + clair), non-régression `@Body()`         |
+| Type                        | Où                                                                                                                                                                                                            |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unitaires — `UploadedFile`  | `unit/UploadedFile.test.ts` — `create()` async, `move`/`moveAsync`, `mimeType`, `realName`                                                                                                                    |
+| Unitaires — `@Body` stream  | `framework` `unit/BodyStream.test.ts` — `@Body({ stream })`, `resolveParamArg`, `routeExpectsBodyStream`                                                                                                      |
+| Intégration — multipart     | `http/upload.test.ts` — upload simple, multi-fichiers, mime non-octet, champ + fichier, `413` par fichier et cumulé ; bornes et empreinte PAR ROUTE (abaissée, relevée), aucun temporaire laissé par un refus |
+| Unitaires — option `upload` | `framework` `unit/httpMethodDecorators.test.ts` — portée jusqu'à la route, figée ; refus à la déclaration                                                                                                     |
+| Intégration — content-types | `http/body-content-types.test.ts` — JSON, urlencoded, `@Body("champ")`, XML → `body`                                                                                                                          |
+| Intégration — bornes        | `http/body-limit.test.ts` — sous la limite `200`, `Content-Length` > 1 MiB → `413`, chunked > 1 MiB refusé                                                                                                    |
+| Intégration — flux brut     | `integration/bodyStream.test.ts` — `@Body({ stream })` bout-en-bout (TLS + clair), non-régression `@Body()`                                                                                                   |
 
 Ce qui **manque** aujourd'hui : pas de banc de **charge** dédié à l'upload (le streaming multipart n'est
 exercé que fonctionnellement), pas de test **d'attaque** (`*.attack.test.ts`) sur le path traversal de

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/http",
-  "version": "10.0.0-beta.5",
+  "version": "10.0.0-beta.7",
   "description": "Serveurs HTTP, HTTPS, HTTP/2 et WebSocket natifs pour Nodefony : sessions, contextes de requête, certificats TLS",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -12,6 +12,12 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./grpc": {
+      "nodefony-source": "./nodefony/grpc/index.ts",
+      "types": "./dist/types/nodefony/grpc/index.d.ts",
+      "import": "./dist/nodefony/grpc/index.js",
+      "default": "./dist/nodefony/grpc/index.js"
     }
   },
   "scripts": {
@@ -27,7 +33,7 @@
   },
   "private": false,
   "engines": {
-    "node": ">=24.14.0"
+    "node": "^24.16.0 || >=26.0.0"
   },
   "keywords": [
     "nodefony",
@@ -51,38 +57,52 @@
     "test": "./nodefony/tests"
   },
   "dependencies": {
-    "@fastify/busboy": "3.2.4",
-    "cookie": "2.0.1",
+    "@fastify/busboy": "3.2.5",
+    "@types/ms": "2.1.0",
+    "@types/qs": "6.15.1",
+    "@types/serve-static": "2.2.0",
+    "@types/ws": "8.18.2",
+    "@types/xml2js": "0.4.14",
+    "cookie": "2.0.2",
     "mime-types": "3.0.2",
     "ms": "^2.1.3",
-    "qs": "^6.16.1",
+    "qs": "^6.17.1",
     "serve-static": "2.2.1",
-    "tslib": "2.8.1",
-    "ws": "8.22.0",
+    "tslib": "2.9.1",
+    "ws": "8.23.0",
     "xml2js": "0.6.2"
   },
   "devDependencies": {
     "@types/chai": "5.2.3",
     "@types/mime-types": "3.0.1",
-    "@types/ms": "2.1.0",
-    "@types/node": "26.6.5",
-    "@types/qs": "6.15.1",
-    "@types/serve-static": "2.2.0",
+    "@types/node": "26.6.6",
     "@types/websocket": "1.0.10",
-    "@types/ws": "8.18.2",
-    "@types/xml2js": "0.4.14",
-    "@vitest/coverage-v8": "5.0.5",
-    "nodefony": "^10.0.0-beta.5",
+    "@vitest/coverage-v8": "5.1.0",
+    "nodefony": "^10.0.0-beta.7",
     "tsx": "4.23.15",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "nodefony": "^10.0.0-beta.5",
+    "@bufbuild/protobuf": "^2.7.0",
+    "@connectrpc/connect": "^2.3.0",
+    "@connectrpc/connect-node": "^2.3.0",
+    "nodefony": "^10.0.0-beta.7",
     "zod": "^4.6.7"
   },
+  "peerDependenciesMeta": {
+    "@bufbuild/protobuf": {
+      "optional": true
+    },
+    "@connectrpc/connect": {
+      "optional": true
+    },
+    "@connectrpc/connect-node": {
+      "optional": true
+    }
+  },
   "files": [
     "dist",
     "docs"
@@ -90,7 +110,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://nodefony.github.io/nodefony-core/",
+  "homepage": "https://nodefony.net/",
   "bugs": {
     "url": "https://github.com/nodefony/nodefony-core/issues"
   }