@nodefony/http 10.0.0-alpha.1

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

@@ -0,0 +1,68 @@
+import http, { OutgoingHttpHeaders } from "node:http";
+import http2 from "node:http2";
+import HttpContext from "../http/HttpContext.js";
+import { Pci, Pdu, Message, Severity, Msgid } from "nodefony";
+import Cookie from "../../cookies/cookie.js";
+declare class HttpResponse {
+    #private;
+    context: HttpContext;
+    response: http.ServerResponse | http2.Http2ServerResponse | null;
+    statusCode: number;
+    statusMessage: string;
+    flushing: boolean;
+    encoding: BufferEncoding;
+    body: Buffer | null;
+    contentType: string;
+    headers: http.OutgoingHttpHeaders;
+    timeout?: number;
+    cookies: Record<string, Cookie>;
+    constructor(response: http.ServerResponse | http2.Http2ServerResponse, context: HttpContext);
+    /**
+     * Filet posé juste avant l'émission des en-têtes : si aucun `Content-Type`
+     * n'a été choisi (ni négociation, ni `render`, ni controller), émet le défaut
+     * `this.contentType` (application/octet-stream) — comportement identique à
+     * l'ancienne pose au constructeur, sans le ping-pong set/remove/re-set.
+     */
+    protected ensureContentTypeHeader(): void;
+    clean(): void;
+    isHeaderSent(): boolean;
+    isHtml(): boolean;
+    setTimeout(ms: number): void;
+    addCookie(cookie: Cookie): Cookie;
+    deleteCookie(cookie: Cookie): boolean;
+    deleteCookieByName(name: string): boolean;
+    setCookies(): void | http.ServerResponse<http.IncomingMessage>;
+    setCookie(cookie: Cookie): void | http.ServerResponse<http.IncomingMessage>;
+    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>;
+    setFileMimeType(type: string, encoding?: BufferEncoding): void | http.ServerResponse<http.IncomingMessage>;
+    setContentTypeByExtension(extention: string): void | http.ServerResponse<http.IncomingMessage>;
+    getMimeType(filenameOrExt: string): string | false;
+    setEncoding(encoding: BufferEncoding): BufferEncoding;
+    setStatusCode(status: number | string, message?: string): {
+        code: number;
+        message: string;
+    };
+    getStatus(): {
+        code: number;
+        message: string;
+    };
+    getStatusCode(): number;
+    getStatusMessage(code?: number | string): string;
+    setBody(ele: unknown, encoding?: BufferEncoding | undefined): Buffer;
+    setLength(body?: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
+    writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void;
+    addTrailers(headers: http.OutgoingHttpHeaders): void;
+    flush(chunk: unknown, encoding: BufferEncoding): Promise<HttpResponse>;
+    send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): Promise<HttpResponse>;
+    write(chunk?: unknown, encoding?: BufferEncoding): Promise<HttpResponse>;
+    writeContinue(): void | undefined;
+    end(chunk?: string | Buffer, encoding?: BufferEncoding): Promise<http.ServerResponse | http2.ServerHttp2Stream>;
+    getHeader(name: string): string | number | string[] | undefined;
+    hasHeader(name: string): boolean;
+    getHeaders(): http.OutgoingHttpHeaders;
+    redirect(url: string, status?: number | string, headers?: Record<string, string | number>): this;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+}
+export default HttpResponse;

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

