@nodefony/framework 10.0.0-beta.5 → 10.0.0-beta.7

package/dist/nodefony/grpc/GrpcController.js

@@ -0,0 +1,138 @@
+import Controller from "../src/Controller.js";
+import { computeActionMeta, getReservedActionNames } from "../decorators/routerDecorators.js";
+import { grpcDeclarationOf } from "./declarations.js";
+import { BootConfigurationError } from "nodefony";
+import { HttpContext } from "@nodefony/http";
+import { GrpcEndpoint, markGrpcRoute } from "@nodefony/http/grpc";
+// nodefony/grpc/GrpcController.ts
+/**
+* Nom de l'action de base, celle que toute route gRPC exécute : elle remet la
+* requête à l'adaptateur. Les gardes, elles, se lisent sur la méthode du
+* contrat.
+*
+* @internal
+*/
+const GRPC_ACTION = "serveGrpc";
+/**
+* Ce que chaque décorateur sans effet en gRPC laisse dans la méta d'action —
+* un refus au démarrage le nomme (ADR-0026 D1, point 5 ; S-grpc-18).
+*/
+function inertDecorators(meta) {
+	const found = [];
+	if (meta.paramsMeta !== null) found.push("@Body/@Param/@Query… (paramètres)");
+	if (meta.schema !== null) found.push("schéma de route");
+	if (meta.sessionIntent !== null) found.push("@UseSession");
+	if (meta.cspDirectives !== null) found.push("@Csp");
+	if (meta.idempotent !== null) found.push("@Idempotent");
+	if (meta.httpCode !== null) found.push("@HttpCode");
+	if (meta.headerEntries !== null) found.push("@Header");
+	if (meta.redirectMeta !== null) found.push("@Redirect");
+	return found;
+}
+/**
+* Classe de base d'un point d'entrée gRPC (ADR-0026 D1), jumelle de
+* `RealtimeController` : marquée par `@GrpcService(Contrat)`, déclarée par
+* `@controllers([...])`. Chaque méthode du contrat est une méthode de la
+* classe, appelée par l'adaptateur Connect avec `(request, HandlerContext)` ;
+* la logique métier vit dans un service injecté.
+*
+* Singleton par défaut : aucune instance par appel, l'adaptateur lie les
+* méthodes une fois. `@Scope("request")` donne une instance par appel.
+*
+* Ce que le framework décide pour chaque méthode, sans code de ta part :
+* - les gardes (`@IsGranted`, `@RequireAuthentication`…) posées sur la
+*   méthode ou la classe s'appliquent ; un refus part en 16
+*   `UNAUTHENTICATED` sans identité, en 7 `PERMISSION_DENIED` sinon ;
+* - `this.user`, l'ALS et la portée `request` valent pendant tout l'appel,
+*   flux compris ;
+* - une `ConnectError` part telle quelle ; une `HttpError` est traduite par
+*   la table de `google/rpc/code.proto` ; toute autre exception devient 13
+*   `INTERNAL`. Dans un flux, la traduction ne vaut qu'avant le premier
+*   message ;
+* - un flux est interrompu en 14 `UNAVAILABLE` à l'arrêt du serveur et en 16
+*   à la révocation de son identité : passer `ctx.signal` à ses sources ;
+* - messages bornés à 4 Mio (section `grpc` de la configuration http).
+*
+* Un décorateur sans effet en gRPC (`@Body`, `@UseSession`, `@Csp`,
+* `@Idempotent`…) sur une méthode du contrat interrompt le démarrage.
+* Guide complet : `docs/grpc.md` du paquet.
+*
+* @example
+* \@GrpcService(GreetService)
+* export class GreetController extends GrpcController {
+*   constructor(context: ContextType) {
+*     super("GreetController", context);
+*   }
+*   greet(request: GreetRequest) {
+*     return { greeting: `Bonjour, ${request.name} !` };
+*   }
+* }
+*
+* @experimental Surface gRPC, ADR-0026 D11.
+*/
+var GrpcController = class extends Controller {
+	/**
+	* Vérifie la déclaration gRPC de la classe et fige ses routes — au
+	* démarrage (`Router.setController`), jamais à la première requête.
+	*
+	* Refuse : une classe sans `@GrpcService` ; une méthode du contrat absente
+	* de la classe ou dont le nom est réservé par le framework ; un décorateur
+	* sans effet en gRPC sur une méthode du contrat (ou sur la classe) — le
+	* refus nomme la méthode et le décorateur.
+	*
+	* Fige ensuite, sur chaque route, la méta d'action lue sur la MÉTHODE DU
+	* CONTRAT (l'action exécutée reste celle de la base) et le corps laissé en
+	* flux : les gardes valent quel que soit l'ordre des décorateurs de classe.
+	*
+	* @throws BootConfigurationError sur une déclaration refusée.
+	*/
+	static assertScope() {
+		const declaration = grpcDeclarationOf(this);
+		if (declaration === void 0) throw new BootConfigurationError(`Contrôleur gRPC « ${this.name} » sans @GrpcService(Contrat) : rien ne dit quel service il sert. Poser @GrpcService sur la classe.`);
+		const typeName = declaration.service.typeName;
+		const reserved = getReservedActionNames();
+		const metas = /* @__PURE__ */ new Map();
+		for (const method of declaration.service.methods) {
+			const name = method.localName;
+			const where = `Service gRPC ${typeName} (« ${this.name} »), méthode « ${name} »`;
+			const owner = name === "serveGrpc" || name === "grpcEndpoint" ? "GrpcController" : reserved.get(name);
+			if (owner !== void 0) throw new BootConfigurationError(`${where} : ce nom est réservé par ${owner}, dont tout contrôleur hérite. Renommer la méthode dans le contrat.`);
+			if (typeof Reflect.get(this.prototype, name) !== "function") throw new BootConfigurationError(`${where} : absente de la classe. Chaque méthode du contrat s'implémente sur son contrôleur.`);
+			const meta = computeActionMeta(this, name);
+			const inert = inertDecorators(meta);
+			if (inert.length !== 0) throw new BootConfigurationError(`${where} : ${inert.join(", ")} sans effet sur un appel gRPC (posé sur la méthode ou sur la classe). Les retirer.`);
+			metas.set(name, meta);
+		}
+		for (const { route, method } of declaration.routes) {
+			const meta = metas.get(method.localName);
+			if (meta === void 0) continue;
+			route.actionMeta = {
+				...meta,
+				bodyStream: true
+			};
+			route.bodyStream = true;
+			markGrpcRoute(route);
+		}
+		Object.defineProperty(this.prototype, "grpcEndpoint", {
+			value: new GrpcEndpoint(declaration.service, { perCall: this.scope !== "singleton" }),
+			configurable: true
+		});
+	}
+	/**
+	* L'action de base de toute route gRPC : remet la requête et la réponse
+	* brutes à l'adaptateur, qui appelle la méthode du contrat et écrit la
+	* réponse. Synchrone, sauf pour un flux dont la session est à sauver : la
+	* promesse de la remise est alors rendue au résolveur, qui en lit l'échec.
+	*
+	* @throws Error quand la classe n'a pas été enregistrée par le routeur, ou
+	*   hors d'une requête HTTP.
+	*/
+	serveGrpc() {
+		const endpoint = this.grpcEndpoint;
+		if (endpoint === void 0) throw new Error(`Contrôleur gRPC « ${this.constructor.name} » non enregistré : le déclarer par @controllers([...]).`);
+		const context = this.context;
+		if (!(context instanceof HttpContext)) throw new Error("Un appel gRPC n'est servi que sur une requête HTTP.");
+		return endpoint.serve(context, this);
+	}
+};
+export { GRPC_ACTION, GrpcController };

