@nodefony/devkit 10.0.0-beta.3 → 10.0.0-beta.5

package/skills/nodefony-dev/SKILL.md

@@ -128,6 +128,11 @@ Elle répond **toujours** — application pas encore construite, terminal sans a
 d'environnement : elle ne lit que des fichiers. Elle le DIT alors (« modules installés », pas
 « chargés ») et renvoie à `inspect modules` pour ce qui est vraiment monté.
 
+**`rg` ou outil MCP ?** Question étroite, format connu (un motif, un fichier) → `rg`, bien moins
+cher. Question ouverte sur l'application qui TOURNE (démarrage sain ? quelle route casse ?) →
+`nodefony_check` (= `nodefony doctor`), `nodefony_observe` : un appel au lieu de plusieurs `rg`,
+et des faits qu'aucun fichier ne porte.
+
 ```bash
 npx nodefony inspect routes --json     # routes réelles (chemin MONTÉ, méthodes, controller)
 npx nodefony inspect services --json   # services enregistrés, et le module qui les porte
@@ -170,9 +175,26 @@ tube, puis remets ton filtre.
 (`npx nodefony ai:mcp` écrit `.mcp.json`) — mêmes réponses, et tes propres modules peuvent publier
 les leurs. La porte est une ROUTE : elle n'existe que serveur démarré, et un client qui la trouve
 éteinte la marque en échec pour toute sa session — démarre l'application D'ABORD, ta session
-ENSUITE. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
+ENSUITE. Aucun serveur ne peut tourner (CI, agent dans un runner) ? Ton client lance lui-même
+`npx nodefony ai:stdio` et lui parle sur l'entrée et la sortie standard : mêmes outils, mais le
+code du démarrage, sans rechargement à chaud ni trafic réel à mesurer. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
 `node_modules/@nodefony/devkit/docs/index.md`.
 
+**Ta tâche est d'OFFRIR les outils de l'application à un agent** (« expose ceci par MCP ») ? Ce
+n'est pas la porte ci-dessus, qui sert l'outillage en développement : c'est une porte de
+l'APPLICATION, et elle se génère — n'écris pas le protocole à la main :
+
+```bash
+npx nodefony create controller mcp --kind mcp                  # porte locale : la machine seulement
+npx nodefony create controller mcp --kind mcp --expose oauth   # production : jeton exigé (401 sans)
+npx nodefony create controller mcp --kind mcp --expose mixte   # outils publics sans jeton, les autres réservés à un scope
+```
+
+Elle naît avec deux outils d'exemple (`nodefony/mcp/mcp-tools.ts`), sa définition
+(`defineMcpGate`, `nodefony/mcp/mcp-gate.ts`) et son test. Ajoute tes outils à la LISTE de la
+porte : elle publie ce qu'elle choisit, rien d'autre. Mode d'emploi :
+`node_modules/@nodefony/ai/docs/mcp.md` § « Monter une porte ».
+
 ### L'environnement : ne devine JAMAIS, demande
 
 ```bash
@@ -344,6 +366,14 @@ ont leur skill, qui part du symptôme : **`nodefony-troubleshoot`**.
   huit, `redis` quatre (`session`, `tokens`, `passkeys`, `idempotency`) : un cache ne garde ni
   comptes ni journal d'audit. Ne promets jamais une parité qui n'existe pas — lis ce champ, et
   `npx nodefony inspect stores` dit où atterrit chaque donnée.
+- **L'entrée d'une route se DÉCLARE — ne la valide pas à la main.** L'option `schema` d'un
+  décorateur de route (`@Post("/posts", { schema: { params, query, body, headers } })`, un schéma Zod
+  par partie) fait valider l'entrée AVANT l'action — **422** qui nomme chaque champ et sa partie, sur
+  HTTP comme par la socket (`api.request`) — et l'action la reçoit typée en UN argument,
+  `input: RouteInput<…>`. Une action à schéma ne prend **aucun** décorateur de paramètre (`@Body`,
+  `@Query`…) : le mélange est refusé au démarrage, qui nomme la route. L'identité se lit par
+  `this.user`. Un corps binaire arrive en octets (`Uint8Array`), un `text/*` en chaîne : un même
+  `z.instanceof(Uint8Array)` vaut pour les deux portes. Doc : `node_modules/@nodefony/framework/docs/decorateurs.md`.
 - **Les violations de contrainte sont DÉJÀ traduites en HTTP — ne les rattrape pas.** Un doublon
   sur une colonne unique ressort en **409**, une donnée qui viole le schéma Zod en **422**, chacun
   avec son corps JSON : le rendu d'erreur lit le code du pilote (`23505`, `ER_DUP_ENTRY`,

package/skills/nodefony-dev/scripts/docs.mjs

@@ -136,7 +136,7 @@ export function docDirectories(root) {
   };
   push(path.join(modules, "nodefony"));
   const scope = path.join(modules, "@nodefony");