@@ -0,0 +1,65 @@
+import HttpRequest from "./Request.js";
+import Http2Request from "../http2/Request.js";
+import QS from "qs";
+import xml2js from "xml2js";
+declare class Parser {
+    request: HttpRequest | Http2Request;
+    chunks: Buffer[];
+    private received;
+    private aborted;
+    private overflow;
+    private onOverflow;
+    constructor(request: HttpRequest | Http2Request);
+    write(buffer: Buffer): Buffer;
+    /**
+     * Résout quand le flux requête est **entièrement reçu** (`end`). No-op si déjà
+     * terminé (corps vide / déjà drainé) → pas de hang d'un `once("end")` tardif.
+     * Indispensable avant de concaténer les chunks pour un corps à décoder
+     * (JSON…) : sinon on lit un buffer encore incomplet. (formidable drainait via
+     * son `await form.parse()` ; ses remplaçants doivent drainer explicitement.)
+     * Rejette en 413 si le corps dépasse `maxBodySize` (avant ou pendant l'attente).
+     */
+    protected ended(): Promise<void>;
+    parse(): Promise<this>;
+}
+declare class ParserQs extends Parser {
+    parserOptions: QS.IParseOptions;
+    charset: BufferEncoding;
+    constructor(request: HttpRequest | Http2Request);
+    parse(): Promise<this>;
+}
+declare class ParserXml extends Parser {
+    xmlParser: xml2js.Parser;
+    charset: BufferEncoding;
+    constructor(request: HttpRequest | Http2Request, settingsXml?: xml2js.ParserOptions);
+    parse(): Promise<this>;
+}
+/**
+ * Parse un corps `application/json` (ou `*+json`) en objet → `queryPost`
+ * (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
+ * invoqué non-awaité par `initialize`, un rejet serait non géré) ; le brut
+ * reste disponible dans `request.data`.
+ */
+declare class ParserJson extends Parser {
+    charset: BufferEncoding;
+    constructor(request: HttpRequest | Http2Request);
+    parse(): Promise<this>;
+}
+/** Media-range « accepte tout » (wildcard type + sous-type) — repli sûr, jamais throw. */
+/**
+ * Une entrée d'en-tête `Accept` analysée : le type et le sous-type compilés en
+ * expressions régulières, plus les paramètres bruts du segment (`q`, `charset`,
+ * `level`…). L'index est ouvert parce que le client choisit ces noms — mais ses
+ * valeurs, elles, sont connues : une regex pour le type, un nombre pour `q`, une
+ * chaîne pour le reste.
+ */
+type AcceptEntry = {
+    type: RegExp;
+    subtype: RegExp;
+    q?: number;
+    [key: string]: RegExp | number | string | undefined;
+};
+declare const acceptParser: (acc?: string) => AcceptEntry[];
+export { Parser, ParserXml, ParserQs, ParserJson, acceptParser };

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

@@ -0,0 +1,52 @@
+/**
+ * Fast-path d'analyse du request-target — évite le `new URL` (parse WHATWG
+ * complet) sur le chemin nominal, où le target est déjà sous sa forme
+ * canonique et où pathname/search s'extraient par simple découpe.
+ *
+ * ⚠️ SÉCURITÉ — le contrat qui rend la découpe légale : la normalisation
+ * WHATWG (dot-segments — y compris leurs formes percent-encodées `%2e` —,
+ * conversion `\` → `/`, percent-encoding, punycode/lowercase du host,
+ * normalisation des hosts « IPv4-like » type `127.1`/`0x7f.1`) PROTÈGE le
+ * routing et le matching de zones du firewall. La découpe n'est donc admise
+ * QUE si elle est prouvablement l'IDENTITÉ : tout caractère ou motif que le
+ * parseur WHATWG transformerait — ou dont l'innocuité n'est pas certaine —
+ * déclenche le bail-out (`null`) et le vrai `new URL` est construit, comme
+ * avant. Whitelist stricte : le doute coûte un parse, jamais un contournement.
+ *
+ * La preuve est portée par `tests/unit/urlFastPath.test.ts` : balayage
+ * exhaustif par caractère (0x00-0x7F, plus témoins > 0x7F) comparant chaque
+ * target ACCEPTÉ au résultat du vrai `new URL` — pathname, search et href
+ * doivent être STRICTEMENT identiques à la découpe.
+ */
+/**
+ * Résultat d'une découpe acceptée : les deux composants, dans la même forme
+ * que `URL.pathname` / `URL.search` (le `?` inclus, `""` si query absente ou
+ * vide — `/x?` donne `search === ""` comme WHATWG).
+ */
+export interface ISplitTarget {
+    pathname: string;
+    search: string;
+}
+/**
+ * Découpe un request-target origin-form (`/path[?query]`) en
+ * pathname/search SI — et seulement si — le parse WHATWG serait l'identité.
+ *
+ * @param target - le request-target brut (`IncomingMessage.url` en HTTP/1,
+ *   pseudo-header `:path` en HTTP/2).
+ * @returns les composants découpés, ou `null` (bail-out → vrai `new URL`).
+ */
+export declare function splitTarget(target: unknown): 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 ?
+ *
+ * Refusé (→ bail-out) : majuscules (lowercase WHATWG), IPv6 (`[`), toute
+ * forme « IPv4-like » ambiguë (`127.1`, `0x7f.1`, `2130706433` — WHATWG les
+ * NORMALISE en dotted-quad, un matcher les lisant brut serait contournable),
+ * label vide (`a..b`, `.a`, `a.`), port par défaut du scheme (élidé par
+ * WHATWG) ou avec zéro de tête, percent-encoding, non-ASCII (punycode).
+ *
+ * @param host - autorité brute (peut contenir `:port`).
+ * @param scheme - scheme effectif (`http` | `https`) — décide du port par défaut.
+ */
+export declare function isCanonicalAuthority(host: unknown, scheme: string): host is string;

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

