@futdevpro/nts-dynamo 1.15.153 → 1.15.155

package/src/_modules/server/safe-diagnostic/safe-diagnostic.control-service.ts

@@ -0,0 +1,99 @@
+import { createHash } from 'crypto';
+
+import { DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SafeDiagnosticCause_Type } from './safe-diagnostic-cause.type-enum';
+import {
+  DyNTS_SafeDiagnosticInput_Interface,
+  DyNTS_SafeDiagnostic_Interface
+} from './safe-diagnostic.interface';
+
+/** Projects arbitrary failures to a versioned, content-free public diagnostic. */
+export class DyNTS_SafeDiagnostic_ControlService {
+  private static readonly contractVersion: 'dynts-safe-diagnostic/1' = 'dynts-safe-diagnostic/1';
+  private static readonly defaultCode: string = 'DYNTS_SAFE_DIAGNOSTIC_INVALID_CODE';
+  private static readonly defaultStatus: number = 500;
+
+  /** Returns an immutable exact allowlist and never reflects raw failure content. */
+  static project(input: DyNTS_SafeDiagnosticInput_Interface): DyNTS_SafeDiagnostic_Interface {
+    const code: string = this.getCode(input.code);
+    const causeType: DyNTS_SafeDiagnosticCause_Type = this.getCauseType(input.error);
+    const status: number = this.getStatus(input.status);
+    const fingerprint: string = this.getFingerprint([
+      this.contractVersion,
+      code,
+      input.stage,
+      causeType,
+      status.toString(),
+    ]);
+
+    return Object.freeze({
+      contractVersion: this.contractVersion,
+      code: code,
+      stage: input.stage,
+      causeType: causeType,
+      fingerprint: fingerprint,
+      status: status,
+    });
+  }
+
+  /** Logs only the projected allowlist and returns the same immutable diagnostic. */
+  static report(input: DyNTS_SafeDiagnosticInput_Interface): DyNTS_SafeDiagnostic_Interface {
+    const diagnostic: DyNTS_SafeDiagnostic_Interface = this.project(input);
+
+    DyFM_Log.error('[DyNTS safe diagnostic]', diagnostic);
+
+    return diagnostic;
+  }
+
+  /** Creates a framework error that carries only the safe diagnostic allowlist. */
+  static toError(diagnostic: DyNTS_SafeDiagnostic_Interface): DyFM_Error {
+    return new DyFM_Error({
+      errorCode: diagnostic.code,
+      message: `Framework failure at ${diagnostic.stage}. Correlation: ${diagnostic.fingerprint}.`,
+      userMessage: 'A server operation failed. Contact the responsible team with the correlation fingerprint.',
+      additionalContent: { diagnostic: diagnostic },
+      status: diagnostic.status,
+    });
+  }
+
+  private static getCode(code: string): string {
+    return /^[A-Z][A-Z0-9_|-]{2,127}$/.test(code) ? code : this.defaultCode;
+  }
+
+  private static getCauseType(error: unknown): DyNTS_SafeDiagnosticCause_Type {
+    try {
+      if (error instanceof DyFM_Error) {
+        return DyNTS_SafeDiagnosticCause_Type.dynamoError;
+      }
+
+      if (error instanceof Error) {
+        return DyNTS_SafeDiagnosticCause_Type.nativeError;
+      }
+
+      if (error !== null && typeof error === 'object') {
+        return DyNTS_SafeDiagnosticCause_Type.object;
+      }
+
+      if (error !== undefined) {
+        return DyNTS_SafeDiagnosticCause_Type.primitive;
+      }
+    } catch {
+      return DyNTS_SafeDiagnosticCause_Type.unknown;
+    }
+
+    return DyNTS_SafeDiagnosticCause_Type.unknown;
+  }
+
+  private static getStatus(status?: number): number {
+    if (typeof status !== 'number' || !Number.isInteger(status) || status < 100 || status > 599) {
+      return this.defaultStatus;
+    }
+
+    return status;
+  }
+
+  private static getFingerprint(subject: string[]): string {
+    return createHash('sha256').update(subject.join('\u0000'), 'utf8').digest('hex');
+  }
+}

package/src/_modules/server/safe-diagnostic/safe-diagnostic.interface.ts

