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

package/dist/types/nodefony/src/grpc/refusal.d.ts

@@ -0,0 +1,136 @@
+import type http from "node:http";
+/**
+ * Refus d'un appel gRPC au format de son protocole (ADR-0026 D5 point 2, D13
+ * point 2). Sans Connect : une application sans service gRPC charge ce module
+ * avec le noyau, et n'y paie rien tant qu'aucune erreur n'est rendue.
+ *
+ * Le protocole se reconnaît aux en-têtes de la requête et se code en petit
+ * entier (`GRPC_WIRE_*`, 0 = aucun) : une valeur toujours du même type, lue
+ * sur le chemin d'erreur seulement.
+ */
+/** Requête qui ne parle aucun protocole gRPC. */
+export declare const GRPC_WIRE_NONE = 0;
+/** gRPC natif (`application/grpc`, `application/grpc+proto`…). */
+export declare const GRPC_WIRE_GRPC = 1;
+/** gRPC-Web (`application/grpc-web`, `application/grpc-web-text`…). */
+export declare const GRPC_WIRE_WEB = 2;
+/** Connect unaire (`connect-protocol-version`, ou GET `?connect=v1`). */
+export declare const GRPC_WIRE_CONNECT = 3;
+/** Connect en flux (`application/connect+proto`, `application/connect+json`). */
+export declare const GRPC_WIRE_CONNECT_STREAM = 4;
+/** Le protocole gRPC d'une requête, `GRPC_WIRE_NONE` s'il n'y en a aucun. */
+export type GrpcWire = typeof GRPC_WIRE_NONE | typeof GRPC_WIRE_GRPC | typeof GRPC_WIRE_WEB | typeof GRPC_WIRE_CONNECT | typeof GRPC_WIRE_CONNECT_STREAM;
+/**
+ * Reconnaît le protocole gRPC d'une requête à ses en-têtes : `content-type`
+ * d'abord, puis `connect-protocol-version`. Une API JSON ordinaire rend
+ * `GRPC_WIRE_NONE`.
+ *
+ * @param headers - les en-têtes de la requête.
+ * @param connectGet - `true` pour un GET qui porte `connect=v1` (Connect
+ *   unaire en GET, sans en-tête propre).
+ * @returns le protocole reconnu.
+ */
+export declare function grpcWireOf(headers: http.IncomingHttpHeaders, connectGet?: boolean): GrpcWire;
+/** 16 `UNAUTHENTICATED`. */
+export declare const GRPC_UNAUTHENTICATED = 16;
+/** 7 `PERMISSION_DENIED`. */
+export declare const GRPC_PERMISSION_DENIED = 7;
+/**
+ * Le nom d'un code gRPC (`unimplemented`, `unauthenticated`…) — le libellé
+ * générique d'un refus (ADR-0026 D5 point 4).
+ *
+ * @param code - le code gRPC, de 0 à 16.
+ * @returns son nom ; `unknown` hors de la plage.
+ */
+export declare function grpcCodeName(code: number): string;
+/**
+ * Le nom d'un code gRPC tel que le publient la ligne d'accès et le canal de
+ * traçage (`UNAVAILABLE`) — ADR-0026 D10 point 1.
+ *
+ * @param code - le code gRPC, de 0 à 16.
+ * @returns son nom ; `UNKNOWN` hors de la plage.
+ */
+export declare function grpcStatusName(code: number): string;
+/**
+ * Le code gRPC d'un refus de transport — rendu avant l'implémentation (chemin
+ * inconnu, méthode refusée, limite de débit, pare-feu) — en gRPC natif et en
+ * gRPC-Web (ADR-0026 D13 point 2). Distincte de la table des erreurs de
+ * l'application (D7) ; seule la règle d'identité de 401/403 est commune (D5).
+ *
+ * @param status - le statut HTTP que le noyau aurait rendu.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function transportRefusalCode(status: number, identified: boolean): number;
+/**
+ * Le code gRPC d'une erreur levée par l'APPLICATION pendant un appel — une
+ * `HttpError` d'un service partagé avec des routes HTTP, une validation, un
+ * conflit (ADR-0026 D7, table « HTTP Mapping » de `google/rpc/code.proto`).
+ * Distincte de la table des refus de transport ({@link transportRefusalCode}) :
+ * un 404 levé par un service dit « entité introuvable » (5), un chemin inconnu
+ * dit « méthode absente » (12). Seule la règle d'identité de 401/403 est
+ * commune (D5).
+ *
+ * `code.proto` associe 409 à `ABORTED` et à `ALREADY_EXISTS` : `ABORTED`, le
+ * sens le plus large, est retenu ; `ALREADY_EXISTS` se lève en `ConnectError`.
+ *
+ * @param status - le statut HTTP que rendrait une route HTTP.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function applicationErrorCode(status: number, identified: boolean): number;
+/**
+ * Le code d'un refus en protocole Connect : celui qu'un client DÉDUIT du
+ * statut HTTP (`connect-protocol.md`, « HTTP to Error Code »), puisque le
+ * statut voyage avec la réponse et doit s'accorder au code. 405 et 421 y
+ * valent donc `unknown` (ADR-0026 D13, précision du lot 3) ; 401/403 suivent
+ * la règle d'identité (D5).
+ *
+ * @param status - le statut HTTP du refus.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function connectRefusalCode(status: number, identified: boolean): number;
+/** Ce que le refus touche de la réponse : son statut et ses en-têtes. */
+export interface IGrpcRefusalTarget {
+    setStatusCode(status: number, message?: string): void;
+    setHeader(name: string, value: string): void;
+}
+/**
+ * Pose le statut et les en-têtes d'un refus au format du protocole, et rend
+ * le corps à envoyer — vide en gRPC et gRPC-Web, dont le statut voyage dans
+ * les en-têtes (_Trailers-Only_ ; en HTTP/2, `Http2Response.writeHead` termine
+ * alors le flux sur la trame d'en-têtes).
+ *
+ * | Protocole       | Statut HTTP                    | Corps                                  |
+ * | --------------- | ------------------------------ | -------------------------------------- |
+ * | gRPC, gRPC-Web  | 200                            | aucun                                  |
+ * | Connect unaire  | celui du refus (401/403 : D5)  | `{"code":"<nom>"}`                     |
+ * | Connect en flux | 200                            | message de fin `{"error":{…}}`         |
+ *
+ * Le message n'est jamais celui de l'erreur, qui nomme parfois la zone
+ * refusée : seul le nom du code part (D5 point 4).
+ *
+ * @param response - la réponse du contexte, pas encore envoyée.
+ * @param wire - le protocole de la requête, autre que `GRPC_WIRE_NONE`.
+ * @param status - le statut HTTP que le noyau aurait rendu.
+ * @param identified - un appelant authentifié est connu.
+ * @param contentType - le `content-type` de la requête, recopié en gRPC,
+ *   gRPC-Web et Connect en flux (déjà reconnu par {@link grpcWireOf}).
+ * @returns le corps : texte vide, JSON, ou octets d'un message de fin.
+ */
+export declare function prepareGrpcRefusal(response: IGrpcRefusalTarget, wire: GrpcWire, status: number, identified: boolean, contentType: string | undefined): string | Uint8Array;
+/**
+ * Marque une route comme servie par un point d'entrée gRPC — au démarrage,
+ * par `@nodefony/framework/grpc`. Allume la garde qui refuse en 12 une requête
+ * gRPC native aboutie à une route qui n'est pas gRPC (ADR-0026 D13 point 3) :
+ * tant qu'aucune route n'est marquée, la garde coûte une lecture de booléen.
+ *
+ * @param route - la route montée pour une méthode du contrat.
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare function markGrpcRoute(route: {
+    grpc?: boolean | undefined;
+}): void;
+/** `true` dès qu'une route gRPC est déclarée dans le processus. */
+export declare function hasGrpcRoutes(): boolean;