@@ -0,0 +1,14 @@
+import http2 from "node:http2";
+import HttpContext from "../http/HttpContext.js";
+import HttpRequest from "../http/Request.js";
+import { HTTPMethod } from "../Context.js";
+declare class Http2Request extends HttpRequest {
+    request: http2.Http2ServerRequest;
+    constructor(request: http2.Http2ServerRequest, context: HttpContext);
+    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

@@ -0,0 +1,20 @@
+import http2 from "node:http2";
+import http from "node:http";
+import HttpContext from "../http/HttpContext.js";
+import HttpResponse from "../http/Response.js";
+declare class Http2Response extends HttpResponse {
+    statusCode: number;
+    stream: http2.ServerHttp2Stream | null;
+    streamId?: number | undefined;
+    constructor(response: http2.Http2ServerResponse, context: HttpContext);
+    isHeaderSent(): boolean;
+    writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void;
+    send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): Promise<Http2Response>;
+    end(chunk?: string | Buffer, encoding?: BufferEncoding): Promise<http.ServerResponse | http2.ServerHttp2Stream>;
+    getStatusMessage(code?: number | string): string;
+    getStatus(): {
+        code: number;
+        message: string;
+    };
+}
+export default Http2Response;

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

@@ -0,0 +1,58 @@
+import type { Data, MetaData } from "../../service/http-kernel.js";
+/**
+ * Forme structurelle minimale d'une route nécessaire pour bâtir l'enveloppe
+ * `nodefony.route`. Découplée de la classe `Route` de `@nodefony/framework`
+ * (pas d'import, pas de cycle, pas de fuite d'instance partagée).
+ */
+export interface IMetaDataRouteSource {
+    name: string;
+    path?: string;
+}
+/**
+ * Contexte structurel minimal nécessaire pour assembler `Context.metaData`.
+ * Volontairement découplé de `Context` (typage par forme, comme
+ * `IParamArgContext`) → {@link buildMetaData} est une fonction pure, testable en
+ * unit avec une fausse source, sans démarrer de serveur. Le vrai `Context`
+ * satisfait cette forme.
+ */
+export interface IMetaDataSource {
+    kernel?: {
+        projectName?: string;
+        version?: string;
+        environment?: MetaData["environment"];
+        debug?: MetaData["debug"];
+    } | null;
+    request?: {
+        url?: URL;
+        href?: string;
+    } | null;
+    scheme: MetaData["scheme"];
+    requestId: string;
+    resolver?: {
+        route: IMetaDataRouteSource | null;
+        getMatchedParams(): Record<string, unknown>;
+    } | null;
+}
+/**
+ * Assemble l'enveloppe `metaData` d'une requête EN PLACE (builder monomorphe) :
+ * met à jour les champs de `target.nodefony` dans un ordre fixe → V8 garde une
+ * hidden class stable et inline les écritures. Remplace l'ancien
+ * `extend(true, …)` qui deep-clonait/dispatchait à chaque réponse JSON et chaque
+ * frame WS — inutile ici puisque `target` est l'objet metaData per-requête
+ * (jamais partagé).
+ *
+ * `route` est un **snapshot per-requête** `{ name, path, variablesMap }` : on ne
+ * diffuse jamais l'instance `Route` partagée (statique), dont les variables
+ * matchées seraient écrasées par toute requête/connexion concurrente (bleed).
+ *
+ * `override` (ex. frame WS `{ nodefony: { websocket } }`) est fusionné *shallow*
+ * dans l'enveloppe : le seul cas réel est l'ajout d'un sous-objet `nodefony`
+ * peu profond — pas besoin du deep-merge récursif générique. Toute clé top-level
+ * hors `nodefony` est préservée telle quelle.
+ *
+ * @param target - objet metaData per-requête à muter (et retourner)
+ * @param src - source structurelle (le `Context` réel, ou un faux en test)
+ * @param override - overrides optionnels de l'appelant
+ * @returns le même `target`, muté
+ */
+export declare function buildMetaData(target: Data, src: IMetaDataSource, override?: Record<string, unknown>): Data;

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