package/dist/nodefony/grpc/GrpcService.js

@@ -0,0 +1,75 @@
+import router_default from "../service/router.js";
+import { applyDeclaredRouteOptions } from "../decorators/routerDecorators.js";
+import { GRPC_ACTION } from "./GrpcController.js";
+import { claimGrpcService, declareGrpcService } from "./declarations.js";
+import { BootConfigurationError } from "nodefony";
+import { MethodOptions_IdempotencyLevel } from "@bufbuild/protobuf/wkt";
+// nodefony/grpc/GrpcService.ts
+/**
+* Déclare un contrôleur comme le point d'entrée du service gRPC `service`
+* (le descripteur généré par `buf`, ex. `EchoService` de `echo_pb.ts`).
+*
+* Monte une route littérale du Router par méthode du contrat,
+* `POST /<paquet.Service>/<Méthode>`, plus `GET` pour une méthode déclarée
+* `option idempotency_level = NO_SIDE_EFFECTS` (le GET de Connect). Ces
+* routes passent par tout le pipeline — pare-feu, `@IsGranted`, hôtes
+* virtuels, profileur, liste des routes —, et leurs gardes se lisent sur la
+* méthode du contrat. La classe se déclare ensuite par `@controllers([...])`,
+* comme tout point d'entrée d'un module.
+*
+* Les décorateurs de classe `@Domain` et `@BypassFirewall` se placent SOUS
+* `@GrpcService` (lus au montage des routes, comme sous `@controller`).
+*
+* Le descripteur vient du code généré, jamais écrit à la main : contrat dans
+* `proto/<paquet>/v1/*.proto`, `npx buf generate` vers `nodefony/gen/`, code
+* commité. Les routes répondent sur 5152 (gRPC, gRPC-Web, Connect), 5151
+* (gRPC-Web, Connect : HTTP/1.1, jamais le gRPC natif) et 5153 si h2c est
+* activé. Guide complet : `docs/grpc.md` du paquet.
+*
+* @param service - le descripteur du service.
+* @returns le décorateur de classe.
+* @throws BootConfigurationError quand une autre classe sert déjà ce contrat.
+*
+* @example
+* \@GrpcService(EchoService)
+* export class EchoController extends GrpcController {
+*   constructor(context: ContextType) {
+*     super("EchoController", context);
+*   }
+*   \@IsGranted("ROLE_ECHO")
+*   say(request: SayRequest) {
+*     return { sentence: request.sentence };
+*   }
+* }
+*
+* @experimental Surface gRPC, ADR-0026 D11.
+*/
+function GrpcService(service) {
+	return function(ctor) {
+		const owner = claimGrpcService(service.typeName, ctor.name);
+		if (owner !== null) throw new BootConfigurationError(`@GrpcService(${service.typeName}) sur « ${ctor.name} » : ce service est déjà servi par « ${owner} ». Un contrat n'a qu'un point d'entrée.`);
+		const routes = [];
+		for (const method of service.methods) {
+			const options = {
+				prefix: `/${service.typeName}`,
+				path: `/${method.name}`,
+				constructor: ctor,
+				className: ctor.name,
+				classMethod: GRPC_ACTION,
+				method: method.idempotency === MethodOptions_IdempotencyLevel.NO_SIDE_EFFECTS ? ["POST", "GET"] : "POST"
+			};
+			applyDeclaredRouteOptions(ctor, options, method.localName);
+			const route = router_default.createRoute(`${ctor.name}::${method.localName}`, options);
+			routes.push({
+				route,
+				method
+			});
+		}
+		declareGrpcService(ctor, {
+			service,
+			routes
+		});
+		return ctor;
+	};
+}
+export { GrpcService };

