@futdevpro/nts-dynamo 1.15.100 → 1.15.102

package/src/_services/base/data.service.ts

@@ -35,6 +35,7 @@ import { DyNTS_DBQueryOptions } from '../../_models/interfaces/db-query-options.
 import { DyNTS_DBUpdate } from '../../_models/types/db-update.type';
 import { DyNTS_GlobalService } from '../core/global.service';
 import { DyNTS_ArchiveDataService } from './archive-data.service';
+import { DyNTS_archiveServiceRegistry } from '../../_collections/archive-service-registry.const';
 import { DyNTS_DBService } from './db.service';
 
 
@@ -171,12 +172,23 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
   }
 
   getArchiveDataService(): DyNTS_ArchiveDataService<T> {
+    // Non-throwing default (BFR-AM-012): ha a dataParams `addArchive`-ot kér, a base ELŐÁLLÍTJA a
+    // default archive-service-t — az `addArchive: true` így out-of-the-box működik (soft-delete →
+    // archív-collection), per-service boilerplate-override nélkül. A korábbi feltétlen throw a
+    // loadData/delete archive-útjain futásidőben crashelt (és async-kontextusban néma
+    // `.split`-elfedésű rejected-promise-ként jelent meg). Override továbbra is felülírhatja.
+    // a registry-n át példányosítunk (körkörös-import feloldás — l. archive-service-registry.const)
+    if (this.dataParams?.addArchive && DyNTS_archiveServiceRegistry.ArchiveDataService) {
+      return new DyNTS_archiveServiceRegistry.ArchiveDataService<T>(this.data, this.dataParams, this.issuer);
+    }
+
+    // addArchive nélkül az archive-service-hívás valódi programhiba → marad az explicit throw
     throw new DyFM_Error({
       ...this._getDefaultErrorSettings(
         'getArchiveDataService',
-        new Error('getArchiveDataService is not implemented!')
+        new Error('getArchiveDataService is not implemented! (dataParams.addArchive is not set)')
       ),
-      
+
       errorCode: `${this.ecBase}DyNTS-DS-GAD0`,
     });
   }
@@ -1292,13 +1304,15 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
 
       await this.validateDataByPropertyParams(data, this.dataParams.properties);
     } catch (error) {
-      if (error?.errorCode?.includes?.('DyNTS-DS0-VBP') || error?.errorCode?.includes?.('DyNTS-DS0-VP')) {
+      // a TELJES validacios csalad (VP/VDP/VBP/VD) valtozatlanul atmegy — a korabbi szukebb szuro a VDP*-t
+      // ujra-becsomagolta (double-wrap: a 400 elveszett; BFR-FUTDEVPRO-001)
+      if (error?.errorCode?.includes?.('DyNTS-DS0-V')) {
         throw error;
       } else {
         throw new DyFM_Error({ 
           ...this._getDefaultErrorSettings('validateForSave', error),
 
-          status: 522, 
+          status: 400, 
           errorCode: `${this.ecBase}DyNTS-DS0-VD0`,
         });
       }
@@ -1363,7 +1377,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
           const validationErrorsSet: DyFM_ValidationErrors = {};
           validationErrors.forEach((error: DyFM_Error) => {
             Object.keys(error.validationErrors).forEach((key: string) => {
-              validationErrors[key] = error.validationErrors[key];
+              validationErrorsSet[key] = error.validationErrors[key];
             });
           });
 
@@ -1382,13 +1396,14 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
         }
       }
     } catch (error) {
-      if (error?.errorCode?.includes?.('DyNTS-DS0-VDP')) {
+      // a teljes validacios csalad atengedese (a leaf VP-hibak eddig VDP0-ba csomagolodtak ujra)
+      if (error?.errorCode?.includes?.('DyNTS-DS0-V')) {
         throw error;
       } else {
         throw new DyFM_Error({ 
           ...this._getDefaultErrorSettings('validateByPropertyParams', error),
 
-          status: 522, 
+          status: 400, 
           errorCode: `${this.ecBase}DyNTS-DS0-VDP0`,
         });
       }
@@ -1426,7 +1441,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
           )
         ),
 
-        status: 522, 
+        status: 400, 
         errorCode: `${this.ecBase}DyNTS-DS0-VP1`,
         userMessage: this.defaultValidationErrorUserMsg,
         validationErrors: {
@@ -1457,7 +1472,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
           )
         ),
 
