@futdevpro/nts-dynamo 1.15.80 → 1.15.82

package/src/_services/server/app.server-retention.spec.ts

@@ -3,7 +3,7 @@ import { DyNTS_App, DyNTS_TtlIndexAction, DyNTS_TtlIndexCollection, DyNTS_TtlInd
 /**
  * FR-258 / SR-2 — unit tests for the retention TTL-index reconciliation logic
  * (`DyNTS_App.ensureRetentionTtlIndex`). Pure with respect to a mockable native-driver collection;
- * no live MongoDB required. Covers create / no-op / update(drop+recreate) and edge cases.
+ * no live MongoDB required. Covers create / no-op / differs(boot-safe, no rebuild) and edge cases.
  */
 describe('| DyNTS_App.ensureRetentionTtlIndex (FR-258 / SR-2)', () => {
 
@@ -51,25 +51,25 @@ describe('| DyNTS_App.ensureRetentionTtlIndex (FR-258 / SR-2)', () => {
     expect(m.dropped.length).toBe(0);
   });
 
-  it('| existing index with a DIFFERENT ttl → drop + recreate (action "updated")', async () => {
+  it('| existing index with a DIFFERENT ttl → BOOT-SAFE: left untouched (action "differs", NO drop/recreate)', async () => {
     const m: MockColl = makeMockCollection([
       { name: '__created_1', key: { __created: 1 }, expireAfterSeconds: 999 },
     ]);
     const action: DyNTS_TtlIndexAction = await DyNTS_App.ensureRetentionTtlIndex(m.coll, TTL_14D);
-    expect(action).toBe('updated');
-    expect(m.dropped).toEqual(['__created_1']);
-    expect(m.created.length).toBe(1);
-    expect(m.created[0].options).toEqual({ expireAfterSeconds: TTL_14D });
+    expect(action).toBe('differs');
+    // Critical: never rebuild a live index at boot (heavy op on large collections → health-probe starvation).
+    expect(m.dropped.length).toBe(0);
+    expect(m.created.length).toBe(0);
   });
 
-  it('| existing NON-TTL __created index (no expireAfterSeconds) → drop + recreate as TTL', async () => {
+  it('| existing NON-TTL __created index (no expireAfterSeconds) → BOOT-SAFE: left untouched (action "differs")', async () => {
     const m: MockColl = makeMockCollection([
       { name: '__created_1', key: { __created: 1 } },
     ]);
     const action: DyNTS_TtlIndexAction = await DyNTS_App.ensureRetentionTtlIndex(m.coll, 604800);
-    expect(action).toBe('updated');
-    expect(m.dropped).toEqual(['__created_1']);
-    expect(m.created.length).toBe(1);
+    expect(action).toBe('differs');
+    expect(m.dropped.length).toBe(0);
+    expect(m.created.length).toBe(0);
   });
 
   it('| ignores indexes on OTHER fields — only reconciles { __created: 1 }', async () => {

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

@@ -254,8 +254,17 @@ export interface DyNTS_TtlIndexCollection {
   dropIndex?: (name: string) => Promise<unknown>;
 }
 
-/** FR-258 / SR-2 — outcome of {@link DyNTS_App.ensureRetentionTtlIndex}. */
-export type DyNTS_TtlIndexAction = 'created' | 'updated' | 'noop';
+/**
+ * FR-258 / SR-2 — outcome of {@link DyNTS_App.ensureRetentionTtlIndex}.
+ * - `created`: no `__created` TTL index existed → one was created.
+ * - `noop`:    an index with the SAME TTL already existed → nothing done.
+ * - `differs`: an index exists with a DIFFERENT TTL (or a non-TTL `__created` index) → left UNTOUCHED,
+ *   only a warning is emitted. We deliberately DO NOT drop+recreate at boot: rebuilding a TTL index on a
+ *   multi-GB production collection is a heavy server-side op that can starve concurrent boot queries (e.g.
+ *   the health-probe) and trip a fail-safe deploy revert. A deliberate retention CHANGE must be applied via
+ *   maintenance, not silently at every startup.
+ */
+export type DyNTS_TtlIndexAction = 'created' | 'differs' | 'noop';
 
 export abstract class DyNTS_App extends DyNTS_SingletonService {
 
@@ -953,10 +962,16 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
 
               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();
+              // FR-258 / SR-2 — install declared-retention TTL indexes. DEFERRED + fire-and-forget +
+              // fully non-fatal: a create-if-missing index op (and the `indexes()` probes) must NOT
+              // compete with boot-readiness. We delay it well past the deploy health-probe window so a
+              // cold boot is never slowed by it, then run it detached. `.unref()` keeps it from holding
+              // the event loop open. Any failure is logged but never crashes the app. (`'differs'` never
+              // rebuilds a live index — see ensureRetentionTtlIndex.)
+              const ttlInstallTimer: ReturnType<typeof setTimeout> = setTimeout((): void => {
+                void this.installRetentionTtlIndexes();
+              }, 30000);
+              if (typeof ttlInstallTimer.unref === 'function') { ttlInstallTimer.unref(); }
             })
             .on('error', (error): void => {
               if (!this.systemControls.mongoose.started) {
@@ -1085,14 +1100,21 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
 
         try {
           const action: DyNTS_TtlIndexAction = await DyNTS_App.ensureRetentionTtlIndex(collection, ttlSeconds);
-          if (action === 'created' || action === 'updated') {
+          if (action === 'created') {
             ensured++;
             if (this.logSetup) {
               DyFM_Log.success(
-                `[FR-258 retention] TTL index ${action} on "${dataName}" — ` +
+                `[FR-258 retention] TTL index created on "${dataName}" — ` +
                 `${Math.round(ttlSeconds / 86400)}d (${ttlSeconds}s)`,
               );
             }
+          } else if (action === 'differs') {
+            // Live index has a different TTL — left untouched at boot (see ensureRetentionTtlIndex doc).
+            DyFM_Log.warn(
+              `[FR-258 retention] "${dataName}" already has a {__created} index with a DIFFERENT TTL than the ` +
+              `declared ${Math.round(ttlSeconds / 86400)}d (${ttlSeconds}s) — left as-is (no boot-time rebuild). ` +
+              `Apply the change via maintenance if intended.`,
+            );
           }
         } catch (idxErr: unknown) {
           DyFM_Log.warn(
@@ -1115,11 +1137,16 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
 
   /**
    * 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).
+   * Extracted as a pure-ish static so it is unit-testable with a mock collection. Idempotent + BOOT-SAFE:
+   * - no existing `__created` index      → create it          → `'created'`
+   * - existing with the SAME TTL          → no-op              → `'noop'`
+   * - existing with a DIFFERENT TTL / non-TTL → leave it as-is → `'differs'` (warn only — NO drop+recreate)
+   *
+   * The `'differs'` case intentionally does NOT mutate the live index. Dropping + recreating a TTL index on a
+   * large (multi-GB) production collection is a heavy server-side operation; doing it automatically inside the
+   * startup path can starve the concurrent boot queries (including the deploy health-probe) and trigger a
+   * fail-safe revert. Create-if-missing is the essential growth-prevention behaviour; a deliberate retention
+   * CHANGE on an already-indexed collection is a maintenance action, not a silent every-boot rebuild.
    */
   static async ensureRetentionTtlIndex(
     collection: DyNTS_TtlIndexCollection,
@@ -1138,12 +1165,9 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     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';
+    // Retention differs from the live index (or it is a non-TTL `__created` index). Leave it UNTOUCHED at
+    // boot — only report it. Avoids a heavy drop+recreate competing with boot-readiness on a large collection.
+    return 'differs';
   }
 
   /**