@futdevpro/nts-dynamo 1.15.54 → 1.15.56

package/src/_services/core/memory-guard.service.ts

@@ -0,0 +1,281 @@
+import * as v8 from 'v8';
+
+import { DyFM_Error, DyFM_ErrorLevel, DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_SingletonServiceBase } from '../base/singleton.service-base';
+import { DyNTS_GlobalService } from './global.service';
+
+/**
+ * FR-193 (2026-06-15) — bedrock OOM korai-figyelmeztető heap-watchdog.
+ *
+ * MIÉRT: a Node heap-OOM (`--max-old-space-size` túllépés, pl. egy óriási JSON.parse)
+ * a process-t AZONNAL megöli — `process.on('uncaughtException')` NEM kapja el, így a
+ * crash pillanatában már nincs mód a hibát rögzíteni. Az EGYETLEN megbízható idő a
+ * rögzítésre a crash ELŐTT van. E watchdog periodikusan figyeli a heap-kihasználtságot,
+ * és amikor egy konfigurálható küszöböt átlép, TARTÓS rekordot hagy (DyFM_Log +
+ * `DyNTS_GlobalService.globalErrorHandler` → az Errors-sink, amit minden szerver megkap)
+ * — így egy OOM-hajlamos szerver NYOMOT hagy mielőtt elszáll, és a kuszob-atlepés
+ * lathato a dashboard-on / Discord-on.
+ *
+ * MIT NEM csinál: NEM állítja le/újraindítja a process-t (az a konténer-szintű
+ * `restart:` policy dolga), és NEM próbálja elkapni a fatal OOM-ot (nem lehet). Tisztán
+ * MEGFIGYELÉS + RÖGZÍTÉS + opcionális `onCritical` hook (amivel a fogyasztó terhet dobhat).
+ *
+ * Hiszterézis: a küszöböket CSAK állapot-VÁLTÁSkor jelzi (normal→warning→critical), és
+ * a `recoveryMargin`-nyit a warning ALÁ esve jelez 'recovered'-et — így nem spamel a
+ * küszöb körül oszcilláló heap.
+ *
+ * Használat (opt-in, mint a `DyNTS_Logs_Service`):
+ *   DyNTS_MemoryGuard.getInstance().install();              // default settings
+ *   DyNTS_MemoryGuard.getInstance().install({ onCritical }); // custom hook
+ * VAGY automatikusan: a base `App` startup feltelepíti, ha
+ *   `DyNTS_global_settings.memoryGuard.enabled === true` (alapértelmezés szerint igen).
+ */
+
+/** Egy MemoryGuard esemény — küszöb-átlépés vagy helyreállás. */
+export interface DyNTS_MemoryGuard_Event {
+  /** `warning` / `critical` küszöb-átlépés, vagy `recovered` (vissza normal-ba). */
+  level: 'warning' | 'critical' | 'recovered';
+  /** Heap használat MB-ban (`process.memoryUsage().heapUsed`). */
+  heapUsedMb: number;
+  /** Heap plafon MB-ban (`v8.getHeapStatistics().heap_size_limit` — a `--max-old-space-size`). */
+  heapLimitMb: number;
+  /** heapUsed / heapLimit * 100 (egész %-ra kerekítve). */
+  heapPct: number;
+  /** Resident Set Size MB-ban (teljes process-memória, heap + non-heap). */
+  rssMb: number;
+  /** External (C++ / Buffer) memória MB-ban. */
+  externalMb: number;
+  /** Esemény időbélyege (ISO). */
+  at: string;
+}
+
+/** `install()` opcionális override-jai (a `DyNTS_global_settings.memoryGuard` FÖLÉ). */
+export interface DyNTS_MemoryGuard_Config {
+  /** Poll-intervallum ms-ben. Default: 10000. */
+  pollIntervalMs?: number;
+  /** Warning küszöb a heap-plafon %-ában. Default: 85. */
+  heapWarningThreshold?: number;
+  /** Critical küszöb a heap-plafon %-ában. Default: 95. */
+  heapCriticalThreshold?: number;
+  /** A warning küszöb ALATTI margó %-ban a 'recovered'-hez (hiszterézis). Default: 10. */
+  recoveryMargin?: number;
+  /** Megőrzött események max száma (ring-buffer). Default: 100. */
+  maxHistoryCount?: number;
+  /** Hook, amit a `critical` küszöb átlépésekor hívunk (pl. terhelés-dobás). */
+  onCritical?: (event: DyNTS_MemoryGuard_Event) => void;
+}
+
+type DyNTS_MemoryGuard_State = 'normal' | 'warning' | 'critical';
+
+const BYTES_PER_MB: number = 1024 * 1024;
+
+export class DyNTS_MemoryGuard extends DyNTS_SingletonServiceBase {
+
+  static getInstance(): DyNTS_MemoryGuard {
+    return DyNTS_MemoryGuard.getSingletonInstance() as DyNTS_MemoryGuard;
+  }
+
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private installed: boolean = false;
+  private state: DyNTS_MemoryGuard_State = 'normal';
+
+  // Feloldott (effektív) konfiguráció — install()-kor töltjük.
+  private pollIntervalMs: number = 10000;
+  private warnPct: number = 85;
+  private critPct: number = 95;
+  private recoveryMargin: number = 10;
+  private maxHistoryCount: number = 100;
+  private onCritical?: (event: DyNTS_MemoryGuard_Event) => void;
+
+  private readonly history: DyNTS_MemoryGuard_Event[] = [];
+  private peakHeapPct: number = 0;
+  private peakRssMb: number = 0;
+
+  protected constructor() {
+    super();
+  }
+
+  /**
+   * Elindítja a heap-watchdogot. Idempotens (többszöri hívás no-op). A `config`
+   * felülírja a `DyNTS_global_settings.memoryGuard` értékeit, ami a beépített
+   * defaultokat írja felül. SOHA nem dob — egy figyelő-réteg nem dönthet be egy
+   * szervert (minden hiba try/catch-elt + descriptive-en logolt).
+   */
+  install(config?: DyNTS_MemoryGuard_Config): void {
+    if (this.installed) { return; }
+
+    try {
+      const g: NonNullable<typeof DyNTS_global_settings.memoryGuard> =
+        DyNTS_global_settings.memoryGuard ?? { enabled: true };
+
+      this.pollIntervalMs = config?.pollIntervalMs ?? g.pollIntervalMs ?? 10000;
+      this.warnPct = config?.heapWarningThreshold ?? g.heapWarningThreshold ?? 85;
+      this.critPct = config?.heapCriticalThreshold ?? g.heapCriticalThreshold ?? 95;
+      this.recoveryMargin = config?.recoveryMargin ?? g.recoveryMargin ?? 10;
+      this.maxHistoryCount = config?.maxHistoryCount ?? g.maxHistoryCount ?? 100;
+      this.onCritical = config?.onCritical;
+
+      this.installed = true;
+      this.timer = setInterval((): void => { this.poll(); }, this.pollIntervalMs);
+      // unref(): a watchdog-timer NE tartsa életben a process-t önmagában (graceful
+      // exit-kor a Node ki tud lépni a függő interval ellenére is).
+      if (typeof this.timer.unref === 'function') { this.timer.unref(); }
+
+      DyFM_Log.info(
+        `[DyNTS_MemoryGuard] installed — poll ${this.pollIntervalMs}ms, ` +
+        `warn ${this.warnPct}%, crit ${this.critPct}% (heap limit ` +
+        `${Math.round(this.getHeapLimitBytes() / BYTES_PER_MB)}MB)`,
+      );
+    } catch (err: unknown) {
+      // Telepítési hiba SEM lehet fatal — a guard hiánya nem ér annyit, hogy a
+      // szerver-indulást megakassza.
+      DyFM_Log.warn('[DyNTS_MemoryGuard] install failed (non-fatal):', err);
+    }
+  }
+
+  /** A heap-plafon byte-ban (`--max-old-space-size`). Külön metódus a spec-mockoláshoz. */
+  private getHeapLimitBytes(): number {
+    return v8.getHeapStatistics().heap_size_limit;
+  }
+
+  /**
+   * Egy poll-ciklus: kiolvassa a heap-kihasználtságot, frissíti a csúcsokat, és a
+   * hiszterézis-állapotgép szerint esemény-átlépéskor rögzít + logol. SOHA nem dob.
+   */
+  private poll(): void {
+    try {
+      const limitBytes: number = this.getHeapLimitBytes();
+      if (!limitBytes || limitBytes <= 0) { return; }
+
+      const mu: NodeJS.MemoryUsage = process.memoryUsage();
+      const pct: number = (mu.heapUsed / limitBytes) * 100;
+
+      const rssMb: number = mu.rss / BYTES_PER_MB;
+      if (pct > this.peakHeapPct) { this.peakHeapPct = pct; }
+      if (rssMb > this.peakRssMb) { this.peakRssMb = rssMb; }
+
+      // Hiszterézis-állapotgép — esemény CSAK állapot-váltáskor.
+      const prev: DyNTS_MemoryGuard_State = this.state;
+      let next: DyNTS_MemoryGuard_State = prev;
+
+      if (pct >= this.critPct) {
+        next = 'critical';
+      } else if (pct >= this.warnPct && prev === 'normal') {
+        next = 'warning';
+      } else if (pct <= this.warnPct - this.recoveryMargin) {
+        next = 'normal';
+      }
+      // Egyébként marad a jelenlegi állapot (hiszterézis-sáv) — nincs re-emit.
+
+      if (next === prev) { return; }
+      this.state = next;
+
+      const event: DyNTS_MemoryGuard_Event = {
+        level:       next === 'normal' ? 'recovered' : next,
+        heapUsedMb:  Math.round(mu.heapUsed / BYTES_PER_MB),
+        heapLimitMb: Math.round(limitBytes / BYTES_PER_MB),
+        heapPct:     Math.round(pct),
+        rssMb:       Math.round(rssMb),
+        externalMb:  Math.round((mu.external ?? 0) / BYTES_PER_MB),
+        at:          new Date().toISOString(),
+      };
+
+      this.recordEvent(event);
+    } catch (err: unknown) {
+      // Poll-hiba sosem fatal — a következő tick újrapróbálja.
+      DyFM_Log.warn('[DyNTS_MemoryGuard] poll error (non-fatal):', err);
+    }
+  }
+
+  /** Esemény ring-bufferbe + log + (warning/critical esetén) tartós error-sink. */
+  private recordEvent(event: DyNTS_MemoryGuard_Event): void {
+    this.history.push(event);
+    while (this.history.length > this.maxHistoryCount) { this.history.shift(); }
+
+    const summary: string =
+      `heap ${event.heapPct}% (${event.heapUsedMb}/${event.heapLimitMb}MB), rss ${event.rssMb}MB`;
+
+    if (event.level === 'recovered') {
+      DyFM_Log.success(`[DyNTS_MemoryGuard] RECOVERED — ${summary}`);
+      return;
+    }
+
+    if (event.level === 'critical') {
+      DyFM_Log.H_error(`[DyNTS_MemoryGuard] CRITICAL heap pressure — ${summary} — OOM imminent`);
+    } else {
+      DyFM_Log.warn(`[DyNTS_MemoryGuard] WARNING heap pressure — ${summary}`);
+    }
+
+    // Tartós rögzítés a központi error-sinkbe (Errors-rendszer + Discord, ha bekötve).
+    try {
+      DyNTS_GlobalService.globalErrorHandler?.(
+        new DyFM_Error({
+          errorCode:
+            `${DyNTS_global_settings.systemShortCodeName ?? 'DyNTS'}|DyNTS-MG0-HEAP-${event.level.toUpperCase()}`,
+          message:
+            `Heap pressure ${event.level.toUpperCase()}: ${summary}. ` +
+            `Process approaching the --max-old-space-size ceiling — OOM crash risk.`,
+          additionalContent: { memoryGuardEvent: event, peakHeapPct: Math.round(this.peakHeapPct) },
+          systemVersion: DyNTS_global_settings.systemVersion,
+          level: event.level === 'critical' ? DyFM_ErrorLevel.critical : DyFM_ErrorLevel.warning,
+        }),
+      );
+    } catch (sinkErr: unknown) {
+      DyFM_Log.warn('[DyNTS_MemoryGuard] error-sink record failed (non-fatal):', sinkErr);
+    }
+
+    if (event.level === 'critical' && this.onCritical) {
+      try {
+        this.onCritical(event);
+      } catch (hookErr: unknown) {
+        DyFM_Log.warn('[DyNTS_MemoryGuard] onCritical hook threw (non-fatal):', hookErr);
+      }
+    }
+  }
+
+  /** A megőrzött események (legrégebbi → legújabb). Csak olvasásra. */
+  getHistory(): DyNTS_MemoryGuard_Event[] {
+    return this.history.slice();
+  }
+
+  /** Pillanatnyi állapot + csúcsok diagnosztikához (pl. egy status-endpoint). */
+  getStatus(): {
+    installed: boolean;
+    state: DyNTS_MemoryGuard_State;
+    peakHeapPct: number;
+    peakRssMb: number;
+    eventCount: number;
+  } {
+    return {
+      installed:   this.installed,
+      state:       this.state,
+      peakHeapPct: Math.round(this.peakHeapPct),
+      peakRssMb:   Math.round(this.peakRssMb),
+      eventCount:  this.history.length,
+    };
+  }
+
+  /** Telepítve van-e a watchdog. */
+  isInstalled(): boolean {
+    return this.installed;
+  }
+
+  /**
+   * Leállítja a watchdogot + visszaállítja az állapotot. Graceful shutdown-hoz ÉS a
+   * spec-ek `afterEach`-éhez (a singleton-state ne szivárogjon a tesztek közt).
+   */
+  _teardownForTesting(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.installed = false;
+    this.state = 'normal';
+    this.history.length = 0;
+    this.peakHeapPct = 0;
+    this.peakRssMb = 0;
+    this.onCritical = undefined;
+  }
+}

