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

package/dist/types/nodefony/src/servers/http2Goaway.d.ts

@@ -0,0 +1,41 @@
+import type { ServerHttp2Session } from "node:http2";
+/** Plus long délai d'annonce (ms) : un pair qui ne répond pas au PING ne retient pas la fermeture. */
+export declare const ANNOUNCE_CAP_MS = 1000;
+/**
+ * Annonce à UNE session HTTP/2 qu'elle va fermer, SANS écarter un flux déjà en route.
+ *
+ * Un PING mesure l'aller-retour, puis GOAWAY à `2^31-1`, puis l'attente de cet
+ * aller-retour : après elle, tout flux ouvert par le client avant l'annonce est
+ * arrivé, et le GOAWAY définitif (`session.close()`, dernier flux traité) peut
+ * suivre. RFC 9113 §6.8 : « SHOULD send an initial GOAWAY frame with the last
+ * stream identifier set to 2^31-1 […] After allowing time for any in-flight
+ * stream creation (at least one round-trip time) ». Sans annonce, un flux croisé
+ * avec le GOAWAY est refusé alors qu'il aurait pu être servi.
+ *
+ * L'aller-retour se MESURE avant l'annonce : après un GOAWAY, un client Node ne
+ * répond plus aux PING (constaté sur Node 26.13).
+ *
+ * @param session - la session à annoncer, ni fermée ni détruite
+ * @param settle - appelé UNE fois : après l'attente, à la fermeture de la
+ *   session, ou aussitôt si le PING ne part pas. Un pair muet ne l'appelle
+ *   jamais — le délai maximal appartient à l'appelant.
+ */
+export declare function announceSessionClose(session: ServerHttp2Session, settle: () => void): void;
+/**
+ * Ferme EN DOUCEUR une session HTTP/2 restée inactive au-delà du délai du serveur.
+ *
+ * RFC 9113 §9.1 : un serveur est « permitted to terminate idle connections »,
+ * et « SHOULD first send a GOAWAY ». La fermeture suit l'annonce en deux temps
+ * ({@link announceSessionClose}), puis `session.close()` : aucun nouveau flux,
+ * mais les flux en cours vont à leur terme — un flux long et muet (abonnement
+ * gRPC) n'est pas coupé, seuls les NOUVEAUX flux repartent sur une autre
+ * connexion, ce que tout client HTTP/2 fait sur GOAWAY.
+ *
+ * Le délai de la session est désarmé d'abord : Node (26.13) marque une session
+ * détruite AVANT de désarmer son minuteur, qui la retiendrait alors jusqu'à son
+ * échéance (nodejs/node#66885).
+ *
+ * @param session - la session inactive
+ * @param capMs - délai maximal d'attente de l'écho du PING (ms)
+ */
+export declare function closeIdleSession(session: ServerHttp2Session, capMs?: number): void;

package/dist/types/nodefony/src/servers/http2Limits.d.ts