-        status: 522, 
+        status: 400, 
         errorCode: `${this.ecBase}DyNTS-DS0-VP2`,
         userMessage: this.defaultValidationErrorUserMsg,
         validationErrors: {
@@ -1498,7 +1513,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP3`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1530,7 +1545,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP4`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1563,7 +1578,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP5`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1597,7 +1612,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP6`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1628,7 +1643,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP7`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1663,7 +1678,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}DyNTS-DS0-VP8`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1703,7 +1718,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
               )
             ),
 
-            status: 522, 
+            status: 400, 
             errorCode: `${this.ecBase}VP9`,
             userMessage: this.defaultValidationErrorUserMsg,
             validationErrors: {
@@ -1733,7 +1748,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
             )
           ),
 
-          status: 522, 
+          status: 400, 
           errorCode: `${this.ecBase}DyNTS-DS0-VP10`,
           userMessage: this.defaultValidationErrorUserMsg,
           validationErrors: {

package/src/_services/base/db.service.ts

@@ -1011,6 +1011,58 @@ export class DyNTS_DBService<T extends DyFM_Metadata> {
     return this.stringifyDataId(data, 'findByIdAndUpdate');
   }
 
+  /**
+   * #MONGOOSE FUNCTION
+   * Atomi compare-and-set: filter-alapú find + update EGY műveletben, a MÓDOSÍTOTT dokumentum
+   * visszaadásával (BFR-FDPTOKENSERVICE-006).
+   *
+   * A `findByIdAndUpdate` (id-only, nem filterezhető) és az `updateOne` (filterezhető, de void —
+   * nem különíthető el a winner/loser konkurens state-átmenetnél) egyike sem elég CAS-hoz: egy
+   * state-machine `transitionStatus`-jellegű átmenetnél a filter a FELTÉTEL (pl. `{_id, status:
+   * 'locked'}`), és a visszatérő érték dönti el, hogy EZ a hívás nyerte-e az átmenetet.
+   * `null` = nincs match (a feltétel már nem áll — a versenytárs nyert / state-collision).
+   *
+   * A `__lastModified`/`forbidModify` szemantika a `findByIdAndUpdate`-tel EGYEZŐ (egységes
+   * update-viselkedés a base-ben); a `{ new: true }` a MÓDOSÍTOTT dokumentumot adja vissza.
+   */
+  async findOneAndUpdate(
+    filterBy: DyFM_DBFilter<T>,
+    update: DyNTS_DBUpdate<T>,
+    issuer: string,
+    dontUpdateModified?: boolean
+  ): Promise<T | null> {
+    if (this.dataParams.forbidModify) {
+      await this.modifyThrowMethod(update, issuer);
+    }
+
+    if (!dontUpdateModified) {
+      update.__lastModified = new Date();
+      update.__lastModifiedBy = issuer;
+    }
+
+    const data: T | null = await this.dataModel
+      .findOneAndUpdate(filterBy, update, { new: true })
+      .then((res): T | null => res?.toObject() as T ?? null)
+      .catch((error): never => {
+        throw new DyFM_Error({
+          ...this._getDefaultErrorSettings('findOneAndUpdate', error, issuer),
+          errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DBS-FOU0`,
+          additionalContent: { filterBy, update },
+          message:
+            `findOneAndUpdate "${this.dataParams.dataName}" was unsuccessful (NTS DB)` +
+            `\n  error: ${DyFM_Error.getErrorMessage(error)}`,
+          issuer,
+        });
+      });
+
+    // no-match (CAS lost / feltétel nem áll): a null ÉRVÉNYES eredmény, nem hiba
+    if (!data) {
+      return null;
+    }
+
+    return this.stringifyDataId(data, 'findOneAndUpdate');
+  }
+
   /**
    * #MONGOOSE FUNCTION
    * Find the data first by any of its parameters

package/src/_services/core/event-loop-diag.service.spec.ts

@@ -0,0 +1,22 @@
+import { DyNTS_EventLoopDiag, DyNTS_EventLoopSample } from './event-loop-diag.service';
+
+// Az event-loop-diag (BFR-OVERSEER-007) alap-tesztjei: snapshot-shape + install-idempotencia.
+// A tényleges lag-értékeket nem asszertáljuk (env-függő) — a mérő-plumbing működését igen.
+describe('| DyNTS_EventLoopDiag', (): void => {
+
+  it('| getSnapshot install előtt is biztonságos (üres kép)', (): void => {
+    const snapshot: { installed: boolean; current: DyNTS_EventLoopSample | null; history: DyNTS_EventLoopSample[] } =
+      DyNTS_EventLoopDiag.getInstance().getSnapshot();
+
+    expect(Array.isArray(snapshot.history)).toBeTrue();
+  });
+
+  it('| install idempotens és a snapshot installed-et jelez', (): void => {
+    const diag: DyNTS_EventLoopDiag = DyNTS_EventLoopDiag.getInstance();
+
+    diag.install();
+    diag.install();
+
+    expect(diag.getSnapshot().installed).toBeTrue();
+  });
+});

package/src/_services/core/event-loop-diag.service.ts

@@ -0,0 +1,122 @@
+import { monitorEventLoopDelay, IntervalHistogram } from 'perf_hooks';
+
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+
+/** Egy event-loop-lag mintavétel (a gördülő history eleme). */
+export interface DyNTS_EventLoopSample {
+  at: number;
+  /** p50 lag ms-ben (a poll-ablakban). */
+  p50Ms: number;
+  /** p95 lag ms-ben. */
+  p95Ms: number;
+  /** max lag ms-ben — a „process él, HTTP néma" wedge fő jele. */
+  maxMs: number;
+  /** Aktív handle-k száma (socket/timer/fd) — connection-leak jel. */
+  activeHandles: number;
+}
+
+/**
+ * Event-loop-lag + connection diagnosztika (BFR-OVERSEER-007) — a „process él, de a HTTP néma"
+ * jelenség (event-loop blokk / wedge) eddig LÁTHATATLAN volt: a MemoryGuard a heap-et figyeli,
+ * a healthcheck kívülről néz — a loop-lag magát a tünetet méri, belülről.
+ *
+ * A `perf_hooks.monitorEventLoopDelay` NATÍV histogramjára épül (elhanyagolható overhead),
+ * poll-onként mintát tesz egy ring-bufferbe; a `getSnapshot()` a `/server/diag` endpoint (és
+ * bármely fogyasztó) számára adja vissza az aktuális + közelmúlt-képet. A MemoryGuard MELLÉ
+ * illeszkedik (nem duplikálja): memória-nyomás = MemoryGuard.pressure(); loop-lag = ez.
+ *
+ * Install: a base App startup (a MemoryGuard-install mintájára), `eventLoopDiag.enabled` gate-tel
+ * (default: true — a mérés olcsó; opt-out lehetséges).
+ */
+export class DyNTS_EventLoopDiag {
+
+  private static instance: DyNTS_EventLoopDiag;
+
+  static getInstance(): DyNTS_EventLoopDiag {
+    if (!DyNTS_EventLoopDiag.instance) {
+      DyNTS_EventLoopDiag.instance = new DyNTS_EventLoopDiag();
+    }
+
+    return DyNTS_EventLoopDiag.instance;
+  }
+
+  private monitor: IntervalHistogram | null = null;
+  private pollTimer: NodeJS.Timeout | null = null;
+  private history: DyNTS_EventLoopSample[] = [];
+  private installed: boolean = false;
+
+  /** A diag-mérés telepítése (idempotens; a settings-gate itt érvényesül). */
+  install(): void {
+    if (this.installed) {
+      return;
+    }
+
+    const settings: { enabled?: boolean; pollIntervalMs?: number; maxHistoryCount?: number } =
+      DyNTS_global_settings.eventLoopDiag ?? {};
+
+    if (settings.enabled === false) {
+      return;
+    }
+
+    const pollIntervalMs: number = settings.pollIntervalMs ?? 5000;
+    const maxHistoryCount: number = settings.maxHistoryCount ?? 120;
+
+    // natív histogram — 10ms felbontás bőven elég a wedge-detektáláshoz (a jel: 100ms+ lag)
+    this.monitor = monitorEventLoopDelay({ resolution: 10 });
+    this.monitor.enable();
+
+    this.pollTimer = setInterval((): void => {
+      if (!this.monitor) {
+        return;
+      }
+
+      // a histogram ns-ben mér → ms-re váltunk; poll után reset (ablakonkénti kép)
+      this.history.push({
+        at: Date.now(),
+        p50Ms: Math.round(this.monitor.percentile(50) / 1e6),
+        p95Ms: Math.round(this.monitor.percentile(95) / 1e6),
+        maxMs: Math.round(this.monitor.max / 1e6),
+        activeHandles: this.getActiveHandleCount(),
+      });
+      this.monitor.reset();
+
+      if (this.history.length > maxHistoryCount) {
+        this.history = this.history.slice(-maxHistoryCount);
+      }
+    }, pollIntervalMs);
+
+    // a poll-timer NE tartsa életben a processzt
+    this.pollTimer.unref?.();
+
+    this.installed = true;
+    DyFM_Log.log(`Event-loop diag installed (poll: ${pollIntervalMs}ms, history: ${maxHistoryCount})`);
+  }
+
+  /** A diag-pillanatkép — a `/server/diag` endpoint (és bármely fogyasztó) forrása. */
+  getSnapshot(): {
+    installed: boolean;
+    current: DyNTS_EventLoopSample | null;
+    history: DyNTS_EventLoopSample[];
+  } {
+    return {
+      installed: this.installed,
+      current: this.history.length ? this.history[this.history.length - 1] : null,
+      history: this.history,
+    };
+  }
+
+  /** Aktív handle-k száma — best-effort (a nem-publikus API hiányát 0-val toleráljuk). */
+  private getActiveHandleCount(): number {
+    // a _getActiveHandles nem publikus API — best-effort diag-jel (connection/timer-leak trend)
+    const getHandles: (() => unknown[]) | undefined =
+      (process as unknown as { _getActiveHandles?: () => unknown[] })._getActiveHandles;
+
+    try {
+      return getHandles ? getHandles().length : 0;
+    } catch {
+      return 0;
+    }
+  }
+}

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

@@ -33,6 +33,7 @@ import { DyNTS_global_settings } from '../../_collections/global-settings.const'
 import { DyNTS_ClientSafeError_Util } from '../../_collections/client-safe-error.util';
 import { DyNTS_getEnvironment_settings } from '../../_collections/get-environment-settings.util';
 import { DyNTS_createSecurityHeadersMiddleware } from '../../_collections/security-headers.util';
+import { DyNTS_createLoadShedMiddleware } from '../../_collections/load-shed.util';
 import { DyNTS_SecurityHeaders_Settings } from '../../_models/interfaces/security-headers-settings.interface';
 import { startMongoReconnectGuard } from '../../_collections/mongo-reconnect-guard.util';
 import { DyNTS_resolveStaticCacheControlHeader } from '../../_collections/static-cache-control.util';
@@ -62,6 +63,7 @@ import { DyNTS_SingletonService } from '../base/singleton.service';
 import { DyNTS_GlobalService } from '../core/global.service';
 import { DyNTS_CollectionGrowthMonitor } from '../core/collection-growth-monitor.service';
 import { DyNTS_MemoryGuard } from '../core/memory-guard.service';
+import { DyNTS_EventLoopDiag } from '../core/event-loop-diag.service';
 import { DyNTS_RoutingModule } from '../route/routing-module.service';
 import { DyNTS_getStarRoute } from '../../_collections/star.controller';
 
@@ -594,6 +596,14 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
         DyFM_Log.warn('[DyNTS_MemoryGuard] auto-install skipped (non-fatal):', memoryGuardError);
       }
 
+      // BFR-OVERSEER-007 — event-loop-lag diag a MemoryGuard MELLÉ: a „process él, HTTP néma" wedge
+      // belső mérése (natív histogram, olcsó). Observation-only, sosem dob; a /server/diag olvas belőle.
+      try {
+        DyNTS_EventLoopDiag.getInstance().install();
+      } catch (eventLoopDiagError: unknown) {
+        DyFM_Log.warn('[DyNTS_EventLoopDiag] auto-install skipped (non-fatal):', eventLoopDiagError);
+      }
+
       // FR-258 / SR-4 — proactive collection-growth monitor (companion to the MemoryGuard). Warns
       // into the Errors-sink when a collection grows unbounded, BEFORE it can be loaded into heap and
       // OOM. Default-on, observation-only, never throws.
@@ -1286,6 +1296,10 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     this.mountSecurityHeaders(this.openExpress);
     // FR-041 — CORS allowlist enforcement. No-op if getCorsSettings() is not overridden.
     this.mountCors(this.openExpress);
+    // BFR-OVERSEER-009 — opt-in auto-load-shed 503 CRITICAL memória-nyomásnál (esszenciális utak kivételével).
+    if (DyNTS_global_settings.memoryGuard?.loadShedEnabled) {
+      this.openExpress.use(DyNTS_createLoadShedMiddleware());
+    }
   }
 
   /**
@@ -1300,6 +1314,10 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     this.mountSecurityHeaders(this.secureExpress);
     // FR-041 — CORS allowlist enforcement (same as open express).
     this.mountCors(this.secureExpress);
+    // BFR-OVERSEER-009 — opt-in auto-load-shed 503 (mint az open expressen).
+    if (DyNTS_global_settings.memoryGuard?.loadShedEnabled) {
+      this.secureExpress.use(DyNTS_createLoadShedMiddleware());
+    }
 
     const options = {
       key: FileSystem.readFileSync(this._cert.keyPath),
@@ -1781,15 +1799,30 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     const fallbackMaxAge: number =
       settings.fallbackCacheMaxAge ?? DyNTS_defaultFallbackCacheMaxAge;
 
+    // API-namespace guard (BFR-DYNAMOBUILDER-001): a catch-all fallback NE fedje az API-prefixeket —
+    // egy ismeretlen `GET /api/...` 404 JSON-t kapjon, ne megtévesztő `200 + index.html`-t.
+    // Konfigurálható (fallbackExcludePrefixes); default a bevett FDP namespace-pár.
+    const excludePrefixes: string[] = settings.fallbackExcludePrefixes ?? ['/api', '/auth-api'];
+    const isApiNamespacePath = (path: string): boolean =>
+      excludePrefixes.some((prefix: string): boolean => path === prefix || path.startsWith(`${prefix}/`));
+
     if (this.openExpress) {
       this.openExpress.use('/', staticMiddleware);
       if (settings.fallbackPath) {
         this.openExpress.get('*', (req: Express.Request, res: Express.Response): void => {
+          if (isApiNamespacePath(req.path)) {
+            res.status(404).send({ message: `Unknown API endpoint: ${req.path}` });
+            return;
+          }
           res.setHeader('Cache-Control', `max-age=${fallbackMaxAge}`);
           res.sendFile(settings.fallbackPath!, { root: absoluteRoot });
         });
       } else {
         this.openExpress.get('*', (req: Express.Request, res: Express.Response): void => {
+          if (isApiNamespacePath(req.path)) {
+            res.status(404).send({ message: `Unknown API endpoint: ${req.path}` });
+            return;
+          }
           res.status(404).type('html').send(DyNTS_defaultNotFoundPageHtml);
         });
       }
@@ -1799,11 +1832,19 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
       this.secureExpress.use('/', staticMiddleware);
       if (settings.fallbackPath) {
         this.secureExpress.get('*', (req: Express.Request, res: Express.Response): void => {
+          if (isApiNamespacePath(req.path)) {
+            res.status(404).send({ message: `Unknown API endpoint: ${req.path}` });
+            return;
+          }
           res.setHeader('Cache-Control', `max-age=${fallbackMaxAge}`);
           res.sendFile(settings.fallbackPath!, { root: absoluteRoot });
         });
       } else {
         this.secureExpress.get('*', (req: Express.Request, res: Express.Response): void => {
+          if (isApiNamespacePath(req.path)) {
+            res.status(404).send({ message: `Unknown API endpoint: ${req.path}` });
+            return;
+          }
           res.status(404).type('html').send(DyNTS_defaultNotFoundPageHtml);
         });
       }

package/src/index.ts

@@ -55,6 +55,8 @@ export * from './_models/interfaces/security-headers-settings.interface';
 export * from './_models/interfaces/db-query-options.interface';
 export * from './_collections/security-headers.util';
 export * from './_collections/client-safe-error.util';
+export * from './_collections/load-shed.util';
+export * from './_services/core/event-loop-diag.service';
 
 // models/CONTROL MODELS
 export * from './_models/control-models/api-call-params.control-model';