@nodefony/framework 10.0.0-alpha.9 → 10.0.0-beta.1

package/README.md

@@ -12,7 +12,10 @@ sert **HTTP et WebSocket dans le même contexte**, nativement.
 
 - **Router** : matching de routes (path + méthode + domaine), `Route.match()`.
 - **Resolver** : résout route → controller → action, injecte les paramètres décorés.
-- **Controller** : classe de base ; cycle `initialize()` → action ; HTTP + WS.
+- **Controller** : classe de base ; cycle `initialize()` → action ; HTTP + WS. Singleton par défaut :
+  une instance partagée par toutes les requêtes, sans état sur `this`, qui ne peut donc pas injecter
+  un service `@injectable({ scope: "request" })` — refusé au démarrage. `@Scope("request")` rend une
+  instance par requête (par connexion en WebSocket). `RealtimeController` est par connexion.
 - **Décorateurs** : `@controller`, `@route`, `@Get/@Post/...`, `@Param/@Body/@Query/@Headers`,
   `@Domain`, etc.
 - **Data plane admin** : `AdminApiController` + `IAdminBroker` (surface `/nodefony/<module>/api/*`).

package/dist/index.js

@@ -87,7 +87,7 @@ let Framework = class Framework extends Module {
 	*    silencieux (le WARNING annonce la dégradation).
 	*/
 	async onKernelBoot() {
-		const configured = this.options?.idempotency?.store ?? AUTO_STORE;
+		const configured = this.options.idempotency.store;
 		let name = configured;
 		let reason = `store explicitement configuré ("${configured}")`;
 		if (name === AUTO_STORE) {
@@ -167,7 +167,7 @@ let Framework = class Framework extends Module {
 			if (!broker.has("kernel")) broker.register(createKernelAdminApi(this.kernel));
 			if (!broker.has("framework")) broker.register(createFrameworkAdminApi(broker, { playground: this.kernel.environment === "development" || Boolean(this.kernel.debug) }));
 			if (this.kernel.syslog && !broker.has("syslog")) {
-				const logDir = path.resolve(process.cwd(), this.kernel.options?.log?.dir ?? "logs");
+				const logDir = path.resolve(process.cwd(), this.kernel.options.log?.dir ?? "logs");
 				broker.register(createSyslogAdminApi(this.kernel.syslog, {
 					logDir,
 					enableFiles: this.kernel.environment !== "production",

package/dist/nodefony/controller/AdminApiController.js

@@ -43,7 +43,7 @@ var AdminApiController = class AdminApiController extends Controller {
 	*/
 	async dispatch(...args) {
 		const { status, headers, body } = await this.runAdmin(args);
-		if (this.context?.type?.startsWith("websocket")) {
+		if (this.context?.type.startsWith("websocket")) {
 			if (status >= 400) {
 				const message = body?.error ?? "admin error";
 				throw new RpcError(message, -32e3, {
@@ -140,14 +140,15 @@ var AdminApiController = class AdminApiController extends Controller {
 		}
 		const als = RequestContext.get();
 		const user = als?.user ?? null;
+		const post = this.queryPost;
 		return {
 			params,
 			query: this.query ?? {},
-			body: als?.body !== void 0 ? als.body : this.queryPost ?? null,
+			body: als?.body !== void 0 ? als.body : post ?? null,
 			user,
 			roles: this.extractRoles(user),
 			requestId: als?.requestId,
-			idempotencyKey: resolveIdempotencyKey(als?.idempotencyKey, this.context?.request?.headers?.["idempotency-key"])
+			idempotencyKey: resolveIdempotencyKey(als?.idempotencyKey, this.context?.request?.headers["idempotency-key"])
 		};
 	}
 	/**

package/dist/nodefony/controller/ApiKeyController.js

@@ -40,7 +40,7 @@ var ApiKeyController = class extends Controller {
 				scopes: body.scopes,
 				expiresInDays: body.expiresInDays
 			});
-			return this.renderJson(created, 201);
+			return await this.renderJson(created, 201);
 		} catch (e) {
 			return this.#renderApiKeyError(e);
 		}

package/dist/nodefony/controller/OAuth2Controller.js

@@ -66,7 +66,7 @@ var OAuth2Controller = class extends Controller {
 		session.set(VERIFIER_KEY, auth.codeVerifier);
 		session.set(PROVIDER_KEY, provider);
 		await session.save();
-		return this.redirect(auth.url, 302);
+		this.redirect(auth.url, 302);
 	}
 	/** Valide `state`, échange le `code`, ouvre la session BFF (302). */
 	async callback(provider) {
@@ -85,26 +85,31 @@ var OAuth2Controller = class extends Controller {
 		const code = this.#queryString("code");
 		const returnedState = this.#queryString("state");
 		const returnedIss = this.#queryString("iss");
-		if (code === null || returnedState === null || typeof expectedState !== "string" || returnedState !== expectedState || expectedProvider !== provider) return this.redirect(failure, 302);
+		if (code === null || returnedState === null || typeof expectedState !== "string" || returnedState !== expectedState || expectedProvider !== provider) {
+			this.redirect(failure, 302);
+			return;
+		}
 		try {
 			const { identifier } = await svc.exchangeAndProvision(provider, code, typeof storedVerifier === "string" ? storedVerifier : null, returnedIss);
 			await flow.establishSessionFor(this.context, identifier, "oauth");
-			return this.redirect(success, 302);
+			this.redirect(success, 302);
+			return;
 		} catch (error) {
 			this.log(`oauth2 callback "${provider}" : ${error.message.slice(0, 200)}`, "WARNING");
-			return this.redirect(failure, 302);
+			this.redirect(failure, 302);
+			return;
 		}
 	}
 	#service() {
 		const svc = this.get("oauth2");
-		return svc && svc.isEnabled() ? svc : null;
+		return svc?.isEnabled() ? svc : null;
 	}
 	#flow() {
 		return this.get("authFlow") ?? null;
 	}
 	/** Lit un paramètre de query string (GET), ou `null`. */
 	#queryString(key) {
-		const v = (this.queryGet ?? {})[key];
+		const v = this.queryGet?.[key];
 		return typeof v === "string" && v.length > 0 ? v : null;
 	}
 };

package/dist/nodefony/controller/SessionAuthController.js

@@ -37,11 +37,11 @@ var SessionAuthController = class extends Controller {
 		const body = this.queryPost ?? {};
 		try {
 			const outcome = await flow.login(this.context, body.username, body.password);
-			if (outcome.status === "mfa_required") return this.renderJson({
+			if (outcome.status === "mfa_required") return await this.renderJson({
 				mfaRequired: true,
 				methods: outcome.methods
 			}, 202);
-			return this.renderJson({ user: outcome.user });
+			return await this.renderJson({ user: outcome.user });
 		} catch (e) {
 			return this.#renderAuthError(e);
 		}
@@ -57,7 +57,7 @@ var SessionAuthController = class extends Controller {
 		const body = this.queryPost ?? {};
 		try {
 			const user = await flow.completeMfaLogin(this.context, body.code);
-			return this.renderJson({ user });
+			return await this.renderJson({ user });
 		} catch (e) {
 			return this.#renderAuthError(e);
 		}

package/dist/nodefony/controller/TokenAuthController.js

@@ -39,7 +39,7 @@ var TokenAuthController = class extends Controller {
 		const body = this.queryPost ?? {};
 		try {
 			const tokens = await svc.issueForCredentials(body.username, body.password, parseScope(body.scope), body.resource);
-			return this.renderJson(tokens);
+			return await this.renderJson(tokens);
 		} catch (e) {
 			return this.#renderAuthError(e);
 		}
@@ -51,7 +51,7 @@ var TokenAuthController = class extends Controller {
 		const body = this.queryPost ?? {};
 		try {
 			const tokens = await svc.refresh(body.refresh_token, body.resource);
-			return this.renderJson(tokens);
+			return await this.renderJson(tokens);
 		} catch (e) {
 			return this.#renderAuthError(e);
 		}

package/dist/nodefony/controller/TotpController.js

@@ -38,14 +38,15 @@ var TotpController = class extends Controller {
 		if (!svc) return this.renderJson({ error: "2FA unavailable" }, 503);
 		const subject = await this.#currentSubject();
 		if (subject === null) return this.renderJson({ error: "Unauthorized" }, 401);
-		const code = (this.queryPost ?? {}).code;
+		const code = this.queryPost?.code;
 		if (typeof code !== "string" || code.length === 0) return this.renderJson({ error: "Invalid code" }, 400);
+		let activation;
 		try {
-			const activation = await svc.confirmEnrollment(subject, code);
-			return this.renderJson(activation);
+			activation = await svc.confirmEnrollment(subject, code);
 		} catch {
 			return this.renderJson({ error: "Invalid or expired code" }, 400);
 		}
+		return this.renderJson(activation);
 	}
 	/** Désactive le 2FA du porteur courant (retire secret + codes). */
 	async disable() {
@@ -66,7 +67,7 @@ var TotpController = class extends Controller {
 	}
 	#service() {
 		const svc = this.get("totp");
-		return svc && svc.isEnabled() ? svc : null;
+		return svc?.isEnabled() ? svc : null;
 	}
 	#flow() {
 		return this.get("authFlow") ?? null;

package/dist/nodefony/controller/WebAuthnController.js

@@ -61,7 +61,7 @@ var WebAuthnController = class extends Controller {
 		if (!challenge) return this.renderJson({ error: "No challenge" }, 400);
 		try {
 			const credential = await svc.verifyRegistration(this.#body().response, challenge, me.username, this.#origin());
-			return this.renderJson({
+			return await this.renderJson({
 				verified: true,
 				credentialId: credential.id
 			});
@@ -106,7 +106,7 @@ var WebAuthnController = class extends Controller {
 		try {
 			const { userId } = await svc.verifyAuthentication(this.#body().response, challenge, this.#origin());
 			const user = await flow.establishSessionFor(this.context, userId, "webauthn");
-			return this.renderJson({
+			return await this.renderJson({
 				verified: true,
 				user
 			});
@@ -143,7 +143,7 @@ var WebAuthnController = class extends Controller {
 	}
 	#service() {
 		const svc = this.get("webauthn");
-		return svc && svc.isEnabled() ? svc : null;
+		return svc?.isEnabled() ? svc : null;
 	}
 	#flow() {
 		return this.get("authFlow") ?? null;
@@ -158,7 +158,7 @@ var WebAuthnController = class extends Controller {
 	}
 	/** Origine HTTP de la requête (validée par le service contre le rpID). */
 	#origin() {
-		const origin = this.context.request?.headers?.origin;
+		const origin = this.context.request?.headers.origin;
 		return typeof origin === "string" ? origin : void 0;
 	}
 	/** Lit le challenge en session puis l'INVALIDE (usage unique, anti-replay). */

package/dist/nodefony/decorators/routerDecorators.js

@@ -118,20 +118,19 @@ function controllers(targets) {
 function controller(prefix) {
 	return function(mycontroller) {
 		mycontroller.prefix = prefix;
-		const metadata = Reflect.getMetadata(metadataKey, mycontroller) || {};
-		if (metadata && Object.keys(metadata).length !== 0) {
+		const metadata = Reflect.getMetadata(metadataKey, mycontroller) ?? {};
+		if (Object.keys(metadata).length !== 0) {
 			let hasMagic = false;
-			for (const name in metadata) {
-				const options = metadata[name];
+			for (const [name, options] of Object.entries(metadata)) {
 				options.prefix = prefix;
 				if (options.host === void 0) {
-					const methodDomain = Reflect.getMetadata(DOMAIN_METHOD_METADATA, mycontroller, options.classMethod);
+					const methodDomain = options.classMethod === void 0 ? void 0 : Reflect.getMetadata(DOMAIN_METHOD_METADATA, mycontroller, options.classMethod);
 					const classDomain = Reflect.getMetadata(DOMAIN_CLASS_METADATA, mycontroller);
 					const domain = methodDomain ?? classDomain;
 					if (domain) options.host = domain;
 				}
 				if (options.bypassFirewall !== true) {
-					const methodBypass = Reflect.getMetadata(BYPASS_FIREWALL_METHOD_METADATA, mycontroller, options.classMethod);
+					const methodBypass = options.classMethod === void 0 ? void 0 : Reflect.getMetadata(BYPASS_FIREWALL_METHOD_METADATA, mycontroller, options.classMethod);
 					const classBypass = Reflect.getMetadata(BYPASS_FIREWALL_CLASS_METADATA, mycontroller);
 					if (methodBypass === true || classBypass === true) options.bypassFirewall = true;
 				}
@@ -184,7 +183,7 @@ function route(name, options) {
 		} catch (error) {
 			filePath = error;
 		}
-		const metadata = Reflect.getMetadata(metadataKey, target.constructor) || {};
+		const metadata = Reflect.getMetadata(metadataKey, target.constructor) ?? {};
 		metadata[name] = {
 			path,
 			filePath,
@@ -205,7 +204,7 @@ function route(name, options) {
 function extractControllerFilePath(stackTrace) {
 	for (const line of stackTrace) {
 		const match = line.match(/\s+at file:\/\/(.*\/controllers?\/.*\.js)/);
-		if (match && match[1]) return match[1];
+		if (match?.[1]) return match[1];
 	}
 }
 const HTTP_CODE_METADATA = "route:httpCode";
@@ -313,7 +312,7 @@ function HttpCode(statusCode) {
 */
 function Header(key, value) {
 	return function(target, propertyKey, descriptor) {
-		const existing = Reflect.getMetadata("route:responseHeaders", target, propertyKey) || {};
+		const existing = Reflect.getMetadata("route:responseHeaders", target, propertyKey) ?? {};
 		existing[key] = value;
 		Reflect.defineMetadata(HEADERS_METADATA, existing, target, propertyKey);
 		return descriptor;
@@ -420,25 +419,31 @@ function BypassFirewall(target, propertyKey, descriptor) {
 	return descriptor;
 }
 /**
-* Déclare le scope d'instanciation d'un controller (V4.3) — pose le statique
-* `scope` de la classe (hérité de `Controller`, défaut `"request"`). Lu par le
-* constructor de `Controller` (`new.target`) et par le `Resolver` : 0 Reflect.
+* Déclare la portée d'instanciation d'un contrôleur — pose le statique `scope`
+* de la classe (hérité de `Controller`, défaut `"singleton"`). Lu par le
+* constructeur de `Controller` (`new.target`) et par le `Resolver` : 0 Reflect.
 *
-* `@Scope("singleton")` : UNE instance partagée par toutes les requêtes
-* (cache kernel-scoped sur le Router, `initialize()` appelé 1× à la création).
-* **Contrat stateless strict** : l'action ne lit/n'écrit AUCUN état par requête
-* sur `this` — tout passe par les arguments décorés (`@Param`/`@Body`…) et les
-* helpers, qui retrouvent la requête courante via l'ALS (V4.1). Un champ muté
-* par requête sur un singleton = data race silencieuse entre deux requêtes
-* concurrentes. Le défaut per-request reste inchangé (0 breaking legacy).
+* `@Scope("request")` : une instance par requête — par CONNEXION en
+* WebSocket. À déclarer quand le contrôleur injecte un service de portée
+* `request` à son constructeur (un singleton qui le tente est refusé au
+* démarrage), prépare chaque requête dans `initialize()`, ou garde un état
+* sur `this`.
+*
+* `@Scope("singleton")` redit le défaut : UNE instance partagée par toutes les
+* requêtes (cache du Router, `initialize()` appelé une fois, à la création).
+* **Contrat sans état** : l'action ne lit ni n'écrit aucun état de requête sur
+* `this` — tout passe par les arguments décorés (`@Param`/`@Body`…) et les
+* helpers, qui retrouvent la requête courante dans l'ALS. Les accesseurs
+* d'état refusent l'écriture, et le développement refuse toute écriture sur
+* un champ.
 *
 * ⚠️ Homonyme : le core `nodefony` exporte aussi `Scope` (le scope DI du
 * `Container`) — celui-ci s'importe depuis `@nodefony/framework`.
 *
 * @example
-* \@Scope("singleton")
-* \@controller("/api/books")
-* class BookController extends ResourceController { ... }
+* \@Scope("request")
+* \@controller("/me")
+* class MeController extends Controller { ... }
 */
 function Scope(scope) {
 	return function(target) {
@@ -517,12 +522,12 @@ function IsGranted(attribute, options) {
 	};
 	return function(target, propertyKey, descriptor) {
 		if (propertyKey === void 0) {
-			const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target) || [];
+			const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target) ?? [];
 			existing.push(clause);
 			Reflect.defineMetadata(SECURITY_CLAUSES_METADATA, existing, target);
 			return target;
 		}
-		const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target, propertyKey) || [];
+		const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target, propertyKey) ?? [];
 		existing.push(clause);
 		Reflect.defineMetadata(SECURITY_CLAUSES_METADATA, existing, target, propertyKey);
 		return descriptor;
@@ -573,12 +578,12 @@ function RequireScope(scope) {
 	const clause = { anyOf: Array.isArray(scope) ? [...scope] : [scope] };
 	return function(target, propertyKey, descriptor) {
 		if (propertyKey === void 0) {
-			const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target) || [];
+			const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target) ?? [];
 			existing.push(clause);
 			Reflect.defineMetadata(SECURITY_SCOPES_METADATA, existing, target);
 			return target;
 		}
-		const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target, propertyKey) || [];
+		const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target, propertyKey) ?? [];
 		existing.push(clause);
 		Reflect.defineMetadata(SECURITY_SCOPES_METADATA, existing, target, propertyKey);
 		return descriptor;
@@ -593,9 +598,9 @@ function mergeCspDirectives(a, b) {
 	const out = {};
 	for (const src of [a, b]) {
 		if (!src) continue;
-		for (const name in src) {
+		for (const [name, values] of Object.entries(src)) {
 			const list = out[name] ??= [];
-			for (const v of src[name]) if (!list.includes(v)) list.push(v);
+			for (const v of values) if (!list.includes(v)) list.push(v);
 		}
 	}
 	return out;
@@ -695,7 +700,7 @@ function Idempotent(options) {
 function paramDecoratorFactory(source) {
 	return function(key) {
 		return function(target, propertyKey, parameterIndex) {
-			const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) || [];
+			const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) ?? [];
 			existing.push({
 				source,
 				key,
@@ -746,11 +751,12 @@ const Query = paramDecoratorFactory("query");
 * ```
 */
 function Body(keyOrOptions) {
-	const isOptions = typeof keyOrOptions === "object" && keyOrOptions !== null;
-	const key = isOptions ? void 0 : keyOrOptions;
-	const stream = isOptions ? keyOrOptions.stream === true : false;
+	const raw = keyOrOptions;
+	const isOptions = typeof raw === "object" && raw !== null;
+	const key = isOptions ? void 0 : raw ?? void 0;
+	const stream = isOptions ? raw.stream === true : false;
 	return function(target, propertyKey, parameterIndex) {
-		const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) || [];
+		const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) ?? [];
 		const meta = {
 			source: "body",
 			key,
@@ -834,7 +840,7 @@ function routeExpectsBodyStream(routeDef) {
 		let flag = false;
 		const ctor = routeDef.controller;
 		const method = routeDef.classMethod;
-		if (ctor && method) flag = (Reflect.getMetadata("route:paramArgs", ctor.prototype, method) || []).some((m) => m.source === "body" && m.stream === true);
+		if (ctor && method) flag = (Reflect.getMetadata("route:paramArgs", ctor.prototype, method) ?? []).some((m) => m.source === "body" && m.stream === true);
 		routeDef.bodyStream = flag;
 	}
 	return routeDef.bodyStream;
@@ -963,7 +969,7 @@ function computeActionMeta(ctor, method) {
 * (pas d'import `Route` → 0 cycle).
 */
 function resolveActionMeta(routeDef) {
-	if (routeDef.actionMeta === void 0) routeDef.actionMeta = computeActionMeta(routeDef.controller, routeDef.classMethod);
+	routeDef.actionMeta ??= computeActionMeta(routeDef.controller, routeDef.classMethod);
 	return routeDef.actionMeta;
 }
 //#endregion

package/dist/nodefony/service/IdempotencyStore.js

@@ -96,7 +96,7 @@ let MemoryIdempotencyStore = class MemoryIdempotencyStore extends Service {
 		const entries = this.entries;
 		if (entries === null) return;
 		const existing = entries.get(key);
-		if (existing === void 0 || existing.kind !== "in-flight") return;
+		if (existing?.kind !== "in-flight") return;
 		entries.set(key, {
 			kind: "done",
 			fingerprint: existing.fingerprint,
@@ -108,8 +108,7 @@ let MemoryIdempotencyStore = class MemoryIdempotencyStore extends Service {
 	abort(key) {
 		const entries = this.entries;
 		if (entries === null) return;
-		const existing = entries.get(key);
-		if (existing !== void 0 && existing.kind === "in-flight") entries.delete(key);
+		if (entries.get(key)?.kind === "in-flight") entries.delete(key);
 	}
 	/**
 	* Borne la taille : purge passive des expirées rencontrées, puis éviction FIFO

package/dist/nodefony/service/router.js

@@ -3,18 +3,21 @@ import { routeExpectsBodyStream } from "../decorators/routerDecorators.js";
 import Resolver from "../src/Resolver.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 { Module, Service, injectable } from "nodefony";
+import { Injector, Module, Service, injectable, isPromise } from "nodefony";
 import { HttpError, isDomainAllowed } from "@nodefony/http";
 //#region nodefony/service/router.ts
 var _Router;
 let routeNoticePromoted = null;
+/**
+* Méthodes que sert une route — lues sur le `methodsSet` COMPILÉ par
+* `Route.compileRequirements`, jamais recalculées depuis la config brute.
+* Deux lectures de la même règle avaient divergé : la route acceptait HEAD
+* (implicite sur GET, RFC 9110 §9.1) quand le `Allow` du 405 l'omettait.
+*/
 function collectSupportedMethods(route) {
-	const set = /* @__PURE__ */ new Set();
-	const m = route.requirements?.methods;
-	if (typeof m === "string") m.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean).forEach((x) => set.add(x));
-	else if (Array.isArray(m)) m.map((s) => String(s).toUpperCase()).forEach((x) => set.add(x));
-	return set;
+	return route.methodsSet ?? NO_METHODS;
 }
+const NO_METHODS = /* @__PURE__ */ new Set();
 const routes = [];
 const serviceName = "router";
 const REG_NON_LITERAL = /[{}*+?()[\]^$|\\]/;
@@ -49,8 +52,7 @@ function invalidateRouteIndex() {
 function buildRouteIndex() {
 	const statics = /* @__PURE__ */ new Map();
 	const dynamics = [];
-	for (let i = 0; i < routes.length; i++) {
-		const route = routes[i];
+	for (const [i, route] of routes.entries()) {
 		const path = route.path;
 		if (path !== void 0 && route.variables.length === 0 && !REG_NON_LITERAL.test(path)) {
 			const key = path.toLowerCase();
@@ -90,23 +92,39 @@ let Router = class Router extends Service {
 	}
 	/**
 	* Retourne l'instance singleton d'une classe controller `@Scope("singleton")`,
-	* en la créant au premier appel via `create`. On cache la **promesse** (pas
-	* l'instance) : N requêtes concurrentes pendant la création (`initialize()`
-	* async) attendent le MÊME travail — jamais deux instances (race de création
-	* éliminée structurellement).
+	* en la créant au premier appel via `create`.
+	*
+	* Tant que la création est en cours (`initialize()` async), c'est la
+	* **promesse** qui est en cache : N requêtes concurrentes attendent le MÊME
+	* travail — jamais deux instances (race de création éliminée
+	* structurellement). Dès que l'instance est prête, elle REMPLACE la promesse :
+	* les requêtes suivantes la reçoivent directement, au lieu d'attendre à
+	* chaque fois une promesse déjà tenue (#505).
 	*
 	* @param ctor - la classe controller (clé du cache).
 	* @param create - fabrique exécutée une seule fois (instantiate + initialize).
-	* @returns la promesse de l'instance partagée.
+	* @returns l'instance partagée quand elle existe — ou que `create` la rend
+	*   sans rien attendre —, sinon la promesse de sa création.
+	* @throws ce que `create` lève de façon synchrone ; rien n'est alors mis en
+	*   cache, la requête suivante recrée.
 	*/
 	getSingletonController(ctor, create) {
-		if (this.singletonControllers == null) this.singletonControllers = /* @__PURE__ */ new Map();
-		let instance = this.singletonControllers.get(ctor);
-		if (!instance) {
-			instance = create();
-			this.singletonControllers.set(ctor, instance);
+		this.singletonControllers ??= /* @__PURE__ */ new Map();
+		const cached = this.singletonControllers.get(ctor);
+		if (cached !== void 0) return cached;
+		const created = create();
+		if (!isPromise(created)) {
+			this.singletonControllers.set(ctor, created);
+			return created;
 		}
-		return instance;
+		const pending = Promise.resolve(created);
+		this.singletonControllers.set(ctor, pending);
+		pending.then((instance) => {
+			if (this.singletonControllers?.get(ctor) === pending) this.singletonControllers.set(ctor, instance);
+		}, () => {
+			if (this.singletonControllers?.get(ctor) === pending) this.singletonControllers.delete(ctor);
+		});
+		return pending;
 	}
 	/**
 	* Résout une route pour un contexte donné.
@@ -138,22 +156,27 @@ let Router = class Router extends Service {
 		let di = 0;
 		while (li < litCount || di < dynCount) {
 			let route;
-			if (li < litCount && (di >= dynCount || literals[li].pos < dynamics[di].pos)) route = literals[li++].route;
+			const literal = literals[li];
+			const candidate = dynamics[di];
+			if (literal !== void 0 && (candidate === void 0 || literal.pos < candidate.pos)) {
+				li++;
+				route = literal.route;
+			} else if (candidate === void 0) break;
 			else {
-				const candidate = dynamics[di++];
+				di++;
 				if (candidate.prefix !== "" && cleanPathLower !== void 0 && !cleanPathLower.startsWith(candidate.prefix)) continue;
 				route = candidate.route;
 			}
 			try {
 				if (resolver.match(route, context, cleanPath)) {
-					if (routeNoticePromoted === null) routeNoticePromoted = this.kernel?.environment !== "production";
+					routeNoticePromoted ??= this.kernel?.environment !== "production";
 					if (routeNoticePromoted) this.log(`Match route : ${route.name}`, "NOTICE");
 					resolver.exception = void 0;
 					routeExpectsBodyStream(route);
 					return resolver;
 				}
 			} catch (e) {
-				this.log(`Match route exception : ${route.name} ${e}`, "DEBUG");
+				this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
 				resolver.exception = e;
 				continue;
 			}
@@ -165,6 +188,14 @@ let Router = class Router extends Service {
 				const servesDomain = !route.hostRegexp || isDomainAllowed(route.hostRegexp, context.domain);
 				if (route.pattern && route.pattern.test(path) && servesDomain) collectSupportedMethods(route).forEach((x) => allowed.add(x));
 			}
+			const servesWebsocket = allowed.delete("WEBSOCKET");
+			if (allowed.size === 0 && servesWebsocket) {
+				context.response?.setHeaders({
+					Upgrade: "websocket",
+					Connection: "Upgrade"
+				});
+				throw new HttpError("Upgrade Required: websocket", 426, context);
+			}
 			if (allowed.size > 0) {
 				const allowHeader = Array.from(allowed).join(", ");
 				const err = new HttpError(`Method ${context.method} Not Allowed`, 405, context);
@@ -219,7 +250,26 @@ let Router = class Router extends Service {
 		invalidateRouteIndex();
 		return routenew;
 	}
+	/**
+	* Enregistre une classe contrôleur pour un module — l'entonnoir UNIQUE : le
+	* décorateur `@controllers` y passe, comme les contrôleurs internes que le
+	* framework enregistre directement (plan d'administration, OAuth,
+	* WebAuthn…).
+	*
+	* C'est donc ICI que se refusent, au démarrage, les fautes de déclaration
+	* qu'un contrôleur ne révélerait qu'à sa première requête : une dépendance
+	* captive (un singleton qui détient un service de portée `request`), et une
+	* portée que sa classe de base n'admet pas (`Controller.assertScope`).
+	*
+	* @param myconstructor - la classe contrôleur.
+	* @param module - le module qui la porte.
+	* @returns la classe, rangée sous `module:Classe`.
+	* @throws BootConfigurationError sur une dépendance captive ou une portée
+	*   refusée — fatale dans tous les environnements.
+	*/
 	static setController(myconstructor, module) {
+		Injector.assertNoCaptiveDependency(myconstructor);
+		myconstructor.assertScope?.();
 		Object.defineProperty(myconstructor.prototype, "module", {
 			value: module,
 			writable: false