@zudojs/core 1.0.0 → 1.2.0

package/dist/runtime/runtimeShutdown/pipeline/runtimeShutdown.pipeline.js

@@ -17,16 +17,24 @@ export async function executeShutdownPipeline(options, services, state, signal,
         runtimeName: services.runtimeName,
     };
     if (options.stopModules) {
-        await runShutdownPhase("stopping", "stopped", () => moduleLifecycle.stop(), moduleLifecycle, options.continueOnStopError, (count) => {
+        await runShutdownPhase("stopping", "stopped", () => moduleLifecycle.stop(phaseOptions(options.continueOnStopError)), moduleLifecycle, options.continueOnStopError, (count) => {
             state.counters.stoppedModules = count;
         }, RuntimeErrorCode.MODULE_STOP_FAILED, identity, state, publish, log);
     }
     if (options.destroyModules) {
-        await runShutdownPhase("destroying", "destroyed", () => moduleLifecycle.destroy(), moduleLifecycle, options.continueOnDestroyError, (count) => {
+        await runShutdownPhase("destroying", "destroyed", () => moduleLifecycle.destroy(phaseOptions(options.continueOnDestroyError)), moduleLifecycle, options.continueOnDestroyError, (count) => {
             state.counters.destroyedModules = count;
         }, RuntimeErrorCode.MODULE_DESTROY_FAILED, identity, state, publish, log);
     }
 }
+/**
+ * Per-phase options for the ModuleLifecycleManager: the runtime flag
+ * relaxes the manager when on and leaves its own setting when off
+ * (see the bootstrap pipeline for the rationale).
+ */
+function phaseOptions(continueOnError) {
+    return continueOnError ? { continueOnError: true } : {};
+}
 async function runShutdownPhase(phase, donePhase, run, moduleLifecycle, continueOnError, setCount, code, identity, state, publish, log) {
     publish(phase);
     log("debug", `Runtime modules ${phase}.`);

package/dist/runtime/runtimeSignals/runtimeSignals.d.ts

@@ -1,5 +1,11 @@
 import type { Logger } from "../../logging/core/logger.js";
 import type { RuntimeSignalOptions } from "../runtimeOptions/runtimeOptions.type.js";
+/**
+ * Fatal-exit settings are optional on the manager so that a
+ * hand-assembled `signals` object from before they existed still
+ * type-checks; they default to exiting after 10 seconds.
+ */
+type ManagerSignalOptions = Required<Omit<RuntimeSignalOptions, "exitOnFatalError" | "fatalExitTimeout">> & Pick<RuntimeSignalOptions, "exitOnFatalError" | "fatalExitTimeout">;
 /**
  * Termination signals the runtime can react to.
  */
@@ -39,7 +45,7 @@ export interface RuntimeSignalHandlers {
  * Options for the signal manager.
  */
 export interface RuntimeSignalManagerOptions {
-    readonly signals: Required<RuntimeSignalOptions>;
+    readonly signals: ManagerSignalOptions;
     readonly target?: RuntimeSignalTarget;
     readonly logger?: Logger;
 }
@@ -52,8 +58,11 @@ export interface RuntimeSignalManagerOptions {
  *   `unregister()`; both are idempotent.
  * - The first termination signal triggers `onSignal` (graceful stop).
  * - A second termination signal while the first is still being
- *   handled is logged and ignored, unless `forceExitOnSecondSignal`
- *   is on, in which case `target.exit(forceExitCode)` is called.
+ *   handled exits with `forceExitCode` when `forceExitOnSecondSignal`
+ *   is on (the default), and is logged and ignored otherwise.
+ * - An uncaught exception or unhandled rejection runs the fatal
+ *   handler and then exits with code 1, unless `exitOnFatalError` is
+ *   off; `fatalExitTimeout` bounds a shutdown that hangs.
  * - `process.exit` is never called otherwise.
  */
 export declare class RuntimeSignalManager {
@@ -88,6 +97,8 @@ export declare class RuntimeSignalManager {
     unregister(): void;
     private createListener;
     private handleSignal;
+    private runFatal;
     private run;
 }
+export {};
 //# sourceMappingURL=runtimeSignals.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.fatal.d.ts

@@ -0,0 +1,29 @@
+import type { Logger } from "../../logging/core/logger.js";
+import type { RuntimeSignalTarget } from "./runtimeSignals.js";
+/** Default grace period for a fatal-error shutdown, in milliseconds. */
+export declare const DEFAULT_FATAL_EXIT_TIMEOUT = 10000;
+/**
+ * How a fatal process event (uncaughtException, unhandledRejection)
+ * ends the process.
+ */
+export interface RuntimeFatalExitPolicy {
+    /** Exit non-zero once the fatal-error shutdown settles. */
+    readonly exitOnFatalError: boolean;
+    /** Exit anyway if that shutdown takes longer than this. */
+    readonly fatalExitTimeout: number;
+    /** Exit code used for a fatal exit. */
+    readonly exitCode: number;
+}
+/**
+ * Runs the runtime's fatal-error handler and then ends the process
+ * with a non-zero code.
+ *
+ * Installing an `uncaughtException` listener suppresses Node's own
+ * crash, so without an explicit exit the process either ended with
+ * code 0 (supervisors saw a clean exit and never restarted or alerted)
+ * or lingered as a stopped zombie behind any open handle. The grace
+ * timer bounds a shutdown that hangs; both are skipped when
+ * `exitOnFatalError` is off.
+ */
+export declare function runFatalHandler(handler: () => void | Promise<void> | undefined, target: RuntimeSignalTarget | undefined, policy: RuntimeFatalExitPolicy, logger: Logger | undefined, event: string): void;
+//# sourceMappingURL=runtimeSignals.fatal.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.fatal.js

@@ -0,0 +1,51 @@
+/** Default grace period for a fatal-error shutdown, in milliseconds. */
+export const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
+/**
+ * Runs the runtime's fatal-error handler and then ends the process
+ * with a non-zero code.
+ *
+ * Installing an `uncaughtException` listener suppresses Node's own
+ * crash, so without an explicit exit the process either ended with
+ * code 0 (supervisors saw a clean exit and never restarted or alerted)
+ * or lingered as a stopped zombie behind any open handle. The grace
+ * timer bounds a shutdown that hangs; both are skipped when
+ * `exitOnFatalError` is off.
+ */
+export function runFatalHandler(handler, target, policy, logger, event) {
+    const exit = () => {
+        if (!policy.exitOnFatalError)
+            return;
+        target?.exit?.(policy.exitCode);
+    };
+    let timer;
+    if (policy.exitOnFatalError && policy.fatalExitTimeout > 0) {
+        timer = setTimeout(() => {
+            logger?.error(`Runtime shutdown after ${event} timed out; exiting.`, {
+                event,
+                timeoutMs: policy.fatalExitTimeout,
+            });
+            exit();
+        }, Math.min(policy.fatalExitTimeout, 2_147_483_647));
+        timer.unref?.();
+    }
+    const finish = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        exit();
+    };
+    let result;
+    try {
+        result = handler();
+    }
+    catch (error) {
+        logger?.error(`Runtime ${event} handler failed.`, error, { event });
+        finish();
+        return;
+    }
+    void Promise.resolve(result)
+        .catch((error) => {
+        logger?.error(`Runtime ${event} handler failed.`, error, { event });
+    })
+        .finally(finish);
+}
+//# sourceMappingURL=runtimeSignals.fatal.js.map

package/dist/runtime/runtimeSignals/runtimeSignals.js

@@ -1,3 +1,4 @@
+import { DEFAULT_FATAL_EXIT_TIMEOUT, runFatalHandler, } from "./runtimeSignals.fatal.js";
 /**
  * Registers and removes process signal/exception handlers on behalf
  * of the runtime.
@@ -7,8 +8,11 @@
  *   `unregister()`; both are idempotent.
  * - The first termination signal triggers `onSignal` (graceful stop).
  * - A second termination signal while the first is still being
- *   handled is logged and ignored, unless `forceExitOnSecondSignal`
- *   is on, in which case `target.exit(forceExitCode)` is called.
+ *   handled exits with `forceExitCode` when `forceExitOnSecondSignal`
+ *   is on (the default), and is logged and ignored otherwise.
+ * - An uncaught exception or unhandled rejection runs the fatal
+ *   handler and then exits with code 1, unless `exitOnFatalError` is
+ *   off; `fatalExitTimeout` bounds a shutdown that hangs.
  * - `process.exit` is never called otherwise.
  */
 export class RuntimeSignalManager {
@@ -91,11 +95,11 @@ export class RuntimeSignalManager {
                 };
             case "uncaughtException":
                 return ((error) => {
-                    this.run(() => this._handlers?.onUncaughtException(error), "uncaughtException");
+                    this.runFatal(() => this._handlers?.onUncaughtException(error), "uncaughtException");
                 });
             case "unhandledRejection":
                 return ((reason) => {
-                    this.run(() => this._handlers?.onUnhandledRejection(reason), "unhandledRejection");
+                    this.runFatal(() => this._handlers?.onUnhandledRejection(reason), "unhandledRejection");
                 });
             default:
                 return () => { };
@@ -118,6 +122,13 @@ export class RuntimeSignalManager {
         });
         this.run(() => this._handlers?.onSignal(signal), signal);
     }
+    runFatal(handler, event) {
+        runFatalHandler(handler, this._target, {
+            exitOnFatalError: this._signals.exitOnFatalError ?? true,
+            fatalExitTimeout: this._signals.fatalExitTimeout ?? DEFAULT_FATAL_EXIT_TIMEOUT,
+            exitCode: 1,
+        }, this._logger, event);
+    }
     run(handler, event) {
         try {
             const result = handler();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Application lifecycle management, execution context propagation, and runtime orchestration for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,10 +55,14 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "publishConfig": {
     "access": "public"
   },