nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/realtime/platformChannels.d.ts

@@ -0,0 +1,147 @@
+/**
+ * platformChannels — **espace de nommage des surfaces temps réel de la plateforme**,
+ * partagé par les deux bords de la socket (serveur et navigateur).
+ *
+ * Tout ce que Nodefony expose sur la socket pour parler **de lui-même** (journaux,
+ * santé de la base, métriques du process, supervision du cluster, journal d'audit,
+ * contrôle du pod) porte le préfixe {@link NODEFONY_CHANNEL_NAMESPACE}. Ce que
+ * l'application expose pour parler de **son métier** ne le porte pas.
+ *
+ * C'est la même convention que les routes d'administration (`/nodefony/<module>/api/*`) :
+ * une seule marque, des deux côtés du transport. Avant, chaque sonde apportait son
+ * propre namespace (`syslog:`, `orm:`, `dashboard:`, `node:`…) — neuf territoires pour
+ * une douzaine de canaux, dont un (`node:`) qui percutait le préfixe d'import des
+ * modules natifs Node et polluait tout audit.
+ *
+ * **La table est la source unique** : personne n'écrit un nom de canal de plateforme en
+ * clair, ni côté serveur (producteurs) ni côté navigateur (consommateurs). Une chaîne
+ * recopiée dans un écran est une chaîne qui survivra au renommage suivant.
+ *
+ * Pur et isomorphe (aucun import, aucune allocation) : chargé aussi bien dans le bundle
+ * navigateur que dans le pod.
+ *
+ * @see {@link rateChannel} — le suffixe de cadence (`base:<ms>`) se compose PAR-DESSUS
+ *   ces bases ; ajouter un segment au préfixe ne le perturbe pas.
+ */
+/**
+ * Marque des surfaces de plateforme sur la socket. Un canal qui commence par ce préfixe
+ * décrit le serveur, jamais le métier de l'application.
+ *
+ * Conséquence côté sécurité : ces canaux ont un **plancher irréductible**
+ * (authentification exigée, et sans module de sécurité ils sont purement fermés aux
+ * connexions clientes). Une application ne peut pas se les approprier par accident —
+ * c'est tout l'intérêt d'une marque en toutes lettres plutôt que d'un mot courant.
+ */
+export declare const NODEFONY_CHANNEL_NAMESPACE = "nodefony:";
+/**
+ * Canaux de **diffusion** de la plateforme (le serveur pousse, les écrans regardent).
+ *
+ * Les valeurs sont des **bases** : trois d'entre elles se déclinent par cible
+ * (`…@<pid>` pour un forage sur un process, `…@<id>` pour un job) et toutes acceptent
+ * le suffixe de cadence `:<ms>` (cf {@link rateChannel}). Composer, jamais concaténer
+ * un préfixe à la main.
+ */
+export declare const PLATFORM_CHANNELS: {
+    /** Journaux du pod (flux de `Pdu`, coalescé par le pont syslog). */
+    readonly syslog: "nodefony:syslog";
+    /** Journal d'audit sécurité — plancher super-admin, un cran au-dessus des autres. */
+    readonly audit: "nodefony:audit";
+    /** Métriques agrégées du tableau de bord (vue d'ensemble). */
+    readonly dashboard: "nodefony:dashboard";
+    /** Supervision des process du cluster ; forage par process : `…@<pid>`. */
+    readonly supervision: "nodefony:supervision";
+    /** Sondes de la barre de debug (mêmes mesures que la supervision, ticker séparé). */
+    readonly debugbar: "nodefony:debugbar";
+    /** Auto-observabilité de la socket elle-même (canaux, abonnés, fan-out, backpressure). */
+    readonly socket: "nodefony:socket";
+    /** Santé des connecteurs de base (état, ping). */
+    readonly ormHealth: "nodefony:orm:health";
+    /** Flux ORM (débit de requêtes, latence, requêtes lentes) — plus dynamique que la santé. */
+    readonly ormFlow: "nodefony:orm:flow";
+    /** Forage détaillé d'un connecteur sur un process donné : `…@<pid>`. */
+    readonly ormRich: "nodefony:orm:rich";
+    /** Sortie d'un job de génération de code : `…@<jobId>` (développement uniquement). */
+    readonly scaffoldJob: "nodefony:scaffold:job";
+};
+/**
+ * Canaux **MONTANTS** de la plateforme (le navigateur pousse, le pod reçoit).
+ *
+ * Ils vivent dans une table à part parce qu'ils sont l'inverse de
+ * {@link PLATFORM_CHANNELS} : là un écran regarde, ici un écran ÉCRIT. Les mélanger
+ * ferait passer une surface d'écriture pour une surface de lecture au premier coup
+ * d'œil — et c'est précisément la distinction qui décide des bornes à poser.
+ *
+ * Ils portent la même marque `nodefony:`, donc le même **plancher irréductible**
+ * (authentification exigée ; sans module de sécurité, fermés aux connexions
+ * clientes). C'est le défaut voulu : un journal d'exploitation ouvert en écriture
+ * anonyme se noie et se falsifie. Une application qui veut capter les erreurs de
+ * visiteurs non authentifiés le déclare explicitement, et hérite des bornes.
+ */
+export declare const PLATFORM_INBOUND: {
+    /** Journaux du navigateur remontés vers le `Syslog` du pod (lots de `Pdu`). */
+    readonly syslogUplink: "nodefony:syslog:uplink";
+};
+/** Nom d'un canal montant de plateforme (valeur de {@link PLATFORM_INBOUND}). */
+export type PlatformInboundChannel = (typeof PLATFORM_INBOUND)[keyof typeof PLATFORM_INBOUND];
+/**
+ * Méthodes **RPC** de la plateforme (le client demande, le serveur répond).
+ *
+ * Elles portent la même marque que les canaux pour la même raison : ce sont des
+ * surfaces du serveur, pas de l'application. `nodefony:kernel:gc` déclenche un cycle
+ * de ramasse-miettes bloquant — un nom aussi lourd de conséquences n'a rien à faire
+ * dans l'espace de nommage où une application déclare ses propres actions.
+ *
+ * ⚠️ À ne pas confondre avec les **notifications du protocole** (`realtime:welcome`,
+ * `realtime:denied`) : celles-là décrivent la mécanique de la socket elle-même, pas
+ * une surface de la plateforme, et ne sont ni des canaux ni des actions.
+ */
+export declare const PLATFORM_METHODS: {
+    /** Liveness + mesure du temps d'aller-retour. */
+    readonly ping: "nodefony:kernel:ping";
+    /** Force un cycle GC (seulement si le pod tourne avec `--expose-gc`). */
+    readonly gc: "nodefony:kernel:gc";
+    /** Ce qu'un scaffold écrirait — fichiers créés, diff des réécritures — sans rien écrire. */
+    readonly scaffoldPreview: "nodefony:scaffold:preview";
+    /** Démarre un job de génération de code et rend son identifiant. */
+    readonly scaffoldRun: "nodefony:scaffold:run";
+    /** Demande l'arrêt d'un job de génération en cours. */
+    readonly scaffoldCancel: "nodefony:scaffold:cancel";
+};
+/**
+ * Événements **DOM** de la plateforme (`window`), dans le même espace de nommage.
+ *
+ * Ils ne passent pas par la socket — ce sont des `CustomEvent` que le navigateur
+ * fait circuler entre la barre de debug, le pont HMR et l'écran qui les écoute.
+ * Ils portent la marque pour la même raison que les canaux : `window` est un
+ * espace partagé avec l'application, et un nom d'événement générique s'y
+ * télescoperait.
+ */
+export declare const PLATFORM_EVENTS: {
+    /** Un hot-update Vite vient d'être appliqué (émis par le pont du template). */
+    readonly hmr: "nodefony:hmr";
+    /** L'utilisateur a choisi une entrée dans la barre de debug. */
+    readonly debugbarSelect: "nodefony:debugbar:select";
+};
+/** Nom d'un canal de plateforme (valeur de {@link PLATFORM_CHANNELS}). */
+export type PlatformChannel = (typeof PLATFORM_CHANNELS)[keyof typeof PLATFORM_CHANNELS];
+/** Nom d'une méthode RPC de plateforme (valeur de {@link PLATFORM_METHODS}). */
+export type PlatformMethod = (typeof PLATFORM_METHODS)[keyof typeof PLATFORM_METHODS];
+/**
+ * `s` commence-t-il par `prefix`, **insensible à la casse** et sans allocation ?
+ *
+ * La casse doit être neutralisée : sinon `NODEFONY:syslog` échapperait au plancher que
+ * `nodefony:syslog` subit — un contournement à un `toUpperCase()` près. Comparaison
+ * caractère par caractère plutôt que `toLowerCase()` : ce test est sur le chemin
+ * d'abonnement, on n'y alloue pas de chaîne.
+ */
+export declare function startsWithCI(s: string, prefix: string): boolean;
+/**
+ * Le nom désigne-t-il une surface de la plateforme (canal OU méthode) ?
+ *
+ * Un seul `startsWith` insensible à la casse, là où il fallait auparavant parcourir
+ * neuf préfixes à chaque abonnement.
+ *
+ * @param name - nom du canal demandé (suffixes de cadence/forage inclus) ou de la
+ *   méthode RPC appelée.
+ */
+export declare function isPlatformChannel(name: string): boolean;

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

