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

package/dist/types/nodefony/service/reverse-proxy.d.ts

@@ -0,0 +1,156 @@
+import http from "node:http";
+import type { Duplex } from "node:stream";
+import { Service, Module } from "nodefony";
+import type { IProxyMount, IProxyMountOptions } from "../interfaces/IReverseProxy.js";
+import { type ProxiedRequest, type ProxiedResponse } from "../src/proxy/forward.js";
+/** Un montage tel que le service le garde : la dernière cible analysée y est mise en cache. */
+interface IMountRecord extends IProxyMount {
+    /** D'où vient le montage : la configuration de l'application, ou un module. */
+    readonly source: "config" | "module";
+    /** Dernière origine rendue par `target`, et son analyse. */
+    lastOrigin: string | undefined;
+    lastUrl: URL | undefined;
+    /** Pool de connexions vers l'amont, créé au premier relais (scheme de la cible). */
+    agent: http.Agent | null;
+    /** Tunnels WebSocket ouverts vers l'amont — bornés par `maxSockets`, hors pool. */
+    tunnels: number;
+}
+/**
+ * Proxy inverse de Nodefony : relaie un préfixe d'URL vers un autre serveur
+ * HTTP — requêtes ET, sur demande, upgrades WebSocket — sur la MÊME origine
+ * que la page. Le client ne voit qu'un serveur, un certificat ; l'amont peut
+ * rester sur la boucle locale.
+ *
+ * Deux sources de montages, mêmes règles (`src/proxy/rules.ts`) : la section
+ * `proxy.mounts` de la configuration, lue à la construction, et
+ * {@link ReverseProxy.mount}, appelé par un module (`@nodefony/frontend` y
+ * relaie `/_vite/<famille>/` vers ses serveurs Vite de développement). Un
+ * module se résout ce service par NOM (`container.get("reverse-proxy")`) :
+ * il n'a pas à importer `@nodefony/http`.
+ *
+ * Consulté AVANT le routage : une route attrape-tout de l'application ne peut
+ * pas avaler un préfixe relayé. Sans montage, le pipeline ne paie qu'une
+ * lecture de champ (`mounts === null`) — c'est le cas de toute application
+ * qui ne s'en sert pas.
+ *
+ * Règles communes à tout montage : en-têtes de connexion jamais transmis
+ * (RFC 9110 §7.6.1), `X-Forwarded-For/-Proto/-Host` et `Via` posés par le
+ * proxy, Host hors `trustedHosts` jamais relayé (même barrière, même 421 que
+ * toute requête), amont injoignable → 502, amont muet → 504, boucle → 508.
+ */
+declare class ReverseProxy extends Service {
+    #private;
+    module: Module;
+    /**
+     * Montages actifs, du préfixe le PLUS LONG au plus court : le premier qui
+     * couvre une URL est le plus spécifique. `null` tant qu'il n'y en a aucun.
+     */
+    mounts: IMountRecord[] | null;
+    /** Délai d'inactivité appliqué aux montages qui n'en fixent pas (`proxy.timeoutMs`). */
+    readonly defaultTimeoutMs: number;
+    /** Délai d'établissement de la connexion amont (`proxy.connectTimeoutMs`). */
+    readonly connectTimeoutMs: number;
+    /** Connexions simultanées par amont (`proxy.maxSockets`) : pool ET tunnels WebSocket. */
+    readonly maxSockets: number;
+    /**
+     * Nom de CE processus dans `Via` (RFC 9110 §7.6.3) : tiré au hasard au
+     * démarrage, il ne dit rien de la machine et distingue deux instances —
+     * un message qui le porte déjà est une boucle (508).
+     */
+    readonly pseudonym: string;
+    constructor(module: Module);
+    /**
+     * Relaie un préfixe d'URL vers un amont. Idempotent pour un même module :
+     * un même préfixe est remplacé. Un module qui recouvre un préfixe de la
+     * CONFIGURATION le remplace aussi, mais le dit — l'auteur de l'application
+     * doit pouvoir lire pourquoi son montage ne sert plus.
+     *
+     * @param prefix - préfixe d'URL (normalisé : `/` en tête et en fin)
+     * @param options - cible et réglages du montage
+     * @throws Error qui nomme chaque refus (préfixe `/` ou réservé, cible qui
+     *   n'est pas une origine http(s) nue, `secure: false` hors boucle locale…)
+     */
+    mount(prefix: string, options: IProxyMountOptions): void;
+    /**
+     * Retire un montage. Le dernier retiré rend `mounts` à `null` : le pipeline
+     * cesse alors de le consulter.
+     *
+     * @param prefix - préfixe tel que monté (normalisé de la même façon)
+     */
+    unmount(prefix: string): void;
+    /**
+     * Ferme tous les pools (arrêt du noyau). Les montages restent déclarés ; un
+     * relais encore en vol part ensuite sur une connexion à usage unique.
+     */
+    closeAll(): void;
+    /**
+     * Montage le plus spécifique qui couvre une URL, s'il y en a un.
+     *
+     * @param url - cible brute de la requête (chemin + requête)
+     * @returns le montage au préfixe le plus long qui couvre l'URL
+     */
+    match(url: string | undefined): IProxyMount | undefined;
+    /**
+     * Origine courante d'un montage, analysée — mise en cache tant que la cible
+     * rend la même chaîne.
+     *
+     * @returns l'URL de l'amont, ou `undefined` si rien n'est relayable
+     */
+    private targetOf;
+    /**
+     * Pool de connexions d'un montage, créé au premier relais et recréé si la
+     * cible change de scheme.
+     *
+     * Un `Agent` DÉDIÉ, jamais l'agent global : sous `NODE_USE_ENV_PROXY`, cas
+     * courant d'un poste d'entreprise, l'agent global envoie tout vers
+     * `HTTP_PROXY` — un amont sur la boucle locale serait demandé au proxy de
+     * l'entreprise. Un agent construit ici n'a pas de `proxyEnv` : il va droit
+     * à la cible. Keep-alive borné (`maxSockets`), `lifo` : le socket le plus
+     * récent, le moins susceptible d'avoir été fermé par l'amont.
+     */
+    private agentFor;
+    /** Réglages de relais d'un montage. */
+    private relayFor;
+    /** Règles du noyau HTTP (résolues par nom), `undefined` hors serveur. */
+    private rules;
+    /** Ce que le proxy annonce à l'amont sur le client. */
+    private fromOf;
+    /**
+     * Relaie une requête HTTP si un montage la couvre — méthode comprise. Cible
+     * pas encore connue → `503` + `Retry-After`, sans aller jusqu'au routage.
+     *
+     * L'appelant a déjà tranché la barrière d'hôte : c'est le pipeline HTTP, qui
+     * la calcule pour toute requête (`Context.validDomain`). Un chemin ambigu
+     * sous un préfixe monté rend 400, sans contacter l'amont.
+     *
+     * ⚠️ Un préfixe monté est servi AVANT le pare-feu, la CSRF et les en-têtes
+     * de sécurité applicatifs : c'est une surface publique pour qui atteint
+     * Nodefony. L'amont porte sa propre politique d'accès.
+     *
+     * @param req - requête du client
+     * @param res - réponse au client
+     * @param scheme - scheme par lequel le client est arrivé
+     * @returns la promesse de fin d'échange, ou `undefined` si la requête n'est
+     *   pas relayée (hors préfixe ou méthode non relayée : elle suit alors son
+     *   chemin normal)
+     */
+    forward(req: ProxiedRequest, res: ProxiedResponse, scheme: string): Promise<void> | undefined;
+    /**
+     * Relaie un upgrade WebSocket si un montage `websocket` couvre son URL.
+     * Appelé par le répartiteur d'`upgrade` des serveurs WebSocket, AVANT le
+     * serveur WebSocket de Nodefony.
+     *
+     * Contrôles, dans l'ordre, chacun avec la réponse que rendrait le serveur
+     * WebSocket de Nodefony : cible pas encore connue → 503 ; `Host` hors `trustedHosts` (si `domainCheck`) →
+     * 421 ; chemin ambigu ou handshake non conforme (RFC 6455 §4.2.1 — seul
+     * `Upgrade: websocket` est relayé, jamais un tunnel `h2c`) → 400 ;
+     * `Origin` refusée par la MÊME règle que le serveur WebSocket (anti-CSWSH,
+     * RFC 6455 §10.2) → 403 ; `maxSockets` tunnels déjà ouverts vers l'amont →
+     * 503 ; quotas par IP du noyau (débit de handshakes, connexions
+     * simultanées) → 429. Le socket est alors consommé.
+     *
+     * @returns `true` si le proxy a pris le socket en charge
+     */
+    handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
+}
+export default ReverseProxy;

