@nodefony/http 10.0.0-beta.5 → 10.0.0-beta.7

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

@@ -10,9 +10,20 @@ import { UploadedFile } from "../../../service/upload/upload-service.js";
 import type { IParsedUploadFile, IUploadOptions } from "../../../interfaces/IUpload.js";
 import { Pci, Pdu, Message, Severity, Msgid } from "nodefony";
 import Session from "../../session/session.js";
+import HttpError from "../../errors/httpError.js";
 import { type ResolvedProxy } from "../forwarded.js";
 declare class BodyHandled {
 }
+/**
+ * Une réception multipart EN COURS, interruptible de l'extérieur : `fail` rompt
+ * la lecture comme le ferait un dépassement de limite (temporaires nettoyés).
+ * Posée dans `request.parser` le temps de la lecture seulement — l'allocation
+ * est réservée au multipart, déjà lourd.
+ */
+declare class MultipartReception {
+    readonly fail: (error: HttpError) => boolean;
+    constructor(fail: (error: HttpError) => boolean);
+}
 declare module "url" {
     interface URL {
         query: QS.ParsedQs;
@@ -31,7 +42,7 @@ declare module "http2" {
         session: Session;
     }
 }
-type ParserType = ParserXml | ParserQs | Parser | BodyHandled;
+type ParserType = ParserXml | ParserQs | Parser | BodyHandled | MultipartReception;
 declare class HttpRequest {
     #private;
     context: HttpContext;
@@ -88,6 +99,9 @@ declare class HttpRequest {
      * temporaire — lus par `@UploadedFile()` / `@UploadedFiles()`. Les champs
      * texte du même corps sont dans {@link body}.
      *
+     * Ces temporaires sont EFFACÉS à la fin de la requête : pour garder un
+     * fichier, l'action le déplace (`moveAsync`) avant de répondre.
+     *
      * Lecture seule : une requête sans upload rend un vide partagé et gelé,
      * aucune allocation.
      */
@@ -150,6 +164,16 @@ declare class HttpRequest {
      * @returns `undefined` quand tout est fait, sinon la promesse à attendre.
      */
     private endWithoutBody;
+    /**
+     * Lit le plafond du corps et les limites d'envoi tels que les voit CETTE
+     * requête : la configuration http, surchargée par le calque que la requête a
+     * pu poser avant la lecture du corps (`overlayConfig`, #494), puis par les
+     * bornes que la route déclare pour elle-même (option de route `upload`). La
+     * route est déjà résolue à ce moment : une route sans bornes propres
+     * n'alloue rien. Hors pipeline (aucun scope ouvert), la configuration du
+     * module telle quelle.
+     */
+    private readBodyLimits;
     /**
      * B1 — Pré-contrôle de taille du corps via l'en-tête `Content-Length` :
      * rejette en 413 (RFC 9110 §15.5.14 « Content Too Large ») AVANT toute lecture
@@ -159,13 +183,6 @@ declare class HttpRequest {
      *
      * @throws {HttpError} 413 si `Content-Length` dépasse `maxBodySize`.
      */
-    /**
-     * Lit le plafond du corps et les limites d'envoi tels que les voit CETTE
-     * requête : la configuration http, surchargée par le calque que la requête a
-     * pu poser avant la lecture du corps (`overlayConfig`, #494). Hors pipeline
-     * (aucun scope ouvert), la configuration du module telle quelle.
-     */
-    private readBodyLimits;
     private enforceBodyLimit;
     parseRequest(): Promise<ParserType | null>;
     /**
@@ -200,6 +217,19 @@ declare class HttpRequest {
      * déjà posés — à la moindre erreur ou dépassement de limite.
      */
     private streamMultipart;
+    /**
+     * Interrompt la réception du corps en cours : la promesse de `initialize()`
+     * rejette avec `error`, rendue par le chemin d'erreur habituel — comme un
+     * corps qui dépasse sa limite (413).
+     *
+     * Sert le délai de réception HTTP/2 (`requestTimeout`), que `node:http2` ne
+     * borne pas. Sans effet hors réception : corps déjà reçu, lu en flux par
+     * l'action (`bodyStream`), ou méthode sans corps.
+     *
+     * @param error - la cause rendue au client (408 au délai dépassé)
+     * @returns vrai si une réception en cours a été interrompue
+     */
+    abortBody(error: HttpError): boolean;
     /**
      * Accumule un champ texte multipart. `foo[]` (ou répétition de `foo`) →
      * tableau ; sinon valeur scalaire. (Anciennement délégué à formidable.)
@@ -220,12 +250,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,35 @@
-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";
+/**
+ * Plafond, en octets, d'un corps de requête HTTP/1.1 non lu que le serveur
+ * accepte de vider pour garder la connexion réutilisable — 256 Kio, le geste du
+ * serveur HTTP de Go que Connect reprend (ADR-0026, D5). Au-delà, la réponse
+ * ferme la connexion.
+ */
+export declare const UNREAD_BODY_DRAIN_LIMIT: number;
+/**
+ * Silence, en millisecondes, au bout duquel une connexion HTTP/1.1 fermée sur
+ * un corps non lu est détruite — 5 s, le `lingering_timeout` par défaut de
+ * nginx. La durée TOTALE reste bornée par le délai de réception de Node
+ * (`requestTimeout`), qui court tant que le corps n'est pas fini.
+ */
+export declare const UNREAD_BODY_LINGER_MS = 5000;
+/**
+ * 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 +42,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 +69,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 +83,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 +96,110 @@ 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;
+    /**
+     * Range les en-têtes de corrélation du contexte — `X-Request-Id` et le
+     * `traceparent` W3C — que toute réponse renvoie, quel qu'en soit l'émetteur.
+     * Validés par Node à la remise, comme le reste de la réserve.
+     */
+    protected putCorrelationHeaders(): void;
+    /**
+     * 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,
+     * adaptateur RPC. La réserve se vide ; ce qui se pose ensuite y retourne, et
+     * Node fusionne les deux au `writeHead` (l'émetteur l'emporte, nom par nom).
+     *
+     * @param contentType - type de la réponse que l'émetteur écrira, quand il
+     *   est connu d'avance (adaptateur RPC). Omis : il se lit à l'extension du
+     *   chemin, comme le serveur statique le fera.
+     */
+    commitHeaders(contentType?: string): 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, posée une fois avec
+     * des attributs constants — toutes les réponses interceptées partagent donc
+     * la même forme — et désarmée en lui RÉAFFECTANT la méthode native, jamais
+     * en la supprimant : un `delete` fait basculer la réponse Node en mode
+     * dictionnaire (constaté par `%HasFastProperties` sur Node 26, 200 réponses
+     * sur 200), et chaque accès suivant de `node:http` le paie — mesuré in situ
+     * sur un 404 : `writeHead` +1,1 µs, `end` +4,3 µs.
+     */
+    commitBeforeNativeWrite(): void;
+    /**
+     * Retire l'interception posée par {@link commitBeforeNativeWrite} : la
+     * propriété propre reçoit la méthode native — la forme de l'objet ne change
+     * pas, la réponse reste en mode rapide pour V8.
+     */
+    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 +222,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 +265,36 @@ 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>;
+    /**
+     * Règle le sort d'un corps de requête resté NON LU au moment de répondre —
+     * route inconnue (404, 405), refus avant l'action, 408, 413. À appeler AVANT
+     * l'écriture des en-têtes ; sans effet si le corps est entièrement reçu.
+     *
+     * HTTP/1.1 : Node vide lui-même un corps non consommé une fois la réponse
+     * écrite, pour réutiliser la connexion — sans borne. On ne le laisse faire
+     * que pour un corps DÉCLARÉ d'au plus {@link UNREAD_BODY_DRAIN_LIMIT}
+     * octets ; au-delà, ou sans longueur déclarée (`transfer-encoding`), la
+     * réponse part avec `connection: close` (RFC 9112 §9.6) et la connexion
+     * n'est pas réutilisée — fermée par étapes ({@link lingerBeforeClose}),
+     * pour que le client qui écrit encore lise la réponse. La décision se prend
+     * sur la longueur ANNONCÉE, sans attendre un octet : la réponse n'est jamais
+     * retardée par le corps.
+     *
+     * HTTP/2 surcharge cette méthode (`Http2Response`) : fermeture du flux en
+     * `NO_ERROR` une fois la réponse écrite. Une seule entrée pour les deux
+     * protocoles, partagée par tout refus qui laisse un corps non lu (ADR-0026,
+     * D5).
+     */
+    closeUnfinishedRequest(): void;
+    /**
+     * 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,27 +57,49 @@ 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;
 }
 /** 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. */
+/** Délai de blocage d'écriture par défaut, en ms — celui de tout flux. */
 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,106 @@
+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;
+/**
+ * Délai de blocage par défaut d'un flux, en ms : un client qui ne lit plus
+ * depuis ce délai est coupé. Valeur commune aux flux d'événements, d'octets et
+ * aux flux RPC.
+ */
+export declare const STREAM_STALL_TIMEOUT_MS = 30000;
+/**
+ * Période du balayage de blocage ({@link StallSweep}) : la moitié du délai de
+ * blocage. Un client bloqué est coupé entre `stallTimeout` et
+ * `stallTimeout + période` après la première contre-pression vue — jamais
+ * avant le délai réglé.
+ */
+export declare const STALL_SWEEP_PERIOD_MS: number;
+/**
+ * Attente maximale, à l'arrêt du serveur, des flux longs qu'on vient de
+ * terminer (`HttpKernel.shutdownStreams`), avant le drain des connexions.
+ *
+ * Un flux qui écoute son signal se ferme en quelques millisecondes : l'attente
+ * finit avec lui. Elle ne dure jusqu'à son terme que pour un gestionnaire qui
+ * n'écoute rien — et ce temps s'AJOUTE au drain (`shutdownTimeout`), d'où une
+ * borne courte, celle de l'annonce du GOAWAY.
+ */
+export declare const SHUTDOWN_STREAMS_WAIT_MS = 1000;
+/**
+ * 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;
+    /**
+     * Les écritures appartiennent à un tiers (adaptateur RPC) : la brique ne les
+     * voit pas. Le blocage s'observe alors par le balayage du noyau
+     * ({@link StallSweep}), et la fermeture par le serveur détruit le transport
+     * au lieu de terminer la réponse — jamais un second écrivain.
+     */
+    foreignWriter: boolean;
+    /**
+     * Le flux n'a pas de fin à lui (SSE, flux RPC, sortie d'un processus) : à
+     * l'arrêt du serveur, le noyau le termine AVANT le drain des connexions
+     * ({@link StreamLifecycle.shutdown}), au lieu de le laisser détruire sans un
+     * mot à `shutdownTimeout`. `false` pour une source FINIE (une archive) : elle
+     * a le drain pour finir, comme toute réponse en vol.
+     */
+    endsAtShutdown: boolean;
+}
+/** 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;
+    /**
+     * Un tiers tient les écritures (adaptateur RPC) — cf
+     * {@link IStreamLifecycleSettings.foreignWriter}. Défaut `false`.
+     */
+    foreignWriter?: boolean;
+    /**
+     * Terminé par le noyau à l'arrêt du serveur — cf
+     * {@link IStreamLifecycleSettings.endsAtShutdown}. Défaut `true`.
+     */
+    endsAtShutdown?: boolean;
+}
+/** Ce que le registre de l'arrêt retient d'un flux : de quoi le terminer. */
+export interface IShutdownStream {
+    /** Le serveur s'arrête : le flux prend fin (cf {@link StreamLifecycle.shutdown}). */
+    shutdown(): unknown;
+}

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

@@ -2,22 +2,36 @@ import HttpRequest from "./Request.js";
 import Http2Request from "../http2/Request.js";
 import QS from "qs";
 import xml2js from "xml2js";
+import HttpError from "../../errors/httpError.js";
 declare class Parser {
     request: HttpRequest | Http2Request;
     chunks: Buffer[];
     private received;
     private aborted;
-    private overflow;
-    private onOverflow;
+    private failure;
+    private onFailure;
     constructor(request: HttpRequest | Http2Request);
     write(buffer: Buffer): Buffer;
+    /**
+     * Interrompt la réception du corps : `parse()` rejette avec `error`, que
+     * l'interruption survienne avant ou pendant l'attente de la fin du flux.
+     *
+     * La RAM déjà bufferisée est libérée et la lecture du flux suspendue ; la
+     * réponse d'erreur peut encore partir. Sans effet si le corps est déjà
+     * entièrement reçu, ou déjà interrompu.
+     *
+     * @param error - la cause rendue au client (413 dépassement, 408 délai)
+     * @returns vrai si la réception a été interrompue
+     */
+    fail(error: HttpError): boolean;
     /**
      * Résout quand le flux requête est **entièrement reçu** (`end`). No-op si déjà
      * terminé (corps vide / déjà drainé) → pas de hang d'un `once("end")` tardif.
      * Indispensable avant de concaténer les chunks pour un corps à décoder
      * (JSON…) : sinon on lit un buffer encore incomplet. (formidable drainait via
      * son `await form.parse()` ; ses remplaçants doivent drainer explicitement.)
-     * Rejette en 413 si le corps dépasse `maxBodySize` (avant ou pendant l'attente).
+     * Rejette avec la cause de {@link Parser.fail} (413 dépassement de
+     * `maxBodySize`, 408 délai de réception), avant ou pendant l'attente.
      */
     protected ended(): Promise<void>;
     parse(): Promise<this>;

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/http/webResponse.d.ts

@@ -0,0 +1,31 @@
+import type http from "node:http";
+import type { ByteStreamSource } from "./ByteStream.js";
+/** Ce qu'une `Response` Web devient pour le flux d'octets de Nodefony. */
+export interface IWebResponseParts {
+    /** Statut de la réponse. */
+    status: number;
+    /** En-têtes à poser, filtrés (voir {@link webResponseParts}). */
+    headers: http.OutgoingHttpHeaders;
+    /** Corps, Web ou vide — jamais `null`. */
+    source: ByteStreamSource;
+}
+/**
+ * Traduit une `Response` Web standard en statut, en-têtes et corps pour le flux
+ * d'octets — sans la lire : le corps reste un flux.
+ *
+ * Deux origines, deux règles, que `response.type` distingue :
+ * - **construite par l'application** (`new Response(…)`, `Response.json(…)`,
+ *   `Response.redirect(…)` — `type === "default"`) : ses en-têtes sont les
+ *   siens, cookies compris (`getSetCookie()`), et partent tels quels ;
+ * - **relayée** (issue de `fetch` — `"basic"`, `"cors"`…) : `content-encoding`,
+ *   `content-length` et `set-cookie` de l'amont sont écartés (voir
+ *   `UPSTREAM_ONLY`).
+ *
+ * Les en-têtes de connexion (RFC 9110 §7.6.1 — la liste du relais,
+ * `HOP_BY_HOP`) ne partent jamais : ils décrivent un saut, et HTTP/2 les
+ * refuse.
+ *
+ * @param response - une `Response` dont le corps n'a pas été consommé.
+ * @returns statut, en-têtes filtrés et corps.
+ */
+export declare function webResponseParts(response: Response): IWebResponseParts;