@@ -0,0 +1,20 @@
+import { DyNTS_SafeDiagnosticCause_Type } from './safe-diagnostic-cause.type-enum';
+import { DyNTS_SafeDiagnosticStage_Type } from './safe-diagnostic-stage.type-enum';
+
+/** Caller-owned input whose raw failure content is never returned or logged. */
+export interface DyNTS_SafeDiagnosticInput_Interface {
+  code: string;
+  stage: DyNTS_SafeDiagnosticStage_Type;
+  error?: unknown;
+  status?: number;
+}
+
+/** Exact public allowlist emitted by the safe diagnostic boundary. */
+export interface DyNTS_SafeDiagnostic_Interface {
+  contractVersion: 'dynts-safe-diagnostic/1';
+  code: string;
+  stage: DyNTS_SafeDiagnosticStage_Type;
+  causeType: DyNTS_SafeDiagnosticCause_Type;
+  fingerprint: string;
+  status: number;
+}

package/src/_modules/server/server-status/db-readiness-probe.control-service.spec.ts

@@ -189,7 +189,7 @@ describe('| DyNTS_DbReadinessProbe_ControlService', (): void => {
     failure.self = failure;
     const result: DyNTS_DbReadinessProbeResult_Interface = await probe(createConnection({
       readyStateGetter: (): number => {
-        throw failure;
+        throw failure;
       },
     }));
 
@@ -203,7 +203,7 @@ describe('| DyNTS_DbReadinessProbe_ControlService', (): void => {
     failure.self = failure;
     const result: DyNTS_DbReadinessProbeResult_Interface = await probe(createConnection({
       databaseGetter: (): mongoose.Connection['db'] => {
-        throw failure;
+        throw failure;
       },
     }));
 

package/src/_services/core/global.service.ts

@@ -1,6 +1,3 @@
-
-
-
 import {
   DyFM_AnyError,
   DyFM_Array,
@@ -11,23 +8,26 @@ import {
   DyFM_Log,
   DyFM_Metadata
 } from '@futdevpro/fsm-dynamo';
-import { DyNTS_App_Params } from '../../_models/control-models/app-params.control-model';
-
-import {
-  DyNTS_GlobalErrorHandlerFn,
-  DyNTS_GlobalService_Settings
-} from '../../_models/interfaces/global-service-settings.interface';
 
 import { DyNTS_AuthService } from './auth.service';
-/* import { DyNTS_DBServiceCollection } from './db-service-collection.service'; */
-import { DyNTS_DBService } from '../base/db.service';
 import { DyNTS_EmailService } from './email.service';
 import { DyNTS_Service_Collection } from './service-collection.service';
+/* import { DyNTS_DBServiceCollection } from './db-service-collection.service'; */
 /* import { DyNTS_EmailServiceCollection } from './email-service-collection.service'; */
-import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_DBService } from '../base/db.service';
 import { DyNTS_SingletonService } from '../base/singleton.service';
 /* import { DyNTS_archiveFlag } from '../../_collections/archive-flag.const'; */
 import { DyNTS_getArchivedDBName } from '../../_collections/archive.util';
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_App_Params } from '../../_models/control-models/app-params.control-model';
+import {
+  DyNTS_GlobalErrorHandlerFn,
+  DyNTS_GlobalService_Settings
+} from '../../_models/interfaces/global-service-settings.interface';
+import { DyNTS_SafeDiagnosticStage_Type } from '../../_modules/server/safe-diagnostic/safe-diagnostic-stage.type-enum';
+import {
+  DyNTS_SafeDiagnostic_ControlService
+} from '../../_modules/server/safe-diagnostic/safe-diagnostic.control-service';
 
 /**
  * This is the main Global/Core Service Collection used by DynamoNTS, 
@@ -76,8 +76,12 @@ export class DyNTS_GlobalService extends DyNTS_SingletonService {
 
   static globalErrorHandler: DyNTS_GlobalErrorHandlerFn = 
     async (error: DyFM_AnyError): Promise<void> => {
-      DyFM_Log.error(`Global Error Handler not set!\nError:`, error);
-    }
+      DyNTS_SafeDiagnostic_ControlService.report({
+        code: 'DYNTS|GLOBAL|HANDLER_NOT_SET',
+        stage: DyNTS_SafeDiagnosticStage_Type.globalErrorHandler,
+        error: error,
+      });
+    };
     
   /**
    * You need to setup global Services through this function
@@ -182,11 +186,11 @@ export class DyNTS_GlobalService extends DyNTS_SingletonService {
       try {
         this.instance.dbServiceCollection[dbModel.dataName] = new DyNTS_DBService(dbModel);
       } catch (error) {
-        if (error instanceof DyFM_Error && !DyFM_global_settings.log_settings.highDetailedLogs) {
-          error.logSimple(`Failed to create DyNTS_DBService (${dbModel.dataName}).`);
-        } else {
-          DyFM_Log.error(`Failed to create DyNTS_DBService (${dbModel.dataName}).`, error);
-        }
+        DyNTS_SafeDiagnostic_ControlService.report({
+          code: 'DYNTS|GLOBAL|DB_SERVICE_CREATE_FAILED',
+          stage: DyNTS_SafeDiagnosticStage_Type.bootstrap,
+          error: error,
+        });
         
         throw new DyFM_Error({
           ...this.getDefaultErrorSettings('setDBServices', error, 'DyNTS_GlobalService'),
@@ -265,7 +269,7 @@ export class DyNTS_GlobalService extends DyNTS_SingletonService {
 
   private static async setErrorHandler(errorHandler?: DyNTS_GlobalErrorHandlerFn): Promise<void> {
     try {
-      DyNTS_GlobalService.globalErrorHandler = (async (error: any): Promise<void> => {
+      DyNTS_GlobalService.globalErrorHandler = (async (error: unknown): Promise<void> => {
         try {
           if (errorHandler) {
             await errorHandler(error);
@@ -280,20 +284,17 @@ export class DyNTS_GlobalService extends DyNTS_SingletonService {
               'please check if it is using the same node_modules as the app)'
           );
 
-          DyFM_Error.logSimple(`Error caught by globalErrorHandler.`, error);
+          DyNTS_SafeDiagnostic_ControlService.report({
+            code: 'DYNTS|GLOBAL|UNHANDLED_ERROR',
+            stage: DyNTS_SafeDiagnosticStage_Type.globalErrorHandler,
+            error: error,
+          });
         } catch (error) {
-          if (error instanceof DyFM_Error) {  
-            error.logSimple(
-              `NTS GLOBAL MULTILEVEL ERROR: ` +
-              `\nFailed to handle error on globalErrorHandler.`,
-            );
-          } else {
-            DyFM_Log.error(
-              `NTS GLOBAL MULTILEVEL ERROR: ` +
-              `\nFailed to handle error on globalErrorHandler.`,
-              (error as DyFM_Error)?.getErrorSimplified?.() ?? error
-            );
-          }
+          DyNTS_SafeDiagnostic_ControlService.report({
+            code: 'DYNTS|GLOBAL|HANDLER_FAILED',
+            stage: DyNTS_SafeDiagnosticStage_Type.globalErrorHandler,
+            error: error,
+          });
         }
       });
     } catch (error) {

package/src/_services/server/app-safe-diagnostic.spec.ts

@@ -0,0 +1,124 @@
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_App_Params } from '../../_models/control-models/app-params.control-model';
+import { DyNTS_Http_Settings } from '../../_models/control-models/http-settings.control-model';
+import { DyNTS_GlobalService_Settings } from '../../_models/interfaces/global-service-settings.interface';
+import { DyNTS_GlobalService } from '../core/global.service';
+import { DyNTS_App } from './app.server';
+
+class DyNTS_SafeDiagnosticTestApp extends DyNTS_App {
+  protected override asyncConstruct(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Supplies the minimal valid application parameters for the boundary test. */
+  getAppParams(): DyNTS_App_Params {
+    return new DyNTS_App_Params({
+      name: 'SafeDiagnosticTestApp',
+      version: '1.0.0',
+      dbName: 'safe_diagnostic_test',
+    });
+  }
+
+  /** Keeps the test application independent from concrete global services. */
+  getGlobalServiceCollection(): DyNTS_GlobalService_Settings {
+    return {};
+  }
+
+  /** Keeps the test application independent from a listening HTTP server. */
+  getPortSettings(): DyNTS_Http_Settings {
+    return new DyNTS_Http_Settings();
+  }
+}
+
+class DyNTS_FailingBootstrapTestApp extends DyNTS_SafeDiagnosticTestApp {
+  protected override asyncConstruct(): Promise<void> {
+    return Promise.reject(new Error(DyNTS_FailingBootstrapTestApp.canary));
+  }
+
+  static readonly canary: string = 'mongodb://bootstrap-user:bootstrap-secret@private-host.example/database';
+}
+
+describe('| DyNTS_App safe process boundary', (): void => {
+  const rejectionCanary: string = 'mongodb://rejection-user:rejection-secret@private-host.example/database';
+  let originalHandler: typeof DyNTS_GlobalService.globalErrorHandler;
+  let initialListeners: NodeJS.UnhandledRejectionListener[];
+
+  beforeEach((): void => {
+    originalHandler = DyNTS_GlobalService.globalErrorHandler;
+    initialListeners = process.listeners('unhandledRejection');
+  });
+
+  afterEach((): void => {
+    DyNTS_GlobalService.globalErrorHandler = originalHandler;
+    process.listeners('unhandledRejection').forEach((listener: NodeJS.UnhandledRejectionListener): void => {
+      if (!initialListeners.includes(listener)) {
+        process.removeListener('unhandledRejection', listener);
+      }
+    });
+  });
+
+  it('| projects an unhandled rejection before logging or forwarding it', async (): Promise<void> => {
+    const logSpy: jasmine.Spy = spyOn(DyFM_Log, 'error');
+    const handlerSpy: jasmine.Spy = jasmine.createSpy('globalErrorHandler').and.resolveTo();
+
+    DyNTS_GlobalService.globalErrorHandler = handlerSpy;
+    new DyNTS_SafeDiagnosticTestApp();
+
+    const addedListeners: NodeJS.UnhandledRejectionListener[] = process
+      .listeners('unhandledRejection')
+      .filter((listener: NodeJS.UnhandledRejectionListener): boolean => !initialListeners.includes(listener));
+
+    expect(addedListeners.length).toBe(1);
+    addedListeners[0](new Error(rejectionCanary), Promise.resolve());
+    await Promise.resolve();
+
+    const serializedLogs: string = JSON.stringify(logSpy.calls.allArgs());
+    const serializedForwardedError: string = JSON.stringify(handlerSpy.calls.mostRecent().args[0]);
+
+    expect(serializedLogs).toContain('dynts-safe-diagnostic/1');
+    expect(serializedForwardedError).toContain('dynts-safe-diagnostic/1');
+    expect(serializedForwardedError).toContain('DYNTS-AS0-BASE-UR');
+    expect(handlerSpy.calls.mostRecent().args.length).toBe(1);
+    expect(serializedLogs).not.toContain(rejectionCanary);
+    expect(serializedLogs).not.toContain('rejection-secret');
+    expect(serializedForwardedError).not.toContain(rejectionCanary);
+    expect(serializedForwardedError).not.toContain('rejection-secret');
+  });
+
+  it('| projects a bootstrap rejection before logging, forwarding and exiting', async (): Promise<void> => {
+    const logSpy: jasmine.Spy = spyOn(DyFM_Log, 'error');
+    const handlerSpy: jasmine.Spy = jasmine.createSpy('globalErrorHandler').and.resolveTo();
+    const exitSpy: jasmine.Spy = spyOn(process, 'exit');
+
+    DyNTS_GlobalService.globalErrorHandler = handlerSpy;
+    new DyNTS_FailingBootstrapTestApp();
+    await new Promise<void>((resolve: () => void): NodeJS.Immediate => setImmediate(resolve));
+
+    const serializedLogs: string = JSON.stringify(logSpy.calls.allArgs());
+    const serializedForwardedError: string = JSON.stringify(handlerSpy.calls.mostRecent().args[0]);
+
+    expect(exitSpy).toHaveBeenCalledOnceWith(1);
+    expect(serializedLogs).toContain('dynts-safe-diagnostic/1');
+    expect(serializedForwardedError).toContain('dynts-safe-diagnostic/1');
+    expect(serializedForwardedError).toContain('DYNTS-AS0-BOOTSTRAP-FAILED');
+    expect(handlerSpy.calls.mostRecent().args.length).toBe(1);
+    expect(serializedLogs).not.toContain(DyNTS_FailingBootstrapTestApp.canary);
+    expect(serializedLogs).not.toContain('bootstrap-secret');
+    expect(serializedForwardedError).not.toContain(DyNTS_FailingBootstrapTestApp.canary);
+    expect(serializedForwardedError).not.toContain('bootstrap-secret');
+  });
+
+  it('| projects raw failures in the default global error handler', async (): Promise<void> => {
+    const logSpy: jasmine.Spy = spyOn(DyFM_Log, 'error');
+
+    await DyNTS_GlobalService.setServices({});
+    await DyNTS_GlobalService.globalErrorHandler(new Error(rejectionCanary));
+
+    const serializedLogs: string = JSON.stringify(logSpy.calls.allArgs());
+
+    expect(serializedLogs).toContain('dynts-safe-diagnostic/1');
+    expect(serializedLogs).not.toContain(rejectionCanary);
+    expect(serializedLogs).not.toContain('rejection-secret');
+  });
+});