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

package/dist/nodefony/src/servers/http2StreamGrace.js

@@ -0,0 +1,100 @@
+import http2 from "node:http2";
+// nodefony/src/servers/http2StreamGrace.ts
+/**
+* Délai avant de retenter un `PING` que Node a refusé (plafond de `PING` en vol
+* atteint par d'autres émetteurs de la session) : ceux-là reviennent en un
+* aller-retour, une boucle `setImmediate` brûlerait le processeur pendant ce
+* temps sur un lien lent.
+*/
+const PING_RETRY_MS = 10;
+/**
+* Les flux d'une session qui attendent leur grâce. `inFlight` : couverts par le
+* `PING` en vol ; `next` : arrivés après son envoi, donc couverts par le
+* suivant — un `PING` envoyé AVANT leurs en-têtes ne prouve rien pour eux.
+*/
+var SessionGrace = class {
+	inFlight = null;
+	next = null;
+};
+/** Chemin d'erreur seulement : aucune session n'a d'entrée hors refus en cours. */
+const graces = /* @__PURE__ */ new WeakMap();
+/** Coupe le flux en `NO_ERROR` s'il est encore ouvert et que le client émet encore. */
+function decide(stream) {
+	if (stream.closed || stream.destroyed || stream.state.remoteClose) return;
+	stream.close(http2.constants.NGHTTP2_NO_ERROR);
+}
+function sendPing(session, grace) {
+	if (session.destroyed) {
+		graces.delete(session);
+		return;
+	}
+	if (session.closed) {
+		const pending = grace.inFlight;
+		const later = grace.next;
+		grace.inFlight = null;
+		grace.next = null;
+		graces.delete(session);
+		setImmediate(() => {
+			if (pending !== null) for (const stream of pending) decide(stream);
+			if (later !== null) for (const stream of later) decide(stream);
+		});
+		return;
+	}
+	if (!session.ping(() => settle(session, grace))) setTimeout(() => sendPing(session, grace), PING_RETRY_MS).unref();
+}
+function settle(session, grace) {
+	const batch = grace.inFlight;
+	grace.inFlight = grace.next;
+	grace.next = null;
+	if (batch !== null) for (const stream of batch) decide(stream);
+	if (grace.inFlight !== null) sendPing(session, grace);
+	else graces.delete(session);
+}
+/**
+* Ferme en `NO_ERROR` un flux HTTP/2 dont la réponse est partie mais dont le
+* client émet encore, après la grâce d'un aller-retour (`PING`, RFC 9113 §6.7).
+*
+* 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`. La coupe ne doit
+* jamais précéder l'envoi de la réponse : un `RST_STREAM` soumis pendant que
+* les en-têtes attendent encore dans la file de nghttp2 les fait JETER, et le
+* client reçoit une fin de flux sans statut (un client gRPC la lit INTERNAL).
+* Le `PING` part derrière la réponse ; son écho prouve qu'elle est arrivée.
+*
+* **Un seul `PING` par session** couvre tous les flux qui attendent : un flux
+* arrivé pendant qu'un `PING` est en vol attend le suivant. Le plafond de
+* `PING` en vol de Node (10 par session) n'est donc jamais atteint par ce
+* chemin, et aucun flux n'est coupé sans grâce — ce que faisait la coupe
+* immédiate quand `ping()` rendait `false`, au-delà de 10 refus simultanés.
+*
+* Session en fermeture GRACIEUSE (délai d'inactivité, arrêt) : Node n'envoie
+* plus de `PING`, et la session attend la fin de ses flux — un client muet la
+* retiendrait. La coupe part alors au tour de boucle suivant, le temps que les
+* réponses déjà soumises quittent la file de nghttp2.
+*
+* Après la grâce : client qui a fini d'émettre → rien (le flux se ferme seul,
+* sans `RST_STREAM`) ; sinon → coupé. L'écho d'un `PING` passe avant les autres
+* trames (§6.7) : une trame DATA encore en route peut arriver après lui, la
+* coupe reste conforme (§8.1).
+*
+* Coût : chemin d'erreur seulement — une entrée de `WeakMap` par session tant
+* que des flux attendent, un `PING` par aller-retour et par session.
+*
+* @param stream - flux dont la réponse est ÉCRITE (`finish` passé).
+*/
+function closeStreamAfterGrace(stream) {
+	if (stream.closed || stream.destroyed || stream.state.remoteClose) return;
+	const session = stream.session;
+	if (session === void 0) return;
+	let grace = graces.get(session);
+	if (grace === void 0) {
+		grace = new SessionGrace();
+		graces.set(session, grace);
+	}
+	if (grace.inFlight === null) {
+		grace.inFlight = [stream];
+		sendPing(session, grace);
+	} else if (grace.next === null) grace.next = [stream];
+	else grace.next.push(stream);
+}
+export { closeStreamAfterGrace };