@@ -0,0 +1,28 @@
+/**
+ * Validation de l'identifiant de corrélation `X-Request-Id` fourni par le
+ * client, avant qu'il ne soit adopté comme `Context.requestId`.
+ *
+ * Le `requestId` finit (1) réfléchi dans la réponse (`X-Request-Id`),
+ * (2) écrit dans les logs (`ID : …`), (3) propagé en ALS à tout le pipeline.
+ * Une valeur cliente non assainie ouvre donc : log-injection (CR/LF dans les
+ * logs), forging de corrélation, et throw `setHeader` natif (→ 500/DoS) sur
+ * caractère de contrôle ou non-ASCII. Cf RFC 9110 §5.5 (field values) + Zero
+ * Trust (mémoire `feedback_security_rfc_rigor`).
+ */
+/**
+ * Longueur maximale acceptée pour un `X-Request-Id` client. Borne anti-abus
+ * (log flooding / header oversize). 128 couvre largement un UUID (36), un
+ * nanoid, ou un `traceparent` (55).
+ */
+export declare const MAX_REQUEST_ID_LENGTH = 128;
+/**
+ * Valide un `X-Request-Id` entrant. Retourne la valeur si elle est sûre, sinon
+ * `null` (l'appelant conserve alors l'UUID généré côté serveur).
+ *
+ * On REJETTE (plutôt que tronquer/nettoyer) une valeur invalide : nettoyer
+ * donnerait au client un faux contrôle sur l'identifiant et masquerait l'abus.
+ *
+ * @param raw - valeur brute du header `x-request-id` (ou `undefined`/`null`).
+ * @returns la valeur si sûre, sinon `null`.
+ */
+export declare function sanitizeRequestId(raw: string | undefined | null): string | null;

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