-  let entries = [];
+  let entries;
   try {
     entries = readdirSync(scope);
   } catch {
@@ -155,7 +155,7 @@ export function docDirectories(root) {
 function markdownFiles(dir) {
   const out = [];
   const walk = (current) => {
-    let entries = [];
+    let entries;
     try {
       entries = readdirSync(current, { withFileTypes: true });
     } catch {
@@ -300,7 +300,7 @@ export function index(root) {
   const pages = [];
   for (const dir of docDirectories(root)) {
     for (const file of markdownFiles(dir)) {
-      let source = "";
+      let source;
       try {
         source = readFileSync(file, "utf8");
       } catch {

package/skills/nodefony-devops/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: nodefony-devops
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 description: >
-  Exploite CETTE application Nodefony en conteneur : image, compose, frontal, secrets, variables,
-  Kubernetes, Podman. N'enseigne pas Docker — il énonce le CONTRAT d'exploitation, chiffré :
-  quelles sondes elle expose, combien de temps elle draine, quel code de sortie elle rend, sous
-  quel identifiant elle tourne, où elle écrit, ce qui casse quand une variable manque. Sert
-  d'abord à savoir ce qu'il ne faut PAS réécrire. À charger AVANT d'écrire un manifeste, un
-  compose, une étape de déploiement, ou de diagnostiquer un conteneur qui redémarre.
+  Exploite CETTE application Nodefony en conteneur : image, compose, frontal (nginx, HAProxy, h2c,
+  Ingress), secrets, variables, Kubernetes, Podman, nombre de pods. N'enseigne pas Docker — il
+  énonce le CONTRAT d'exploitation, chiffré : sondes, durée du drain, code de sortie, identifiant,
+  dossiers écrits, ce qui casse quand une variable manque. À charger AVANT d'écrire un manifeste,
+  un compose, une configuration de frontal, de dimensionner les pods, ou de diagnostiquer un
+  conteneur qui redémarre.
   Déclencheurs : "déployer mon application en production", "mettre mon app en production",
-  "construire et vérifier l'image", "docker compose", "derrière nginx", "Kubernetes",
-  "mon pod redémarre", "mon pod perd des requêtes", "redéploiement sans coupure",
-  "arrêt gracieux", "readOnlyRootFilesystem", "politique Restricted", "secrets",
-  "mot de passe en production", "variables d'environnement", "Podman", "GitLab CI".
+  "docker compose", "derrière nginx", "derrière HAProxy", "Ingress", "h2c",
+  "ma WebSocket se coupe derrière le proxy", "SSE derrière un proxy", "combien de pods ?", "dimensionner un pod",
+  "plusieurs pods en temps réel", "Kubernetes", "mon pod redémarre", "mon pod perd des requêtes",
+  "arrêt gracieux", "politique Restricted", "secrets", "variables d'environnement", "Podman".
 ---
 
 # nodefony-devops — exploiter cette application
@@ -28,19 +28,21 @@ Tu sais faire du Docker. Ce que tu ne sais pas encore, c'est ce que **cette** ap
 Ce que l'application tient, sans que tu aies rien à coder. Chiffré, parce qu'un ordonnanceur se
 règle avec des nombres.
 
-| Ce que tu veux                    | Ce qu'elle fait                                                                                                                                                        |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Savoir si le process vit**      | `GET /livez` → `200`. Reste à `200` **pendant tout l'arrêt** : un exemplaire qui draine est vivant, le tuer ferait exactement ce qu'on veut éviter.                    |
-| **Savoir s'il peut servir**       | `GET /readyz` → `503` avant d'être prêt, `200` ensuite, et `503` **dès la première milliseconde du SIGTERM**. C'est lui qui te retire du répartiteur.                  |
-| **Ne pas être cru mort à tort**   | Les deux sondes **court-circuitent le pipeline avant la limitation de débit**. Un agent d'ordonnancement limité recevrait `429`, qu'il lirait comme un échec de sonde. |
-| **Un arrêt propre**               | `SIGTERM` → refus des nouvelles requêtes, on laisse finir celles en vol, borné à **15 s**. Sous les 30 s qu'un kubelet accorde par défaut.                             |
-| **Laisser le répartiteur suivre** | Un délai configurable **avant** le début du drain, le temps que ton frontal retire l'exemplaire de sa table.                                                           |
-| **Vérifier que l'arrêt a marché** | Code de sortie **`0`**. Un **`137`** signifie qu'il a été tué : les requêtes en vol sont perdues, à chaque déploiement, **sans une ligne de journal**.                 |
-| **Un utilisateur non root**       | `USER 1000:1000` — **numérique**, donc utilisable tel quel par un `runAsUser`. Un `USER nom` ne l'est pas, et certains ordonnanceurs le refusent.                      |
-| **Des secrets montés**            | **Toute** variable accepte le suffixe `_FILE` : `NF_CSRF_SECRET_FILE=/run/secrets/csrf` lit le contenu du fichier. Secrets Docker **et** Kubernetes.                   |
-| **Identifier l'exemplaire**       | `NF_POD_NAME` — à alimenter depuis `metadata.name`. Elle dérive l'identité d'origine du bus temps réel ; sans elle, plusieurs exemplaires se confondent.               |
-| **Un port**                       | `5151`, déclaré par `EXPOSE`. Au-dessus de 1024, donc aucune capacité privilégiée n'est requise.                                                                       |
-| **Un contrôle de santé natif**    | `HEALTHCHECK` sur `/readyz`, déjà dans l'image.                                                                                                                        |
+| Ce que tu veux                    | Ce qu'elle fait                                                                                                                                                                           |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Savoir si le process vit**      | `GET /livez` → `200`. Reste à `200` **pendant tout l'arrêt** : un exemplaire qui draine est vivant, le tuer ferait exactement ce qu'on veut éviter.                                       |
+| **Savoir s'il peut servir**       | `GET /readyz` → `503` avant d'être prêt, `200` ensuite, et `503` **dès la première milliseconde du SIGTERM**. C'est lui qui te retire du répartiteur.                                     |
+| **Ne pas être cru mort à tort**   | Les deux sondes **court-circuitent le pipeline avant la limitation de débit**. Un agent d'ordonnancement limité recevrait `429`, qu'il lirait comme un échec de sonde.                    |
+| **Un arrêt propre**               | `SIGTERM` → refus des nouvelles requêtes, on laisse finir celles en vol, borné à **15 s**. Sous les 30 s qu'un kubelet accorde par défaut.                                                |
+| **Laisser le répartiteur suivre** | Un délai configurable **avant** le début du drain, le temps que ton frontal retire l'exemplaire de sa table.                                                                              |
+| **Vérifier que l'arrêt a marché** | Code de sortie **`0`**. Un **`137`** signifie qu'il a été tué : les requêtes en vol sont perdues, à chaque déploiement, **sans une ligne de journal**.                                    |
+| **Un utilisateur non root**       | `USER 1000:1000` — **numérique**, donc utilisable tel quel par un `runAsUser`. Un `USER nom` ne l'est pas, et certains ordonnanceurs le refusent.                                         |
+| **Des secrets montés**            | Les variables du catalogue acceptent le suffixe `_FILE` : `NF_CSRF_SECRET_FILE=/run/secrets/csrf` lit le contenu du fichier — URL de base et de cache comprises (`NF_DATABASE_URL_FILE`). |
+| **Identifier l'exemplaire**       | `NF_POD_NAME` — à alimenter depuis `metadata.name`. Elle dérive l'identité d'origine du bus temps réel ; sans elle, plusieurs exemplaires se confondent.                                  |
+| **Un port**                       | `5151`, déclaré par `EXPOSE`. Au-dessus de 1024, donc aucune capacité privilégiée n'est requise.                                                                                          |
+| **HTTP/2 vers un frontal**        | En option, un port **h2c** (HTTP/2 en clair, `5153`) : `NF__APP__SERVERS__H2C__ENABLED=true`. Ni sondes ni WebSocket dessus — elles restent sur `5151`.                                   |
+| **Des WebSocket qui survivent**   | Un battement de cœur ping/pong réclame les sockets mortes ; à l'arrêt, chaque client reçoit `1001` et se reconnecte ailleurs. Le frontal doit tolérer ≥ 300 s d'inactivité.               |
+| **Un contrôle de santé natif**    | `HEALTHCHECK` sur `/readyz`, déjà dans l'image.                                                                                                                                           |
 
 **Où l'application écrit — la question qui décide de tout le reste.** Deux dossiers, et deux
 seulement : **`tmp/`** et **`var/`**. Tout le reste du système de fichiers peut être scellé.
@@ -74,9 +76,14 @@ Ce que l'application ne peut pas deviner. Chacun de ces oublis produit une dégr
 **silencieuse** — pas une erreur, pas une alerte.
 
 - **`NF__HTTP__TRUSTPROXY`** dès qu'un frontal termine le TLS. Sans lui, l'application constate un
-  schéma `http` et **un cookie `__Host-` n'est pas émis** : les sessions ne tiennent plus, sans le
-  moindre message — et toute connexion par mot de passe répond `403`, le secret étant reçu
-  « en clair ». Détail et preuve → [`references/frontal.md`](references/frontal.md).
+  schéma `http` : **toute connexion par mot de passe répond `403`** (le secret est reçu « en
+  clair »), le cookie de session perd son préfixe `__Host-`, et l'adresse cliente devient celle du
+  frontal — donc une vague de reconnexions WebSocket épuise **un seul** quota. Sans le moindre
+  message. Détail et preuve → [`references/frontal.md`](references/frontal.md).
+- **Une inactivité de frontal ≥ 300 s.** Plus courte que le battement, elle coupe des WebSocket et
+  des flux SSE **vivants**. `proxy:generate` la dérive ; un contrôleur d'entrée Kubernetes, non.
+- **Un bus temps réel partagé dès deux exemplaires** : `NF_REALTIME_DRIVER=redis`. Sans lui, un
+  message n'atteint que les clients du pod qui l'émet → [`references/dimensionnement.md`](references/dimensionnement.md).
 - **Deux volumes inscriptibles**, sur `/app/tmp` et `/app/var`, si tu scelles la racine.
 - **Une fenêtre d'arrêt ≥ 30 s**, strictement supérieure au drain de 15 s.
 - **Pas de limite processeur.** Une limite mémoire tue proprement et l'exemplaire redémarre ; une
@@ -88,20 +95,22 @@ Ce que l'application ne peut pas deviner. Chacun de ces oublis produit une dégr
 
 Chaque ligne a la commande qui la **prouve**. Une case cochée sans commande est une supposition.
 
-| #   | Le point                                                  | La preuve                                                                                      |
-| --- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| 1   | L'image se construit                                      | `docker build -t <app> .`                                                                      |
-| 2   | Elle n'embarque **aucun secret**                          | `npx nodefony image:check <app>` — lit les **couches**, pas l'image aplatie (§5)               |
-| 3   | Elle démarre et se déclare prête                          | `docker run -d --name t <app>` puis `curl -fsS localhost:5151/readyz`                          |
-| 4   | Elle s'arrête **proprement**                              | `docker stop t; docker inspect t --format '{{.State.ExitCode}}'` → doit rendre **`0`**         |
-| 5   | Les variables requises sont posées                        | `npx nodefony doctor --env production`                                                         |
-| 6   | Les secrets sont **montés**, pas dans l'environnement     | Suffixe `_FILE` → [`references/secrets.md`](references/secrets.md)                             |
-| 7   | Les migrations passent **avant** les nouveaux exemplaires | `kubectl apply -f deploy/migrate-job.yaml`, attendre la fin                                    |
-| 8   | Le frontal est **dérivé**, pas écrit à la main            | `npx nodefony proxy:generate nginx`                                                            |
-| 9   | Le schéma constaté derrière le frontal est le bon         | Une requête réelle pose un cookie `__Host-` → [`references/frontal.md`](references/frontal.md) |
-| 10  | Un redéploiement ne perd **aucune** requête               | Charge constante pendant un `rollout restart` ; zéro `5xx`                                     |
-| 11  | La racine du conteneur est **scellée**                    | `--read-only` + volumes sur `/app/tmp` et `/app/var`                                           |
-| 12  | Tu sais ce que tu **ne** peux **pas** garantir            | Podman sans privilèges perd l'adresse du client (§7) — à énoncer, pas à masquer                |
+| #   | Le point                                                  | La preuve                                                                                               |
+| --- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1   | L'image se construit                                      | `docker build -t <app> .`                                                                               |
+| 2   | Elle n'embarque **aucun secret**                          | `npx nodefony image:check <app>` — lit les **couches**, pas l'image aplatie (§5)                        |
+| 3   | Elle démarre et se déclare prête                          | `docker run -d --name t <app>` puis `curl -fsS localhost:5151/readyz`                                   |
+| 4   | Elle s'arrête **proprement**                              | `docker stop t; docker inspect t --format '{{.State.ExitCode}}'` → doit rendre **`0`**                  |
+| 5   | Les variables requises sont posées                        | `npx nodefony doctor --env production`                                                                  |
+| 6   | Les secrets sont **montés**, pas dans l'environnement     | Suffixe `_FILE` → [`references/secrets.md`](references/secrets.md)                                      |
+| 7   | Les migrations passent **avant** les nouveaux exemplaires | `kubectl apply -f deploy/migrate-job.yaml`, attendre la fin                                             |
+| 8   | Le frontal est **dérivé**, pas écrit à la main            | `npx nodefony proxy:generate nginx`                                                                     |
+| 9   | Le schéma constaté derrière le frontal est le bon         | Une requête réelle pose un cookie `__Host-` → [`references/frontal.md`](references/frontal.md)          |
+| 10  | Un redéploiement ne perd **aucune** requête               | Charge constante pendant un `rollout restart` ; zéro `5xx`                                              |
+| 11  | Une WebSocket **traverse** le frontal et y survit         | Ouverte à travers lui, muette plus d'une minute : toujours ouverte                                      |
+| 12  | Le nombre de pods et leur mémoire sont **calculés**       | Débit mesuré sur **ton** application → [`references/dimensionnement.md`](references/dimensionnement.md) |
+| 13  | La racine du conteneur est **scellée**                    | `--read-only` + volumes sur `/app/tmp` et `/app/var`                                                    |
+| 14  | Tu sais ce que tu **ne** peux **pas** garantir            | Podman sans privilèges perd l'adresse du client (§7) — à énoncer, pas à masquer                         |
 
 ## 5. Symptôme → cause → correction
 
@@ -112,7 +121,13 @@ Le tableau qu'on lit en urgence.
 | L'exemplaire redémarre en boucle, journaux muets                | La sonde de vivacité tombe avant la fin du démarrage                                                                                              | Sonde de démarrage sur `/readyz`, dimensionnée sur le **pire** cas                                                                                                        |
 | Le conteneur sort en **137** à l'arrêt                          | Il a été tué : la fenêtre d'arrêt est ≤ au drain                                                                                                  | Fenêtre ≥ 30 s (Podman : `--stop-timeout 20`, son défaut est **10 s**)                                                                                                    |
 | Des `5xx` **pendant** chaque déploiement                        | Le répartiteur envoie encore du trafic quand le drain a commencé                                                                                  | Un délai avant drain, et un court arrêt avant terminaison                                                                                                                 |
-| Les sessions ne tiennent pas derrière le frontal                | Schéma constaté `http` → le cookie `__Host-` n'est pas émis                                                                                       | `NF__HTTP__TRUSTPROXY`                                                                                                                                                    |
+| Le cookie de session n'a pas le préfixe `__Host-` en production | Schéma constaté `http` derrière le frontal                                                                                                        | `NF__HTTP__TRUSTPROXY`                                                                                                                                                    |
+| La WebSocket se ferme seule au bout d'une minute                | L'inactivité du frontal est plus courte que le battement                                                                                          | Régénérer le frontal ; sur un contrôleur d'entrée, `proxy-read-timeout` ≥ 300 s → [`references/frontal.md`](references/frontal.md)                                        |
+| Un message temps réel n'arrive qu'à une partie des clients      | Plusieurs exemplaires, bus local : chaque pod ne diffuse qu'à ses propres clients                                                                 | `NF_REALTIME_DRIVER=redis` + `NF_REDIS_URL` → [`references/dimensionnement.md`](references/dimensionnement.md)                                                            |
+| Depuis l'activation de h2c, le pod n'est jamais prêt            | La sonde vise le port h2c (5153), qui refuse HTTP/1.1                                                                                             | Sonder le port HTTP (5151)                                                                                                                                                |
+| Depuis l'activation de h2c, les WebSocket ne s'ouvrent plus     | Le frontal les envoie au port h2c                                                                                                                 | Router `Upgrade: websocket` vers le port HTTP → [`references/frontal.md`](references/frontal.md) §8                                                                       |
+| `DB_SQLITE_FALLBACK` en production alors que la base est posée  | Le nom de la variable est faux d'un caractère, ou le Secret n'est pas monté dans CE conteneur                                                     | `npx nodefony doctor --env production` nomme la variable lue (`NF_DATABASE_URL` ou `NF_DATABASE_URL_FILE`)                                                                |
+| Le pod est tué (`OOMKilled`) avec peu de connexions             | La contre-pression : des clients lents retiennent jusqu'à 4 Mio chacun                                                                            | Baisser `maxBackpressure` sur `websocket` **et** `websocketSecure` → [`references/dimensionnement.md`](references/dimensionnement.md)                                     |
 | Toutes les connexions répondent `403` « doit passer par HTTPS » | Même cause : le mot de passe arrive sur une requête que l'application croit en clair                                                              | `NF__HTTP__TRUSTPROXY` — jamais `allowInsecureCredentials`                                                                                                                |
 | Sortie **78** au démarrage, une clé ou une variable nommée      | Faute de configuration : clé inconnue (ou retirée par une mise à jour), valeur invalide, secret requis absent (`NF_CSRF_SECRET`, `NF_JWT_KEYSET`) | Lire la ligne qui la nomme ; `npx nodefony doctor --env production` annonce AVANT les variables requises (pas `NF_JWT_KEYSET`, exigée seulement si l'app émet des jetons) |
 | Les journaux d'audit montrent tous la **même adresse**          | L'adresse du client n'est pas propagée, ou le frontal n'est pas de confiance                                                                      | `trustProxy` ; en Podman sans privilèges, **c'est irréparable** (§7)                                                                                                      |
@@ -131,21 +146,26 @@ Service et l'Ingress ne le sont pas — tu les écris, et les §1 et §3 te dise
 kubectl apply -f deploy/migrate-job.yaml    # les migrations AVANT les exemplaires
 ```
 
-**Le manifeste rendu est ton modèle : il est conforme à la politique Restricted.** Recopie-en le
-contexte de sécurité dans ton Deployment — c'est le seul endroit du dépôt où il est déjà juste.
+**Le manifeste rendu passe la politique Restricted.** Recopie-en le contexte de sécurité dans ton
+Deployment — sauf son `readOnlyRootFilesystem: false`, juste pour un travail éphémère, pas pour un
+exemplaire qui sert du trafic.
 
-La politique exige six champs. Aucun n'est « fourni par l'image » : ce sont des champs de
-**manifeste**, c'est toi qui les poses. Ce que l'image apporte, c'est de les rendre tous
-satisfaisables :
+Aucun de ces champs n'est « fourni par l'image » : ce sont des champs de **manifeste**, c'est toi
+qui les poses. Ce que l'image apporte, c'est de les rendre satisfaisables :
 
-| Le champ                              | Ce qu'il te coûte                                                                                                                 |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `runAsNonRoot: true`                  | rien                                                                                                                              |
-| `runAsUser` / `runAsGroup` numériques | rien — l'image déclare `USER 1000:1000`, tu reportes `1000`                                                                       |
-| `allowPrivilegeEscalation: false`     | rien                                                                                                                              |
-| `capabilities.drop: ["ALL"]`          | rien — l'application n'écoute qu'au-dessus de 1024                                                                                |
-| `seccompProfile: RuntimeDefault`      | rien — mais **à ne pas oublier** : la politique traite l'**absence** de profil comme une violation, pas comme un défaut permissif |
-| `readOnlyRootFilesystem: true`        | **les deux volumes du §3** — sans eux le conteneur ne démarre pas                                                                 |
+| Le champ                              | Exigé par Restricted ?     | Ce qu'il te coûte                                                                                          |
+| ------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `runAsNonRoot: true`                  | **oui**                    | rien                                                                                                       |
+| `runAsUser` / `runAsGroup` numériques | non nul **s'il est posé**  | rien — l'image déclare `USER 1000:1000`, tu reportes `1000`                                                |
+| `allowPrivilegeEscalation: false`     | **oui**                    | rien                                                                                                       |
+| `capabilities.drop: ["ALL"]`          | **oui**                    | rien — l'application n'écoute qu'au-dessus de 1024                                                         |
+| `seccompProfile: RuntimeDefault`      | **oui**                    | rien — mais la politique traite l'**absence** de profil comme une violation, pas comme un défaut permissif |
+| `readOnlyRootFilesystem: true`        | non — durcissement en plus | **les deux volumes du §3** — sans eux le conteneur ne démarre pas                                          |
+
+**Sondes sur le port HTTP (5151)**, même avec h2c actif. Combien d'exemplaires, quelle mémoire, et
+le bus partagé dès qu'il y en a deux → [`references/dimensionnement.md`](references/dimensionnement.md).
+L'Ingress (ingress-nginx est retiré depuis mars 2026), la Gateway API et leurs délais →
+[`references/frontal.md`](references/frontal.md) §10.
 
 **La base de données n'est pas dans le cluster**, et ça a trois conséquences dures →
 [`references/kubernetes.md`](references/kubernetes.md).
@@ -173,15 +193,16 @@ de la politique, ni l'Ingress, ni un déploiement progressif. Ce qu'il ne prouve
 
 ## 8. Les références
 
-| Fichier                                                | Quand l'ouvrir                                                                          |
-| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| [`references/image.md`](references/image.md)           | Modifier le `Dockerfile` : étages, arguments, bases candidates, ce qui ne se touche pas |
-| [`references/compose.md`](references/compose.md)       | Services, profils, volumes, réseaux, le profil de topologie de production               |
-| [`references/variables.md`](references/variables.md)   | Le catalogue, la grammaire des noms, `_FILE`, **ce qui casse si absent**                |
-| [`references/secrets.md`](references/secrets.md)       | Mots de passe, rotation, couches d'image, ce qui n'entre jamais                         |
-| [`references/frontal.md`](references/frontal.md)       | nginx et haproxy dérivés, TLS, en-têtes, `trustProxy`, `__Host-`                        |
-| [`references/kubernetes.md`](references/kubernetes.md) | Ton Deployment, Restricted, la base administrée                                         |
-| [`references/podman.md`](references/podman.md)         | Les six écarts, et celui qui ne se répare pas                                           |
+| Fichier                                                          | Quand l'ouvrir                                                                             |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| [`references/image.md`](references/image.md)                     | Modifier le `Dockerfile` : étages, arguments, bases candidates, ce qui ne se touche pas    |
+| [`references/compose.md`](references/compose.md)                 | Services, profils, volumes, réseaux, le profil de topologie de production                  |
+| [`references/variables.md`](references/variables.md)             | Le catalogue, la grammaire des noms, `_FILE`, **ce qui casse si absent**                   |
+| [`references/secrets.md`](references/secrets.md)                 | Mots de passe, rotation, couches d'image, ce qui n'entre jamais                            |
+| [`references/frontal.md`](references/frontal.md)                 | nginx et HAProxy dérivés, `trustProxy`, SSE, **h2c**, Envoy, Traefik, Ingress, Gateway API |
+| [`references/kubernetes.md`](references/kubernetes.md)           | Ton Deployment, Restricted, sondes, arrêt, la base administrée                             |
+| [`references/dimensionnement.md`](references/dimensionnement.md) | Combien de pods, quelle mémoire, WebSocket et SSE, plusieurs exemplaires                   |
+| [`references/podman.md`](references/podman.md)                   | Les six écarts, et celui qui ne se répare pas                                              |
 
 ## 9. Passer la main
 

package/skills/nodefony-devops/references/dimensionnement.md

@@ -0,0 +1,122 @@
+# Dimensionner un pod — HTTP, WebSocket, SSE
+
+> **Maintenance** : vérité courante. Éditer en place. Les constantes du §2 se recalent sur la page
+> de performance publiée, jamais de mémoire.
+
+## 1. Le modèle — un process, une boucle, un cœur
+
+Un process Node exécute ton code sur **une seule** boucle d'événements. Ce qui borne un pod n'est
+donc pas le nombre de cœurs de la machine, c'est la part de temps où cette boucle travaille :
+l'**ELU** (_event loop utilization_, de 0 à 1). À ELU 1, le pod ne sert pas plus vite : il met en
+file, et la latence monte.
+
+| Conséquence                                   | Le geste                                                                                                                                                                                                    |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Un pod n'utilise **qu'un cœur** pour ton code | `requests.cpu: "1"`. Davantage ne sert qu'au ramasse-miettes et aux E/S de fond                                                                                                                             |
+| Une **limite** processeur ralentit sans tuer  | pas de `limits.cpu` (voir le §3 de la page principale)                                                                                                                                                      |
+| Monter en charge, c'est **ajouter des pods**  | horizontal, par l'orchestrateur ; `nodefony cluster -w N` n'est que pour une machine sans orchestrateur                                                                                                     |
+| Plusieurs workers dans un pod                 | à éviter : la diffusion `broadcast()` ne touche que les clients du **même** worker, et le cluster Node répartit des **connexions** — avec les rares connexions h2c d'un proxy, un worker peut tout recevoir |
+
+## 2. Les constantes mesurées — un ordre de grandeur, pas ta capacité
+
+Mesurées sur Nodefony **10.0.0**, en **production**, Node 26.10, **un** process, route de banc
+**triviale**, charge de 1 Ko. Chaque débit est ramené à ELU 1 (débit observé ÷ ELU), donc c'est un
+**plafond**. Source et calculateur :
+[peut-on partir en production ?](https://nodefony.github.io/nodefony-core/performance/latest/).
+
+| Constante                                         | Valeur                        | Ce qu'elle dit                                                                        |
+| ------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------- |
+| Tas par socket WebSocket — TLS terminé au frontal | **≈ 10 Ko**                   | le coût d'une connexion **ouverte et muette** ; pente linéaire sur 0 → 800 sockets    |
+| Tas par socket — TLS terminé par Node (`wss`)     | ≈ 12 à 14 Ko                  | mesure non concordante d'un run à l'autre : retenir le haut de la fourchette          |
+| Écho WebSocket 1:1                                | ≈ 35 000 à 46 000 msg/s       | messages reçus **et** renvoyés par seconde, à ELU 1                                   |
+| Diffusion à 100 abonnés                           | ≈ 197 000 livraisons/s        | une livraison = un message remis à un abonné ; c'est elle qui coûte, pas l'émission   |
+| HTTP/1.1, route triviale                          | ≈ 15 000 req/s (TLS ≈ 12 000) | p99 ≈ 0,3 ms à vide — **ton** contrôleur, ta base et tes services dominent ce chiffre |
+| Mémoire au repos (RSS)                            | **à mesurer chez toi**        | dépend des modules chargés ; `docker stats` sur un conteneur prêt et sans trafic      |
+
+🔴 **Ce que ces constantes ne disent pas.** Une route réelle lit une base, signe un jeton, rend une
+vue : elle coûte dix à cent fois la route de banc. Le coût d'un **flux SSE** ouvert n'est pas
+mesuré. Ces nombres servent à vérifier un ordre de grandeur, puis à **mesurer ton application**
+(§5) — jamais à remplir directement un manifeste.
+
+## 3. La formule
+
+Trois plafonds, et le pod est borné par le **premier** atteint :
+
+```text
+pods = max( ⌈ C / C_pod ⌉ , ⌈ M / (D_msg × u) ⌉ , ⌈ R / (D_req × u) ⌉ ) + 1
+
+C      connexions simultanées (WebSocket + flux SSE) au pic
+M      livraisons temps réel par seconde au pic (un message diffusé à N abonnés = N livraisons)
+R      requêtes HTTP par seconde au pic
+D_msg  livraisons/s d'UN pod à ELU 1  — mesurées sur TON application (§5)
+D_req  requêtes/s d'UN pod à ELU 1    — idem
+u      ELU visée : 0,6 — la marge absorbe une rafale et la reconnexion d'un déploiement (§4)
++1     le pod qui draine pendant un déploiement, ou celui qu'on perd
+```
+
+`C_pod` se déduit de la **mémoire** :
+
+```text
+limits.memory ≥ RSS_repos + C_pod × coût_socket + L × maxBackpressure + marge GC (≈ 30 %)
+
+coût_socket      ≈ 10 Ko de tas (§2) + les tampons noyau et TLS, hors tas
+L                clients LENTS simultanés tolérés
+maxBackpressure  file d'envoi par socket avant de jeter : 4 Mio par défaut
+```
+
+> 🔴 **Le terme qui fait exploser la mémoire n'est pas le nombre de sockets, c'est la
+> contre-pression.** Dix mille sockets muettes tiennent en ≈ 100 Mo de tas ; cent clients mobiles
+> qui ne lisent plus, à 4 Mio chacun, en réservent 400. Pour des canaux d'**état** (seul le dernier
+> instantané compte), baisser `maxBackpressure` — et le régler sur `websocket` **et**
+> `websocketSecure`, régler l'un ne règle pas l'autre :
+>
+> ```ts
+> use("@nodefony/http", {
+>   websocket: { maxBackpressure: 262144, backpressureCloseAfterDrops: 50 },
+>   websocketSecure: {
+>     maxBackpressure: 262144,
+>     backpressureCloseAfterDrops: 50,
+>   },
+> });
+> ```
+>
+> Au-delà du solde de refus, le client est fermé en `1013` et se reconnecte de lui-même.
+
+**Exemple.** 20 000 connexions, 2 000 messages/s diffusés à 50 abonnés en moyenne (100 000
+livraisons/s), 300 req/s. Ton application mesure `D_msg = 60 000`, `D_req = 1 500`, RSS au repos
+250 Mo, et tu tolères 200 clients lents avec `maxBackpressure` à 256 Kio :
+
+- mémoire par pod pour 10 000 connexions : 250 + 10 000 × 0,01 + 200 × 0,25 = 400 Mo, + 30 % ≈ **520 Mo** ;
+- connexions : ⌈20 000 / 10 000⌉ = 2 ;
+- temps réel : ⌈100 000 / (60 000 × 0,6)⌉ = 3 ;
+- HTTP : ⌈300 / (1 500 × 0,6)⌉ = 1 ;
+- **pods = 3 + 1 = 4**, `limits.memory: 768Mi`. C'est le temps réel qui dimensionne, pas les connexions.
+
+## 4. Ce qui change dès qu'il y a plus d'un pod
+
+| Fait                                                                                              | Conséquence, et le geste                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Un canal est **local au pod** par défaut                                                          | deux utilisateurs sur deux pods ne se voient pas, **sans erreur**. Bus partagé : `NF_REALTIME_DRIVER=redis` et `NF_REDIS_URL`, plus un `namespace` explicite si le Redis est mutualisé — sinon deux applications se parlent. Le canal doit aussi **demander** à traverser : skill `nodefony-add-realtime-channel` |
+| Chaque exemplaire doit être **identifiable**                                                      | `NF_POD_NAME` depuis `metadata.name` — sans elle, l'identité d'origine du bus se confond entre pods                                                                                                                                                                                                               |
+| Un déploiement **ferme** les WebSocket du pod qui draine (`1001`)                                 | tous ses clients se reconnectent **en même temps** sur les pods restants : `maxUnavailable: 0`, `maxSurge: 1`, et la marge `u = 0,6` du §3                                                                                                                                                                        |
+| La limitation de débit compte **par adresse cliente**                                             | derrière un frontal sans `NF__HTTP__TRUSTPROXY`, tous les clients ont l'adresse du frontal : une vague de reconnexions épuise un seul quota et répond `429` à tout le monde                                                                                                                                       |
+| Une connexion WebSocket **ne migre pas**                                                          | après un ajout de pods, les anciens gardent leurs connexions jusqu'à ce qu'elles se rouvrent : l'équilibre ne revient qu'avec les reconnexions. Côté HAProxy, `balance leastconn` répartit mieux des connexions longues que le tourniquet                                                                         |
+| Le CPU est un mauvais signal de mise à l'échelle pour des connexions longues                      | un pod chargé de sockets muettes a peu de CPU et beaucoup de mémoire. L'application **n'expose aucune métrique Prometheus** : une mise à l'échelle sur le nombre de connexions demande de la produire toi-même                                                                                                    |
+| Chaque connexion est un **descripteur de fichier**, deux à travers un frontal sur la même machine | vérifier `ulimit -n` de l'hôte ou du conteneur avant de viser des dizaines de milliers de connexions par pod                                                                                                                                                                                                      |
+
+## 5. Mesurer TON application — la seule source de `D_msg` et `D_req`
+
+1. **Un pod**, en production (`NODE_ENV=production`), à la taille prévue, avec ses vraies
+   dépendances (base, Redis). Pas de limite processeur.
+2. Une charge qui ressemble au trafic réel : tes routes, tes canaux, tes tailles de message.
+   `h2load` (HTTP/1.1 et h2c avec le même instrument), `k6` ou `artillery` pour le WebSocket.
+3. Monter par paliers jusqu'à ce que le CPU du conteneur plafonne autour d'**un** cœur
+   (`kubectl top pod`, `docker stats`) ou que le p99 décroche : le débit à ce palier est ton plafond.
+4. Rejouer **trois fois** et garder la médiane. Un écart de plus de 10 % entre runs ne tranche
+   rien : le décor bouge (autre charge sur la machine, base froide).
+5. Mesurer la mémoire **à connexions ouvertes et muettes**, par paliers (0, 1 000, 2 000…) : la
+   pente est ton `coût_socket`. Une mesure à un seul point mélange le repos et le coût.
+
+> Le CPU d'un conteneur additionne la boucle, le ramasse-miettes et les fils d'E/S : il surestime
+> un peu l'ELU. C'est sans gravité pour dimensionner — la marge `u = 0,6` le couvre — mais deux
+> mesures ne se comparent qu'avec le même instrument.