package/dist/nodefony/grpc/declarations.js

@@ -0,0 +1,33 @@
+// nodefony/grpc/declarations.ts
+/**
+* Déclarations par classe contrôleur. Écrite à l'import (`@GrpcService`), lue
+* une fois au démarrage (`GrpcController.assertScope`) : jamais sur le chemin
+* d'un appel.
+*/
+const declarations = /* @__PURE__ */ new WeakMap();
+/**
+* Contrat déjà servi, par nom complet : deux classes qui serviraient le même
+* service monteraient deux fois les mêmes chemins.
+*/
+const servedBy = /* @__PURE__ */ new Map();
+/** @internal */
+function declareGrpcService(ctor, declaration) {
+	declarations.set(ctor, declaration);
+}
+/** @internal */
+function grpcDeclarationOf(ctor) {
+	return declarations.get(ctor);
+}
+/**
+* Retient quelle classe sert un contrat.
+*
+* @returns le nom de la classe qui le servait déjà, ou `null`.
+* @internal
+*/
+function claimGrpcService(typeName, className) {
+	const owner = servedBy.get(typeName);
+	if (owner !== void 0) return owner;
+	servedBy.set(typeName, className);
+	return null;
+}
+export { claimGrpcService, declareGrpcService, grpcDeclarationOf };

package/dist/nodefony/grpc/index.js

@@ -0,0 +1,3 @@
+import { GrpcController } from "./GrpcController.js";
+import { GrpcService } from "./GrpcService.js";
+export { GrpcController, GrpcService };

package/dist/nodefony/service/AdminBroker.js

