@nodefony/framework 10.0.0-alpha.1

package/dist/types/nodefony/src/Route.d.ts

@@ -0,0 +1,192 @@
+import { HTTPMethod, SchemeType, ContextType } from "@nodefony/http";
+import type { IRoute } from "../interfaces/index.js";
+import type { RouteActionMeta } from "../decorators/routerDecorators.js";
+import Controller from "./Controller.js";
+export interface ControllerConstructor {
+    new (...args: any[]): Controller;
+}
+/**
+ * Options pour la configuration d'une route.
+ *
+ * @example
+ * |@route("myroute", {
+ *   path: "/add/{name}",
+ *   method: ["GET", "POST"],
+ *   defaults: { name: "john" },
+ * })
+ * method(name: string) {
+ *   return this.renderJson({ name });
+ * }
+ */
+export interface RouteOptions {
+    path?: string;
+    constructor?: Controller["constructor"];
+    classMethod?: string;
+    prefix?: string;
+    method?: HTTPMethod | HTTPMethod[];
+    className?: string;
+    host?: string | string[];
+    pattern?: string;
+    defaults?: Record<string, unknown>;
+    requirements?: RouteRequirements;
+    filePath?: string;
+    /**
+     * Court-circuite le firewall pour cette route — `handleSecurity` retourne sans
+     * exécuter la chaîne d'authenticators. Réservé aux routes qui SONT le mécanisme
+     * d'auth (login/logout/me du flux BFF) : elles ne peuvent pas être gardées par
+     * le mécanisme qu'elles servent. Défaut `false` (Zero Trust).
+     */
+    bypassFirewall?: boolean;
+}
+export interface RouteRequirements {
+    domain?: string | string[];
+    scheme?: SchemeType;
+    methods?: HTTPMethod[] | HTTPMethod;
+    protocol?: string;
+}
+declare class Route implements IRoute {
+    #private;
+    name: string;
+    path?: string;
+    controller?: ControllerConstructor;
+    classMethod?: string;
+    prefix?: string;
+    method?: HTTPMethod;
+    schemes?: SchemeType;
+    pattern?: RegExp;
+    variables: string[];
+    /**
+     * Caractères du chemin déclaré qu'une requête ne peut PAS porter — la route
+     * est donc inatteignable. `undefined` tant que rien n'a été trouvé (le cas de
+     * toutes les routes saines : aucune allocation).
+     *
+     * @see {@link UNREACHABLE_IN_PATHNAME}
+     */
+    unreachableChars?: string[];
+    defaults: Partial<Record<string, unknown>>;
+    requirements: Partial<RouteRequirements>;
+    hash?: string;
+    host?: string | string[];
+    /**
+     * Patterns de domaine pré-compilés (host + `requirements.domain`), RegExp
+     * ancrées/wildcard. Compilé UNE fois dans {@link compile} ; testé par requête
+     * via {@link isDomainAllowed} (zéro alloc hot-path). `undefined` = route servie
+     * sur tous les vhosts.
+     */
+    hostRegexp?: RegExp[];
+    /**
+     * P3a — requirements pré-compilés au boot (0 alloc par match) :
+     * `methodsSet` = méthodes autorisées normalisées UPPERCASE (lookup O(1)) ;
+     * `methodsAllow` = valeur du header `Allow` du 405, jointe UNE fois ;
+     * `varRegexp` = requirements de variables de route (string → RegExp).
+     * `this.requirements` reste la config BRUTE (hash de route + introspection).
+     */
+    methodsSet?: Set<string>;
+    methodsAllow?: string;
+    varRegexp?: Record<string, RegExp>;
+    bypassFirewall: boolean;
+    /**
+     * P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
+     * (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er
+     * `routeExpectsBodyStream(route)` via lecture `Reflect` des `ParamMeta`, O(1)
+     * ensuite). Lu en amont par `handleHttp` pour sauter le parse.
+     */
+    bodyStream?: boolean;
+    /**
+     * P5 — Metadata d'action figées (`@HttpCode`/`@Header`/`@Redirect`/params/
+     * session), memo au 1er hit comme {@link bodyStream} : `undefined` = pas
+     * encore résolu (via `resolveActionMeta`, 1 lecture Reflect par route, O(1)
+     * ensuite → plus aucun `Reflect.getMetadata` par requête). Objet PARTAGÉ
+     * entre requêtes — ne jamais muter. Posé après `generateId()` → hash stable.
+     */
+    actionMeta?: RouteActionMeta;
+    filePath?: string;
+    /**
+     * Module propriétaire de la route — set par `Router.setController()` à
+     * `onBoot`, donc PAS disponible à la création de la route (via `@controller`)
+     * qui s'évalue à l'import. Utilisé pour `toLogLine()`.
+     */
+    module?: {
+        name: string;
+    };
+    constructor(name: string, obj?: RouteOptions);
+    /**
+     * Normalise le pathname de la requête pour le matching : retire le(s)
+     * slash(es) final(aux) via `stripTrailingSlashes`. À calculer UNE fois
+     * par requête dans `Router.resolve`, puis à passer à chaque {@link Route.match}
+     * scannée — sinon le getter `URL.pathname` + la normalisation sont refaits
+     * pour CHAQUE route du scan O(N) (hot path, ~N routes/req).
+     *
+     * @param context - contexte HTTP/WS courant.
+     * @returns le pathname sans slash final, ou `undefined` si la requête n'a pas d'URL.
+     */
+    static cleanPathname(context: ContextType): string | undefined;
+    match(context: ContextType, cleanPath?: string, methodOverride?: string): ((string | null)[] & Record<string, unknown>) | null | undefined;
+    /**
+     * Compile the route into a regular expression pattern.
+     * @returns The compiled regular expression pattern.
+     */
+    compile(): RegExp;
+    /**
+     * Pré-compile les requirements (P3a) — méthodes normalisées en Set UPPERCASE
+     * + RegExp des requirements de variables. Appelé par {@link compile} et
+     * {@link addRequirement} ; {@link matchRequirements} et la boucle de
+     * variables ne font plus que des lookups (0 alloc, 0 RegExp par match).
+     * Une RegExp string invalide throw ICI (création de la route, fail-fast)
+     * au lieu du 1er match.
+     */
+    compileRequirements(): void;
+    hydrateDefaultParameters(res: RegExpMatchArray): void;
+    toString(): string;
+    /**
+     * Formatte la route en une seule ligne lisible pour le log debug — évite le
+     * JSON multi-ligne du `toString()` qui polluait ~7 lignes par route au boot.
+     *
+     * Format : `[METHODS] path → @module/Controller.action  (no auth?)`
+     *
+     * Exemple :
+     * ```
+     * [GET|HEAD] /nodefony/test/index → @test/DefaultController.index
+     * [ANY]      /admin/users         → @app/AdminController.users  (no auth)
+     * ```
+     *
+     * Le `@module` ne s'affiche qu'après que `Router.setController()` ait set
+     * `this.module` à `onBoot` — appel via le décorateur `@controllers` du module.
+     */
+    toLogLine(): string;
+    toObject(): object;
+    setDefaults(arg?: Record<string, unknown>): void;
+    addDefault(key: string, value: unknown): void;
+    setPrefix(prefix?: string): void;
+    setPattern(pattern?: string): string;
+    setHostname(hostname?: string | string[]): void;
+    /**
+     * Pré-compile les patterns de domaine de la route (`host` + `requirements.domain`)
+     * en `RegExp[]` ancrées, via le matcher partagé `@nodefony/http`. Appelé par
+     * {@link compile} (kernel ↔ route = même politique). `undefined` si aucun
+     * domaine → route servie sur tous les vhosts.
+     */
+    compileHost(): void;
+    matchHostname(context: ContextType): boolean;
+    /**
+     * Empreinte stable de la route — sert d'identité pour la comparer à
+     * elle-même (deux déclarations identiques donnent la même empreinte, deux
+     * chemins différents non). Ce n'est PAS un secret, et rien ne la vérifie :
+     * elle n'est ni persistée, ni exposée, ni transmise.
+     *
+     * SHA-256 et non MD5, bien qu'aucune propriété cryptographique ne soit
+     * requise ici : `JSON.stringify(this)` sérialise la route ENTIÈRE, donc ses
+     * `defaults` et ses `requirements` — ce que l'analyse statique lit, à juste
+     * titre, comme une donnée d'application passée dans un condensat cassé. Le
+     * coût est nul (une fois à la déclaration) et personne ne dépend de la
+     * valeur ; garder MD5 n'aurait acheté qu'une alerte à réexpliquer.
+     *
+     * @returns l'empreinte hexadécimale, également posée sur {@link hash}.
+     */
+    generateId(): string;
+    addRequirement<K extends keyof RouteRequirements>(key: K, value: RouteRequirements[K]): RouteRequirements[K] | undefined;
+    getRequirement<K extends keyof RouteRequirements>(key: K): RouteRequirements[K] | undefined;
+    hasRequirements(): number;
+    matchRequirements(context: ContextType, methodOverride?: string): boolean;
+}
+export default Route;