@@ -0,0 +1,77 @@
+/**
+ * Politique de confiance envers les en-têtes `X-Forwarded-*` (et le scheme
+ * proxifié), pour décider si la connexion entrante provient d'un reverse-proxy
+ * légitime.
+ *
+ * Sans cette barrière, n'importe quel client peut envoyer
+ * `X-Forwarded-For: 1.2.3.4` → IP spoofée (contournement de rate-limit /
+ * d'allow-list IP, falsification des logs d'audit) et `X-Forwarded-Proto: https`
+ * → faux scheme. Cf RFC 7239 / OWASP « Host header & forwarded headers ».
+ */
+/**
+ * Valeur de configuration `trustProxy` :
+ * - `false` (défaut sûr) : ne JAMAIS faire confiance aux `X-Forwarded-*`.
+ * - `true` : confiance totale (déploiement où le LB est l'unique point d'entrée).
+ * - `string` / `string[]` : IP, CIDR (`10.0.0.0/8`, `::1/128`) ou presets
+ *   `"loopback"`, `"linklocal"`, `"uniquelocal"`.
+ */
+export type TrustProxyConfig = boolean | string | string[];
+/** Décide si l'adresse distante (socket réel) est un proxy de confiance. */
+export interface TrustProxyChecker {
+    isTrusted(remoteAddress: string | undefined | null): boolean;
+}
+/**
+ * Compile une config `trustProxy` en un {@link TrustProxyChecker} (une fois, au
+ * boot — pas par requête). Les entrées invalides lèvent à la compilation (fail
+ * fast) plutôt que silencieusement par requête.
+ *
+ * @param config - voir {@link TrustProxyConfig}. `undefined` → aucune confiance.
+ * @returns un checker `isTrusted(remoteAddress)`.
+ */
+export declare function buildTrustProxy(config: TrustProxyConfig | undefined): TrustProxyChecker;
+/**
+ * Cœur de la résolution **from-right** (OWASP) partagé par `X-Forwarded-For`
+ * (de-facto) et le paramètre `for` du header `Forwarded` (RFC 7239 §5.2).
+ *
+ * `chain` = liste des maillons forwarded NORMALISÉS (IP nues, gauche→droite :
+ * `[client, proxy1, proxy2]`), telle qu'écrite par les proxies par **append à
+ * droite**. La partie gauche est forgeable par le client (cf {@link extractClientIp}).
+ * La résolution part de la **connexion réelle** (le socket, non forgeable) et
+ * remonte de DROITE à GAUCHE : tant que le maillon courant est un proxy de
+ * confiance, on passe au précédent ; le **premier maillon non fiable** est l'IP
+ * cliente réelle.
+ *
+ * Un maillon `null` (identifiant obfusqué `_secret`, `unknown`, ou node illisible
+ * — RFC 7239 §6.3/§8.3) est une **barrière non franchissable** : on ne peut pas
+ * en vérifier la confiance → on s'arrête et on retourne le dernier maillon de
+ * confiance connu (une vraie IP de l'infra), jamais `null` ni la valeur obfusquée.
+ *
+ * @param chain - maillons forwarded normalisés (IP ou `null` si obfusqué).
+ * @param socketAddress - `socket.remoteAddress` (connexion TCP réelle, fiable).
+ * @param checker - politique de confiance ({@link buildTrustProxy}).
+ * @returns l'IP cliente réelle résolue (toujours une valeur fiable).
+ */
+export declare function resolveFromRight(chain: ReadonlyArray<string | null>, socketAddress: string, checker: TrustProxyChecker): string;
+/**
+ * Résout l'adresse IP cliente RÉELLE à partir de la connexion socket et de la
+ * chaîne `X-Forwarded-For`, en dépouillant les proxies de confiance **de droite
+ * à gauche** (algorithme OWASP).
+ *
+ * `X-Forwarded-For` (de-facto) est construit par **append de gauche à droite** :
+ * `XFF: client, proxy1, proxy2`. Chaque proxy ajoute À DROITE l'adresse qu'il a
+ * vue. La partie **gauche** est donc entièrement **forgeable** par le client
+ * (il peut envoyer `X-Forwarded-For: 1.2.3.4` ; le 1ᵉʳ proxy ne fait qu'append
+ * l'IP réelle après). Lire `XFF[0]` revient à lire la valeur du client →
+ * **IP spoofing** (contournement de ban / rate-limit / allow-list / audit).
+ *
+ * Hot path préservé : sans `X-Forwarded-For` (cas direct usuel) la fonction
+ * retourne immédiatement le socket — 0 allocation (pas de split). Pour le header
+ * standard `Forwarded` (RFC 7239), voir `resolveForwarded` (module `forwarded`).
+ *
+ * @param xff - valeur brute de l'en-tête `X-Forwarded-For` (string, ou string[]
+ *   si l'en-tête est répété), ou `undefined`.
+ * @param socketAddress - `socket.remoteAddress` (la connexion TCP réelle).
+ * @param checker - politique de confiance ({@link buildTrustProxy}).
+ * @returns l'IP cliente réelle, ou `null` si aucune connexion socket fiable.
+ */
+export declare function extractClientIp(xff: string | string[] | undefined, socketAddress: string | undefined | null, checker: TrustProxyChecker): string | null;

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