package/src/_services/server/app.server.ts

@@ -52,6 +52,7 @@ import {
 } from '../../_models/interfaces/cors-settings.interface';
 import { DyNTS_SingletonService } from '../base/singleton.service';
 import { DyNTS_GlobalService } from '../core/global.service';
+import { DyNTS_MemoryGuard } from '../core/memory-guard.service';
 import { DyNTS_RoutingModule } from '../route/routing-module.service';
 import { DyNTS_getStarRoute } from '../../_collections/star.controller';
 
@@ -541,6 +542,18 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
         });
       }
 
+      // FR-193 — bedrock OOM korai-figyelmeztetés: feltelepítjük a heap-watchdogot, ha
+      // engedélyezve (DyNTS_global_settings.memoryGuard.enabled, default true). Biztonságos:
+      // a guard egy könnyű setInterval, ami SOHA nem dob; csak near-OOM küszöböknél hagy
+      // tartós nyomot az error-sinkbe, mielőtt a fatal heap-OOM megölné a process-t.
+      try {
+        if (DyNTS_global_settings.memoryGuard?.enabled) {
+          DyNTS_MemoryGuard.getInstance().install();
+        }
+      } catch (memoryGuardError: unknown) {
+        DyFM_Log.warn('[DyNTS_MemoryGuard] auto-install skipped (non-fatal):', memoryGuardError);
+      }
+
       if (!extended) {
         await this.ready();
 

package/src/index.ts

@@ -72,6 +72,7 @@ export * from './_services/core/auth.service';
 
 export * from './_services/core/email.service';
 export * from './_services/core/global.service';
+export * from './_services/core/memory-guard.service';
 
 export * from './_services/core/service-collection.service';