@nodefony/http 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/nodefony/service/http-kernel.js

@@ -4,7 +4,6 @@ import { resolveForwarded } from "../src/context/forwarded.js";
 import { MemoryRateLimitStore } from "../src/rateLimit/MemoryRateLimitStore.js";
 import { WsConnectionCounter } from "../src/rateLimit/WsConnectionCounter.js";
 import { compileDomainPatterns, compileTrustedHosts, isDomainAllowed } from "../src/context/domainMatcher.js";
-import Context from "../src/context/Context.js";
 import WebsocketContext from "../src/context/websocket/WebsocketContext.js";
 import HttpContext from "../src/context/http/HttpContext.js";
 import DefaultErrorRenderer from "./error-renderer.js";
@@ -12,10 +11,12 @@ import DefaultRequestLogger from "./request-logger.js";
 import JsonAuditLogger from "./audit-logger.js";
 import PrettyRequestLogger from "./pretty-request-logger.js";
 import { resolveTraceparent } from "./trace.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
-import { GcScheduler, Module, RequestContext, Service, injectable, logColor, nodefonyError, servedUrl, writeRuntimeState } from "nodefony";
+import { asServersConfig, configuredServerPort } from "../src/servers/kernelServers.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import { GcScheduler, Module, RequestContext, Service, finallyMaybe, injectable, isPromise, logColor, nodefonyError, servedUrl, thenMaybe, writeRuntimeState } from "nodefony";
 import cluster from "node:cluster";