@@ -0,0 +1,53 @@
+import Cookie from "../../cookies/cookie.js";
+import { Message, Msgid, Pci, Severity } from "nodefony";
+import WebsocketContext from "./WebsocketContext.js";
+import Ws from "ws";
+export type { IWsCookie } from "../../../interfaces/ICookie.js";
+/**
+ * `true` si l'erreur d'écriture signifie seulement que le client s'est
+ * déconnecté (frame perdue, connexion en cours de fermeture) — à logger DEBUG,
+ * jamais ERROR + stack (vécu : un simple reload de page pendant un ping WS
+ * remplissait le journal d'« Error: write EPIPE »).
+ */
+export declare function isPeerGoneError(error: unknown): boolean;
+declare class WebsocketResponse {
+    private context;
+    statusCode: number;
+    body: Buffer | null;
+    encoding: BufferEncoding;
+    connection: Ws | null;
+    statusMessage: string;
+    webSocketVersion?: number;
+    cookies: Record<string, Cookie>;
+    constructor(connection: Ws | null, context: WebsocketContext);
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu | undefined;
+    setConnection(connection: Ws): Ws;
+    send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise<WebsocketResponse>;
+    broadcast(data?: Buffer | string | null, type?: BufferEncoding): void;
+    /**
+     * Logge UNE seule fois par connexion (au 1er drop) qu'un client subit la
+     * backpressure — observabilité opérateur sans bruit dans le hot path.
+     */
+    private logFirstDrop;
+    setBody(ele: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): Buffer<ArrayBufferLike> | null;
+    drop(reasonCode: number, description: string): void;
+    close(reasonCode: number, description: string): void;
+    getStatus(): {
+        code: number;
+        message: string;
+    };
+    getStatusCode(): number;
+    getStatusMessage(): string;
+    setStatusCode(status: number | string, message?: string): {
+        code: number;
+        message: string;
+    };
+    clean(): void;
+    setEncoding(encoding: BufferEncoding): BufferEncoding;
+    setHeader(): boolean;
+    setHeaders(): boolean;
+    addCookie(cookie: Cookie): void;
+    setCookies(): void;
+    setCookie(_cookie: Cookie): void;
+}
+export default WebsocketResponse;

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