@@ -1,6 +1,6 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
 import router_default from "./router.js";
 import AdminApiController from "../controller/AdminApiController.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { ADMIN_DEFAULT_ROLE, Service, injectable, resolveAdminRole } from "nodefony";
 // nodefony/service/AdminBroker.ts
 const serviceName = "adminBroker";

package/dist/nodefony/service/IdempotencyStore.js

@@ -1,4 +1,4 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { Service, assertPageQuery, injectable } from "nodefony";
 // nodefony/service/IdempotencyStore.ts
 const serviceName = "idempotencyStore";

package/dist/nodefony/service/router.js

@@ -1,7 +1,7 @@
 import Route from "../src/Route.js";
-import { assertRouteSchemaDeclaration, routeExpectsBodyStream } from "../decorators/routerDecorators.js";
 import Resolver from "../src/Resolver.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import { assertRouteSchemaDeclaration, routeExpectsBodyStream } from "../decorators/routerDecorators.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { BootConfigurationError, Injector, Module, Service, injectable, isPromise, stripTrailingSlashes } from "nodefony";
 import { HttpError, isDomainAllowed } from "@nodefony/http";
 // nodefony/service/router.ts
@@ -173,10 +173,11 @@ let Router = class Router extends Service {
 	*   lieu de `context.request.url` — permet de router un path **porté par un message**
 	*   (WS-RPC `invoke`) vers une action, sans muter l'URL de la connexion (état partagé).
 	*   `undefined` (cas hot path normal) → comportement inchangé.
-	* @param methodOverride - méthode HTTP **logique** à exiger en plus du transport
-	*   WEBSOCKET (pont WS-RPC `api.request` d'une MUTATION) : lève l'ambiguïté
-	*   GET-via-WS / POST-via-WS sur un même chemin (`context.method` = "WEBSOCKET").
-	*   `undefined` (GET/HTTP) → match historique sur `context.method`.
+	* @param methodOverride - méthode HTTP **logique** du pont WS-RPC `api.request`,
+	*   GET compris, exigée en plus du transport WEBSOCKET par la règle du cœur
+	*   `bridgeServesVerb` : un GET n'atteint jamais une action POST du même
+	*   chemin. `undefined` (requête HTTP, ouverture de socket) → match sur
+	*   `context.method`.
 	* @returns un `Resolver` (`.resolve === true` si une route a matché) — ou,
 	*   pour un chemin servi en WebSocket SEULEMENT et demandé en HTTP, un
 	*   `Resolver` dont `exception` porte le `426` (en-têtes `Upgrade` posés) :
@@ -220,8 +221,9 @@ let Router = class Router extends Service {
 					return resolver;
 				}
 			} catch (e) {
-				this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
-				resolver.exception = e;
+				routeMatchLogged ??= this.kernel?.environment !== "production";
+				if (routeMatchLogged) this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
+				resolver.exception = e instanceof Error ? e : new Error(String(e));
 				continue;
 			}
 		}
@@ -239,12 +241,12 @@ let Router = class Router extends Service {
 					Upgrade: "websocket",
 					Connection: "Upgrade"
 				});
-				resolver.exception = new HttpError("Upgrade Required: websocket", 426, context);
+				resolver.exception = HttpError.withoutStack("Upgrade Required: websocket", 426, context);
 				return resolver;
 			}
 			if (allowed.size > 0) {
 				const allowHeader = Array.from(allowed).join(", ");
-				const err = new HttpError(`Method ${context.method} Not Allowed`, 405, context);
+				const err = HttpError.withoutStack(`Method ${context.method} Not Allowed`, 405, context);
 				const methodErr = err;
 				methodErr.allow = allowHeader;
 				methodErr.type = "method";
@@ -349,11 +351,12 @@ Router = _Router = __decorate([injectable()], Router);
 * installées du framework feraient échouer `instanceof` en silence. Une
 * lecture de propriété.
 *
-* @param router - le routeur lu sur le contexte (`context.router`).
+* @param router - le routeur lu sur le contexte (`context.router`) ou le
+*   service `router` du conteneur.
 * @returns `true` si c'est le Router du framework.
 */
 function isFrameworkRouter(router) {
-	return router != null && FRAMEWORK_ROUTER in router;
+	return typeof router === "object" && router !== null && FRAMEWORK_ROUTER in router;
 }
 var router_default = Router;
 export { FRAMEWORK_ROUTER, router_default as default, isFrameworkRouter };