package/dist/types/nodefony/src/profiler/Profiler.d.ts

@@ -116,6 +116,14 @@ export declare class Profiler implements IProfilerReader {
     private readonly _caps;
     /** Dernier numéro d'ordre attribué (0 = aucun profil collecté). */
     private _seq;
+    /**
+     * Démarrage du profileur, donc du processus (ms epoch, horloge du serveur) :
+     * aucune requête servie avant n'est connue. Rendu avec un profil absent, pour
+     * que le lecteur dise « le serveur a redémarré » plutôt que « évincé ».
+     */
+    readonly startedAt: number;
+    /** Dernier vidage des anneaux (ms epoch), `null` s'il n'y en a jamais eu. */
+    private _clearedAt;
     /**
      * @param cap - capacité de l'anneau de l'application.
      * @param sideCap - capacité de chacun des anneaux de l'outillage et des
@@ -155,7 +163,9 @@ export declare class Profiler implements IProfilerReader {
     since(cursor: number): IProfileBatch;
     /** Nombre de profils en mémoire. */
     get size(): number;
-    /** Vide les anneaux. */
+    /** Vide les anneaux, et retient l'instant du vidage ({@link clearedAt}). */
     clear(): void;
+    /** Dernier vidage des anneaux (ms epoch, horloge du serveur), `null` si aucun. */
+    get clearedAt(): number | null;
 }
 export default Profiler;

