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

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

@@ -5,6 +5,20 @@ 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).
@@ -137,13 +151,23 @@ declare class HttpResponse {
      * 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. La
-     * réserve se vide ; ce qui se pose ensuite y retourne, et Node fusionne les
-     * deux au `writeHead`.
+     * 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(): void;
+    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
@@ -151,11 +175,20 @@ declare class HttpResponse {
      * 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.
+     * 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}. */
+    /**
+     * 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.
@@ -232,6 +265,27 @@ 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).

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

@@ -70,7 +70,7 @@ export interface ISseSendOptions<K extends string = string> {
 }
 /** 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;

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

@@ -27,6 +27,29 @@ import type http2 from "node:http2";
  * 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
@@ -43,6 +66,21 @@ export interface IStreamLifecycleSettings {
     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 {
@@ -50,4 +88,19 @@ export interface IOpenStreamLifecycle {
     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/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;

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

@@ -54,8 +54,9 @@ declare class Http2Response extends HttpResponse {
      */
     end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise<http.ServerResponse | http2.ServerHttp2Stream>;
     /**
-     * Termine la réponse de compatibilité d'un HEAD, dont Node a clos le flux de
-     * lui-même au `respond()`.
+     * Termine la réponse de compatibilité d'un HEAD, ou d'une réponse gRPC
+     * _Trailers-Only_ (statut gRPC dans les en-têtes), dont le flux s'est clos
+     * au `respond()`.
      *
      * Sans ce geste, `Http2ServerResponse` n'émet ni `finish` ni `close` : le
      * démontage de la requête, branché sur ce `close` (ligne d'accès, profil,
@@ -70,5 +71,37 @@ declare class Http2Response extends HttpResponse {
         code: number;
         message: string;
     };
+    /**
+     * Règle le sort d'un corps non lu quand la réponse part avant qu'il soit
+     * consommé (408 délai, 413 trop gros, refus précoce) : les octets en tampon
+     * sont jetés, puis — une fois la réponse écrite — le flux est fermé en
+     * `NO_ERROR` si le client ÉMET ENCORE.
+     *
+     * RFC 9113 §8.1 : après une réponse complète, le serveur PEUT demander au
+     * client d'arrêter d'émettre par un `RST_STREAM` `NO_ERROR`. `node:http2` ne
+     * le fait pas : le flux resterait ouvert tant que le client émet, et un
+     * client lent garderait sa place de flux sur la session. Attendre `finish`
+     * (fin d'écriture) garantit que la réponse elle-même n'est pas tronquée.
+     *
+     * « Émet encore » se décide après une GRÂCE d'un aller-retour
+     * ({@link closeStreamAfterGrace} : un `PING` par session pour tous les
+     * flux qui attendent, puis l'état du flux). Fini → le flux se ferme seul,
+     * sans `RST_STREAM` ; sinon — client qui émet encore, ou muet — fermé.
+     * Jamais de coupe avant la grâce : un `RST_STREAM` soumis pendant que la
+     * réponse attend dans la file de nghttp2 la fait jeter, et le client reçoit
+     * une fin de flux sans statut. grpc-go, Go `net/http2` et nginx coupent AUSSITÔT : Node, lui,
+     * répond avant de lire les trames DATA déjà en route, et la coupe
+     * immédiate frappait des clients qui finissaient d'émettre — le client
+     * HTTP/2 de Go la lit en erreur (ADR-0026 D13 point 1, constaté par la
+     * suite de conformité de Connect). `request.complete` ne dit rien ici : il
+     * ne passe à `true` qu'une fois le corps CONSOMMÉ.
+     *
+     * Chemin d'erreur seulement : un `PING` par aller-retour et par session,
+     * quel que soit le nombre de refus en attente.
+     *
+     * Sans effet si le corps est entièrement consommé, ou le flux déjà fermé.
+     * Peut s'appeler avant comme après l'écriture de la réponse.
+     */
+    closeUnfinishedRequest(): void;
 }
 export default Http2Response;

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

@@ -1,4 +1,5 @@
 import type { IRequestTrace, RequestTraceProtocol } from "../../interfaces/IRequestTrace.js";
+import type { IRpcOutcome } from "../../interfaces/IRpcCall.js";
 import type Context from "./Context.js";
 /**
  * Nom du `TracingChannel` qui encadre chaque requête HTTP et chaque handshake
@@ -60,5 +61,6 @@ export declare function runTraced<ThisArg, Args extends unknown[], Result>(trace
  * @param context - le contexte de la requête
  * @param statusCode - le statut rendu au client, `null` s'il n'y en a pas eu
  * @param error - l'exception attrapée par le pipeline, `null` ou `undefined` sinon
+ * @param rpc - l'appel RPC de la requête, `null` hors RPC : copié, jamais publié tel quel
  */
