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

package/dist/types/nodefony/src/context/http/urlFastPath.d.ts

@@ -36,6 +36,46 @@ export interface ISplitTarget {
  * @returns les composants découpés, ou `null` (bail-out → vrai `new URL`).
  */
 export declare function splitTarget(target: unknown): ISplitTarget | null;
+/** Un request-target en forme absolue, découpé en autorité et forme origine. */
+export interface IAbsoluteTarget {
+    /** `hôte[:port]` de la cible — l'hôte de la requête (RFC 9112 §3.2.2). */
+    authority: string;
+    /** La forme origine (`/chemin[?query]`), `/` quand la cible n'a pas de chemin. */
+    target: string;
+}
+/**
+ * Découpe un request-target en forme absolue (`http://hôte:port/chemin?q`) :
+ * la forme qu'un client envoie à un proxy, et qu'un serveur d'origine DOIT
+ * accepter (RFC 9112 §3.2.2). Il DOIT alors ignorer l'en-tête `Host` et prendre
+ * l'hôte de la cible — le recoller à `Host` fabriquait un hôte qui n'existe pas.
+ *
+ * Seuls `http` et `https` sont reconnus (RFC 6455 §4.2.1 vaut aussi pour un
+ * handshake WebSocket) ; le schéma de la cible ne remplace jamais celui de la
+ * connexion. Une autorité porteuse d'identifiants (`user@hôte`, interdite par
+ * RFC 9110 §4.2.4) n'est pas reconnue : `Host` garde la main.
+ *
+ * Chemin de chaque requête : un seul test de caractère pour la forme origine,
+ * aucune allocation.
+ *
+ * @param target - le request-target brut, tel que reçu.
+ * @returns l'autorité et la forme origine, ou `null` pour toute autre forme.
+ */
+export declare function splitAbsoluteForm(target: string | undefined): IAbsoluteTarget | null;
+/**
+ * Analyse un request-target origin-form (`/chemin[?query]`) dans la forme
+ * NORMALISÉE que la porte HTTP donne au routeur (`HttpRequest`) : découpe exacte
+ * quand le parse WHATWG serait l'identité ({@link splitTarget}), vrai parse
+ * WHATWG sinon — dot-segments résolus, `\` replié, percent-encoding posé.
+ *
+ * Pour qui reçoit un chemin hors d'une requête HTTP — le pont WebSocket
+ * `api.request` — et doit router exactement comme HTTP : la même chaîne, deux
+ * transports, une seule forme.
+ *
+ * @param target - le chemin reçu ; il doit commencer par `/`.
+ * @returns pathname et search normalisés, ou `null` si `target` n'est pas un
+ *   chemin origin-form analysable.
+ */
+export declare function parseRequestTarget(target: string): ISplitTarget | null;
 /**
  * L'autorité (`host[:port]` brut de l'en-tête `Host` / `:authority`) est-elle
  * déjà sous la forme exacte que le parseur WHATWG rendrait ?

package/dist/types/nodefony/src/context/http2/Response.d.ts

@@ -9,8 +9,9 @@ interface IHeaderSource {
     getHeader(name: string): http.OutgoingHttpHeader | undefined;
 }
 /**
- * Compose les en-têtes d'une réponse HTTP/2 : ceux posés sur la réponse, puis
- * ceux passés à `writeHead`, qui gagnent.
+ * Compose les en-têtes d'une réponse HTTP/2 : ceux qu'un tiers a écrits sur la
+ * réponse Node, puis ceux de la réserve de la réponse, puis ceux passés à
+ * `writeHead` — chacun l'emporte sur le précédent.
  *
  * Les clés sont ramenées en MINUSCULES : `getHeaders()` rend `content-type`,
  * un contrôleur passe `Content-Type` — fusionnées telles quelles, les deux
@@ -26,9 +27,10 @@ interface IHeaderSource {
  * @param statusMessage - message de statut, recopié en `x-status-message`
  * @param current - la réponse Node qui porte les en-têtes déjà posés
  * @param extra - en-têtes passés à `writeHead` (objet, ou liste plate clé/valeur)
+ * @param stored - la réserve de la réponse, liste plate aux noms en minuscules
  * @returns les en-têtes à transmettre à `respond()`
  */
-export declare function mergeResponseHeaders(statusMessage: string, current: IHeaderSource, extra?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): http.OutgoingHttpHeaders;
+export declare function mergeResponseHeaders(statusMessage: string, current: IHeaderSource, extra?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[], stored?: readonly http.OutgoingHttpHeader[]): http.OutgoingHttpHeaders;
 declare class Http2Response extends HttpResponse {
     statusCode: number;
     stream: http2.ServerHttp2Stream | null;

package/dist/types/nodefony/src/context/transport.d.ts

@@ -51,3 +51,20 @@ export declare function requestAuthority(headers: {
     host?: string | undefined;
     ":authority"?: string | undefined;
 }): string | undefined;
+/**
+ * Une requête HTTP/2 nomme-t-elle deux hôtes — `:authority` ET un `Host`
+ * différent ? RFC 9113 §8.3.1 : « SHOULD treat a request as malformed ». Le
+ * serveur lit `:authority` ({@link requestAuthority}), mais un code qui lit
+ * `headers.host` verrait un autre hôte que celui que le routage et le
+ * pare-feu ont jugé.
+ *
+ * Chemin de chaque requête : une lecture d'en-tête ; la comparaison n'a lieu
+ * que si les deux sont présents (un navigateur n'envoie pas `Host` en HTTP/2).
+ *
+ * @param headers - en-têtes de la requête Node.
+ * @returns `true` quand les deux autorités diffèrent (casse ignorée).
+ */
+export declare function hasConflictingAuthority(headers: {
+    host?: string | undefined;
+    ":authority"?: string | undefined;
+}): boolean;

package/dist/types/nodefony/src/context/websocket/WebsocketContext.d.ts

@@ -1,6 +1,7 @@
 import Context from "../Context.js";
 import { ServerType, SchemeType } from "../../../service/http-kernel.js";
 import { Severity, Msgid, Message, nodefonyError, Scope } from "nodefony";
+import type { IFrameCodec } from "nodefony";
 import Ws from "ws";
 import type { IncomingMessage } from "node:http";
 import WebsocketResponse from "./Response.js";
@@ -11,6 +12,7 @@ import HttpError from "../../errors/httpError.js";
 import { FrameProfile } from "../../profiler/FrameProfile.js";
 import type { PhaseName, IWebsocketContext } from "../../../interfaces/IContext.js";
 import { ProxyType } from "../http/HttpContext.js";
+import { type IFrameRateWindow } from "./wsFrameRate.js";
 import { type ResolvedProxy } from "../forwarded.js";
 export interface IWsRequestExtension {
     url: URL;
@@ -70,10 +72,22 @@ declare class WebsocketContext extends Context implements IWebsocketContextInter
     request: WsIncomingMessage | null;
     response: WebsocketResponse | null;
     acceptedProtocol?: string | undefined;
+    /**
+     * Codec des trames BINAIRES de cette connexion, posé par la couche qui l'a négocié
+     * (le temps réel, ADR-0022 §2). Hors production, le traceur s'en sert pour
+     * afficher une trame binaire décodée plutôt que sa seule taille ; jamais lu en
+     * production. `null` = octets bruts, résumés à leur taille.
+     */
+    frameCodec: IFrameCodec | null;
     port: number | string;
     rejected: boolean;
     teardownWired: boolean;
     connection: Ws | null;
+    /**
+     * Fenêtre de la borne de débit entrante — `null` tant que la borne est
+     * désactivée ou qu'aucune trame n'est arrivée (créée au premier usage).
+     */
+    frameRate: IFrameRateWindow | null;
     /**
      * Le verdict du handshake encore à rendre : posé par le noyau tant que le
      * pipeline décide (pare-feu, garde de l'action), `null` dès que la socket
@@ -110,6 +124,22 @@ declare class WebsocketContext extends Context implements IWebsocketContextInter
     render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>;
     send(data?: string | Buffer | null, encoding?: BufferEncoding): Promise<WebsocketResponse>;
     broadcast(data?: string | Buffer | null, encoding?: BufferEncoding): null | undefined;
+    /**
+     * Le contenu des messages est-il journalisé ? Hors production seulement —
+     * décidé une fois pour le processus (P8 : runtime ∈ {development, production},
+     * `resolveRuntimeEnv`).
+     */
+    private tracesMessageContent;
+    /**
+     * Traceur des trames SORTANTES écrites hors de {@link send} — le temps réel
+     * écrit droit sur la socket. À demander UNE fois par connexion : `null` en
+     * production, donc l'appelant choisit son chemin d'écriture à l'ouverture et
+     * ne paie rien par trame.
+     *
+     * @returns une fonction qui journalise une trame comme `send` (`WS SEND`),
+     *   ou `null` quand le contenu des messages n'est pas journalisé.
+     */
+    outboundTracer(): ((data: unknown) => void) | null;
     /**
      * Logge le CONTENU d'un message WS (corrélé `requestId` via l'override `log`),
      * gaté hors prod et borné — le Suivi de requête (Studio) le surface alors par
@@ -150,6 +180,16 @@ declare class WebsocketContext extends Context implements IWebsocketContextInter
      */
     phaseStart(name: PhaseName): void;
     phaseEnd(name: PhaseName): void;
+    /**
+     * Applique la borne de débit entrante à une trame : `true` = l'admettre.
+     *
+     * Écartée → comptée (`frameRateRejectedTotal`) ; solde de refus atteint →
+     * connexion fermée en `1008` (RFC 6455 §7.4.1, violation de politique).
+     *
+     * @param bound - trames admises par seconde (`> 0`)
+     * @returns `true` si la trame poursuit son chemin
+     */
+    private admitInboundFrame;
     handleMessage(data: Buffer | string, isBinary: boolean): Promise<unknown>;
     onClose(code: number, reason: Buffer): void;
     /**

package/dist/types/nodefony/src/context/websocket/websocketUrl.d.ts

@@ -7,6 +7,10 @@
  * un hôte de l'autre — et une route acceptée par l'une serait refusée par
  * l'autre.
  *
+ * Une cible en forme absolue (`http://hôte/chemin`, RFC 6455 §4.2.1) donne son
+ * hôte, et l'en-tête `Host` est ignoré (RFC 9112 §3.2.2) — la même règle que
+ * `HttpRequest.getHost`.
+ *
  * @param scheme - `ws` ou `wss`
  * @param host - en-tête `Host` de la requête (`localhost` s'il manque)
  * @param rawUrl - cible brute de la requête (`/` si elle manque)

package/dist/types/nodefony/src/context/websocket/wsBackpressure.d.ts

@@ -1,6 +1,7 @@
 import Ws, { WebSocketServer } from "ws";
+import { type BackpressurePolicy, type BackpressureVerdict } from "nodefony";
 /** Politique appliquée quand le buffer d'envoi d'un client dépasse le seuil. */
-export type WsBackpressurePolicy = "drop" | "close";
+export type WsBackpressurePolicy = BackpressurePolicy;
 /**
  * Options de backpressure SORTANTE (serveur → client).
  *
@@ -24,6 +25,10 @@ export interface IWsBackpressureOptions {
 export interface IBackpressureTarget {
     readonly bufferedAmount?: number;
     close(code?: number, reason?: string): void;
+    /** Cumul des frames refusées pour contre-pression (lazy — lu par la sonde socket). */
+    _nfDrops?: number;
+    /** Solde de refus courant (cf {@link nextDropBalance}) ; absent = 0. */
+    _nfDropStreak?: number;
 }
 /** Socket augmentée d'un compteur de drops (number lazy — lu par la sonde socket). */
 export interface IBackpressureSocket extends Ws {
@@ -37,7 +42,7 @@ export interface IBackpressureSocket extends Ws {
     _nfDropStreak?: number;
 }
 /** Décision pour une frame : l'émettre, la sauter, ou (socket fermée) ne rien faire. */
-export type WsSendDecision = "send" | "drop" | "close";
+export type WsSendDecision = BackpressureVerdict;
 /**
  * Relit le seuil + la politique depuis les options du `WebSocketServer`.
  *
@@ -65,9 +70,14 @@ export declare const readBackpressureOptions: (wss: WebSocketServer | null | und
  * « Try Again Later » → le client peut back-off + reconnecter). NE FAIT PAS le `send()`
  * — le caller émet uniquement si le retour vaut `"send"`.
  *
+ * La DÉCISION est celle du cœur (`decideBackpressure` / `nextDropBalance`, partagée
+ * avec `NodefonySocket`) ; cette fonction n'en porte que l'état (compteurs sur la
+ * socket) et le geste serveur (fermeture `1013`).
+ *
  * @param ws - la socket destinataire
  * @param max - seuil d'octets (`<= 0` → désactivé)
  * @param policy - action au dépassement
+ * @param closeAfterDrops - solde de refus qui ferme (`0` = jamais)
  * @returns `"send"` (émettre) · `"drop"` (sauter cette frame) · `"close"` (socket fermée)
  */
 export declare const decideSend: (ws: IBackpressureTarget, max: number, policy: WsBackpressurePolicy, closeAfterDrops?: number) => WsSendDecision;

package/dist/types/nodefony/src/context/websocket/wsFrameRate.d.ts

@@ -0,0 +1,69 @@
+import { type BackpressureVerdict } from "nodefony";
+/**
+ * Options de la borne de débit ENTRANTE (client → serveur), lues dans `wss.options`.
+ *
+ * Knobs Nodefony (pas des options `ws`), conservés par le spread du constructeur
+ * de `ws` — même voie que `IWsBackpressureOptions`.
+ */
+export interface IWsFrameRateOptions {
+    /** Trames reçues admises par seconde et par connexion ; `0`/absent = désactivée. */
+    maxFramesPerSecond?: number;
+    /** Solde de trames écartées qui ferme la connexion (`1008`) ; `0` = jamais. */
+    frameRateCloseAfterRejects?: number;
+}
+/**
+ * Fenêtre de comptage d'une connexion, créée à la PREMIÈRE trame reçue borne activée.
+ *
+ * Mutée en place : aucune allocation par trame.
+ */
+export interface IFrameRateWindow {
+    /** Début de la fenêtre courante (ms, `Date.now()`). */
+    start: number;
+    /** Trames reçues dans la fenêtre courante. */
+    count: number;
+    /** Solde de refus (+1 par trame écartée, −1 par trame admise). */
+    balance: number;
+}
+/** Durée d'une fenêtre de comptage (ms) : la borne s'exprime en trames PAR SECONDE. */
+export declare const FRAME_RATE_WINDOW_MS = 1000;
+/**
+ * Nombre cumulé de trames entrantes écartées par la borne de débit dans ce processus (unité : une trame reçue).
+ *
+ * Monotone, `0` tant que la borne est désactivée. Relayé par la sonde du hub
+ * temps réel sous le nom figé `frameRateRejectedTotal` (ADR-0021 §S9).
+ *
+ * @returns le cumul depuis le démarrage du processus
+ */
+export declare const frameRateRejectedTotal: () => number;
+/**
+ * Borne de débit entrante du serveur WebSocket (`maxFramesPerSecond`) ; `0` = désactivée.
+ *
+ * Appelée à chaque trame : une lecture de propriété, aucune allocation.
+ *
+ * @param server - le serveur du contexte (`context.server`)
+ * @returns trames admises par seconde, `0` si la borne est désactivée
+ */
+export declare const readFrameRateBound: (server: unknown) => number;
+/**
+ * Solde de refus qui ferme la connexion (`frameRateCloseAfterRejects`) ; `0` = jamais.
+ *
+ * @param server - le serveur du contexte (`context.server`)
+ * @returns le solde de fermeture
+ */
+export declare const readFrameRateCloseAfter: (server: unknown) => number;
+/**
+ * Décide du sort d'une trame reçue, AVANT tout décodage : l'admettre, l'écarter, ou fermer la connexion.
+ *
+ * Compte des TRAMES, pas des octets (`maxPayload` borne déjà la taille). La
+ * décision est la règle unique du cœur (`decideBackpressure`), appliquée au
+ * nombre de trames de la fenêtre : écarter au-delà de la borne, fermer quand le
+ * solde de refus atteint `closeAfter` — jamais au premier dépassement. Une
+ * trame écartée est comptée dans {@link frameRateRejectedTotal}.
+ *
+ * @param win - la fenêtre de la connexion (mutée)
+ * @param now - l'instant de réception (ms)
+ * @param bound - trames admises par seconde (`> 0`)
+ * @param closeAfter - solde de refus qui ferme (`0` = jamais)
+ * @returns `"send"` (admettre), `"drop"` (écarter) ou `"close"` (fermer en `1008`)
+ */
+export declare const admitFrame: (win: IFrameRateWindow, now: number, bound: number, closeAfter: number) => BackpressureVerdict;

package/dist/types/nodefony/src/context/websocket/wsLogContent.d.ts

@@ -1,15 +1,18 @@
 /**
- * Formatage **pur** (0 état, 0 dépendance) du CONTENU d'un message WebSocket pour
- * le log de trace (Suivi de requête Studio). Séparé de `WebsocketContext` pour
- * être testable aux limites sans serveur.
+ * Formatage **pur** (0 état) du CONTENU d'un message WebSocket pour le log de trace
+ * (Suivi de requête Studio). Séparé de `WebsocketContext` pour être testable aux
+ * limites sans serveur.
  *
  * 🔒 Robustesse binaire (cf doc `ws` — `socket.send(data)` accepte
  * `String | Number | Object | Buffer | ArrayBuffer | TypedArray | DataView |
  * Buffer[] | Blob`, et l'event `message` livre `Buffer | ArrayBuffer | Buffer[]`).
- * **Toute** charge binaire est résumée `[binary N B]` — JAMAIS sérialisée
- * (`JSON.stringify(new Uint8Array(...))` produirait `{"0":..,"1":..}`, énorme et
- * faux). Seules string et objets « JSON » sont rendus en texte (borné).
+ * **Toute** charge binaire est résumée `[binary N B]` — JAMAIS vidée octet par
+ * octet (`JSON.stringify(new Uint8Array(...))` produirait `{"0":..,"1":..}`, énorme
+ * et faux). Quand la connexion a négocié un codec de frame (CBOR, ADR-0022 §2), la
+ * trame est en plus DÉCODÉE pour être lisible : le débogage se fait à l'observation,
+ * jamais en changeant le fil.
  */
+import { type IFrameCodec } from "nodefony";
 /** Cap de troncature du contenu loggé (octets/chars). Borne ring + JSONL. */
 export declare const WS_LOG_CONTENT_CAP = 4096;
 /**
@@ -26,12 +29,17 @@ export declare function binaryByteLength(data: unknown): number;
 /**
  * Formate une charge utile WS en chaîne **bornée** et **sûre** pour le log :
  *  - `string` → tronquée à `cap` (+ ellipse) ;
- *  - binaire (cf {@link binaryByteLength}) → `[binary N B]` (jamais de dump) ;
+ *  - binaire (cf {@link binaryByteLength}) → `[binary N B]` (jamais de vidage) ;
+ *    avec un `codec`, une trame d'un seul tenant est aussi décodée :
+ *    `[binary N B] <protocole> <frame en JSON>`, octets imbriqués étiquetés ;
+ *    illisible → `[binary N B] <protocole> illisible` ;
  *  - `null`/`undefined` → `""` ;
  *  - objet « JSON » → `JSON.stringify` compact tronqué (cycle, `bigint`, valeur
  *    non sérialisable → repli `String(...)`).
  *
  * @param data - charge utile (RECEIVE/SEND/BROADCAST).
  * @param cap - longueur max avant troncature (défaut {@link WS_LOG_CONTENT_CAP}).
+ * @param codec - codec des trames binaires de la connexion, `null` = octets bruts.
+ * @returns la ligne à journaliser, jamais plus longue que `cap` + 1.
  */
-export declare function formatWsLogContent(data: unknown, cap?: number): string;
+export declare function formatWsLogContent(data: unknown, cap?: number, codec?: IFrameCodec | null): string;

package/dist/types/nodefony/src/cookies/cookie.d.ts

@@ -19,7 +19,6 @@ declare module "http2" {
  * externe nomme le type par `ICookieOptions`, exporté au barrel.
  */
 export type CookieOptionsType = ICookieOptions;
-declare function parser(strToParse: string): import("cookie").Cookies;
 declare function cookiesParser(context: ContextType): void;
 declare class Cookie implements ICookieInterface {
     options: CookieOptionsType;
@@ -57,7 +56,26 @@ declare class Cookie implements ICookieInterface {
     setExpires(date: Date | string | number | undefined): Date | undefined;
     setOriginalMaxAge(ms: number | StringValue): number;
     setPriority(val: PriorityType): PriorityType;
+    /**
+     * Durée de vie restante en SECONDES ENTIÈRES, `undefined` sous une seconde.
+     *
+     * RFC 6265 §4.1.1 : `max-age-av = "Max-Age=" non-zero-digit *DIGIT`. Un
+     * `Max-Age=3599.874` est ignoré par le navigateur, et le cookie devient un
+     * cookie de session. Arrondi INFÉRIEUR : le cookie ne survit jamais à son
+     * `Expires`.
+     */
     getMaxAge(): number | undefined;
+    /**
+     * Vérifie la grammaire RFC 6265 §4.1.1 du nom, du `Path` et du `Domain`,
+     * au moment où le cookie est POSÉ sur la réponse.
+     *
+     * Sans elle, `path: "/; Domain=evil.example"` injectait un attribut, et un
+     * nom porteur de `;` partait tel quel. La grammaire est celle du paquet
+     * `cookie` : une seule implémentation.
+     *
+     * @throws {TypeError} nommant l'attribut hors grammaire.
+     */
+    assertGrammar(): void;
     toString(): string;
     /**
      * Signe une valeur de cookie : `HMAC-SHA256(value)` clé = `secret`, encodé en
@@ -85,4 +103,4 @@ declare class Cookie implements ICookieInterface {
     serializeWebSocket(): IWsCookie;
 }
 export default Cookie;
-export { cookiesParser, parser };
+export { cookiesParser };

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

@@ -55,6 +55,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 +131,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 +168,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/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/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.