@@ -14,24 +14,37 @@ import type { IHttpConfig } from "../../config/config.js";
  */
 export declare function http2ServerLimits(limits: Partial<IHttpConfig["http2"]> | undefined): Pick<ServerOptions, "maxSessionMemory" | "settings">;
 /**
- * Borne l'inactivité des sessions d'un serveur HTTP/2 — TLS (5152) comme h2c —
- * et contourne un défaut de Node qui garde chaque session fermée en vie jusqu'à
- * l'échéance de ce délai.
+ * Ferme les sessions d'un serveur HTTP/2 — TLS (5152) comme h2c — restées
+ * inactives au-delà de `timeoutMs`, et contourne un défaut de Node qui garde
+ * chaque session fermée en vie jusqu'à l'échéance de ce délai.
  *
- * Le défaut (Node 24, 26) : `closeSession` (`internal/http2/core`) marque la
- * session détruite PUIS appelle `session.setTimeout(0)` ; or `setStreamTimeout`
- * sort aussitôt sur un objet détruit. Le minuteur n'est jamais désarmé et retient
- * la session (~2,4 Ko) pendant `timeoutMs` : sous un flux de connexions neuves,
- * connexions/s × délai × 2,4 Ko. Signalé à Node : https://github.com/nodejs/node/issues/66885
+ * **La fermeture est À NOUS.** Node arme chaque session par
+ * `session.setTimeout(server.timeout, sessionOnTimeout)` — un écouteur `once` —
+ * et `sessionOnTimeout` ne détruit la session que si le serveur n'a AUCUN
+ * écouteur `timeout` ; s'il en a un, il lui passe la main, UNE fois par session
+ * (`internal/http2/core`, Node 26.13). Le serveur 5152 en a toujours un
+ * (`routeSocketTimeout`, pour ses sockets HTTP/1.1), et ce délai doit prévenir
+ * l'application (`onTimeout`) : sans fermeture ici, une session inactive vivait
+ * jusqu'à ce que le CLIENT la ferme (#763). À l'échéance, la session est fermée
+ * en douceur — GOAWAY annoncé puis définitif, les flux en cours vont à leur
+ * terme ({@link closeIdleSession}, RFC 9113 §9.1 et §6.8).
  *
- * Le contournement : désarmer à la réception du GOAWAY, AVANT la destruction —
- * c'est ainsi que ferment un proxy et un client Node, même par `destroy()`. Rien
- * n'est retiré à la protection : Node n'agit déjà plus à l'échéance sur une
- * session fermée (`sessionOnTimeout` sort sur `closed`). Une coupure TCP sans
- * GOAWAY garde la rétention, bornée au délai.
+ * **Le contournement** (Node 24, 26) : `closeSession` marque la session détruite
+ * PUIS appelle `session.setTimeout(0)`, qui sort aussitôt sur un objet détruit ;
+ * le minuteur retient alors la session (~2,4 Ko) pendant `timeoutMs`. Il est
+ * désarmé à la réception du GOAWAY, AVANT la destruction — c'est ainsi que
+ * ferment un proxy et un client Node, même par `destroy()` ; et
+ * `closeIdleSession` le désarme avant de fermer. Signalé à Node :
+ * https://github.com/nodejs/node/issues/66885 (corrigé par nodejs/node#66886,
+ * absent de la 26.13). Une coupure TCP sans GOAWAY garde la rétention, bornée
+ * au délai.
+ *
+ * Coût par requête : nul — un écouteur par serveur, et la fermeture n'agit qu'à
+ * l'échéance.
  *
  * @param server - le serveur HTTP/2.
  * @param timeoutMs - délai d'inactivité ; 0 ou absent le laisse désactivé.
- * @param onTimeout - appelé à l'échéance (événement `timeout` du serveur).
+ * @param onTimeout - appelé à l'échéance d'une session (événement `timeout` du
+ *   serveur), après le début de sa fermeture.
  */
 export declare function setHttp2SessionTimeout(server: Http2Server | Http2SecureServer, timeoutMs: number | undefined, onTimeout: () => void): void;

package/dist/types/nodefony/src/servers/http2StreamGrace.d.ts

@@ -0,0 +1,34 @@
+import { type Http2Stream } from "node:http2";
+/**
+ * Ferme en `NO_ERROR` un flux HTTP/2 dont la réponse est partie mais dont le
+ * client émet encore, après la grâce d'un aller-retour (`PING`, RFC 9113 §6.7).
+ *
+ * RFC 9113 §8.1 : après une réponse complète, le serveur PEUT demander au
+ * client d'arrêter d'émettre par un `RST_STREAM` `NO_ERROR`. La coupe ne doit
+ * jamais précéder l'envoi de la réponse : un `RST_STREAM` soumis pendant que
+ * les en-têtes attendent encore dans la file de nghttp2 les fait JETER, et le
+ * client reçoit une fin de flux sans statut (un client gRPC la lit INTERNAL).
+ * Le `PING` part derrière la réponse ; son écho prouve qu'elle est arrivée.
+ *
+ * **Un seul `PING` par session** couvre tous les flux qui attendent : un flux
+ * arrivé pendant qu'un `PING` est en vol attend le suivant. Le plafond de
+ * `PING` en vol de Node (10 par session) n'est donc jamais atteint par ce
+ * chemin, et aucun flux n'est coupé sans grâce — ce que faisait la coupe
+ * immédiate quand `ping()` rendait `false`, au-delà de 10 refus simultanés.
+ *
+ * Session en fermeture GRACIEUSE (délai d'inactivité, arrêt) : Node n'envoie
+ * plus de `PING`, et la session attend la fin de ses flux — un client muet la
+ * retiendrait. La coupe part alors au tour de boucle suivant, le temps que les
+ * réponses déjà soumises quittent la file de nghttp2.
+ *
+ * Après la grâce : client qui a fini d'émettre → rien (le flux se ferme seul,
+ * sans `RST_STREAM`) ; sinon → coupé. L'écho d'un `PING` passe avant les autres
+ * trames (§6.7) : une trame DATA encore en route peut arriver après lui, la
+ * coupe reste conforme (§8.1).
+ *
+ * Coût : chemin d'erreur seulement — une entrée de `WeakMap` par session tant
+ * que des flux attendent, un `PING` par aller-retour et par session.
+ *
+ * @param stream - flux dont la réponse est ÉCRITE (`finish` passé).
+ */
+export declare function closeStreamAfterGrace(stream: Http2Stream): void;

