@futdevpro/nts-dynamo 1.15.68 → 1.15.70

package/src/_collections/global-settings.const.ts

@@ -1,89 +1,89 @@
-
-
-import { DyNTS_RouteSecurity } from '../_enums/route-security.enum';
-import { DyNTS_Global_Settings } from '../_models/interfaces/global-settings.interface';
-import { DyNTS_SocketSecurity } from '../_modules/socket/_enums/socket-security.enum';
-import { DyNTS_getEnvironment_settings } from './get-environment-settings.util';
-
-/**
- * Default configuration used across the NodeTS framework.
- * These values can be overridden when bootstrapping the server.
- */
-export const DyNTS_global_settings: DyNTS_Global_Settings = {
-  baseUrl: '/api',
-  systemVersion: 'unknown-version',
-  defaultRouteSecurity: DyNTS_RouteSecurity.open,
-  defaultSocketSecurity: DyNTS_SocketSecurity.open,
-  
-  defaultPageSize: 10,
-  archiveListAfter: 100,
-  env_settings: DyNTS_getEnvironment_settings(),
-  
-  autoResolveEndpointCirculationErrors: true,
-  compactErrorResponse: true,
-
-  log_settings: {
-    highDetailedLogs: false,
-    
-    setup: false,
-  
-    request: true,
-    requestsContent: false,
-    responseContent: false,
-    requestStackLocation: false,
-  
-    socket_allEvents: true,
-    socket_mainEvents: true,
-    socket_eventContent: false,
-  
-    api_events: true,
-    api_requestContents: false,
-    api_requestSettings: false,
-    api_responseContents: false,
-    api_errors: true,
-  
-    detailedErrors: false,
-
-    server_debug: false,
-
-    logs_endpoint: {
-      enabled: false,
-      maxEntries: 2000,
-    },
-  },
-
-  autoResearchIssues: true,
-
-  // Auth-service kötelező alapból (régi viselkedés). Public / no-auth szervereknél
-  // `auth_settings.optional = true` → getAuthService() undefined-ot ad dobás helyett,
-  // és a startup 'Authentication Service missing!' warn is elmarad.
-  auth_settings: {
-    optional: false,
-  },
-
-  bot_settings: null,
-
-  openAi_settings: null,
-
-  dias_settings: null,
-
-  assistant_settings: null,
-
-  docChunking: {
-    maxChunkSize: 1000,
-    maxChunkCount: 1000,
-  },
-
-  // FR-193 — bedrock OOM korai-figyelmeztető heap-watchdog. Default-on: minden nts-szerver
-  // megkapja a heap-nyomás-figyelést a base App startup-ban (lásd DyNTS_MemoryGuard). Csak
-  // MEGFIGYELÉS + tartós rögzítés a near-OOM küszöböknél — nem változtat a viselkedésen.
-  memoryGuard: {
-    enabled: true,
-    pollIntervalMs: 10000,
-    heapWarningThreshold: 85,
-    heapCriticalThreshold: 95,
-    recoveryMargin: 10,
-    maxHistoryCount: 100,
-  },
-};
-
+
+
+import { DyNTS_RouteSecurity } from '../_enums/route-security.enum';
+import { DyNTS_Global_Settings } from '../_models/interfaces/global-settings.interface';
+import { DyNTS_SocketSecurity } from '../_modules/socket/_enums/socket-security.enum';
+import { DyNTS_getEnvironment_settings } from './get-environment-settings.util';
+
+/**
+ * Default configuration used across the NodeTS framework.
+ * These values can be overridden when bootstrapping the server.
+ */
+export const DyNTS_global_settings: DyNTS_Global_Settings = {
+  baseUrl: '/api',
+  systemVersion: 'unknown-version',
+  defaultRouteSecurity: DyNTS_RouteSecurity.open,
+  defaultSocketSecurity: DyNTS_SocketSecurity.open,
+  
+  defaultPageSize: 10,
+  archiveListAfter: 100,
+  env_settings: DyNTS_getEnvironment_settings(),
+  
+  autoResolveEndpointCirculationErrors: true,
+  compactErrorResponse: true,
+
+  log_settings: {
+    highDetailedLogs: false,
+    
+    setup: false,
+  
+    request: true,
+    requestsContent: false,
+    responseContent: false,
+    requestStackLocation: false,
+  
+    socket_allEvents: true,
+    socket_mainEvents: true,
+    socket_eventContent: false,
+  
+    api_events: true,
+    api_requestContents: false,
+    api_requestSettings: false,
+    api_responseContents: false,
+    api_errors: true,
+  
+    detailedErrors: false,
+
+    server_debug: false,
+
+    logs_endpoint: {
+      enabled: false,
+      maxEntries: 2000,
+    },
+  },
+
+  autoResearchIssues: true,
+
+  // Auth-service kötelező alapból (régi viselkedés). Public / no-auth szervereknél
+  // `auth_settings.optional = true` → getAuthService() undefined-ot ad dobás helyett,
+  // és a startup 'Authentication Service missing!' warn is elmarad.
+  auth_settings: {
+    optional: false,
+  },
+
+  bot_settings: null,
+
+  openAi_settings: null,
+
+  dias_settings: null,
+
+  assistant_settings: null,
+
+  docChunking: {
+    maxChunkSize: 1000,
+    maxChunkCount: 1000,
+  },
+
+  // FR-193 — bedrock OOM korai-figyelmeztető heap-watchdog. Default-on: minden nts-szerver
+  // megkapja a heap-nyomás-figyelést a base App startup-ban (lásd DyNTS_MemoryGuard). Csak
+  // MEGFIGYELÉS + tartós rögzítés a near-OOM küszöböknél — nem változtat a viselkedésen.
+  memoryGuard: {
+    enabled: true,
+    pollIntervalMs: 10000,
+    heapWarningThreshold: 85,
+    heapCriticalThreshold: 95,
+    recoveryMargin: 10,
+    maxHistoryCount: 100,
+  },
+};
+