package/dist/types/nodefony/src/proxy/forward.d.ts

@@ -38,6 +38,13 @@ export interface IRelaySettings {
      */
     agent: http.Agent | false | undefined;
 }
+/**
+ * En-têtes de CONNEXION (RFC 9110 §7.6.1) : ils décrivent un saut, jamais le
+ * message — un intermédiaire ne les transmet pas. Les cinq premiers sont en
+ * outre INTERDITS en HTTP/2 (RFC 9113 §8.2.2) : Node lève
+ * `ERR_HTTP2_INVALID_CONNECTION_HEADERS` si une réponse les porte.
+ */
+export declare const HOP_BY_HOP: ReadonlySet<string>;
 /**
  * Sauts `Via` au-delà desquels un message est tenu pour une boucle. Notre
  * pseudonyme ne repère une boucle qu'au RETOUR dans ce processus : derrière un
@@ -55,6 +62,19 @@ export declare const MAX_VIA_HOPS = 10;
  * @param pseudonym - pseudonyme de ce processus
  */
 export declare function viaLoops(via: string | string[] | undefined, pseudonym: string): boolean;
+/**
+ * `Max-Forwards` reçu, tel qu'un intermédiaire doit le lire (RFC 9110 §7.6.2) :
+ * sur `OPTIONS` et `TRACE` seulement — la même section permet de l'ignorer
+ * pour toute autre méthode, et il part alors tel quel.
+ *
+ * @param method - méthode de la requête
+ * @param value - en-tête `Max-Forwards` reçu
+ * @returns `null` s'il n'y a rien à faire (autre méthode, en-tête absent) ;
+ *   `-1` si la valeur n'est pas `1*DIGIT` — elle ne se décrémente pas, l'en-tête
+ *   n'est donc pas transmis ; sinon la valeur reçue (`0` : le proxy répond
+ *   lui-même, sans joindre l'amont).
+ */
+export declare function receivedMaxForwards(method: string, value: string | string[] | undefined): number | null;
 /**
  * Cadrage du corps transmis à l'amont (RFC 9112 §6). `unsupported` : un
  * codage de transfert autre que `chunked` seul — le proxy ne sait pas le
@@ -118,8 +138,9 @@ export declare function upstreamPath(url: string, mount: IProxyMount): string;
  * Relaie une requête HTTP vers l'amont et renvoie sa réponse au client.
  *
  * Le corps est transmis avec un cadrage cohérent ({@link bodyFramingOf}). Un
- * message qui porte déjà notre `Via` rend 508 sans contacter l'amont. Un
- * client parti coupe l'échange amont ; un amont injoignable rend 502 ; une
+ * message qui porte déjà notre `Via` rend 508 sans contacter l'amont. Sur
+ * `OPTIONS` et `TRACE`, `Max-Forwards` est décrémenté ; à `0`, le proxy répond
+ * lui-même en destinataire final (RFC 9110 §7.6.2). Un client parti coupe l'échange amont ; un amont injoignable rend 502 ; une
  * connexion non établie à temps ou un amont muet rendent 504 — à condition
  * que rien n'ait encore été envoyé, sinon la réponse est interrompue (un
  * statut ne se rattrape pas). Un amont coupé en plein corps interrompt la
@@ -154,6 +175,20 @@ export declare function rawHead(status: string, rawHeaders: readonly string[], s
  * @param headers - en-têtes du refus (`WWW-Authenticate`, `Retry-After`…)
  */
 export declare function refuseUpgrade(socket: Duplex, status: number, reason: string, headers?: Readonly<Record<string, string | number>> | null): void;
