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

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

@@ -20,106 +20,12 @@
  */
 import type { ProfiledResolver } from "./FrameProfile.js";
 import type { ProtocolName } from "../../interfaces/IContext.js";
-/** Une phase du pipeline, projetée pour le transport (durée résolue). */
-export interface ProfilePhase {
-    name: string;
-    /** Début relatif `performance.now()` (ms) — sert au calcul du waterfall. */
-    startMs: number;
-    /** Durée en ms, `null` si la phase ne s'est pas terminée (erreur). */
-    durationMs: number | null;
-}
-/**
- * Une requête SQL/NoSQL exécutée pendant la requête HTTP (SEAM ORM — futur).
- *
- * Non collecté aujourd'hui : quand `@nodefony/orm-core` arrivera, les adapters
- * pousseront leurs requêtes dans un buffer per-request dev-only (via l'ALS
- * `RequestContext.getRequestId()`, déjà en place) que `collect()` lira ici.
- * Le champ `queries` reste donc `undefined` tant qu'aucun ORM ne pushe → 0 coût.
- */
-export interface ProfileQuery {
-    /** Requête (SQL ou commande NoSQL), tronquée si volumineuse. */
-    sql: string;
-    /** Début relatif (`performance.now()`) — même horloge que les phases. */
-    startMs?: number | undefined;
-    /** Durée d'exécution en ms. */
-    durationMs: number;
-    /** Lignes affectées/retournées, si connu. */
-    rows?: number | undefined;
-    /** Connecteur émetteur (`drizzle`, `mongoose`…). */
-    connector?: string | undefined;
-}
-/**
- * Traversée du firewall par cette requête — **ce qui était possible** (la zone :
- * son nom, si elle est protégée, quels authenticators elle accepte) croisé avec
- * **ce qui s'est passé** (quel maillon a résolu l'identité, l'issue, le motif
- * d'un refus).
- *
- * Sans cela, une requête qui PASSE est invisible côté sécurité : le chemin de
- * succès n'émet aucun événement d'audit (choix délibéré — le volume nominal
- * n'est pas un signal). `undefined` hors zone firewall.
- */
-export interface ProfileSecurity {
-    /** Nom de la zone traversée. */
-    zone: string | null;
-    /** La zone exige-t-elle une identité (`security: true`) ? */
-    protected: boolean;
-    /** Chaîne d'authenticators : `first` = le premier qui supporte, `all` = MFA. */
-    mode: string | null;
-    /** Authenticators que la zone accepte (ce qui était POSSIBLE). */
-    candidates: string[];
-    /** Authenticator qui a RÉELLEMENT résolu l'identité. */
-    authenticator: string | null;
-    /** `granted` · `anonymous` · `denied` · `failure` · `throttled` · `bypass` · `public`. */
-    outcome: string | null;
-    /** Motif du refus (`no_credentials`, `invalid_credentials`…). */
-    reason: string | null;
-    /** Rôles du token résolu (l'axe autorisation). */
-    roles: string[] | null;
-}
-/** Profil complet d'une requête (HTTP ou message WS), exposé par `get`. */
-export interface ProfileEntry {
-    requestId: string;
-    /**
-     * Numéro d'ordre de collecte, croissant sur la vie du profileur. Un profil
-     * réinséré (identifiant réutilisé) reçoit un numéro neuf.
-     */
-    seq: number;
-    /** Horodatage de la collecte (`Date.now()`), pour le tri client. */
-    ts: number;
-    kind: "http" | "ws";
-    method: string | null;
-    url: string;
-    scheme: string;
-    status: number | null;
-    /** Durée totale serveur (ms), dérivée des phases. */
-    durationMs: number | null;
-    route: string | null;
-    controller: string | null;
-    action: string | null;
-    remoteAddress: string | null;
-    /** Identité (username) si le firewall l'a injectée, sinon `null`. */
-    user: string | null;
-    /** `traceparent` W3C Trace Context (P2.7) — corrélation distribuée RFC-propre. */
-    traceparent: string | null;
-    error: string | null;
-    phases: ProfilePhase[];
-    /** Requêtes ORM (SEAM futur — `undefined` tant qu'aucun adapter ne pushe). */
-    queries?: ProfileQuery[] | undefined;
-    /** Traversée du firewall — `undefined` si la requête n'a croisé aucune zone. */
-    security?: ProfileSecurity | undefined;
-}
-/** Résumé léger d'un profil pour la liste `recent` (sans les phases). */
-export interface ProfileSummary {
-    requestId: string;
-    ts: number;
-    kind: "http" | "ws";
-    method: string | null;
-    url: string;
-    status: number | null;
-    durationMs: number | null;
-    route: string | null;
-    error: string | null;
-}
+import type { IProfileEntry, IProfilePhase, IProfileQuery, IProfileSecurity, IProfileSummary } from "nodefony";
+export type ProfilePhase = IProfilePhase;
+export type ProfileQuery = IProfileQuery;
+export type ProfileSecurity = IProfileSecurity;
+export type ProfileEntry = IProfileEntry;
+export type ProfileSummary = IProfileSummary;
 /** Forme structurelle minimale lue sur un `Context` (lecture défensive). */
 interface ProfilableContext {
     requestId?: string | undefined;
@@ -142,6 +48,11 @@ interface ProfilableContext {
         durationMs?: number | undefined;
     }> | undefined;
     resolver?: ProfiledResolver | null | undefined;
+    /**
+     * Arrête l'horloge de la requête et rend sa durée (ms) — la même que le
+     * journal d'accès (`IContext.stopClock`). `null` si `timing.enabled` vaut `false`.
+     */
+    stopClock(): number | null;
     /**
      * Buffer de requêtes ORM rempli pendant la requête (dev-only). Même tableau
      * que la payload ALS — les adapters ORM y poussent via `RequestContext`.
@@ -205,6 +116,14 @@ export declare class Profiler implements IProfilerReader {
     private readonly _caps;
     /** Dernier numéro d'ordre attribué (0 = aucun profil collecté). */
     private _seq;
+    /**
+     * Démarrage du profileur, donc du processus (ms epoch, horloge du serveur) :
+     * aucune requête servie avant n'est connue. Rendu avec un profil absent, pour
+     * que le lecteur dise « le serveur a redémarré » plutôt que « évincé ».
+     */
+    readonly startedAt: number;
+    /** Dernier vidage des anneaux (ms epoch), `null` s'il n'y en a jamais eu. */
+    private _clearedAt;
     /**
      * @param cap - capacité de l'anneau de l'application.
      * @param sideCap - capacité de chacun des anneaux de l'outillage et des
@@ -222,8 +141,12 @@ export declare class Profiler implements IProfilerReader {
     get(requestId: string): ProfileEntry | undefined;
     /**
      * Résumés des requêtes les plus récentes (récent → ancien), capés à `limit`.
+     *
+     * @param limit - nombre maximal de résumés
+     * @param connection - le requestId d'une connexion WebSocket : ses SEULES
+     *   frames du pont (`<connection>.<n>`, règle `frameIndexOf` du cœur)
      */
-    recent(limit?: number): ProfileSummary[];
+    recent(limit?: number, connection?: string): ProfileSummary[];
     /** Dernier numéro d'ordre attribué : le point de départ d'une lecture suivie. */
     get cursor(): number;
     /**
@@ -240,7 +163,9 @@ export declare class Profiler implements IProfilerReader {
     since(cursor: number): IProfileBatch;
     /** Nombre de profils en mémoire. */
     get size(): number;
-    /** Vide les anneaux. */
+    /** Vide les anneaux, et retient l'instant du vidage ({@link clearedAt}). */
     clear(): void;
+    /** Dernier vidage des anneaux (ms epoch, horloge du serveur), `null` si aucun. */
+    get clearedAt(): number | null;
 }
 export default Profiler;

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