package/dist/types/nodefony/src/SyslogAdminApi.d.ts

@@ -0,0 +1,38 @@
+import type { ISyslog, IAdminApi } from "nodefony";
+/** Options du producteur syslog — viewer de fichiers (DEV only). */
+export interface SyslogAdminApiOptions {
+    /**
+     * Répertoire des fichiers de log (`kernel.tmpDir`). Sans lui, l'endpoint
+     * `files` répond « désactivé » (cas prod cloud-native : logs → stdout).
+     */
+    logDir?: string;
+    /**
+     * `true` en dev/staging uniquement. La rotation/rétention des logs n'est PAS
+     * le rôle de Nodefony (cf cloud-native, PM2 déprécié) : en prod les logs vont
+     * sur stdout/stderr → collecteur. Le viewer fichiers est un confort DEV qui
+     * remplace `tail -f` localement.
+     */
+    enableFiles?: boolean;
+    /**
+     * Environnement du kernel (`"development"` | `"production"` | …). Garde la
+     * **switch du driver de relecture** (`POST backplane/driver`) en **dev-only**
+     * (403 hors `development`) — action de contrôle runtime, jamais en prod.
+     */
+    environment?: string;
+}
+/**
+ * Producteur `IAdminApi` du **syslog** (core) — exposé sous
+ * `/nodefony/syslog/api/*`. 4ᵉ et dernier producteur de P10.3.
+ *
+ * Le syslog vit dans `@nodefony/core` et ne peut pas importer framework →
+ * framework le wrappe (comme le kernel) via `createSyslogAdminApi(syslog)`.
+ * Lecture seule du ring buffer (`ISyslog.ringStack`, FIFO O(1)).
+ *
+ * Endpoints :
+ *  - `GET /nodefony/syslog/api/logs` → Pdu récents (`?severity=ERROR&limit=N`)
+ *  - `GET /nodefony/syslog/api/info` → compteurs (valid/invalid/missed/buffer)
+ *
+ * @param syslog - instance Syslog du kernel (`kernel.syslog`).
+ * @param options - viewer de fichiers (DEV) : `logDir` + `enableFiles`.
+ */
+export declare function createSyslogAdminApi(syslog: ISyslog, options?: SyslogAdminApiOptions): IAdminApi;

