Référence d'API — nodefony — service

stable

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

function clearRuntimeState(cwd: string): void

collectDevStatus#

function collectDevStatus(cwd: string, opts?: DiscoverOptions & DevObservationDeps): Promise<DevStatusReport>

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#

function computeBackoff(crashes: number, baseMs: number, maxMs: number): number

Calcule le délai de respawn d’un worker mort selon un backoff exponentiel.

defaultDevPorts#

function defaultDevPorts(cwd?: string, env?: Record<string, string>): number[]

Ports serveur à SONDER (status, stop, readiness, attente de libération).

detectPortShift#

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#

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#

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#

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#

function isClusterProbeCtl(m: unknown): m is IClusterProbeCtl

Type-guard d’un IClusterProbeCtl — narrowing sûr du canal IPC partagé.

isClusterProbeEnrich#

function isClusterProbeEnrich(m: unknown): m is IClusterProbeEnrich

Type-guard d’un IClusterProbeEnrich — narrowing sûr du canal IPC partagé.

isFrameworkZone#

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#

function isPortListening(port: number, host?: string, timeoutMs?: number): Promise<boolean>

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#

function loadClusterConfig(appPath?: string): Promise<WorkersSetting | null>

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#

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#

function readEventLoopDelay(histogram: Pick<ELDHistogram, "mean" | "max" | "count">, resolutionMs?: number): IEventLoopDelay

Lit le retard RÉEL de la boucle sur un histogramme monitorEventLoopDelay.

readOrmHealth#

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#

function readOrmRich(): Promise<unknown> | 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#

function readRuntimeState(cwd: string, opts?: { purgeStale?: boolean; }): RuntimeState | null

readSupervisorSuspension#

function readSupervisorSuspension(cwd: string): SupervisorLock | null

Le rechargement est-il suspendu, et pourquoi ?

readyAnnouncement#

function readyAnnouncement(state: RuntimeState | null, probedPorts?: readonly number[]): ReadyAnnouncement

Ce qu’un démarrage doit DIRE de l’endroit où il sert.

resolvePortPolicy#

function resolvePortPolicy(environment: string, explicit?: PortPolicy): PortPolicy

Politique de port effective.

resolveTopology#

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#

function resolveWorkerCount(opts?: ResolveWorkerOptions): number

Résout le nombre de workers à forker, dans l’ordre de priorité :

resumeSupervisor#

function resumeSupervisor(cwd: string): void

Rend la main au superviseur (fin de l’opération, quelle qu’en soit l’issue).

runtimeModes#

function runtimeModes(procs: readonly DevProcessInfo[]): Set<RuntimeMode>

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#

function servedUrl(scheme: "http" | "https", host: string, port: number): string

L’adresse où TAPER pour atteindre un serveur qui écoute sur host:port.

setOrmHealthProvider#

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#

function setOrmRichProvider(fn: () => Promise<unknown> | 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#

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#

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#

function writeRuntimeState(cwd: string, state: Omit<RuntimeState, "ts">): 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#

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#

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#

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#

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#

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#

const EVENT_LOOP_RESOLUTION_MS = 20

Période d’échantillonnage des histogrammes de retard de la boucle (ms).

Interfaces (29)#

ClusterManagerOptions#

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#

interface ClusterProbeAggregatorOptions

Options du ClusterProbeAggregator.

• intervalMs?: number — Cadence de diffusion du snapshot agrégé (ms).
• log?: (msg: string, severity?: Severity) => void

ClusterRelayOptions#

interface ClusterRelayOptions

Options du ClusterRelay. Effets de bord (log) injectables.

• log?: (msg: string, severity?: Severity) => void

ClusterScheduler#

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#

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#

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<Partial<Record<number, string>>> — 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#

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#

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#

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#

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#

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#

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#

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#

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#

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<string>
• readonly allowsAnonymous?: boolean

IInstanceErrorHealth#

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#

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#

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#

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#

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<string, number>; } — 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#

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#

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#

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#

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#

interface ResolveTopologyOptions

Seams de resolveTopology — tous injectables (résolution pure, testable sans FS).

• flag?: string — CLI --workers <n|auto> (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#

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#

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#

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#

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#

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#

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#

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#

type PortPolicy = "auto" | "strict"

Que faire si le port désiré est occupé — servers.portPolicy.

RuntimeMode#

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#

type TopologySource = "flag" | "env" | "config" | "default"

D’où vient la valeur workers retenue — pour le log de diagnostic au boot.

TreeSignalOutcome#

type TreeSignalOutcome = "group" | "forced-tree" | "single" | "gone"

Ce qu’un envoi de signal a RÉELLEMENT pu atteindre — le verdict, pas l’intention.

WorkersSetting#

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