@zudojs/runtime 0.1.0 → 1.1.0

package/dist/signalHandler/signalHandler.core.js

@@ -1,90 +1,160 @@
+/** Default grace period for a fatal-error shutdown. */
+const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
 /**
  * Signal handler for process lifecycle events.
  */
 export class SignalHandler {
     logger;
-    handleSignals;
-    handleFatalErrors;
+    options;
     shutdownHandler = null;
     isShuttingDown = false;
+    registered = false;
+    forcedExitTimer = null;
     constructor(logger, options) {
         this.logger = logger;
-        this.handleSignals = options.handleSignals;
-        this.handleFatalErrors = options.handleFatalErrors;
+        this.options = options;
     }
     /**
      * Registers signal handlers.
+     *
+     * Registering twice is a no-op rather than a second set of listeners,
+     * so a stop/start cycle cannot accumulate handlers.
      */
     register(shutdownHandler) {
         this.shutdownHandler = shutdownHandler;
-        if (this.handleSignals) {
+        if (this.registered) {
+            return;
+        }
+        this.registered = true;
+        this.isShuttingDown = false;
+        if (this.options.handleSignals) {
             process.on("SIGTERM", this.handleTermination);
             process.on("SIGINT", this.handleInterruption);
         }
-        if (this.handleFatalErrors) {
+        if (this.options.handleFatalErrors) {
             process.on("uncaughtException", this.handleUncaughtException);
             process.on("unhandledRejection", this.handleUnhandledRejection);
         }
     }
     /**
      * Removes all signal handlers.
+     *
+     * Safe to call when nothing is registered, so it can run on both the
+     * success and failure paths of a shutdown.
      */
     unregister() {
-        if (this.handleSignals) {
+        if (this.forcedExitTimer) {
+            clearTimeout(this.forcedExitTimer);
+            this.forcedExitTimer = null;
+        }
+        if (!this.registered) {
+            this.shutdownHandler = null;
+            return;
+        }
+        if (this.options.handleSignals) {
             process.off("SIGTERM", this.handleTermination);
             process.off("SIGINT", this.handleInterruption);
         }
-        if (this.handleFatalErrors) {
+        if (this.options.handleFatalErrors) {
             process.off("uncaughtException", this.handleUncaughtException);
             process.off("unhandledRejection", this.handleUnhandledRejection);
         }
+        this.registered = false;
+        this.isShuttingDown = false;
         this.shutdownHandler = null;
     }
     /**
-     * Handles SIGTERM signal.
+     * Whether a shutdown has been initiated by a signal.
      */
+    get shuttingDown() {
+        return this.isShuttingDown;
+    }
     handleTermination = () => {
         this.logger.info("Received SIGTERM signal.");
-        this.initiateShutdown();
+        this.initiateShutdown("SIGTERM");
     };
-    /**
-     * Handles SIGINT signal.
-     */
     handleInterruption = () => {
         this.logger.info("Received SIGINT signal.");
-        this.initiateShutdown();
+        this.initiateShutdown("SIGINT");
     };
     /**
      * Handles uncaught exceptions.
+     *
+     * The process state is no longer trustworthy after one, so this shuts
+     * down and then exits non-zero rather than continuing to serve.
      */
     handleUncaughtException = (error) => {
-        this.logger.error("Uncaught exception.", { errorMessage: error.message });
-        if (this.handleFatalErrors) {
-            this.initiateShutdown();
-        }
+        this.logger.error("Uncaught exception.", {
+            errorMessage: error.message,
+            stack: error.stack,
+        });
+        this.initiateFatalShutdown();
     };
-    /**
-     * Handles unhandled promise rejections.
-     */
     handleUnhandledRejection = (reason) => {
         const message = reason instanceof Error ? reason.message : String(reason);
-        this.logger.error("Unhandled rejection.", { reason: message });
-        if (this.handleFatalErrors) {
-            this.initiateShutdown();
-        }
+        this.logger.error("Unhandled rejection.", {
+            reason: message,
+            ...(reason instanceof Error && reason.stack
+                ? { stack: reason.stack }
+                : {}),
+        });
+        this.initiateFatalShutdown();
     };
+    /**
+     * Shuts down after a fatal error and exits non-zero.
+     */
+    initiateFatalShutdown() {
+        if (this.options.exitOnFatalError === false) {
+            this.initiateShutdown("fatal");
+            return;
+        }
+        const timeout = this.options.fatalExitTimeout ?? DEFAULT_FATAL_EXIT_TIMEOUT;
+        if (!this.isShuttingDown) {
+            // Exit even if the shutdown itself hangs — a process that is
+            // already in an undefined state must not linger indefinitely.
+            this.forcedExitTimer = setTimeout(() => {
+                this.logger.error("Fatal shutdown timed out; exiting.");
+                this.exit(1);
+            }, timeout);
+            this.forcedExitTimer.unref?.();
+        }
+        void Promise.resolve(this.initiateShutdown("fatal")).finally(() => {
+            if (this.forcedExitTimer) {
+                clearTimeout(this.forcedExitTimer);
+                this.forcedExitTimer = null;
+            }
+            this.exit(1);
+        });
+    }
     /**
      * Initiates graceful shutdown.
+     *
+     * A second termination signal exits immediately: an operator pressing
+     * Ctrl-C again on a stuck shutdown is asking for exactly that.
      */
-    initiateShutdown() {
+    initiateShutdown(source) {
         if (this.isShuttingDown) {
+            if ((this.options.forceExitOnSecondSignal ?? true) &&
+                source !== "fatal") {
+                this.logger.warn(`Received a second ${source} while shutting down; exiting immediately.`);
+                this.exit(1);
+                return;
+            }
             this.logger.warn("Shutdown already in progress, ignoring signal.");
             return;
         }
         this.isShuttingDown = true;
         if (this.shutdownHandler) {
-            this.shutdownHandler();
+            return Promise.resolve(this.shutdownHandler()).catch((error) => {
+                this.logger.error("Shutdown handler failed.", {
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
+            });
         }
     }
+    exit(code) {
+        const exit = this.options.exit ?? ((value) => process.exit(value));
+        exit(code);
+    }
 }
 //# sourceMappingURL=signalHandler.core.js.map

package/dist/startup/startup.core.d.ts

@@ -1,12 +1,13 @@
 import type { Logger } from "@zudojs/logger";
 import type { EventBus } from "@zudojs/events";
 import { LifecycleManager } from "../lifecycle/index.js";
+import type { LifecycleFailure } from "../lifecycle/lifecycle.type.js";
 /**
  * Executes the startup sequence.
  */
-export declare function executeStartup(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, emitEvents: boolean): Promise<void>;
+export declare function executeStartup(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, emitEvents: boolean, startupTimeout?: number): Promise<void>;
 /**
  * Rolls back a failed startup.
  */
-export declare function rollbackStartup(lifecycle: LifecycleManager, logger: Logger): Promise<void>;
+export declare function rollbackStartup(lifecycle: LifecycleManager, logger: Logger): Promise<readonly LifecycleFailure[]>;
 //# sourceMappingURL=startup.core.d.ts.map

package/dist/startup/startup.core.js

@@ -1,35 +1,56 @@
 import { createEvent } from "@zudojs/events";
+import { createFailureEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { LifecycleManager } from "../lifecycle/index.js";
-import { RuntimeStartError } from "../runtimeError/index.js";
+import { RuntimeStartError, RuntimeTimeoutError, } from "../runtimeError/index.js";
+/** Largest delay a timer can represent. */
+const MAX_TIMER_DELAY = 2_147_483_647;
 /**
- * Executes the startup sequence.
+ * Runs the startup sequence under a bound.
+ *
+ * `startupTimeout` was validated as positive and then never enforced, so
+ * a module whose `onInitialize` never settles hung the boot forever with
+ * no diagnostic. The timer is cleared whichever side wins.
  */
-export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
-    // Initialize modules
-    if (emitEvents && eventBus) {
-        eventBus.publish(createEvent({
-            type: "runtime.module.initializing",
-            payload: {
-                runtimeId,
-                timestamp: new Date(),
-                state: "initializing",
-            },
-        }));
+async function withStartupTimeout(operation, timeoutMs) {
+    if (timeoutMs <= 0) {
+        return operation;
+    }
+    // The startup promise keeps running if the timeout wins; attach a
+    // handler now so its eventual rejection is never unhandled.
+    operation.catch(() => { });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new RuntimeTimeoutError("startup", timeoutMs)), Math.min(timeoutMs, MAX_TIMER_DELAY));
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([operation, timeout]);
     }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Executes the startup sequence.
+ */
+export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, startupTimeout = 0) {
+    return withStartupTimeout(runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents), startupTimeout);
+}
+/**
+ * Runs the startup sequence.
+ */
+async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
+    // Per-module `runtime.module.*` events are emitted by the lifecycle
+    // manager, which is the only layer that knows which module is running.
     const initResult = await lifecycle.initialize();
     if (initResult.failed.length > 0) {
         const failure = initResult.failed[0];
         if (emitEvents && eventBus) {
-            eventBus.publish(createEvent({
-                type: "runtime.module.failed",
-                payload: {
-                    runtimeId,
-                    state: "initialization_failed",
-                    timestamp: new Date(),
-                    error: failure.error,
-                    phase: "initialize",
-                    failedModuleId: failure.moduleId,
-                },
+            publishRuntimeEvent(eventBus, logger, createEvent({
+                type: "runtime.failed",
+                payload: createFailureEventPayload(runtimeId, "initialization_failed", failure.error, "initialize", failure.moduleId),
             }));
         }
         throw new RuntimeStartError(`Module "${failure.moduleId}" failed during initialization.`, {
@@ -42,31 +63,13 @@ export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emi
         modules: initResult.succeeded,
         durationMs: initResult.durationMs,
     });
-    // Start modules
-    if (emitEvents && eventBus) {
-        eventBus.publish(createEvent({
-            type: "runtime.module.starting",
-            payload: {
-                runtimeId,
-                timestamp: new Date(),
-                state: "starting",
-            },
-        }));
-    }
     const startResult = await lifecycle.start();
     if (startResult.failed.length > 0) {
         const failure = startResult.failed[0];
         if (emitEvents && eventBus) {
-            eventBus.publish(createEvent({
-                type: "runtime.module.failed",
-                payload: {
-                    runtimeId,
-                    state: "startup_failed",
-                    timestamp: new Date(),
-                    error: failure.error,
-                    phase: "start",
-                    failedModuleId: failure.moduleId,
-                },
+            publishRuntimeEvent(eventBus, logger, createEvent({
+                type: "runtime.failed",
+                payload: createFailureEventPayload(runtimeId, "startup_failed", failure.error, "start", failure.moduleId),
             }));
         }
         throw new RuntimeStartError(`Module "${failure.moduleId}" failed during startup.`, {
@@ -85,7 +88,10 @@ export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emi
  */
 export async function rollbackStartup(lifecycle, logger) {
     logger.info("Rolling back module startup.");
-    await lifecycle.rollback();
-    logger.info("Module rollback complete.");
+    const failures = await lifecycle.rollback();
+    logger.info("Module rollback complete.", {
+        failedModules: failures.map((failure) => failure.moduleId),
+    });
+    return failures;
 }
 //# sourceMappingURL=startup.core.js.map

package/dist/testRuntime/index.d.ts

@@ -1,5 +1,10 @@
 /**
- * @zudojs/runtime — Test Runtime Barrel
+ * @zudojs/runtime/testing
+ *
+ * Testing helpers. Exposed through the "@zudojs/runtime/testing" subpath
+ * rather than the package root, so a test-only module never sits on the
+ * main entry point.
  */
+export type { MockModule } from "./testRuntime.core.js";
 export { createTestRuntime, createMockModule, withTestRuntime, } from "./testRuntime.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testRuntime/index.js

@@ -1,5 +1,9 @@
 /**
- * @zudojs/runtime — Test Runtime Barrel
+ * @zudojs/runtime/testing
+ *
+ * Testing helpers. Exposed through the "@zudojs/runtime/testing" subpath
+ * rather than the package root, so a test-only module never sits on the
+ * main entry point.
  */
 export { createTestRuntime, createMockModule, withTestRuntime, } from "./testRuntime.core.js";
 //# sourceMappingURL=index.js.map

package/dist/testRuntime/testRuntime.core.d.ts

@@ -15,14 +15,33 @@ import type { RuntimeOptions } from "../runtimeOptions/runtimeOptions.type.js";
  * @returns A runtime instance ready for testing.
  */
 export declare function createTestRuntime(modules?: Module[], options?: Partial<RuntimeOptions>): DefaultRuntime;
+/**
+ * A module whose lifecycle hooks record their calls.
+ */
+export interface MockModule extends Module {
+    /** How many times each hook ran, in call order. */
+    readonly calls: {
+        readonly onInitialize: number;
+        readonly onReady: number;
+        readonly onShutdown: number;
+        readonly onDestroy: number;
+    };
+    /** Hook names in the order they were invoked. */
+    readonly callOrder: readonly string[];
+}
 /**
  * Creates a mock module for testing.
  *
+ * The hooks are plain counting functions rather than `vi.fn()`: this
+ * module ships in the package, so it must not import a test runner —
+ * `vitest` is a dev dependency consumers do not install, and `require`
+ * is not available in an ESM package at all.
+ *
  * @param id - Module identifier.
  * @param dependencies - Module dependencies.
- * @returns A mock module with vi.fn() hooks.
+ * @returns A mock module that records its lifecycle calls.
  */
-export declare function createMockModule(id: string, dependencies?: string[]): Module;
+export declare function createMockModule(id: string, dependencies?: string[]): MockModule;
 /**
  * Starts a test runtime, runs a callback, and stops it.
  *

package/dist/testRuntime/testRuntime.core.js

@@ -45,20 +45,37 @@ export function createTestRuntime(modules = [], options = {}) {
 /**
  * Creates a mock module for testing.
  *
+ * The hooks are plain counting functions rather than `vi.fn()`: this
+ * module ships in the package, so it must not import a test runner —
+ * `vitest` is a dev dependency consumers do not install, and `require`
+ * is not available in an ESM package at all.
+ *
  * @param id - Module identifier.
  * @param dependencies - Module dependencies.
- * @returns A mock module with vi.fn() hooks.
+ * @returns A mock module that records its lifecycle calls.
  */
 export function createMockModule(id, dependencies = []) {
-    const { vi } = require("vitest");
+    const calls = {
+        onInitialize: 0,
+        onReady: 0,
+        onShutdown: 0,
+        onDestroy: 0,
+    };
+    const callOrder = [];
+    const record = (hook) => async () => {
+        calls[hook] += 1;
+        callOrder.push(hook);
+    };
     return {
         id,
         name: `Module ${id}`,
         dependencies,
-        onInitialize: vi.fn().mockResolvedValue(undefined),
-        onReady: vi.fn().mockResolvedValue(undefined),
-        onShutdown: vi.fn().mockResolvedValue(undefined),
-        onDestroy: vi.fn().mockResolvedValue(undefined),
+        calls,
+        callOrder,
+        onInitialize: record("onInitialize"),
+        onReady: record("onReady"),
+        onShutdown: record("onShutdown"),
+        onDestroy: record("onDestroy"),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/runtime",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,36 +10,36 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
+    "./testing": {
+      "types": "./dist/testRuntime/index.d.ts",
+      "import": "./dist/testRuntime/index.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "tsc -p tsconfig.json --clean"
-  },
   "devDependencies": {
     "@types/node": "^26.4.1",
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/container": "0.1.0",
-    "@zudojs/config": "0.1.0",
-    "@zudojs/logger": "0.1.0",
-    "@zudojs/events": "0.1.0",
-    "@zudojs/core": "0.1.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/container": "1.1.0",
+    "@zudojs/config": "1.0.1",
+    "@zudojs/logger": "1.1.0",
+    "@zudojs/events": "1.0.1",
+    "@zudojs/core": "1.1.0"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -54,8 +54,19 @@
     "services"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/runtime"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
   }
-}
+}