@@ -1,4 +1,6 @@
 import type { ProfileEntry } from "./Profiler.js";
+import type { IStatusBreakdown, IPhaseTotal, IRouteStats, INPlusOne, ISqlShapeStats, IErrorSample, IProfileReport } from "nodefony";
+export type { IStatusBreakdown, IPhaseTotal, IRouteStats, INPlusOne, ISqlShapeStats, IErrorSample, IProfileReport, };
 /**
  * Agrégation des profils de requêtes — règle PURE, sans horloge ni I/O.
  *
@@ -21,7 +23,14 @@ export declare const ROUTE_SAMPLE_CAP = 256;
 export declare const SQL_SHAPE_CAP = 200;
 /** Exemples d'erreurs retenus (statut ≥ 500 ou exception). */
 export declare const ERROR_SAMPLE_CAP = 10;
-/** Préfixe des routes de l'outillage (console, API d'administration, porte MCP). */
+/**
+ * Préfixe de l'espace réservé au framework.
+ *
+ * @deprecated Ne dit pas ce qui est de l'outillage : une connexion
+ *   d'utilisateur (`/nodefony/security/api/auth/…`) ou une route d'application
+ *   (`/nodefony/test/index`) passent sous ce préfixe. La règle est
+ *   `isConsolePath` (`nodefony`), que `profileLane` appelle.
+ */
 export declare const TOOLING_URL_PREFIX = "/nodefony/";
 /**
  * Provenance d'un profil : l'application, l'outillage (`/nodefony/…` :
@@ -30,8 +39,10 @@ export declare const TOOLING_URL_PREFIX = "/nodefony/";
  */
 export type ProfileLane = "app" | "tooling" | "asset";
 /**
- * Range un profil par provenance, d'après son URL. Seule règle du partage —
- * les anneaux du profileur et le filtre de l'agrégation la lisent tous deux.
+ * Range un profil par provenance, d'après son URL. L'outillage est reconnu par
+ * la règle du cœur, `isConsolePath` — la même que les Journaux, la barre de
+ * débogage et le Studio : une connexion d'utilisateur reste de l'application.
+ * Les anneaux du profileur et le filtre de l'agrégation la lisent tous deux.
  *
  * @param url - URL du profil, absolue ou chemin.
  * @returns la provenance du profil.
@@ -44,113 +55,19 @@ export declare function profileLane(url: string): ProfileLane;
  * @param url - URL du profil, absolue ou chemin.
  */
 export declare function isToolingUrl(url: string): boolean;
