nodefony 7.0.2 → 10.0.0-alpha.2

package/templates/controller/duplex/nodefony/controllers/__NAME__.ts.tpl

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import {
+  route,
+  controller,
+  Param,
+  Body,
+  Query,
+  HttpCode,
+  Idempotent,
+  CurrentUser,
+<% if (it.hasSecurity) { %>  IsGranted,
+<% } %>} from "@nodefony/framework";
+import { RealtimeController } from "@nodefony/realtime";
+import { HttpError } from "@nodefony/http";
+import type { ContextType } from "@nodefony/http";
+<% if (it.hasSecurity) { %>import type { IUser } from "@nodefony/user";
+<% } %>
+
+/** Forme d'un item — remplace par ton entité (`nodefony create entity`). */
+interface IItem {
+  id: string;
+  name: string;
+  createdAt: number;
+  createdBy: string;
+}
+
+/**
+ * <%= it.nameClass %> — resource **DUPLEX** : les MÊMES actions répondent en
+ * REST (curl/fetch) ET par la **socket Nodefony** via le pont `api.request`
+ * (« API souveraine » : 1 action = N transports, même pipeline — firewall,
+ * idempotence, audit). Deux ingrédients :
+ *
+ *  1. chaque route déclare ses transports — `methods: ["GET", "WEBSOCKET"]`
+ *     (zéro bypass : une action dit à quelles portes elle répond) ;
+ *  2. `realtimeApiRequest()` → `true` (opt-in) : la connexion socket expose la
+ *     méthode RPC `api.request {path}` qui re-route vers l'action.
+ *
+ * ⚠ Zero Trust : dans une zone firewall `security` (ex. `^/api` du manifeste),
+ * le pont exige une identité NON-anonyme — même si la zone accepte l'anonyme en
+ * HTTP (une surface d'invocation WS ne s'ouvre jamais par défaut). Connecte-toi
+ * d'abord (le cookie de session voyage avec le handshake), ou place la route
+ * hors zone pour un accès anonyme assumé.
+ *
+ * Côté client (navigateur OU script Node — la façade est isomorphe, le
+ * subpath `nodefony/client` est sa porte explicite) :
+ * ```ts
+ * import { RealtimeClient } from "nodefony/client";
+ * // URL RELATIVE, résolue contre la page (https → wss automatique) ;
+ * // `.shared()` = UNE socket par URL, partagée par toute la page.
+ * const socket = RealtimeClient.shared({ url: "<%= it.route %>/realtime" });
+ * await socket.connect();
+ * // LECTURE — la même action que `GET <%= it.route %>` :
+ * const items = await socket.request("<%= it.route %>?limit=10");
+ * // MUTATION — méthode HTTP logique + clé d'idempotence OBLIGATOIRE (une
+ * // socket qui reconnecte peut rejouer une frame → la clé dédoublonne) :
+ * const created = await socket.mutate("<%= it.route %>", {
+ *   method: "POST",
+ *   body: { name: "premier" },
+ *   idempotencyKey: crypto.randomUUID(),
+ * });
+ * ```
+ * Et les MÊMES actions au curl :
+ * ```bash
+ * curl -k "https://127.0.0.1:5152<%= it.route %>?limit=10"
+ * curl -k -X POST -H "content-type: application/json" \
+ *   -H "idempotency-key: demo-1" -d '{"name":"premier"}' https://127.0.0.1:5152<%= it.route %>
+ * ```
+ */
+@controller("<%= it.route %>")
+<% if (it.roleGuard) { %>// Habilitation exigée pour TOUT ce controller.
+//
+// Posée sur la CLASSE : chaque action en hérite, y compris celles qu'on
+// ajoutera demain — c'est ce qui distingue une règle d'un rappel. Le refus est
+// rendu par le framework AVANT que le controller ne soit instancié (403), donc
+// aucune ligne de contrôle d'accès n'a sa place dans une action.
+//
+// L'administrateur y a accès sans porter ce rôle : `nodefony.config.ts` le
+// déclare sous `ROLE_ADMIN` dans `roleHierarchy` — administrer, c'est déjà
+// pouvoir tout consulter. Une hiérarchie vaut pour TOUTES les routes gardées par
+// ce rôle, présentes et futures ; lister les rôles un par un sur chaque action ne
+// généralise pas.
+@IsGranted("<%= it.role %>")
+<% } %>class <%= it.nameClass %> extends RealtimeController {
+  /** Store démo en mémoire — remplace par un repository (`create entity`). */
+  static items = new Map<string, IItem>();
+
+  constructor(context: ContextType) {
+    super("<%= it.kebab %>", context);
+  }
+
+  /**
+   * Le PONT (opt-in, défaut `false`) : expose `api.request` sur chaque
+   * connexion socket de ce controller. N'atteint QUE les routes déclarant le
+   * transport `WEBSOCKET` dans leurs `methods`.
+   */
+  protected override realtimeApiRequest(): boolean {
+    return true;
+  }
+
+  /** Handshake de la socket Nodefony (JSON-RPC 2.0) — la porte du pont. */
+  @route("<%= it.kebab %>-realtime", {
+    path: "/realtime",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async realtime(message: string | Buffer | null): Promise<void> {
+    this.handleRealtime(message);
+  }
+
+  /** Liste — `GET <%= it.route %>` OU `socket.request("<%= it.route %>")`. */
+  @route("<%= it.kebab %>-list", {
+    path: "",
+    requirements: { methods: ["GET", "WEBSOCKET"] },
+  })
+  list(@Query("limit") limit?: string) {
+    const max = Math.min(Number(limit) || 50, 200);
+    return [...<%= it.nameClass %>.items.values()].slice(0, max);
+  }
+
+  /** Détail — 404 typée si inconnu (RpcError `data.status: 404` côté socket). */
+  @route("<%= it.kebab %>-get", {
+    path: "/{id}",
+    requirements: { methods: ["GET", "WEBSOCKET"] },
+  })
+  detail(@Param("id") id: string) {
+    const item = <%= it.nameClass %>.items.get(id);
+    if (!item) {
+      throw new HttpError(`item ${id} introuvable`, 404);
+    }
+    return item;
+  }
+
+  /**
+   * Création idempotente par les DEUX portes : en HTTP la clé vient de
+   * l'en-tête `Idempotency-Key`, par la socket elle voyage dans la frame
+   * (`socket.mutate` l'exige) — même dédup, même cache de rejeu. ⚠ Une action
+   * `@Idempotent` RETOURNE son payload BRUT (c'est LUI qui est mémorisé).
+   */
+  @route("<%= it.kebab %>-create", {
+    path: "",
+    requirements: { methods: ["POST", "WEBSOCKET"] },
+  })
+  @HttpCode(201)
+  @Idempotent()
+  create(
+    @Body() payload: { name?: string },
+    @CurrentUser() user?: { identifier?: string },
+  ) {
+    const item: IItem = {
+      id: randomUUID(),
+      name: payload?.name ?? "sans nom",
+      createdAt: Date.now(),
+      createdBy: user?.identifier ?? "anon.",
+    };
+    <%= it.nameClass %>.items.set(item.id, item);
+    return item;
+  }
+
+<% if (it.hasSecurity) { %>  /**
+   * Suppression PROTÉGÉE par rôle — la MÊME garde pour les DEUX portes : en
+   * HTTP `@IsGranted` refuse (403) AVANT l'action ; par la socket, le pont
+   * `api.request` re-traverse le MÊME pipeline (le token du handshake voyage
+   * dans l'ALS) → même refus. En dev, `admin/admin` a le rôle.
+   */
+  @route("<%= it.kebab %>-delete", {
+    path: "/{id}",
+    requirements: { methods: ["DELETE", "WEBSOCKET"] },
+  })
+  @IsGranted("ROLE_ADMIN")
+  destroy(@Param("id") id: string, @CurrentUser() user: IUser) {
+    if (!<%= it.nameClass %>.items.delete(id)) {
+      throw new HttpError(`item ${id} introuvable`, 404);
+    }
+    return { deleted: id, by: user.identifier };
+  }
+<% } else { %>  /** Suppression — `DELETE` HTTP ou `socket.mutate(path, { method: "DELETE", … })`. */
+  @route("<%= it.kebab %>-delete", {
+    path: "/{id}",
+    requirements: { methods: ["DELETE", "WEBSOCKET"] },
+  })
+  destroy(@Param("id") id: string) {
+    if (!<%= it.nameClass %>.items.delete(id)) {
+      throw new HttpError(`item ${id} introuvable`, 404);
+    }
+    return { deleted: id };
+  }
+<% } %>}
+
+export default <%= it.nameClass %>;

package/templates/controller/example/nodefony/controllers/__NAME__.ts.tpl

@@ -0,0 +1,348 @@
+import { randomUUID } from "node:crypto";
+import {
+  route,
+  controller,
+  Controller,
+  Get,
+  Post,
+  Put,
+  Patch,
+  Delete,
+  HttpCode,
+  Header,
+  Redirect,
+  Param,
+  Body,
+  Query,
+  Headers,
+  Cookie,
+  UseSession,
+  Session,
+  Idempotent,
+  UploadedFile,
+  UploadedFiles,
+  // Identité ALS posée par le firewall — marche AUSSI sans @nodefony/security
+  // (injecte alors `undefined`) : le décorateur vient du framework, pas de security.
+  CurrentUser,
+<% if (it.hasSecurity) { %>  IsGranted,
+  RequireScope,
+  CsrfProtect,
+<% } %>} from "@nodefony/framework";
+import { HttpError } from "@nodefony/http";
+import type { ContextType, ICookie, IUploadedFile } from "@nodefony/http";
+<% if (it.hasSecurity) { %>import type { IUser } from "@nodefony/user";
+<% } %>
+/** Forme d'un item — remplace par ton entité (`nodefony create entity`). */
+interface IItem {
+  id: string;
+  name: string;
+  createdAt: number;
+  createdBy: string;
+}
+
+/**
+ * <%= it.nameClass %> — **vitrine des décorateurs Nodefony** (saveur `example`) :
+ * chaque action montre une capacité du pipeline, commentée et testable au curl.
+ * Pour un squelette de PRODUCTION, préfère `--kind rest` (CRUD pur) ou
+ * `--kind duplex` (la même ressource en HTTP ET par la socket Nodefony).
+ *
+ *  - CRUD complet : `@Get`/`@Post`/`@Put`/`@Patch`/`@Delete` + `@Param`/`@Body`/`@Query`
+ *  - Réponse : `@HttpCode`, `@Header`, `@Redirect`
+ *  - Anti double-effet : `@Idempotent` (header `Idempotency-Key`)
+ *  - Session : `@UseSession` + `@Session` (compteur de visites)
+ *  - Requête brute : `@Headers`, `@Cookie`, upload `@UploadedFile(s)`
+ *  - Identité : `@CurrentUser` (utilisateur ALS posé par le firewall)
+<% if (it.hasSecurity) { %> *  - Sécurité : `@IsGranted` (rôles), `@RequireScope` (API keys M2M),
+ *    `@CsrfProtect` (mutations pilotées session)
+<% } else { %> *  - (ajoute `@nodefony/security` pour débloquer `@IsGranted`, `@RequireScope`,
+ *    `@CsrfProtect` — régénère alors cette saveur pour voir les exemples)
+<% } %> *  - WebSocket : echo dans la MÊME classe (un seul pipeline)
+ *
+ *  - Flux BRUT : `@Body({ stream: true })` (gros uploads sans parse en RAM)
+ *
+ * Existent aussi (non générés ici) : `@All`/`@Options`/`@Head`, `@Req`/`@Res`
+ * (objets requête/réponse bruts), `@Anonymous`, `@BypassFirewall` (⚠ réfléchis
+ * avant), `@Domain` (routage par vhost), `@Csp`, `@CsrfExempt`, `@Scope`
+ * (scope DI du controller).
+ *
+ * Essais rapides (zone `^/api` du manifeste : identité résolue, jamais bloquante) :
+ * ```bash
+ * curl -k "https://127.0.0.1:5152<%= it.route %>?page=1&limit=10"
+ * curl -k -X POST -H "content-type: application/json" \
+ *   -H "idempotency-key: demo-1" -d '{"name":"premier"}' https://127.0.0.1:5152<%= it.route %>
+ * # rejoue la MÊME clé → réponse mémorisée (aucun doublon créé)
+ * curl -k -c /tmp/jar -b /tmp/jar https://127.0.0.1:5152<%= it.route %>/session   # ×2 → visits: 2
+ * ```
+ */
+@controller("<%= it.route %>")
+<% if (it.roleGuard) { %>// Habilitation exigée pour TOUT ce controller.
+//
+// Posée sur la CLASSE : chaque action en hérite, y compris celles qu'on
+// ajoutera demain — c'est ce qui distingue une règle d'un rappel. Le refus est
+// rendu par le framework AVANT que le controller ne soit instancié (403), donc
+// aucune ligne de contrôle d'accès n'a sa place dans une action.
+//
+// L'administrateur y a accès sans porter ce rôle : `nodefony.config.ts` le
+// déclare sous `ROLE_ADMIN` dans `roleHierarchy` — administrer, c'est déjà
+// pouvoir tout consulter. Une hiérarchie vaut pour TOUTES les routes gardées par
+// ce rôle, présentes et futures ; lister les rôles un par un sur chaque action ne
+// généralise pas.
+@IsGranted("<%= it.role %>")
+<% } %>class <%= it.nameClass %> extends Controller {
+  /** Stub EN MÉMOIRE volontairement naïf (par process, perdu au restart) —
+   *  branche un repository dès que tu crées ton entité. */
+  static readonly items = new Map<string, IItem>();
+
+  constructor(context: ContextType) {
+    super("<%= it.kebab %>", context);
+  }
+
+  // ── Lecture ────────────────────────────────────────────────────────────────
+
+  /**
+   * `@Query` = querystring typée à la carte ; `@Header` fixe un header de
+   * RÉPONSE déclarativement (ici : cache court côté client).
+   */
+  @Get("")
+  @Header("cache-control", "private, max-age=5")
+  list(@Query("page") page: string, @Query("limit") limit: string) {
+    const p = Math.max(1, Number(page) || 1);
+    const l = Math.min(100, Math.max(1, Number(limit) || 20));
+    const all = [...<%= it.nameClass %>.items.values()];
+    return this.renderJson({
+      page: p,
+      limit: l,
+      total: all.length,
+      items: all.slice((p - 1) * l, p * l),
+    });
+  }
+
+  // ── Mutations ──────────────────────────────────────────────────────────────
+
+  /**
+   * `@Idempotent()` (strict) : la mutation EXIGE un header `Idempotency-Key` —
+   * sans clé → 400 ; rejeu de la MÊME clé → la réponse mémorisée est renvoyée
+   * SANS ré-exécuter (anti double-clic / retry réseau / réplique cross-pod avec
+   * le store redis `NF_IDEMPOTENCY_STORE=redis`) ; même clé + payload différent
+   * → 422. `@HttpCode(201)` force le status de création.
+   *
+   * ⚠ Une action `@Idempotent` doit RETOURNER son payload BRUT (`return item`) :
+   * c'est LUI qui est mémorisé puis rejoué. `renderJson()` enverrait la Response
+   * (structure circulaire) au cache → la mémorisation échouerait.
+   */
+  @Post("")
+  @HttpCode(201)
+  @Idempotent()
+  create(
+    @Body() payload: { name?: string },
+    @CurrentUser() user?: { identifier?: string },
+  ) {
+    const item: IItem = {
+      id: randomUUID(),
+      name: payload?.name ?? "sans nom",
+      createdAt: Date.now(),
+      createdBy: user?.identifier ?? "anon.",
+    };
+    <%= it.nameClass %>.items.set(item.id, item);
+    return item;
+  }
+
+  /** `@Body("name")` = UN champ du body (le reste est ignoré). */
+  @Put("/{id}")
+  update(@Param("id") id: string, @Body("name") name: string) {
+    const item = <%= it.nameClass %>.items.get(id);
+    if (!item) {
+      throw new HttpError(`<%= it.kebab %> ${id} introuvable`, 404, this.context);
+    }
+    if (name !== undefined) {
+      item.name = name;
+    }
+    return this.renderJson(item);
+  }
+
+  /**
+   * `@Patch` = mise à jour PARTIELLE (vs `@Put` remplacement) : seuls les
+   * champs présents dans le body sont appliqués.
+   */
+  @Patch("/{id}")
+  patchItem(@Param("id") id: string, @Body() changes: Partial<Pick<IItem, "name">>) {
+    const item = <%= it.nameClass %>.items.get(id);
+    if (!item) {
+      throw new HttpError(`<%= it.kebab %> ${id} introuvable`, 404, this.context);
+    }
+    Object.assign(item, { name: changes?.name ?? item.name });
+    return this.renderJson(item);
+  }
+
+<% if (it.hasSecurity) { %>  /**
+   * AUTORISATION déclarative — la zone firewall AUTHENTIFIE, `@IsGranted`
+   * DÉCIDE ensuite : anonyme ou simple user → **403** (pas 401), porteur du
+   * rôle → l'action s'exécute. `@CurrentUser()` injecte l'utilisateur de l'ALS
+   * (jamais le credential). Teste : DELETE anonyme → 403 ; loggé `admin` → 200.
+   */
+  @Delete("/{id}")
+  @IsGranted("ROLE_ADMIN")
+  destroy(@Param("id") id: string, @CurrentUser() user: IUser) {
+    if (!<%= it.nameClass %>.items.delete(id)) {
+      throw new HttpError(`<%= it.kebab %> ${id} introuvable`, 404, this.context);
+    }
+    return this.renderJson({ deleted: id, by: user.identifier });
+  }
+
+  /**
+   * `@RequireScope` = autorisation MACHINE-À-MACHINE par scope d'API key
+   * (`Authorization: ApiKey <clé>` — la clé porte ses scopes, cf commande
+   * `nodefony security:apikey:*` et la page API Keys de /nodefony).
+   *
+   * ⚠ Un scope ne bride QUE les jetons machine (clé API / JWT délégué / OAuth) :
+   * une clé sans le scope → 403, mais un HUMAIN (session) ou l'anonyme PASSE —
+   * son autorisation à lui se décide par rôles (`@IsGranted`). Pour une route
+   * exigeante sur les DEUX axes, combine les deux décorateurs.
+   */
+  @Get("/export/all")
+  @RequireScope("<%= it.kebab %>:export")
+  exportAll() {
+    return this.renderJson({
+      exportedAt: Date.now(),
+      items: [...<%= it.nameClass %>.items.values()],
+    });
+  }
+
+  /**
+   * `@CsrfProtect` = anti-CSRF sur mutation pilotée par SESSION (cookie) :
+   * le double-submit est exigé — cookie `csrf-token` (posé par le serveur,
+   * non HttpOnly) REJOUÉ dans l'en-tête `x-csrf-token` — un POST forgé
+   * cross-site sans token → 403. Inutile pour du M2M sans cookie
+   * (`@CsrfExempt` existe pour l'inverse).
+   */
+  @Post("/reset")
+  @UseSession()
+  @CsrfProtect()
+  reset(@Session() session: unknown) {
+    const count = <%= it.nameClass %>.items.size;
+    <%= it.nameClass %>.items.clear();
+    void session; // la session prouve le contexte BFF (cookie) de la mutation
+    return this.renderJson({ cleared: count });
+  }
+
+<% } else { %>  /** DELETE sans garde — ajoute @nodefony/security pour la version gardée par rôle. */
+  @Delete("/{id}")
+  destroy(@Param("id") id: string) {
+    if (!<%= it.nameClass %>.items.delete(id)) {
+      throw new HttpError(`<%= it.kebab %> ${id} introuvable`, 404, this.context);
+    }
+    return this.renderJson({ deleted: id });
+  }
+
+<% } %>  // ── Session / requête brute ───────────────────────────────────────────────
+
+  /**
+   * `@UseSession()` ACTIVE la session sur CETTE action (granularité méthode —
+   * possible aussi au niveau classe) ; `@Session()` injecte l'objet session.
+   * Recharge la page : `visits` s'incrémente, porté par le cookie de session.
+   */
+  @Get("/session")
+  @UseSession()
+  sessionVisits(
+    @Session() session: { get: (k: string) => unknown; set: (k: string, v: unknown) => void },
+  ) {
+    const visits = (Number(session.get("visits")) || 0) + 1;
+    session.set("visits", visits);
+    return this.renderJson({ visits, sessionActive: true });
+  }
+
+  /**
+   * `@Headers("x")` = UN header de requête ; `@Cookie()` = map des cookies
+   * (`@Cookie("nom")` = un seul, objet `{ value }`). Diagnostic sans toucher
+   * aux objets bruts (`@Req()`/`@Res()` existent pour ça).
+   */
+  @Get("/whoami")
+  whoami(
+    @Headers("user-agent") ua: string,
+    @Cookie() cookies: Record<string, ICookie> | undefined,
+    // Identité posée dans l'ALS par le firewall (anonyme = identifier "anon.").
+    @CurrentUser() user?: { identifier?: string; roles?: string[] },
+  ) {
+    return this.renderJson({
+      identifier: user?.identifier ?? null,
+      roles: user?.roles ?? [],
+      userAgent: ua ?? null,
+      cookies: cookies ? Object.keys(cookies) : [],
+    });
+  }
+
+  /** `@UploadedFile()` = 1ᵉʳ fichier multipart ; `@UploadedFiles()` = tous. */
+  @Post("/upload")
+  upload(
+    @UploadedFile() file: IUploadedFile | undefined,
+    @UploadedFiles() files: IUploadedFile[] | undefined,
+  ) {
+    return this.renderJson({
+      received: file?.filename ?? null,
+      count: files?.length ?? 0,
+    });
+  }
+
+  /**
+   * `@Body({ stream: true })` = le pipeline SAUTE le parse (JSON/busboy) et
+   * injecte le FLUX brut (`Readable`) : gros fichiers, proxys, ingestion —
+   * zéro copie en RAM. Ici on compte les octets :
+   * `curl -k -X POST --data-binary @gros.bin https://…<%= it.route %>/ingest`
+   */
+  @Post("/ingest")
+  async ingest(@Body({ stream: true }) body: NodeJS.ReadableStream) {
+    let bytes = 0;
+    await new Promise<void>((resolve, reject) => {
+      body.on("data", (chunk: Buffer) => {
+        bytes += chunk.length;
+      });
+      body.once("end", () => resolve());
+      body.once("error", reject);
+    });
+    return this.renderJson({ ingested: bytes });
+  }
+
+  /** `@Redirect(url, code)` — le retour `{ url }` peut surcharger la cible. */
+  @Get("/latest")
+  @Redirect("/unused", 302)
+  latest() {
+    const last = [...<%= it.nameClass %>.items.keys()].at(-1);
+    return { url: last ? `<%= it.route %>/${last}` : "<%= it.route %>" };
+  }
+
+  /**
+   * `@Param("id")` = segment d'URL `{id}` injecté. Déclarée EN DERNIER des GET :
+   * une route paramétrique déclarée avant capturerait `/session`, `/latest`…
+   */
+  @Get("/{id}")
+  read(@Param("id") id: string) {
+    const item = <%= it.nameClass %>.items.get(id);
+    if (!item) {
+      throw new HttpError(`<%= it.kebab %> ${id} introuvable`, 404, this.context);
+    }
+    return this.renderJson(item);
+  }
+
+  // ── WebSocket — MÊME classe, même pipeline ────────────────────────────────
+
+  /**
+   * Echo WS : `wscat -c wss://127.0.0.1:5152<%= it.route %>/echo`.
+   *
+   * ⚠ WS BRUT = démo du pipeline partagé, pas un modèle. Pour du WS métier
+   * (canaux pub/sub, actions RPC, policies), la bonne couche est la socket
+   * Nodefony : `nodefony create controller <nom> --kind realtime` — ou
+   * `--kind duplex` pour les MÊMES actions REST par la socket.
+   */
+  @route("<%= it.kebab %>-echo", {
+    path: "/echo",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async echo(message: string | Buffer | null) {
+    if (!message) {
+      return this.renderJson({ handshake: true });
+    }
+    return this.renderJson({ echo: message.toString() });
+  }
+}
+
+export default <%= it.nameClass %>;

package/templates/controller/hello/nodefony/controllers/__NAME__.ts.tpl

@@ -0,0 +1,143 @@
+import {
+  route,
+  controller,
+  Controller,
+  CurrentUser,
+  Param,
+<% if (it.roleGuard) { %>  IsGranted,
+<% } %>} from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+
+/**
+ * <%= it.nameClass %> — UN controller, DEUX protocoles (le différenciateur
+ * Nodefony) : HTTP et WebSocket sont co-citoyens du même contexte controller,
+ * même pipeline (firewall, audit, logs).
+ *
+ * Routes montées sous `<%= it.route %>` (couvertes par la zone firewall `^/api`
+ * si tu as gardé le manifeste par défaut : identité résolue, jamais bloquante).
+ *
+ * C'est le MÊME gabarit qui sert le controller d'accueil d'une app neuve et
+ * `nodefony create controller --kind hello` : le premier exemple que tu lis est
+ * donc exactement celui que la commande te régénérera.
+ */
+@controller("<%= it.route %>")
+<% if (it.roleGuard) { %>// Habilitation exigée pour TOUT ce controller.
+//
+// Posée sur la CLASSE : chaque action en hérite, y compris celles qu'on
+// ajoutera demain — c'est ce qui distingue une règle d'un rappel. Le refus est
+// rendu par le framework AVANT que le controller ne soit instancié (403), donc
+// aucune ligne de contrôle d'accès n'a sa place dans une action.
+//
+// L'administrateur y a accès sans porter ce rôle : `nodefony.config.ts` le
+// déclare sous `ROLE_ADMIN` dans `roleHierarchy` — administrer, c'est déjà
+// pouvoir tout consulter. Une hiérarchie vaut pour TOUTES les routes gardées par
+// ce rôle, présentes et futures ; lister les rôles un par un sur chaque action ne
+// généralise pas.
+@IsGranted("<%= it.role %>")
+<% } %>class <%= it.nameClass %> extends Controller {
+  constructor(context: ContextType) {
+    super("<%= it.kebab %>", context);
+  }
+
+  // ── `initialize()` — le constructeur ASYNCHRONE du controller ──────────────
+  // Un `constructor` ne peut pas être `async` : tout ce qui demande un `await`
+  // avant l'action se fait ici. Le hook est optionnel — ne l'écris que si tu en
+  // as besoin.
+  //
+  //   async initialize(): Promise<this> {
+  //     this.setContextJson();                        // format de sortie
+  //     const user = RequestContext.getUser();        // identité déjà résolue
+  //     this.prefs = await this.get("prefs").load(user.identifier);
+  //     return this;
+  //   }
+  //
+  // Quand il tourne :
+  //  • en HTTP — APRÈS le firewall et la garde `@IsGranted` : l'identité est
+  //    résolue, et rien ne s'exécute pour un appelant qui sera rejeté ;
+  //  • en WebSocket — AVANT l'accept du handshake, donc avant le firewall :
+  //    l'identité n'y est PAS encore résolue. C'est en revanche la dernière
+  //    fenêtre pour poser un cookie ou un en-tête sur la réponse de handshake.
+  //    Pour de la mise en place par connexion AUTHENTIFIÉE, fais-la au
+  //    handshake (`echo(null)` ci-dessous), qui lui est post-firewall.
+  //
+  // À ne pas y mettre : une décision d'autorisation (c'est `@IsGranted`, qui
+  // s'évalue avant), ni un travail qu'une seule action sur cinq utilise — il
+  // serait payé par toutes.
+
+  @route("<%= it.kebab %>-index", { path: "<%= it.indexPath %>", method: "GET" })
+  // `@CurrentUser()` injecte l'utilisateur posé dans l'ALS par le firewall.
+  // `identifier` = identifiant fonctionnel ; l'anonyme est un VRAI user
+  // (AnonymousUser, identifier "anon."), jamais null en zone firewall.
+  async index(@CurrentUser() user?: { identifier?: string }) {
+    const authenticated = !!user?.identifier && user.identifier !== "anon.";
+    return this.renderJson({
+      hello: "<%= it.helloName %>",
+      pid: process.pid,
+      who: authenticated ? user!.identifier! : "anonyme",
+    });
+  }
+
+  /**
+   * Une valeur PORTÉE PAR LE CHEMIN — et c'est la seule syntaxe de Nodefony qui
+   * diffère de ce que tu connais ailleurs.
+   *
+   * Le segment variable s'écrit **`{name}`**, entre accolades. `:name` — la
+   * forme d'Express, de Nest et de Fastify — compile, se monte, s'affiche dans
+   * `nodefony inspect routes`… et ne correspond à AUCUNE URL réelle : il est
+   * pris pour un segment littéral. Le symptôme est un 404 sur une route qu'on
+   * VOIT dans le code. (`nodefony doctor` nomme ce cas et rend le chemin
+   * corrigé.)
+   *
+   * La valeur se lit avec `@Param("name")`. Elle arrive aussi en argument
+   * positionnel, dans l'ordre des variables du chemin, mais le décorateur
+   * nomme ce qu'il injecte : il survit à un segment ajouté devant.
+   *
+   * Contraindre le format se fait dans le chemin : `{id}(\d+)` n'accepte que
+   * des chiffres, et `/{slug}?` rend le segment optionnel.
+   */
+  @route("<%= it.kebab %>-greet", { path: "/hello/{name}", method: "GET" })
+  async greet(@Param("name") name: string) {
+    return this.renderJson({ hello: name, pid: process.pid });
+  }
+
+<% if (it.secureRoute) { %>  /**
+   * Route PROTÉGÉE par la zone `secure` (`^/api/secure`, session SEULE — cf
+   * nodefony.config.ts) : sans session, le firewall répond 401 AVANT d'entrer
+   * ici. Le controller peut donc supposer un utilisateur authentifié.
+   *
+   * Elle n'est générée que pour l'app, parce qu'une route protégée n'a de sens
+   * que si une ZONE la couvre — et c'est le manifeste de l'app qui la déclare.
+   * Sous un autre préfixe (`/api/blog/secure/…`), la même méthode serait
+   * ouverte à tous : un exemple qui enseigne le contraire de ce qu'il montre.
+   */
+  @route("<%= it.kebab %>-secure", { path: "/secure/hello", method: "GET" })
+  async secureHello(@CurrentUser() user?: { identifier?: string }) {
+    return this.renderJson({
+      message: `Bonjour ${user?.identifier ?? "?"}`,
+      zone: "secure",
+      pid: process.pid,
+    });
+  }
+
+<% } %>  /**
+   * WebSocket natif : `wscat -c wss://127.0.0.1:5152<%= it.route %>/echo`
+   * puis tape un message — la réponse repasse par le MÊME pipeline.
+   *
+   * ⚠ Cet echo BRUT est une DÉMO du pipeline HTTP/WS partagé, pas un modèle :
+   * pour du WS métier (canaux pub/sub, actions RPC, reconnexion, policies),
+   * génère la bonne couche — `nodefony create controller <nom> --kind realtime`
+   * (socket Nodefony JSON-RPC, côté client `RealtimeClient`/hooks React).
+   */
+  @route("<%= it.kebab %>-echo", {
+    path: "/echo",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async echo(message: string | Buffer | null) {
+    if (!message) {
+      return this.renderJson({ handshake: true });
+    }
+    return this.renderJson({ echo: message.toString() });
+  }
+}
+
+export default <%= it.nameClass %>;