package/dist/nodefony/src/servers/receiveDeadline.js

@@ -0,0 +1,177 @@
+// nodefony/src/servers/receiveDeadline.ts
+/** Capacité de départ de l'anneau, et celle où il revient une fois vide. */
+const INITIAL_CAPACITY = 64;
+/**
+* Une échéance ABSOLUE pour des réceptions en cours, sans un minuteur par
+* réception : un seul balayage périodique pour toutes.
+*
+* ## Pourquoi
+*
+* `node:http2` ne borne pas la réception d'une requête : il n'a que des délais
+* d'INACTIVITÉ (`http2stream.setTimeout`, `http2session.setTimeout`), qu'un
+* client tient en vie avec un octet avant chaque échéance. `requestTimeout`,
+* la borne absolue anti « slow-loris », n'existe que pour HTTP/1.1.
+*
+* ## Le coût, et pourquoi cette forme
+*
+* C'est la forme que Node donne lui-même à `requestTimeout` : aucun minuteur
+* par requête, un contrôle périodique (`connectionsCheckingInterval`). Les
+* réceptions suivies vivent dans un ANNEAU — un tableau des éléments et un
+* `Int32Array` des tours d'entrée, indexés par un numéro de séquence :
+* - suivre = deux écritures ; libérer = une comparaison et une écriture. Ni
+*   minuteur, ni fermeture, ni lecture d'horloge (le temps se compte en TOURS),
+*   ni champ ajouté à l'élément suivi ;
+* - mesuré contre une `Map` (hachage d'identité de la clé) : ~26–32 ns par
+*   réception contre ~90–150 ns, de 1 à 10 000 réceptions simultanées.
+*
+* Toutes les entrées ont le même délai : l'ordre d'insertion EST l'ordre
+* d'échéance. Un tour avance la tête et s'arrête à la première entrée vivante
+* non échue — il ne coûte que ce qu'il expire ou saute.
+*
+* Contrepartie, bornée : une case libérée DERRIÈRE une entrée vivante attend
+* que la tête la dépasse, soit au plus un délai de réception — 12 octets par
+* réception commencée dans cette fenêtre. Sous charge, l'anneau garde sa
+* capacité d'un tour à l'autre (jamais rétréci puis recrû) ; il la rend au
+* premier tour sans réception nouvelle. Le minuteur unique est `unref`, et s'arrête au
+* même moment.
+*
+* ## Précision
+*
+* Une entrée expire entre `timeoutMs` et `timeoutMs + periodMs` après son
+* suivi — jamais AVANT le délai configuré.
+*
+* @typeParam T - l'élément suivi (un contexte de requête)
+*/
+var ReceiveDeadline = class {
+	#items = new Array(INITIAL_CAPACITY).fill(null);
+	#ticks = new Int32Array(INITIAL_CAPACITY);
+	#mask = 63;
+	/** Numéro de séquence de la plus ancienne case non balayée. */
+	#head = 0;
+	/** Numéro de séquence de la prochaine entrée. */
+	#tail = 0;
+	#tick = 0;
+	#timer = null;
+	#onExpire;
+	#periodMs;
+	/** Tours pleins qu'une entrée doit voir passer avant d'expirer. */
+	#ttl;
+	/**
+	* @param timeoutMs - le délai de réception (> 0)
+	* @param onExpire - appelé une fois par entrée échue, déjà retirée
+	* @param periodMs - la période du balayage, bornée par le délai (défaut 1 s)
+	* @throws RangeError si `timeoutMs` ou `periodMs` n'est pas un entier > 0
+	*/
+	constructor(timeoutMs, onExpire, periodMs = 1e3) {
+		if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) throw new RangeError(`délai de réception invalide : ${timeoutMs}`);
+		if (!Number.isInteger(periodMs) || periodMs <= 0) throw new RangeError(`période de balayage invalide : ${periodMs}`);
+		this.#onExpire = onExpire;
+		this.#periodMs = Math.min(periodMs, timeoutMs);
+		this.#ttl = Math.ceil(timeoutMs / this.#periodMs);
+	}
+	/** Cases occupées, libérées ou non, entre la tête et la queue. */
+	get size() {
+		return this.#tail - this.#head;
+	}
+	/** Capacité courante de l'anneau. */
+	get capacity() {
+		return this.#mask + 1;
+	}
+	/** Vrai tant que le balayage tourne. */
+	get running() {
+		return this.#timer !== null;
+	}
+	/**
+	* Suit une réception qui commence ; démarre le balayage s'il dormait.
+	*
+	* @param item - la réception
+	* @returns le numéro à rendre à {@link ReceiveDeadline.release}
+	*/
+	track(item) {
+		if (this.#tail - this.#head > this.#mask) this.#grow();
+		const seq = this.#tail++;
+		const index = seq & this.#mask;
+		this.#items[index] = item;
+		this.#ticks[index] = this.#tick;
+		if (this.#timer === null) {
+			this.#timer = setInterval(() => this.#sweep(), this.#periodMs);
+			this.#timer.unref();
+		}
+		return seq;
+	}
+	/**
+	* Cesse de suivre une réception terminée (reçue, refusée ou échue). Sans
+	* effet si la case a déjà été balayée ou réattribuée : l'identité de
+	* l'élément est vérifiée. Le balayage ne s'arrête pas ici mais au tour
+	* suivant s'il ne reste rien — jamais un minuteur armé puis désarmé par
+	* requête.
+	*
+	* @param seq - le numéro rendu par {@link ReceiveDeadline.track}
+	* @param item - la réception suivie
+	*/
+	release(seq, item) {
+		const index = seq & this.#mask;
+		if (this.#items[index] === item) this.#items[index] = null;
+	}
+	/** Arrête le balayage et oublie toutes les réceptions (arrêt du serveur). */
+	close() {
+		if (this.#timer !== null) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+		this.#reset();
+	}
+	#sweep() {
+		const tick = ++this.#tick;
+		const items = this.#items;
+		const carried = this.#tail - this.#head;
+		while (this.#head < this.#tail) {
+			const index = this.#head & this.#mask;
+			const item = items[index] ?? null;
+			if (item !== null && tick - (this.#ticks[index] ?? 0) <= this.#ttl) break;
+			items[index] = null;
+			this.#head++;
+			if (item !== null) this.#onExpire(item);
+		}
+		if (this.#head !== this.#tail) return;
+		if (carried > 0) {
+			this.#head = 0;
+			this.#tail = 0;
+			return;
+		}
+		if (this.#timer !== null) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+		this.#reset();
+	}
+	/**
+	* Anneau au repos ou fermé : numéros remis à zéro et capacité de départ
+	* rendue. Un numéro encore détenu par un appelant ne désigne plus son
+	* élément : `release` le reconnaît à l'identité.
+	*/
+	#reset() {
+		this.#head = 0;
+		this.#tail = 0;
+		if (this.#mask + 1 !== INITIAL_CAPACITY) {
+			this.#items = new Array(INITIAL_CAPACITY).fill(null);
+			this.#ticks = new Int32Array(INITIAL_CAPACITY);
+			this.#mask = 63;
+		} else this.#items.fill(null);
+	}
+	/** Double la capacité, les entrées gardant leur numéro de séquence. */
+	#grow() {
+		const capacity = (this.#mask + 1) * 2;
+		const mask = capacity - 1;
+		const items = new Array(capacity).fill(null);
+		const ticks = new Int32Array(capacity);
+		for (let seq = this.#head; seq < this.#tail; seq++) {
+			items[seq & mask] = this.#items[seq & this.#mask] ?? null;
+			ticks[seq & mask] = this.#ticks[seq & this.#mask] ?? 0;
+		}
+		this.#items = items;
+		this.#ticks = ticks;
+		this.#mask = mask;
+	}
+};
+export { ReceiveDeadline };

package/dist/types/index.d.ts

@@ -77,7 +77,10 @@ export { decideSend, readBackpressureOptions, type WsBackpressurePolicy, type Ws
 export { admitFrame, frameRateRejectedTotal, readFrameRateBound, readFrameRateCloseAfter, FRAME_RATE_WINDOW_MS, type IFrameRateWindow, type IWsFrameRateOptions, } from "./nodefony/src/context/websocket/wsFrameRate.js";
 export { isWebsocketContext } from "./nodefony/src/context/websocket/isWebsocketContext.js";
 export { REQUEST_TRACE_CHANNEL } from "./nodefony/src/context/requestTrace.js";
+export { rpcCorsLists } from "./nodefony/src/grpc/cors.js";
+export type { IRpcCorsLists } from "./nodefony/src/grpc/cors.js";
 export type { IRequestTrace, RequestTraceProtocol, } from "./nodefony/interfaces/IRequestTrace.js";
+export type { IRpcCall, IRpcOutcome, RpcSystem, } from "./nodefony/interfaces/IRpcCall.js";
 export { compileDomainPattern, compileDomainPatterns, compileTrustedHosts, isDomainAllowed, } from "./nodefony/src/context/domainMatcher.js";
 export type { DomainPattern, ITrustedHostsConfig, } from "./nodefony/src/context/domainMatcher.js";
 export { MemoryRateLimitStore } from "./nodefony/src/rateLimit/MemoryRateLimitStore.js";
@@ -108,8 +111,8 @@ export type { IHttpResponse, IWebsocketResponse, } from "./nodefony/interfaces/I
 export type { IHttpKernel } from "./nodefony/interfaces/IHttpKernel.js";
 export type { IResolvedRoute, IRouteResolver, IRequestRouter, } from "./nodefony/interfaces/IRouting.js";
 export type { ISecurityZone, IFirewallGate, } from "./nodefony/interfaces/ISecurity.js";
-export type { IUploadedFile, IUploadService, IParsedUploadFile, IUploadOptions, } from "./nodefony/interfaces/IUpload.js";
-export type { IErrorRenderer, IErrorHttpResult, IErrorWebsocketResult, } from "./nodefony/interfaces/IErrorRenderer.js";
+export type { IUploadedFile, IUploadService, IParsedUploadFile, IUploadOptions, IRouteUploadOptions, } from "./nodefony/interfaces/IUpload.js";
+export type { IErrorRenderer, IErrorHttpResult, IErrorWebsocketResult, IErrorDescription, } from "./nodefony/interfaces/IErrorRenderer.js";
 export type { IRequestLogger, IRequestLogEntry, } from "./nodefony/interfaces/IRequestLogger.js";
 export type { AuditLogEntry, AuditErrorEntry, JsonAuditLoggerOptions, } from "./nodefony/service/audit-logger.js";
 export type { ContextType, httpRequest, httpResponse, ProtocolType, } from "./nodefony/service/http-kernel.js";

package/dist/types/nodefony/config/config.d.ts

@@ -108,6 +108,7 @@ export declare const httpConfigSchema: z.ZodObject<{
         }, z.core.$loose>]>>;
         skipUTF8Validation: z.ZodDefault<z.ZodBoolean>;
         autoPong: z.ZodDefault<z.ZodBoolean>;
+        maxPendingAutoPongs: z.ZodDefault<z.ZodNumber>;
         allowSynchronousEvents: z.ZodDefault<z.ZodBoolean>;
         maxBackpressure: z.ZodDefault<z.ZodNumber>;
         backpressureCloseAfterDrops: z.ZodDefault<z.ZodNumber>;
@@ -134,6 +135,7 @@ export declare const httpConfigSchema: z.ZodObject<{
         }, z.core.$loose>]>>;
         skipUTF8Validation: z.ZodDefault<z.ZodBoolean>;
         autoPong: z.ZodDefault<z.ZodBoolean>;
+        maxPendingAutoPongs: z.ZodDefault<z.ZodNumber>;
         allowSynchronousEvents: z.ZodDefault<z.ZodBoolean>;
         maxBackpressure: z.ZodDefault<z.ZodNumber>;
         backpressureCloseAfterDrops: z.ZodDefault<z.ZodNumber>;
@@ -208,6 +210,14 @@ export declare const httpConfigSchema: z.ZodObject<{
             }>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    grpc: z.ZodDefault<z.ZodObject<{
+        grpc: z.ZodDefault<z.ZodBoolean>;
+        grpcWeb: z.ZodDefault<z.ZodBoolean>;
+        connect: z.ZodDefault<z.ZodBoolean>;
+        readMaxBytes: z.ZodDefault<z.ZodNumber>;
+        writeMaxBytes: z.ZodDefault<z.ZodNumber>;
+        requireConnectProtocolHeader: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
     wsMaxConnectionsPerIp: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strict>;
 /** Type de sortie (config normalisée + défauts appliqués). */

package/dist/types/nodefony/grpc/GrpcCall.d.ts

@@ -0,0 +1,142 @@
+import type { ContextKey, ContextValues, HandlerContext } from "@connectrpc/connect";
+import type { IRpcCall, RpcSystem } from "../interfaces/IRpcCall.js";
+import type HttpContext from "../src/context/http/HttpContext.js";
+/**
+ * Fiche d'un appel gRPC : ce que Nodefony attache à l'appel, et le
+ * `ContextValues` que Connect remet au gestionnaire (`ctx.values`).
+ *
+ * Connect alloue à chaque appel un `ContextValues` fait d'un objet littéral et
+ * de trois fermetures (`context-values.js#createContextValues`), dont la forme
+ * change à chaque `set`. La fiche le REMPLACE (option `contextValues` de
+ * l'adaptateur) : une classe à champs déclarés, méthodes au prototype, une
+ * allocation par appel au lieu de quatre.
+ *
+ * Les clés posées par un tiers (intercepteur, porte) sont confiées à un
+ * `createContextValues()` créé au premier `set` : aucune allocation tant que
+ * personne n'en pose, et aucune conversion de type — la valeur rendue est celle
+ * que le magasin de Connect a typée.
+ *
+ * C'est aussi l'appel RPC du contexte (`HttpContext.rpc`, ADR-0026 D10) : à
+ * l'échéance du délai de réponse, le noyau le termine par {@link expire} ; au
+ * `close` de la réponse, il en fixe le code par {@link settle}, que lisent la
+ * ligne d'accès, l'audit et le canal de traçage.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare class GrpcCall implements ContextValues, IRpcCall {
+    #private;
+    /**
+     * L'objet qui implémente le service pour CET appel : le contrôleur, une
+     * instance par appel sous `@Scope("request")`. `null` quand l'adaptateur est
+     * appelé hors de {@link GrpcEndpoint.serve} (jamais en service normal).
+     */
+    readonly target: object | null;
+    /**
+     * Le contexte de la requête qui porte l'appel : l'identité y est lue
+     * (`authenticatedUser()`) sur son magasin, jamais par l'ALS, pour choisir
+     * entre 16 et 7 (ADR-0026 D5, D7). `null` hors de {@link GrpcEndpoint.serve}.
+     */
+    readonly context: HttpContext | null;
+    constructor(target: object | null, context?: HttpContext | null);
+    /**
+     * Le protocole parlé sur le fil : celui du contexte d'appel (`grpc`,
+     * `grpc-web`, `connect`) ; à défaut, celui des en-têtes de la requête.
+     */
+    get system(): RpcSystem;
+    /**
+     * `paquet.Service/Méthode` : le chemin de la route, que l'adaptateur a
+     * reconnu à l'octet près. Lu à la première demande, puis retenu.
+     */
+    get method(): string;
+    /** Le code de l'appel (0 à 16), `null` avant {@link settle}. */
+    get code(): number | null;
+    /** Le nom du code (`OK`, `UNAVAILABLE`…), `null` avec lui. */
+    get codeName(): string | null;
+    /**
+     * Fixe le code de l'appel au `close` de la réponse (ADR-0026 D10 point 2) :
+     *
+     * - motif `ConnectError` → son code ; sa cause, si c'est une `Error`, part
+     *   à la ligne d'accès (exception traduite par D7). Réponse NON finie : 1,
+     *   sauf une fin posée par le serveur (échéance 4, interruption de la fiche)
+     *   — le client est parti, quel que soit le code de son `RST_STREAM` ;
+     * - `AbortError` ou aucun motif → 0 si la réponse est finie, sinon 1 (le
+     *   client est parti — le 499 du noyau, dit en gRPC) ;
+     * - autre valeur → 13, et elle part à la ligne d'accès.
+     *
+     * Une interruption du serveur (délai échu, identité révoquée) abaisse le
+     * signal avec sa `ConnectError` : elle suit la première règle. Sans contexte
+     * d'appel, le code reste `null`.
+     *
+     * @param ended - la réponse a-t-elle été terminée par le serveur ?
+     * @returns la cause à porter par la ligne d'accès, `null` sinon.
+     */
+    settle(ended: boolean): Error | null;
+    /**
+     * Lit une valeur posée par un tiers, ou la valeur par défaut de sa clé.
+     *
+     * @param key - la clé (`createContextKey`).
+     * @returns la valeur posée, sinon `key.defaultValue`.
+     */
+    get<T>(key: ContextKey<T>): T;
+    /**
+     * Pose une valeur pour la durée de l'appel.
+     *
+     * @param key - la clé (`createContextKey`).
+     * @param value - la valeur.
+     * @returns la fiche, pour chaîner.
+     */
+    set<T>(key: ContextKey<T>, value: T): this;
+    /**
+     * Retire une valeur ; sa clé rendra de nouveau sa valeur par défaut.
+     *
+     * @param key - la clé (`createContextKey`).
+     * @returns la fiche, pour chaîner.
+     */
+    delete(key: ContextKey<unknown>): this;
+    /**
+     * Le délai de réponse du serveur est échu : le signal de l'appel s'abaisse
+     * (`ctx.abort`) et l'appel se termine en 4 `DEADLINE_EXCEEDED`, même si le
+     * gestionnaire ne lit pas son signal. Échu avant que le gestionnaire ne
+     * démarre : il est terminé dès son démarrage. Sans effet après la fin.
+     */
+    expire(): void;
+    /**
+     * L'identité qui a ouvert l'appel n'est plus valable : le signal de l'appel
+     * s'abaisse et l'appel se termine en 16 `UNAUTHENTICATED`. Réponse unique :
+     * sa promesse est rejetée. Flux : il s'arrête au message suivant, même si le
+     * gestionnaire ne lit pas son signal — au plus le message déjà en vol part.
+     * Sans effet après la fin, ou après une autre interruption.
+     */
+    revoke(): void;
+    /**
+     * Le serveur s'arrête : le signal de l'appel s'abaisse et l'appel se termine
+     * en 14 `UNAVAILABLE` — le client le rejoue ailleurs (ADR-0026 D8). Flux : il
+     * s'arrête au message suivant, même si le gestionnaire ne lit pas son
+     * signal. Un gestionnaire bloqué qui n'écoute rien tombe avec sa connexion, à
+     * `shutdownTimeout`. Sans effet après la fin, ou après une autre interruption.
+     */
+    shutdown(): void;
+}
+/**
+ * Le contexte d'appel que Connect remet réellement au gestionnaire : son type
+ * public (`HandlerContext`) ne dit pas `abort`, que porte pourtant l'objet créé
+ * par `createHandlerContext` (`HandlerContextController`, non exporté).
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IAbortableHandlerContext extends HandlerContext {
+    /** Interrompt l'appel : `ctx.signal` s'abaisse avec `reason`. */
+    abort(reason?: unknown): void;
+}
+/**
+ * Garde de type : le contexte d'appel porte-t-il `abort` ? Connect le pose sur
+ * tout contexte qu'il crée ; le garde le CONSTATE au lieu de le supposer, pour
+ * qu'une version de Connect qui le retirerait se voie à l'exécution (et au
+ * test qui le garde) plutôt que par un appel qui ne s'interrompt plus.
+ *
+ * @param ctx - le contexte remis au gestionnaire.
+ * @returns `true` si `ctx.abort` est une fonction.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare function hasAbort(ctx: HandlerContext): ctx is IAbortableHandlerContext;

package/dist/types/nodefony/grpc/GrpcEndpoint.d.ts

@@ -0,0 +1,98 @@
+import type { DescService } from "@bufbuild/protobuf";
+import type HttpContext from "../src/context/http/HttpContext.js";
+/**
+ * Protocoles servis — la section `grpc` de la configuration http
+ * (ADR-0026 D3, point 5).
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IGrpcProtocols {
+    readonly grpc: boolean;
+    readonly grpcWeb: boolean;
+    readonly connect: boolean;
+}
+/**
+ * La section `grpc` de la configuration http : protocoles servis (D3, point
+ * 5) et bornes des messages (D4, points 1, 2 et 6).
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IGrpcSettings extends IGrpcProtocols {
+    /** Taille maximale d'un message reçu, après décompression (octets). */
+    readonly readMaxBytes: number;
+    /** Taille maximale d'un message émis (octets). */
+    readonly writeMaxBytes: number;
+    /** Exige l'en-tête `Connect-Protocol-Version` sur les requêtes Connect. */
+    readonly requireConnectProtocolHeader: boolean;
+}
+/**
+ * Options d'un {@link GrpcEndpoint}.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IGrpcEndpointOptions {
+    /**
+     * `true` : la cible change à chaque appel (contrôleur `@Scope("request")`),
+     * chaque méthode la relit dans la fiche d'appel. `false` (défaut) : la cible
+     * du premier appel sert tous les suivants (contrôleur singleton) et ses
+     * méthodes sont liées une fois — aucune indirection par appel.
+     */
+    readonly perCall?: boolean;
+}
+/**
+ * Point d'entrée gRPC d'un service : possède l'adaptateur Connect
+ * (`connectNodeAdapter`) et lui confie la requête et la réponse BRUTES de Node
+ * d'un contexte déjà passé par le pipeline (pare-feu, gardes).
+ *
+ * L'adaptateur est construit au premier appel, depuis la section `grpc` de la
+ * configuration http. Il reçoit la fiche d'appel ({@link GrpcCall}) par son
+ * option `contextValues`, qu'il appelle de façon SYNCHRONE avant toute
+ * attente (`connect-node-adapter.js#nodeRequestHandler`) : la cible passe par
+ * une case lue à cet instant — ni ALS, ni promesse, ni écouteur de plus.
+ *
+ * Les méthodes s'inscrivent une à une par `router.rpc`, SANS options : des
+ * options passées à l'inscription rallumeraient gRPC et gRPC-Web coupés par la
+ * configuration (connectrpc/connect-es#1835). La restriction de protocoles
+ * vit sur l'adaptateur seul.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare class GrpcEndpoint<S extends DescService = DescService> {
+    #private;
+    /** Le contrat servi (descripteur généré par `buf`). */
+    readonly service: S;
+    /** Cible relue à chaque appel (`@Scope("request")`). */
+    readonly perCall: boolean;
+    constructor(service: S, options?: IGrpcEndpointOptions);
+    /**
+     * Remet la requête du contexte à l'adaptateur, qui écrit lui-même la
+     * réponse et ses trailers. Synchrone : rien n'est attendu ici.
+     *
+     * Avant de la remettre : le contexte est marqué répondu (`sended`), si bien
+     * que le pipeline n'attend aucune réponse de l'action.
+     *
+     * - Appel unaire : le délai de réponse de Nodefony reste armé, et termine
+     *   l'appel en 4 `DEADLINE_EXCEEDED` par sa fiche (`HttpContext.rpc`,
+     *   ADR-0026 D4 point 3).
+     * - Flux : aucune échéance. Il s'ouvre par le cycle de vie d'un flux
+     *   (`openStreamLifecycle`, D4 point 4) — délai de réponse désarmé (à
+     *   l'expiration il écrirait un 503 par-dessus l'adaptateur), place dans
+     *   le budget de connexions longues par IP, client qui ne lit plus coupé
+     *   par le balayage de blocage. Synchrone, sauf quand une session est à
+     *   sauver : l'appel n'est remis qu'après.
+     *
+     * @param context - le contexte HTTP de la requête, pas encore répondu.
+     * @param target - l'objet qui implémente le service pour cet appel.
+     * @returns rien, ou la promesse de la remise quand une session est à sauver.
+     * @throws HttpError 500 quand la réponse est déjà partie, ou que son
+     *   transport n'est pas reconnu.
+     * @throws HttpError 429 quand l'IP du client a déjà tous ses flux et sockets
+     *   (`wsMaxConnectionsPerIp`) — rendu par le pipeline en 14 `UNAVAILABLE`.
+     * @throws HttpError 400 quand l'adaptateur refuse la requête avant d'avoir
+     *   rien écrit (requête sans autorité `Host`) — la réponse revient alors au
+     *   pipeline.
+     * @throws HttpError 404 quand aucune méthode ne correspond au chemin exact
+     *   (casse modifiée) — rendu par le pipeline en 12 `UNIMPLEMENTED`.
+     */
+    serve(context: HttpContext, target: object): void | Promise<void>;
+}

