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

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

@@ -7,6 +7,7 @@ import http2 from "node:http2";
 import http from "node:http";
 import https from "node:https";
 import HttpKernel, { ServerType, Data, SchemeType } from "../../service/http-kernel.js";
+import type { AlpnProtocol, ProtocolName } from "../../interfaces/IContext.js";
 import HttpResponse from "./http/Response.js";
 import Http2Response from "./http2/Response.js";
 import WebsocketResponse from "./websocket/Response.js";
@@ -50,7 +51,15 @@ declare class Context extends Service implements IContextInterface {
     requested: boolean;
     sessionStarting: boolean;
     domain: string;
-    type: ServerType;
+    /** Famille traitée (`network.protocol.name` d'OpenTelemetry) — union ouverte. */
+    type: ProtocolName;
+    /** Serveur qui a reçu la requête — choisit la configuration par serveur. */
+    serverType: ServerType;
+    /**
+     * Protocole du saut local (registre IANA ALPN) — union ouverte. Une connexion
+     * WebSocket naît d'un upgrade HTTP/1.1 ; `HttpContext` le constate sur la requête.
+     */
+    alpnProtocol: AlpnProtocol;
     server?: WebSocketServer | http.Server | https.Server | http2.Http2SecureServer | null | undefined;
     httpKernel: HttpKernel | null;
     request: contextRequest | null;
@@ -88,6 +97,12 @@ declare class Context extends Service implements IContextInterface {
     crossDomain: boolean;
     router: IRequestRouter | null;
     resolver: IRouteResolver | null;
+    /**
+     * Module qui signe les lignes de CETTE requête : la ligne d'accès et les
+     * lignes du contrôleur. `null` = le module de la route (sans route : le
+     * journal du noyau). Un contrôleur le change : `this.context.logModule = "billing"`.
+     */
+    logModule: string | null;
     /**
      * Intent de session de la route courante (posé par le Resolver depuis
      * `@UseSession` / paramètre `@Session`). Pilote le point d'activation unique
@@ -119,6 +134,9 @@ declare class Context extends Service implements IContextInterface {
     securityTrace: ISecurityTrace | null;
     private readonly _timingEnabled;
     private readonly _timingVerbose;
+    private readonly _clockEnabled;
+    private readonly _clockStartMs;
+    private _durationMs;
     readonly phases: PhaseTiming[];
     private _phaseIndex;
     private _afterResponseFns;
@@ -128,7 +146,7 @@ declare class Context extends Service implements IContextInterface {
     metaData: Data;
     scheme: SchemeType;
     webSocketState: WebSocketState;
-    constructor(container: Container | Scope, type: ServerType);
+    constructor(container: Container | Scope, serverType: ServerType);
     /**
      * Assemble l'enveloppe `metaData` de la requête (`nodefony.*` + `route`
      * snapshot per-requête + overrides appelant). Délègue au builder monomorphe
@@ -152,6 +170,21 @@ declare class Context extends Service implements IContextInterface {
     get timingEnabled(): boolean;
     phaseStart(name: PhaseName): void;
     phaseEnd(name: PhaseName): void;
+    /**
+     * Arrête l'horloge de la requête et rend sa durée, en millisecondes.
+     *
+     * La durée court de la construction du contexte au PREMIER appel : le
+     * démontage HTTP (`close` de la réponse, dernier octet remis — la mesure
+     * d'OpenTelemetry et du `$request_time` de nginx), la ligne d'accès pour un
+     * handshake WebSocket. Les appels suivants rendent la même valeur : journal
+     * d'accès, profiler et trace verbose lisent UNE durée, jamais trois.
+     *
+     * Active par défaut dans tous les environnements, production comprise :
+     * seul `timing.enabled: false` la coupe (cf `resolveTimingMode`).
+     *
+     * @returns la durée, ou `null` si `timing.enabled` vaut `false`
+     */
+    stopClock(): number | null;
     onAfterResponse(fn: AfterResponseHandler): void;
     /**
      * Exécute les hooks `onAfterResponse`, une seule fois, dans l'ordre
@@ -167,7 +200,7 @@ declare class Context extends Service implements IContextInterface {
     private runAfterResponseHooks;
     get signal(): AbortSignal;
     _abortIfPending(reason?: string): void;
-    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): Pdu;
     /**
      * Confie au contexte le magasin `RequestContext` de son unité de travail
      * (requête HTTP, connexion WebSocket), pour qu'il le VIDE à son nettoyage.
@@ -183,8 +216,8 @@ declare class Context extends Service implements IContextInterface {
     clean(): void;
     /**
      * Log d'un event du cycle de vie — gate boot-time (V2.1) : en production le
-     * Pdu n'est PAS construit (return avant toute allocation). Hors prod, jalon
-     * notable → INFO (EVENT_SEVERITY), event technique → DEBUG.
+     * Pdu n'est PAS construit (return avant toute allocation). Hors prod : DEBUG,
+     * pour le Suivi de requête de Studio — la ligne `req` porte le bilan.
      */
     private logEvent;
     fire(event: KernelEventsType, ...args: unknown[]): boolean;

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

@@ -1,6 +1,7 @@
 import { ServerType, SchemeType } from "../../../service/http-kernel.js";
+import HttpError from "../../errors/httpError.js";
 import Context, { HTTPMethod } from "../Context.js";
-import { Container, Scope } from "nodefony";
+import { Container, Scope, nodefonyError } from "nodefony";
 import type { MaybePromise } from "nodefony";
 import HttpRequest from "./Request.js";
 import HttpResponse from "./Response.js";
@@ -50,10 +51,15 @@ declare class HttpContext extends Context implements IHttpContextInterface {
     private activeSocket;
     isRedirect: boolean;
     sended: boolean;
+    /**
+     * Requête relayée par le proxy inverse : la politique de ligne d'accès de
+     * son montage. `null` = servie par l'application (cas de toute requête).
+     */
+    relayAccessLog: "all" | "errors" | null;
     request: HttpRequestType;
     response: HttpRsponseType;
     uploadService: uploadService | null;
-    constructor(container: Container | Scope, request: http.IncomingMessage | http2.Http2ServerRequest, response: http.ServerResponse | http2.Http2ServerResponse, type: ServerType);
+    constructor(container: Container | Scope, request: http.IncomingMessage | http2.Http2ServerRequest, response: http.ServerResponse | http2.Http2ServerResponse, serverType: ServerType);
     /**
      * URL d'origine effective, construite À LA DEMANDE (1ʳᵉ lecture, puis
      * mémoïsée). `Origin` invalide ou `null` (RFC 6454) → repli sur l'URL de la
@@ -84,6 +90,14 @@ declare class HttpContext extends Context implements IHttpContextInterface {
      */
     handle(): MaybePromise<this>;
     setTimeout(): void;
+    /**
+     * Ligne d'accès — pour une requête RELAYÉE, avec le statut que l'amont a
+     * réellement rendu (le relais écrit la réponse brute, pas celle du
+     * contexte) ; un montage `accessLog: "errors"` ne l'écrit qu'en échec.
+     *
+     * @param httpError - l'erreur de la requête, s'il y en a une
+     */
+    logRequest(httpError?: Error | HttpError | nodefonyError | null): import("nodefony").Pdu | undefined;
     /**
      * Nettoie le contexte, et le DÉTACHE de sa socket h1 : la connexion
      * persistante survit à la requête, et l'entrée de `socketActiveContext`

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

@@ -5,6 +5,7 @@ import { URL } from "node:url";
 import { HTTPMethod, Cookies } from "../Context.js";
 import QS from "qs";
 import { ParserXml, ParserQs, Parser, acceptParser } from "./parser.js";
+import type { RequestBody } from "../../../interfaces/IRequest.js";
 import { UploadedFile } from "../../../service/upload/upload-service.js";
 import type { IParsedUploadFile, IUploadOptions } from "../../../interfaces/IUpload.js";
 import { Pci, Pdu, Message, Severity, Msgid } from "nodefony";
@@ -75,22 +76,24 @@ declare class HttpRequest {
     get url(): URL;
     set url(u: URL);
     parser: ParserType | null;
-    queryPost: Record<string, unknown>;
-    queryGet: Record<string, unknown>;
-    queryFile: UploadedFile[];
-    query: Record<string, unknown>;
     /**
-     * Le CORPS de la requête, parsé — nom universel de l'écosystème (Express,
-     * Fastify, NestJS), alias de {@link queryPost}.
-     *
-     * Ne pas confondre avec {@link query}, qui FUSIONNE la query string et le
-     * corps : `body` ne rend jamais un paramètre d'URL. Le data plane admin
-     * expose déjà cette sémantique (`IAdminRequest.body`) ; ce getter la rend
-     * disponible partout.
+     * Le CORPS de la requête, parsé (JSON, urlencoded, XML, champs multipart) —
+     * nom universel de l'écosystème (Express, Fastify, NestJS) et celui
+     * d'`IAdminRequest.body`. Jamais un paramètre d'URL : ceux-là sont dans
+     * {@link query}, et les deux ne fusionnent pas.
+     */
+    body: RequestBody;
+    /**
+     * Les fichiers reçus dans un corps multipart, déjà écrits dans le répertoire
+     * temporaire — lus par `@UploadedFile()` / `@UploadedFiles()`. Les champs
+     * texte du même corps sont dans {@link body}.
      *
-     * Getter (aucune allocation) : `queryPost` reste la source unique.
+     * Lecture seule : une requête sans upload rend un vide partagé et gelé,
+     * aucune allocation.
      */
-    get body(): Record<string, unknown>;
+    get files(): readonly UploadedFile[];
+    /** Les paramètres d'URL, seuls — jamais un champ du corps ({@link body}). */
+    query: Record<string, unknown>;
     queryStringOptions: (QS.IParseOptions & {
         decoder?: undefined;
     }) | undefined;
@@ -112,7 +115,7 @@ declare class HttpRequest {
      * remplace le `once("onRequestEnd")` du ctor qui allouait 1 onceWrapper +
      * 1 closure à CHAQUE requête.
      *
-     * Il porte le CORPS (`queryPost`), pas la fusion `query` : un seul sens de
+     * Il porte le CORPS (`body`), jamais les paramètres d'URL : un seul sens de
      * `body` dans tout le framework, celui de l'écosystème et d'`IAdminRequest`.
      */
     private fireRequestEnd;
@@ -228,7 +231,9 @@ declare class HttpRequest {
     /**
      * Scheme effectif côté client : `Forwarded`/`X-Forwarded-*` résolu de façon
      * canonique (this.forwarded, gated proxy de confiance) ; sinon le transport
-     * réel. HTTP/2 remplace la lecture du socket par le pseudo-header `:scheme`.
+     * réel. Vaut pour HTTP/2 aussi : le pseudo-en-tête `:scheme` vient du client
+     * (RFC 9113 §8.3.1) et n'est jamais cru — sur h2c, `:scheme: https` ferait
+     * passer une connexion claire pour chiffrée.
      */
     protected resolveScheme(request: http.IncomingMessage | http2.Http2ServerRequest): string;
     getFullUrl(request?: http.IncomingMessage | http2.Http2ServerRequest): string;

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

@@ -50,6 +50,17 @@ declare class HttpResponse {
     deleteCookieByName(name: string): boolean;
     setCookies(): void | http.ServerResponse<http.IncomingMessage>;
     setCookie(cookie: Cookie): void | http.ServerResponse<http.IncomingMessage>;
+    /**
+     * Journalise en DEBUG un cookie posé, sa VALEUR MASQUÉE : nom et attributs
+     * seulement. Le journal de développement se lit par le plan d'administration
+     * — un identifiant de session y entrerait chez quiconque le consulte.
+     * La ligne n'est construite que si DEBUG passe le gate du syslog pour ce
+     * `msgid` (debug ciblé compris) : rien n'est alloué en production.
+     *
+     * @param cookie - le cookie posé.
+     * @param serialized - sa forme `Set-Cookie`, déjà calculée pour l'en-tête.
+     */
+    private logCookie;
     setHeader(name: string, value: number | string | readonly string[]): void | http.ServerResponse<http.IncomingMessage>;
     setHeaders(obj: OutgoingHttpHeaders): OutgoingHttpHeaders;
     setContentType(type?: string, encoding?: BufferEncoding): void | http.ServerResponse<http.IncomingMessage>;

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

@@ -22,6 +22,22 @@ declare class Parser {
     protected ended(): Promise<void>;
     parse(): Promise<this>;
 }
+/**
+ * Corps d'un type que le framework ne décode pas : livré TEL QU'IL EST REÇU,
+ * jamais remplacé par un objet vide qui mentirait.
+ *
+ * - `text/*` → une chaîne, décodée au `charset` du `Content-Type` (UTF-8 par
+ *   défaut) — comme une trame texte RFC 6455 ;
+ * - tout autre type, et un corps sans `Content-Type` (RFC 9110 §8.3 : supposé
+ *   `application/octet-stream`) → les OCTETS : le `Buffer` déjà assemblé dans
+ *   `request.data`, sans copie — donc un `Uint8Array`, le type d'octets que
+ *   la socket livrera aussi (#618). Un même schéma passe par les deux portes.
+ *
+ * Un corps VIDE laisse `body` tel quel : une requête sans charge ne change pas.
+ */
+declare class ParserRaw extends Parser {
+    parse(): Promise<this>;
+}
 declare class ParserQs extends Parser {
     parserOptions: QS.IParseOptions;
     charset: BufferEncoding;
@@ -35,7 +51,7 @@ declare class ParserXml extends Parser {
     parse(): Promise<this>;
 }
 /**
- * Parse un corps `application/json` (ou `*+json`) en objet → `queryPost`
+ * Parse un corps `application/json` (ou `*+json`) en objet → `body`
  * (source lue par le décorateur `@Body`). Reprend le rôle de l'ancien plugin
  * `json` de formidable, supprimé avec le passage à busboy (multipart seul).
  * Lenient : un corps JSON malformé est ignoré (pas de throw — `parse()` est
@@ -62,4 +78,4 @@ type AcceptEntry = {
     [key: string]: RegExp | number | string | undefined;
 };
 declare const acceptParser: (acc?: string) => AcceptEntry[];
-export { Parser, ParserXml, ParserQs, ParserJson, acceptParser };
+export { Parser, ParserRaw, ParserXml, ParserQs, ParserJson, acceptParser };

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

@@ -5,10 +5,10 @@ import { HTTPMethod } from "../Context.js";
 declare class Http2Request extends HttpRequest {
     request: http2.Http2ServerRequest;
     constructor(request: http2.Http2ServerRequest, context: HttpContext);
+    /** `:authority`, sinon `Host` — cf `requestAuthority` (RFC 9113 §8.3.1). */
     getHost(): string | undefined;
     getUserAgent(): string | undefined;
     getMethod(): HTTPMethod;
     getRawTarget(): string | undefined;
-    protected resolveScheme(): string;
 }
 export default Http2Request;

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

@@ -3,6 +3,11 @@ import type { MaybePromise } from "nodefony";
 import http from "node:http";
 import HttpContext from "../http/HttpContext.js";
 import HttpResponse from "../http/Response.js";
+/** Ce que la fusion lit d'une réponse Node : ses en-têtes posés, nom par nom. */
+interface IHeaderSource {
+    getHeaderNames(): string[];
+    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.
@@ -13,12 +18,17 @@ import HttpResponse from "../http/Response.js";
  * (`ERR_HTTP2_HEADER_SINGLE_VALUE`), soit une 500 sur tout média servi en
  * HTTP/2. HTTP/2 n'a de toute façon que des noms en minuscules (RFC 9113 §8.2.1).
  *
+ * Les en-têtes posés se lisent nom par nom (`getHeaderNames`, déjà en
+ * minuscules) : `getHeaders()` les recopiait d'abord dans un objet sans
+ * prototype, avant cette fusion — 3,8 µs par réponse pour 12 en-têtes,
+ * contre 1,1 µs en une passe.
+ *
  * @param statusMessage - message de statut, recopié en `x-status-message`
- * @param current - en-têtes déjà posés sur la réponse
+ * @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)
  * @returns les en-têtes à transmettre à `respond()`
  */
-export declare function mergeResponseHeaders(statusMessage: string, current: http.OutgoingHttpHeaders, extra?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): http.OutgoingHttpHeaders;
+export declare function mergeResponseHeaders(statusMessage: string, current: IHeaderSource, extra?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): http.OutgoingHttpHeaders;
 declare class Http2Response extends HttpResponse {
     statusCode: number;
     stream: http2.ServerHttp2Stream | null;
@@ -27,9 +37,9 @@ declare class Http2Response extends HttpResponse {
     isHeaderSent(): boolean;
     writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void;
     /**
-     * Écrit le corps sur le flux HTTP/2. Synchrone pour une redirection, un flux
-     * fermé ou le repli HTTP/1 ; une promesse quand le corps est écrit sur le
-     * flux, réglée par le rappel d'écriture (#505).
+     * Écrit le corps sur le flux HTTP/2 et, pour une réponse unique, le termine
+     * d'un seul `end(corps)`. Synchrone, sauf en streaming (`flush()`) : une
+     * promesse réglée par le rappel d'écriture, la contre-pression (#505).
      *
      * @returns la réponse, ou sa promesse.
      */
@@ -41,6 +51,18 @@ declare class Http2Response extends HttpResponse {
      * @throws de façon SYNCHRONE ce que lève la fin du flux.
      */
     end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise<http.ServerResponse | http2.ServerHttp2Stream>;
+    /**
+     * Termine la réponse de compatibilité d'un HEAD, dont Node a clos le flux de
+     * lui-même au `respond()`.
+     *
+     * Sans ce geste, `Http2ServerResponse` n'émet ni `finish` ni `close` : le
+     * démontage de la requête, branché sur ce `close` (ligne d'accès, profil,
+     * hooks d'après-réponse, libération du scope DI), n'a jamais lieu. Les statuts
+     * que Node termine aussi d'office (204, 205, 304) émettent leur `close` seuls,
+     * et un flux détruit (client parti) aussi : ils ne sont pas touchés. Hors du
+     * chemin servi — appelé seulement quand le flux est déjà clos.
+     */
+    private settleHeadResponse;
     getStatusMessage(code?: number | string): string;
     getStatus(): {
         code: number;

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

@@ -0,0 +1,64 @@
+import type { IRequestTrace, RequestTraceProtocol } from "../../interfaces/IRequestTrace.js";
+import type Context from "./Context.js";
+/**
+ * Nom du `TracingChannel` qui encadre chaque requête HTTP et chaque handshake
+ * WebSocket — forme `module.fonction` recommandée par la documentation de
+ * `node:diagnostics_channel` ; les sous-canaux sont
+ * `tracing:nodefony.http.request:start`, `:end`, `:asyncStart`, `:asyncEnd`,
+ * `:error`.
+ */
+export declare const REQUEST_TRACE_CHANNEL = "nodefony.http.request";
+/**
+ * Le message tel que Nodefony le remplit au fil de la requête : la vue
+ * modifiable d'{@link IRequestTrace}, qui reste en lecture seule pour
+ * l'abonné.
+ */
+export type RequestTraceRecord = {
+    -readonly [K in keyof IRequestTrace]: IRequestTrace[K];
+};
+/**
+ * Dit si quelqu'un écoute le canal — LA garde du chemin chaud : ~1,6 ns
+ * mesurées, aucune allocation. Lue une seule fois, au début de la requête :
+ * un abonné arrivé ensuite ne voit que les requêtes suivantes (règle des
+ * `TracingChannel`, qui interdit une fin sans début).
+ *
+ * @returns `true` si au moins un sous-canal a un abonné
+ */
+export declare function hasRequestTraceSubscribers(): boolean;
+/**
+ * Crée le message de la requête et le range sur son contexte. À n'appeler
+ * que sous {@link hasRequestTraceSubscribers} : c'est la seule allocation
+ * du canal, et elle n'a lieu que si quelqu'un écoute.
+ *
+ * @param context - le contexte qui vient d'être construit
+ * @param protocol - requête HTTP ou handshake WebSocket
+ * @returns le message, de forme fixe, dont les champs de résultat valent `null`
+ */
+export declare function openRequestTrace(context: Context, protocol: RequestTraceProtocol): RequestTraceRecord;
+/**
+ * Exécute la partie synchrone du traitement sous `start.runStores` puis
+ * publie `end` — la séquence de `TracingChannel.tracePromise`. Les stores
+ * liés au canal (`bindStore`, ce que fait un agent APM) restent actifs pour
+ * toute la suite asynchrone de la requête.
+ *
+ * @param trace - le message de la requête
+ * @param fn - la fonction qui sert la requête
+ * @param thisArg - le receveur de `fn`
+ * @param args - les arguments de `fn`
+ * @returns ce que rend `fn` — un contexte ou sa promesse
+ */
+export declare function runTraced<ThisArg, Args extends unknown[], Result>(trace: RequestTraceRecord, fn: (this: ThisArg, ...args: Args) => Result, thisArg: ThisArg, ...args: Args): Result;
+/**
+ * Termine la trace de la requête : remplit les champs de résultat puis
+ * publie `error` (s'il y a une exception), `asyncStart` et `asyncEnd`.
+ * Idempotent — le premier appel gagne, les suivants ne font rien : un
+ * handshake WebSocket a plusieurs sorties, une seule publie la fin.
+ *
+ * La durée est celle de l'horloge unique du contexte (`stopClock`), la même
+ * que celle de la ligne d'accès : le canal n'en mesure aucune.
+ *
+ * @param context - le contexte de la requête
+ * @param statusCode - le statut rendu au client, `null` s'il n'y en a pas eu
+ * @param error - l'exception attrapée par le pipeline, `null` ou `undefined` sinon
+ */
+export declare function closeRequestTrace(context: Context, statusCode: number | null, error: unknown): void;

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

@@ -0,0 +1,23 @@
+/**
+ * Ce que le chronométrage mesure sur une requête :
+ *
+ * - `"off"` — rien : ni horloge, ni phases ; la ligne d'accès sort sans durée ;
+ * - `"clock"` — la durée seule : une lecture d'horloge à l'entrée, une à la fin ;
+ * - `"phases"` — la durée ET le détail par phase (resolve, firewall, action…).
+ */
+export type TimingMode = "off" | "clock" | "phases";
+/**
+ * Résout le mode de chronométrage d'une requête depuis `timing.enabled` et
+ * l'environnement — la SEULE règle, appelée par le constructeur du `Context`.
+ *
+ * Défaut (`null`, pas d'avis) : la durée partout, les phases hors production.
+ * La durée coûte deux lectures d'horloge, l'équivalent de quelques pourcents
+ * de la ligne d'accès qu'elle complète ; les phases coûtent une lecture par
+ * phase, un tableau et un index par requête — réservées au développement, ou
+ * à un diagnostic à chaud (`true`). `false` coupe tout, durée comprise.
+ *
+ * @param enabled - valeur de `timing.enabled` (`true`, `false`, `null`)
+ * @param environment - environnement normalisé du noyau (`"production"`…)
+ * @returns le mode de la requête — une chaîne littérale, rien d'alloué
+ */
+export declare function resolveTimingMode(enabled: unknown, environment: string | undefined): TimingMode;

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

@@ -0,0 +1,53 @@
+import type { AlpnProtocol, ProtocolName, ServerType } from "../../interfaces/IContext.js";
+/**
+ * Famille du protocole traité par un contexte, déduite du serveur qui l'a
+ * reçu. Règle UNIQUE : `Context` la pose à la construction.
+ *
+ * @param serverType - identité du serveur (`http`, `https`, `ws`, `wss`)
+ * @returns `"websocket"` pour `ws`/`wss`, `"http"` sinon
+ */
+export declare function protocolNameOf(serverType: ServerType): ProtocolName;
+/**
+ * Ce que la détection lit d'une requête Node, et rien d'autre : `http.IncomingMessage`
+ * (HTTP/1.1) et `http2.Http2ServerRequest` (h2, h2c) le satisfont par leur forme, sans
+ * transtypage — et une doublure de test s'écrit en littéral.
+ */
+export interface IAlpnSource {
+    readonly httpVersionMajor: number;
+    readonly stream?: {
+        readonly session?: {
+            readonly alpnProtocol?: string | undefined;
+        } | undefined;
+    } | undefined;
+}
+/**
+ * Protocole du saut qui a porté cette requête jusqu'au processus, au sens du
+ * registre IANA des identifiants ALPN. Règle UNIQUE : `HttpContext` la lit pour
+ * choisir ses classes de requête et de réponse.
+ *
+ * La valeur se CONSTATE sur la requête, elle ne se déduit pas du serveur : un
+ * même serveur TLS reçoit HTTP/1.1 et h2 (`allowHTTP1`). Pour h2, c'est la
+ * session de Node qui tranche — `Http2Session.alpnProtocol` vaut `"h2c"` sur
+ * une session en clair, l'ALPN négocié (`"h2"`) sur une session TLS.
+ *
+ * @param request - la requête Node reçue par le serveur
+ * @returns `"http/1.1"`, `"h2"` ou `"h2c"`
+ */
+export declare function alpnProtocolOf(request: IAlpnSource): AlpnProtocol;
+/**
+ * Autorité (hôte et port) d'une requête, HTTP/1.1 comme HTTP/2. Règle UNIQUE
+ * des lecteurs du serveur.
+ *
+ * `:authority` d'abord, puis `Host` (RFC 9113 §8.3.1). Le repli n'est pas un
+ * confort : un intermédiaire qui convertit une requête HTTP/1.1 de forme origine
+ * (`GET /chemin`) en HTTP/2 ne DOIT PAS fabriquer `:authority` — il garde
+ * `Host`. C'est ce que fait HAProxy `proto h2` vers un port h2c : sans ce repli,
+ * l'hôte est introuvable et la requête part en 421.
+ *
+ * @param headers - en-têtes de la requête Node (`IncomingMessage` ou `Http2ServerRequest`).
+ * @returns l'autorité, ou `undefined` si la requête n'en porte aucune.
+ */
+export declare function requestAuthority(headers: {
+    host?: string | undefined;
+    ":authority"?: string | undefined;
+}): string | undefined;

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

@@ -0,0 +1,16 @@
+import type { IRouteResolver } from "../../interfaces/IRouting.js";
+/**
+ * Rédige l'avertissement de développement d'une requête restée sans réponse :
+ * l'action a rendu une valeur que le framework ne sait pas envoyer, et la
+ * requête a attendu son délai d'expiration.
+ *
+ * Le message nomme l'action fautive, ce qu'elle a rendu, et le geste qui
+ * convient à ce cas — `null` est presque toujours une entité absente, qui
+ * appelle un 404.
+ *
+ * @param resolver - le resolver de la requête (route, controller, action,
+ *   valeur non rendue), `null` si aucune route n'a été résolue.
+ * @param url - l'URL de la requête, repli quand aucune route n'est connue.
+ * @returns le texte de l'avertissement.
+ */
+export declare function unsentResponseWarning(resolver: IRouteResolver | null | undefined, url: string): string;

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

@@ -1,3 +1,4 @@
+import type { OutgoingHttpHeaders } from "node:http";
 import Cookie from "../../cookies/cookie.js";
 import { Message, Msgid, Pci, Severity } from "nodefony";
 import WebsocketContext from "./WebsocketContext.js";
@@ -44,8 +45,23 @@ declare class WebsocketResponse {
     };
     clean(): void;
     setEncoding(encoding: BufferEncoding): BufferEncoding;
-    setHeader(): boolean;
-    setHeaders(): boolean;
+    /**
+     * En-têtes de la réponse au handshake, retenus tant que la socket n'est pas
+     * acceptée : ils ne partent que dans un REFUS (`refuseHandshake`) — le `101`
+     * de `ws` ne les porte pas. `null` tant que personne n'en pose (le cas
+     * nominal : aucune allocation).
+     */
+    handshakeHeaders: Record<string, string | number> | null;
+    /**
+     * Retient un en-tête du handshake (cf {@link handshakeHeaders}) ; sans effet
+     * une fois la socket ouverte, où il n'y a plus de réponse HTTP.
+     *
+     * @param name - nom de l'en-tête
+     * @param value - valeur
+     * @returns toujours `true`
+     */
+    setHeader(name: string, value: number | string | readonly string[]): boolean;
+    setHeaders(obj: OutgoingHttpHeaders): boolean;
     addCookie(cookie: Cookie): void;
     setCookies(): void;
     setCookie(_cookie: Cookie): void;

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

@@ -4,21 +4,21 @@ import { Severity, Msgid, Message, nodefonyError, Scope } from "nodefony";
 import Ws from "ws";
 import type { IncomingMessage } from "node:http";
 import WebsocketResponse from "./Response.js";
+import type { IUpgradeAdmission } from "../../servers/upgradeDispatch.js";
 import { URL } from "node:url";
 import { HTTPMethod } from "../Context.js";
 import HttpError from "../../errors/httpError.js";
 import { FrameProfile } from "../../profiler/FrameProfile.js";
-import type { PhaseName } from "../../../interfaces/IContext.js";
+import type { PhaseName, IWebsocketContext } from "../../../interfaces/IContext.js";
 import { ProxyType } from "../http/HttpContext.js";
 import { type ResolvedProxy } from "../forwarded.js";
 export interface IWsRequestExtension {
     url: URL;
     query: Record<string, string>;
-    queryGet: Record<string, string>;
     path: string;
 }
 export type WsIncomingMessage = IncomingMessage & IWsRequestExtension;
-import type { IWebsocketContext as IWebsocketContextInterface } from "../../../interfaces/IContext.js";
+import type { IWebsocketContext as IWebsocketContextInterface, IWebsocketConnectionState } from "../../../interfaces/IContext.js";
 /**
  * Coerce un code (applicatif / HTTP / WS) en code de fermeture WebSocket VALIDE
  * et conforme RFC 6455 §7.4, en PRÉFÉRANT les codes standard §7.4.1 quand le
@@ -36,7 +36,36 @@ import type { IWebsocketContext as IWebsocketContextInterface } from "../../../i
  * @returns un code de fermeture WS valide.
  */
 export declare function toWsCloseCode(code: number | undefined | null): number;
-export default class WebsocketContext extends Context implements IWebsocketContextInterface {
+/**
+ * Statut HTTP d'un handshake REFUSÉ avant le `101` (RFC 6455 §4.2.2) — la
+ * réciproque de {@link toWsCloseCode} : une erreur levée pendant la décision
+ * porte un code HTTP (pare-feu, garde) ou, par héritage, un code de fermeture
+ * WS (origine `1008`, protocole `1002`, introuvable `4004`) ; le client qui
+ * lit le statut doit y reconnaître le même sens.
+ *
+ * @param code - code porté par l'erreur
+ * @returns un statut HTTP 4xx/5xx
+ */
+export declare function toHandshakeStatus(code: number | undefined | null): number;
+/**
+ * Statut HTTP que reçoit le client d'un handshake refusé — ou `null` si la
+ * connexion était déjà acceptée.
+ *
+ * La ligne de journal d'un refus s'écrit AVANT `refuseHandshake` : sans ce
+ * calcul, elle affichait le code de fermeture par défaut (`1000`) en ERROR,
+ * pour un `400` que le client reçoit. Même conversion que le refus
+ * ({@link toHandshakeStatus}), donc même chiffre. Chemin d'ERREUR seulement :
+ * 1 comparaison et 1 `typeof`, aucune allocation.
+ *
+ * @param context - le contexte WS de la ligne
+ * @param error - l'erreur qui a interrompu le handshake
+ * @returns le statut HTTP du refus, ou `null` après l'acceptation
+ */
+export declare function handshakeRefusalStatus(context: IWebsocketContext, error: Error): number | null;
+interface WebsocketContext extends IWebsocketConnectionState {
+}
+export { WebsocketContext as default };
+declare class WebsocketContext extends Context implements IWebsocketContextInterface {
     #private;
     request: WsIncomingMessage | null;
     response: WebsocketResponse | null;
@@ -45,16 +74,37 @@ export default class WebsocketContext extends Context implements IWebsocketConte
     rejected: boolean;
     teardownWired: boolean;
     connection: Ws | 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
+     * est acceptée ou refusée. Tant qu'il est là, AUCUN `101` n'est parti.
+     */
+    admission: IUpgradeAdmission | null;
     origin: string;
     proxy: ProxyType | null;
     forwarded: ResolvedProxy | null;
     wsUrl: URL | null;
-    queryGet: Record<string, string>;
-    queryRequest: Record<string, string>;
+    query: Record<string, string>;
     wsPath: string;
-    constructor(scope: Scope, req: IncomingMessage, ws: Ws, type: ServerType);
-    log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
+    constructor(scope: Scope, req: IncomingMessage, ws: Ws | null, serverType: ServerType);
+    log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): import("nodefony").Pdu;
     logRequest(httpError?: Error | HttpError | nodefonyError | null, acceptedProtocol?: string | null): import("nodefony").Pdu | undefined;
+    /**
+     * Rattache la socket que le handshake vient d'ouvrir (`101` envoyé) : le
+     * contexte a été construit et jugé AVANT, sans elle.
+     *
+     * @param ws - la socket acceptée
+     */
+    acceptConnection(ws: Ws): void;
+    /**
+     * Refuse le handshake par un statut HTTP, avant tout `101` (RFC 6455
+     * §4.2.2) — avec les en-têtes posés pendant la décision (`WWW-Authenticate`
+     * du pare-feu, `Retry-After`).
+     *
+     * @param status - statut HTTP du refus
+     * @returns `false` si le verdict était déjà rendu (rien n'est écrit)
+     */
+    refuseHandshake(status: number): boolean;
     connect(): Promise<Ws>;
     handle(data?: unknown[]): Promise<this>;
     render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>;

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

@@ -0,0 +1,15 @@
+import type { ContextType } from "../../../service/http-kernel.js";
+import type WebsocketContext from "./WebsocketContext.js";
+/**
+ * Dit si un contexte sert une connexion WebSocket — la garde qui rétrécit
+ * `ContextType` à `WebsocketContext` sans conversion.
+ *
+ * Elle lit la famille (`type`) posée à la construction du contexte, jamais
+ * `instanceof` : deux copies installées de `@nodefony/http` font échouer
+ * `instanceof` en silence, quand ce champ dit vrai pour les deux. Deux
+ * Une comparaison de chaînes, aucune allocation.
+ *
+ * @param context - le contexte à éprouver.
+ * @returns `true` si le contexte traite une connexion WebSocket (`ws` ou `wss`).
+ */
+export declare function isWebsocketContext(context: ContextType): context is WebsocketContext;