+/**
+ * Refuse un handshake WebSocket non conforme — la réponse qui convient à la
+ * raison rendue par `websocketHandshakeProblem`, seule implémentation pour le
+ * serveur WebSocket ET le proxy inverse.
+ *
+ * Une version inconnue reçoit `426` avec `Sec-WebSocket-Version: 13` : le
+ * client apprend vers quelle version se rabattre (RFC 6455 §4.2.2 point 6,
+ * §4.4), et le 426 porte l'`Upgrade` qu'exige RFC 9110 §15.5.22. Tout autre
+ * défaut de forme reçoit `400`.
+ *
+ * @param socket - socket du client, encore en attente de sa réponse
+ * @param problem - la raison rendue par `websocketHandshakeProblem`
+ */
+export declare function refuseMalformedHandshake(socket: Duplex, problem: string): void;
 /**
  * Relaie un upgrade WebSocket DÉJÀ validé (méthode, `Upgrade`, clé, version,
  * `Origin` — cf `ReverseProxy.handleUpgrade`) : rejoue le handshake vers

package/dist/types/nodefony/src/proxy/generateProxyConfig.d.ts

@@ -44,8 +44,9 @@ export interface ProxyIntrospection {
     httpsPort: number;
     /**
      * Port h2c du backend (`servers.h2c`), ou `null` s'il n'est pas activé. Le
-     * générateur haproxy y envoie le trafic en HTTP/2 (`proto h2`) ; nginx, qui
-     * ne parle pas HTTP/2 à ses amonts, l'ignore.
+     * générateur haproxy y envoie tout le trafic hors WebSocket (`proto h2`) ;
+     * nginx, qui ne parle HTTP/2 à ses amonts que par `grpc_pass`, n'y envoie
+     * que gRPC. Règle d'usage : {@link upstreamH2cPort}.
      */
     h2cPort?: number | null;
     /** Dossiers statiques servis à la racine `/` (ordre = priorité). */
@@ -98,6 +99,18 @@ export interface ProxyIntrospection {
 }
 /** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
 export declare const defaultIntrospection: ProxyIntrospection;
+/**
+ * Port h2c que le proxy doit joindre, ou `null` — règle UNIQUE des deux
+ * générateurs.
+ *
+ * Seulement vers un backend en clair : le re-chiffrement vise le port TLS, qui
+ * négocie déjà HTTP/2 par ALPN, et mélanger les deux liens ferait voyager une
+ * partie du trafic en clair alors que l'utilisateur a demandé le chiffrement.
+ *
+ * @param intro - modèle d'introspection Nodefony.
+ * @returns le port h2c à joindre, ou `null` s'il n'y a pas de lien h2c.
+ */
+export declare function upstreamH2cPort(intro: ProxyIntrospection): number | null;
 /**
  * Génère une configuration nginx complète (reverse-proxy + offload statiques).
  *

package/dist/types/nodefony/src/proxy/rules.d.ts

@@ -73,6 +73,26 @@ export declare function proxyMountProblems(prefix: string, mount: IProxyMountSha
  * @returns `true` si le chemin doit être refusé
  */
 export declare function isAmbiguousPath(url: string): boolean;