package/dist/types/nodefony/service/servers/server-websocket-secure.d.ts

@@ -7,6 +7,7 @@ import { AddressInfo } from "node:net";
 import type { IncomingMessage } from "node:http";
 import httpsServers from "./server-https.js";
 declare class WebsocketSecure extends Service {
+    #private;
     private readonly httpKernel;
     options: IHttpConfig["websocketSecure"] & DefaultOptionsService;
     module: Module;

package/dist/types/nodefony/service/servers/server-websocket.d.ts

@@ -7,6 +7,7 @@ import { AddressInfo } from "node:net";
 import type { IncomingMessage } from "node:http";
 import httpServer from "./server-http.js";
 declare class Websocket extends Service {
+    #private;
     private readonly httpKernel;
     options: IHttpConfig["websocket"] & DefaultOptionsService;
     module: Module;

package/dist/types/nodefony/service/servers/wsHeartbeat.d.ts

@@ -13,6 +13,18 @@ export interface IWsHeartbeatOptions {
     /** Délai (ms) accordé pour recevoir le `pong` avant de couper la socket. */
     keepaliveGracePeriod?: number;
 }
+/**
+ * Ce que le tick lit et écrit d'une connexion — la socket `ws` en production.
+ */
+export interface IHeartbeatClient {
+    readonly readyState: number;
+    ping(): void;
+    terminate(): void;
+    /** Dernier signe de vie (date du dernier `pong`, ou de la connexion). */
+    _nfLastPong?: number;
+    /** Date du dernier `ping` émis ; `0` = aucun ping en attente de réponse. */
+    _nfPingedAt?: number;
+}
 /**
  * Arme le suivi keep-alive d'UNE connexion : initialise l'horodatage de vie et
  * attache l'unique listener `pong` qui le rafraîchit.
@@ -24,6 +36,20 @@ export interface IWsHeartbeatOptions {
  * @param ws - la socket fraîchement connectée
  */
 export declare const trackPong: (ws: Ws) => void;
+/**
+ * Un tick du keep-alive : pingue les connexions muettes depuis `interval`, et
+ * coupe celles dont le ping attend sa réponse depuis plus de `grace`.
+ *
+ * Fonction PURE du temps : l'horloge est passée en argument, si bien que la
+ * règle se prouve pas à pas, sans minuteur réel — un banc qui la prouverait à
+ * l'horloge murale confondrait une boucle d'événements chargée avec un zombie.
+ *
+ * @param clients - les connexions du serveur
+ * @param now - l'instant du tick (`performance.now()` en production)
+ * @param interval - délai sans signe de vie avant un ping, ms
+ * @param grace - délai accordé au pong avant de couper, ms
+ */
+export declare const heartbeatTick: (clients: Iterable<IHeartbeatClient>, now: number, interval: number, grace: number) => void;
 /**
  * Démarre le heartbeat keep-alive du serveur : détecte les connexions zombies
  * (half-open — TCP encore ouvert mais le pair a disparu sans frame Close) et les

package/dist/types/nodefony/service/sessions/sessions-service.d.ts

@@ -1,6 +1,6 @@
 import { Service, Module } from "nodefony";
 import type { IPage } from "nodefony";
-import type { ISessionStorage, ISessionSummary, ISessionRecord, ISessionListQuery } from "../../interfaces/ISession.js";
+import type { ISessionStorage, ISerializedSession, ISessionSummary, ISessionRecord, ISessionListFilter, ISessionListQuery } from "../../interfaces/ISession.js";
 import HttpKernel, { ContextType } from "../http-kernel.js";
 import Session, { OptionsSessionType } from "../../src/session/session.js";
 import type { IHttpConfig } from "../../config/config.js";
@@ -191,6 +191,24 @@ declare class SessionsService extends Service {
      * est sûre. Idempotent — `false` si aucun `ref` ne correspond.
      */
     destroyByRef(ref: string, actor?: string | null): Promise<boolean>;
+    /**
+     * Détruit TOUTES les sessions dont le contenu satisfait `match` — la primitive
+     * des révocations groupées (« déconnecter partout », déconnexion demandée par
+     * un fournisseur d'identité). Ni journal ni audit : l'appelant, qui connaît le
+     * motif, les émet.
+     *
+     * @remarks Quand la méthode rend la main, il ne reste AUCUNE session qui
+     * satisfait `match` (au plus `MAX_LOGOUT_PASSES` passages). Une révocation qui
+     * en laisse une seule n'est pas une imprécision, c'est une faille.
+     *
+     * @param filter - restriction poussée au store (`user` : WHERE indexable) ;
+     *   `undefined` parcourt tout le parc.
+     * @param match - prédicat sur la session sérialisée — il doit RE-VÉRIFIER ce
+     *   que `filter` exprime, un store pouvant l'ignorer.
+     * @returns le nombre de sessions détruites.
+     * @throws Error si le store actif ne sait pas énumérer ses sessions.
+     */
+    destroyWhere(filter: ISessionListFilter | undefined, match: (data: ISerializedSession) => boolean): Promise<number>;
     /**
      * « Déconnexion partout » : détruit TOUTES les sessions d'un utilisateur (scan
      * O(N) — pas d'index inverse, acceptable en admin). Renvoie le nombre détruit.

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

@@ -1,5 +1,5 @@
 import { Container, Service, Severity, Msgid, Message, Pci, Pdu, KernelEventsType, nodefonyError, Scope } from "nodefony";
-import type { IProfilerQuery } from "nodefony";
+import type { IProfilerQuery, RequestContextPayload } from "nodefony";
 import type { IRouteResolver, IRequestRouter } from "../../interfaces/IRouting.js";
 import type { ISecurityZone } from "../../interfaces/ISecurity.js";
 import { WebSocketServer } from "ws";
@@ -43,7 +43,6 @@ declare class Context extends Service implements IContextInterface {
     secure: boolean;
     security?: ISecurityZone | null | undefined;
     cleaned: boolean;
-    isControlledAccess: boolean;
     validDomain: boolean;
     finished: boolean;
     pushAllowed: boolean;
@@ -68,6 +67,14 @@ declare class Context extends Service implements IContextInterface {
     session: Session | null | undefined;
     cookieSession: Cookie | null | undefined;
     user: unknown;
+    /**
+     * Identifiant de l'appelant AUTHENTIFIÉ, posé par le pare-feu ; `null` hors
+     * zone ou pour un anonyme. Lisible au démontage, hors de la bulle ALS : c'est
+     * ce que lisent le journal d'audit et le profileur. Distinct de `user`, qui
+     * lie la session à son principal de SESSION — y écrire l'identité d'un jeton
+     * rattacherait la session d'un autre compte.
+     */
+    userIdentifier: string | null;
     waitAsync: boolean;
     isJson: boolean;
     protected _isHtml: boolean | null;
@@ -116,6 +123,7 @@ declare class Context extends Service implements IContextInterface {
     private _phaseIndex;
     private _afterResponseFns;
     private _afterResponseFired;
+    private requestStore;
     private _abortController;
     metaData: Data;
     scheme: SchemeType;
@@ -160,6 +168,18 @@ declare class Context extends Service implements IContextInterface {
     get signal(): AbortSignal;
     _abortIfPending(reason?: string): void;
     log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    /**
+     * Confie au contexte le magasin `RequestContext` de son unité de travail
+     * (requête HTTP, connexion WebSocket), pour qu'il le VIDE à son nettoyage.
+     *
+     * Un minuteur ou une promesse armé pendant l'unité de travail capture ce
+     * magasin et le garde au-delà de la réponse — avec le contexte, l'identité
+     * et le jeton du pare-feu. Le vidage ({@link RequestContext.release}) n'y
+     * laisse que la corrélation et le scope refermé.
+     *
+     * @param store - le magasin passé à `RequestContext.run`
+     */
+    holdRequestStore(store: RequestContextPayload): void;
     clean(): void;
     /**
      * Log d'un event du cycle de vie — gate boot-time (V2.1) : en production le

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

@@ -13,12 +13,22 @@
  * Politique de compilation (sûre, ancrée, ReDoS-free) :
  * - string sans `*` → match EXACT ancré (`^...$`, le `.` est littéral).
  * - string avec `*` → wildcard UN label (`*.example.com` → `^[^.]+\.example\.com$`,
- *   RFC 6125 TLS-wildcard : matche `img.example.com`, pas `a.b.example.com` ni `example.com`).
+ *   RFC 9525 TLS-wildcard : matche `img.example.com`, pas `a.b.example.com` ni `example.com`).
  * - `RegExp` → reprise telle quelle (l'auteur assume l'ancrage).
  *
  * Compilation faite UNE fois (boot / enregistrement de route) ; le test par
  * requête est un simple `RegExp.test` sur une liste pré-compilée (zéro alloc hot-path).
  */
+/**
+ * Nom d'hôte d'une autorité brute (`host[:port]`), sans port — la valeur que
+ * rendrait `URL.hostname` pour une autorité déjà canonique, sans en payer le
+ * parse (`indexOf` + `slice`, #508). Un littéral IPv6 garde ses crochets
+ * (`[::1]:5151` → `[::1]`) : couper au premier `:` le réduirait à `[`.
+ *
+ * @param host - autorité brute (`Host`), éventuellement absente
+ * @returns le nom d'hôte, `""` si l'autorité est absente
+ */
+export declare function hostnameOf(host: string | undefined): string;
 /** Un pattern de domaine : string (exact ou `*`-wildcard) ou `RegExp` (libre). */
 export type DomainPattern = string | RegExp;
 /**

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

@@ -30,11 +30,24 @@ export interface ProxyType {
     proxyRealIp?: string | undefined;
     proxyVia?: string | undefined;
 }
+/**
+ * Même URL (chemin, requête, hôte) sous un autre schéma et un autre port.
+ * `port` absent → port par défaut du schéma (omis de l'URL).
+ *
+ * @param from - URL de la requête.
+ * @param scheme - schéma cible.
+ * @param port - port du serveur cible, s'il est connu.
+ * @returns l'URL absolue de redirection.
+ */
+export declare function switchUrlScheme(from: URL, scheme: "http" | "https", port?: number): string;
 export type HttpRequestType = Http2Request | HttpRequest;
 export type HttpRsponseType = Http2Response | HttpResponse;
 import type { IHttpContext as IHttpContextInterface } from "../../../interfaces/IContext.js";
+import { type ISseStreamOptions, type SseStream } from "./SseStream.js";
 declare class HttpContext extends Context implements IHttpContextInterface {
     proxy: ProxyType | null;
+    /** Socket h1 inscrite dans `socketActiveContext` — retirée par `clean()`. */
+    private activeSocket;
     isRedirect: boolean;
     sended: boolean;
     request: HttpRequestType;
@@ -71,6 +84,16 @@ declare class HttpContext extends Context implements IHttpContextInterface {
      */
     handle(): MaybePromise<this>;
     setTimeout(): void;
+    /**
+     * Nettoie le contexte, et le DÉTACHE de sa socket h1 : la connexion
+     * persistante survit à la requête, et l'entrée de `socketActiveContext`
+     * retiendrait sinon tout le contexte jusqu'à sa fermeture. Seule l'entrée qui
+     * pointe encore sur CE contexte est retirée — une requête suivante sur la
+     * même socket a pu la réécrire. Le gestionnaire `timeout` de la socket ne
+     * trouve alors rien et prend le chemin « socket inactive → `destroy()` »,
+     * celui qu'il prenait déjà pour un contexte nettoyé.
+     */
+    clean(): void;
     /**
      * Sérialise la donnée selon son type (JSON, HTML, texte), pose statut et
      * en-têtes, puis l'envoie ({@link send}). Synchrone quand l'envoi l'est (#505).
@@ -115,6 +138,16 @@ declare class HttpContext extends Context implements IHttpContextInterface {
      * @returns la réponse, ou sa promesse quand l'écriture attend.
      */
     write(chunk: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise<Http2Response | HttpResponse>;
+    /**
+     * Répond par un flux d'événements serveur (`text/event-stream`).
+     *
+     * La requête ne se termine qu'à `close()` du flux, ou au départ du client.
+     *
+     * @param options - battement de cœur, délai `retry:` initial.
+     * @returns le flux, ou sa promesse quand une session est à sauver d'abord.
+     * @throws HttpError 500 quand la réponse est déjà partie.
+     */
+    openSse(options?: ISseStreamOptions): SseStream | Promise<SseStream>;
     flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse>;
     /**
      * Termine la requête : hook `onClose`, puis fin de la réponse si l'envoi ne
@@ -126,7 +159,21 @@ declare class HttpContext extends Context implements IHttpContextInterface {
     /** Fin de la réponse, sauf si l'envoi l'a déjà terminée. */
     private endResponse;
     redirect(Url: string, status?: number | string, headers?: Record<string, string | number>): HttpResponse;
+    /**
+     * Redirige vers la même URL en HTTPS, sur le port du serveur HTTPS lié —
+     * ou le port par défaut derrière un proxy, dont le port public est inconnu.
+     *
+     * @param status - code de redirection (défaut de `redirect`).
+     * @param headers - en-têtes ajoutés à la réponse.
+     */
     redirectHttps(status?: number | string, headers?: Record<string, string | number>): HttpResponse;
+    /**
+     * Redirige vers la même URL en HTTP, sur le port du serveur HTTP lié — ou
+     * le port par défaut derrière un proxy.
+     *
+     * @param status - code de redirection (défaut de `redirect`).
+     * @param headers - en-têtes ajoutés à la réponse.
+     */
     redirectHttp(status?: number | string, headers?: Record<string, string | number>): HttpResponse;
     getHostName(): string;
     getRemoteAddress(): string | null;

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

@@ -22,6 +22,9 @@ declare class HttpResponse {
      * 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.
+     *
+     * Une réponse SANS corps n'annonce aucun type : `Content-Type` décrit le
+     * contenu (RFC 9110 §8.3), et il n'y en a pas.
      */
     protected ensureContentTypeHeader(): void;
     /**

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

@@ -0,0 +1,155 @@
+import type HttpContext from "./HttpContext.js";
+/**
+ * Le flux d'événements serveur (SSE) d'une réponse HTTP — `text/event-stream`.
+ *
+ * SSE n'est pas une méthode : c'est un FORMAT de réponse, choisi à l'exécution
+ * par l'action. La route reste déclarée `GET` ou `POST`, et le même `POST` peut
+ * répondre en JSON ou en flux selon l'en-tête `Accept`.
+ *
+ * Ce que la classe porte, et qu'une action écrite à la main oubliait :
+ * - les en-têtes du flux (`Cache-Control: no-cache, no-transform`,
+ *   `X-Accel-Buffering: no` pour qu'un nginx ne mette pas le flux en tampon) ;
+ * - HTTP/1.1 ET HTTP/2 : en HTTP/1.1 Node découpe le corps en morceaux
+ *   (RFC 9112 §7.1) ; en HTTP/2 l'écriture passe par le FLUX, et aucun
+ *   `Transfer-Encoding` n'est posé (interdit, RFC 9113 §8.2.2) ;
+ * - la fermeture lue sur la RÉPONSE, jamais sur la requête : en HTTP/2,
+ *   `request.on("close")` part dès la fin du corps de la requête — c'est le
+ *   défaut qui avait tué l'ancien flux de la console d'administration ;
+ * - le délai d'inactivité de la requête DÉSARMÉ (un flux n'a pas de fin
+ *   attendue), remplacé par un battement de cœur sur un minuteur `unref` ;
+ * - la contre-pression : un client lent freine l'émetteur qui attend `send()` ;
+ *   un client qui ne lit PLUS est coupé au bout de `stallTimeout` ;
+ * - les gardes des connexions longues, les mêmes que pour une socket
+ *   WebSocket : plafond de connexions par IP (`wsMaxConnectionsPerIp`, un seul
+ *   budget pour les deux transports) et fermeture du flux quand l'identité qui
+ *   l'a ouvert est révoquée (`RevocationWatch`, cœur).
+ *
+ * Norme : WHATWG HTML §9.2 (copie hors ligne
+ * `nodefony-framework-dev/references/rfc/specs/whatwg-sse.md`).
+ */
+/** Options d'ouverture d'un flux. */
+export interface ISseStreamOptions {
+    /**
+     * Période du battement de cœur (commentaire `:`), en ms entre 1 et 2^31-1 —
+     * `false` pour l'éteindre. Défaut : 15 000, la valeur que la norme suggère
+     * contre les proxys qui coupent une connexion muette (§9.2.7).
+     */
+    heartbeat?: number | false | undefined;
+    /** Délai de reconnexion imposé au client (champ `retry:`), en ms. */
+    retry?: number | undefined;
+    /**
+     * Délai maximal pendant lequel une écriture peut rester bloquée — le client
+     * ne lit plus —, en ms entre 1 et 2^31-1 ; au-delà, la connexion est coupée.
+     * Remplace le délai d'inactivité de la requête, désarmé pendant un flux.
+     * `false` pour l'éteindre. Défaut : 30 000.
+     */
+    stallTimeout?: number | false | undefined;
+    /**
+     * Taille maximale d'un événement écrit, en octets (UTF-8). Au-delà, `send()`
+     * lève une `RangeError` au lieu d'écrire. Défaut : 1 Mio.
+     */
+    maxEventBytes?: number | undefined;
+    /**
+     * Durée de vie maximale du flux, en ms entre 1 et 2^31-1 : il est fermé
+     * ensuite, et un `EventSource` se reconnecte — en repassant par le pare-feu.
+     * `false` (défaut) : pas de borne.
+     */
+    maxDuration?: number | false | undefined;
+}
+/** Ce qu'un événement porte en plus de ses données. */
+export interface ISseSendOptions {
+    /** Type de l'événement (champ `event:`) — absent : `message`. */
+    event?: string | undefined;
+    /** Identifiant (champ `id:`) que le client renverra en `Last-Event-ID`. */
+    id?: string | undefined;
+}
+/** Battement de cœur par défaut, en ms (§9.2.7 : « every 15 seconds or so »). */
+export declare const SSE_HEARTBEAT_MS = 15000;
+/** Délai de blocage d'écriture par défaut, en ms. */
+export declare const SSE_STALL_TIMEOUT_MS = 30000;
+/** Taille maximale d'un événement par défaut, en octets (1 Mio). */
+export declare const SSE_MAX_EVENT_BYTES = 1048576;
+/**
+ * Un flux `text/event-stream` ouvert sur une réponse.
+ *
+ * Il s'obtient par {@link openSseStream} (ou `this.renderSse()` dans un
+ * contrôleur), jamais par `new` : l'ouverture écrit les en-têtes, et un flux
+ * sans en-têtes ne se rattrape pas.
+ */
+export declare class SseStream {
+    #private;
+    /** Le flux est-il fermé — par le serveur (`close()`) ou par le client parti ? */
+    get closed(): boolean;
+    /**
+     * Envoie un événement.
+     *
+     * @param data - texte envoyé tel quel, ou valeur sérialisée en JSON ; un
+     *   texte de plusieurs lignes part en autant de champs `data:`.
+     * @param options - type (`event`) et identifiant (`id`) de l'événement.
+     * @returns rien quand l'écriture est acceptée ; une promesse réglée au
+     *   `drain` quand le client lit moins vite qu'on écrit — l'attendre borne la
+     *   mémoire du serveur. Sans effet une fois le flux fermé.
+     * @throws TypeError quand `event` ou `id` contient une fin de ligne.
+     * @throws RangeError quand l'événement dépasse `maxEventBytes`.
+     */
+    send(data: unknown, options?: ISseSendOptions): Promise<void> | undefined;
+    /**
+     * Envoie un commentaire — ignoré par le client, utile pour garder une
+     * connexion vivante ou marquer le flux à la lecture.
+     *
+     * @returns comme {@link send}.
+     */
+    comment(text?: string): Promise<void> | undefined;
+    /**
+     * Impose au client un délai de reconnexion (champ `retry:`).
+     *
+     * @param ms - délai en millisecondes, entier positif.
+     * @returns comme {@link send}.
+     * @throws RangeError quand `ms` n'est pas un entier entre 0 et 2^31-1.
+     */
+    retry(ms: number): Promise<void> | undefined;
+    /**
+     * Appelle `listener` à la fermeture du flux, quelle qu'en soit la cause.
+     *
+     * L'écouteur est lié au contexte asynchrone de la requête au moment de
+     * l'enregistrement : la fermeture par le client part de la SOCKET, hors de
+     * la bulle de la requête, et un `RequestContext.get()` y rendrait `undefined`.
+     * Un flux déjà fermé appelle l'écouteur au tour suivant.
+     */
+    onClose(listener: () => void): void;
+    /**
+     * Ferme le flux et termine la requête. Idempotent.
+     *
+     * @returns la fin de la requête (hooks `onClose` du contexte compris).
+     */
+    close(): Promise<void> | undefined;
+}
+/**
+ * Le client accepte-t-il un flux d'événements ? Lit l'en-tête `Accept`.
+ *
+ * Un même `POST` répond en JSON ou en flux selon ce que demande le client
+ * (porte MCP) : c'est cette fonction qui tranche, et elle seule. Une plage
+ * `q=0` est un REFUS explicite (RFC 9110 §12.4.2) ; `*\/*` ne suffit pas — un
+ * client qui ne nomme pas le flux ne sait pas le lire.
+ *
+ * @param accept - valeur de l'en-tête `Accept`, absente ou multiple.
+ * @returns `true` quand `text/event-stream` est nommé avec un poids non nul.
+ */
+export declare function acceptsEventStream(accept: string | string[] | undefined): boolean;
+/**
+ * Ouvre un flux d'événements sur la réponse d'un contexte HTTP.
+ *
+ * Sauve la session d'abord — ses cookies partent avec les en-têtes, qu'on ne
+ * pourra plus toucher —, puis écrit les en-têtes du flux et désarme le délai
+ * d'inactivité de la requête.
+ *
+ * @param context - le contexte de la requête, pas encore répondu.
+ * @param options - battement de cœur, délai `retry:` initial.
+ * @returns le flux ouvert, ou sa promesse quand une session est à sauver.
+ * @throws HttpError 500 quand la réponse est déjà partie.
+ * @throws HttpError 429 quand l'IP du client a déjà tous ses flux et sockets
+ *   (`wsMaxConnectionsPerIp`) — refusé AVANT d'écrire quoi que ce soit.
+ * @throws RangeError quand un délai n'est ni `false` ni un entier entre 1 et
+ *   2^31-1, ou que `maxEventBytes` n'est pas un entier positif.
+ */
+export declare function openSseStream(context: HttpContext, options?: ISseStreamOptions): SseStream | Promise<SseStream>;

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

@@ -0,0 +1,20 @@
+import http2 from "node:http2";
+import type http from "node:http";
+/**
+ * La réponse a-t-elle été TERMINÉE par le serveur ? Règle UNIQUE, pour HTTP/1.1
+ * comme pour HTTP/2 — l'écouteur `close` du noyau (client parti → 499) et le
+ * timeout par flux de `HttpContext` l'appellent tous deux.
+ *
+ * Sous HTTP/2, la réponse Nodefony écrit et termine le FLUX
+ * (`stream.respond`/`stream.end`), jamais la réponse de compatibilité : son
+ * `writableEnded` reste à `false` alors que le client a tout reçu. Mais le
+ * flux seul ne suffit pas non plus : un flux ANNULÉ par le pair (RST_STREAM
+ * avant la fin) a LUI AUSSI `writableEnded === true`, Node terminant le côté
+ * écriture en le détruisant. `aborted` sépare la fin posée par le serveur de la
+ * coupure du client — même sémantique que `writableEnded` en HTTP/1.1.
+ *
+ * @param response - la réponse Node de la requête
+ * @returns `true` si le serveur a terminé la réponse (ou son flux HTTP/2) ;
+ *   `false` s'il ne l'a pas terminée, client parti compris
+ */
+export declare function responseEnded(response: http.ServerResponse | http2.Http2ServerResponse): boolean;

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

@@ -0,0 +1,16 @@
+/**
+ * URL d'une requête d'upgrade WebSocket, telle que le pipeline la lit.
+ *
+ * Seule construction : le contexte WebSocket en tire son chemin et sa requête,
+ * et le contrôle d'avant `101` en tire le chemin qu'il confronte aux routes.
+ * Deux constructions divergeraient — `//a/b` lu comme un chemin d'un côté, comme
+ * un hôte de l'autre — et une route acceptée par l'une serait refusée par
+ * l'autre.
+ *
+ * @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)
+ * @returns l'URL analysée
+ * @throws TypeError si l'hôte ou la cible ne forment pas une URL
+ */
+export declare function parseWebsocketUrl(scheme: string, host: string | undefined, rawUrl: string | undefined): URL;

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

@@ -116,6 +116,7 @@ export interface ProfileSummary {
 /** Forme structurelle minimale lue sur un `Context` (lecture défensive). */
 interface ProfilableContext {
     requestId?: string | undefined;
+    userIdentifier?: string | null | undefined;
     type?: string | undefined;
     scheme?: string | undefined;
     method?: string | null | undefined;