package/src/_collections/mongo-reconnect-guard.util.spec.ts

@@ -1,52 +1,52 @@
-import { shouldForceMongoReconnect, MongoReconnectState } from './mongo-reconnect-guard.util';
-
-/**
- * A Mongo reconnect-guard PURE döntés-magjának unit-tesztjei. A helyesség kritikus, mert ez dönti
- * el, hogy egy futó service force-reconnectolja-e a Mongo-kapcsolatát (disconnect+connect →
- * re-resolve). Healthy connection-t SOHA nem szabad bántani; csak tartós nem-connected + grace +
- * cooldown letelt esetén szabad force-reconnectolni.
- */
-describe('| mongo-reconnect-guard shouldForceMongoReconnect', () => {
-  const base: MongoReconnectState = {
-    readyState: 0,
-    msSinceUnhealthy: 60_000,         // 60s unhealthy (a 30s grace fölött)
-    unhealthyGraceMs: 30_000,
-    reconnectInFlight: false,
-    msSinceLastReconnect: Number.POSITIVE_INFINITY,
-    reconnectCooldownMs: 20_000,
-  };
-
-  it('| connected (readyState=1) → SOHA nem reconnect (a healthy connection-t nem bántjuk)', () => {
-    expect(shouldForceMongoReconnect({ ...base, readyState: 1 }).reconnect).toBe(false);
-  });
-
-  it('| connecting (readyState=2) → nem reconnect (hagyjuk a drivert befejezni)', () => {
-    expect(shouldForceMongoReconnect({ ...base, readyState: 2 }).reconnect).toBe(false);
-  });
-
-  it('| disconnected + grace + cooldown letelt + nincs in-flight → RECONNECT', () => {
-    const d = shouldForceMongoReconnect({ ...base, readyState: 0 });
-    expect(d.reconnect).toBe(true);
-    expect(d.reason).toContain('re-resolve');
-  });
-
-  it('| disconnecting (readyState=3) ugyanígy → RECONNECT (tartós nem-connected)', () => {
-    expect(shouldForceMongoReconnect({ ...base, readyState: 3 }).reconnect).toBe(true);
-  });
-
-  it('| grace-en BELÜL → nem reconnect (hagyjuk a driver saját reconnect-jét előbb)', () => {
-    expect(shouldForceMongoReconnect({ ...base, msSinceUnhealthy: 10_000 }).reconnect).toBe(false);
-  });
-
-  it('| cooldown-on belül (frissen reconnectoltunk) → nem reconnect (anti-thrash)', () => {
-    expect(shouldForceMongoReconnect({ ...base, msSinceLastReconnect: 5_000 }).reconnect).toBe(false);
-  });
-
-  it('| már van in-flight reconnect → nem indítunk másikat', () => {
-    expect(shouldForceMongoReconnect({ ...base, reconnectInFlight: true }).reconnect).toBe(false);
-  });
-
-  it('| pontosan a grace-küszöbön (msSinceUnhealthy === grace) → RECONNECT', () => {
-    expect(shouldForceMongoReconnect({ ...base, msSinceUnhealthy: 30_000, unhealthyGraceMs: 30_000 }).reconnect).toBe(true);
-  });
-});
+import { shouldForceMongoReconnect, MongoReconnectState } from './mongo-reconnect-guard.util';
+
+/**
+ * A Mongo reconnect-guard PURE döntés-magjának unit-tesztjei. A helyesség kritikus, mert ez dönti
+ * el, hogy egy futó service force-reconnectolja-e a Mongo-kapcsolatát (disconnect+connect →
+ * re-resolve). Healthy connection-t SOHA nem szabad bántani; csak tartós nem-connected + grace +
+ * cooldown letelt esetén szabad force-reconnectolni.
+ */
+describe('| mongo-reconnect-guard shouldForceMongoReconnect', () => {
+  const base: MongoReconnectState = {
+    readyState: 0,
+    msSinceUnhealthy: 60_000,         // 60s unhealthy (a 30s grace fölött)
+    unhealthyGraceMs: 30_000,
+    reconnectInFlight: false,
+    msSinceLastReconnect: Number.POSITIVE_INFINITY,
+    reconnectCooldownMs: 20_000,
+  };
+
+  it('| connected (readyState=1) → SOHA nem reconnect (a healthy connection-t nem bántjuk)', () => {
+    expect(shouldForceMongoReconnect({ ...base, readyState: 1 }).reconnect).toBe(false);
+  });
+
+  it('| connecting (readyState=2) → nem reconnect (hagyjuk a drivert befejezni)', () => {
+    expect(shouldForceMongoReconnect({ ...base, readyState: 2 }).reconnect).toBe(false);
+  });
+
+  it('| disconnected + grace + cooldown letelt + nincs in-flight → RECONNECT', () => {
+    const d = shouldForceMongoReconnect({ ...base, readyState: 0 });
+    expect(d.reconnect).toBe(true);
+    expect(d.reason).toContain('re-resolve');
+  });
+
+  it('| disconnecting (readyState=3) ugyanígy → RECONNECT (tartós nem-connected)', () => {
+    expect(shouldForceMongoReconnect({ ...base, readyState: 3 }).reconnect).toBe(true);
+  });
+
+  it('| grace-en BELÜL → nem reconnect (hagyjuk a driver saját reconnect-jét előbb)', () => {
+    expect(shouldForceMongoReconnect({ ...base, msSinceUnhealthy: 10_000 }).reconnect).toBe(false);
+  });
+
+  it('| cooldown-on belül (frissen reconnectoltunk) → nem reconnect (anti-thrash)', () => {
+    expect(shouldForceMongoReconnect({ ...base, msSinceLastReconnect: 5_000 }).reconnect).toBe(false);
+  });
+
+  it('| már van in-flight reconnect → nem indítunk másikat', () => {
+    expect(shouldForceMongoReconnect({ ...base, reconnectInFlight: true }).reconnect).toBe(false);
+  });
+
+  it('| pontosan a grace-küszöbön (msSinceUnhealthy === grace) → RECONNECT', () => {
+    expect(shouldForceMongoReconnect({ ...base, msSinceUnhealthy: 30_000, unhealthyGraceMs: 30_000 }).reconnect).toBe(true);
+  });
+});