+/**
+ * Le corps reçu porte-t-il un codage de transfert que le serveur ne sait pas
+ * défaire ? Seul `chunked` est compris : Node le retire, mais laisse en place
+ * tout codage qui le précède (`gzip, chunked`) — le corps livré serait encore
+ * compressé. RFC 9112 §6.1 : un tel message reçoit 501. Un `chunked` qui n'est
+ * pas le DERNIER codage est déjà refusé par Node en 400 (§6.3).
+ *
+ * Seule règle, pour le serveur d'origine et pour le proxy inverse. Chemin de
+ * chaque requête : une lecture d'en-tête, rien d'autre sans `Transfer-Encoding`.
+ *
+ * @param coding - valeur de l'en-tête `Transfer-Encoding`, absente le plus souvent
+ * @returns `true` quand le corps ne peut pas être lu tel qu'annoncé
+ */
+export declare function isUnsupportedTransferCoding(coding: string | undefined): boolean;
+/**
+ * Raison rendue par {@link websocketHandshakeProblem} quand le client parle une
+ * autre version du protocole : la seule qui appelle une réponse distincte —
+ * le client doit apprendre vers quelle version se rabattre (RFC 6455 §4.4).
+ */
+export declare const WS_UNSUPPORTED_VERSION = "Sec-WebSocket-Version \u2260 13";
 /**
  * Un upgrade est-il un handshake WebSocket conforme (RFC 6455 §4.2.1) ? Seul
  * un tel handshake est relayé : un `Upgrade` quelconque (`h2c`…) raccordé

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/dist/types/nodefony/src/servers/upgradeDispatch.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";
-import type { WebSocket, WebSocketServer } from "ws";
+import { WebSocketServer, type ServerOptions, type WebSocket } from "ws";
 /** Serveur qui émet `upgrade` : HTTP/1.1, HTTPS ou HTTP/2 sécurisé (`allowHTTP1`). */
 interface IUpgradeEmitter {
     on(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
@@ -26,6 +26,18 @@ export interface IUpgradeAdmission {
      *   le handshake) — il n'y a alors rien à servir
      */
     accept(): WebSocket | null | Promise<WebSocket | null>;
+    /**
+     * Retient le sous-protocole que le serveur renverra dans le `101` (RFC 6455
+     * §4.2.2 : « the subprotocol the server is ready to use »), à appeler AVANT
+     * {@link accept}. Sans choix, la règle d'avant s'applique : l'option
+     * `handleProtocols` de la configuration `ws`, sinon le premier offert.
+     *
+     * Un choix absent de l'offre du client n'est jamais renvoyé — la norme ne
+     * permet que l'un des sous-protocoles offerts, ou aucun.
+     *
+     * @param protocol - le sous-protocole choisi, `false` pour n'en renvoyer aucun
+     */
+    selectSubprotocol(protocol: string | false): void;
     /**
      * Refuse par un statut HTTP, AVANT le `101` (RFC 6455 §4.2.2).
      *
@@ -36,6 +48,34 @@ export interface IUpgradeAdmission {
 }
 /** Ce qui décide d'un upgrade : reçoit la requête et rend son verdict, plus tard s'il le faut. */
 export type UpgradeAdmit = (req: IncomingMessage, admission: IUpgradeAdmission) => void;
+/** Signature de l'option `handleProtocols` de `ws` (`ServerOptions`). */
+export type SubprotocolHandler = (protocols: Set<string>, request: IncomingMessage) => string | false;
+/**
+ * Fabrique l'option `handleProtocols` du serveur `ws` de Nodefony : le choix
+ * retenu par l'admission ({@link IUpgradeAdmission.selectSubprotocol}) s'il y
+ * en a un, sinon `fallback` (celle de la configuration), sinon le premier
+ * offert — le défaut de `ws` 8, conservé pour tout contrôleur qui ne choisit
+ * pas.
+ *
+ * @param fallback - l'option `handleProtocols` de la configuration, s'il y en a une
+ * @returns le rappel à passer à `new WebSocketServer({ handleProtocols })`
+ */
+export declare function createSubprotocolHandler(fallback?: SubprotocolHandler): SubprotocolHandler;
+/**
+ * Construit le serveur `ws` de Nodefony à partir des options de la
+ * configuration, en forçant ce que Nodefony gère — seul endroit où ces
+ * options sont posées, pour le serveur clair comme pour le sécurisé :
+ *
+ * - `noServer` : l'upgrade passe d'abord par le proxy inverse, puis par
+ *   {@link attachUpgradeDispatch} ;
+ * - `clientTracking` : requis par `broadcast()` et le heartbeat ;
+ * - `handleProtocols` : le sous-protocole CHOISI par le contrôleur
+ *   ({@link createSubprotocolHandler}), celui de la configuration à défaut.
+ *
+ * @param options - options `ws` issues de la configuration du serveur WebSocket
+ * @returns le serveur, sans écoute propre
+ */
+export declare function createNodefonyWebSocketServer(options: ServerOptions): WebSocketServer;
 /**
  * Pose l'UNIQUE écouteur `upgrade` d'un serveur : le proxy inverse d'abord,
  * puis le serveur WebSocket de Nodefony.