package/dist/types/nodefony/src/Template.d.ts

@@ -0,0 +1,8 @@
+import { Service, Module } from "nodefony";
+declare class Template extends Service {
+    engine: unknown;
+    module: Module;
+    cache: boolean;
+    constructor(name: string, engine: unknown, module: Module, options?: Record<string, unknown>);
+}
+export default Template;

package/dist/types/nodefony/src/configMutation.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Mutation de configuration en direct (édition live admin, page Studio config).
+ *
+ * Brique PURE et testable derrière l'endpoint `PATCH /nodefony/kernel/api/config/{module}`
+ * ({@link createKernelAdminApi}). Une mutation de config runtime par un admin est une
+ * **surface sensible** : ces helpers fail-closed décident *si* un champ est éditable à
+ * chaud, *valident* la valeur contre le JSON Schema du module (même esprit que les
+ * overrides `NF__*` validés par Zod), et produisent la **recette** d'override pour les
+ * champs non mutables (12-factor : la majorité se change au redémarrage, jamais en RAM).
+ *
+ * Périmètre assumé (MVP) : on édite une **feuille scalaire** (`string`/`number`/
+ * `boolean`/`null`/enum/union de scalaires). Les objets/arrays imbriqués ne sont pas
+ * éditables en place (recette uniquement) — un `runtimeMutable` se pose sur un scalaire.
+ * Les `.refine()` Zod custom ne sont PAS dans le JSON Schema : la validation feuille
+ * couvre type/enum/bornes/longueur/pattern, le module reste juge au prochain boot.
+ */
+/**
+ * Vue minimale d'un nœud JSON Schema (produit par `z.toJSONSchema`), incluant les
+ * **flags Nodefony** recopiés au top-level par le `.meta()` natif zod des modules.
+ */
+export interface IJsonSchemaNode {
+    type?: string | string[];
+    enum?: readonly unknown[];
+    anyOf?: readonly unknown[];
+    oneOf?: readonly unknown[];
+    properties?: Record<string, unknown>;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    default?: unknown;
+    /** Éditable à chaud (relu par requête) — seul cas autorisé en édition live. */
+    runtimeMutable?: boolean;
+    /** Réservé à une feature future — jamais éditable. */
+    reserved?: boolean;
+    /** Dérivé par le kernel au boot — jamais éditable. */
+    kernelDerived?: boolean;
+    /** Donnée sensible — jamais éditée via l'API (recette `*_FILE`). */
+    secret?: boolean;
+    [k: string]: unknown;
+}
+/** Drapeaux d'éditabilité d'un champ, dérivés de son nœud JSON Schema. */
+export interface IFieldFlags {
+    runtimeMutable: boolean;
+    reserved: boolean;
+    kernelDerived: boolean;
+    secret: boolean;
+}
+/** Résultat d'une validation de feuille : succès, ou échec avec message humain. */
+export type LeafValidation = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Descend dans un JSON Schema le long d'un chemin pointé (`upload.maxFileSize`)
+ * et renvoie le nœud feuille, ou `null` si un segment ne résout pas.
+ *
+ * @param schema - JSON Schema racine du module (`mod.configSchema()`).
+ * @param segments - segments du chemin (casse réelle ou insensible).
+ * @returns le nœud feuille, ou `null` si le chemin est inconnu.
+ */
+export declare function navigateSchemaNode(schema: unknown, segments: string[]): IJsonSchemaNode | null;
+/** Extrait les flags Nodefony d'un nœud (défaut `false` partout). */
+export declare function nodeFlags(node: IJsonSchemaNode): IFieldFlags;
+/**
+ * Valide une valeur scalaire contre un nœud JSON Schema feuille (type(s), `enum`,
+ * `anyOf`/`oneOf`, bornes numériques, longueur/pattern de chaîne). Fail-closed :
+ * un nœud objet/array non scalaire est refusé (édition feuille uniquement).
+ *
+ * @param node - nœud JSON Schema cible.
+ * @param value - valeur candidate (déjà typée — provient d'un body JSON).
+ * @returns succès, ou échec avec message explicatif.
+ */
+export declare function validateLeafValue(node: IJsonSchemaNode, value: unknown): LeafValidation;
+/** Raison machine du refus d'édition live (`null` = éditable). */
+export type NotEditableReason = "secret" | "reserved" | "kernel_derived" | "boot_only";
+/**
+ * Décide si un champ est éditable à chaud. Ordre de refus : secret > réservé >
+ * dérivé kernel > non-`runtimeMutable` (boot). `null` = éditable.
+ *
+ * @param flags - flags du nœud ({@link nodeFlags}).
+ * @returns la raison du refus, ou `null` si éditable live.
+ */
+export declare function notEditableReason(flags: IFieldFlags): NotEditableReason | null;
+/**
+ * Construit la **recette** d'override à appliquer dans le déploiement pour un champ
+ * non mutable à chaud (12-factor). Un secret passe par la variante `*_FILE` (jamais
+ * la valeur en clair dans l'environnement).
+ *
+ * @param seg - segment d'adressage du module (`http`, `security`, `app`…).
+ * @param segments - chemin pointé du champ.
+ * @param isSecret - le champ porte-t-il le flag secret ?
+ * @returns la ligne d'override prête à copier.
+ */
+export declare function recipeFor(seg: string, segments: string[], isSecret: boolean): string;
+/**
+ * Lit la valeur courante d'une config à un chemin pointé (insensible à la casse) —
+ * sert à journaliser l'ancienne valeur (`before`) avant mutation.
+ *
+ * @param obj - objet de config (`mod.options`).
+ * @param segments - chemin pointé.
+ * @returns la valeur, ou `undefined` si le chemin ne résout pas.
+ */
+export declare function getResolvedPath(obj: Record<string, unknown>, segments: string[]): unknown;