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

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

@@ -0,0 +1,168 @@
+import http from "node:http";
+import type http2 from "node:http2";
+import type { Duplex } from "node:stream";
+import type { IProxyMount } from "../../interfaces/IReverseProxy.js";
+/** Requête entrante relayable : HTTP/1.1 ou HTTP/2 (API de compatibilité). */
+export type ProxiedRequest = http.IncomingMessage | http2.Http2ServerRequest;
+/** Réponse vers le client : HTTP/1.1 ou HTTP/2 (API de compatibilité). */
+export type ProxiedResponse = http.ServerResponse | http2.Http2ServerResponse;
+/**
+ * Ce que le proxy sait du client, et qu'il annonce à l'amont
+ * (`X-Forwarded-*`, `Via`).
+ */
+export interface IForwardedFrom {
+    /** Adresse du pair TCP immédiat — ajoutée à la chaîne `X-Forwarded-For`. */
+    remoteAddress: string | undefined;
+    /** Scheme par lequel le pair est arrivé (`http` | `https`). */
+    scheme: string;
+    /** Autorité demandée (`Host` ou `:authority`). */
+    host: string | undefined;
+    /**
+     * Le pair est-il un relais de confiance (`trustProxy`) ? Seul un tel pair
+     * peut faire passer des `Forwarded`/`X-Forwarded-*`/`X-Real-IP` : venus
+     * d'ailleurs, ils sont forgeables (RFC 7239 §8.1) et sont écartés.
+     */
+    trustedPeer: boolean;
+    /** Version du message reçu, pour `Via` (`"1.1"`, `"2.0"`). */
+    httpVersion: string;
+}
+/** Réglages du relais, fixés par le service (identiques pour tous les montages). */
+export interface IRelaySettings {
+    /** Pseudonyme de CE processus dans `Via` (RFC 9110 §7.6.3) — base de la garde de boucle. */
+    pseudonym: string;
+    /** Délai d'établissement de la connexion amont (ms). Dépassé : 504. */
+    connectTimeoutMs: number;
+    /**
+     * Pool de connexions du montage (keep-alive borné) ; `false` = connexion à
+     * usage unique (arrêt engagé : plus de pool à créer).
+     */
+    agent: http.Agent | false | undefined;
+}
+/**
+ * Sauts `Via` au-delà desquels un message est tenu pour une boucle. Notre
+ * pseudonyme ne repère une boucle qu'au RETOUR dans ce processus : derrière un
+ * répartiteur qui tourne sur N instances, cela peut prendre N+1 sauts, chacun
+ * tenant une connexion. Une chaîne légitime (CDN, répartiteur, ingress) en
+ * compte rarement plus de cinq.
+ */
+export declare const MAX_VIA_HOPS = 10;
+/**
+ * Le message est-il déjà passé par CE processus ? Un `Via` qui porte notre
+ * pseudonyme signe une boucle (RFC 9110 §7.6 : un proxy ne se renvoie pas un
+ * message sans s'en protéger).
+ *
+ * @param via - en-tête `Via` reçu
+ * @param pseudonym - pseudonyme de ce processus
+ */
+export declare function viaLoops(via: string | string[] | undefined, pseudonym: string): boolean;
+/**
+ * Cadrage du corps transmis à l'amont (RFC 9112 §6). `unsupported` : un
+ * codage de transfert autre que `chunked` seul — le proxy ne sait pas le
+ * transmettre fidèlement.
+ */
+export type BodyFraming = "none" | "length" | "chunked" | "unsupported";
+/**
+ * Cadrage du corps reçu — décidé UNE fois, pour que l'amont lise exactement
+ * les octets que le proxy lui envoie (RFC 9112 §6.3). Un `Transfer-Encoding`
+ * l'emporte sur un `Content-Length` (que l'on retire alors) ; en HTTP/2, un
+ * flux sans fin à la tête porte un corps même sans longueur annoncée.
+ *
+ * @param req - requête reçue
+ * @returns le cadrage à appliquer vers l'amont
+ */
+export declare function bodyFramingOf(req: ProxiedRequest): BodyFraming;
+/**
+ * En-têtes de la requête à transmettre à l'amont.
+ *
+ * - écartés : pseudo-en-têtes HTTP/2, en-têtes de connexion et ceux que nomme
+ *   `Connection`, `Expect` (le serveur a déjà répondu `100`), en-têtes retirés
+ *   par le montage, chaîne de relais venue d'un pair NON fiable ;
+ * - `Host` réécrit sur la cible (sauf `preserveHost`) ;
+ * - `X-Forwarded-For` prolongé (pair fiable) ou recommencé ;
+ *   `X-Forwarded-Proto`/`-Host` hérités d'un pair fiable, posés sinon ;
+ *   `X-Forwarded-Prefix` quand le préfixe est retiré — à la suite de celui
+ *   d'un pair fiable ; `Forwarded` d'un pair fiable prolongé de ce saut ;
+ * - `Via` prolongé de ce saut ;
+ * - cadrage du corps rendu cohérent ({@link bodyFramingOf}).
+ *
+ * @returns un objet neuf, prêt pour `http.request`
+ */
+export declare function requestHeadersFor(headers: http.IncomingHttpHeaders, mount: IProxyMount, target: URL, from: IForwardedFrom, pseudonym: string, framing: BodyFraming): http.OutgoingHttpHeaders;
+/**
+ * Ramène sous le préfixe un `Location` émis par un amont qui ignore son
+ * montage (`stripPrefix`) — l'équivalent de `proxy_redirect default` de
+ * nginx. Un chemin absolu (`/login`) et une URL sur l'origine de l'amont sont
+ * réécrits ; toute autre URL (un tiers) part intacte.
+ *
+ * @returns la valeur réécrite, ou celle reçue
+ */
+export declare function rewriteLocation(location: string, mount: IProxyMount, target: URL): string;
+/**
+ * En-têtes de la réponse de l'amont à renvoyer au client : en-têtes de
+ * connexion écartés — y compris ceux que nomme `Connection` —, `Via`
+ * prolongé, `Location` ramené sous le préfixe (`stripPrefix`) ; le reste
+ * intact (un `set-cookie` multiple reste un tableau).
+ *
+ * @returns un objet neuf, valable en HTTP/1.1 comme en HTTP/2
+ */
+export declare function responseHeadersFor(headers: http.IncomingHttpHeaders, mount: IProxyMount, target: URL, hop: string): http.OutgoingHttpHeaders;
+/**
+ * Chemin transmis à l'amont : tel quel, ou sans le préfixe (`stripPrefix`).
+ *
+ * @param url - cible de la requête (chemin + requête), qui commence par le préfixe
+ * @param mount - montage qui relaie
+ * @returns le chemin, toujours avec un `/` en tête
+ */
+export declare function upstreamPath(url: string, mount: IProxyMount): string;
+/**
+ * Relaie une requête HTTP vers l'amont et renvoie sa réponse au client.
+ *
+ * Le corps est transmis avec un cadrage cohérent ({@link bodyFramingOf}). Un
+ * message qui porte déjà notre `Via` rend 508 sans contacter l'amont. Un
+ * client parti coupe l'échange amont ; un amont injoignable rend 502 ; une
+ * connexion non établie à temps ou un amont muet rendent 504 — à condition
+ * que rien n'ait encore été envoyé, sinon la réponse est interrompue (un
+ * statut ne se rattrape pas). Un amont coupé en plein corps interrompt la
+ * réponse au client au lieu de la laisser pendre.
+ *
+ * @returns une promesse résolue à la fermeture de la réponse — jamais rejetée
+ */
+export declare function forwardRequest(req: ProxiedRequest, res: ProxiedResponse, mount: IProxyMount, target: URL, from: IForwardedFrom, relay: IRelaySettings): Promise<void>;
+/**
+ * Sérialise une tête de réponse HTTP/1.1 depuis des en-têtes BRUTS (paires
+ * nom/valeur), sans réordonner ni fusionner, en écartant les noms donnés —
+ * une réponse `101` doit rendre au client exactement ce que l'amont a négocié.
+ *
+ * @param status - ligne de statut, sans CRLF
+ * @param rawHeaders - `IncomingMessage.rawHeaders`
+ * @param skip - noms à écarter (minuscules)
+ * @param extra - lignes ajoutées à la fin (`Nom: valeur`)
+ * @returns la tête complète, CRLF final compris
+ */
+export declare function rawHead(status: string, rawHeaders: readonly string[], skip?: ReadonlySet<string> | null, extra?: readonly string[]): string;
+/**
+ * Réponse brute minimale sur un socket d'upgrade, puis fermeture.
+ *
+ * Les en-têtes passent par la validation de `node:http` : un nom ou une valeur
+ * invalide — un saut de ligne surtout, qui forgerait un en-tête de plus — est
+ * OMIS, jamais écrit. `Connection` et `Content-Length` sont posés ici et ne se
+ * remplacent pas.
+ *
+ * @param socket - socket du client, encore en attente de sa réponse
+ * @param status - statut HTTP du refus
+ * @param reason - phrase de raison
+ * @param headers - en-têtes du refus (`WWW-Authenticate`, `Retry-After`…)
+ */
+export declare function refuseUpgrade(socket: Duplex, status: number, reason: string, headers?: Readonly<Record<string, string | number>> | null): void;
+/**
+ * Relaie un upgrade WebSocket DÉJÀ validé (méthode, `Upgrade`, clé, version,
+ * `Origin` — cf `ReverseProxy.handleUpgrade`) : rejoue le handshake vers
+ * l'amont, renvoie sa réponse `101` au client puis raccorde les deux sockets
+ * octet pour octet. Un refus de l'amont (`400`, `403`…) est rendu avec un
+ * cadrage refait (fin de corps = fermeture) ; un amont injoignable rend `502`,
+ * une connexion non établie à temps — ou un amont qui accepte puis se tait
+ * au-delà de `timeoutMs` — `504`, une boucle `508`. Le délai d'inactivité
+ * cesse au `101` : un tunnel établi peut rester muet. Une erreur d'un côté
+ * détruit l'autre.
+ */
+export declare function forwardUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer, mount: IProxyMount, target: URL, from: IForwardedFrom, relay: IRelaySettings): void;

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

