@lenne.tech/nest-server 11.31.3 → 11.32.0

package/src/core/common/helpers/process-diagnostics.helper.spec.ts

@@ -0,0 +1,310 @@
+import { EventEmitter } from 'node:events';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { handleFatalBootstrapError, installProcessDiagnostics } from './process-diagnostics.helper';
+
+// `vi.spyOn(fs, 'writeSync')` cannot work here — an ESM module namespace is not configurable, so
+// the property cannot be redefined. Mocking the module is the only way to observe the default
+// sink, and the helper imports nothing else from `node:fs`.
+const { writeSyncMock } = vi.hoisted(() => ({ writeSyncMock: vi.fn<(fd: number, data: string) => number>() }));
+vi.mock('node:fs', () => ({ writeSync: writeSyncMock }));
+
+/**
+ * Regression guard for the "silent exit" class of failures: a Node API under a ts-node dev
+ * runner can die printing nothing but `app crashed` — no stacktrace, which reads like a
+ * product bug and costs long, misdirected debugging sessions. The diagnostics helper makes
+ * the exit reason visible — a rejected fire-and-forget promise no longer takes the server
+ * down, an uncaught exception is logged with a clear marker before it exits, and an EXTERNAL
+ * termination signal (another tool's pkill, `lt dev down`, an OS OOM SIGTERM, Ctrl-C) is
+ * logged as such instead of masquerading as an in-process crash.
+ *
+ * The installer is tested against an injected EventEmitter so the real process (and the
+ * Vitest runner it lives in) is never signalled or exited.
+ *
+ * Repo-wiring assertions (src/main.ts, src/index.ts, nodemon.json) deliberately live in
+ * `tests/unit/process-diagnostics-wiring.spec.ts`, NOT here: this file ships inside `src/core/`
+ * and is copied verbatim into vendor-mode consumer projects, where those repo-root paths do not
+ * exist. Keeping this spec free of `process.cwd()` is what makes it portable.
+ */
+function setup(
+  preRegister?: Partial<Record<string, () => void>>,
+  options?: Parameters<typeof installProcessDiagnostics>[0],
+) {
+  const target = new EventEmitter();
+  target.setMaxListeners(50);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const logger = {
+    error: (message: string) => errors.push(message),
+    warn: (message: string) => warnings.push(message),
+  };
+  const exit = vi.fn();
+  const reraise = vi.fn();
+  if (preRegister) {
+    for (const [event, fn] of Object.entries(preRegister)) {
+      target.on(event, fn);
+    }
+  }
+  installProcessDiagnostics({ exit, logger, reraise, target, ...options });
+  return { errors, exit, reraise, target, warnings };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
+
+describe('installProcessDiagnostics', () => {
+  it('logs an unhandled rejection but keeps the process alive', () => {
+    const { exit, target, warnings } = setup();
+    target.emit('unhandledRejection', new Error('SMTP down'));
+    expect(warnings.some((line) => line.includes('[unhandledRejection]') && line.includes('SMTP down'))).toBe(true);
+    expect(exit).not.toHaveBeenCalled();
+  });
+
+  it('routes an unhandled rejection to the NON-blocking sink', () => {
+    // An unhandled rejection can fire once per request while the server keeps serving. A
+    // synchronous write would block the whole event loop until stderr drains, so this path must
+    // use `warn` (async) and never `error` (sync). Nothing is terminating, so there is no
+    // last-gasp guarantee worth blocking for.
+    const { errors, target, warnings } = setup();
+    target.emit('unhandledRejection', new Error('per-request failure'));
+    expect(warnings).toHaveLength(1);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('formats a non-Error rejection reason via String()', () => {
+    const { target, warnings } = setup();
+    target.emit('unhandledRejection', 'plain string reason');
+    expect(warnings.some((line) => line.includes('[unhandledRejection]') && line.includes('plain string reason'))).toBe(
+      true,
+    );
+  });
+
+  it('exits on an unhandled rejection when onUnhandledRejection is "exit"', () => {
+    // Restores Node >= 15's own `--unhandled-rejections=throw` default for deployments that
+    // prefer a clean restart over serving from an unknown state.
+    const { errors, exit, target } = setup(undefined, { onUnhandledRejection: 'exit' });
+    target.emit('unhandledRejection', new Error('inconsistent state'));
+    expect(errors.some((line) => line.includes('[unhandledRejection]'))).toBe(true);
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+
+  it('logs an uncaught exception with a marker and exits with code 1', () => {
+    const { errors, exit, target } = setup();
+    target.emit('uncaughtException', new Error('boom'));
+    expect(errors.some((line) => line.includes('[uncaughtException]') && line.includes('boom'))).toBe(true);
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+
+  it('does NOT print the error message twice', () => {
+    // `error.stack` already begins with `${name}: ${message}`. Prefixing the message again put the
+    // same line in the output twice, which reads like two distinct failures.
+    const { errors, target } = setup();
+    const error = new Error('duplicated');
+    target.emit('uncaughtException', error);
+    const occurrences = errors[0].split('duplicated').length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it('falls back to name + message when an Error carries no stack', () => {
+    const { errors, target } = setup();
+    const error = new Error('no stack here');
+    error.stack = undefined;
+    target.emit('uncaughtException', error);
+    expect(errors[0]).toContain('Error: no stack here');
+  });
+
+  it('does NOT register a process warning handler', () => {
+    // Node prints process warnings to stderr itself and adding a listener does not replace that —
+    // it appends a second, strictly worse copy (Node's own line carries the warning `name` and the
+    // `--trace-warnings` hint). Duplicating it doubles the volume on a path that fires during
+    // normal operation.
+    const { target } = setup();
+    expect(target.listenerCount('warning')).toBe(0);
+  });
+
+  it('logs a non-zero exit code', () => {
+    const { errors, target } = setup();
+    target.emit('exit', 143);
+    expect(errors.some((line) => line.includes('[exit]') && line.includes('143'))).toBe(true);
+  });
+
+  it('stays silent on a clean exit', () => {
+    // A clean exit is not a diagnostic. Logging it under every CLI script and every graceful
+    // shutdown trains readers to ignore the marker.
+    const { errors, target } = setup();
+    target.emit('exit', 0);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('logs SIGTERM as external termination and re-raises it when it is the only listener', () => {
+    const { errors, exit, reraise, target } = setup();
+    target.emit('SIGTERM', 'SIGTERM');
+    expect(errors.some((line) => line.includes('[signal]') && line.includes('SIGTERM'))).toBe(true);
+    expect(reraise).toHaveBeenCalledWith('SIGTERM');
+    expect(exit).not.toHaveBeenCalled();
+    // The handler MUST remove itself before re-raising — otherwise the re-raised signal
+    // re-enters the same handler forever (infinite log-and-re-raise loop, never terminates).
+    expect(target.listenerCount('SIGTERM')).toBe(0);
+  });
+
+  it('logs SIGINT and re-raises it when it is the only listener', () => {
+    const { errors, reraise, target } = setup();
+    target.emit('SIGINT', 'SIGINT');
+    expect(errors.some((line) => line.includes('[signal]') && line.includes('SIGINT'))).toBe(true);
+    expect(reraise).toHaveBeenCalledWith('SIGINT');
+    expect(target.listenerCount('SIGINT')).toBe(0);
+  });
+
+  it.each(['SIGHUP', 'SIGQUIT'] as const)('labels %s as an external termination too', (signal) => {
+    // A closed terminal (SIGHUP) or a SIGQUIT from an orchestrator used to terminate unannotated,
+    // producing exactly the stackless death this helper exists to explain.
+    const { errors, reraise, target } = setup();
+    target.emit(signal, signal);
+    expect(errors.some((line) => line.includes('[signal]') && line.includes(signal))).toBe(true);
+    expect(reraise).toHaveBeenCalledWith(signal);
+  });
+
+  it('does NOT touch SIGUSR2', () => {
+    // nodemon restarts the app with SIGUSR2. Attaching a listener overrides its disposition, and
+    // labelling a restart is not worth changing how restarts behave.
+    const { target } = setup();
+    expect(target.listenerCount('SIGUSR2')).toBe(0);
+  });
+
+  it('does NOT re-raise a signal when a graceful-shutdown handler is also registered', () => {
+    // `app.enableShutdownHooks()` registers its own SIGTERM/SIGINT listener. Re-raising on top of
+    // it would kill the process mid-shutdown and defeat the graceful teardown.
+    const other = vi.fn();
+    const { errors, reraise, target } = setup({ SIGTERM: other }, { shutdownTimeoutMs: 0 });
+    target.emit('SIGTERM', 'SIGTERM');
+    expect(errors.some((line) => line.includes('[signal]'))).toBe(true);
+    expect(errors.some((line) => line.includes('another handler owns the shutdown'))).toBe(true);
+    expect(reraise).not.toHaveBeenCalled();
+  });
+
+  it('forces an exit when the co-listener never finishes the shutdown', () => {
+    // Abdicating unconditionally means a co-listener that never terminates makes SIGTERM a
+    // permanent no-op while the log line claims the process is going down — only SIGKILL would
+    // still work. The watchdog bounds that.
+    vi.useFakeTimers();
+    const { errors, exit, target } = setup({ SIGTERM: vi.fn() }, { shutdownTimeoutMs: 30_000 });
+    target.emit('SIGTERM', 'SIGTERM');
+    expect(exit).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(30_000);
+    expect(errors.some((line) => line.includes('shutdown watchdog expired'))).toBe(true);
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+
+  it('does not arm the watchdog when shutdownTimeoutMs is 0', () => {
+    vi.useFakeTimers();
+    const { exit, target } = setup({ SIGTERM: vi.fn() }, { shutdownTimeoutMs: 0 });
+    target.emit('SIGTERM', 'SIGTERM');
+    vi.advanceTimersByTime(120_000);
+    expect(exit).not.toHaveBeenCalled();
+  });
+
+  it('is idempotent — installing twice does not stack duplicate handlers', () => {
+    const target = new EventEmitter();
+    const logger = { error: () => undefined };
+    const exit = vi.fn();
+    const reraise = vi.fn();
+    installProcessDiagnostics({ exit, logger, reraise, target });
+    installProcessDiagnostics({ exit, logger, reraise, target });
+    expect(target.listenerCount('uncaughtException')).toBe(1);
+    expect(target.listenerCount('unhandledRejection')).toBe(1);
+    expect(target.listenerCount('SIGTERM')).toBe(1);
+    expect(target.listenerCount('SIGINT')).toBe(1);
+  });
+
+  it('falls back to the error sink when a custom logger provides no warn', () => {
+    const target = new EventEmitter();
+    const errors: string[] = [];
+    installProcessDiagnostics({
+      exit: vi.fn(),
+      logger: { error: (message: string) => errors.push(message) },
+      reraise: vi.fn(),
+      target,
+    });
+    target.emit('unhandledRejection', new Error('no warn sink'));
+    expect(errors.some((line) => line.includes('[unhandledRejection]'))).toBe(true);
+  });
+});
+
+describe('redaction and truncation', () => {
+  it('masks a JWT and truncates an oversized line', () => {
+    const target = new EventEmitter();
+    const warnings: string[] = [];
+    installProcessDiagnostics({
+      exit: vi.fn(),
+      logger: { error: () => undefined, warn: (message: string) => warnings.push(message) },
+      reraise: vi.fn(),
+      target,
+    });
+    const jwt = `eyJhbGciOiJIUzI1NiJ9.${'a'.repeat(40)}.${'b'.repeat(20)}`;
+    const error = new Error(`token=${jwt} ${'x'.repeat(30_000)}`);
+    error.stack = `Error: token=${jwt} ${'x'.repeat(30_000)}`;
+    target.emit('unhandledRejection', error);
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).not.toContain(jwt);
+    expect(warnings[0]).toContain('[truncated]');
+    expect(warnings[0].length).toBeLessThan(20_000);
+  });
+});
+
+describe('defaultDiagnosticsLogger', () => {
+  it('writes synchronously to fd 2 so a last-gasp line cannot be truncated', () => {
+    // console.error is asynchronous on a pipe, so a line written immediately before process.exit()
+    // can be dropped — silently losing the very line this helper exists to emit.
+    writeSyncMock.mockReset();
+    writeSyncMock.mockReturnValue(0);
+    const target = new EventEmitter();
+    installProcessDiagnostics({ exit: vi.fn(), reraise: vi.fn(), target });
+    target.emit('uncaughtException', new Error('sync sink'));
+
+    expect(writeSyncMock).toHaveBeenCalled();
+    const [fd, payload] = writeSyncMock.mock.calls[0];
+    expect(fd).toBe(2);
+    expect(String(payload)).toContain('[uncaughtException]');
+  });
+
+  it('survives a broken stderr instead of escalating', () => {
+    // EBADF (fd 2 closed), EPIPE (reader exited) and EAGAIN (non-blocking pipe) all make writeSync
+    // throw. A throw raised INSIDE the uncaughtException handler makes Node exit 7 and print its
+    // own "throw inside handler" message — losing the original error entirely.
+    writeSyncMock.mockReset();
+    writeSyncMock.mockImplementation(() => {
+      throw Object.assign(new Error('EBADF: bad file descriptor'), { code: 'EBADF' });
+    });
+    const exit = vi.fn();
+    const target = new EventEmitter();
+    installProcessDiagnostics({ exit, reraise: vi.fn(), target });
+
+    expect(() => target.emit('uncaughtException', new Error('original failure'))).not.toThrow();
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('handleFatalBootstrapError', () => {
+  it('logs a failed bootstrap with a marker and exits with code 1', () => {
+    const errors: string[] = [];
+    const logger = { error: (message: string) => errors.push(message) };
+    const exit = vi.fn();
+    handleFatalBootstrapError(new Error('listen EADDRINUSE: address already in use'), { exit, logger });
+    expect(errors.some((line) => line.includes('[bootstrap]') && line.includes('EADDRINUSE'))).toBe(true);
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+
+  it('redacts secrets out of a startup error before logging it', () => {
+    // The documented motivating failures ("DB unreachable") carry connection strings.
+    const errors: string[] = [];
+    const exit = vi.fn();
+    handleFatalBootstrapError(new Error('connect failed: password=hunter2'), {
+      exit,
+      logger: { error: (message: string) => errors.push(message) },
+    });
+    expect(errors[0]).not.toContain('hunter2');
+  });
+});

package/src/core/common/helpers/process-diagnostics.helper.ts

@@ -0,0 +1,321 @@
+/**
+ * Process-level exit diagnostics.
+ *
+ * A Node API can die "silently": the dev runner (`nodemon`, `lt dev`) prints only
+ * `app crashed - waiting for file changes before starting...` with NO stacktrace, and in a
+ * container the process simply vanishes. A missing stacktrace means the process was killed by a
+ * SIGNAL rather than throwing — either an OS OOM SIGKILL (uncatchable) or an EXTERNAL
+ * SIGTERM/SIGINT (an orchestrator's stop, another tool's pkill, `lt dev down`, Ctrl-C).
+ *
+ * `installProcessDiagnostics()` makes the exit reason visible:
+ * - `unhandledRejection` is logged but NOT fatal by default — a rejected fire-and-forget promise
+ *   (e.g. a transactional email failing on an auth path outside a try/catch) must never take the
+ *   whole server down. Set `onUnhandledRejection: 'exit'` to restore Node's own fail-fast.
+ * - `uncaughtException` is logged with a clear marker and then exits(1) — process state is unknown
+ *   after one, so crashing and being restarted is the safe behaviour, but with a guaranteed log
+ *   line above the runner's "app crashed".
+ * - a NON-ZERO `exit` code is logged (a clean exit needs no explanation and no extra line).
+ * - termination signals are logged as EXTERNAL terminations so they stop masquerading as
+ *   in-process crashes.
+ *
+ * **Deliberately NOT handled: process `warning`s.** Node prints them to stderr itself, and adding a
+ * listener does not replace that — it appends a second, strictly worse copy (Node's own line
+ * carries the warning `name` and the `--trace-warnings` hint; ours would not). Duplicating it would
+ * double the volume on the one path that fires during normal operation. Use `--trace-warnings`
+ * instead when a warning needs a stack.
+ *
+ * **Call it from `main.ts`, not from a module.** It is deliberately NOT wired into
+ * `CoreModule.forRoot()`:
+ * 1. It must run BEFORE `NestFactory.create()` to catch failures during module construction —
+ *    inside a module it would already be too late.
+ * 2. It installs a `process.exit(1)` path. Registering that from a module would also arm it inside
+ *    `Test.createTestingModule()`, where an uncaught exception would then kill the whole test
+ *    runner instead of failing one spec.
+ *
+ * **Known limitation:** it cannot cover failures during synchronous *import* evaluation of
+ * `main.ts` (a throwing `config.env.ts`, an SWC temporal-dead-zone `ReferenceError`), because
+ * imports are hoisted above the first statement of `bootstrap()`. That class of failure is loud
+ * anyway — Node prints it with a full stack. Only a `--require` preload module could cover it.
+ *
+ * **Pair it with `enableShutdownHooks()`.** On its own this helper labels a signal; it does not
+ * make the process terminate on one. In a container Node is PID 1, where a userspace re-raise with
+ * the default disposition is silently discarded by the kernel — the event loop stays busy and
+ * `docker stop` waits out its grace period before SIGKILL. `app.enableShutdownHooks()` is what
+ * actually drains the loop, and this helper then correctly defers to it.
+ *
+ * @example
+ * ```typescript
+ * // src/main.ts
+ * import { handleFatalBootstrapError, installProcessDiagnostics } from '@lenne.tech/nest-server';
+ *
+ * async function bootstrap() {
+ *   installProcessDiagnostics();
+ *   const server = await NestFactory.create<NestExpressApplication>(ServerModule);
+ *   server.enableShutdownHooks(); // required for a graceful container stop
+ *   await server.listen(envConfig.port);
+ * }
+ *
+ * // A rejection here is a fatal startup failure — exit instead of leaving a zombie process.
+ * bootstrap().catch(handleFatalBootstrapError);
+ * ```
+ */
+
+import { writeSync } from 'node:fs';
+
+import { redactSensitiveText } from './logging.helper';
+
+/**
+ * Hard cap for a single diagnostic line.
+ *
+ * `describeError` renders a caller-controlled value — a rejected promise can carry an object whose
+ * `toString()` returns megabytes. One unbounded synchronous write would stall the event loop for
+ * its whole duration.
+ */
+const MAX_DIAGNOSTIC_CHARS = 16_384;
+
+/** Minimal logger surface — `console` satisfies it. */
+export interface DiagnosticsLogger {
+  /**
+   * Sink for TERMINAL diagnostics (uncaught exception, non-zero exit, signals, fatal bootstrap).
+   * These are written immediately before the process goes away, so the default implementation is
+   * synchronous.
+   */
+  error: (message: string) => void;
+  /**
+   * Sink for NON-TERMINAL diagnostics (an unhandled rejection while the server keeps serving).
+   * Defaults to `error` when omitted. The default implementation is ASYNCHRONOUS on purpose — see
+   * {@link defaultDiagnosticsLogger}.
+   */
+  warn?: (message: string) => void;
+}
+
+/**
+ * Caps and redacts a diagnostic line before it reaches any sink.
+ *
+ * Redaction matters because this sink deliberately bypasses the Nest logger, and with it every
+ * structured-log redaction a consumer has configured. The framework's own `redactSensitiveText`
+ * is the same one the Hub log buffer uses, so a connection string or bearer token in an error
+ * message is masked here exactly as it would be there.
+ *
+ * @param message - The raw diagnostic line
+ * @returns The line, truncated to {@link MAX_DIAGNOSTIC_CHARS} and redacted
+ */
+function formatDiagnostic(message: string): string {
+  // Cap BEFORE redacting: only the truncated head is ever emitted, so redacting the discarded
+  // tail would be wasted work on the very path that must stay cheap.
+  const capped =
+    message.length > MAX_DIAGNOSTIC_CHARS ? `${message.slice(0, MAX_DIAGNOSTIC_CHARS)}… [truncated]` : message;
+  return redactSensitiveText(capped);
+}
+
+/**
+ * Default diagnostic sink.
+ *
+ * `error` is a SYNCHRONOUS write to fd 2 (stderr). `console.error` is asynchronous on a pipe, so a
+ * last-gasp line written immediately before `process.exit()` or a signal re-raise can be truncated
+ * — silently dropping the very line this helper exists to emit. `writeSync` completes before we
+ * terminate.
+ *
+ * `warn` is deliberately ASYNCHRONOUS. A synchronous write blocks the whole event loop until the
+ * pipe drains, so on the one path that fires while the server is still serving — an unhandled
+ * rejection, potentially once per request — a stalled log collector would stall the entire process.
+ * Nothing is about to terminate there, so there is no last-gasp guarantee to preserve.
+ *
+ * Both bypass the Nest logger (including any JSON logger configured for production): these lines
+ * must survive the exact moments when the DI container is being torn down or is already gone.
+ * Structured-log consumers see them as plain stderr records. Pass a custom `logger` if they must be
+ * routed elsewhere.
+ */
+const defaultDiagnosticsLogger: DiagnosticsLogger = {
+  error: (message: string) => {
+    try {
+      writeSync(2, `${message}\n`);
+    } catch {
+      // EBADF (fd 2 closed), EPIPE (reader exited — routine under `| head` or a detached log
+      // driver), EAGAIN (non-blocking pipe under backpressure). A diagnostic line is best-effort:
+      // throwing here would escalate. Worse, a throw raised INSIDE the uncaughtException handler
+      // makes Node exit 7 and print its own "throw inside handler" message instead of the original
+      // error — inverting the entire purpose of this helper.
+    }
+  },
+  warn: (message: string) => {
+    console.error(message);
+  },
+};
+
+/** Options for {@link installProcessDiagnostics}. All dependencies are injectable for testing. */
+export interface ProcessDiagnosticsOptions {
+  /** Process-exit function. Defaults to `process.exit`. Injected in tests. */
+  exit?: (code: number) => void;
+  /** Logger for the diagnostic lines. Defaults to a synchronous stderr sink. */
+  logger?: DiagnosticsLogger;
+  /**
+   * What to do on an unhandled rejection.
+   *
+   * - `'log'` (default): log and continue — a fire-and-forget failure must not take the server down.
+   * - `'exit'`: log and `exit(1)`, restoring Node >= 15's own `--unhandled-rejections=throw`
+   *   default for deployments that prefer a clean restart over serving from an unknown state.
+   *
+   * @default 'log'
+   */
+  onUnhandledRejection?: 'exit' | 'log';
+  /** Re-raise a signal with its default disposition. Defaults to `process.kill(process.pid, signal)`. */
+  reraise?: (signal: NodeJS.Signals) => void;
+  /**
+   * How long to wait for another signal handler (e.g. `enableShutdownHooks()`) to finish the
+   * shutdown before forcing an exit. `0` disables the watchdog.
+   *
+   * Without it, a co-listener that never terminates makes SIGTERM a permanent no-op while the log
+   * line claims the process is going down — only SIGKILL would still work.
+   *
+   * @default 30000
+   */
+  shutdownTimeoutMs?: number;
+  /** Event target to attach handlers to. Defaults to the global `process`. Injected in tests. */
+  target?: NodeJS.EventEmitter;
+}
+
+/**
+ * Signals whose default disposition is to terminate the process.
+ *
+ * `SIGUSR2` is deliberately absent: nodemon uses it to trigger a restart, and attaching a listener
+ * overrides its disposition. Labelling a restart is not worth the risk of changing how it behaves.
+ */
+const TERMINATION_SIGNALS: readonly NodeJS.Signals[] = ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT'];
+
+/** Guards against double-installation (e.g. an accidental second bootstrap call). */
+const installedTargets = new WeakSet<object>();
+
+/**
+ * Renders any thrown value as a loggable string, preserving the stack when there is one.
+ *
+ * @param value - The thrown / rejected value (not necessarily an `Error`)
+ * @returns The stack for an `Error` (it already begins with `name: message`), `String(value)` otherwise
+ */
+function describeError(value: unknown): string {
+  if (value instanceof Error) {
+    // `stack` already starts with `${name}: ${message}` — prefixing the message again would print
+    // it twice. Fall back to that same shape when a stack is missing.
+    return value.stack ?? `${value.name}: ${value.message}`;
+  }
+  return String(value);
+}
+
+/**
+ * Attaches the process-level diagnostic handlers. Idempotent per target — calling it twice does
+ * not stack duplicate listeners.
+ *
+ * Call this as the first statement of `bootstrap()`, before `NestFactory.create()`. See the module
+ * docblock for why it must not live inside `CoreModule.forRoot()`.
+ *
+ * @param options - Injectable dependencies; defaults target the real `process`
+ *
+ * @example
+ * installProcessDiagnostics();
+ * installProcessDiagnostics({ onUnhandledRejection: 'exit' }); // restore Node's fail-fast
+ */
+export function installProcessDiagnostics(options: ProcessDiagnosticsOptions = {}): void {
+  const target: NodeJS.EventEmitter = options.target ?? process;
+  const logger: DiagnosticsLogger = options.logger ?? defaultDiagnosticsLogger;
+  const exit: (code: number) => void = options.exit ?? ((code: number) => process.exit(code));
+  const reraise: (signal: NodeJS.Signals) => void =
+    options.reraise ?? ((signal: NodeJS.Signals) => process.kill(process.pid, signal));
+  const onUnhandledRejection: 'exit' | 'log' = options.onUnhandledRejection ?? 'log';
+  const shutdownTimeoutMs: number = options.shutdownTimeoutMs ?? 30_000;
+
+  // Non-terminal lines go through `warn` (async, cannot block the event loop); everything else
+  // through `error` (sync, survives teardown). A custom logger may omit `warn` — then it opts into
+  // its own `error` for both.
+  const logTerminal = (message: string): void => logger.error(formatDiagnostic(message));
+  const logNonTerminal = (message: string): void => (logger.warn ?? logger.error)(formatDiagnostic(message));
+
+  if (installedTargets.has(target)) {
+    return;
+  }
+  installedTargets.add(target);
+
+  target.on('unhandledRejection', (reason: unknown) => {
+    if (onUnhandledRejection === 'exit') {
+      logTerminal(`[unhandledRejection] ${describeError(reason)}`);
+      exit(1);
+      return;
+    }
+    logNonTerminal(`[unhandledRejection] ${describeError(reason)}`);
+  });
+
+  target.on('uncaughtException', (error: unknown) => {
+    logTerminal(`[uncaughtException] ${describeError(error)}`);
+    exit(1);
+  });
+
+  target.on('exit', (code: unknown) => {
+    // A clean exit is not a diagnostic. Logging it unconditionally puts a line under every CLI
+    // script and every graceful shutdown, which trains readers to ignore the marker.
+    if (code !== 0) {
+      logTerminal(`[exit] process exiting with code ${String(code)}`);
+    }
+  });
+
+  for (const signal of TERMINATION_SIGNALS) {
+    const handler = (received: NodeJS.Signals): void => {
+      // Attaching a listener overrode Node's default terminate disposition. When we are the only
+      // listener, re-raise the signal so the process still terminates as it would have. If another
+      // handler is also registered (e.g. `app.enableShutdownHooks()`), let it own the exit.
+      const alone = target.listenerCount(signal) <= 1;
+      logTerminal(
+        `[signal] received ${received} — external termination (not an in-process crash)${
+          alone ? '' : ' — another handler owns the shutdown'
+        }`,
+      );
+
+      if (alone) {
+        target.removeListener(signal, handler);
+        reraise(received);
+        return;
+      }
+
+      if (shutdownTimeoutMs > 0) {
+        // The co-listener owns the exit — but it may never reach one. Do not stay hostage forever:
+        // an unkillable-by-SIGTERM process is worse than an ungraceful one.
+        const watchdog = setTimeout(() => {
+          logTerminal(`[signal] shutdown watchdog expired after ${shutdownTimeoutMs}ms — forcing exit`);
+          exit(1);
+        }, shutdownTimeoutMs);
+        // Never keep the event loop alive purely for the watchdog.
+        watchdog.unref?.();
+      }
+    };
+    target.on(signal, handler);
+  }
+}
+
+/** Options for {@link handleFatalBootstrapError}. All dependencies are injectable for testing. */
+export interface FatalBootstrapErrorOptions {
+  /** Process-exit function. Defaults to `process.exit`. Injected in tests. */
+  exit?: (code: number) => void;
+  /** Logger for the diagnostic line. Defaults to a synchronous stderr sink. */
+  logger?: DiagnosticsLogger;
+}
+
+/**
+ * Terminal handler for a failed server bootstrap. Use it as the `catch` of the fire-and-forget
+ * `bootstrap()` call in `main.ts`.
+ *
+ * Without it, a rejection from `bootstrap()` (e.g. `server.listen` failing with EADDRINUSE, or a
+ * MongoDB connection error) surfaces as a mere `unhandledRejection` — which the runtime guard logs
+ * but does NOT act on, leaving a ZOMBIE process that is "alive" but listening on nothing. A startup
+ * failure is fatal: log it loudly and exit so the supervisor (nodemon in dev, the container runtime
+ * in production) restarts a clean instance.
+ *
+ * @param error - The rejection value from `bootstrap()`
+ * @param options - Injectable dependencies; defaults exit the real process
+ *
+ * @example
+ * bootstrap().catch(handleFatalBootstrapError);
+ */
+export function handleFatalBootstrapError(error: unknown, options: FatalBootstrapErrorOptions = {}): void {
+  const logger: DiagnosticsLogger = options.logger ?? defaultDiagnosticsLogger;
+  const exit: (code: number) => void = options.exit ?? ((code: number) => process.exit(code));
+  logger.error(formatDiagnostic(`[bootstrap] fatal startup error — exiting: ${describeError(error)}`));
+  exit(1);
+}

package/src/core/common/interfaces/server-options.interface.ts

@@ -1520,6 +1520,19 @@ export interface IServerOptions {
      */
     exclude?: RegExp;
 
+    /**
+     * How often the SDK retries a failed send (408 / 429 / 5xx).
+     *
+     * The Brevo SDK defaults to 2 retries and honours `Retry-After` with a cap of 60 SECONDS per
+     * attempt. `BrevoService.sendMail()` is awaited inside request handlers (e.g. the BetterAuth
+     * email-verification hook), so a rate-limited Brevo can otherwise park a user-facing HTTP
+     * request for roughly two minutes. The framework default of `0` keeps the request fast and
+     * leaves retrying to the caller.
+     *
+     * @default 0
+     */
+    maxRetries?: number;
+
     /**
      * Default sender for Brevo
      */
@@ -1527,6 +1540,25 @@ export interface IServerOptions {
       email: string;
       name: string;
     };
+
+    /**
+     * Whether a failed send should throw instead of resolving to `null`.
+     *
+     * `false` (default) preserves the historical contract: errors are logged and the method
+     * resolves to `null`. Set `true` when the caller must not proceed on a silent failure — the
+     * framework's own email-verification path checks the `null` either way.
+     *
+     * @default false
+     */
+    throwOnError?: boolean;
+
+    /**
+     * Per-request timeout in seconds. Unset means no timeout — a hung connection is then bounded
+     * only by the HTTP agent's own (300 s) limits, multiplied by `maxRetries`.
+     *
+     * @default 10
+     */
+    timeoutInSeconds?: number;
   };
 
   /**