--- title: "Référence d'API — nodefony — service" source: docs/api/core/service.md url: https://nodefony.github.io/nodefony-core/docs/api/core/service/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › service > Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `nodefony` `import { … } from "nodefony"` — 83 symboles. ### Classes (7) #### `ClusterManager` ```ts class ClusterManager ``` Superviseur cluster du process MASTER (Phase 2 du mode cluster sans PM2). - `constructor(opts: ClusterManagerOptions)` - `get size(): number` — Nombre de workers actuellement vivants. - `get shuttingDown(): boolean` — `true` une fois `shutdown()` enclenché (plus aucun respawn). - `start(): this` — Fork les workers initiaux et arme le respawn. - `shutdown(signal?: NodeJS.Signals): void` — Arrêt gracieux : déconnecte/SIGTERM chaque worker (drain), puis SIGKILL les survivants après `shutdownTimeoutMs`, et sort le process. - `installSignalHandlers(): void` — Branche SIGTERM/SIGINT du process MASTER sur `shutdown`. - `removeSignalHandlers(): number` — Retire les gestionnaires que `installSignalHandlers` a posés. #### `ClusterProbeAggregator` ```ts class ClusterProbeAggregator ``` **Agrégateur de sondes** master-side du mode cluster (Phase 4c) — le « gardien » qui collecte la santé de chaque worker et **rediffuse la vue d'ensemble** à tous. - `constructor(opts?: ClusterProbeAggregatorOptions)` - `get size(): number` — Nombre de workers rattachés. - `get broadcastTotal(): number` — Total de snapshots diffusés (sonde de la gateway). - `attach(worker: IProbeWorker): void` — Rattache un worker : cible de diffusion + récepteur de ses remontées de sonde. - `detach(id: number): void` — Détache un worker (au `exit`) : il sort de l'agrégat. - `start(): void` — Démarre la diffusion périodique du snapshot agrégé. - `broadcast(): void` — Diffuse immédiatement le snapshot courant (liste des dernières sondes connues) à tous les workers vivants. - `stop(): void` — Arrête le timer de diffusion. - `clear(): void` — Vide l'agrégateur (arrêt du master). #### `ClusterRelay` ```ts class ClusterRelay ``` **Master-gateway** du backplane realtime cluster (Phase 3) — routeur IPC qui vit dans le process MASTER (lequel ne sert AUCUN HTTP, cf `ClusterManager`). - `constructor(opts?: ClusterRelayOptions)` - `get size(): number` — Nombre de workers actuellement rattachés au relay. - `get relayedTotal(): number` — Total des messages realtime rebroadcastés (sonde gateway). - `attach(worker: IRelayWorker): void` — Rattache un worker : l'enregistre comme cible de broadcast et branche la réception de ses messages. - `detach(id: number): void` — Détache un worker (au `exit`). - `clear(): void` — Vide le relay (arrêt du master). #### `Fetch` ```ts class Fetch extends Service ``` Service `Fetch` — façade DI au-dessus de l'API `fetch` **native** de Node.js. - `fetch: typeof globalThis.fetch` - `Response: typeof globalThis.Response` - `Request: typeof globalThis.Request` - `Headers: typeof globalThis.Headers` - `constructor(owner: Module | Kernel)` #### `GitService` ```ts class GitService ``` Introspection git du dépôt — **sans spawn `git` ni dépendance** (lecture directe de `.git/`). Résultat caché pour la vie du process. Best-effort : champs `""` hors d'un dépôt (ex. container sans `.git`). Consommé par le data plane kernel (`/nodefony/kernel/api/info` → `git`) et la barre de debug (bloc `app`). - `static read(cwd?: string): GitInfo` — Lit branche + commit court (une fois, puis cache process). - `static branch(cwd?: string): string` — Branche seule (raccourci). #### `ProcessProbe` ```ts class ProcessProbe ``` Sonde PROCESS **stateful** d'un worker — calcule les métriques par INTERVALLE (CPU, event-loop lag, ELU sont des deltas entre 2 `read()`). Une instance par process worker. - `read(): IProcessHealth` — Lit la santé process courante (métriques par intervalle depuis le dernier `read()`). - `dispose(): void` — Libère le monitor event-loop natif (à l'arrêt du worker). #### `RichProcessProbe` ```ts class RichProcessProbe ``` Sonde process **riche stateful** d'un worker — calcule les métriques par INTERVALLE (GC, ELU active/idle, changements de contexte sont des deltas entre deux `read()`). Une instance par process worker, **lazy & opt-in** : créée seulement quand un drill est actif sur ce worker (« on paie ce qu'on regarde »). - `enable(): void` — Attache l'observer GC et réinitialise les baselines de delta (ELU/ctx). - `read(): IProcessRich` — Lit la sonde riche courante (deltas depuis le dernier `read()`, snapshots heap/handles). - `disable(): void` — Détache l'observer GC (fin du drill / arrêt du worker). ### Fonctions (33) #### `buildDevStatus` ```ts function buildDevStatus(cwd: string, pid: number | null, pidAlive: boolean, procs: readonly DevProcessInfo[], ports: readonly PortState[], inProject?: boolean, discoverySupported?: boolean, foreign?: readonly DevProcessWithCwd[], projectScopeBlind?: boolean, readiness?: IReadinessProbe | null, portShift?: PortShift | null): DevStatusReport ``` Compose le `DevStatusReport` (décompte + incohérences) — fonction PURE : `pidAlive` est fourni par l'appelant (aucun syscall ici → testable sans `ps`/process). Centralise la synthèse + les warnings consommés AUSSI BIEN par le rendu ANSI CLI (`renderStatus`) que par le data plane Studio (`collectDevStatus`). #### `cleanZonePattern` ```ts function cleanZonePattern(pattern: string): string ``` Pattern de zone LISIBLE : `describe()` remonte `RegExp.source`, où V8 échappe les slashes (`^\/nodefony\/…`) — on dé-échappe pour l'affichage ET pour le classement par namespace (un `startsWith("^/nodefony")` sur la source brute ne matcherait jamais — bug vécu au premier boot réel). #### `clearRuntimeState` ```ts function clearRuntimeState(cwd: string): void ``` #### `collectDevStatus` ```ts function collectDevStatus(cwd: string, opts?: DiscoverOptions & DevObservationDeps): Promise ``` Collecte l'état dev (ps + sonde ports + pidfile) → `DevStatusReport` JSON. Best-effort : Windows (pas de `ps` POSIX) → `supported:false`. `opts.includeSelf` (data plane = le serveur DOIT se compter). AUCUN boot kernel requis (observation externe pure) → utilisable depuis le fast-path standalone ET depuis le data plane. #### `computeBackoff` ```ts function computeBackoff(crashes: number, baseMs: number, maxMs: number): number ``` Calcule le délai de respawn d'un worker mort selon un backoff exponentiel. #### `defaultDevPorts` ```ts function defaultDevPorts(cwd?: string, env?: Record): number[] ``` Ports serveur à SONDER (`status`, `stop`, readiness, attente de libération). #### `detectPortShift` ```ts function detectPortShift(state: RuntimeState | null): PortShift | null ``` Le décalage de ports d'un runtime, ou `null` s'il sert bien ce qu'on lui a demandé. #### `detectRuntimeMode` ```ts function detectRuntimeMode(procs: readonly DevProcessInfo[]): RuntimeMode | null ``` Mode runtime dominant observé, ou `null` si aucun process principal. Priorité dev > cluster > prod en cas de cohabitation anormale (le conflit est signalé par ailleurs en warning / refus). Fonction PURE. #### `findRuntimeConflict` ```ts function findRuntimeConflict(procs: readonly DevProcessInfo[], intended: RuntimeMode): DevProcessInfo[] ``` Process PRINCIPAUX appartenant à un runtime d'un mode DIFFÉRENT de `intended` — un conflit de cohabitation (ex. un `prod`/`cluster` occupe les ports quand on veut démarrer en `dev`, ou l'inverse). Vite exclu (enfant). Sert aux gardes anti-collision : fail-loud (refus + message), JAMAIS de kill cross-mode automatique (un prod est intentionnel). Fonction PURE. #### `isClusterMessage` ```ts function isClusterMessage(m: unknown): m is IClusterMessage ``` Type-guard d'un message IPC cluster — narrowing sûr d'un message `unknown` du canal partagé. #### `isClusterProbeCtl` ```ts function isClusterProbeCtl(m: unknown): m is IClusterProbeCtl ``` Type-guard d'un `IClusterProbeCtl` — narrowing sûr du canal IPC partagé. #### `isClusterProbeEnrich` ```ts function isClusterProbeEnrich(m: unknown): m is IClusterProbeEnrich ``` Type-guard d'un `IClusterProbeEnrich` — narrowing sûr du canal IPC partagé. #### `isFrameworkZone` ```ts function isFrameworkZone(z: IFirewallZoneView): boolean ``` `true` si la zone vit dans le namespace réservé `/nodefony` → déclarée par `@nodefony/framework` (les aires data plane admin). L'inférence par pattern est fiable PAR CONVENTION : le routage `/nodefony` est réservé au framework (règle figée), aucune app/module tiers n'y monte d'aire. #### `isPortListening` ```ts function isPortListening(port: number, host?: string, timeoutMs?: number): Promise ``` `true` si un service écoute sur `port` en loopback (connexion acceptée). Inverse de la sonde « port libre » du superviseur : ici on confirme qu'un serveur RÉPOND. Le verdict de `probePort`, sans sa cause. #### `loadClusterConfig` ```ts function loadClusterConfig(appPath?: string): Promise ``` Lit le bloc `cluster` de la config app de façon **standalone** (best-effort), sans booter de Kernel — c'est tout ce dont le master a besoin pour décider du fork. #### `readCgroupCpuQuota` ```ts function readCgroupCpuQuota(read?: FileReader): number | null ``` Lit le quota CPU effectif depuis les cgroups Linux — cgroup v2 (`cpu.max`) puis v1 (`cpu.cfs_quota_us` / `cpu.cfs_period_us`). #### `readEventLoopDelay` ```ts function readEventLoopDelay(histogram: Pick, resolutionMs?: number): IEventLoopDelay ``` Lit le retard RÉEL de la boucle sur un histogramme `monitorEventLoopDelay`. #### `readOrmHealth` ```ts function readOrmHealth(): IOrmLeanHealth | null ``` Lit la santé ORM lean du process via le fournisseur branché, ou `null` si aucun ORM n'est branché (le champ `orm` du report est alors omis). Lecture pure, jamais throw. #### `readOrmRich` ```ts function readOrmRich(): Promise | null ``` Appelle le fournisseur ORM riche branché (async), ou `null` si aucun driver ne l'a posé. Le résultat est un blob OPAQUE (forme connue de Studio seul). Ne throw pas pour son propre compte : la propagation d'un rejet du provider reste à l'appelant (qui catch dans son tick). #### `readRuntimeState` ```ts function readRuntimeState(cwd: string, opts?: { purgeStale?: boolean; }): RuntimeState | null ``` #### `readSupervisorSuspension` ```ts function readSupervisorSuspension(cwd: string): SupervisorLock | null ``` Le rechargement est-il suspendu, et pourquoi ? #### `readyAnnouncement` ```ts function readyAnnouncement(state: RuntimeState | null, probedPorts?: readonly number[]): ReadyAnnouncement ``` Ce qu'un démarrage doit DIRE de l'endroit où il sert. #### `resolvePortPolicy` ```ts function resolvePortPolicy(environment: string, explicit?: PortPolicy): PortPolicy ``` Politique de port effective. #### `resolveTopology` ```ts function resolveTopology(opts?: ResolveTopologyOptions): Topology ``` Résout LA topologie de lancement — source unique de vérité pour « combien de workers ». Ordre de priorité (premier défini gagne) : #### `resolveWorkerCount` ```ts function resolveWorkerCount(opts?: ResolveWorkerOptions): number ``` Résout le nombre de workers à forker, dans l'ordre de priorité : #### `resumeSupervisor` ```ts function resumeSupervisor(cwd: string): void ``` Rend la main au superviseur (fin de l'opération, quelle qu'en soit l'issue). #### `runtimeModes` ```ts function runtimeModes(procs: readonly DevProcessInfo[]): Set ``` Modes runtime présents parmi les process PRINCIPAUX (Vite exclu — un Vite ne « tient » pas les ports serveur). Set vide = aucun runtime principal vivant. Fonction PURE. #### `servedUrl` ```ts function servedUrl(scheme: "http" | "https", host: string, port: number): string ``` L'adresse où TAPER pour atteindre un serveur qui écoute sur `host:port`. #### `setOrmHealthProvider` ```ts function setOrmHealthProvider(fn: () => IOrmLeanHealth | null): void ``` Branche (ou débranche avec `null`) le fournisseur de santé ORM lean. Idempotent (dernier gagne) — plusieurs drivers branchant la même fonction globale est sûr. #### `setOrmRichProvider` ```ts function setOrmRichProvider(fn: () => Promise | null): void ``` Branche (ou débranche avec `null`) le fournisseur de diagnostic ORM riche. Idempotent (dernier gagne). Coût NUL hors drill : ce fournisseur n'est appelé que quand le master a demandé l'enrichissement ORM de CE worker. #### `signalProcessGroup` ```ts function signalProcessGroup(pid: number, signal: NodeJS.Signals, deps?: SignalTreeDeps): TreeSignalOutcome ``` Envoie `signal` à l'ARBRE de `pid` — enfant serveur ET ses Vite — et dit ce qu'il a pu atteindre. No-op silencieux si le process n'existe plus. #### `suspendSupervisor` ```ts function suspendSupervisor(cwd: string, reason: string, detail?: string): void ``` Suspend le rechargement automatique le temps d'une opération qui écrit dans les sources. #### `writeRuntimeState` ```ts function writeRuntimeState(cwd: string, state: Omit): void ``` Publie les ports EFFECTIFS du runtime. Best-effort : un échec d'écriture ne doit jamais faire tomber un serveur qui, lui, écoute très bien (les lecteurs retomberont sur les ports par défaut). ### Constantes (6) #### `CLUSTER_PROBE_CTL_KIND` ```ts const CLUSTER_PROBE_CTL_KIND: "nf:probe:ctl" ``` `kind` d'un **ordre d'enrichissement** worker → master (Phase 2 drill-down). Un worker (celui qui tient la connexion navigateur) demande au master d'activer/couper la sonde **riche** (GC/heap-spaces/handles/ELU/ctx — cf `RichProcessProbe`) sur le worker `pid` ciblé. Routé par le `"./ClusterProbeAggregator"` vers ce worker via CLUSTER_PROBE_ENRICH_KIND. « On paie ce qu'on regarde » : aucun rich produit hors drill. #### `CLUSTER_PROBE_ENRICH_KIND` ```ts const CLUSTER_PROBE_ENRICH_KIND: "nf:probe:enrich" ``` `kind` de l'**ordre ciblé** master → worker (Phase 2 drill-down). Dit au worker d'inclure (ou non) son blob de sonde **riche** dans son report périodique (`CLUSTER_PROBE_KIND`). Le rich voyage ensuite dans le snapshot agrégé EXISTANT (aucun nouveau flux de données — juste un champ `rich` de plus pour ce worker). #### `CLUSTER_PROBE_KIND` ```ts const CLUSTER_PROBE_KIND: "nf:probe" ``` `kind` d'une **remontée de sonde** worker → master (Phase 4c). Chaque worker envoie périodiquement sa santé per-instance (opaque pour le master) ; le `"./ClusterProbeAggregator"` les collecte. Le `"./ClusterRelay"` IGNORE ce kind (ce n'est pas une publication realtime à rebroadcaster). #### `CLUSTER_PROBE_SNAPSHOT_KIND` ```ts const CLUSTER_PROBE_SNAPSHOT_KIND: "nf:probe:snap" ``` `kind` du **snapshot agrégé** master → workers (Phase 4c). Le master diffuse périodiquement la liste des sondes de TOUS les workers (`{ ts, instances }`) ; chaque worker la met en cache pour servir la vue POD sur son endpoint santé (push, pas pull). #### `CLUSTER_RT_KIND` ```ts const CLUSTER_RT_KIND: "nf:rt" ``` `kind` d'une publication **realtime** (port `IBackplane`). Le `"./ClusterRelay"` rebroadcast ces messages aux **autres** workers ; le `ClusterBackplane` (framework) les produit/consomme. #### `EVENT_LOOP_RESOLUTION_MS` ```ts const EVENT_LOOP_RESOLUTION_MS = 20 ``` Période d'échantillonnage des histogrammes de retard de la boucle (ms). ### Interfaces (29) #### `ClusterManagerOptions` ```ts interface ClusterManagerOptions ``` Options du `ClusterManager`. Tous les effets de bord (runtime, timers, exit, log) sont injectables. - `workers: number` — Nombre de workers à forker (résolu par `resolveWorkerCount`). - `log?: (msg: string, severity?: Severity) => void` - `runtime?: IClusterRuntime` - `scheduler?: ClusterScheduler` - `exit?: (code: number) => void` — Sortie process — injectable pour ne pas tuer le process de test. - `respawnBaseMs?: number` — Délai du 1er respawn (ms). - `respawnMaxMs?: number` — Plafond du délai de respawn (ms). - `stableMs?: number` — Durée de vie minimale d'un worker pour réinitialiser le backoff (ms). - `shutdownTimeoutMs?: number` — Délai de drain gracieux avant SIGKILL des survivants (ms). #### `ClusterProbeAggregatorOptions` ```ts interface ClusterProbeAggregatorOptions ``` Options du `ClusterProbeAggregator`. - `intervalMs?: number` — Cadence de diffusion du snapshot agrégé (ms). - `log?: (msg: string, severity?: Severity) => void` #### `ClusterRelayOptions` ```ts interface ClusterRelayOptions ``` Options du `ClusterRelay`. Effets de bord (log) injectables. - `log?: (msg: string, severity?: Severity) => void` #### `ClusterScheduler` ```ts interface ClusterScheduler ``` Planificateur (setTimeout/clearTimeout) — injectable pour tester backoff + timeout sans horloge réelle. - `set(fn: () => void, ms: number): unknown` - `clear(handle: unknown): void` #### `DevProcessInfo` ```ts interface DevProcessInfo ``` Process runtime Nodefony vivant observé via `ps` (sans IPC) — dev, prod ou cluster. - `readonly pid: number` - `readonly ppid: number` — PID du parent (relie l'enfant au superviseur/master, Vite à l'enfant). - `readonly mode: RuntimeMode` — Mode runtime du process (dev/prod/cluster) — distingue prod-server de dev-server. - `readonly role: DevProcessRole` - `readonly label: string` — Étiquette courte de colonne (`supervisor`, `server`, `vite`). - `readonly detail?: string` — Détail optionnel hors colonne (bundles d'une instance Vite : `react+vue`). - `readonly rssKb: number` — Mémoire résidente en kilo-octets (champ `rss` de `ps`). - `readonly cpu: number` — Pourcentage CPU instantané (champ `pcpu` de `ps`). - `readonly uptimeSec: number` — Durée de vie en secondes (champ `etime` de `ps`, normalisé). #### `DevStatusReport` ```ts interface DevStatusReport ``` Rapport d'introspection des process dev — forme JSON, SOURCE DE VÉRITÉ unique partagée par le rendu ANSI CLI (`nodefony status`) et le data plane Studio (`GET /nodefony/kernel/api/processes`). CLI et Web affichent EXACTEMENT le même état. - `readonly supported: boolean` — `false` si l'OBSERVATION EXTERNE n'a pas pu être menée — CONSTATÉ, jamais déduit de la plateforme : Windows, mais aussi `ps` absent (images Node minces, distroless, Alpine nu) ou syntaxe refusée (cert … - `readonly running: boolean` — `true` si au moins un process runtime Nodefony tourne. - `readonly mode: RuntimeMode | null` — Mode runtime dominant détecté (`dev`/`prod`/`cluster`), ou `null` si aucun process principal vivant. - `readonly processes: readonly DevProcessInfo[]` — Process runtime observés (triés superviseur/master → serveur/worker → Vite). - `readonly ports: readonly PortState[]` — État des ports serveur sondés. - `readonly summary: { readonly supervisors: number; readonly servers: number; readonly vites: number; readonly masters: number; readonly workers: number; readonly portsUp: number; readonly portsTotal: n …` — Décompte par rôle + ports à l'écoute. - `readonly warnings: readonly string[]` — Incohérences détectées (pidfile périmé, orphelins, empilement) — fail-loud. - `readonly pidfile: { readonly path: string; readonly pid: number | null; readonly alive: boolean; }` — Pidfile single-instance du superviseur — indice, chemin RELATIF (pas de fuite FS). - `readonly inProject: boolean` — `false` si le cwd n'est PAS un projet Nodefony (`isNodefonyProjectDir`) — le rendu remplace alors « lance nodefony dev » par un message explicite (un dev perdu hors projet croyait l'app simplement arr … - `readonly foreign: readonly DevProcessWithCwd[]` — Runtimes des AUTRES projets du poste — jamais comptés dans `processes`, jamais tus. - `readonly readiness: IReadinessProbe | null` — Ce que le runtime dit de sa DISPONIBILITÉ — `null` quand la sonde n'a rien pu conclure (aucun port en écoute, runtime muet), jamais un verdict deviné. - `readonly portOwners: Readonly>>` — Ports occupés par un projet identifié qui n'est PAS le nôtre (port → racine). - `readonly portShift: PortShift | null` — Le runtime sert-il ailleurs que là où sa configuration le demandait ? #### `GitInfo` ```ts interface GitInfo ``` Identité git du dépôt courant. Champs `""` si indéterminés (hors dépôt). - `branch: string` — Branche courante, ou sha court si HEAD détaché. - `commit: string` — Commit HEAD court (7 caractères). #### `IClusterConfig` ```ts interface IClusterConfig ``` Bloc `cluster` de la config app — lisible **sans kernel** (le master fork les workers AVANT de booter le moindre Kernel : il doit donc lire ce réglage seul). Doit rester kernel-free pour pouvoir être importé directement par le master. - `workers: WorkersSetting` — Nombre de workers / topologie. #### `IClusterMessage` ```ts interface IClusterMessage ``` Base de tout message du protocole IPC cluster — seul le `kind` est imposé. Les autres champs sont opaques pour le master (il route/agrège sans les inspecter). - `readonly kind: string` #### `IClusterProbeCtl` ```ts interface IClusterProbeCtl extends IClusterMessage ``` Ordre d'enrichissement (worker → master, `CLUSTER_PROBE_CTL_KIND`). `op` = `"enrich"` (activer) | `"stop"` (couper) ; `pid` = worker à (dés)enrichir ; `facet` = quelle sonde riche cibler (défaut `"process"` si absent → rétro-compat supervision). - `readonly kind: typeof CLUSTER_PROBE_CTL_KIND` - `readonly op: "enrich" | "stop"` - `readonly pid: number` - `readonly facet?: ClusterProbeFacet` #### `IClusterProbeEnrich` ```ts interface IClusterProbeEnrich extends IClusterMessage ``` Ordre ciblé (master → worker, `CLUSTER_PROBE_ENRICH_KIND`). `enabled` = le worker doit-il joindre sa sonde riche à ses prochains reports ; `facet` = laquelle (défaut `"process"`). - `readonly kind: typeof CLUSTER_PROBE_ENRICH_KIND` - `readonly enabled: boolean` - `readonly facet?: ClusterProbeFacet` #### `IClusterRuntime` ```ts interface IClusterRuntime ``` Runtime cluster — abstrait `node:cluster` pour piloter fork/exit dans les tests sans forker de process. - `readonly isPrimary: boolean` - `fork(): IClusterWorker` - `onExit(cb: (worker: IClusterWorker, code: number | null, signal: string | null) => void): void` #### `IClusterWorker` ```ts interface IClusterWorker ``` Handle minimal d'un worker — sous-ensemble de `cluster.Worker` réellement utilisé (testable). - `readonly id: number` - `kill(signal?: NodeJS.Signals): void` — Envoie un signal au process worker (déconnecte + signale, cf `cluster.Worker.kill`). - `isDead(): boolean` — `true` si le process est mort. #### `IEventLoopDelay` ```ts interface IEventLoopDelay ``` Retard de la boucle d'événements sur un intervalle, en ms. - `meanMs: number` — Retard moyen : ce qu'un minuteur attend en plus de son échéance, en moyenne. - `maxMs: number` — Pire retard : le plus long blocage de la boucle sur l'intervalle. #### `IFirewallZoneView` ```ts interface IFirewallZoneView ``` Vue minimale d'une zone du firewall (`firewall.describe().zones`), résolue par duck-typing — le core n'importe jamais - `readonly name: string` - `readonly pattern: string` - `readonly security?: boolean` - `readonly authenticators?: ReadonlyArray` - `readonly allowsAnonymous?: boolean` #### `IInstanceErrorHealth` ```ts interface IInstanceErrorHealth ``` Santé **erreurs per-instance** — compteurs Syslog monotones (cf `Syslog.errorTotal` / `Syslog.criticTotal`). Permet une carte « erreurs par worker » + un taux d'erreur pod (delta côté lecteur). Lecture pure d'entiers, 0 scan du ring buffer. - `errorTotal: number` — Logs ERROR/CRITIC/ALERT/EMERGENCY cumulés (sévérité 0–3) (monotone). - `criticTotal: number` — Sous-ensemble CRITIQUE : CRITIC/ALERT/EMERGENCY (sévérité 0–2) (monotone). #### `IOrmLeanHealth` ```ts interface IOrmLeanHealth ``` Santé ORM **agrégée per-instance** (lean) — somme process-wide de tous les connecteurs enregistrés, dérivée des singletons `queryFlowMonitor` + `connectionMonitor` (0 ping, 0 `toSQL`, O(N connecteurs)). Rejoint le report de sonde du worker à chaque tick (≥ 1 s). Tous les cumuls sont **monotones** → débit/s dérivé côté lecteur (delta/ts, comme le CPU%). - `connectors: number` — Connecteurs ORM enregistrés (registre). - `connected: number` — Connecteurs actuellement connectés (`isConnected()`). - `assumed: number` — Parmi les connectés, ceux dont l'état est **SUPPOSÉ** et non constaté : leur adapter n'a aucun signal de cycle de vie à traduire (base embarquée, driver muet), donc « connecté » y veut seulement dire … - `queryTotal: number` — Requêtes ORM cumulées, tous connecteurs (monotone ; 0 si flux OFF en prod). - `slowTotal: number` — Requêtes lentes cumulées (au-dessus du seuil `slowMs`) (monotone). - `errorTotal: number` — Erreurs de connexion ORM cumulées (monotone). - `reconnectTotal: number` — Reconnexions ORM cumulées (monotone). - `maxEwmaMs: number | null` — Pire latence EWMA (ms) parmi les connecteurs (instantané), ou `null` si non observé. #### `IProbeWorker` ```ts interface IProbeWorker ``` Handle master-side d'un worker, vu par l'agrégateur — sous-ensemble **testable** de `cluster.Worker` (même seam que `IRelayWorker`). Prouve la collecte + la diffusion sans forker de process réel. - `readonly id: number` - `readonly pid: number` — PID OS du worker (`worker.process.pid`) — clé de ciblage du drill-down (Phase 2). - `send(msg: unknown): void` — Envoie un message IPC à CE worker (master → worker). - `onMessage(cb: (msg: unknown) => void): void` — Enregistre le récepteur des messages de CE worker (worker → master). #### `IProcessHealth` ```ts interface IProcessHealth ``` Santé PROCESS d'un worker — lue par `ProcessProbe`, agrégée par worker dans le snapshot pod (cf `ClusterProbeAggregator`). Volontairement **lean** (sérialisée par worker à chaque tick de report ≥ 1 s) : juste de quoi peupler une grille « salle des machines » (1 carte/worker). Les sondes lourdes (GC, heap-spaces, ctx-switches) restent au canal `nodefony:supervision` per-process pour le drill-down. - `pid: number` — PID du worker (= instanceId de la vue pod). - `uptime: number` — Uptime du process (secondes). - `cpuPercent: number` — % d'UN cœur sur l'intervalle (comme `top` : un Node mono-thread sature ~100). - `eventLoopMs: number` — Retard moyen de la boucle sur l'intervalle (ms), période d'échantillonnage retranchée : 0 sur une boucle libre. - `eventLoopMaxMs: number` — Pire retard de la boucle sur l'intervalle (ms) : le plus long blocage. - `eluUtilization: number` — Saturation de la boucle (ELU) sur l'intervalle, 0–1 (~1 = thread saturé). - `rss: number` — Resident Set Size (octets). - `heapUsed: number` — Heap V8 utilisé (octets). - `heapTotal: number` — Heap V8 total (octets). - `heapLimit: number` — Plafond heap V8 (octets, constant) — pour `heapUsed/heapLimit` (% avant OOM). - `external: number` — Mémoire hors-heap (buffers, etc.) (octets). - `ts: number` — Horodatage de la mesure. #### `IProcessRich` ```ts interface IProcessRich ``` Sonde process **riche** d'un worker — le complément du lean `IProcessHealth` pour le drill-down (Phase 2). Ne contient QUE ce qui manque au lean : pression GC, répartition du heap V8, ressources actives, ELU active/idle (ms) et changements de contexte OS. Fusionné côté front avec le lean déjà présent dans le snapshot pod. - `gc: { count: number; pauseMs: number; major: number; minor: number; }` — Pression GC sur l'intervalle (cycles, pause totale ms, majeurs/mineurs). - `heapSpaces: { name: string; used: number; size: number; }[]` — Répartition mémoire V8 par espace (new/old/code/large_object…), octets. - `handles: { total: number; byType: Record; }` — Ressources actives qui tiennent la boucle, total + par type. - `elu: { active: number; idle: number; }` — Saturation de la boucle sur l'intervalle (ms actifs / idle ; utilization est dans le lean). - `ctx: { voluntary: number; involuntary: number; }` — Changements de contexte OS sur l'intervalle (volontaires = cède, involontaires = préempté). - `loadavg: [ number, number, number ]` — Load average système (1/5/15 min). - `heapLimit: number` — Limite de heap V8 du process (octets) — constante. - `cpuCount: number` — Nombre de cœurs vus par le process — constante. - `ts: number` — Horodatage de la mesure. #### `IRelayWorker` ```ts interface IRelayWorker ``` Handle master-side d'un worker, vu par le relay — sous-ensemble **testable** de `cluster.Worker` réellement utilisé (même approche que `IClusterWorker` du ClusterManager). Permet de prouver le routage sans forker de process réel. - `readonly id: number` - `send(msg: unknown): void` — Envoie un message IPC à CE worker (master → worker). - `onMessage(cb: (msg: unknown) => void): void` — Enregistre le récepteur des messages de CE worker (worker → master). #### `PortShift` ```ts interface PortShift ``` Un décalage de ports CONSTATÉ : ce que la config demandait, ce qui sert. - `readonly desired: readonly number[]` — Ports écrits dans la configuration. - `readonly served: readonly number[]` — Ports réellement servis. #### `PortState` ```ts interface PortState ``` État de sonde d'un port serveur. - `readonly port: number` - `readonly listening: boolean` — `true` si un service accepte une connexion loopback sur ce port. #### `ReadyAnnouncement` ```ts interface ReadyAnnouncement ``` Ce qu'un démarrage annonce de l'endroit où il sert. - `readonly served: string` — Où taper — adresses publiées, ou à défaut les ports constatés. - `readonly shift: string | null` — Le décalage, en toutes lettres, ou `null` s'il n'y en a pas. #### `ResolveTopologyOptions` ```ts interface ResolveTopologyOptions ``` Seams de `resolveTopology` — tous injectables (résolution pure, testable sans FS). - `flag?: string` — CLI `--workers ` (chaîne Commander). - `env?: string` — Override `NF_WORKERS` (Docker/k8s). - `config?: WorkersSetting` — Valeur de la config app `cluster.workers` (le knob DevOps par défaut). #### `ResolveWorkerOptions` ```ts interface ResolveWorkerOptions ``` Options de `resolveWorkerCount` — tous les seams sont injectables pour les tests. - `requested?: number` — `--workers N` explicite. - `cgroupQuota?: number | null` — Quota cgroup pré-calculé (tests). - `availableParallelism?: number` — Parallélisme schedulable (tests). #### `RuntimeState` ```ts interface RuntimeState ``` Ce que le serveur publie sur lui-même une fois ses serveurs en écoute. - `pid: number` — PID du process qui écoute. - `ports: number[]` — Ports EFFECTIFS (après résolution d'un éventuel conflit). - `desiredPorts?: number[]` — Ports DÉSIRÉS (config) — diffèrent des effectifs si `auto` a dû décaler. - `urls?: string[]` — Adresses à VISER, telles qu'un client doit les écrire (`http://localhost:5151`). - `ts: number` — Horodatage d'écriture (`Date.now()`). #### `SupervisorLock` ```ts interface SupervisorLock ``` Ce que le serveur publie quand il demande au superviseur de patienter. - `pid: number` — PID du process qui tient le verrou — sert à détecter un verrou ORPHELIN. - `reason: string` — Pourquoi le rechargement est suspendu, en clair. - `detail?: string` — Précision libre (id de job, nom de migration…) — traçabilité. - `ts: number` — Horodatage de pose (`Date.now()`) — sert à l'expiration. #### `Topology` ```ts interface Topology ``` Résultat résolu de la topologie : nombre de workers + provenance. - `workers: number` — Nombre de workers à forker. - `source: TopologySource` — Provenance de la valeur (CLI `--workers`, env, config app, défaut). ### Types (8) #### `ClusterProbeFacet` ```ts type ClusterProbeFacet = "process" | "orm" ``` **Facette** de sonde riche ciblée par un ordre d'enrichissement (drill-down) : - `"process"` : sonde process riche (GC/heap-spaces/handles/ELU/ctx — `RichProcessProbe`) ; - `"orm"` : sonde ORM riche (diagnostic connexions + flux — `connection/health` + `flow`). #### `DevProcessRole` ```ts type DevProcessRole = "supervisor" | "server" | "vite" | "master" | "worker" ``` Rôle d'un process dans la topologie runtime Nodefony (dev OU prod OU cluster). `supervisor`/`master` = superviseurs (0 HTTP) ; `server`/`worker` = servent le HTTP ; `vite` = enfant dev (bundler). #### `FileReader` ```ts type FileReader = (path: string) => string | null ``` Lecteur de fichier système — abstrait pour rendre la résolution cgroup testable sans conteneur. Retourne le contenu du fichier, ou `null` si absent / illisible. #### `PortPolicy` ```ts type PortPolicy = "auto" | "strict" ``` Que faire si le port désiré est occupé — `servers.portPolicy`. #### `RuntimeMode` ```ts type RuntimeMode = "dev" | "prod" | "cluster" ``` Mode de runtime d'un process Nodefony — la « molette front » (cf modèle 2 molettes). `dev` = superviseur + serveur + Vite (HMR) ; `prod` = serveur mono-process foreground (1 pod) ; `cluster` = master superviseur + N workers. Distingue un `nodefony server` (prod) d'un `nodefony-dev-server` (dev) là où le seul `role` ne suffit pas. #### `TopologySource` ```ts type TopologySource = "flag" | "env" | "config" | "default" ``` D'où vient la valeur `workers` retenue — pour le log de diagnostic au boot. #### `TreeSignalOutcome` ```ts type TreeSignalOutcome = "group" | "forced-tree" | "single" | "gone" ``` Ce qu'un envoi de signal a RÉELLEMENT pu atteindre — le verdict, pas l'intention. #### `WorkersSetting` ```ts type WorkersSetting = number | "auto" ``` Réglage de topologie de l'application — la « molette » côté DevOps (remplace le rôle de `instances` dans l'ancien `pm2.config.ts`, retiré en cloud-native). --- [← Toutes les références d'API](../../)