@@ -42,6 +42,12 @@ export interface ProxyIntrospection {
     httpPort: number;
     /** Port HTTPS/2 du backend (re-encrypt). */
     httpsPort: number;
+    /**
+     * Port h2c du backend (`servers.h2c`), ou `null` s'il n'est pas activé. Le
+     * générateur haproxy y envoie le trafic en HTTP/2 (`proto h2`) ; nginx, qui
+     * ne parle pas HTTP/2 à ses amonts, l'ignore.
+     */
+    h2cPort?: number | null;
     /** Dossiers statiques servis à la racine `/` (ordre = priorité). */
     staticRoots: string[];
     /** Montages statiques préfixés (servis tels quels). */
@@ -71,6 +77,16 @@ export interface ProxyIntrospection {
      * saines.
      */
     keepaliveIntervalMs: number;
+    /**
+     * Chemin de la sonde de disponibilité (`health.readinessPath`), ou `null`
+     * si les sondes sont désactivées.
+     *
+     * HAProxy la sonde (`option httpchk`) au lieu d'un simple contrôle de
+     * connexion : un exemplaire qui draine garde son port ouvert, mais `/readyz`
+     * répond déjà `503` — c'est ce qui le retire du répartiteur AVANT qu'il
+     * cesse d'accepter. Un contrôle TCP le garderait jusqu'à la fermeture du port.
+     */
+    readinessPath?: string | null;
     /**
      * Terminaison TLS au frontal, ou `null` pour n'écouter qu'en clair.
      *

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

@@ -0,0 +1,88 @@
+/**
+ * Règles d'un montage du proxy inverse — UNIQUE source, lue par le schéma de
+ * configuration (`proxy.mounts`) ET par `ReverseProxy.mount()` : un montage
+ * écrit dans la config et un montage posé par un module obéissent aux mêmes
+ * refus, avec les mêmes mots.
+ *
+ * Pur : n'importe que le cœur, importable depuis `config/config.ts` sans
+ * cycle.
+ */
+/**
+ * Préfixes que le framework se réserve : un montage n'y est JAMAIS accepté.
+ * `/nodefony/` porte la console d'administration et les API de Studio — les
+ * relayer ailleurs détournerait une surface protégée par le pare-feu.
+ */
+export declare const RESERVED_PROXY_PREFIXES: readonly string[];
+/**
+ * Préfixes réservés aux montages POSÉS PAR UN MODULE : la configuration ne
+ * peut pas les prendre. `/_vite/` appartient à `@nodefony/frontend`, qui y
+ * relaie ses serveurs Vite de développement.
+ */
+export declare const MODULE_PROXY_PREFIXES: readonly string[];
+/**
+ * Normalise un préfixe d'URL : `/` en tête et en fin, sans `/` doublé. Règle
+ * UNIQUE des montages statiques et du proxy inverse — deux écritures du même
+ * préfixe doivent désigner la même entrée.
+ *
+ * @param prefix - préfixe tel qu'écrit (`"svc"`, `"/svc"`, `"/svc/"`)
+ * @returns le préfixe normalisé (`"/svc/"`)
+ */
+export declare function normalizePrefix(prefix: string): string;
+/**
+ * Analyse une origine d'amont. Seule une origine NUE est acceptée : un chemin,
+ * une requête, un fragment ou des identifiants dans la cible déplaceraient en
+ * silence toutes les URL relayées, ou feraient voyager un secret dans la
+ * configuration.
+ *
+ * @param origin - `scheme://hôte[:port]`
+ * @returns l'URL analysée, ou `null` si ce n'est pas une origine http(s) nue
+ */
+export declare function parseProxyOrigin(origin: string): URL | null;
+/** Ce qu'une règle de montage examine — la forme commune config / code. */
+export interface IProxyMountShape {
+    target: unknown;
+    methods?: readonly string[] | undefined;
+    stripHeaders?: readonly string[] | undefined;
+    timeoutMs?: number | undefined;
+    secure?: boolean | undefined;
+}
+/** Un refus, nommé : le champ fautif et pourquoi. */
+export interface IProxyMountProblem {
+    field: "prefix" | "target" | "methods" | "stripHeaders" | "timeoutMs" | "secure";
+    message: string;
+}
+/**
+ * Examine un montage. Rend TOUS les refus, pas le premier : une configuration
+ * se corrige en une passe.
+ *
+ * @param prefix - préfixe tel qu'écrit
+ * @param mount - réglages du montage
+ * @param source - `"config"` (déclaré dans `proxy.mounts`) ou `"module"`
+ *   (posé par un module) — seuls les préfixes réservés aux modules diffèrent
+ * @returns la liste des refus, vide si le montage est sain
+ */
+export declare function proxyMountProblems(prefix: string, mount: IProxyMountShape, source: "config" | "module"): IProxyMountProblem[];
+/**
+ * Le chemin d'une requête relayée est-il ambigu ? Un chemin que le proxy et
+ * l'amont pourraient lire différemment — segment `.`/`..`, barre inverse,
+ * octet nul, ou leur forme encodée (`%2e`, `%2f`, `%5c`, `%00`, `%25`) — est
+ * REFUSÉ (400), jamais normalisé en silence : c'est le défaut de Traefik, et
+ * la parade aux contournements de préfixe (`/svc/..%2fadmin`).
+ *
+ * @param url - cible brute de la requête (chemin + requête éventuelle)
+ * @returns `true` si le chemin doit être refusé
+ */
+export declare function isAmbiguousPath(url: string): boolean;
+/**
+ * Un upgrade est-il un handshake WebSocket conforme (RFC 6455 §4.2.1) ? Seul
+ * un tel handshake est relayé : un `Upgrade` quelconque (`h2c`…) raccordé
+ * octet pour octet ouvrirait un tunnel que rien n'inspecte.
+ *
+ * Appelé à CHAQUE handshake (proxy inverse et routes de Nodefony) : aucune
+ * allocation — des expressions testées, jamais de découpe de chaîne.
+ *
+ * @param method - méthode de la requête
+ * @param headers - en-têtes reçus
+ * @returns la raison du refus, ou `null` si le handshake est conforme
+ */
+export declare function websocketHandshakeProblem(method: string | undefined, headers: Record<string, string | string[] | undefined>): string | null;

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

@@ -0,0 +1,37 @@
+import type { Http2SecureServer, Http2Server, ServerOptions } from "node:http2";
+import type { IHttpConfig } from "../../config/config.js";
+/**
+ * Limites anti-DoS d'un serveur HTTP/2, lues dans la section `http2` du module :
+ * `maxSessionMemory` (amplification mémoire) et `maxConcurrentStreams` dans les
+ * SETTINGS (CVE-2023-44487, Rapid Reset). Règle UNIQUE des serveurs HTTP/2 — TLS
+ * (5152) comme h2c — : une limite oubliée sur l'un d'eux en ferait la porte de
+ * l'attaque.
+ *
+ * Une limite absente garde le défaut de Node (aucune régression).
+ *
+ * @param limits - `module.options.http2`.
+ * @returns les options à fusionner dans celles de `createServer`/`createSecureServer`.
+ */
+export declare function http2ServerLimits(limits: Partial<IHttpConfig["http2"]> | undefined): Pick<ServerOptions, "maxSessionMemory" | "settings">;
+/**
+ * Borne l'inactivité des sessions d'un serveur HTTP/2 — TLS (5152) comme h2c —
+ * et contourne un défaut de Node qui garde chaque session fermée en vie jusqu'à
+ * l'échéance de ce délai.
+ *
+ * Le défaut (Node 24, 26) : `closeSession` (`internal/http2/core`) marque la
+ * session détruite PUIS appelle `session.setTimeout(0)` ; or `setStreamTimeout`
+ * sort aussitôt sur un objet détruit. Le minuteur n'est jamais désarmé et retient
+ * la session (~2,4 Ko) pendant `timeoutMs` : sous un flux de connexions neuves,
+ * connexions/s × délai × 2,4 Ko. Signalé à Node : https://github.com/nodejs/node/issues/66885
+ *
+ * Le contournement : désarmer à la réception du GOAWAY, AVANT la destruction —
+ * c'est ainsi que ferment un proxy et un client Node, même par `destroy()`. Rien
+ * n'est retiré à la protection : Node n'agit déjà plus à l'échéance sur une
+ * session fermée (`sessionOnTimeout` sort sur `closed`). Une coupure TCP sans
+ * GOAWAY garde la rétention, bornée au délai.
+ *
+ * @param server - le serveur HTTP/2.
+ * @param timeoutMs - délai d'inactivité ; 0 ou absent le laisse désactivé.
+ * @param onTimeout - appelé à l'échéance (événement `timeout` du serveur).
+ */
+export declare function setHttp2SessionTimeout(server: Http2Server | Http2SecureServer, timeoutMs: number | undefined, onTimeout: () => void): void;

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

@@ -10,6 +10,15 @@ import type { ServersConfig } from "nodefony";
  * @returns la section typée, ou `undefined` si elle est absente ou n'est pas un objet.
  */
 export declare function asServersConfig(servers: unknown): ServersConfig | undefined;
+/**
+ * Le serveur h2c démarre-t-il ? Seul un `enabled: true` EXPLICITE l'allume : la
+ * section existe toujours (défauts), un port seul ne vaut pas activation.
+ *
+ * @param entry - `servers.h2c`.
+ */
+export declare function isH2cEnabled(entry: {
+    enabled?: boolean | undefined;
+} | undefined): boolean;
 /**
  * Port DEMANDÉ pour un serveur (`servers.<type>.port`), ou `undefined` si le
  * serveur est désactivé, absent, ou sans port numérique.
@@ -17,4 +26,4 @@ export declare function asServersConfig(servers: unknown): ServersConfig | undef
  * @param servers - section `servers` déjà rétrécie ({@link asServersConfig}).
  * @param type - le serveur visé.
  */
-export declare function configuredServerPort(servers: ServersConfig | undefined, type: "http" | "https"): number | undefined;
+export declare function configuredServerPort(servers: ServersConfig | undefined, type: "http" | "https" | "h2c"): number | undefined;

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

@@ -3,12 +3,19 @@ import { resolvePortPolicy } from "nodefony";
 import type { PortPolicy } from "nodefony";
 export { resolvePortPolicy };
 export type { PortPolicy };
-/** Serveur écoutable (surface minimale commune `http`/`https`/`http2`). */
+/**
+ * Serveur écoutable (surface minimale commune `http`/`https`/`http2`).
+ *
+ * Les écouteurs sont typés événement par événement : c'est la forme que les
+ * surcharges de Node acceptent telle quelle, sans conversion chez l'appelant.
+ */
 export interface Listenable {
     listen(port: number, host?: string): unknown;
     address(): AddressInfo | string | null;
-    once(event: string, listener: (...args: never[]) => void): unknown;
-    removeListener(event: string, listener: (...args: never[]) => void): unknown;
+    once(event: "error", listener: (error: NodeJS.ErrnoException) => void): unknown;
+    once(event: "listening", listener: () => void): unknown;
+    removeListener(event: "error", listener: (error: NodeJS.ErrnoException) => void): unknown;
+    removeListener(event: "listening", listener: () => void): unknown;
 }
 /** Nombre de ports essayés après le désiré, en `auto`. */
 export declare const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
@@ -34,18 +41,35 @@ export interface ServersPortConfig {
     https?: {
         port?: number | undefined;
     } | false;
+    h2c?: {
+        enabled?: boolean | undefined;
+        port?: number | undefined;
+    };
     portPolicy?: PortPolicy;
     portRetryAttempts?: number;
 }
+/** Serveur dont `buildBindPlan` compose le plan. */
+export type BoundServer = "http" | "https" | "h2c";
+/**
+ * Serveur actif qui convoite le MÊME port que h2c, ou `null`.
+ *
+ * Un port partagé avec h2c n'est pas un conflit à contourner : sur ce port, le
+ * client HTTP/1.1 et le proxy h2c se marchent dessus, et le repli `auto` ferait
+ * glisser l'un des deux là où personne ne l'attend. Le boot le refuse.
+ *
+ * @param servers - `kernel.options.servers`.
+ * @returns `"http"` ou `"https"` en conflit, sinon `null` (h2c inactif, port 0).
+ */
+export declare function h2cPortConflict(servers: ServersPortConfig | undefined): "http" | "https" | null;
 /**
  * Compose le plan de bind d'un serveur depuis la config du kernel — source UNIQUE
- * (les deux serveurs l'appellent ; la politique n'est décidée qu'ici).
+ * (les serveurs l'appellent ; la politique n'est décidée qu'ici).
  *
  * @param which - le serveur qu'on borne.
  * @param servers - `kernel.options.servers`.
  * @param environment - `kernel.environment` (arbitre le défaut de la politique).
  */
-export declare function buildBindPlan(which: "http" | "https", servers: ServersPortConfig | undefined, environment: string | undefined): BindPlan;
+export declare function buildBindPlan(which: BoundServer, servers: ServersPortConfig | undefined, environment: string | undefined): BindPlan;
 /**
  * Sonde « un serveur répond-il déjà ici ? ».
  *

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

@@ -0,0 +1,69 @@
+import { type IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import type { WebSocket, WebSocketServer } from "ws";
+/** Serveur qui émet `upgrade` : HTTP/1.1, HTTPS ou HTTP/2 sécurisé (`allowHTTP1`). */
+interface IUpgradeEmitter {
+    on(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+    removeListener(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+}
+/** Ce que le répartiteur lit du proxy inverse (cf `ReverseProxy`). */
+interface IUpgradeRelay {
+    readonly mounts: readonly unknown[] | null;
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+}
+/**
+ * Le verdict d'un upgrade, rendu par le noyau APRÈS sa décision — qui peut
+ * attendre (session, pare-feu, garde de l'action). Un seul verdict compte : le
+ * premier appel l'emporte, les suivants sont ignorés.
+ */
+export interface IUpgradeAdmission {
+    /**
+     * Termine le handshake (`101`) et rend la socket ouverte.
+     *
+     * @returns la socket DIRECTEMENT quand `ws` la rend tout de suite (le cas
+     *   nominal : aucune promesse, aucune micro-tâche), sinon sa promesse ;
+     *   `null` si le client est parti pendant la décision (ou si `ws` a rejeté
+     *   le handshake) — il n'y a alors rien à servir
+     */
+    accept(): WebSocket | null | Promise<WebSocket | null>;
+    /**
+     * Refuse par un statut HTTP, AVANT le `101` (RFC 6455 §4.2.2).
+     *
+     * @param status - statut du refus (`401`, `403`, `429`…)
+     * @param headers - en-têtes du refus (`WWW-Authenticate`, `Retry-After`)
+     */
+    refuse(status: number, headers?: Readonly<Record<string, string | number>> | null): void;
+}
+/** Ce qui décide d'un upgrade : reçoit la requête et rend son verdict, plus tard s'il le faut. */
+export type UpgradeAdmit = (req: IncomingMessage, admission: IUpgradeAdmission) => void;
+/**
+ * Pose l'UNIQUE écouteur `upgrade` d'un serveur : le proxy inverse d'abord,
+ * puis le serveur WebSocket de Nodefony.
+ *
+ * Pourquoi un seul écouteur : `ws` attaché par son option `server` prend TOUS
+ * les upgrades et répond `400` à ceux qu'il ne reconnaît pas. Un second
+ * écouteur, même posé avant, ne l'empêcherait pas de répondre sur un socket
+ * déjà relayé. Le serveur `ws` est donc créé en `noServer`, et c'est ici que
+ * l'upgrade lui est confié — avec ses propres contrôles intacts (`path`,
+ * `verifyClient`, `maxPayload`…), que `handleUpgrade` applique.
+ *
+ * Entre les deux, `refusal` tranche ce qui doit être refusé AVANT le `101`
+ * (RFC 6455 §4.2.2) : un chemin sans route WebSocket reçoit un statut HTTP,
+ * jamais une ouverture suivie d'une fermeture. Puis la FORME du handshake est
+ * contrôlée (`websocketHandshakeProblem`, la règle du proxy inverse) : un
+ * handshake malformé reçoit `400` sans jamais atteindre le noyau. Enfin
+ * `admit` décide — pare-feu, garde de l'action — et seul son verdict ouvre.
+ *
+ * Sans montage, le coût par connexion est une lecture de champ.
+ *
+ * @param server - serveur HTTP(S) qui reçoit les upgrades
+ * @param wss - serveur WebSocket de Nodefony (`noServer: true`)
+ * @param relay - proxy inverse, lu à chaque upgrade (il peut naître après)
+ * @param refusal - statut HTTP qui refuse l'upgrade, `null` pour l'admettre
+ *   (cf `HttpKernel.websocketUpgradeRefusal`)
+ * @param admit - décide d'un upgrade admis (cf `HttpKernel.onWebsocketUpgrade`) ;
+ *   par défaut, tout upgrade conforme est accepté et émis en `connection`
+ * @returns la fonction qui retire l'écouteur — à appeler à l'arrêt
+ */
+export declare function attachUpgradeDispatch(server: IUpgradeEmitter, wss: WebSocketServer, relay: () => IUpgradeRelay | null, refusal: (req: IncomingMessage) => number | null, admit?: UpgradeAdmit): () => void;
+export {};

package/dist/types/nodefony/src/session/session.d.ts

@@ -118,6 +118,8 @@ declare class Session implements ISession {
      * `onSaveSession`.
      *
      * @param user - principal authentifié (string) lié au blob ; défaut courant.
+     *   Fourni, il DEVIENT le principal de la session : une sauvegarde suivante,
+     *   dans la même requête, le garde sans qu'on le lui redonne.
      */
     save(user?: string): Promise<this>;
     /**