package/dist/types/nodefony/src/servers/receiveDeadline.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Une échéance ABSOLUE pour des réceptions en cours, sans un minuteur par
+ * réception : un seul balayage périodique pour toutes.
+ *
+ * ## Pourquoi
+ *
+ * `node:http2` ne borne pas la réception d'une requête : il n'a que des délais
+ * d'INACTIVITÉ (`http2stream.setTimeout`, `http2session.setTimeout`), qu'un
+ * client tient en vie avec un octet avant chaque échéance. `requestTimeout`,
+ * la borne absolue anti « slow-loris », n'existe que pour HTTP/1.1.
+ *
+ * ## Le coût, et pourquoi cette forme
+ *
+ * C'est la forme que Node donne lui-même à `requestTimeout` : aucun minuteur
+ * par requête, un contrôle périodique (`connectionsCheckingInterval`). Les
+ * réceptions suivies vivent dans un ANNEAU — un tableau des éléments et un
+ * `Int32Array` des tours d'entrée, indexés par un numéro de séquence :
+ * - suivre = deux écritures ; libérer = une comparaison et une écriture. Ni
+ *   minuteur, ni fermeture, ni lecture d'horloge (le temps se compte en TOURS),
+ *   ni champ ajouté à l'élément suivi ;
+ * - mesuré contre une `Map` (hachage d'identité de la clé) : ~26–32 ns par
+ *   réception contre ~90–150 ns, de 1 à 10 000 réceptions simultanées.
+ *
+ * Toutes les entrées ont le même délai : l'ordre d'insertion EST l'ordre
+ * d'échéance. Un tour avance la tête et s'arrête à la première entrée vivante
+ * non échue — il ne coûte que ce qu'il expire ou saute.
+ *
+ * Contrepartie, bornée : une case libérée DERRIÈRE une entrée vivante attend
+ * que la tête la dépasse, soit au plus un délai de réception — 12 octets par
+ * réception commencée dans cette fenêtre. Sous charge, l'anneau garde sa
+ * capacité d'un tour à l'autre (jamais rétréci puis recrû) ; il la rend au
+ * premier tour sans réception nouvelle. Le minuteur unique est `unref`, et s'arrête au
+ * même moment.
+ *
+ * ## Précision
+ *
+ * Une entrée expire entre `timeoutMs` et `timeoutMs + periodMs` après son
+ * suivi — jamais AVANT le délai configuré.
+ *
+ * @typeParam T - l'élément suivi (un contexte de requête)
+ */
+export declare class ReceiveDeadline<T extends object> {
+    #private;
+    /**
+     * @param timeoutMs - le délai de réception (> 0)
+     * @param onExpire - appelé une fois par entrée échue, déjà retirée
+     * @param periodMs - la période du balayage, bornée par le délai (défaut 1 s)
+     * @throws RangeError si `timeoutMs` ou `periodMs` n'est pas un entier > 0
+     */
+    constructor(timeoutMs: number, onExpire: (item: T) => void, periodMs?: number);
+    /** Cases occupées, libérées ou non, entre la tête et la queue. */
+    get size(): number;
+    /** Capacité courante de l'anneau. */
+    get capacity(): number;
+    /** Vrai tant que le balayage tourne. */
+    get running(): boolean;
+    /**
+     * Suit une réception qui commence ; démarre le balayage s'il dormait.
+     *
+     * @param item - la réception
+     * @returns le numéro à rendre à {@link ReceiveDeadline.release}
+     */
+    track(item: T): number;
+    /**
+     * Cesse de suivre une réception terminée (reçue, refusée ou échue). Sans
+     * effet si la case a déjà été balayée ou réattribuée : l'identité de
+     * l'élément est vérifiée. Le balayage ne s'arrête pas ici mais au tour
+     * suivant s'il ne reste rien — jamais un minuteur armé puis désarmé par
+     * requête.
+     *
+     * @param seq - le numéro rendu par {@link ReceiveDeadline.track}
+     * @param item - la réception suivie
+     */
+    release(seq: number, item: T): void;
+    /** Arrête le balayage et oublie toutes les réceptions (arrêt du serveur). */
+    close(): void;
+}

package/docs/byte-stream.md

@@ -181,6 +181,27 @@ L'union **peut s'agrandir** : un `switch` exhaustif sur `reason` garde une branc
 
 ### 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() {
@@ -277,6 +298,17 @@ deux types de flux.
    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
@@ -336,26 +368,29 @@ désoptimisation de V8 (`--trace-deopt`) ne cite pas `ByteStream`.
 
 ## ⚠️ 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`                                             |
+| 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 |
-| 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                                                                                                                                                                                                                                                                      |
+| 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

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/servers.md

@@ -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,23 @@ 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).                    |
-| `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.       |
+| 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`, `backpressurePolicy`,
@@ -855,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
@@ -864,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`).
@@ -895,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.
 
@@ -918,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