nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/syslog/Syslog.d.ts

@@ -0,0 +1,482 @@
+import Pdu, { Severity, ModuleName, Msgid, Message, Pci } from "./Pdu.js";
+import { DebugType, EnvironmentType } from "../types/globals.js";
+import Event from "../Event.js";
+import { ISyslog } from "../types/ISyslog.js";
+import type { ITransport } from "../types/ITransport.js";
+export interface ILogSink {
+    readonly name: string;
+    /** Chunk classe-stdout (déjà coalescé par tick). NON bloquant si possible. */
+    writeOut(s: string): void;
+    /** Chunk classe-stderr (sévérité ≤ 3 — durable). */
+    writeErr(s: string): void;
+    /** Flush SYNCHRONE de secours (process `exit`). Best-effort, JAMAIS async. */
+    flushSync(): void;
+    /** Libère les ressources (fd…). Idempotent. */
+    close(): void;
+}
+/** Sink `/dev/null` : noop total (bench — mesure du plafond sans I/O de log). */
+export declare const NULL_LOG_SINK: ILogSink;
+type Operator = "<" | ">" | "<=" | ">=" | "==" | "===" | "!=" | "RegExp";
+type Condition = "&&" | "||";
+type Data = any;
+export interface ConditionSetting {
+    operator?: Operator;
+    data: Data;
+    [key: string]: Data;
+}
+export interface conditionsInterface {
+    severity?: ConditionSetting;
+    msgid?: ConditionSetting;
+    data?: Data;
+    checkConditions?: Condition;
+    [key: string]: Data;
+}
+export interface SyslogDefaultSettings {
+    moduleName?: ModuleName;
+    msgid?: Msgid;
+    maxStack?: number;
+    rateLimit?: boolean | number;
+    burstLimit?: number;
+    defaultSeverity?: Severity;
+    checkConditions?: Condition;
+    async?: boolean;
+    overrideConsole?: boolean;
+}
+export interface WrapperResult {
+    logger: (...args: unknown[]) => void;
+    text: string;
+}
+export type CallbackFunction = (pdu: Pdu) => void;
+/**
+ * Hub central de logs structurés de Nodefony — conforme RFC 5424.
+ *
+ * Reçoit des {@link Pdu} via {@link log}, les pousse dans un ring buffer (`CircularBuffer`,
+ * O(1)), applique les filtres ({@link listenWithConditions}), et fire `"onLog"` pour les
+ * transports branchés (console, file, JSON, SSE Studio).
+ *
+ * Hérite d'{@link Event} (EventEmitter étendu) → toute brique du framework peut s'abonner.
+ *
+ * Modes :
+ * - **rateLimit** + **burstLimit** : protection anti-flood (ex: boucle qui log 10k/s)
+ * - **async** : fire `"onLog"` sur next tick (libère le hot path) ou inline
+ * - **overrideConsole** : intercepte `console.log/warn/error/debug/info` → pipe vers Syslog
+ *
+ * @example
+ * ```ts
+ * const syslog = new Syslog({ moduleName: "MyApp", defaultSeverity: "INFO" });
+ * syslog.on("onLog", (pdu: Pdu) => console.log(pdu.toString()));
+ * syslog.log("hello world", "INFO");
+ * ```
+ *
+ * @remarks Utilisé par défaut par chaque {@link Service} via `this.syslog`. Pour les apps
+ *   complexes, partager un Syslog unique entre services évite de dupliquer les buffers.
+ */
+declare class Syslog extends Event implements ISyslog {
+    settings: SyslogDefaultSettings;
+    private _ring;
+    burstPrinted: number;
+    missed: number;
+    invalid: number;
+    valid: number;
+    /**
+     * Cumul monotone des logs de classe ERREUR (sévérité 0–3 : ERROR/CRITIC/ALERT/EMERGENCY)
+     * acceptés depuis la construction. Compteur entier O(1) bumpé dans le seul point de passage
+     * {@link pushStack} (0 alloc) → sonde « erreurs par worker » de la santé
+     * pod (cf `IInstanceErrorHealth`). Débit dérivé côté lecteur (delta `errorTotal`/ts).
+     */
+    errorTotal: number;
+    /** Sous-ensemble CRITIQUE (sévérité 0–2 : CRITIC/ALERT/EMERGENCY). Cumul monotone. */
+    criticTotal: number;
+    start: number;
+    private _async;
+    private _transports;
+    /**
+     * Transports désactivés à chaud (par `setTransportEnabled`) — **lazy** (`null`
+     * tant qu'aucun toggle). Garde la réf hors de `_transports` pour pouvoir la
+     * remonter. Un transport désactivé est PHYSIQUEMENT retiré de la boucle de fire
+     * → **0 surcoût hot path** (pas de test `enabled` par log). Outil dev/diagnostic.
+     */
+    private _disabledTransports;
+    /**
+     * Stockage des Pdu dans le ring buffer (relecture mémoire). `false` = on ne
+     * garde plus rien en mémoire (l'Explorer « mémoire » et `buffered` tombent à 0)
+     * — outil avancé perf/mémoire (très haut débit). Les compteurs (valid/error)
+     * restent comptés. Coût hot path : un test booléen par log.
+     */
+    private _ringEnabled;
+    /**
+     * Diffusion temps réel active (bus `nodefony:syslog` Studio). `false` = le pont de
+     * diffusion (`createSyslogBridge`) n'accumule ni ne publie rien → l'onglet Live se
+     * grise. N'affecte NI l'écriture (transports/sink) NI la relecture. Coupé = on
+     * cesse juste de POUSSER en live ; les logs continuent d'être générés et écrits.
+     */
+    private _streamEnabled;
+    /**
+     * T2 (profil delta vs Express) — gate d'ENTRÉE par sévérité. `null` (défaut) =
+     * pas de gate (comportement historique : tout Pdu est créé + poussé au ring,
+     * le filtrage de sévérité n'a lieu qu'au LISTENER d'impression — un DEBUG en
+     * prod coûtait createPDU + pushStack pour rien, ~1,7 % du profil CPU/req).
+     * Valeur numérique N = un log de sévérité STRICTEMENT supérieure à N (moins
+     * grave) est court-circuité AVANT toute allocation. Posé par {@link init}
+     * (production sans debug → 6 = DEBUG gaté), **re-résoluble à chaud** via
+     * {@link setSeverityThreshold} (vision « audit à chaud » : élever la
+     * verbosité prod sur une fenêtre bornée sans redémarrer). Une sévérité
+     * INCONNUE (`-1`) passe toujours — c'est `createPDU` qui la refuse, et le
+     * gate ne doit pas transformer une erreur d'usage en silence. Compteur
+     * {@link gated} pour l'introspection.
+     */
+    private _severityThreshold;
+    /** Pdu singleton retourné par un log gaté (contrat `log(): Pdu`, 1 alloc lazy). */
+    private _gatedPdu;
+    /** Nombre de logs court-circuités par le gate de sévérité (T2). */
+    gated: number;
+    /**
+     * Overrides de seuil PAR MODULE (clé = `msgid` du Pdu, qui vaut le nom du
+     * Service émetteur par défaut — cf `Service.log`). `null` par défaut → 0 coût
+     * sur le hot path tant qu'aucun debug ciblé n'est actif (RÈGLE perf : lazy
+     * null). Posé à chaud par {@link setDebugOverride} (env `NF__DEBUG` au boot,
+     * endpoint admin, toggle Studio) : élève la verbosité d'UN module sous gate
+     * prod sans toucher les autres ni redémarrer. Consulté dans {@link log} APRÈS
+     * le gate global, AVANT toute allocation.
+     */
+    private _debugOverrides;
+    /**
+     * Timers d'auto-extinction des overrides (clé = même `msgid`). `null` tant
+     * qu'aucun override temporisé n'est armé. Garde-fou anti-oubli : un debug
+     * ciblé ne reste JAMAIS allumé indéfiniment. Timers `unref` (ne tiennent pas
+     * la boucle d'événements en vie) + purgés par {@link clearDebugOverride} /
+     * {@link reset} (RÈGLE perf : pas de timer sans cleanup).
+     */
+    private _debugOverrideTimers;
+    /**
+     * Échéance (epoch ms) de chaque override TEMPORISÉ — pour exposer le « s'éteint
+     * dans X » au panneau Studio. `null` tant qu'aucun override temporisé ; un
+     * override permanent (sans ttl) n'y figure pas. Nettoyé en miroir du timer.
+     */
+    private _debugOverrideExpiry;
+    /**
+     * Construit le Syslog avec settings (merge default + override user).
+     *
+     * @param settings - config (`moduleName`, `maxStack`, `rateLimit`, `burstLimit`,
+     *   `defaultSeverity`, `async`, `overrideConsole`).
+     */
+    constructor(settings?: SyslogDefaultSettings);
+    get ringStack(): Pdu[];
+    /**
+     * Capacité MAX du ring buffer (`settings.maxStack`) — nombre de Pdu que la
+     * mémoire peut relire. `ringStack.length` = remplissage courant ; ce getter =
+     * le plafond. Lecture seule, 0 allocation (introspection data plane Studio).
+     */
+    get bufferCapacity(): number;
+    /** `true` si les Pdu sont stockés dans le ring (relecture mémoire active). */
+    get ringEnabled(): boolean;
+    /**
+     * Active/désactive le stockage mémoire (ring) à chaud — outil avancé perf/mémoire.
+     * Désactiver = l'Explorer « mémoire » et `buffered` retombent à 0 (les logs ne
+     * sont plus gardés en RAM) ; les compteurs santé restent comptés. Vide le ring
+     * quand on coupe (libère la RAM tout de suite). Idempotent.
+     *
+     * @param enabled - `true` = stocker dans le ring ; `false` = ne plus stocker.
+     * @returns `true` si l'état a changé.
+     */
+    setRingEnabled(enabled: boolean): boolean;
+    /** `true` si la diffusion temps réel (`nodefony:syslog`) est active. */
+    get streamEnabled(): boolean;
+    /**
+     * Active/désactive la diffusion temps réel (bus `nodefony:syslog`) à chaud. Coupé =
+     * le pont Studio cesse de pousser des frames (onglet Live grisé) ; l'écriture et la
+     * relecture froide ne sont PAS touchées. Idempotent.
+     *
+     * @param enabled - `true` = diffuser ; `false` = couper la diffusion live.
+     * @returns `true` si l'état a changé.
+     */
+    setStreamEnabled(enabled: boolean): boolean;
+    /**
+     * Redimensionne le ring buffer (capacité de relecture en mémoire) en
+     * **préservant** les Pdu déjà présents (tronqués aux `max` plus récents si on
+     * rétrécit). Destiné au **boot uniquement** (lu depuis `config.log.maxStack`) —
+     * recrée le buffer, donc à ne pas appeler dans le hot path. No-op si `max`
+     * invalide ou inchangé.
+     *
+     * @param max - nouvelle capacité (> 0).
+     */
+    setMaxStack(max: number): void;
+    static formatDebug(debug: DebugType): DebugType;
+    /**
+     * Initialise le pipeline Syslog selon environnement + debug. Idempotent — purge les
+     * listeners `"onLog"` existants avant d'en ajouter un.
+     *
+     * @param environment - `"development"` / `"production"` / `"test"`.
+     * @param debug - active sévérité DEBUG (`+7`).
+     * @param options - conditions de filtrage Syslog custom (override des conditions par env).
+     */
+    init(environment: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void;
+    /**
+     * T2 — résout une sévérité (nom ou numérique) en valeur RFC 5424. Inconnue →
+     * `-1` (passe toujours le gate : fail-open, `createPDU` jettera comme avant).
+     * `sysLogSeverity` est un enum numérique TS → la reverse-map mêle string et
+     * number, d'où le narrowing explicite.
+     */
+    private static toSeverityNumber;
+    /**
+     * Valide STRICTEMENT une sévérité d'ENTRÉE (nom RFC 5424 ou numérique 0-7) →
+     * numéro, ou `null` si invalide. Pour les surfaces d'entrée (endpoint admin,
+     * env) : un niveau inconnu doit être REJETÉ, jamais silencieusement
+     * réinterprété (≠ {@link toSeverityNumber}, fail-open `-1` pour le hot path).
+     *
+     * @param level - nom (`"DEBUG"`) ou numéro (`7` / `"7"`).
+     * @returns le numéro 0-7, ou `null` si hors plage / nom inconnu.
+     */
+    static severityFromInput(level: string | number): number | null;
+    /**
+     * Parse une spec `NF__DEBUG` (env runtime) en directives de debug ciblé.
+     * Tokens séparés par virgule/espace :
+     * - `*` → debug GLOBAL (lève le gate de sévérité, tout passe) ;
+     * - `MODULE` → override `MODULE` à DEBUG ;
+     * - `MODULE:LEVEL` → override `MODULE` au niveau `LEVEL` (nom/numérique ;
+     *   inconnu → DEBUG, tolérant : un typo d'env ne doit pas crasher le boot).
+     *
+     * Pur (statique, sans état) → testable seul ; appliqué par le Kernel au boot
+     * via {@link setSeverityThreshold} / {@link setDebugOverride}.
+     *
+     * @param spec - valeur brute de `NF__DEBUG` (ex. `"FIREWALL,SESSION:NOTICE"`).
+     * @returns `{ global, overrides }`.
+     */
+    static parseDebugSpec(spec: string): {
+        global: boolean;
+        overrides: Array<{
+            module: string;
+            level: number;
+        }>;
+    };
+    /**
+     * T2 — règle (ou lève) le gate d'entrée par sévérité À CHAUD, sans reboot.
+     * `null` = plus de gate (tout est créé/poussé, comportement historique) ;
+     * `"DEBUG"`/7 = tout passe en restant gateable ; `"INFO"`/6 = défaut prod.
+     * Levier de la fenêtre « audit à chaud » : élever temporairement la
+     * verbosité prod puis restaurer.
+     *
+     * @param threshold - sévérité max acceptée (nom ou numérique RFC 5424), ou `null`.
+     */
+    setSeverityThreshold(threshold: Severity | number | null): void;
+    /**
+     * T2 — un log de cette sévérité franchirait-il le gate d'entrée ? À utiliser
+     * aux call sites du hot path AVANT de construire un message coûteux
+     * (template string, JSON) — pattern L1 « ne jamais formater au-dessus du
+     * niveau actif ».
+     *
+     * @param severity - sévérité à tester (nom ou numérique).
+     * @returns `true` si un log de cette sévérité serait accepté.
+     */
+    severityEnabled(severity: Severity | number): boolean;
+    /**
+     * Élève à chaud le seuil de verbosité d'UN module (debug ciblé), sans reboot et
+     * sans toucher aux autres modules. `module` = `msgid` du Pdu (par défaut le nom
+     * du Service émetteur, cf `Service.log`). Effet : tant que l'override est actif,
+     * un log de ce module passe le gate d'entrée jusqu'à `level` (ex. `"DEBUG"`)
+     * alors que le reste reste au seuil global (ex. `"INFO"` en prod).
+     *
+     * Garde-fou : si `ttlMs > 0`, l'override s'auto-éteint après ce délai (timer
+     * `unref`). (Re)poser le même module ré-arme proprement le timer. Sans gate
+     * global actif (`_severityThreshold === null`, ex. dev) l'override est sans
+     * effet — tout passe déjà.
+     *
+     * @param module - identité du module (`msgid` / nom du Service).
+     * @param level - sévérité max laissée passer pour ce module (nom ou numérique).
+     * @param ttlMs - durée de vie en ms (auto-extinction). Omis/≤0 = permanent (déconseillé en prod).
+     */
+    setDebugOverride(module: string, level: Severity | number, ttlMs?: number): void;
+    /**
+     * Retire l'override de debug ciblé d'un module (et son timer d'auto-extinction).
+     * Retombe à `null` quand le dernier override part (RÈGLE perf : 0 coût hot path).
+     *
+     * @param module - identité du module (`msgid`).
+     * @returns `true` si un override existait et a été retiré.
+     */
+    clearDebugOverride(module: string): boolean;
+    /** Retire TOUS les overrides de debug ciblé + leurs timers (retour à 0 coût). */
+    clearAllDebugOverrides(): void;
+    /**
+     * Snapshot des overrides de debug ciblé actifs (introspection — endpoint admin,
+     * toggle Studio). Cold path. `{}` si aucun.
+     *
+     * @returns map `module → seuil numérique` (copie, pas la structure interne).
+     */
+    getDebugOverrides(): Record<string, number>;
+    /**
+     * Échéances (epoch ms) des overrides TEMPORISÉS (introspection — countdown
+     * Studio « s'éteint dans X »). `{}` si aucun ; un override permanent (sans ttl)
+     * n'y figure pas.
+     *
+     * @returns map `module → epoch ms d'extinction` (copie).
+     */
+    getDebugOverrideExpiry(): Record<string, number>;
+    /** Annule + retire le timer d'auto-extinction d'un module (si présent). */
+    private clearOverrideTimer;
+    get async(): boolean;
+    set async(value: boolean);
+    /**
+     * Alias de {@link reset} — purge ring buffer + listeners.
+     */
+    clean(): this;
+    /**
+     * Reset complet — vide le ring buffer ET retire tous les listeners.
+     *
+     * @returns `this` pour chaînage.
+     */
+    reset(): this;
+    /**
+     * Vide uniquement le ring buffer (conserve les listeners attachés).
+     */
+    clearLogStack(): void;
+    /**
+     * Push manuel d'un Pdu dans le ring buffer + incrémente compteur `valid`.
+     *
+     * @param pdu - Pdu à enregistrer.
+     * @returns nouvelle taille du ring buffer après push.
+     */
+    pushStack(pdu: Pdu): number;
+    /**
+     * Crée un Pdu et le diffuse dans le pipeline (rate-limit → push → fire `"onLog"`).
+     *
+     * **Protection rate limit** : si `settings.rateLimit > 0`, ne fire `"onLog"` que pour les
+     * `burstLimit` premiers Pdu de la fenêtre. Les suivants incrémentent `missed`.
+     *
+     * **Mode async** : si `this.async === true`, fire `"onLog"` sur `setImmediate()` (libère
+     * le hot path du caller).
+     *
+     * @param payload - contenu (string, Error, objet — narrower côté lecteur).
+     * @param severity - sévérité RFC 5424 (`"INFO"`, `"ERROR"`, ...) ou numérique (6, 3, ...).
+     * @param msgid - catégorie de message (`"AUTH"`, `"ROUTER"`). Défaut = `settings.msgid`.
+     * @param msg - détail libre optionnel.
+     * @returns le `Pdu` créé (utile pour audit/tests).
+     */
+    log(payload: Pci, severity?: Severity, msgid?: ModuleName, msg?: Message): Pdu;
+    getLogStack(start?: number, end?: number, condition?: conditionsInterface): Pdu[] | Pdu;
+    getLogs(conditions: conditionsInterface, stack?: Pdu[] | null): Pdu[];
+    logToJson(conditions: conditionsInterface, stack?: Pdu[] | null): string;
+    loadStack(stack: Pdu[] | string, doEvent?: boolean, beforeConditions?: ((pdu: Pdu, stackItem: Pdu) => void) | null): Pdu[];
+    filter(conditions: conditionsInterface, callback: CallbackFunction): void;
+    listenWithConditions(conditions: conditionsInterface, callback: CallbackFunction): void;
+    error(data: Pci): Pdu;
+    warn(data: Pci): Pdu;
+    info(data: Pci): Pdu;
+    debug(data: Pci): Pdu;
+    trace(data: Pci, ...args: unknown[]): Pdu;
+    print(...args: Pci[]): Pdu;
+    logMultiple(severity: Severity, ...args: Pci[]): Pdu;
+    addTransport(transport: ITransport): this;
+    removeTransport(transport: ITransport): this;
+    /**
+     * Nombre de transports d'écriture branchés (introspection — data plane Studio,
+     * tests d'idempotence). Lecture seule, 0 allocation.
+     */
+    get transportCount(): number;
+    /**
+     * Liste polymorphe des transports d'écriture — chaque entrée porte le `name` de
+     * l'`ITransport` (`console`, `file`, `loki`, `syslog`…) et son état `enabled`.
+     * C'est l'axe **WRITE** du Log Backplane : l'écriture est un **fan-out** (1 log →
+     * N transports actifs), orthogonal à l'axe READ (1 driver queryable). Sert au data
+     * plane Studio pour afficher les vraies destinations (et non les inférer des drivers
+     * de relecture, ce qui masquait les transports write-only console/syslog/http).
+     *
+     * Inclut les transports désactivés à chaud (`enabled:false`) pour que l'UI puisse
+     * les ré-activer. Chemin FROID (introspection admin) : alloue à l'appel, jamais
+     * dans le hot path du log.
+     *
+     * @returns un tableau `{ name, enabled }` (montés `true` d'abord, puis désactivés).
+     */
+    listTransports(): {
+        name: string;
+        enabled: boolean;
+    }[];
+    /**
+     * Active/désactive un transport d'écriture **à chaud, par nom** (outil dev /
+     * diagnostic — ex. couper la console pour un bench, ou remonter un transport).
+     * Désactiver = retirer le transport de la boucle de fire (réf gardée dans
+     * {@link _disabledTransports}) → **0 surcoût hot path**. Activer = le remonter.
+     *
+     * Réversible et idempotent : un toggle vers l'état déjà courant renvoie `false`.
+     * N'instancie RIEN : ne peut réactiver qu'un transport préalablement désactivé
+     * (un transport jamais monté — ex. `loki` sans URL — exige sa config, pas ce toggle).
+     *
+     * @param name - `ITransport.name` ciblé.
+     * @param enabled - `true` = remonter, `false` = retirer.
+     * @returns `true` si l'état a changé, `false` sinon (déjà dans l'état / introuvable).
+     */
+    setTransportEnabled(name: string, enabled: boolean): boolean;
+    private _fireTransports;
+    private static readonly _nativeConsole;
+    private static _savedConsole;
+    /** Largeur fixe du champ `severityName` — couvre `WARNING` (7). */
+    private static readonly SEVERITY_WIDTH;
+    /** Largeur fixe du champ `msgid` — couvre 95% des cas, déborde proprement pour les longs. */
+    private static readonly MSGID_WIDTH;
+    static wrapper(pdu: Pdu): WrapperResult;
+    /**
+     * Transport console par défaut — formate un Pdu et l'écrit vers `process.stdout` ou
+     * `process.stderr` selon sévérité (ERROR+ vers stderr).
+     *
+     * Format : `HH:MM:SS.mmm SEVERITY MSGID : payload` avec coloration ANSI.
+     *
+     * @param pdu - Pdu à imprimer.
+     * @param pid - PID préfixé (vide en dev mono-process pour réduire le bruit).
+     * @returns le Pdu (chaînable).
+     */
+    static normalizeLog(pdu: Pdu, pid?: string): Pdu;
+    static rawLog(pdu: Pdu, pid?: string): Pdu;
+    /**
+     * Mode de bufférisation de la sortie console — **process-global** (un seul
+     * `process.stdout`). Câblé par {@link Kernel.initializeLog} depuis `config.log.buffered`.
+     *
+     * - `"auto"` (défaut) : bufférise si stdout n'est PAS un TTY (pipe/fichier =
+     *   prod/collecteur → débit) ; immédiat sur TTY (dev interactif → feedback + spinner).
+     * - `true` : toujours bufférisé (ex. bench dans un terminal).
+     * - `false` : jamais (ex. `tail -f` non bufférisé en debug prod).
+     *
+     * Bufférisé = coalesce les écritures d'un même tick en 1 `write()` (1 syscall).
+     * stderr (ERROR+) reste TOUJOURS immédiat. Flush les lignes en attente avant de switcher.
+     *
+     * @param mode - `true` | `false` | `"auto"`.
+     */
+    static setOutputBuffering(mode: boolean | "auto"): void;
+    /** Vide immédiatement (synchrone) le buffer stdout en attente. Idempotent. */
+    static flushOutput(): void;
+    /**
+     * Bascule le DRIVER de sink (LB.W — où partent les lignes après coalescing).
+     * `null` → stdout (défaut isomorphe). Câblé par {@link Kernel.initializeLog}
+     * depuis `config.log.driver`. Flush + close l'ancien driver avant de switcher.
+     *
+     * @param sink - driver `ILogSink` (ex. `FileSink`, `NULL_LOG_SINK`) ou `null`.
+     */
+    static setLogSink(sink: ILogSink | null): void;
+    /** Nom du driver de sink actif (`"stdout"` | `"null"` | `"file"` | custom). */
+    static get logSinkName(): string;
+    /** `true` si le sink texte écrit (non muté). Coupé = plus de console/fichier .log. */
+    static get sinkEnabled(): boolean;
+    /**
+     * Mute/démute le sink texte **à chaud, sans changer la config ni le driver**
+     * (outil dev/diagnostic — ex. couper la console en `npx nodefony dev`). Le nom
+     * du sink est préservé ; seul {@link sinkEnabled} bascule. Process-global (un seul
+     * sink texte par process). Idempotent.
+     *
+     * @param enabled - `true` = le sink écrit ; `false` = mute (rien n'est écrit).
+     * @returns `true` si l'état a changé.
+     */
+    static setSinkEnabled(enabled: boolean): boolean;
+    /**
+     * Intercepte `console.log/warn/error/debug/info` → pipe vers le Syslog passé.
+     *
+     * **Side effect global** : modifie l'objet `console` du process. À utiliser avec parcimonie
+     * (un seul appel par process). {@link restoreConsole} restaure les méthodes originales.
+     *
+     * @param instance - Syslog cible (recevra tous les console.* du process).
+     */
+    static overrideConsole(instance: Syslog): void;
+    /**
+     * Restaure `console.log/warn/error/debug/info` à leurs valeurs originales.
+     * Annule un {@link overrideConsole} précédent.
+     */
+    static restoreConsole(): void;
+}
+export default Syslog;

package/dist/client/types/src/syslog/drivers/ILogDriver.d.ts

@@ -0,0 +1,177 @@
+import type { FlowStepId } from "./pduFlow.js";
+/**
+ * Contrat du **Log Backplane** (axe DESTINATION queryable, LB.0).
+ *
+ * À NE PAS confondre avec {@link ILogSink} (LB.W) : `ILogSink` écrit la **ligne
+ * texte** déjà coalescée (`writeOut(s: string)`) vers stdout/fichier/null et ne
+ * voit jamais les Pdu structurés → incapable de relire/filtrer. `ILogDriver`, lui,
+ * est la **destination des Pdu structurés** : il sait les **stocker** (write) ET
+ * les **relire** (query). Les deux sont liés dans le même driver (cohérence
+ * « j'écris dans Elastic → je relis dans Elastic »).
+ *
+ * - `memory` (défaut dev) : le ring buffer `Syslog` EST le stockage → `query`
+ *   = {@link filterPdus} sur `syslog.ringStack`. Aucun write dédié (le ring est
+ *   alimenté par `Syslog.pushStack`).
+ * - `file` (JSONL, LB.2), `elastic`/`loki` (LB.4) : write = persistance des Pdu,
+ *   query = scan / API externe. Drivers Node-only enregistrés à part.
+ *
+ * Le driver actif est sélectionné par {@link logDriverRegistry} (config/env, ou
+ * action de contrôle dev-only). Le **bus temps réel** (`nodefony:syslog`) reste
+ * indépendant : il diffuse les Pdu live quel que soit le driver (même non-queryable).
+ */
+export interface ILogDriver {
+    /** Nom unique du driver (`"memory"` | `"file"` | `"elastic"` | custom). */
+    readonly name: string;
+    /** Ce que le driver sait faire (pilote l'UI Studio + le contrat data-plane). */
+    readonly capabilities: ILogDriverCapabilities;
+    /**
+     * Interroge la destination — chemin **FROID** (admin/debug), `async`, **JAMAIS**
+     * dans le pipeline requête. Absent si `capabilities.query === false` (ex. `console`).
+     *
+     * @param criteria - critères de filtrage (tous optionnels, combinés en AND).
+     * @returns enregistrements (récents d'abord) + total avant pagination.
+     */
+    query?(criteria: ILogQueryCriteria): Promise<ILogQueryResult>;
+    /**
+     * Sonde de SANTÉ de la destination (chemin FROID, admin) — « est-ce que la cible
+     * répond, en combien de temps, et quelques infos utiles ? ». Présent surtout sur
+     * les drivers DISTANTS (loki/opensearch) où la joignabilité n'est pas acquise ;
+     * absent sur les drivers locaux triviaux (memory). Ne `throw` JAMAIS : un échec se
+     * traduit par `{ ok:false, detail }` (l'admin doit voir la panne, pas un crash).
+     *
+     * @returns joignabilité + latence + infos (version, statut, nb d'entrées…).
+     */
+    probe?(): Promise<ILogDriverProbe>;
+}
+/**
+ * Résultat d'une {@link ILogDriver.probe} — santé d'une destination de logs.
+ * Affiché par Studio (badge joignable/latence + infos) ; jamais de credential.
+ */
+export interface ILogDriverProbe {
+    /** `true` si la destination répond correctement. */
+    ok: boolean;
+    /** Latence aller-retour de la sonde (ms). */
+    latencyMs: number;
+    /** Message d'erreur si `ok === false` (jamais de secret). */
+    detail?: string;
+    /** Infos utiles à afficher (version, statut cluster, nb d'entrées, endpoint…). */
+    info?: Record<string, string | number>;
+}
+/** Capacités déclarées d'un driver (introspection Studio + garde-fous endpoint). */
+export interface ILogDriverCapabilities {
+    /** Le driver persiste les Pdu (≠ ring volatile). `memory` = false (volatile). */
+    readonly write: boolean;
+    /** Le driver expose `query()` (relecture filtrée). `console` = false. */
+    readonly query: boolean;
+    /** Le driver peut alimenter un flux temps réel (tap `onLog`). */
+    readonly stream: boolean;
+}
+/**
+ * Critères de requête — tous optionnels, combinés en **AND**. Vide = tout (borné
+ * par `limit`). Les comparaisons string sont insensibles à la casse. `requestId`
+ * matche **exactement** (trace full-stack ciblée d'UNE requête) ; `module`/`msgid`/
+ * `text` matchent par **inclusion**.
+ */
+export interface ILogQueryCriteria {
+    /** Corrélation log↔requête (ALS) — match EXACT. La clé de la trace full-stack. */
+    requestId?: string;
+    /** Nom(s) de sévérité RFC 5424 (`"ERROR"` ou `["ERROR","CRITIC"]`). Insensible casse. */
+    severity?: string | string[];
+    /** Nom de module/service — inclusion insensible à la casse. */
+    module?: string;
+    /** Catégorie de message (msgid) — inclusion insensible à la casse. */
+    msgid?: string;
+    /** Borne basse du `timeStamp` (epoch ms, inclus). */
+    from?: number;
+    /** Borne haute du `timeStamp` (epoch ms, inclus). */
+    to?: number;
+    /** Recherche plein-texte (payload string + msg + module + msgid). Insensible casse. */
+    text?: string;
+    /**
+     * Protocole d'origine du log :
+     *  - `"ws"` : logs émis dans un contexte WebSocket (`msgid === "WEBSOCKET CONTEXT"`) ;
+     *  - `"http"` : tout le reste du pipeline (requête HTTP, router, firewall, applicatif).
+     *
+     * Absent = les deux protocoles. Classification PURE, cf `pduProtocol`.
+     */
+    protocol?: "ws" | "http";
+    /**
+     * Étape(s) du cycle de vie d'une requête/connexion — classification STRUCTURÉE
+     * (cf `pduFlowStep`), pas une recherche texte. Ex. `"ws-open"` ou
+     * `["request-in","route-matched"]`. Tableau = OU entre étapes ; combiné en AND
+     * avec les autres critères. Absent = toutes les étapes.
+     */
+    flow?: FlowStepId | FlowStepId[];
+    /** Nombre max d'enregistrements renvoyés (le driver borne à un plafond sûr). */
+    limit?: number;
+    /** Décalage de pagination (depuis le plus récent). */
+    offset?: number;
+    /**
+     * Ordre chronologique des `rows` :
+     *  - `"desc"` (DÉFAUT) : du plus RÉCENT au plus ancien (entrée naturelle d'un viewer) ;
+     *  - `"asc"` : du plus ANCIEN au plus récent (lecture chronologique d'une trace).
+     *
+     * L'ordre s'appuie sur l'`uid` du Pdu (compteur monotone d'émission) → garantit
+     * la **chronologie exacte même à `timeStamp` égal** (plusieurs logs dans la même ms).
+     */
+    order?: "asc" | "desc";
+}
+/**
+ * Forme **wire** d'un Pdu (isomorphe) — sérialisation stable partagée par TOUTES
+ * les façades (endpoint data-plane, canal `nodefony:syslog`, drivers). Le front
+ * réhydrate via `Object.assign(new Pdu(""), record)` → une seule logique de rendu.
+ * Produite par {@link pduToRecord}.
+ */
+export interface ILogRecord {
+    uid: number;
+    severity: number;
+    severityName: string;
+    moduleName: string;
+    msgid: string;
+    msg: string;
+    timeStamp: number;
+    /** PID émetteur (procid RFC 5424) — groupe par worker en cluster. */
+    pid: number;
+    /** Corrélation requête (ALS) si présent. `undefined` ignoré par `JSON.stringify`. */
+    requestId?: string;
+    /** Contenu brut (string/Error/objet). Narrower côté lecteur. */
+    payload: unknown;
+}
+/** Résultat d'une requête : enregistrements (récents d'abord) + méta de pagination. */
+export interface ILogQueryResult {
+    /** Enregistrements du plus RÉCENT au plus ancien, après `offset`/`limit`. */
+    rows: ILogRecord[];
+    /** Nombre total d'enregistrements qui matchent les critères (avant pagination). */
+    total: number;
+    /** `true` s'il reste des résultats au-delà de la fenêtre renvoyée. */
+    truncated: boolean;
+}
+/**
+ * Sous-ensemble des champs d'un `Pdu` lus par {@link filterPdus} et
+ * {@link pduToRecord}. Permet de filtrer/projeter SANS instancier un `Pdu` — son
+ * constructeur incrémente un compteur d'`uid` et lit le `requestIdProvider`, donc
+ * effets de bord à proscrire lors d'une simple RELECTURE. Un `Pdu` le satisfait
+ * structurellement ; un enregistrement relu d'un fichier JSONL (driver `file`,
+ * LB.2) aussi → une SEULE logique de filtrage pour memory, file et le futur CLI.
+ */
+export interface IPduLike {
+    uid: number;
+    severity: number;
+    severityName: string;
+    moduleName: string;
+    msgid: string;
+    msg: string;
+    timeStamp: number;
+    pid: number;
+    payload: unknown;
+    requestId?: string;
+}
+/**
+ * Sérialise un Pdu en {@link ILogRecord} (forme wire). Source unique de la
+ * projection Pdu→wire : réutilisée par {@link filterPdus} (driver memory) ET par
+ * le producteur data-plane `syslog` (framework) — pas de shape dupliqué qui dérive.
+ *
+ * @param pdu - Pdu (instance ou objet structurellement compatible — {@link IPduLike}).
+ * @returns enregistrement plat sérialisable. `requestId` omis si absent.
+ */
+export declare function pduToRecord(pdu: IPduLike): ILogRecord;