@@ -0,0 +1,125 @@
+import Context from "../Context.js";
+import { ServerType, SchemeType } from "../../../service/http-kernel.js";
+import { Severity, Msgid, Message, nodefonyError, Scope } from "nodefony";
+import Ws from "ws";
+import type { IncomingMessage } from "node:http";
+import WebsocketResponse from "./Response.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 { 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";
+/**
+ * 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
+ * sens existe :
+ *  - code déjà valide émissible (1000-1003, 1007-1011, 3000-4999) → conservé ;
+ *  - HTTP 5xx / interne / code absent → **1011** (Internal Error) ;
+ *  - HTTP 401 / 403 / 421 → **1008** (Policy Violation) ;
+ *  - autre `< 1000` (ex. 404, sans équivalent RFC) → **4004**, plage privée
+ *    4000-4999 (§7.4.2, « undefined by this protocol » → convention applicative).
+ *
+ * Évite d'émettre un code de la plage 0-999 (« not used », rejeté par `ws`) ou
+ * un code réservé non émissible (1004/1005/1006/1015).
+ *
+ * @param code - code source (number, undefined…).
+ * @returns un code de fermeture WS valide.
+ */
+export declare function toWsCloseCode(code: number | undefined | null): number;
+export default class WebsocketContext extends Context implements IWebsocketContextInterface {
+    #private;
+    request: WsIncomingMessage | null;
+    response: WebsocketResponse | null;
+    acceptedProtocol?: string;
+    port: number | string;
+    rejected: boolean;
+    teardownWired: boolean;
+    connection: Ws | null;
+    origin: string;
+    proxy: ProxyType | null;
+    forwarded: ResolvedProxy | null;
+    wsUrl: URL | null;
+    queryGet: Record<string, string>;
+    queryRequest: 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;
+    logRequest(httpError?: Error | HttpError | nodefonyError | null, acceptedProtocol?: string | null): import("nodefony").Pdu | undefined;
+    connect(): Promise<Ws>;
+    handle(data?: unknown[]): Promise<this>;
+    render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>;
+    send(data?: string | Buffer | null, encoding?: BufferEncoding): Promise<WebsocketResponse>;
+    broadcast(data?: string | Buffer | null, encoding?: BufferEncoding): 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
+     * direction. Hot path : le gate booléen court-circuite en prod AVANT toute
+     * construction de chaîne (0 allocation / 0 concat).
+     *
+     * @param dir - sens du message du point de vue serveur.
+     * @param data - charge utile (string, Buffer binaire, objet, ou null).
+     */
+    private logMessageContent;
+    /**
+     * Ouvre le profil d'**une invocation** du pont RPC (une frame `api.request`).
+     *
+     * Le contexte WS vit pour la CONNEXION : ses `phases` sont cumulatives et son
+     * `requestId` est unique pour toute la socket. Une frame reçoit donc son
+     * propre profil, identifié `<requestId de la connexion>.<n° de frame>` — le
+     * `id` JSON-RPC ne peut pas servir de clé : il est choisi par le client.
+     *
+     * @param method - méthode LOGIQUE de l'invocation (`GET`, `POST`…).
+     * @param framePath - chemin invoqué par la frame (jamais l'URL de la
+     *          connexion) — nommé ainsi parce que `url` masquerait le module
+     *          `node:url`, importé ici et utilisé par `connect()`.
+     * @returns le profil, ou `null` si profiler ET timing sont éteints (prod) —
+     *          zéro allocation dans ce cas.
+     */
+    beginFrame(method: string, framePath: string): FrameProfile | null;
+    /**
+     * Enregistre le profil d'une invocation terminée dans le ring buffer du
+     * Profiler (no-op hors dev, ou si aucun profil n'a été ouvert).
+     */
+    collectFrame(frame: FrameProfile | null): void;
+    /**
+     * Les phases émises pendant une invocation du pont (`initialize` par le
+     * Resolver, `render` par le Controller…) vont dans le profil de **la frame**,
+     * pas du contexte : sans cette redirection, `Context.phases` accumulerait deux
+     * entrées par message pour toute la vie de la socket (timeline cumulative
+     * ET croissance sans borne). Hors invocation (handshake), comportement de base.
+     */
+    phaseStart(name: PhaseName): void;
+    phaseEnd(name: PhaseName): void;
+    handleMessage(data: Buffer | string, isBinary: boolean): Promise<unknown>;
+    onClose(code: number, reason: Buffer): void;
+    /**
+     * Listener `error` de la socket ws (OBLIGATOIRE — sans lui, un 'error' émis
+     * sans listener crashe le process via EventEmitter). `ws` émet 'error' PUIS
+     * 'close' → le teardown se fait dans {@link onClose} ; ici on logge seulement
+     * (pas de double-close). Erreur transport (reset TCP, frame corrompue…).
+     *
+     * @param error - erreur émise par la socket.
+     */
+    onConnectionError(error: Error): void;
+    setScheme(): SchemeType;
+    getRemoteAddress(): string | null;
+    getHost(): string | undefined;
+    getHostName(): string | undefined;
+    getUserAgent(): string;
+    getMethod(): HTTPMethod;
+    setContextJson(): void;
+    clean(): void;
+    close(reasonCode: number | undefined | null, description: string): void;
+    drop(reasonCode: number, description: string): void;
+    reject(code: number | string | undefined, message?: string): void;
+}

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