+/**
+ * Une requête de cette URL se profile-t-elle ? L'application toujours ;
+ * l'outillage et les assets relayés seulement sur demande (`timing.tooling`)
+ * — on ne mesure pas la façon dont on mesure.
+ *
+ * @param url - URL ou chemin de la requête (ou de la frame du pont)
+ * @param tooling - profiler aussi l'outillage
+ */
+export declare function isProfiledUrl(url: string, tooling: boolean): boolean;
 /** Groupe des requêtes qu'aucune route n'a servies (404, statique, sondes). */
 export declare const NO_ROUTE = "(aucune route)";
 /** Pseudo-phase : le temps de l'action hors phases imbriquées et hors SQL. */
 export declare const ACTION_SELF_PHASE = "action.self";
-/** Répartition des statuts HTTP d'une route. */
-export interface IStatusBreakdown {
-    s2xx: number;
-    s3xx: number;
-    s4xx: number;
-    s5xx: number;
-    /** Dont 401 : la route exige une authentification que la requête n'avait pas. */
-    unauthorized: number;
-    /** Dont 403 : authentifiée, mais refusée. */
-    forbidden: number;
-}
-/** Temps cumulé d'une phase sur les requêtes d'une route. */
-export interface IPhaseTotal {
-    totalMs: number;
-    /** Requêtes où la phase est apparue et s'est terminée. */
-    count: number;
-}
-/** Statistiques d'une route sur la fenêtre agrégée. */
-export interface IRouteStats {
-    route: string;
-    kind: "http" | "ws";
-    controller: string | null;
-    action: string | null;
-    count: number;
-    /** Requêtes sans durée mesurée (mesure des phases désactivée, erreur précoce). */
-    untimed: number;
-    /**
-     * Requêtes SERVIES et chronométrées (statut < 400, sans exception) : la
-     * population de tout ce qui se dit « par requête » ci-dessous. Refus et
-     * erreurs se lisent dans `status` et `errors`.
-     */
-    served: number;
-    /** Percentiles et maximum, sur les requêtes servies. */
-    p50Ms: number | null;
-    p95Ms: number | null;
-    maxMs: number | null;
-    status: IStatusBreakdown;
-    /** Requêtes en erreur : statut ≥ 500 ou exception levée. */
-    errors: number;
-    /**
-     * Requêtes SQL/NoSQL des requêtes servies : total, maximum dans une
-     * requête, temps CUMULÉ (des requêtes parallèles s'y additionnent).
-     */
-    queries: {
-        total: number;
-        perRequestMax: number;
-        totalMs: number;
-    };
-    /** Temps par phase des requêtes servies, `action.self` compris. */
-    phases: Record<string, IPhaseTotal>;
-}
-/** Un N+1 : la même forme SQL répétée dans une requête. */
-export interface INPlusOne {
-    route: string;
-    controller: string | null;
-    action: string | null;
-    shape: string;
-    /** Plus grand nombre de répétitions vu dans une requête. */
-    maxRepeats: number;
-    /** Requêtes touchées. */
-    requests: number;
-    /** Temps cumulé de ces répétitions. */
-    totalMs: number;
-    /** Une requête touchée, pour aller voir son profil complet. */
-    sampleRequestId: string;
-}
-/** Une forme SQL et son coût sur la fenêtre. */
-export interface ISqlShapeStats {
-    shape: string;
-    connector: string | null;
-    count: number;
-    totalMs: number;
-    maxMs: number;
-    /** Routes qui l'ont émise (au plus cinq). */
-    routes: string[];
-}
-/** Un exemple d'erreur, de quoi la retrouver dans le journal. */
-export interface IErrorSample {
-    route: string;
-    status: number | null;
-    error: string | null;
-    requestId: string;
-}
-/** Le rapport agrégé. */
-export interface IProfileReport {
-    /** Requêtes agrégées (hors outillage filtré). */
-    requests: number;
-    http: number;
-    ws: number;
-    /** Requêtes de l'outillage écartées (`/nodefony/…`, `/_vite/…`). */
-    filteredTooling: number;
-    /** Requêtes sans durée mesurée. */
-    untimed: number;
-    /** Triées par p95 décroissant. */
-    routes: IRouteStats[];
-    /** Triés par temps cumulé décroissant. */
-    nPlusOne: INPlusOne[];
-    /** Les dix formes SQL les plus coûteuses (temps cumulé décroissant). */
-    slowQueries: ISqlShapeStats[];
-    /** Formes SQL distinctes vues au-delà de la capacité, comptées sans détail. */
-    sqlShapesDropped: number;
-    errors: IErrorSample[];
-}
 /** Réglages d'une agrégation. */
 export interface IProfileAggregatorOptions {
     /** Répétitions à partir desquelles une forme SQL est un N+1. */

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

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

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

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

package/dist/types/nodefony/src/servers/upgradeDispatch.d.ts

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