+import http from "node:http";
 import Ws from "ws";
 //#region nodefony/service/http-kernel.ts
 const HEALTH_HEADERS = {
@@ -46,6 +47,11 @@ const perfProbe = process.env.NF_PERF_PROBE === "1" ? {
 	reqAcceptNs: 0
 } : null;
 if (perfProbe) globalThis.__nfPerfProbe = perfProbe;
+/**
+* Règlement ignoré d'une promesse dont personne n'attend l'issue — UNE fonction
+* de module, jamais une fermeture allouée par requête.
+*/
+const ignoreSettled = () => void 0;
 const serviceName = "HttpKernel";
 const WS_DEV_LOOPBACK = /* @__PURE__ */ new Set([
 	"localhost",
@@ -153,7 +159,7 @@ let HttpKernel = class HttpKernel extends Service {
 		this.computeSecurityHeaderCaches();
 		this._trustProxyChecker = null;
 		this._wsOriginPolicy = Object.create(null);
-		this.trustedHosts = this.options?.trustedHosts;
+		this.trustedHosts = this.options.trustedHosts;
 		this.regAlias = this.compileAlias();
 		this.configureRateLimit();
 		this.configureWsConnectionLimit();
@@ -239,7 +245,7 @@ let HttpKernel = class HttpKernel extends Service {
 			this.serviceCerticats = this.get("certificates");
 			this.serverStatic = this.get("server-static");
 			this.domain = this.kernel?.domain;
-			this.trustedHosts = this.options?.trustedHosts;
+			this.trustedHosts = this.options.trustedHosts;
 			this.regAlias = this.compileAlias();
 			this.sessionService = this.get("sessions");
 			this.profiler = this.get("profiler");
@@ -271,7 +277,7 @@ let HttpKernel = class HttpKernel extends Service {
 	* @returns le {@link TrustProxyChecker} partagé.
 	*/
 	getTrustProxyChecker() {
-		if (this._trustProxyChecker === null) this._trustProxyChecker = buildTrustProxy(this.options?.trustProxy);
+		this._trustProxyChecker ??= buildTrustProxy(this.options.trustProxy);
 		return this._trustProxyChecker;
 	}
 	/**
@@ -287,7 +293,7 @@ let HttpKernel = class HttpKernel extends Service {
 	getWsOriginPolicy(cfgKey) {
 		let policy = this._wsOriginPolicy[cfgKey];
 		if (!policy) {
-			const raw = this.options[cfgKey]?.allowedOrigins;
+			const raw = this.options[cfgKey].allowedOrigins;
 			if (raw === true) policy = {
 				disabled: true,
 				extra: []
@@ -352,7 +358,7 @@ let HttpKernel = class HttpKernel extends Service {
 	* gagne toujours sur la config (idempotent — last setter wins).
 	*/
 	applyRequestLoggerFromConfig() {
-		const kernelLog = this.kernel?.options?.log ?? {};
+		const kernelLog = this.kernel?.options.log ?? {};
 		let format = kernelLog.requestFormat ?? "auto";
 		if (format === "auto") {
 			const env = this.kernel?.environment;
@@ -370,7 +376,17 @@ let HttpKernel = class HttpKernel extends Service {
 			this.requestLogger = new JsonAuditLogger(opts);
 		}
 	}
-	async handle(request, response, type) {
+	/**
+	* Ouvre le scope `request` de la requête et la confie au pipeline HTTP.
+	*
+	* Pas `async` : rien n'y est attendu — la fonction rend directement ce que
+	* rend le pipeline, sans l'envelopper dans une promesse (#505).
+	*
+	* @returns le contexte servi, ou sa promesse (celle de {@link handleHttp}).
+	* @throws de façon synchrone si le scope `request` n'est pas déclaré — faute
+	*   de configuration ; l'appelant ({@link onHttpRequest}) l'absorbe.
+	*/
+	handle(request, response, type) {
 		let scope;
 		if (perfProbe) {
 			const t0 = process.hrtime.bigint();
@@ -378,7 +394,7 @@ let HttpKernel = class HttpKernel extends Service {
 			perfProbe.enterScopeNs += Number(process.hrtime.bigint() - t0);
 			perfProbe.count++;
 		} else scope = this.container?.enterScope("request");
-		if (this.kernel?.debug) this.log(logColor.cyanBgBlue(`${request.url}`), "DEBUG", `${type}`);
+		if (this.kernel?.debug) this.log(logColor.cyanBgBlue(`${request.url}`), "DEBUG", type);
 		return this.handleHttp(scope, request, response, type);
 	}
 	/**
@@ -392,13 +408,16 @@ let HttpKernel = class HttpKernel extends Service {
 	* elle, exécute du code utilisateur (`initialize()`) et résout des dépendances
 	* DI : elle n'a rien à faire avant que la requête soit autorisée.
 	*
+	* Synchrone : le match est un calcul pur, rien n'y est attendu (#505).
+	*
 	* @param checkFirewall - calcule `context.secure` (zone protégée) ; laissé à
 	*   `false` par un appelant qui l'a déjà tranché.
+	* @returns le résolveur de la route, posé sur `context.resolver`.
 	* @throws HttpError 404 quand aucune route ne matche, ou l'exception portée
-	*   par le résolveur (405…) — inchangé, et toujours avant le firewall : une
-	*   route inexistante ne devient pas un 401.
+	*   par le résolveur (405…) — de façon SYNCHRONE, et toujours avant le
+	*   firewall : une route inexistante ne devient pas un 401.
 	*/
-	async prepareFrontController(context, checkFirewall = true) {
+	prepareFrontController(context, checkFirewall = true) {
 		if (!this.router) throw new Error("kernel HTTP not ready");
 		if (this.firewall && checkFirewall) context.secure = this.firewall.isSecure(context);
 		let resolver;
@@ -429,7 +448,7 @@ let HttpKernel = class HttpKernel extends Service {
 	*   `Resolver.executeAction` créer l'instance une fois la requête autorisée.
 	*/
 	async handleFrontController(context, checkFirewall = true) {
-		return await (await this.prepareFrontController(context, checkFirewall)).newController(context);
+		return this.prepareFrontController(context, checkFirewall).newController(context);
 	}
 	/**
 	* Handles errors by setting appropriate response codes and messages.
@@ -484,49 +503,77 @@ let HttpKernel = class HttpKernel extends Service {
 	}
 	async onError(error, context, _extraHeaders) {
 		if (context) context.error = error;
-		switch (true) {
-			case context instanceof HttpContext: {
-				const result = this.errorRenderer.renderHttp(error, context);
-				if (error instanceof HttpError || error instanceof nodefonyError) error.code = result.status;
-				context.response.setStatusCode(result.status, result.message);
-				if (result.headers) context.response.setHeaders(result.headers);
-				if (this.kernel?.debug) this.log(error.toString(), "ERROR");
-				if (context.finished || context.sended) {
-					this.log(error.toString(), "DEBUG", "onError on closed context");
-					return context;
-				}
-				if (!context.response.isHeaderSent()) {
-					try {
-						await context.render(result.body);
-					} catch (e) {
-						this.log(e, "CRITIC");
-						throw e;
-					}
-					return context;
-				}
-				await context.close();
+		if (context instanceof HttpContext) {
+			const result = this.errorRenderer.renderHttp(error, context);
+			if (error instanceof HttpError || error instanceof nodefonyError) error.code = result.status;
+			context.response.setStatusCode(result.status, http.STATUS_CODES[result.status] ?? "Unknown Error");
+			if (result.headers) context.response.setHeaders(result.headers);
+			if (this.kernel?.debug) this.log(error.toString(), "ERROR");
+			if (context.finished || context.sended) {
+				this.log(error.toString(), "DEBUG", "onError on closed context");
 				return context;
 			}
-			case context instanceof WebsocketContext: try {
-				const wsResult = this.errorRenderer.renderWebsocket(error, context);
-				if (context.response && context.response.connection) {
-					context.close(wsResult.code, wsResult.reason);
-					return context;
-				}
-				if (context.request && !context.rejected) {
-					context.reject(wsResult.code, wsResult.reason);
-					return context;
+			if (!context.response.isHeaderSent()) {
+				try {
+					await context.render(result.body);
+				} catch (e) {
+					this.log(e, "CRITIC");
+					throw e;
 				}
-			} catch (e) {
-				throw error;
+				return context;
+			}
+			await context.close();
+			return context;
+		}
+		if (context instanceof WebsocketContext) try {
+			const wsResult = this.errorRenderer.renderWebsocket(error, context);
+			if (context.response?.connection) {
+				context.close(wsResult.code, wsResult.reason);
+				return context;
 			}
-			default: throw error;
+			if (context.request && !context.rejected) {
+				context.reject(wsResult.code, wsResult.reason);
+				return context;
+			}
+		} catch {
+			throw error;
 		}
+		throw error;
 	}
 	compileAlias() {
 		return compileTrustedHosts(this.domain, this.trustedHosts, this.kernel?.environment === "development");
 	}
-	async onHttpRequest(request, response, type) {
+	/**
+	* Point d'entrée d'une requête HTTP, appelé par les serveurs depuis leur
+	* écouteur `request`.
+	*
+	* Ne lève et ne rejette JAMAIS : dans un écouteur d'événement, une exception
+	* deviendrait une erreur non capturée du processus. Ce qui échappe au
+	* pipeline a déjà été traité — rendu au client par `onError`, qui journalise
+	* en CRITIC l'échec de son propre rendu avant de le relever. C'était le
+	* `.catch` vide des serveurs ; il vit désormais ici, une seule fois.
+	*
+	* @returns `undefined` quand la requête est servie sans pipeline (sonde de
+	*   santé, 429) ; sinon la promesse de la fin du pipeline — elle ne rejette
+	*   pas, et personne n'est tenu de l'attendre.
+	*/
+	onHttpRequest(request, response, type) {
+		let pipeline;
+		try {
+			pipeline = this.dispatchHttpRequest(request, response, type);
+		} catch {
+			return;
+		}
+		return isPromise(pipeline) ? Promise.resolve(pipeline).then(ignoreSettled, ignoreSettled) : void 0;
+	}
+	/**
+	* Le travail d'{@link onHttpRequest} : en-têtes de transport, sondes de
+	* santé, rate-limit, hook `onServerRequest`, puis le pipeline.
+	*
+	* @returns `undefined` quand la requête est servie ici ; sinon la promesse du
+	*   pipeline.
+	*/
+	dispatchHttpRequest(request, response, type) {
 		const headerServer = this.options.headerServer;
 		if (headerServer != null && headerServer !== "") response.setHeader("Server", headerServer);
 		if (this.secContentTypeOptions !== null) response.setHeader("X-Content-Type-Options", this.secContentTypeOptions);
@@ -534,11 +581,17 @@ let HttpKernel = class HttpKernel extends Service {
 		if (this.secHsts !== null && (type === "https" || type === "http2")) response.setHeader("Strict-Transport-Security", this.secHsts);
 		if (this.#healthPaths !== null) {
 			const url = request.url;
-			if (url === this.#healthPaths.liveness) return this.#respondHealth(response, true);
-			if (url === this.#healthPaths.readiness) return this.#respondHealth(response, !this.#terminating && this.kernel?.servable === true);
+			if (url === this.#healthPaths.liveness) {
+				this.#respondHealth(response, true);
+				return;
+			}
+			if (url === this.#healthPaths.readiness) {
+				this.#respondHealth(response, !this.#terminating && this.kernel?.servable === true);
+				return;
+			}
 		}
 		if (this.rateLimiter !== null) {
-			const ip = resolveForwarded(request.headers, request.socket?.remoteAddress, this.getTrustProxyChecker()).clientIp;
+			const ip = resolveForwarded(request.headers, request.socket.remoteAddress, this.getTrustProxyChecker()).clientIp;
 			if (ip !== null) {
 				const verdict = this.rateLimiter.hit(ip);
 				response.setHeader("X-RateLimit-Limit", verdict.limit);
@@ -553,12 +606,8 @@ let HttpKernel = class HttpKernel extends Service {
 				}
 			}
 		}
-		if (this.listenerCount("onServerRequest")) await this.fireAsync("onServerRequest", request, response, type).catch((e) => {
-			throw e;
-		});
-		return this.handle(request, response, type).catch((e) => {
-			throw e;
-		});
+		if (this.listenerCount("onServerRequest")) return this.fireAsync("onServerRequest", request, response, type).then(() => this.handle(request, response, type));
+		return this.handle(request, response, type);
 	}
 	async initServers() {
 		const servers = [];
@@ -623,18 +672,18 @@ let HttpKernel = class HttpKernel extends Service {
 		if (serverHttp?.active && serverHttp.port > 0) {
 			ports.push(serverHttp.port);
 			urls.push(servedUrl("http", serverHttp.domain, serverHttp.port));
-			const d = this.kernel?.options.servers?.http;
-			if (d && d.port) desired.push(d.port);
+			const port = configuredServerPort(asServersConfig(this.kernel?.options.servers), "http");
+			if (port) desired.push(port);
 		}
 		if (serverHttps?.active && serverHttps.port > 0) {
 			ports.push(serverHttps.port);
 			urls.push(servedUrl("https", serverHttps.domain, serverHttps.port));
-			const d = this.kernel?.options.servers?.https;
-			if (d && d.port) desired.push(d.port);
+			const port = configuredServerPort(asServersConfig(this.kernel?.options.servers), "https");
+			if (port) desired.push(port);
 		}
 		if (ports.length === 0) return;
 		writeRuntimeState(process.cwd(), {
-			pid: cluster.isWorker ? process.ppid ?? process.pid : process.pid,
+			pid: cluster.isWorker ? process.ppid : process.pid,
 			ports,
 			desiredPorts: desired.length > 0 ? desired : void 0,
 			urls
@@ -648,16 +697,22 @@ let HttpKernel = class HttpKernel extends Service {
 	* session (lazy). Remplace l'ancien `sessionAutoStart` global « démarre sur
 	* toutes les routes » (le moteur du ×23).
 	*
+	* Le contrat de retour suit ce qui est réellement attendu : `null` tout de
+	* suite quand aucune session n'est à ouvrir (le cas nominal — ni intent, ni
+	* cookie), la promesse de la session seulement quand le store est interrogé
+	* (#505).
+	*
 	* @param context - contexte HTTP/HTTP2/WS courant.
-	* @returns la session active, ou `null` si la requête n'en requiert aucune.
+	* @returns `null` si la requête n'en requiert aucune ; sinon la promesse de
+	*   la session active.
 	*/
-	async startSession(context) {
+	startSession(context) {
 		if (!this.sessionService) return null;
 		const intent = context.sessionIntent;
 		if (context.security?.stateless === true) {
 			if (intent) {
 				const name = context.security.name;
-				if (this.#statelessIntentVues === null) this.#statelessIntentVues = /* @__PURE__ */ new Set();
+				this.#statelessIntentVues ??= /* @__PURE__ */ new Set();
 				if (!this.#statelessIntentVues.has(name)) {
 					this.#statelessIntentVues.add(name);
 					this.log(`Zone "${name}" is stateless: the session requested by this route is IGNORED (no session opened, no cookie sent). Drop \`stateless: true\` on the area, or stop requiring a session on its routes.`, "WARNING", "SESSION");
@@ -666,36 +721,71 @@ let HttpKernel = class HttpKernel extends Service {
 			return null;
 		}
 		if (!intent && !context.hasSession()) return null;
-		return await this.sessionService.start(context, intent?.readOnly);
+		return this.sessionService.start(context, intent?.readOnly);
 	}
 	/**
-	* Teardown post-réponse — fire-and-forget depuis le `once("close")` posé par
-	* `createHttpContext` (un seul fire possible : once auto-détaché). Loggue la
-	* requête, draine les hooks afterResponse/onFinish, libère le scope DI.
+	* Teardown post-réponse — fire-and-forget depuis l'écouteur `close` posé par
+	* `createHttpContext`. Loggue la requête, draine les hooks
+	* afterResponse/onFinish, libère le scope DI.
+	*
+	* Synchrone dans le cas nominal — aucun hook `onAfterResponse`, aucun écouteur
+	* `onFinish` : rien n'y est attendu (#505). Ne lève et ne rejette jamais —
+	* l'appelant est un écouteur d'événement : une faute est journalisée, et le
+	* scope TOUJOURS libéré.
+	*
+	* @returns `undefined` quand le démontage est terminé ; sinon la promesse de
+	*   sa fin, qui ne rejette pas.
 	*/
-	async teardownHttp(context, scope) {
-		if (context.finished) return;
+	teardownHttp(context, scope) {
+		if (context.finished) return void 0;
 		try {
 			if (context.waitAsync && !context.sended && this.kernel?.environment === "development") this.log(`Action "${context.resolver?.route?.name ?? context.url}" returned a non-renderable value (void/null/class instance) and never sent a response. Use 'return <object|string|number|boolean|Buffer>' (auto-JSON) or send/stream manually.`, "WARNING");
 			context.logRequest();
 			context.logPhasesVerbose();
 			this.profiler?.collect(context);
-			await context._runAfterResponse();
+			const afterResponse = context._runAfterResponse();
+			if (afterResponse !== void 0 || context.listenerCount("onFinish")) return this.finishTeardownHttp(context, scope, afterResponse);
+			this.releaseHttpContext(context, scope);
+		} catch (e) {
+			this.failTeardownHttp(e, context, scope);
+		}
+	}
+	/**
+	* Suite ASYNCHRONE du démontage, quand il y a des hooks à attendre :
+	* `onAfterResponse` puis `onFinish`, avant de libérer le contexte. Ne rejette
+	* jamais (cf {@link teardownHttp}).
+	*/
+	async finishTeardownHttp(context, scope, afterResponse) {
+		try {
+			if (afterResponse !== void 0) await afterResponse;
 			if (context.listenerCount("onFinish")) await context.fireAsync("onFinish", context);
+			this.releaseHttpContext(context, scope);
+		} catch (e) {
+			this.failTeardownHttp(e, context, scope);
+		}
+	}
+	/** Fin d'un contexte HTTP : marqué fini, scope DI libéré, contexte nettoyé. */
+	releaseHttpContext(context, scope) {
+		context.finished = true;
+		if (perfProbe) {
+			const t0 = process.hrtime.bigint();
+			this.container?.leaveScope(scope);
+			perfProbe.leaveScopeNs += Number(process.hrtime.bigint() - t0);
+		} else this.container?.leaveScope(scope);
+		context.clean();
+	}
+	/**
+	* R2 — le démontage est fire-and-forget : un throw (hook onFinish /
+	* afterResponse) serait une erreur non capturée du processus. On journalise,
+	* et on GARANTIT la libération du scope DI (sinon le scope `request` fuit à
+	* chaque hook qui lève).
+	*/
+	failTeardownHttp(e, context, scope) {
+		this.log(e, "ERROR", "TEARDOWN");
+		if (!context.finished) {
 			context.finished = true;
-			if (perfProbe) {
-				const t0 = process.hrtime.bigint();
-				this.container?.leaveScope(scope);
-				perfProbe.leaveScopeNs += Number(process.hrtime.bigint() - t0);
-			} else this.container?.leaveScope(scope);
+			this.container?.leaveScope(scope);
 			context.clean();
-		} catch (e) {
-			this.log(e, "ERROR", "TEARDOWN");
-			if (!context.finished) {
-				context.finished = true;
-				this.container?.leaveScope(scope);
-				context.clean();
-			}
 		}
 	}
 	createHttpContext(scope, request, response, type) {
@@ -708,7 +798,7 @@ let HttpKernel = class HttpKernel extends Service {
 				perfProbe.ctxNs += Number(process.hrtime.bigint() - t0);
 				perfProbe.t0 = 0n;
 			} else context = new HttpContext(scope, request, response, type);
-			response.once("close", () => {
+			response.on("close", () => {
 				if (!response.writableEnded) {
 					context._abortIfPending("Connection closed before response finished");
 					if (!context.sended) context.response.statusCode = 499;
@@ -721,87 +811,176 @@ let HttpKernel = class HttpKernel extends Service {
 			throw e;
 		}
 	}
-	async handleHttp(scope, request, response, type) {
+	/**
+	* Crée le contexte HTTP de la requête et la sert dans sa bulle ALS ; toute
+	* erreur — synchrone ou rejet — passe par {@link onError}.
+	*
+	* Pas `async` : un GET servi par une action synchrone traverse le pipeline
+	* sans une seule promesse (#505). Une promesse seulement quand une étape
+	* attend, ou quand l'erreur est rendue (`onError`).
+	*
+	* @returns le contexte servi, ou sa promesse.
+	*/
+	handleHttp(scope, request, response, type) {
 		let context = null;
 		try {
 			context = this.createHttpContext(scope, request, response, type);
-			if (this.listenerCount("onCreateContext")) await this.fireAsync("onCreateContext", context);
-			context.traceparent = resolveTraceparent(request.headers?.traceparent);
-			const profilerQueries = this.profiler ? [] : null;
-			context.profilerQueries = profilerQueries;
-			context.profiling = profilerQueries !== null;
-			return await RequestContext.run({
-				requestId: context.requestId,
-				scheme: context.scheme,
-				traceparent: context.traceparent,
-				queries: profilerQueries ?? void 0,
-				context
-			}, async () => {
-				if (this.firewall?.handleCors(context) === 204) {
-					context.response.writeHead(204);
-					context.response.end();
-					return context;
-				}
-				context.phaseStart("resolve");
-				context.resolver = this.router ? this.router.resolve(context) : null;
-				context.phaseEnd("resolve");
-				this.firewall?.applySecurityHeaders(context);
-				if (this.serverStatic && context.resolver?.resolve !== true && !context.resolver?.exception && (this.kernel?.options.servers.statics || this.kernel?.options.statics || this.serverStatic.hasMounts())) {
-					response.removeHeader("Content-Type");
-					await this.serverStatic.handle(request, response).catch(() => void 0);
-				}
-				const streamBody = context.resolver?.resolve === true && context.resolver.route?.bodyStream === true;
-				context.phaseStart("parse");
-				try {
-					if (!streamBody) await context.request.initialize();
-				} finally {
-					context.phaseEnd("parse");
-				}
-				const ctx = await this.onRequestEnd(context);
-				if (ctx instanceof Context) {
-					ctx.phaseStart("action");
-					try {
-						return await ctx.handle();
-					} finally {
-						ctx.phaseEnd("action");
-					}
-				}
-				return context;
-			});
+			const created = context;
+			const served = this.listenerCount("onCreateContext") ? this.fireAsync("onCreateContext", created).then(() => this.serveHttpContext(created, scope, request, response)) : this.serveHttpContext(created, scope, request, response);
+			if (!isPromise(served)) return served;
+			return served.catch((e) => this.failHttp(e, created, scope));
 		} catch (e) {
-			return await this.onError(e, context);
+			return this.failHttp(e, context, scope);
 		}
 	}
-	async onRequestEnd(context, error) {
-		if (!context) throw new nodefonyError("Bad context", 500);
+	/**
+	* Traceparent, tampon du profileur, puis le pipeline dans la bulle ALS de la
+	* requête (`RequestContext.run`).
+	*/
+	serveHttpContext(context, scope, request, response) {
+		context.traceparent = resolveTraceparent(request.headers.traceparent);
+		const profilerQueries = this.profiler ? [] : null;
+		context.profilerQueries = profilerQueries;
+		context.profiling = profilerQueries !== null;
+		return RequestContext.run({
+			requestId: context.requestId,
+			scheme: context.scheme,
+			traceparent: context.traceparent,
+			queries: profilerQueries ?? void 0,
+			context,
+			scope
+		}, () => this.runHttpPipeline(context, request, response));
+	}
+	/**
+	* Chemin d'erreur de {@link handleHttp} : libère le scope d'un contexte qui
+	* n'a pas pu se construire, puis rend l'erreur au client (`onError`).
+	*/
+	failHttp(e, context, scope) {
+		if (context === null) this.container?.leaveScope(scope);
+		return this.onError(e, context);
+	}
+	/**
+	* Le trajet d'une requête HTTP DANS la bulle ALS : CORS, calque de
+	* configuration, route, en-têtes de sécurité, repli statique, corps, gardes,
+	* action.
+	*
+	* Chaque étape rend sa valeur, ou une promesse quand elle attend réellement
+	* (préflight à terminer, hook asynchrone, fichier statique, corps à lire,
+	* session, pare-feu, action asynchrone) — et la suite ne s'enchaîne par
+	* `then` que dans ce cas. Un `await` sur une valeur déjà connue suspendait le
+	* pipeline pour rien : ~50 évènements asynchrones par GET (#505).
+	*
+	* @returns le contexte servi, ou la promesse de ce contexte.
+	* @throws l'erreur d'une étape synchrone — {@link handleHttp} la traite comme
+	*   un rejet (même `catch`, même `onError`).
+	*/
+	runHttpPipeline(httpContext, request, response) {
+		if (this.firewall?.handleCors(httpContext) === 204) {
+			httpContext.response.writeHead(204);
+			return thenMaybe(httpContext.response.end(), () => httpContext);
+		}
+		if (this.kernel && this.kernel.listenerCount("onRequestScope") > 0) return this.kernel.fireAsync("onRequestScope", httpContext).then(() => this.routeHttpRequest(httpContext, request, response));
+		return this.routeHttpRequest(httpContext, request, response);
+	}
+	/**
+	* Route, en-têtes de sécurité applicatifs, repli statique — puis le corps.
+	* N'attend que le repli statique, et seulement quand aucune route ne matche.
+	*/
+	routeHttpRequest(httpContext, request, response) {
+		httpContext.phaseStart("resolve");
+		httpContext.resolver = this.router ? this.router.resolve(httpContext) : null;
+		httpContext.phaseEnd("resolve");
+		this.firewall?.applySecurityHeaders(httpContext);
+		if (this.serverStatic && httpContext.resolver?.resolve !== true && !httpContext.resolver?.exception && (asServersConfig(this.kernel?.options.servers)?.statics || this.kernel?.options.statics || this.serverStatic.hasMounts())) {
+			response.removeHeader("Content-Type");
+			return this.serverStatic.handle(request, response).catch(() => void 0).then(() => this.serveHttpRequest(httpContext));
+		}
+		return this.serveHttpRequest(httpContext);
+	}
+	/**
+	* Le corps — lu seulement s'il y en a un à lire —, puis les gardes
+	* ({@link onRequestEnd}) et l'action. Chacun n'est attendu que s'il attend.
+	*/
+	serveHttpRequest(httpContext) {
+		const streamBody = httpContext.resolver?.resolve === true && httpContext.resolver.route?.bodyStream === true;
+		httpContext.phaseStart("parse");
+		const parsed = finallyMaybe(() => streamBody ? void 0 : httpContext.request.initialize(), () => httpContext.phaseEnd("parse"));
+		return thenMaybe(parsed, () => thenMaybe(this.onRequestEnd(httpContext), (guarded) => {
+			guarded.phaseStart("action");
+			return finallyMaybe(() => guarded.handle(), () => guarded.phaseEnd("action"));
+		}));
+	}
+	/**
+	* Les gardes d'une requête HTTP, corps lu : en-têtes de scheme, domaine, hook
+	* `beforeResolve`, armement de la route, CSRF, session, pare-feu — dans cet
+	* ordre.
+	*
+	* Synchrone tant qu'aucune garde n'attend (#505) : le hook `beforeResolve`
+	* n'est attendu que s'il a un écouteur, la session que si la requête en
+	* ouvre une, le pare-feu que sur une zone protégée ou à accès contrôlé.
+	*
+	* @param context - le contexte de la requête.
+	* @param error - une erreur survenue en amont : relevée telle quelle.
+	* @returns le contexte une fois les gardes passées, ou la promesse de ce
+	*   contexte quand une garde attend.
+	* @throws de façon SYNCHRONE l'erreur reçue, l'exception du résolveur (404,
+	*   405…) et le refus CSRF ; un refus du pare-feu ou de session rompt la
+	*   promesse rendue.
+	*/
+	onRequestEnd(context, error) {
 		if (error) throw error;
-		if (this.options[context.scheme].headers) context.response.setHeaders(this.options[context.scheme].headers);
+		const schemeHeaders = context.scheme === "https" ? this.options.https.headers : context.scheme === "http" ? this.options.http.headers : null;
+		if (schemeHeaders) context.response.setHeaders(schemeHeaders);
 		if (this.kernel?.options.domainCheck) this.checkValidDomain(context);
-		if (this.listenerCount("beforeResolve")) await this.fireAsync("beforeResolve", context);
-		await this.prepareFrontController(context);
+		if (this.listenerCount("beforeResolve")) return this.fireAsync("beforeResolve", context).then(() => this.armAndGuard(context));
+		return this.armAndGuard(context);
+	}
+	/**
+	* Suite d'{@link onRequestEnd} : armement de la route, CSRF, session, puis
+	* pare-feu. Synchrone tant que ni la session ni le pare-feu n'attendent.
+	*/
+	armAndGuard(context) {
+		this.prepareFrontController(context);
 		this.firewall?.enforceCsrf(context);
-		await this.startSession(context);
-		if (context.secure || context.isControlledAccess) {
-			context.phaseStart("firewall");
+		return thenMaybe(this.startSession(context), () => context.secure || context.isControlledAccess ? this.runFirewall(context) : context);
+	}
+	/**
+	* Le pare-feu d'une requête en zone protégée : `handleSecurity`, puis les
+	* hooks `afterAuth` (succès) ou `onAuthFailure` (refus, relevé ensuite).
+	*
+	* @returns la promesse du contexte autorisé.
+	* @throws (rejet) le refus du pare-feu, après `onAuthFailure`.
+	*/
+	async runFirewall(context) {
+		context.phaseStart("firewall");
+		try {
 			try {
-				try {
-					await this.firewall?.handleSecurity(context);
-					if (this.listenerCount("afterAuth")) await this.fireAsync("afterAuth", context);
-				} catch (authError) {
-					await this.fireAsync("onAuthFailure", context, authError).catch((e) => this.log(e, "ERROR", "onAuthFailure"));
-					throw authError;
-				}
-			} finally {
-				context.phaseEnd("firewall");
+				await this.firewall?.handleSecurity(context);
+				if (this.listenerCount("afterAuth")) await this.fireAsync("afterAuth", context);
+			} catch (authError) {
+				await this.fireAsync("onAuthFailure", context, authError).catch((e) => this.log(e, "ERROR", "onAuthFailure"));
+				throw authError;
 			}
-			return context;
+		} finally {
+			context.phaseEnd("firewall");
 		}
 		return context;
 	}
 	createWebsocketContext(scope, req, ws, type) {
 		const context = new WebsocketContext(scope, req, ws, type);
-		context.once("onFinish", async (wscontext) => {
-			if (!context) return;
+		context.once("onFinish", () => {
+			this.finishWebsocket(context, scope);
+		});
+		return context;
+	}
+	/**
+	* Teardown d'une connexion WS à sa fermeture : signal d'abandon, hooks
+	* post-réponse, persistance de la session, puis libération du scope.
+	* Ne rejette jamais : toute erreur est journalisée (l'appelant est un
+	* écouteur d'événement synchrone, qui n'attend rien).
+	*/
+	async finishWebsocket(context, scope) {
+		try {
 			if (context.finished) return;
 			context._abortIfPending("WebSocket closed");
 			await context._runAfterResponse();
@@ -810,18 +989,19 @@ let HttpKernel = class HttpKernel extends Service {
 			} catch (e) {
 				this.log(e, "ERROR", "WS onFinish saveSession");
 			}
-			this.container?.leaveScope(wscontext.container);
+			this.container?.leaveScope(scope);
 			context.clean();
 			context.finished = true;
-		});
-		return context;
+		} catch (e) {
+			this.log(e, "ERROR", "WS onFinish");
+		}
 	}
 	async onWebsocketRequest(ws, req, type) {
 		const wsConnCounter = this.#wsConnCounter;
 		if (this.rateLimiter !== null || wsConnCounter !== null) {
-			const ip = resolveForwarded(req.headers, req.socket?.remoteAddress, this.getTrustProxyChecker()).clientIp;
+			const ip = resolveForwarded(req.headers, req.socket.remoteAddress, this.getTrustProxyChecker()).clientIp;
 			if (ip !== null) {
-				if (this.rateLimiter !== null && this.rateLimiter.hit(ip).limited) {
+				if (this.rateLimiter?.hit(ip).limited) {
 					if (ws.readyState === Ws.OPEN) ws.close(1013, "rate limit");
 					return;
 				}
@@ -834,13 +1014,9 @@ let HttpKernel = class HttpKernel extends Service {
 				}
 			}
 		}
-		await this.fireAsync("onServerRequest", req, null, type).catch((e) => {
-			throw e;
-		});
+		await this.fireAsync("onServerRequest", req, null, type);
 		const scope = this.container?.enterScope("request");
-		return this.handleWebsocket(scope, ws, req, type).catch((e) => {
-			throw e;
-		});
+		return this.handleWebsocket(scope, ws, req, type);
 	}
 	async handleWebsocket(scope, ws, req, type) {
 		let context = null;
@@ -852,7 +1028,7 @@ let HttpKernel = class HttpKernel extends Service {
 		}
 		try {
 			if (context) {
-				context.traceparent = resolveTraceparent(req.headers?.traceparent);
+				context.traceparent = resolveTraceparent(req.headers.traceparent);
 				context.profiling = this.profiler !== null;
 			}
 			const wsRunId = context?.requestId ?? "ws-no-ctx";
@@ -862,7 +1038,8 @@ let HttpKernel = class HttpKernel extends Service {
 				requestId: wsRunId,
 				scheme: wsScheme,
 				...wsTrace ? { traceparent: wsTrace } : {},
-				context
+				context,
+				scope
 			}, async () => {
 				await this.onConnect(context, error);
 				if (this.firewall && (context?.secure || context?.isControlledAccess)) {
@@ -922,7 +1099,7 @@ let HttpKernel = class HttpKernel extends Service {
 			throw e;
 		}
 		if (!context.sessionStarting) await this.startSession(context);
-		return await context.connect();
+		return context.connect();
 	}
 	checkValidDomain(context) {
 		if (context.validDomain) return 200;