@@ -0,0 +1,73 @@
+import Ws, { WebSocketServer } from "ws";
+/** Politique appliquée quand le buffer d'envoi d'un client dépasse le seuil. */
+export type WsBackpressurePolicy = "drop" | "close";
+/**
+ * Options de backpressure SORTANTE (serveur → client).
+ *
+ * Knobs Nodefony (pas des options `ws`) ; `ws` les conserve quand même dans
+ * `wss.options` car son constructeur fait `{ ...defaults, ...options }` → on les
+ * relit ici via {@link readBackpressureOptions}.
+ */
+export interface IWsBackpressureOptions {
+    /** Seuil (octets) de `ws.bufferedAmount` ; `0`/absent = désactivé. */
+    maxBackpressure?: number;
+    /** Action au dépassement du seuil. Défaut `"drop"`. */
+    backpressurePolicy?: WsBackpressurePolicy;
+    /** Refus consécutifs au-delà desquels on ferme (1013) ; `0`/absent = jamais. */
+    backpressureCloseAfterDrops?: number;
+}
+/**
+ * Ce dont la règle a besoin, et rien de plus : la taille de la file d'envoi et
+ * de quoi fermer. Typé STRUCTURELLEMENT pour que `@nodefony/realtime` applique
+ * la même règle sans importer `ws` (son transport type déjà sa connexion ainsi).
+ */
+export interface IBackpressureTarget {
+    readonly bufferedAmount?: number;
+    close(code?: number, reason?: string): void;
+}
+/** Socket augmentée d'un compteur de drops (number lazy — lu par la sonde socket). */
+export interface IBackpressureSocket extends Ws {
+    /** Nombre cumulé de frames droppées/refusées pour backpressure sur cette socket. */
+    _nfDrops?: number;
+    /**
+     * Frames refusées **d'affilée**, remis à zéro dès qu'une frame repart. C'est
+     * le signal d'une file qui ne se draine plus — le seul qui distingue un pic
+     * passager d'un client mort. Cf le palier 2 de {@link decideSend}.
+     */
+    _nfDropStreak?: number;
+}
+/** Décision pour une frame : l'émettre, la sauter, ou (socket fermée) ne rien faire. */
+export type WsSendDecision = "send" | "drop" | "close";
+/**
+ * Relit le seuil + la politique depuis les options du `WebSocketServer`.
+ *
+ * `ws` préserve nos clés custom (`maxBackpressure`/`backpressurePolicy`) dans
+ * `wss.options` via le spread de son constructeur. Appelé UNE fois hors de la boucle
+ * `broadcast()` (pas par frame).
+ *
+ * @param wss - le serveur WebSocket (ou null/undefined → backpressure désactivée)
+ * @returns seuil résolu (`max`, 0 = off) + politique (`policy`, défaut `"drop"`)
+ */
+export declare const readBackpressureOptions: (wss: WebSocketServer | null | undefined) => {
+    max: number;
+    policy: WsBackpressurePolicy;
+    closeAfterDrops: number;
+};
+/**
+ * Décide si une frame doit partir vers `ws` selon la backpressure SORTANTE
+ * (serveur → client). Protège la RAM d'envoi du serveur quand le client est lent à
+ * RECEVOIR (ne lit pas assez vite → `ws.bufferedAmount` gonfle → OOM). `broadcast()`
+ * amplifie : un seul client lent peut, sans borne, faire tomber la diffusion entière.
+ *
+ * PERF (hot path WS) : lecture O(1) de `ws.bufferedAmount`, **0 allocation sous le
+ * seuil** (chemin nominal = comportement inchangé). Au-delà : incrémente `_nfDrops`
+ * (lazy) et, si la politique est `close`, ferme la socket (RFC 6455 close 1013
+ * « Try Again Later » → le client peut back-off + reconnecter). NE FAIT PAS le `send()`
+ * — le caller émet uniquement si le retour vaut `"send"`.
+ *
+ * @param ws - la socket destinataire
+ * @param max - seuil d'octets (`<= 0` → désactivé)
+ * @param policy - action au dépassement
+ * @returns `"send"` (émettre) · `"drop"` (sauter cette frame) · `"close"` (socket fermée)
+ */
+export declare const decideSend: (ws: IBackpressureTarget, max: number, policy: WsBackpressurePolicy, closeAfterDrops?: number) => WsSendDecision;