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

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

@@ -97,6 +97,12 @@ declare class Context extends Service implements IContextInterface {
     crossDomain: boolean;
     router: IRequestRouter | null;
     resolver: IRouteResolver | null;
+    /**
+     * Module qui signe les lignes de CETTE requête : la ligne d'accès et les
+     * lignes du contrôleur. `null` = le module de la route (sans route : le
+     * journal du noyau). Un contrôleur le change : `this.context.logModule = "billing"`.
+     */
+    logModule: string | null;
     /**
      * Intent de session de la route courante (posé par le Resolver depuis
      * `@UseSession` / paramètre `@Session`). Pilote le point d'activation unique
@@ -128,6 +134,9 @@ declare class Context extends Service implements IContextInterface {
     securityTrace: ISecurityTrace | null;
     private readonly _timingEnabled;
     private readonly _timingVerbose;
+    private readonly _clockEnabled;
+    private readonly _clockStartMs;
+    private _durationMs;
     readonly phases: PhaseTiming[];
     private _phaseIndex;
     private _afterResponseFns;
@@ -161,6 +170,21 @@ declare class Context extends Service implements IContextInterface {
     get timingEnabled(): boolean;
     phaseStart(name: PhaseName): void;
     phaseEnd(name: PhaseName): void;
+    /**
+     * Arrête l'horloge de la requête et rend sa durée, en millisecondes.
+     *
+     * La durée court de la construction du contexte au PREMIER appel : le
+     * démontage HTTP (`close` de la réponse, dernier octet remis — la mesure
+     * d'OpenTelemetry et du `$request_time` de nginx), la ligne d'accès pour un
+     * handshake WebSocket. Les appels suivants rendent la même valeur : journal
+     * d'accès, profiler et trace verbose lisent UNE durée, jamais trois.
+     *
+     * Active par défaut dans tous les environnements, production comprise :
+     * seul `timing.enabled: false` la coupe (cf `resolveTimingMode`).
+     *
+     * @returns la durée, ou `null` si `timing.enabled` vaut `false`
+     */
+    stopClock(): number | null;
     onAfterResponse(fn: AfterResponseHandler): void;
     /**
      * Exécute les hooks `onAfterResponse`, une seule fois, dans l'ordre
@@ -176,7 +200,7 @@ declare class Context extends Service implements IContextInterface {
     private runAfterResponseHooks;
     get signal(): AbortSignal;
     _abortIfPending(reason?: string): void;
-    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): Pdu;
     /**
      * Confie au contexte le magasin `RequestContext` de son unité de travail
      * (requête HTTP, connexion WebSocket), pour qu'il le VIDE à son nettoyage.

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

@@ -0,0 +1,109 @@
+import http from "node:http";
+import { Readable } from "node:stream";
+import type HttpContext from "./HttpContext.js";
+/**
+ * Réponse en FLUX D'OCTETS — la sortie d'un processus, le relais d'un autre
+ * service, une archive construite à la volée : toute source d'octets qui n'est
+ * pas un fichier du disque.
+ *
+ * Le cycle de vie (prise de la réponse, session, fermeture lue sur la réponse,
+ * plafond par IP, révocation, coupure d'un client qui ne lit plus) est celui de
+ * la brique commune au SSE (`StreamLifecycle`). Ce fichier porte ce qui est
+ * propre aux octets :
+ * - les en-têtes au PREMIER morceau : une erreur de la source avant lui passe
+ *   par le chemin d'erreur normal (`HttpKernel.onError`), donc un vrai 5xx ;
+ * - l'arrêt de la source par `destroy()`, jamais `unpipe()` — qui la laisse en
+ *   pause, et un producteur bloqué en écriture ne meurt plus ;
+ * - un chien de garde sur une source MUETTE (`idleTimeout`) : un seul minuteur
+ *   périodique par flux, qui compare le compteur d'octets — aucun minuteur ni
+ *   appel d'horloge par morceau (mesuré : l'horodatage par morceau coûtait
+ *   2 à 6 % de CPU sur des morceaux de 4 Kio) ;
+ * - la coupure (jamais une fin propre) quand la source échoue après le premier
+ *   octet : le client doit savoir que le corps est tronqué.
+ */
+/**
+ * Raison de la fin d'un flux d'octets.
+ *
+ * - `end` : la source est finie, ou le serveur a fermé le flux (durée de vie,
+ *   révocation de l'identité) ;
+ * - `client` : le client est parti ;
+ * - `error` : la source a échoué ;
+ * - `timeout` : la source est restée muette plus de `idleTimeout` ;
+ * - `stall` : le client ne lisait plus depuis `stallTimeout`.
+ *
+ * L'union PEUT S'AGRANDIR : un `switch` exhaustif garde une branche `default`.
+ */
+export type ByteStreamEndReason = "end" | "client" | "error" | "timeout" | "stall";
+/** Ce que rend la fin d'un flux d'octets. */
+export interface IByteStreamResult {
+    /** Pourquoi le flux s'est terminé. */
+    reason: ByteStreamEndReason;
+    /** Octets écrits sur la réponse. */
+    bytes: number;
+}
+/** Options d'une réponse en flux d'octets. */
+export interface IByteStreamOptions {
+    /** Statut de la réponse, entre 200 et 599. Défaut : 200. */
+    status?: number | undefined;
+    /**
+     * En-têtes de la réponse, écrits au premier morceau. `Content-Length` est
+     * repris s'il est fourni ; sinon HTTP/1.1 envoie par morceaux. Défauts posés
+     * seulement s'ils manquent — ni ici, ni déjà sur la réponse :
+     * `Content-Type: application/octet-stream`, et pour un flux `live`
+     * `Cache-Control: no-cache, no-transform` et `X-Accel-Buffering: no`.
+     */
+    headers?: http.OutgoingHttpHeaders | undefined;
+    /**
+     * Flux VIVANT (défaut `true`) : la sortie d'un processus, un relais — un
+     * proxy inverse ne doit pas le mettre en tampon, ni un cache le garder, d'où
+     * `Cache-Control: no-cache, no-transform` et `X-Accel-Buffering: no` par
+     * défaut. `false` pour une source FINIE et rejouable (un fichier, une
+     * archive) : aucun de ces deux en-têtes n'est posé.
+     */
+    live?: boolean | undefined;
+    /**
+     * Délai maximal sans un octet de la source, en ms ; `0` le désarme. Au-delà :
+     * 504 si rien n'est encore parti, coupure sinon. Le silence est constaté
+     * par un tour de garde tous les quarts de délai : la coupure tombe entre
+     * `idleTimeout` et 1,25 × `idleTimeout`. Défaut : le délai de réponse
+     * du serveur (`responseTimeout`, 30 s). À garder sous le délai de lecture du
+     * proxy inverse (`proxy_read_timeout`, 60 s chez nginx).
+     */
+    idleTimeout?: number | undefined;
+    /**
+     * Délai maximal pendant lequel une écriture peut rester bloquée — le client
+     * ne lit plus —, en ms ; au-delà, la connexion est coupée. `false` pour
+     * l'éteindre. Défaut : 30 000, celui du SSE.
+     */
+    stallTimeout?: number | false | undefined;
+    /** Durée de vie maximale du flux, en ms. `false` (défaut) : pas de borne. */
+    maxDuration?: number | false | undefined;
+    /**
+     * Appelé une fois à la fin du flux, avec sa raison — AVANT la fin de la
+     * requête et la résolution de la promesse. Lié au contexte asynchrone de la
+     * requête.
+     */
+    onClose?: ((reason: ByteStreamEndReason) => void) | undefined;
+}
+/** Une source d'octets : flux Node, ou flux web (`fetch().body`). */
+export type ByteStreamSource = Readable | ReadableStream<Uint8Array>;
+/**
+ * Répond par un flux d'octets sur la réponse d'un contexte HTTP.
+ *
+ * Prend la réponse à l'appel (le noyau ne peut plus répondre par-dessus) ;
+ * les en-têtes partent au premier morceau de la source. La promesse se règle à
+ * la fin du flux, quelle qu'en soit la raison, et ne rejette JAMAIS.
+ *
+ * @param context - le contexte de la requête, pas encore répondu.
+ * @param source - flux Node, ou flux web (`fetch().body`) ; jamais en mode objet.
+ * @param options - statut, en-têtes, délais, écouteur de fin.
+ * @returns la raison de la fin et le nombre d'octets envoyés.
+ * @throws TypeError quand la source est en mode objet.
+ * @throws RangeError quand une option est hors bornes.
+ * @throws HttpError 500 quand la réponse est déjà partie ; 429 quand l'IP a
+ *   déjà tous ses flux et sockets (`wsMaxConnectionsPerIp`).
+ *
+ * La source appartient au flux dès l'appel : quand l'appel lève, elle est
+ * DÉTRUITE (un flux web est annulé) avant que l'erreur ne remonte.
+ */
+export declare function openByteStream(context: HttpContext, source: ByteStreamSource, options?: IByteStreamOptions): Promise<IByteStreamResult>;

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

@@ -1,7 +1,8 @@
 import { ServerType, SchemeType } from "../../../service/http-kernel.js";
+import HttpError from "../../errors/httpError.js";
 import Context, { HTTPMethod } from "../Context.js";
-import { Container, Scope } from "nodefony";
-import type { MaybePromise } from "nodefony";
+import { Container, Scope, nodefonyError } from "nodefony";
+import type { DefaultEventsMap, EventsMap, MaybePromise } from "nodefony";
 import HttpRequest from "./Request.js";
 import HttpResponse from "./Response.js";
 import Http2Request from "../http2/Request.js";
@@ -42,14 +43,41 @@ export interface ProxyType {
 export declare function switchUrlScheme(from: URL, scheme: "http" | "https", port?: number): string;
 export type HttpRequestType = Http2Request | HttpRequest;
 export type HttpRsponseType = Http2Response | HttpResponse;
+/**
+ * Route le délai d'inactivité d'une socket HTTP/1.1 vers la requête qu'elle
+ * porte : 408/504 si une requête est en cours, fermeture si la connexion
+ * persistante est inactive. Écouteur `timeout` du SERVEUR — un seul pour
+ * toutes ses connexions —, que Node appelle avec la socket en argument
+ * (`socketOnTimeout` → `server.emit("timeout", socket)`).
+ *
+ * Pourquoi au serveur et pas sur la socket : Node y pose déjà son propre
+ * écouteur `timeout`, et un second faisait créer à `EventEmitter` un tableau
+ * d'écouteurs par CONNEXION. Ce site d'allocation, partagé avec tout le
+ * processus et toujours survivant (une connexion vit longtemps), finissait
+ * par être basculé dans le vieux tas par V8 (pretenuring) — dans un démarrage
+ * sur trois environ, mesuré sous charge. Le graphe de chaque requête y
+ * restait alors accroché jusqu'à la collecte complète suivante : +45 % de CPU
+ * par requête, 14 à 19 collectes complètes au lieu de 3. Un écouteur par
+ * serveur supprime aussi une fermeture et une entrée de registre par connexion.
+ *
+ * @param socket - la socket dont le délai a expiré ; une session HTTP/2 (même
+ *   événement sur un serveur `allowHTTP1`) est laissée à son propre délai
+ */
+export declare function routeSocketTimeout(socket: unknown): void;
 import type { IHttpContext as IHttpContextInterface } from "../../../interfaces/IContext.js";
 import { type ISseStreamOptions, type SseStream } from "./SseStream.js";
+import { type ByteStreamSource, type IByteStreamOptions, type IByteStreamResult } from "./ByteStream.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;
+    /**
+     * Requête relayée par le proxy inverse : la politique de ligne d'accès de
+     * son montage. `null` = servie par l'application (cas de toute requête).
+     */
+    relayAccessLog: "all" | "errors" | null;
     request: HttpRequestType;
     response: HttpRsponseType;
     uploadService: uploadService | null;
@@ -84,6 +112,14 @@ declare class HttpContext extends Context implements IHttpContextInterface {
      */
     handle(): MaybePromise<this>;
     setTimeout(): void;
+    /**
+     * Ligne d'accès — pour une requête RELAYÉE, avec le statut que l'amont a
+     * réellement rendu (le relais écrit la réponse brute, pas celle du
+     * contexte) ; un montage `accessLog: "errors"` ne l'écrit qu'en échec.
+     *
+     * @param httpError - l'erreur de la requête, s'il y en a une
+     */
+    logRequest(httpError?: Error | HttpError | nodefonyError | null): import("nodefony").Pdu | undefined;
     /**
      * Nettoie le contexte, et le DÉTACHE de sa socket h1 : la connexion
      * persistante survit à la requête, et l'entrée de `socketActiveContext`
@@ -143,11 +179,31 @@ declare class HttpContext extends Context implements IHttpContextInterface {
      *
      * La requête ne se termine qu'à `close()` du flux, ou au départ du client.
      *
+     * @typeParam Events - carte des événements du flux (cf `SseStream`).
      * @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>;
+    openSse<Events extends EventsMap = DefaultEventsMap>(options?: ISseStreamOptions): SseStream<Events> | Promise<SseStream<Events>>;
+    /**
+     * Répond par un FLUX D'OCTETS : un `<video src>`, un `fetch()`, un
+     * téléchargement ou un outil tiers (curl) le consomment comme n'importe quelle
+     * réponse HTTP, une réponse par consommateur.
+     *
+     * La réponse est prise à l'appel, ses en-têtes partent au premier morceau de
+     * la source. La source est DÉTRUITE à la fin, quelle qu'en soit la raison
+     * (jamais `unpipe`, qui laisse un producteur bloqué en écriture). Pour des
+     * événements texte lus par `EventSource`, voir {@link HttpContext.openSse}.
+     * Dans un middleware, la requête est répondue : ne pas appeler la suite.
+     *
+     * @param source - flux Node, ou flux web (`fetch().body`) ; jamais en mode objet.
+     * @param options - statut, en-têtes, délais, écouteur de fin.
+     * @returns la raison de la fin et le nombre d'octets ; ne rejette jamais.
+     * @throws HttpError 500 quand la réponse est déjà partie, 429 au-delà du
+     *   plafond de connexions par IP ; TypeError pour une source en mode objet.
+     *   Quand l'appel lève, la source est DÉTRUITE (un flux web est annulé).
+     */
+    openStream(source: ByteStreamSource, options?: IByteStreamOptions): Promise<IByteStreamResult>;
     flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse>;
     /**
      * Termine la requête : hook `onClose`, puis fin de la réponse si l'envoi ne
@@ -180,7 +236,7 @@ declare class HttpContext extends Context implements IHttpContextInterface {
     getHost(): string | undefined;
     getUserAgent(): string | undefined;
     getMethod(): HTTPMethod;
-    setContentType(type?: string, encoding?: BufferEncoding): void | http.ServerResponse<http.IncomingMessage>;
+    setContentType(type?: string, encoding?: BufferEncoding): void;
     protected resolveIsHtml(): boolean;
     setDefaultContentType(): void;
     setContextJson(encoding?: BufferEncoding): void;

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

@@ -220,12 +220,19 @@ declare class HttpRequest {
     getDomain(): string;
     getUserAgent(): string | undefined;
     getHostName(host?: string): string;
+    /**
+     * L'autorité de la requête : celle de la cible en forme absolue, sinon
+     * l'en-tête `Host` (RFC 9112 §3.2.2 — le serveur DOIT alors ignorer `Host`).
+     * HTTP/2 lit `:authority` (override).
+     */
     getHost(): string | undefined;
     getRemoteAddress(): string | null;
     /**
      * Request-target brut (origin-form) tel que reçu du transport — SOURCE
      * UNIQUE partagée par la concaténation de {@link getFullUrl} et la découpe
-     * fast-path du ctor. HTTP/2 lit le pseudo-header `:path` (override).
+     * fast-path du ctor. Une cible en forme absolue est ramenée à sa forme
+     * origine, son autorité passant par {@link getHost}. HTTP/2 lit le
+     * pseudo-header `:path` (override).
      */
     getRawTarget(): string | undefined;
     /**

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

@@ -1,9 +1,21 @@
-import http, { OutgoingHttpHeaders } from "node:http";
+import http, { OutgoingHttpHeaders, OutgoingHttpHeader } from "node:http";
 import http2 from "node:http2";
 import HttpContext from "../http/HttpContext.js";
 import { Pci, Pdu, Message, Severity, Msgid } from "nodefony";
 import type { MaybePromise } from "nodefony";
 import Cookie from "../../cookies/cookie.js";
+import type { IFirewallGate } from "../../../interfaces/ISecurity.js";
+/**
+ * Vrai pour un statut dont la réponse n'a, par définition, aucun contenu —
+ * 204, 205 et 304 (RFC 9110 §15.3.5, §15.3.6, §15.4.5).
+ *
+ * Seule source de cette liste : la réponse s'en sert pour ne jamais écrire de
+ * corps, le résolveur pour terminer une action qui ne rend rien.
+ *
+ * @param status - le code de statut de la réponse.
+ * @returns `true` quand aucun corps ne doit partir.
+ */
+export declare function isContentlessStatus(status: number): boolean;
 declare class HttpResponse {
     #private;
     context: HttpContext;
@@ -16,6 +28,13 @@ declare class HttpResponse {
     headers: http.OutgoingHttpHeaders;
     timeout?: number | undefined;
     cookies: Record<string, Cookie>;
+    /**
+     * Pare-feu qui posera les en-têtes de sécurité applicatifs juste avant
+     * l'émission des en-têtes, une fois le type de la réponse fixé : la politique
+     * suit ce type (ADR-0024 §C11). Armé par le noyau HTTP au routage, consommé
+     * une fois ; `null` sans module de sécurité.
+     */
+    headerPolicy: IFirewallGate | null;
     constructor(response: http.ServerResponse | http2.Http2ServerResponse, context: HttpContext);
     /**
      * Filet posé juste avant l'émission des en-têtes : si aucun `Content-Type`
@@ -36,7 +55,9 @@ declare class HttpResponse {
     /**
      * Corps tel qu'il part sur le fil : le texte s'il n'a jamais été encodé, sinon
      * les octets — vide légal si rien n'a été posé (`write(null)` jetterait
-     * ERR_STREAM_NULL_VALUES).
+     * ERR_STREAM_NULL_VALUES). Vide aussi sous un statut sans contenu : un corps
+     * posé par l'application sous un 205 ne part pas (RFC 9110 §15.3.6) — Node
+     * ne l'écarte de lui-même que pour 204 et 304.
      */
     protected get payload(): string | Buffer;
     /** Encodage à passer avec {@link payload} (ignoré par Node pour des octets). */
@@ -48,8 +69,8 @@ declare class HttpResponse {
     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>;
+    setCookies(): void;
+    setCookie(cookie: Cookie): void;
     /**
      * Journalise en DEBUG un cookie posé, sa VALEUR MASQUÉE : nom et attributs
      * seulement. Le journal de développement se lit par le plan d'administration
@@ -61,11 +82,91 @@ declare class HttpResponse {
      * @param serialized - sa forme `Set-Cookie`, déjà calculée pour l'en-tête.
      */
     private logCookie;
-    setHeader(name: string, value: number | string | readonly string[]): void | http.ServerResponse<http.IncomingMessage>;
+    /**
+     * Pose un en-tête de la réponse ; en flux chunké déjà ouvert, le range en
+     * trailer. Le nom et la valeur sont VALIDÉS ici, comme le ferait Node : une
+     * valeur invalide (saut de ligne…) lève tout de suite et n'entre jamais dans
+     * la réserve — sinon elle lèverait au `writeHead`, et la page d'erreur
+     * rejouerait le même en-tête.
+     *
+     * @param name - nom de l'en-tête (casse indifférente).
+     * @param value - valeur ; une liste émet une ligne par élément (`Set-Cookie`).
+     * @throws TypeError `ERR_INVALID_HTTP_TOKEN` / `ERR_INVALID_CHAR` sur un nom
+     *   ou une valeur qu'un en-tête HTTP ne peut pas porter.
+     */
+    setHeader(name: string, value: number | string | readonly string[]): void;
+    /**
+     * Pose un en-tête dont la valeur a DÉJÀ été validée par l'appelant — une
+     * table figée et contrôlée au démarrage (en-têtes de sécurité). Node la
+     * validera une fois, au `writeHead` ; la revalider ici effaçait le gain de
+     * l'écriture groupée (`micro-write-head.mjs`, ligne « plat validé »).
+     *
+     * ⚠️ Jamais pour une valeur venue d'une requête : elle passe par {@link setHeader}.
+     *
+     * @param name - nom de l'en-tête (casse indifférente).
+     * @param value - valeur contrôlée au démarrage.
+     */
+    setValidatedHeader(name: string, value: string): void;
+    /**
+     * Pose un en-tête validé au démarrage SAUF si la réponse en porte déjà un :
+     * la valeur du framework est un défaut, celle que l'application a écrite
+     * gagne. Même coût que {@link setValidatedHeader} — le rangement cherche
+     * l'en-tête de toute façon.
+     *
+     * @param name - nom de l'en-tête (casse indifférente).
+     * @param value - valeur contrôlée au démarrage.
+     */
+    setDefaultHeader(name: string, value: string): void;
+    /**
+     * Pose les en-têtes de la politique armée ({@link headerPolicy}) pour une
+     * réponse de type `contentType` — une fois, juste avant l'émission.
+     *
+     * Un `304` n'en reçoit aucun : ses en-têtes REMPLACENT ceux de la
+     * représentation en cache (RFC 9111 §4.3.4). Une politique courte y
+     * réduirait la page gardée, un nonce neuf la désaccorderait de ses balises.
+     *
+     * @param contentType - type de la réponse ; `null` = sans contenu ; `undefined`
+     *   = inconnu (politique complète).
+     * @param servedAsFile - corps écrit par un tiers (fichier statique, relais),
+     *   qui ne peut pas porter de nonce.
+     */
+    protected applyHeaderPolicy(contentType: string | null | undefined, servedAsFile?: boolean): void;
+    /**
+     * Type qui choisit la politique : `null` pour une réponse sans contenu (204,
+     * corps vide) — même si un `Content-Type` y a été posé, rien n'y sera rendu ;
+     * sinon le `Content-Type` posé.
+     */
+    protected contentTypeForPolicy(): string | null;
+    /**
+     * Recopie la réserve sur la réponse Node, pour un émetteur qui écrit sans
+     * passer par {@link writeHead} — fichier statique, relais vers un amont. La
+     * réserve se vide ; ce qui se pose ensuite y retourne, et Node fusionne les
+     * deux au `writeHead`.
+     */
+    commitHeaders(): void;
+    /**
+     * Recopie la réserve sur la réponse Node au PREMIER `setHeader` qu'un tiers
+     * y fera — fichier statique servi, redirection de dossier — et seulement
+     * alors : un raté du repli statique (la 404 d'une route inconnue) ne recopie
+     * rien, sa réponse part ensuite en un seul `writeHead`. À désarmer par
+     * {@link disarmNativeWrite} quand le tiers rend la main sans avoir écrit.
+     *
+     * L'interception est une propriété PROPRE de la réponse, ajoutée puis
+     * retirée : V8 annule alors la dernière transition de forme de l'objet.
+     */
+    commitBeforeNativeWrite(): void;
+    /** Retire l'interception posée par {@link commitBeforeNativeWrite}. */
+    disarmNativeWrite(): void;
+    /**
+     * Retire un en-tête, de la réserve comme de la réponse Node.
+     *
+     * @param name - nom de l'en-tête (casse indifférente).
+     */
+    removeHeader(name: string): void;
     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>;
+    setContentType(type?: string, encoding?: BufferEncoding): void;
+    setFileMimeType(type: string, encoding?: BufferEncoding): void;
+    setContentTypeByExtension(extention: string): void;
     getMimeType(filenameOrExt: string): string | false;
     setEncoding(encoding: BufferEncoding): BufferEncoding;
     setStatusCode(status: number | string, message?: string): {
@@ -88,7 +189,25 @@ declare class HttpResponse {
     setBody(ele: unknown, encoding?: BufferEncoding): void;
     setLength(body?: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
     writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void;
+    /** La réserve amorcée — pour une remise sous une autre forme (HTTP/2). */
+    protected headerList(): readonly OutgoingHttpHeader[];
     addTrailers(headers: http.OutgoingHttpHeaders): void;
+    /**
+     * Écrit un morceau d'une réponse en flux, sans la terminer — c'est `end()`
+     * qui la clôt après le dernier.
+     *
+     * Au premier morceau, les en-têtes partent SANS longueur ni corps posé (le
+     * patron de `SseStream`), et le cadrage revient à Node : `chunked` pour un
+     * client HTTP/1.1, fermeture de connexion pour un HTTP/1.0 (RFC 9112 §6.1 —
+     * pas de `Transfer-Encoding` à qui ne le connaît pas), trames DATA en HTTP/2
+     * où l'en-tête est interdit (RFC 9113 §8.2.2). Ne JAMAIS le poser à la main :
+     * une fois `flushing` levé, `setHeader` range en trailer, et un
+     * `Transfer-Encoding` en trailer est un message malformé (RFC 9110 §6.5.1).
+     *
+     * @param chunk - le morceau à écrire.
+     * @param encoding - l'encodage d'un morceau texte.
+     * @returns la promesse réglée quand le flux accepte l'écriture suivante.
+     */
     flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse>;
     /**
      * Écrit le corps sur le flux et, pour une réponse unique, la termine.
@@ -113,8 +232,15 @@ declare class HttpResponse {
      * @throws de façon SYNCHRONE quand la réponse Node n'existe plus.
      */
     end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise<http.ServerResponse | http2.ServerHttp2Stream>;
+    /**
+     * Valeur d'un en-tête posé — dans la réserve, sinon sur la réponse Node (ce
+     * qu'un tiers y a écrit directement : `send`, quota).
+     *
+     * @param name - nom de l'en-tête (casse indifférente).
+     */
     getHeader(name: string): string | number | string[] | undefined;
     hasHeader(name: string): boolean;
+    /** Tous les en-têtes posés, noms en minuscules — une copie, à chaque appel. */
     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;

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

@@ -1,4 +1,5 @@
 import type HttpContext from "./HttpContext.js";
+import type { DefaultEventsMap, EventNames, EventsMap } from "nodefony";
 /**
  * Le flux d'événements serveur (SSE) d'une réponse HTTP — `text/event-stream`.
  *
@@ -56,10 +57,14 @@ export interface ISseStreamOptions {
      */
     maxDuration?: number | false | undefined;
 }
-/** Ce qu'un événement porte en plus de ses données. */
-export interface ISseSendOptions {
+/**
+ * Ce qu'un événement porte en plus de ses données.
+ *
+ * @typeParam K - nom de l'événement : un canal du contrat quand le flux en a un.
+ */
+export interface ISseSendOptions<K extends string = string> {
     /** Type de l'événement (champ `event:`) — absent : `message`. */
-    event?: string | undefined;
+    event?: K | undefined;
     /** Identifiant (champ `id:`) que le client renverra en `Last-Event-ID`. */
     id?: string | undefined;
 }
@@ -69,14 +74,32 @@ export declare const SSE_HEARTBEAT_MS = 15000;
 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;
+/**
+ * Charge d'un événement SSE : celle du canal nommé par `event`, ou — sans
+ * `event` (« un flux = un canal ») — l'une de celles de la carte. Carte non
+ * déclarée : `unknown`.
+ */
+export type SseEventData<Events extends EventsMap, K extends string> = [
+    K
+] extends [never] ? Events[EventNames<Events>] : Events[K];
 /**
  * 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.
+ *
+ * Typé par une carte d'événements (`ContractServerEmit<C>` : le MÊME contrat
+ * que la socket temps réel) : `event:` est un canal de la carte et la charge est
+ * celle du canal. Deux formes se lisent sur la même carte — **multiplexé**
+ * (`send(data, { event: canal })`, plusieurs canaux sur une connexion) ou **un
+ * flux = un canal** (carte d'un seul canal, `send(data)` sans `event`). Sans
+ * carte, le flux reste libre (porte MCP, flux hors contrat). Le type n'est pas
+ * une validation, et ne coûte rien à l'exécution.
+ *
+ * @typeParam Events - carte des événements du flux.
  */
-export declare class SseStream {
+export declare class SseStream<Events extends EventsMap = DefaultEventsMap> {
     #private;
     /** Le flux est-il fermé — par le serveur (`close()`) ou par le client parti ? */
     get closed(): boolean;
@@ -89,10 +112,12 @@ export declare class SseStream {
      * @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 TypeError quand `event` ou `id` contient une fin de ligne, ou
+     *   quand `data` est fait d'octets (`Uint8Array`, `Buffer`, `ArrayBuffer`) :
+     *   un flux SSE ne porte que du texte, les encoder soi-même (base64).
      * @throws RangeError quand l'événement dépasse `maxEventBytes`.
      */
-    send(data: unknown, options?: ISseSendOptions): Promise<void> | undefined;
+    send<K extends EventNames<Events> = never>(data: SseEventData<Events, K>, options?: ISseSendOptions<K>): Promise<void> | undefined;
     /**
      * Envoie un commentaire — ignoré par le client, utile pour garder une
      * connexion vivante ou marquer le flux à la lecture.
@@ -152,4 +177,4 @@ export declare function acceptsEventStream(accept: string | string[] | undefined
  * @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>;
+export declare function openSseStream<Events extends EventsMap = DefaultEventsMap>(context: HttpContext, options?: ISseStreamOptions): SseStream<Events> | Promise<SseStream<Events>>;

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

@@ -0,0 +1,53 @@
+import http from "node:http";
+import type http2 from "node:http2";
+/**
+ * Cycle de vie d'une réponse en flux — la brique commune au flux d'événements
+ * (`SseStream`) et au flux d'octets, NON exportée.
+ *
+ * Elle porte ce qu'un flux doit à la requête qui l'ouvre, quel que soit son
+ * format :
+ * - la PRISE de la réponse (`sended`), avant toute attente : le noyau ne peut
+ *   plus répondre par-dessus, et l'avertissement « réponse non envoyée » se tait ;
+ * - la session sauvée AVANT les en-têtes — ses cookies partent avec eux ;
+ * - la fermeture lue sur la RÉPONSE, écouteur posé de façon SYNCHRONE à
+ *   l'ouverture : un client parti pendant la sauvegarde de la session est vu ;
+ * - le délai d'inactivité de la requête désarmé, remplacé par les gardes du
+ *   flux : coupure d'un client qui ne lit plus (`stallTimeout`), durée de vie
+ *   maximale (`maxDuration`) ;
+ * - le plafond de connexions longues par IP (`wsMaxConnectionsPerIp`, le budget
+ *   des sockets WebSocket) et la fermeture à la révocation de l'identité ;
+ * - une fin unique, et des écouteurs de fin liés au contexte asynchrone.
+ *
+ * Le FORMAT (en-têtes, écriture, battement de cœur) appartient au flux qui la
+ * porte.
+ */
+/**
+ * Plus long délai qu'un minuteur sait tenir (2^31-1 ms). Au-delà, Node le
+ * ramène à 1 ms : un délai qui le dépasse ferait battre ou couper le flux
+ * mille fois par seconde.
+ */
+export declare const MAX_TIMER_MS = 2147483647;
+/**
+ * Qui a fermé le flux, quand ce n'est pas le client : le serveur (`close()` —
+ * fin demandée, durée de vie, révocation), ou la coupure d'un client qui ne lit
+ * plus. `null` : le client est parti, ou le flux est encore ouvert.
+ */
+export type StreamLifecycleCause = "server" | "stall" | null;
+/** Ce sur quoi on écrit : la réponse HTTP/1.1, ou le flux HTTP/2. */
+export type StreamTarget = http.ServerResponse | http2.ServerHttp2Stream;
+/** Gardes et identité d'un flux, options résolues. */
+export interface IStreamLifecycleSettings {
+    stallTimeout: number | false;
+    maxDuration: number | false;
+    /** Revalidateur de l'identité du flux — `null` pour un anonyme. */
+    revalidate: (() => Promise<boolean>) | null;
+    /** Identifiant de connexion de l'identité qui ouvre le flux — `null` anonyme. */
+    identifier: string | null;
+}
+/** Ce que l'ouverture reçoit de l'appelant. */
+export interface IOpenStreamLifecycle {
+    /** Préfixe des messages d'erreur (`SSE`, `Flux`). */
+    label: string;
+    stallTimeout: number | false;
+    maxDuration: number | false;
+}