package/src/_collections/mongo-reconnect-guard.util.ts

@@ -1,172 +1,172 @@
-import { DyFM_Log, second } from '@futdevpro/fsm-dynamo';
-
-/**
- * DyNTS Mongo reconnect-guard (2026-06-20) — TÚLÉLI a Mongo-konténer IP-VÁLTÁSÁT.
- *
- * PROBLÉMA (élőben, 2026-06-19): a MongoDB-driver a hostnevet (`mongodb`) connect-kor EGYSZER
- * resolválja és cache-eli az IP-t (pl. 172.18.0.20); standalone-nál disconnect után UGYANAZT az
- * IP-t pingeli, NEM re-resolve-ol. Ha a Mongo-konténert recreate-elik (új docker-network IP), a
- * driver örökre a HALOTT IP-n lóg → `connect ECONNREFUSED <oldIp>:29017` + `buffering timed out`,
- * és a service magától SOHA nem áll vissza (csak külső restart-tal). Ez a 2026-06-19 incidens fél
- * test-stacket levitt (auth/ftp/helocia/futdevpro/… mind a régi Mongo-IP-n ragadt).
- *
- * MEGOLDÁS: a guard figyeli a `mongoose.connection.readyState`-et; ha TARTÓSAN nem-connected
- * (a driver saját reconnect-grace-e UTÁN is), **TELJES `disconnect()` + `connect()`-et** csinál
- * → ÚJ MongoClient → ÚJ DNS-resolve → új IP → reconnect. Így minden DyNTS_App-service magától
- * túléli a Mongo IP-váltását, KÜLSŐ beavatkozás nélkül. Best-effort, sose dob; csak konténer-IP-
- * frissítés, NEM törli/írja az adatot.
- *
- * SAFE always-on: egy app újracsatlakozása a SAJÁT DB-jéhez korrekt, nem-destruktív viselkedés
- * (nincs az infra-restart-érzékenység, ami a külső watchdog-oknál — FR-229/237). Csak akkor
- * avatkozik be, ha readyState !== 1 a grace + cooldown letelte UTÁN is; healthy connection-t (===1)
- * SOHA nem bánt.
- *
- * A döntés-mag (`shouldForceMongoReconnect`) PURE + unit-tesztelt; a futtató injektált dep-ekkel
- * dolgozik (readyState-olvasás / reconnect / log) a tesztelhetőségért.
- */
-
-/** A pure döntés inputja (minden numerikus → determinisztikus + tesztelhető). */
-export interface MongoReconnectState {
-  /** mongoose.connection.readyState: 0=disconnected, 1=connected, 2=connecting, 3=disconnecting. */
-  readyState: number;
-  /** Mióta (ms) nem-connected a readyState (0, ha épp connected). */
-  msSinceUnhealthy: number;
-  /** Grace: ennyi ideig hagyjuk a drivert SAJÁT magát visszahozni, mielőtt force-reconnectolnánk. */
-  unhealthyGraceMs: number;
-  /** Épp folyamatban van-e már egy force-reconnect (ne torlódjon). */
-  reconnectInFlight: boolean;
-  /** Mióta (ms) volt az utolsó force-reconnect (Infinity, ha még nem volt). */
-  msSinceLastReconnect: number;
-  /** Két force-reconnect közti minimum (anti-thrash). */
-  reconnectCooldownMs: number;
-}
-
-/** A pure döntés eredménye. */
-export interface MongoReconnectDecision {
-  reconnect: boolean;
-  reason: string;
-}
-
-/**
- * PURE döntés: kell-e force-reconnect. Healthy (===1) / connecting (===2) / in-flight / grace-en
- * vagy cooldown-on belül → NEM. Csak tartós nem-connected (disconnected/disconnecting) + grace és
- * cooldown letelt + nincs in-flight → IGEN.
- */
-export function shouldForceMongoReconnect(s: MongoReconnectState): MongoReconnectDecision {
-  if (s.readyState === 1) {
-    return { reconnect: false, reason: 'connected (readyState=1)' };
-  }
-  if (s.readyState === 2) {
-    return { reconnect: false, reason: 'connecting (readyState=2) — letting the driver finish' };
-  }
-  if (s.reconnectInFlight) {
-    return { reconnect: false, reason: 'a force-reconnect is already in flight' };
-  }
-  if (s.msSinceUnhealthy < s.unhealthyGraceMs) {
-    return {
-      reconnect: false,
-      reason: `unhealthy for ${Math.round(s.msSinceUnhealthy / 1000)}s (< ${Math.round(s.unhealthyGraceMs / 1000)}s grace) — letting the driver self-heal first`,
-    };
-  }
-  if (s.msSinceLastReconnect < s.reconnectCooldownMs) {
-    return {
-      reconnect: false,
-      reason: `last force-reconnect ${Math.round(s.msSinceLastReconnect / 1000)}s ago (< ${Math.round(s.reconnectCooldownMs / 1000)}s cooldown)`,
-    };
-  }
-  return {
-    reconnect: true,
-    reason: `Mongo connection unhealthy (readyState=${s.readyState}) for ${Math.round(s.msSinceUnhealthy / 1000)}s past grace — forcing disconnect+connect to re-resolve the host IP`,
-  };
-}
-
-/** Injektált függőségek a futtatóhoz (best-effort; a futtató sose dob). */
-export interface MongoReconnectGuardDeps {
-  /** A jelenlegi `mongoose.connection.readyState`. */
-  getReadyState: () => number;
-  /**
-   * Force-reconnect: `disconnect()` majd `connect(uri, opts)` — ÚJ MongoClient → ÚJ DNS-resolve.
-   * Dobhat (a connect elbukhat, ha a Mongo épp tényleg down) — a futtató elkapja.
-   */
-  reconnect: () => Promise<void>;
-  /** Log. */
-  log: (msg: string) => void;
-  /** Tick-intervallum (ms). Default 10s. */
-  intervalMs?: number;
-  /** Grace, amíg a driver saját reconnect-jét várjuk (ms). Default 30s. */
-  unhealthyGraceMs?: number;
-  /** Cooldown két force-reconnect közt (ms). Default 20s. */
-  reconnectCooldownMs?: number;
-}
-
-/**
- * Elindítja a periodikus reconnect-guard-ot. A visszaadott függvény leállítja (teszt/teardown).
- * `.unref()` — nem tartja életben az event-loop-ot.
- */
-export function startMongoReconnectGuard(deps: MongoReconnectGuardDeps): () => void {
-  const intervalMs: number = deps.intervalMs ?? 10 * second;
-  const unhealthyGraceMs: number = deps.unhealthyGraceMs ?? 30 * second;
-  const reconnectCooldownMs: number = deps.reconnectCooldownMs ?? 20 * second;
-
-  let unhealthySinceMs: number | null = null;
-  let lastReconnectAtMs: number | null = null;
-  let inFlight: boolean = false;
-  let ticking: boolean = false;
-
-  const tick = async (): Promise<void> => {
-    if (ticking) { return; }
-    ticking = true;
-    try {
-      const nowMs: number = Date.now();
-      const readyState: number = deps.getReadyState();
-
-      if (readyState === 1) {
-        if (unhealthySinceMs !== null) {
-          deps.log(`[mongo-reconnect-guard] Mongo connection healthy again (was unhealthy ${Math.round((nowMs - unhealthySinceMs) / 1000)}s)`);
-        }
-        unhealthySinceMs = null;
-        return;
-      }
-
-      // Nem-connected: indítsuk/folytassuk az unhealthy-órát.
-      if (unhealthySinceMs === null) { unhealthySinceMs = nowMs; }
-
-      const decision: MongoReconnectDecision = shouldForceMongoReconnect({
-        readyState: readyState,
-        msSinceUnhealthy: nowMs - unhealthySinceMs,
-        unhealthyGraceMs: unhealthyGraceMs,
-        reconnectInFlight: inFlight,
-        msSinceLastReconnect: lastReconnectAtMs === null ? Number.POSITIVE_INFINITY : nowMs - lastReconnectAtMs,
-        reconnectCooldownMs: reconnectCooldownMs,
-      });
-
-      if (!decision.reconnect) { return; }
-
-      deps.log(`[mongo-reconnect-guard] ${decision.reason}`);
-      inFlight = true;
-      lastReconnectAtMs = nowMs;
-      try {
-        await deps.reconnect();
-        deps.log('[mongo-reconnect-guard] force-reconnect dispatched ✓ (re-resolved host; awaiting connection open)');
-      } catch (e: unknown) {
-        // A connect elbukhat, ha a Mongo épp tényleg elérhetetlen — nem baj, a következő tick
-        // (cooldown után) újrapróbál; amint a Mongo új IP-n elérhető, a re-resolve becsatlakozik.
-        deps.log(`[mongo-reconnect-guard] force-reconnect attempt failed (will retry after cooldown): ${e instanceof Error ? e.message : String(e)}`);
-      } finally {
-        inFlight = false;
-      }
-    } catch (e: unknown) {
-      deps.log(`[mongo-reconnect-guard] tick error (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
-    } finally {
-      ticking = false;
-    }
-  };
-
-  const handle: NodeJS.Timeout = setInterval((): void => { void tick(); }, intervalMs);
-  if (typeof handle.unref === 'function') { handle.unref(); }
-  DyFM_Log.info(
-    `[mongo-reconnect-guard] started — check every ${Math.round(intervalMs / 1000)}s, `
-    + `force disconnect+reconnect after ${Math.round(unhealthyGraceMs / 1000)}s sustained-unhealthy (re-resolves host IP), cooldown ${Math.round(reconnectCooldownMs / 1000)}s`,
-  );
-  return (): void => { clearInterval(handle); };
-}
+import { DyFM_Log, second } from '@futdevpro/fsm-dynamo';
+
+/**
+ * DyNTS Mongo reconnect-guard (2026-06-20) — TÚLÉLI a Mongo-konténer IP-VÁLTÁSÁT.
+ *
+ * PROBLÉMA (élőben, 2026-06-19): a MongoDB-driver a hostnevet (`mongodb`) connect-kor EGYSZER
+ * resolválja és cache-eli az IP-t (pl. 172.18.0.20); standalone-nál disconnect után UGYANAZT az
+ * IP-t pingeli, NEM re-resolve-ol. Ha a Mongo-konténert recreate-elik (új docker-network IP), a
+ * driver örökre a HALOTT IP-n lóg → `connect ECONNREFUSED <oldIp>:29017` + `buffering timed out`,
+ * és a service magától SOHA nem áll vissza (csak külső restart-tal). Ez a 2026-06-19 incidens fél
+ * test-stacket levitt (auth/ftp/helocia/futdevpro/… mind a régi Mongo-IP-n ragadt).
+ *
+ * MEGOLDÁS: a guard figyeli a `mongoose.connection.readyState`-et; ha TARTÓSAN nem-connected
+ * (a driver saját reconnect-grace-e UTÁN is), **TELJES `disconnect()` + `connect()`-et** csinál
+ * → ÚJ MongoClient → ÚJ DNS-resolve → új IP → reconnect. Így minden DyNTS_App-service magától
+ * túléli a Mongo IP-váltását, KÜLSŐ beavatkozás nélkül. Best-effort, sose dob; csak konténer-IP-
+ * frissítés, NEM törli/írja az adatot.
+ *
+ * SAFE always-on: egy app újracsatlakozása a SAJÁT DB-jéhez korrekt, nem-destruktív viselkedés
+ * (nincs az infra-restart-érzékenység, ami a külső watchdog-oknál — FR-229/237). Csak akkor
+ * avatkozik be, ha readyState !== 1 a grace + cooldown letelte UTÁN is; healthy connection-t (===1)
+ * SOHA nem bánt.
+ *
+ * A döntés-mag (`shouldForceMongoReconnect`) PURE + unit-tesztelt; a futtató injektált dep-ekkel
+ * dolgozik (readyState-olvasás / reconnect / log) a tesztelhetőségért.
+ */
+
+/** A pure döntés inputja (minden numerikus → determinisztikus + tesztelhető). */
+export interface MongoReconnectState {
+  /** mongoose.connection.readyState: 0=disconnected, 1=connected, 2=connecting, 3=disconnecting. */
+  readyState: number;
+  /** Mióta (ms) nem-connected a readyState (0, ha épp connected). */
+  msSinceUnhealthy: number;
+  /** Grace: ennyi ideig hagyjuk a drivert SAJÁT magát visszahozni, mielőtt force-reconnectolnánk. */
+  unhealthyGraceMs: number;
+  /** Épp folyamatban van-e már egy force-reconnect (ne torlódjon). */
+  reconnectInFlight: boolean;
+  /** Mióta (ms) volt az utolsó force-reconnect (Infinity, ha még nem volt). */
+  msSinceLastReconnect: number;
+  /** Két force-reconnect közti minimum (anti-thrash). */
+  reconnectCooldownMs: number;
+}
+
+/** A pure döntés eredménye. */
+export interface MongoReconnectDecision {
+  reconnect: boolean;
+  reason: string;
+}
+
+/**
+ * PURE döntés: kell-e force-reconnect. Healthy (===1) / connecting (===2) / in-flight / grace-en
+ * vagy cooldown-on belül → NEM. Csak tartós nem-connected (disconnected/disconnecting) + grace és
+ * cooldown letelt + nincs in-flight → IGEN.
+ */
+export function shouldForceMongoReconnect(s: MongoReconnectState): MongoReconnectDecision {
+  if (s.readyState === 1) {
+    return { reconnect: false, reason: 'connected (readyState=1)' };
+  }
+  if (s.readyState === 2) {
+    return { reconnect: false, reason: 'connecting (readyState=2) — letting the driver finish' };
+  }
+  if (s.reconnectInFlight) {
+    return { reconnect: false, reason: 'a force-reconnect is already in flight' };
+  }
+  if (s.msSinceUnhealthy < s.unhealthyGraceMs) {
+    return {
+      reconnect: false,
+      reason: `unhealthy for ${Math.round(s.msSinceUnhealthy / 1000)}s (< ${Math.round(s.unhealthyGraceMs / 1000)}s grace) — letting the driver self-heal first`,
+    };
+  }
+  if (s.msSinceLastReconnect < s.reconnectCooldownMs) {
+    return {
+      reconnect: false,
+      reason: `last force-reconnect ${Math.round(s.msSinceLastReconnect / 1000)}s ago (< ${Math.round(s.reconnectCooldownMs / 1000)}s cooldown)`,
+    };
+  }
+  return {
+    reconnect: true,
+    reason: `Mongo connection unhealthy (readyState=${s.readyState}) for ${Math.round(s.msSinceUnhealthy / 1000)}s past grace — forcing disconnect+connect to re-resolve the host IP`,
+  };
+}
+
+/** Injektált függőségek a futtatóhoz (best-effort; a futtató sose dob). */
+export interface MongoReconnectGuardDeps {
+  /** A jelenlegi `mongoose.connection.readyState`. */
+  getReadyState: () => number;
+  /**
+   * Force-reconnect: `disconnect()` majd `connect(uri, opts)` — ÚJ MongoClient → ÚJ DNS-resolve.
+   * Dobhat (a connect elbukhat, ha a Mongo épp tényleg down) — a futtató elkapja.
+   */
+  reconnect: () => Promise<void>;
+  /** Log. */
+  log: (msg: string) => void;
+  /** Tick-intervallum (ms). Default 10s. */
+  intervalMs?: number;
+  /** Grace, amíg a driver saját reconnect-jét várjuk (ms). Default 30s. */
+  unhealthyGraceMs?: number;
+  /** Cooldown két force-reconnect közt (ms). Default 20s. */
+  reconnectCooldownMs?: number;
+}
+
+/**
+ * Elindítja a periodikus reconnect-guard-ot. A visszaadott függvény leállítja (teszt/teardown).
+ * `.unref()` — nem tartja életben az event-loop-ot.
+ */
+export function startMongoReconnectGuard(deps: MongoReconnectGuardDeps): () => void {
+  const intervalMs: number = deps.intervalMs ?? 10 * second;
+  const unhealthyGraceMs: number = deps.unhealthyGraceMs ?? 30 * second;
+  const reconnectCooldownMs: number = deps.reconnectCooldownMs ?? 20 * second;
+
+  let unhealthySinceMs: number | null = null;
+  let lastReconnectAtMs: number | null = null;
+  let inFlight: boolean = false;
+  let ticking: boolean = false;
+
+  const tick = async (): Promise<void> => {
+    if (ticking) { return; }
+    ticking = true;
+    try {
+      const nowMs: number = Date.now();
+      const readyState: number = deps.getReadyState();
+
+      if (readyState === 1) {
+        if (unhealthySinceMs !== null) {
+          deps.log(`[mongo-reconnect-guard] Mongo connection healthy again (was unhealthy ${Math.round((nowMs - unhealthySinceMs) / 1000)}s)`);
+        }
+        unhealthySinceMs = null;
+        return;
+      }
+
+      // Nem-connected: indítsuk/folytassuk az unhealthy-órát.
+      if (unhealthySinceMs === null) { unhealthySinceMs = nowMs; }
+
+      const decision: MongoReconnectDecision = shouldForceMongoReconnect({
+        readyState: readyState,
+        msSinceUnhealthy: nowMs - unhealthySinceMs,
+        unhealthyGraceMs: unhealthyGraceMs,
+        reconnectInFlight: inFlight,
+        msSinceLastReconnect: lastReconnectAtMs === null ? Number.POSITIVE_INFINITY : nowMs - lastReconnectAtMs,
+        reconnectCooldownMs: reconnectCooldownMs,
+      });
+
+      if (!decision.reconnect) { return; }
+
+      deps.log(`[mongo-reconnect-guard] ${decision.reason}`);
+      inFlight = true;
+      lastReconnectAtMs = nowMs;
+      try {
+        await deps.reconnect();
+        deps.log('[mongo-reconnect-guard] force-reconnect dispatched ✓ (re-resolved host; awaiting connection open)');
+      } catch (e: unknown) {
+        // A connect elbukhat, ha a Mongo épp tényleg elérhetetlen — nem baj, a következő tick
+        // (cooldown után) újrapróbál; amint a Mongo új IP-n elérhető, a re-resolve becsatlakozik.
+        deps.log(`[mongo-reconnect-guard] force-reconnect attempt failed (will retry after cooldown): ${e instanceof Error ? e.message : String(e)}`);
+      } finally {
+        inFlight = false;
+      }
+    } catch (e: unknown) {
+      deps.log(`[mongo-reconnect-guard] tick error (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      ticking = false;
+    }
+  };
+
+  const handle: NodeJS.Timeout = setInterval((): void => { void tick(); }, intervalMs);
+  if (typeof handle.unref === 'function') { handle.unref(); }
+  DyFM_Log.info(
+    `[mongo-reconnect-guard] started — check every ${Math.round(intervalMs / 1000)}s, `
+    + `force disconnect+reconnect after ${Math.round(unhealthyGraceMs / 1000)}s sustained-unhealthy (re-resolves host IP), cooldown ${Math.round(reconnectCooldownMs / 1000)}s`,
+  );
+  return (): void => { clearInterval(handle); };
+}