@@ -0,0 +1,134 @@
+export type Pci = unknown;
+export type ModuleName = string;
+export type Message = string;
+export type Msgid = string;
+export type PduDate = string | number | Date;
+export type Status = "NOTDEFINED" | "INVALID" | "ACCEPTED" | "DROPPED";
+type SeverityKeys = keyof typeof SysLogSeverity;
+type SeverityValues = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | -1;
+export type Severity = SeverityKeys | SeverityValues;
+declare enum SysLogSeverity {
+    EMERGENCY = 0,
+    ALERT = 1,
+    CRITIC = 2,
+    ERROR = 3,
+    WARNING = 4,
+    NOTICE = 5,
+    INFO = 6,
+    DEBUG = 7
+}
+/**
+ * Les noms de sévérité RFC 5424, **dans l'ordre de l'enum** (l'index EST la
+ * valeur : `SEVERITY_NAMES[3] === "ERROR"`). Les huit niveaux de la RFC, et
+ * rien d'autre : une animation de terminal n'est pas un niveau de journal.
+ *
+ * Source **unique** du vocabulaire, côté serveur comme côté navigateur (le
+ * bundle client la réexporte). Elle existe parce qu'elle était écrite trois
+ * fois — deux copies dans la console d'administration, dans deux ORDRES
+ * différents, et aucune côté data plane, si bien qu'un `?severity=CRITICAL`
+ * n'était refusé nulle part : il rendait le journal entier.
+ *
+ * Pour un sélecteur qui va du moins au plus grave, lire `[...SEVERITY_NAMES]
+ * .reverse()` — l'ordre d'affichage se dérive, il ne se redéclare pas.
+ */
+export declare const SEVERITY_NAMES: readonly ["EMERGENCY", "ALERT", "CRITIC", "ERROR", "WARNING", "NOTICE", "INFO", "DEBUG"];
+/** Un nom de sévérité RFC 5424. */
+export type SeverityName = (typeof SEVERITY_NAMES)[number];
+/**
+ * `moduleName` porté par une entrée de journal venue d'un NAVIGATEUR.
+ *
+ * Valeur de confiance : le pod l'impose lui-même en recevant un lot sur le canal
+ * montant, sans jamais reprendre ce que la page prétend être. Une ligne qui la porte
+ * a donc traversé ce canal, et rien d'autre ne peut la produire.
+ *
+ * Elle vit ICI, dans le cœur isomorphe, pour la même raison que
+ * {@link SEVERITY_NAMES} : le serveur l'écrit, le navigateur la lit pour distinguer
+ * ces lignes à l'écran. Une copie côté console d'administration dériverait le jour
+ * où le mot change — et un écran qui ne reconnaît plus l'origine ne se plaint pas,
+ * il affiche simplement une ligne de plus au milieu des autres.
+ */
+export declare const BROWSER_ORIGIN = "browser";
+declare class Pdu {
+    payload: Pci;
+    uid: number;
+    severity: number;
+    timeStamp: number;
+    severityName: keyof typeof SysLogSeverity;
+    typePayload: string | null;
+    moduleName: ModuleName;
+    msgid: Msgid;
+    msg: Message;
+    status: Status;
+    /** PID du process émetteur (= procid RFC 5424). Constant, capturé au chargement du module. */
+    pid: number;
+    /**
+     * Identifiant de la requête en cours (corrélation log↔requête).
+     *
+     * Présent UNIQUEMENT si le Pdu est créé dans une bulle `RequestContext` active
+     * (ALS Node) ET que {@link Pdu.requestIdProvider} a été branché côté Node — voir
+     * `src/index.ts` (barrel Node uniquement, isomorphisme préservé : le bundle
+     * client/browser ne branche pas, le provider reste `null` → 0 alloc, 0 lecture).
+     *
+     * Combiné à `pid` (procid RFC 5424), permet la corrélation **complète** :
+     * `pid` = quel worker, `requestId` = quelle requête. Voyage dans ring buffer +
+     * `nodefony:syslog` + transports JSON (champ public sérialisé naturellement).
+     */
+    requestId?: string;
+    /**
+     * Provider injectable du `requestId` courant (ALS). Branché par le barrel
+     * Node (`src/index.ts`) sur `RequestContext.getRequestId`. Reste `null` côté
+     * browser/debugbar (le bundle client n'importe pas `node:async_hooks`) et
+     * pendant les phases boot pré-Kernel (cohérent : pas de requête en cours).
+     *
+     * Coût : 1 test de référence par Pdu (~5 ns) quand `null` ; ~50-100 ns quand
+     * branché (lecture ALS + accès propriété). Pas d'alloc supplémentaire si
+     * `requestId` est `undefined` (le champ reste non-défini sur l'instance).
+     */
+    static requestIdProvider: (() => string | undefined) | null;
+    /**
+     * Construit un Pdu prêt à être publié dans le pipeline Syslog.
+     *
+     * @param pci - payload (string, Error, objet — typé `unknown`, narrower côté lecteur).
+     * @param severity - niveau RFC 5424 (string `"INFO"` ou numérique `6`). Défaut `"INFO"`.
+     * @param moduleName - nom du module/service qui a produit le log. Défaut `"nodefony"`.
+     * @param msgid - catégorie de message (`"AUTH"`, `"ROUTER"`, etc.). Défaut `""`.
+     * @param msg - détail libre optionnel. Défaut `""`.
+     * @param date - timestamp (number, Date, ou string parsable). Défaut `Date.now()`.
+     * @throws Si `severity` n'est pas une valeur valide de {@link SysLogSeverity}.
+     */
+    constructor(pci: Pci, severity?: Severity, moduleName?: ModuleName, msgid?: Msgid, msg?: Message, date?: PduDate);
+    /**
+     * Map bidirectionnelle des sévérités RFC 5424 (`{ INFO: 6, 6: "INFO", ... }`).
+     *
+     * @returns dictionnaire `{ severityName: severityValue }` plus enum reverse.
+     */
+    static sysLogSeverity(): Record<Severity, Severity>;
+    /**
+     * Convertit une sévérité numérique ou string en son nom canonique.
+     *
+     * @param severity - valeur numérique (`6`) ou string (`"INFO"` ou `"6"`).
+     * @returns nom canonique (`"INFO"`) ou `undefined` si invalide.
+     */
+    static severityToString(severity: number | string): string | undefined;
+    /**
+     * Retourne le timestamp formaté `HH:MM:SS GMT±HHMM (TZ Name)`.
+     *
+     * @returns time string lisible par humain.
+     */
+    getDate(): string;
+    /**
+     * Sérialise le Pdu en string mono-ligne pour transport console/file.
+     *
+     * @returns ligne formatée `TimeStamp:... Log:... ModuleName:... SeverityName:... MessageID:... UID:... Message:...`.
+     */
+    toString(): string;
+    /**
+     * Réhydrate un Pdu existant à partir d'une string JSON — mute uniquement les
+     * clés déjà présentes sur l'instance (filtre `key in this`).
+     *
+     * @param str - JSON sérialisé d'un Pdu.
+     * @returns objet parsé (ou `null` si JSON vide). Mute l'instance courante au passage.
+     */
+    parseJson(str: string): Record<string, unknown> | null;
+}
+export default Pdu;