@nodefony/http 10.0.0-beta.4 → 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;
@@ -51,6 +53,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

@@ -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/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/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
@@ -87,7 +101,7 @@ declare class WebsocketContext extends Context implements IWebsocketContextInter
     query: Record<string, string>;
     wsPath: string;
     constructor(scope: Scope, req: IncomingMessage, ws: Ws | null, serverType: ServerType);
-    log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
+    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
@@ -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/FrameProfile.d.ts

@@ -80,6 +80,12 @@ export declare class FrameProfile {
      * invocation, il redevient exact, et le SQL se replace dans le waterfall.
      */
     readonly profilerQueries: IProfilerQuery[] | null;
+    /**
+     * Ce profil sera-t-il gardé par le Profiler ? Faux quand seul le timing
+     * l'a ouvert (chemin d'outillage) : son id ne désigne alors aucun profil
+     * lisible, et ne doit pas être annoncé au client.
+     */
+    get profiled(): boolean;
     /** Resolver de la frame — porte route / controller / action. */
     resolver: ProfiledResolver | null;
     /** Statut HTTP-équivalent de l'invocation (200, 403, 404…). */
@@ -90,7 +96,16 @@ export declare class FrameProfile {
         message: string;
     } | null;
     private readonly timing;
+    private readonly clockStartMs;
+    private durationMs;
     constructor(init: FrameProfileInit);
+    /**
+     * Arrête l'horloge de la frame (au premier appel) et rend sa durée en ms ;
+     * `null` si le timing est éteint. Contrat de `IContext.stopClock`.
+     *
+     * @returns la durée de l'invocation, ou `null`
+     */
+    stopClock(): number | null;
     /**
      * Ouvre une phase. Contrairement au `Context`, l'index est un **scan arrière**
      * (pas de `Map<nom, index>`) : une frame porte une poignée de phases, et une