package/dist/types/nodefony/grpc/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@nodefony/http/grpc` — la primitive de transport gRPC (ADR-0026).
+ *
+ * Sous-chemin à part : le point d'entrée principal de `@nodefony/http` ne cite
+ * ni Connect ni protobuf, même en type (D12). Seule une application qui
+ * déclare un service l'importe — par `@nodefony/framework/grpc` — et charge
+ * alors Connect au démarrage.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export { GrpcCall, hasAbort } from "./GrpcCall.js";
+export type { IAbortableHandlerContext } from "./GrpcCall.js";
+export { GrpcEndpoint } from "./GrpcEndpoint.js";
+export type { IGrpcEndpointOptions, IGrpcProtocols, IGrpcSettings, } from "./GrpcEndpoint.js";
+export { markGrpcRoute } from "../src/grpc/refusal.js";

package/dist/types/nodefony/interfaces/IContext.d.ts

@@ -3,6 +3,7 @@ import type { MaybePromise } from "nodefony";
 import type { ICookie } from "./ICookie.js";
 import type { ISession } from "./ISession.js";
 import type { HTTPMethodType } from "./IRequest.js";
+import type { IRpcCall } from "./IRpcCall.js";
 /**
  * Identité du serveur qui a reçu la requête, nommée par le schéma d'URI qu'il
  * sert en LOCAL (RFC 9110 §4.2, RFC 6455 §3) : elle choisit la section de
@@ -156,6 +157,14 @@ export interface IContext {
 export interface IHttpContext extends IContext {
     proxy: object | null;
     isRedirect: boolean;
+    /**
+     * L'appel RPC servi par cette requête (gRPC, gRPC-Web, Connect), `null` hors
+     * appel RPC — ADR-0026 D10. Son code est fixé au `close`, avant la ligne
+     * d'accès.
+     *
+     * @experimental Surface gRPC, ADR-0026 D11.
+     */
+    rpc: IRpcCall | null;
     /**
      * Sert la requête — synchrone quand l'action et son rendu le sont.
      *

package/dist/types/nodefony/interfaces/IErrorRenderer.d.ts

@@ -11,6 +11,20 @@ export interface IErrorHttpResult {
     body: unknown;
     headers?: Record<string, string | number>;
 }
+/**
+ * Ce qu'une route HTTP rendrait pour une erreur — son statut et le message
+ * destiné au client —, sans rien écrire. Sert les transports qui n'ont pas de
+ * corps d'erreur à rendre : un appel gRPC traduit ce statut en code
+ * (ADR-0026 D7).
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export interface IErrorDescription {
+    /** Statut HTTP émettable (100 à 599). */
+    readonly status: number;
+    /** Message pour le client : opaque pour un 5xx en production. */
+    readonly message: string;
+}
 /**
  * Aide jointe au corps d'erreur — ce que le développeur doit faire, en clair.
  *

package/dist/types/nodefony/interfaces/IRequest.d.ts

@@ -1,5 +1,6 @@
 import type { URL } from "node:url";
 import type { ICookie } from "./ICookie.js";
+import type { IUploadedFile } from "./IUpload.js";
 export type HTTPMethodType = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH" | "WEBSOCKET";
 export interface IRequest {
     url: URL | string;
@@ -19,7 +20,7 @@ export interface IHttpRequest extends IRequest {
     url: URL;
     query: Record<string, unknown>;
     body: RequestBody;
-    files: readonly unknown[];
+    files: readonly IUploadedFile[];
     remoteAddress: string | null | undefined;
     acceptHtml: boolean;
     getRemoteAddress(): string | null | undefined;

package/dist/types/nodefony/interfaces/IRequestTrace.d.ts

@@ -1,5 +1,6 @@
 import type { SchemeType } from "./IContext.js";
 import type { HTTPMethodType } from "./IRequest.js";
+import type { IRpcOutcome } from "./IRpcCall.js";
 /**
  * Nature de l'opération tracée : une requête HTTP, ou le handshake d'une
  * connexion WebSocket.
@@ -53,4 +54,13 @@ export interface IRequestTrace {
      * sans exception n'en porte pas ; c'est à l'abonné de classer un statut.
      */
     readonly error: unknown;
+    /**
+     * L'appel RPC (gRPC, gRPC-Web, Connect) servi par la requête, `null` hors
+     * RPC : système, méthode, code et son nom (ADR-0026 D10 point 5). Un flux
+     * est UN message, de l'ouverture au `close` ; rien par message.
+     * `statusCode` reste le statut HTTP, vrai sur le fil.
+     *
+     * @experimental Surface gRPC, ADR-0026 D11.
+     */
+    readonly rpc: IRpcOutcome | null;
 }