@futdevpro/nts-dynamo 1.15.75 → 1.15.80

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

@@ -20,8 +20,9 @@ import {
   DyFM_Error, 
   DyFM_error_defaults,
   DyFM_Error_Settings,
-  DyFM_ErrorLevel, 
+  DyFM_ErrorLevel,
   DyFM_Log,
+  DyFM_resolveRetentionTtlSeconds,
   megabyte,
   second
 } from '@futdevpro/fsm-dynamo';
@@ -51,8 +52,10 @@ import {
 import {
   DyNTS_Cors_Settings
 } from '../../_models/interfaces/cors-settings.interface';
+import { DyNTS_DBService } from '../base/db.service';
 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_RoutingModule } from '../route/routing-module.service';
 import { DyNTS_getStarRoute } from '../../_collections/star.controller';
@@ -230,8 +233,30 @@ import { DyNTS_getStarRoute } from '../../_collections/star.controller';
  * 
  * 
  * ```
- * 
+ *
+ */
+
+/** FR-258 / SR-2 — one entry from `collection.indexes()` (only the fields the TTL-installer reads). */
+export interface DyNTS_TtlIndexInfo {
+  name?: string;
+  key?: Record<string, number>;
+  expireAfterSeconds?: number;
+}
+
+/**
+ * FR-258 / SR-2 — the minimal native-driver collection surface the TTL-installer needs. Declared
+ * structurally (not importing mongodb types) so it stays dependency-light and is trivially mockable
+ * in unit tests.
  */
+export interface DyNTS_TtlIndexCollection {
+  indexes?: () => Promise<DyNTS_TtlIndexInfo[]>;
+  createIndex: (keys: Record<string, number>, options: { expireAfterSeconds: number }) => Promise<unknown>;
+  dropIndex?: (name: string) => Promise<unknown>;
+}
+
+/** FR-258 / SR-2 — outcome of {@link DyNTS_App.ensureRetentionTtlIndex}. */
+export type DyNTS_TtlIndexAction = 'created' | 'updated' | 'noop';
+
 export abstract class DyNTS_App extends DyNTS_SingletonService {
 
   protected systemControls: DyNTS_AppSystemControls = new DyNTS_AppSystemControls();
@@ -555,6 +580,17 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
         DyFM_Log.warn('[DyNTS_MemoryGuard] auto-install skipped (non-fatal):', memoryGuardError);
       }
 
+      // 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.
+      try {
+        if (DyNTS_global_settings.collectionGrowthMonitor?.enabled) {
+          DyNTS_CollectionGrowthMonitor.getInstance().install();
+        }
+      } catch (cgmError: unknown) {
+        DyFM_Log.warn('[DyNTS_CollectionGrowthMonitor] auto-install skipped (non-fatal):', cgmError);
+      }
+
       if (!extended) {
         await this.ready();
 
@@ -916,6 +952,11 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
               DyFM_Log.success(`\nConnected to MongoDB (${this._params.dbUri})\n`);
 
               resolve();
+
+              // FR-258 / SR-2 — install declared-retention TTL indexes. Fire-and-forget +
+              // fully non-fatal: an index build on a large collection must NOT block startup,
+              // and any failure here is logged but never crashes the app.
+              void this.installRetentionTtlIndexes();
             })
             .on('error', (error): void => {
               if (!this.systemControls.mongoose.started) {
@@ -1013,7 +1054,100 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
   }
 
   /**
-   * 
+   * FR-258 / SR-2 — install MongoDB TTL indexes for every data-model that declared `retention`.
+   *
+   * Runs ONCE right after the DB connection opens. For each registered DB service (including the
+   * auto-created `_archived` siblings, which inherit the parent model's `retention`), it ensures a
+   * TTL index on the `__created` Date field with the resolved `expireAfterSeconds` — so MongoDB
+   * NATIVELY auto-deletes documents older than the configured age. This is the fleet-wide defense
+   * against the unbounded-collection-growth → in-memory-load → GC-thrash/OOM class.
+   *
+   * Guarantees:
+   * - **Non-fatal** — any error is logged but NEVER blocks startup (called fire-and-forget).
+   * - **Idempotent** — an existing index with the same TTL is a no-op; a CHANGED retention (different
+   *   `expireAfterSeconds`, or an existing non-TTL `__created` index) is reconciled by drop+recreate
+   *   (the field index is restored immediately, so query coverage is preserved).
+   */
+  private async installRetentionTtlIndexes(): Promise<void> {
+    try {
+      const services: DyNTS_DBService<any>[] = DyNTS_GlobalService.getAllDBServices();
+      let ensured: number = 0;
+
+      for (const service of services) {
+        const ttlSeconds: number | undefined = DyFM_resolveRetentionTtlSeconds(service?.dataParams?.retention);
+        if (!ttlSeconds) { continue; }
+
+        const dataName: string = service.dataParams.dataName;
+        // The mongoose Model exposes the native driver collection (.indexes / .createIndex / .dropIndex).
+        const collection: DyNTS_TtlIndexCollection | undefined =
+          (service?.dataModel as unknown as { collection?: DyNTS_TtlIndexCollection })?.collection;
+        if (!collection || typeof collection.createIndex !== 'function') { continue; }
+
+        try {
+          const action: DyNTS_TtlIndexAction = await DyNTS_App.ensureRetentionTtlIndex(collection, ttlSeconds);
+          if (action === 'created' || action === 'updated') {
+            ensured++;
+            if (this.logSetup) {
+              DyFM_Log.success(
+                `[FR-258 retention] TTL index ${action} on "${dataName}" — ` +
+                `${Math.round(ttlSeconds / 86400)}d (${ttlSeconds}s)`,
+              );
+            }
+          }
+        } catch (idxErr: unknown) {
+          DyFM_Log.warn(
+            `[FR-258 retention] TTL index on "${dataName}" failed (non-fatal): ` +
+            `${idxErr instanceof Error ? idxErr.message : String(idxErr)}`,
+          );
+        }
+      }
+
+      if (ensured > 0) {
+        DyFM_Log.success(`[FR-258 retention] ${ensured} TTL index(es) ensured (auto-retention active).`);
+      }
+    } catch (err: unknown) {
+      DyFM_Log.warn(
+        `[FR-258 retention] TTL-installer failed (non-fatal): ` +
+        `${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /**
+   * FR-258 / SR-2 — ensure a single `{ __created: 1 }` TTL index with the given `expireAfterSeconds`.
+   * Extracted as a pure-ish static so it is unit-testable with a mock collection. Idempotent:
+   * - no existing `__created` index      → create it             → `'created'`
+   * - existing with the SAME TTL          → no-op                 → `'noop'`
+   * - existing with a DIFFERENT TTL / non-TTL → drop + recreate   → `'updated'`
+   * Drop+recreate preserves query coverage (the `{__created:1}` index is restored immediately).
+   */
+  static async ensureRetentionTtlIndex(
+    collection: DyNTS_TtlIndexCollection,
+    ttlSeconds: number,
+  ): Promise<DyNTS_TtlIndexAction> {
+    const existingList: DyNTS_TtlIndexInfo[] = typeof collection.indexes === 'function'
+      ? await collection.indexes().catch((): DyNTS_TtlIndexInfo[] => [])
+      : [];
+    const existing: DyNTS_TtlIndexInfo | undefined =
+      existingList.find((ix): boolean => !!ix?.key && ix.key.__created === 1);
+
+    if (!existing) {
+      await collection.createIndex({ __created: 1 }, { expireAfterSeconds: ttlSeconds });
+      return 'created';
+    }
+    if (existing.expireAfterSeconds === ttlSeconds) {
+      return 'noop';
+    }
+    // Retention changed, or an existing non-TTL `__created` index → reconcile by drop+recreate.
+    if (existing.name && typeof collection.dropIndex === 'function') {
+      await collection.dropIndex(existing.name).catch((): void => undefined);
+    }
+    await collection.createIndex({ __created: 1 }, { expireAfterSeconds: ttlSeconds });
+    return 'updated';
+  }
+
+  /**
+   *
    */
   private async initExpresses(): Promise<void> {
     if (this.fnLogs && this.deepLog) DyFM_Log.log('\nfn:. initExpresses');

package/src/index.ts

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