@nodefony/framework 10.0.0-beta.4 → 10.0.0-beta.6

package/docs/controller.md

@@ -306,7 +306,7 @@ class ChatController extends Controller {
 | Nombre d'appels d'action | 1 | 1 au handshake (`WebsocketContext.handle()`, `WebsocketContext.ts#WebsocketContext.handle`) + 1 par frame (`handleMessage()`, `WebsocketContext.ts#WebsocketContext.handleMessage`) |
 | Argument de l'action | Variables de route (ou paramètres décorés) | Idem + **le message** en dernier argument (`WebsocketContext.ts#WebsocketContext.handleMessage`) |
 | Rendu d'un `return` | Corps de la réponse | Frame envoyée sur la socket |
-| Échec | Statut HTTP + corps d'erreur | **Code de fermeture** RFC 6455 (401/403 → 1008, 5xx → 1011, autre → 4004) ; chemin sans route WebSocket → **404 HTTP avant l'ouverture** |
+| Échec | Statut HTTP + corps d'erreur | **Au handshake** : une garde refusée répond par un **statut HTTP** (401/403) **avant l'ouverture** (`Resolver.authorizeAction()`, `Resolver.ts#Resolver.authorizeAction`), chemin sans route WebSocket → **404** ; **après l'ouverture** : un **code de fermeture** RFC 6455 (401/403 → 1008, 5xx → 1011, autre → 4004) |
 | `initialize()` | Singleton : **une fois**, à la création · `@Scope("request")` : à chaque requête | Singleton : une fois, à la création · `@Scope("request")` : **une fois par connexion**, au handshake |
 
 La réutilisation de l'instance vient du cache posé sur le container du contexte
@@ -415,14 +415,14 @@ de ce que tu as retourné :
 | Un `number` / un `boolean` | Auto-JSON scalaire (RFC 8259 §2 : `42`, `true` sont des documents valides) | `Resolver.ts#Resolver._callWithIdempotency` |
 | Un `Buffer` | Envoyé brut | `Resolver.ts#Resolver.returnController` |
 | Une `Response` (via un `render*`) | Retournée telle quelle — l'envoi a déjà eu lieu | `Resolver.ts#Resolver._invokeAction` |
-| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `NO_BODY_STATUS` (`Resolver.ts#NO_BODY_STATUS`) |
+| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `isContentlessStatus` (`Response.ts#isContentlessStatus`, `@nodefony/http`) |
 | `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts#Resolver.returnController` |
 | Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts#Resolver.returnController` |
 
 > [!WARNING]
 > **Le piège n° 1 : `return null` sur un statut à corps.** Le framework l'interprète comme « je
 > répondrai moi-même » et attend — jusqu'au timeout. La distinction se fait sur le **statut** :
-> `NO_BODY_STATUS` (`Resolver.ts#NO_BODY_STATUS`) contient 204, 205 et 304. Donc un `@Delete` qui fait
+> `isContentlessStatus` (`Response.ts#isContentlessStatus`, liste unique de `@nodefony/http`) rend vrai pour 204, 205 et 304. Donc un `@Delete` qui fait
 > `@HttpCode(204)` puis `return null` répond bien 204 vide ; le même `return null` sans `@HttpCode`
 > laisse la requête pendue.
 
@@ -463,8 +463,10 @@ Deux besoins distincts, deux helpers.
 ### Téléchargement — `renderFileDownload()`
 
 `renderFileDownload(file, options?, headers?)` (`Controller.ts#Controller.renderFileDownload`) pose
-`Content-Disposition: attachment`, `Content-Length`, le type MIME du fichier, puis délègue au moteur
-de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts#Controller.getFileAsync`) ;
+`Content-Disposition: attachment`, `Content-Length`, le type MIME du fichier et un `Expires` déjà
+passé, puis délègue au moteur de flux. Un nom de fichier accentué ou porteur de `"` part en
+`filename*` UTF-8, précédé d'un repli ASCII (RFC 6266 §4.3, RFC 8187) — un nom quelconque ne fait
+jamais lever la réponse. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts#Controller.getFileAsync`) ;
 la variante synchrone `getFile()` existe encore mais est marquée obsolète — elle appelle `lstatSync`
 et gèle le process le temps du stat.
 
@@ -473,25 +475,136 @@ et gèle le process le temps du stat.
 `renderMediaStream(file, headers?, options?)` (`Controller.ts#Controller.renderMediaStream`) implémente les **requêtes par
 plage** (RFC 9110 §14), ce qui permet à un lecteur vidéo de sauter dans le flux :
 
-| Le client envoie…                             | Réponse                                                         |
-| --------------------------------------------- | --------------------------------------------------------------- |
-| Pas de `Range`                                | 200 + fichier complet, `Accept-Ranges: bytes`                   |
-| `Range: bytes=0-499`                          | **206** + `Content-Range`, bornes clampées à la taille réelle   |
-| `Range: bytes=-500` (suffixe)                 | 206 sur les 500 derniers octets                                 |
-| Plage hors fichier                            | **416** + `Content-Range: bytes */<taille>` (RFC 9110 §15.5.17) |
-| Syntaxe invalide, multi-plage, unité inconnue | En-tête **ignoré** → 200 complet (jamais un 500)                |
+| Le client envoie…                                | Réponse                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| Pas de `Range`                                   | 200 + fichier complet, `Accept-Ranges: bytes`                   |
+| `Range: bytes=0-499`                             | **206** + `Content-Range`, bornes clampées à la taille réelle   |
+| `Range: bytes=-500` (suffixe)                    | 206 sur les 500 derniers octets                                 |
+| Plage hors fichier                               | **416** + `Content-Range: bytes */<taille>` (RFC 9110 §15.5.17) |
+| Syntaxe invalide, multi-plage, unité inconnue    | En-tête **ignoré** → 200 complet (jamais un 500)                |
+| `HEAD` avec `Range`                              | `Range` **ignoré** : en-têtes du GET complet (RFC 9110 §14.2)   |
+| `If-Range` égal à l'`ETag` ou au `Last-Modified` | 206 : la reprise est sûre, le fichier n'a pas changé            |
+| `If-Range` différent, ou étiquette faible        | `Range` **ignoré** → 200 complet (RFC 9110 §13.1.5)             |
+
+Une condition `If-Range` fausse sert le fichier entier — plutôt qu'une plage d'un fichier qui a
+changé, que le client recollerait à l'ancienne. Seuls un `ETag` FORTEMENT égal, ou une date égale
+à un `Last-Modified` vieux d'au moins une seconde, autorisent la reprise.
 
 La logique est isolée dans une fonction pure exportée, `parseByteRange()` (`Controller.ts#parseByteRange`) —
 donc testable sans serveur.
 
 ### Ce que `streamFile()` garantit
 
-`streamFile()` (`Controller.ts#Controller.streamFile`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
-**nettoyage** : le flux est ouvert avec `autoClose: false`, et un client qui raccroche en plein
-téléchargement laisserait sinon un descripteur de fichier ouvert et une promesse pendue à jamais. Un
-écouteur `close` sur la réponse détruit le flux, ce qui déclenche la fermeture du descripteur et
-résout la promesse (`Controller.ts#Controller.streamFile`), puis se retire lui-même (`Controller.ts#Controller.streamFile`). Un
-téléchargement interrompu ne coûte donc **rien** en ressource retenue.
+`streamFile()` (`Controller.ts#Controller.streamFile`) est le moteur commun, et il repose sur le
+même cycle de vie que `renderStream()` ci-dessous (`HttpContext.openStream`) :
+
+- **la réponse est prise à l'appel**, les en-têtes partent au premier morceau ;
+- **un client qui raccroche détruit le flux**, donc ferme le descripteur : un téléchargement
+  interrompu ne retient rien ;
+- **un fichier illisible à l'ouverture** (`EACCES`) rend la page d'erreur ordinaire, 500 ; une
+  lecture qui échoue en route coupe la connexion, jamais une fin propre ;
+- **la longueur annoncée est tenue** : la lecture est bornée à la taille relevée (un fichier qui
+  grossit pendant l'envoi n'envoie pas plus que `Content-Length`), et un extrait `start`/`end`
+  annonce sa propre longueur ;
+- **un fichier n'est pas un flux vivant** : ni `X-Accel-Buffering: no`, ni délai d'inactivité.
+
+### Requêtes conditionnelles — 304, 412, reprise
+
+Les trois helpers posent sur le fichier ENTIER une `ETag` forte et un `Last-Modified`, tirés de sa
+taille et de sa date de modification, sans le lire. Les préconditions sont évaluées dans l'ordre de
+RFC 9110 §13.2.2, AVANT d'ouvrir le fichier (`conditionalRequest.ts#evaluatePreconditions`) :
+
+| Le client envoie…                                            | Réponse                                     |
+| ------------------------------------------------------------ | ------------------------------------------- |
+| `If-None-Match` égal (comparaison faible), ou `*`            | **304** en GET/HEAD, sans corps ; 412 sinon |
+| `If-Modified-Since` ≥ date du fichier (sans `If-None-Match`) | **304** en GET/HEAD                         |
+| `If-Match` différent (comparaison forte)                     | **412** `Precondition Failed`               |
+| `If-Unmodified-Since` < date du fichier (sans `If-Match`)    | **412**                                     |
+
+Le 304 porte ce qu'aurait porté le 200 : `ETag`, `Last-Modified`, `Cache-Control`, `Expires`,
+`Vary` (RFC 9110 §15.4.5). Le helper rend alors `null` : aucun fichier n'a été ouvert.
+
+**`Cache-Control: private, no-cache` par défaut.** Sans lui, `Last-Modified` rendrait la réponse
+« heuristiquement cacheable » (RFC 9111 §4.2.2) : un cache partagé pourrait garder le fichier et le
+resservir sans redemander — or un fichier servi par une action est le plus souvent protégé.
+`private` ferme les caches partagés, `no-cache` fait revalider avant chaque réutilisation, ce qui
+ne coûte qu'un 304. Un fichier public fixe le sien :
+
+```ts
+return this.renderMediaStream(file, {
+  "Cache-Control": "public, max-age=3600",
+});
+```
+
+Une `ETag` ou un `Last-Modified` passés dans les en-têtes (un hachage du contenu, une version)
+remplacent ceux du fichier ET servent à la comparaison. Un extrait `streamFile(f, h, { start, end })`
+n'est pas la représentation entière : il ne reçoit ni validateur ni évaluation.
+
+**Ce que l'application peut changer** :
+
+| Besoin                                                | Geste                                                                      |
+| ----------------------------------------------------- | -------------------------------------------------------------------------- |
+| Un autre `Cache-Control` (fichier public, `no-store`) | le passer dans les en-têtes, ou `@Header("Cache-Control", …)` sur l'action |
+| Sa propre `ETag` (hachage du contenu, version)        | la passer dans les en-têtes, ou `@Header("ETag", …)` — elle sert au 304    |
+| Aucun validateur, aucun 304, aucun `Cache-Control`    | `{ validators: false }` dans les options                                   |
+| Le défaut de toute l'application                      | la section `fileServing` de la config du module (ci-dessous)               |
+
+Un en-tête posé AVANT l'appel (`@Header`, `this.response.setHeader`) est respecté comme s'il était
+passé en argument.
+
+**Pour toute l'application**, la section `fileServing` de la config du module fixe le défaut
+(`config.ts#fileServingSchema`) ; un appel le remplace toujours :
+
+```ts
+use("@nodefony/framework", {
+  fileServing: {
+    validators: true, // false : aucun validateur, aucun 304, aucun Cache-Control par défaut
+    cacheControl: "private, no-cache", // null : n'en poser aucun
+  },
+});
+```
+
+`cacheControl` est validé au démarrage : une valeur porteuse d'un retour à la ligne (qui forgerait
+un en-tête de plus) l'interrompt en nommant la clé. `{ validators: true }` dans les options d'un
+appel rétablit les validateurs quand la config les a coupés.
+
+⚠️ **La date d'un fichier n'est pas toujours fiable.** Une archive décompressée ou un build
+reproductible donne la même date à tous les fichiers : deux contenus de même taille portent alors
+la même `ETag`, et le client garde l'ancien sur un 304 sans que rien ne le signale. Pour ces
+fichiers, passer une `ETag` tirée du contenu — le 304 reste juste — ou couper les validateurs :
+
+```ts
+// le 304 garde son sens : l'étiquette suit le contenu
+return this.renderMediaStream(file, { ETag: `"${hash}"` });
+// ou : aucune requête conditionnelle, le fichier part toujours entier
+return this.renderMediaStream(file, {}, { validators: false });
+```
+
+### Une source qui n'est pas un fichier — `renderStream()`
+
+La sortie d'un processus (ffmpeg, `tar`), le corps d'un `fetch()` relayé, une archive construite à
+la volée : `renderStream(source, options?)` (`Controller.ts#Controller.renderStream`) répond par
+ce flux d'octets, en HTTP/1.1 comme en HTTP/2. La réponse est prise à l'appel, ses en-têtes partent
+au premier morceau, et la source est **détruite** à la fin quelle qu'en soit la raison. La promesse
+ne rejette jamais : elle rend `{ reason, bytes }`.
+
+```typescript
+const ff = spawn("ffmpeg", args, {
+  stdio: ["ignore", "pipe", "ignore"],
+  windowsHide: true,
+});
+try {
+  await this.renderStream(ff.stdout, {
+    headers: { "content-type": "video/mp4" },
+  });
+} finally {
+  ff.kill("SIGKILL"); // le flux est fini, quelle qu'en soit la raison
+}
+```
+
+Page complète — options, raisons de fin, erreurs avant et après le premier octet, relais `fetch`,
+pièges : [Flux d'octets](../../http/docs/byte-stream.md). Pour des **événements texte** lus par
+`EventSource`, voir [Flux SSE](../../http/docs/sse.md).
 
 ## ⚠️ Erreurs — lever, rendre, observer
 
@@ -594,15 +707,21 @@ code du framework applique — et attend de toi — les règles suivantes :
 
 ## 📜 Normes appliquées
 
-| Domaine                          | Norme                    | Comment le code s'y conforme                                                         |
-| -------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
-| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts#NO_BODY_STATUS`)                                      |
-| Requêtes par plage               | RFC 9110 §14.1.2, §14.2  | `parseByteRange()` (`Controller.ts#parseByteRange`)                                  |
-| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts#Controller.renderResponse`)              |
-| Redirections                     | RFC 9110 §15.4           | Liste blanche + repli 302 (`Response.ts#HttpResponse.send`)                          |
-| Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts#Resolver.returnController`), vérifié par le banc `auto-json` |
-| Scalaire JSON de premier niveau  | RFC 8259 §2              | `number`/`boolean` rendus (`Resolver.ts#Resolver._callWithIdempotency`)              |
-| Codes de fermeture WebSocket     | RFC 6455 §7.4            | `renderWebsocket()` (`error-renderer.ts#DefaultErrorRenderer.renderWebsocket`)       |
+| Domaine                           | Norme                            | Comment le code s'y conforme                                                          |
+| --------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
+| Statuts sans corps (204/205/304)  | RFC 9110 §15.3.5/§15.3.6/§15.4.5 | `isContentlessStatus` (`Response.ts#isContentlessStatus`) — aucun corps ne part       |
+| Requêtes par plage                | RFC 9110 §14.1.2, §14.2          | `parseByteRange()` (`Controller.ts#parseByteRange`)                                   |
+| Plage insatisfiable → 416         | RFC 9110 §15.5.17                | `renderResponse()` avec 416 (`Controller.ts#Controller.renderResponse`)               |
+| `Range` hors GET, sous `If-Range` | RFC 9110 §14.2, §13.1.5          | `renderMediaStream()` (`Controller.ts#Controller.renderMediaStream`)                  |
+| Validateurs d'un fichier          | RFC 9110 §8.8.2, §8.8.3          | `fileValidators()` (`conditionalRequest.ts#fileValidators`)                           |
+| Ordre des préconditions → 304/412 | RFC 9110 §13.1, §13.2.2          | `evaluatePreconditions()` (`conditionalRequest.ts#evaluatePreconditions`)             |
+| Cache d'un fichier protégé        | RFC 9111 §4.2.2, §5.2.2          | `Cache-Control: private, no-cache` par défaut (`Controller.ts#Controller.streamFile`) |
+| Nom de fichier téléchargé         | RFC 6266 §4.3, RFC 8187          | `contentDisposition()` (`Controller.ts#contentDisposition`)                           |
+| Longueur du corps tenue           | RFC 9112 §6.3, RFC 9113 §8.1.1   | `streamFile()` (`Controller.ts#Controller.streamFile`) + `ByteStream.ts#ByteStream`   |
+| Redirections                      | RFC 9110 §15.4                   | Liste blanche + repli 302 (`Response.ts#HttpResponse.send`)                           |
+| Média JSON sans `charset`         | RFC 8259 §11                     | Auto-JSON (`Resolver.ts#Resolver.returnController`), vérifié par le banc `auto-json`  |
+| Scalaire JSON de premier niveau   | RFC 8259 §2                      | `number`/`boolean` rendus (`Resolver.ts#Resolver._callWithIdempotency`)               |
+| Codes de fermeture WebSocket      | RFC 6455 §7.4                    | `renderWebsocket()` (`error-renderer.ts#DefaultErrorRenderer.renderWebsocket`)        |
 
 ## 📡 Observabilité — Studio
 

package/docs/decorateurs.md

@@ -334,7 +334,7 @@ Deux points qu'un dev découvre sinon à ses dépens :
   méthodes, ne serait-ce que pour l'en-tête `Allow`.
 
 Le second argument accepte les options de route non redondantes — `Omit<RouteOptions, "path" | "method">`
-(`routerDecorators.ts#route`), soit `defaults`, `requirements`, `host`, `bypassFirewall`
+(`routerDecorators.ts#route`), notamment `defaults`, `requirements`, `host`, `bypassFirewall` et `fallback`
 (`RouteOptions`, `Route.ts#RouteOptions`) :
 
 ```typescript
@@ -342,6 +342,12 @@ Le second argument accepte les options de route non redondantes — `Omit<RouteO
 async index(@Param("page") page: string) { /* … */ }
 ```
 
+`requirements.scheme` se compare au scheme **effectif** de la requête — celui qu'annonce un proxy de
+confiance compris : hors exigence, la route répond **403**, jamais une redirection
+(`Route.ts#Route.matchRequirements`). Rediriger `http` vers `https` relève de la bordure (HSTS, proxy
+inverse), pas du routage. `fallback: true` fait de la route un **repli**, servi seulement si aucune
+autre ne correspond — voir [le routage](routing.md#-ordre-de-résolution--trois-situations).
+
 ### Paramètres — ce que l'action reçoit
 
 Onze décorateurs, tous produits par `paramDecoratorFactory()` (`routerDecorators.ts#paramDecoratorFactory`) sauf
@@ -425,7 +431,7 @@ update(input: RouteInput<{ params: typeof postParams; body: typeof postBody }>)
 **Ce que fait le framework, dans l'ordre :**
 
 - chaque partie déclarée est un [Standard Schema](https://standardschema.dev) — Zod, Valibot,
-  ArkType… ; l'interface est recopiée au cœur (`runtime/standardSchema.ts#IStandardSchemaV1`), aucune
+  ArkType… ; l'interface est recopiée au cœur (`runtime/standardSchemaTypes.ts#IStandardSchemaV1`), aucune
   dépendance n'est imposée ;
 - la validation a lieu **après** les gardes (`@IsGranted` : un 403 ne révèle pas le contrat) et
   **avant** l'instanciation du contrôleur : une entrée invalide ne construit rien

package/docs/idempotence.md

@@ -263,7 +263,7 @@ Deux mécanismes rendent ça possible côté socket :
   `resolveIdempotencyKey()` (`idempotency.ts#resolveIdempotencyKey`) donne la **priorité à l'ALS** sur l'en-tête HTTP.
 - **La méthode logique voyage par `methodOverride`** — sur une socket, `context.method` vaut
   `WEBSOCKET`, qui n'est **pas** une mutation. Sans override, la porte serait sautée et un rejeu de
-  frame `socket.mutate` créerait un doublon. Le Resolver teste donc
+  frame `socket.post` créerait un doublon. Le Resolver teste donc
   `isMutationMethod(this.methodOverride ?? context.method)` (`Resolver.ts#Resolver.action`).
 
 Le pont utilise `executeActionGuarded()` (`Resolver.ts#Resolver.executeActionGuarded`) : porte d'idempotence **sans** rendu HTTP
@@ -619,14 +619,32 @@ registerIdempotencyStore("mon-backend", (ctx) => {
 });
 ```
 
-Trois règles héritées du code existant, à respecter sous peine de double-effet :
+Quatre règles héritées du code existant, à respecter sous peine de double-effet :
 
 1. **`begin` doit être atomique côté backend.** Un `GET` puis `SET` séparés laissent deux retries
    concurrents obtenir `fresh` — précisément ce que l'idempotence doit empêcher.
 2. **Ne jamais rendre `fresh` hors réservation gagnée.** En cas de doute (course, état illisible),
-   rendre `in-flight` : le client réessaiera, c'est sans danger.
+   rendre `in-flight` : le client réessaiera, c'est sans danger. La seule exception est la coupure
+   du backend, et elle se décide (règle 4).
 3. **`complete` doit préserver l'empreinte** de l'entrée in-flight, sinon un rejeu avec un autre
    payload après complétion ne produit plus de 422.
+4. **Une fabrique qui ne peut pas construire son store LÈVE — elle ne rend jamais un store qui se
+   tait.** Module manquant, client du mauvais type, configuration incohérente : tout ce qui est
+   certain dès le démarrage se refuse dans la fabrique. Le framework en fait un arrêt de boot en
+   production, et un `WARNING` suivi d'un repli sur la mémoire en développement
+   ([contrat de dégradation](#le-contrat-de-dégradation--fail-loud-jamais-silencieux)). Un store
+   construit malgré tout, qui garde chaque appel par `if (!connected) return`, échappe à ce
+   contrat : le registre affiche ton backend pendant que plus rien n'est dédoublonné. C'est un
+   échec **ouvert** — la garde a disparu, et rien ne le dit.
+
+   La connexion, elle, ne peut pas être exigée là : la fabrique est appelée à `onKernelBoot`
+   (`index.ts#Framework.onKernelBoot`), avant que l'ORM ne soit connecté. Elle se résout donc à
+   chaque appel, comme le fait `DrizzleIdempotencyStore.from()`
+   (`DrizzleIdempotencyStore.ts#DrizzleIdempotencyStore.from`), et la conduite pendant une coupure
+   est un **choix à écrire**. Les stores livrés rendent `fresh` — exécuter sans dédoublonnage
+   plutôt que bloquer — et l'annoncent comme un compromis
+   ([`redis`](#redis--le-choix-cluster)). Si ton domaine ne tolère aucun double effet, rends
+   `in-flight` (le client réessaiera) ou lève : la requête échoue, rien n'est exécuté deux fois.
 
 Fonctions du registre : `registerIdempotencyStore()` (`idempotencyStoreRegistry.ts#registerIdempotencyStore`),
 `getIdempotencyStoreFactory()` (`idempotencyStoreRegistry.ts#getIdempotencyStoreFactory`), `listIdempotencyStores()`
@@ -638,7 +656,7 @@ pour l'affichage Studio, `idempotencyStoreRegistry.ts#listIdempotencyBackends`).
 <!-- prettier-ignore -->
 | Sujet | Norme | Ancrage |
 | --- | --- | --- |
-| En-tête `Idempotency-Key`, statuts, rejeu | `draft-ietf-httpapi-idempotency-key-header-06` | `evaluateIdempotency()` (`idempotency.ts#evaluateIdempotency`) |
+| En-tête `Idempotency-Key`, statuts, rejeu | `draft-ietf-httpapi-idempotency-key-header-08` | `evaluateIdempotency()` (`idempotency.ts#evaluateIdempotency`) |
 | Clé réutilisée avec un autre payload → 422 | draft §2.2 / §2.7 | `idempotency.ts#evaluateIdempotency` |
 | Exécution concurrente identique → 409 | draft §2.6 | `idempotency.ts#evaluateIdempotency` |
 | Clé requise absente → 400 | draft §2.7 | `idempotency.ts#evaluateIdempotency` |

package/docs/index.md

@@ -108,8 +108,10 @@ dans `.ai/symbols.json` et les types générés — jamais recopiées ici, où e
 ## ⚙️ Configuration
 
 Bloc Zod (`nodefony/config/config.ts`), déclaré depuis l'application via
-`use("@nodefony/framework", { … })` : `router`, `adminBroker`, et `idempotency` (choix du store et
-réglages du GC — détaillé dans la page [Idempotence](idempotence.md)).
+`use("@nodefony/framework", { … })` : `router`, `adminBroker`, `idempotency` (choix du store et
+réglages du GC — détaillé dans la page [Idempotence](idempotence.md)), et `fileServing` (validateurs
+et `Cache-Control` des fichiers servis par une action — détaillé dans la page
+[Contrôleur](controller.md#requêtes-conditionnelles--304-412-reprise)).
 
 ## 📜 Normes appliquées
 

package/docs/routing.md

@@ -172,7 +172,7 @@ class CatalogController extends Controller {
     path: "/files/*",
     requirements: { methods: ["GET"] },
   })
-  async files(rest: string) {
+  async download(rest: string) {
     return this.renderJson({ rest });
   }
 
@@ -363,6 +363,20 @@ le suit — un `@All("*")` déclaré tôt masque le reste du contrôleur.
 > ses propres routes, quel que soit l'ordre d'écriture (`hasMagic`, `routerDecorators.ts#controller`). Ça ne
 > vaut **que** pour `"*"` seul : `/files/*` reste ordonné comme les autres.
 
+Pour un repli qui doit céder **entre modules** — la page d'une application monopage, servie sur
+`/app/{page}` ou `/app/*` —, l'option `fallback: true` range la route après toutes les autres, dans
+leur ordre relatif, au moment de construire l'index (`Route.ts#RouteOptions.fallback`) : une route
+littérale ou dynamique de même forme, déclarée par un module chargé après, garde la main. Aucun coût
+par requête. Sans ce drapeau, un repli déclaré tôt capture en silence les routes des modules
+suivants.
+
+```ts ignore
+@Get("/app/{page}", { fallback: true })
+renderSpa(): unknown {
+  return this.renderApp();
+}
+```
+
 ### Situation 2 — le même chemin, deux méthodes
 
 Deux routes peuvent partager un chemin et se distinguer par la méthode. La passe 1 essaie la première,

package/docs/templates.md

@@ -249,6 +249,21 @@ inerte `<script>alert(1)</script>`.
 > par un utilisateur (pseudo, commentaire, champ de formulaire, paramètre d'URL). Réserve-le à des
 > fragments HTML que ton propre code a construits.
 
+**La politique de sécurité du contenu (CSP) est signée pour toi.** La politique par défaut n'exécute
+un `<script>` et n'applique un `<style>` que s'ils portent le nonce de la requête. `renderView` le
+pose seul sur chaque balise ÉCRITE dans le gabarit (`viewNonce.ts#signTemplateTags`) — rien à
+ajouter. Il ne signe jamais :
+
+- une balise que les données apportent (`<%~ %>`) : c'est ce qui laisse au nonce sa valeur contre
+  l'injection ;
+- un `<script>` dont un attribut vient des données (`src="<%= it.url %>"`) : le signer exécuterait
+  l'URL qu'elles apportent. Si tu la tiens pour sûre, écris le nonce toi-même :
+  `<script nonce="<%= it.cspNonce %>" src="<%= it.url %>">` ;
+- un gestionnaire en attribut (`onclick="…"`, `onload="…"`) : aucun nonce ne s'y pose, la politique
+  le refuse. Attache l'écouteur depuis un `<script>` du gabarit (`addEventListener`).
+
+Le détail de la politique et ses réglages : [En-têtes de sécurité](../../security/docs/headers.md).
+
 ## 🧰 API publique
 
 Deux niveaux : ce que le **service Eta** expose, et ce que le **contrôleur** t'offre au-dessus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/framework",
-  "version": "10.0.0-beta.4",
+  "version": "10.0.0-beta.6",
   "description": "Le modèle de programmation Nodefony : routeur, contrôleurs, décorateurs et vues — HTTP et WebSocket dans le même contexte",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -46,23 +46,24 @@
   "dependencies": {
     "eta": "4.6.0",
     "reflect-metadata": "0.2.2",
-    "tslib": "2.8.1"
+    "tslib": "2.9.1"
   },
   "devDependencies": {
-    "@nodefony/http": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.6",
     "@types/chai": "5.2.3",
-    "@types/node": "26.6.5",
-    "@vitest/coverage-v8": "5.0.5",
-    "nodefony": "^10.0.0-beta.4",
+    "@types/node": "26.6.6",
+    "@vitest/coverage-v8": "5.1.0",
+    "nodefony": "^10.0.0-beta.6",
     "tsx": "4.23.15",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0",
+    "ws": "8.22.1"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/http": "^10.0.0-beta.4",
-    "nodefony": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.6",
+    "nodefony": "^10.0.0-beta.6",
     "zod": "^4.6.7"
   },
   "files": [