-export declare function closeRequestTrace(context: Context, statusCode: number | null, error: unknown): void;
+export declare function closeRequestTrace(context: Context, statusCode: number | null, error: unknown, rpc?: IRpcOutcome | null): void;

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

@@ -0,0 +1,11 @@
+import type { IRpcOutcome } from "../../interfaces/IRpcCall.js";
+/**
+ * Copie le résultat d'un appel RPC — les quatre champs, jamais la fiche
+ * d'appel entière, qui porte le contrôleur et le contexte (ADR-0026 D10). La
+ * forme est fixe : un objet par appel, alloué seulement par qui publie (audit
+ * JSON, canal de traçage avec abonné).
+ *
+ * @param call - l'appel RPC de la requête, `null` hors RPC.
+ * @returns sa copie, `null` hors RPC.
+ */
+export declare function rpcOutcomeOf(call: IRpcOutcome | null): IRpcOutcome | null;

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

@@ -54,7 +54,12 @@ declare class WebsocketResponse {
     handshakeHeaders: Record<string, string | number> | null;
     /**
      * Retient un en-tête du handshake (cf {@link handshakeHeaders}) ; sans effet
-     * une fois la socket ouverte, où il n'y a plus de réponse HTTP.
+     * une fois la socket ouverte, où il n'y a plus de réponse HTTP — sauf
+     * `Retry-After` posé par une action invoquée par le pont `api.request` : il
+     * va au puits de CETTE invocation, et le pont le sert avec le refus. Le même
+     * code de contrôleur dit donc « réessaie dans N s » sur les deux transports.
+     * Seul cet en-tête passe : un `Set-Cookie` ou un `WWW-Authenticate` n'a
+     * aucun sens sur une trame, et rien d'autre ne doit fuir par là.
      *
      * @param name - nom de l'en-tête
      * @param value - valeur

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

@@ -123,6 +123,14 @@ declare class WebsocketContext extends Context implements IWebsocketContextInter
     handle(data?: unknown[]): Promise<this>;
     render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>;
     send(data?: string | Buffer | null, encoding?: BufferEncoding): Promise<WebsocketResponse>;
+    /**
+     * Rend le corps rendu (`setBody`) en le RETIRANT de la réponse : une trame
+     * envoyée n'a plus à vivre aussi longtemps que la connexion.
+     *
+     * @param response - la réponse de ce contexte
+     * @returns le corps rendu, ou `null` s'il n'y en a pas
+     */
+    private static takeRenderedBody;
     broadcast(data?: string | Buffer | null, encoding?: BufferEncoding): null | undefined;
     /**
      * Le contenu des messages est-il journalisé ? Hors production seulement —

package/dist/types/nodefony/src/errors/httpError.d.ts

@@ -1,15 +1,40 @@
 import { nodefonyError as NodefonyError } from "nodefony";
 import { ContextType } from "../../service/http-kernel.js";
-import { HttpRequestType, HttpRsponseType } from "../context/http/HttpContext.js";
+/**
+ * Sérialise les propriétés propres d'une erreur HTTP, sans jamais LIRE celles
+ * qu'on écarte.
+ *
+ * Ne pas lire compte : `stack` est un accesseur paresseux de V8, et sa première
+ * lecture FORMATE la pile (`prepareStackTrace`, plusieurs µs). Lire puis
+ * supprimer, c'est payer ce formatage pour le jeter — ce que faisait le rendu
+ * d'erreur en production, sur chaque 404.
+ *
+ * @param error - l'erreur à sérialiser (en pratique un `HttpError`).
+ * @param omit - clés à écarter EN PLUS des références vivantes, ou `null`.
+ * @returns un objet plat, prêt pour `JSON.stringify`.
+ */
+export declare function serializeHttpError(error: Error, omit?: ReadonlySet<string> | null): Record<string, unknown>;
 declare class HttpError extends NodefonyError {
-    context?: ContextType | undefined;
-    response?: HttpRsponseType | undefined;
-    request?: HttpRequestType | undefined;
     url?: string | undefined;
     controller?: string | undefined;
     action?: string | undefined;
     jsonResponse?: string | undefined;
     constructor(message?: unknown, code?: number, context?: ContextType);
+    /**
+     * Construit un VERDICT de protocole (404, 405, 426…) sans capturer de pile.
+     *
+     * La pile d'un verdict pointe toujours au même endroit du noyau ou du routeur
+     * et ne dit rien de la requête ; la capturer coûte ~3,6 µs à profondeur
+     * réelle (`micro-error-path.mjs`), payés par chaque requête d'un scanner.
+     * Réservé à ce que le framework DÉCIDE — une panne garde sa pile. `stack` ne
+     * porte que l'en-tête (`HttpError: Not Found`).
+     *
+     * @param message - message du verdict.
+     * @param code - statut HTTP (ou code de fermeture WebSocket).
+     * @param context - contexte de la requête, comme pour le constructeur.
+     * @returns l'erreur, sans pile.
+     */
+    static withoutStack(message: string, code: number, context?: ContextType): HttpError;
     toString(): string;
 }
 export default HttpError;

package/dist/types/nodefony/src/grpc/cors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ce que les protocoles RPC servis (gRPC, gRPC-Web, Connect) demandent à la
+ * politique CORS de l'application (ADR-0026 D9).
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IRpcCorsLists {
+    /** Méthodes que le préflight doit autoriser. */
+    readonly allowedMethods: readonly string[];
+    /** En-têtes de requête que le préflight doit autoriser. */
+    readonly allowedHeaders: readonly string[];
+    /**
+     * En-têtes qu'une réponse RPC doit exposer au script de la page — sans eux,
+     * un client gRPC-Web ne lit ni le statut ni l'encodage de la réponse.
+     */
+    readonly exposedHeaders: readonly string[];
+}
+/**
+ * `Access-Control-Expose-Headers` d'une réponse RPC, composé une fois au
+ * chargement.
+ */
+export declare const RPC_EXPOSED_HEADERS: string;
+/**
+ * Les listes CORS que demandent les protocoles RPC — dès qu'un service gRPC
+ * est déclaré dans le processus, `null` sinon. Le pare-feu les ajoute à la
+ * politique de l'application au démarrage (`onReady`) : le préflight ne
+ * connaît pas la route, l'union est la seule voie (ADR-0026 D9 point 2).
+ *
+ * @returns les listes, ou `null` sans service gRPC déclaré.
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare function rpcCorsLists(): IRpcCorsLists | null;

package/dist/types/nodefony/src/grpc/limits.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Borne par défaut d'un message gRPC, reçu ou émis : 4 Mio (ADR-0026 D4,
+ * points 1 et 2). C'est la borne de réception des implémentations de
+ * référence (`grpc-js`, `grpc-go`) ; l'adaptateur Connect, lui, n'en pose
+ * aucune (`limit-io.js` : `0xffffffff`). Seule source de cette valeur : le
+ * schéma de la section `grpc` et le point d'entrée gRPC la lisent ici.
+ */
+export declare const GRPC_DEFAULT_MAX_MESSAGE_BYTES: number;
+/**
+ * Plus grande borne qu'accepte l'adaptateur Connect pour `readMaxBytes` et
+ * `writeMaxBytes` (`limit-io.js#validateReadWriteMaxBytes`) : la longueur
+ * d'une enveloppe tient sur 32 bits.
+ */
+export declare const GRPC_MAX_MESSAGE_BYTES = 4294967295;

package/dist/types/nodefony/src/grpc/refusal.d.ts

@@ -0,0 +1,136 @@
+import type http from "node:http";
+/**
+ * Refus d'un appel gRPC au format de son protocole (ADR-0026 D5 point 2, D13
+ * point 2). Sans Connect : une application sans service gRPC charge ce module
+ * avec le noyau, et n'y paie rien tant qu'aucune erreur n'est rendue.
+ *
+ * Le protocole se reconnaît aux en-têtes de la requête et se code en petit
+ * entier (`GRPC_WIRE_*`, 0 = aucun) : une valeur toujours du même type, lue
+ * sur le chemin d'erreur seulement.
+ */
+/** Requête qui ne parle aucun protocole gRPC. */
+export declare const GRPC_WIRE_NONE = 0;
+/** gRPC natif (`application/grpc`, `application/grpc+proto`…). */
+export declare const GRPC_WIRE_GRPC = 1;
+/** gRPC-Web (`application/grpc-web`, `application/grpc-web-text`…). */
+export declare const GRPC_WIRE_WEB = 2;
+/** Connect unaire (`connect-protocol-version`, ou GET `?connect=v1`). */
+export declare const GRPC_WIRE_CONNECT = 3;
+/** Connect en flux (`application/connect+proto`, `application/connect+json`). */
+export declare const GRPC_WIRE_CONNECT_STREAM = 4;
+/** Le protocole gRPC d'une requête, `GRPC_WIRE_NONE` s'il n'y en a aucun. */
+export type GrpcWire = typeof GRPC_WIRE_NONE | typeof GRPC_WIRE_GRPC | typeof GRPC_WIRE_WEB | typeof GRPC_WIRE_CONNECT | typeof GRPC_WIRE_CONNECT_STREAM;
+/**
+ * Reconnaît le protocole gRPC d'une requête à ses en-têtes : `content-type`
+ * d'abord, puis `connect-protocol-version`. Une API JSON ordinaire rend
+ * `GRPC_WIRE_NONE`.
+ *
+ * @param headers - les en-têtes de la requête.
+ * @param connectGet - `true` pour un GET qui porte `connect=v1` (Connect
+ *   unaire en GET, sans en-tête propre).
+ * @returns le protocole reconnu.
+ */
+export declare function grpcWireOf(headers: http.IncomingHttpHeaders, connectGet?: boolean): GrpcWire;
+/** 16 `UNAUTHENTICATED`. */
+export declare const GRPC_UNAUTHENTICATED = 16;
+/** 7 `PERMISSION_DENIED`. */
+export declare const GRPC_PERMISSION_DENIED = 7;
+/**
+ * Le nom d'un code gRPC (`unimplemented`, `unauthenticated`…) — le libellé
+ * générique d'un refus (ADR-0026 D5 point 4).
+ *
+ * @param code - le code gRPC, de 0 à 16.
+ * @returns son nom ; `unknown` hors de la plage.
+ */
+export declare function grpcCodeName(code: number): string;
+/**
+ * Le nom d'un code gRPC tel que le publient la ligne d'accès et le canal de
+ * traçage (`UNAVAILABLE`) — ADR-0026 D10 point 1.
+ *
+ * @param code - le code gRPC, de 0 à 16.
+ * @returns son nom ; `UNKNOWN` hors de la plage.
+ */
+export declare function grpcStatusName(code: number): string;
+/**
+ * Le code gRPC d'un refus de transport — rendu avant l'implémentation (chemin
+ * inconnu, méthode refusée, limite de débit, pare-feu) — en gRPC natif et en
+ * gRPC-Web (ADR-0026 D13 point 2). Distincte de la table des erreurs de
+ * l'application (D7) ; seule la règle d'identité de 401/403 est commune (D5).
+ *
+ * @param status - le statut HTTP que le noyau aurait rendu.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function transportRefusalCode(status: number, identified: boolean): number;
+/**
+ * Le code gRPC d'une erreur levée par l'APPLICATION pendant un appel — une
+ * `HttpError` d'un service partagé avec des routes HTTP, une validation, un
+ * conflit (ADR-0026 D7, table « HTTP Mapping » de `google/rpc/code.proto`).
+ * Distincte de la table des refus de transport ({@link transportRefusalCode}) :
+ * un 404 levé par un service dit « entité introuvable » (5), un chemin inconnu
+ * dit « méthode absente » (12). Seule la règle d'identité de 401/403 est
+ * commune (D5).
+ *
+ * `code.proto` associe 409 à `ABORTED` et à `ALREADY_EXISTS` : `ABORTED`, le
+ * sens le plus large, est retenu ; `ALREADY_EXISTS` se lève en `ConnectError`.
+ *
+ * @param status - le statut HTTP que rendrait une route HTTP.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function applicationErrorCode(status: number, identified: boolean): number;
+/**
+ * Le code d'un refus en protocole Connect : celui qu'un client DÉDUIT du
+ * statut HTTP (`connect-protocol.md`, « HTTP to Error Code »), puisque le
+ * statut voyage avec la réponse et doit s'accorder au code. 405 et 421 y
+ * valent donc `unknown` (ADR-0026 D13, précision du lot 3) ; 401/403 suivent
+ * la règle d'identité (D5).
+ *
+ * @param status - le statut HTTP du refus.
+ * @param identified - un appelant authentifié est connu.
+ * @returns le code gRPC.
+ */
+export declare function connectRefusalCode(status: number, identified: boolean): number;
+/** Ce que le refus touche de la réponse : son statut et ses en-têtes. */
+export interface IGrpcRefusalTarget {
+    setStatusCode(status: number, message?: string): void;
+    setHeader(name: string, value: string): void;
+}
+/**
+ * Pose le statut et les en-têtes d'un refus au format du protocole, et rend
+ * le corps à envoyer — vide en gRPC et gRPC-Web, dont le statut voyage dans
+ * les en-têtes (_Trailers-Only_ ; en HTTP/2, `Http2Response.writeHead` termine
+ * alors le flux sur la trame d'en-têtes).
+ *
+ * | Protocole       | Statut HTTP                    | Corps                                  |
+ * | --------------- | ------------------------------ | -------------------------------------- |
+ * | gRPC, gRPC-Web  | 200                            | aucun                                  |
+ * | Connect unaire  | celui du refus (401/403 : D5)  | `{"code":"<nom>"}`                     |
+ * | Connect en flux | 200                            | message de fin `{"error":{…}}`         |
+ *
+ * Le message n'est jamais celui de l'erreur, qui nomme parfois la zone
+ * refusée : seul le nom du code part (D5 point 4).
+ *
+ * @param response - la réponse du contexte, pas encore envoyée.
+ * @param wire - le protocole de la requête, autre que `GRPC_WIRE_NONE`.
+ * @param status - le statut HTTP que le noyau aurait rendu.
+ * @param identified - un appelant authentifié est connu.
+ * @param contentType - le `content-type` de la requête, recopié en gRPC,
+ *   gRPC-Web et Connect en flux (déjà reconnu par {@link grpcWireOf}).
+ * @returns le corps : texte vide, JSON, ou octets d'un message de fin.
+ */
+export declare function prepareGrpcRefusal(response: IGrpcRefusalTarget, wire: GrpcWire, status: number, identified: boolean, contentType: string | undefined): string | Uint8Array;
+/**
+ * Marque une route comme servie par un point d'entrée gRPC — au démarrage,
+ * par `@nodefony/framework/grpc`. Allume la garde qui refuse en 12 une requête
+ * gRPC native aboutie à une route qui n'est pas gRPC (ADR-0026 D13 point 3) :
+ * tant qu'aucune route n'est marquée, la garde coûte une lecture de booléen.
+ *
+ * @param route - la route montée pour une méthode du contrat.
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare function markGrpcRoute(route: {
+    grpc?: boolean | undefined;
+}): void;
+/** `true` dès qu'une route gRPC est déclarée dans le processus. */
+export declare function hasGrpcRoutes(): boolean;

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

@@ -38,6 +38,13 @@ export interface IRelaySettings {
      */
     agent: http.Agent | false | undefined;
 }
+/**
+ * En-têtes de CONNEXION (RFC 9110 §7.6.1) : ils décrivent un saut, jamais le
+ * message — un intermédiaire ne les transmet pas. Les cinq premiers sont en
+ * outre INTERDITS en HTTP/2 (RFC 9113 §8.2.2) : Node lève
+ * `ERR_HTTP2_INVALID_CONNECTION_HEADERS` si une réponse les porte.
+ */
+export declare const HOP_BY_HOP: ReadonlySet<string>;
 /**
  * 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

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

@@ -44,8 +44,9 @@ export interface ProxyIntrospection {
     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.
+     * générateur haproxy y envoie tout le trafic hors WebSocket (`proto h2`) ;
+     * nginx, qui ne parle HTTP/2 à ses amonts que par `grpc_pass`, n'y envoie
+     * que gRPC. Règle d'usage : {@link upstreamH2cPort}.
      */
     h2cPort?: number | null;
     /** Dossiers statiques servis à la racine `/` (ordre = priorité). */
@@ -98,6 +99,18 @@ export interface ProxyIntrospection {
 }
 /** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
 export declare const defaultIntrospection: ProxyIntrospection;
+/**
+ * Port h2c que le proxy doit joindre, ou `null` — règle UNIQUE des deux
+ * générateurs.
+ *
+ * Seulement vers un backend en clair : le re-chiffrement vise le port TLS, qui
+ * négocie déjà HTTP/2 par ALPN, et mélanger les deux liens ferait voyager une
+ * partie du trafic en clair alors que l'utilisateur a demandé le chiffrement.
+ *
+ * @param intro - modèle d'introspection Nodefony.
+ * @returns le port h2c à joindre, ou `null` s'il n'y a pas de lien h2c.
+ */
+export declare function upstreamH2cPort(intro: ProxyIntrospection): number | null;
 /**
  * Génère une configuration nginx complète (reverse-proxy + offload statiques).
  *