@zudojs/runtime 1.3.0 → 1.3.1

package/README.md

@@ -86,6 +86,36 @@ to reject; if it fails, the runtime logs a `RuntimeSignalError` (with the
 failure as `cause`) as the `error` field of its "Shutdown handler
 failed." entry.
 
+## Signals and exit codes
+
+With `handleSignals: true`, a `SIGTERM` or `SIGINT` runs a graceful
+`stop()`, and the runtime holds the process open until that shutdown has
+finished — every `onShutdown` and `onDestroy` hook runs, even when nothing
+else is keeping the event loop alive or a hook closes the last open socket
+before its async work is done. (Node's signal listeners do not keep the
+process alive by themselves; before this was fixed, a process with nothing
+else pending exited with code 0 mid-shutdown, still `running` or
+`stopping`.)
+
+When the shutdown is over the runtime lets the process exit on its own
+rather than calling `process.exit()`, so your own `SIGTERM` listeners and
+pending writes still finish:
+
+- clean shutdown: the exit code is left alone (0 unless you set one);
+- failed shutdown — `stop()` rejected (including an `onShutdown` that
+  outlives `shutdownTimeout`, which leaves the runtime `failed`), or a
+  module's hook failed (`status.shutdownFailures` is non-empty):
+  `process.exitCode` is set to `1` and the failure is logged as a
+  `RuntimeSignalError`. A failed stop publishes `runtime.failed`
+  (`phase: "stop"`) once;
+- fatal error (`exitOnFatalError`): `process.exit(1)` once shutdown ends;
+- second `SIGTERM`/`SIGINT` during shutdown (`forceExitOnSecondSignal`):
+  `process.exit(1)` at once.
+
+If something outside the runtime still holds a handle (a server you did not
+close in a module), the process stays up after the runtime has stopped, as
+it would without the runtime.
+
 ```typescript
 import { RuntimeStartError } from "@zudojs/runtime";
 

package/dist/runtime/runtime.core.d.ts

@@ -153,6 +153,10 @@ export declare class DefaultRuntime implements Runtime {
     private performStop;
     /**
      * Runs shutdown in response to a termination signal.
+     *
+     * Rejects when the stop failed or a module failed to shut down, so the
+     * signal handler logs a `RuntimeSignalError` and sets a non-zero exit
+     * code. Swallowing the failure here let a broken shutdown exit with 0.
      */
     private handleShutdownSignal;
     /**

package/dist/runtime/runtime.core.js

@@ -10,7 +10,7 @@ import { ReadinessTracker } from "../readiness/index.js";
 import { computeRuntimeHealth } from "../health/index.js";
 import { createRuntimeEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { createEvent } from "@zudojs/events";
-import { RuntimeRollbackError, RuntimeStateError, toRuntimeError, } from "../runtimeError/index.js";
+import { RuntimeRollbackError, RuntimeStartError, RuntimeStateError, RuntimeStopError, toRuntimeError, } from "../runtimeError/index.js";
 /**
  * Default runtime implementation.
  */
@@ -287,7 +287,11 @@ export class DefaultRuntime {
             this.logger.error("Runtime failed to start.", {
                 errorMessage: runtimeError.message,
             });
-            if (this.options.emitEvents) {
+            // A module failure was already published by executeStartup, with the
+            // failing module and phase; publishing it again here reported one
+            // failure twice. A timeout or other error is published here.
+            const alreadyPublished = error instanceof RuntimeStartError && error.failedModuleId !== undefined;
+            if (this.options.emitEvents && !alreadyPublished) {
                 this.emitEvent("runtime.failed", createFailureEventPayload(this.options.runtimeId, "failed", runtimeError, "startup"));
             }
             let rollbackError;
@@ -359,8 +363,13 @@ export class DefaultRuntime {
         if (this.options.emitEvents) {
             this.emitEvent("runtime.stopping");
         }
+        // `executeShutdown` publishes `runtime.failed` itself when it rejects,
+        // so the catch below only publishes for a failure raised after it.
+        // Publishing on both paths delivered every failed stop twice.
+        let shutdownSettled = false;
         try {
             const result = await executeShutdown(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.shutdownTimeout, this.options.emitEvents);
+            shutdownSettled = true;
             const containerFailure = await this.releaseContainer();
             this._shutdownFailures =
                 containerFailure === undefined
@@ -392,7 +401,7 @@ export class DefaultRuntime {
             this.logger.error("Runtime failed to stop.", {
                 errorMessage: runtimeError.message,
             });
-            if (this.options.emitEvents) {
+            if (this.options.emitEvents && shutdownSettled) {
                 this.emitEvent("runtime.failed", createFailureEventPayload(this.options.runtimeId, "failed", runtimeError, "stop"));
             }
             this.transitionTo("failed");
@@ -407,14 +416,22 @@ export class DefaultRuntime {
     }
     /**
      * Runs shutdown in response to a termination signal.
+     *
+     * Rejects when the stop failed or a module failed to shut down, so the
+     * signal handler logs a `RuntimeSignalError` and sets a non-zero exit
+     * code. Swallowing the failure here let a broken shutdown exit with 0.
      */
     async handleShutdownSignal() {
-        try {
-            await this.stop();
-        }
-        catch (error) {
-            this.logger.error("Shutdown failed.", {
-                errorMessage: error instanceof Error ? error.message : String(error),
+        await this.stop();
+        const failures = this._shutdownFailures;
+        if (failures.length > 0) {
+            throw new RuntimeStopError(`Runtime stopped with ${failures.length} module failure(s): ` +
+                failures.map((failure) => failure.moduleId).join(", ") +
+                ".", {
+                phase: "shutdown",
+                cause: failures.length === 1
+                    ? failures[0].error
+                    : new AggregateError(failures.map((failure) => failure.error)),
             });
         }
     }

package/dist/runtimeEvents/runtimeEvents.type.d.ts

@@ -3,9 +3,10 @@ import type { RuntimeFailureState, RuntimeState } from "../runtimeState/runtimeS
  * Runtime lifecycle events.
  *
  * These events are emitted through the EventBus when
- * the runtime transitions through its lifecycle.
+ * the runtime transitions through its lifecycle. Derived from
+ * {@link RuntimeEventMap}, so every event with a payload type is named here.
  */
-export type RuntimeEventType = "runtime.initializing" | "runtime.running" | "runtime.stopping" | "runtime.stopped" | "runtime.failed" | "runtime.module.initializing" | "runtime.module.initialized" | "runtime.module.starting" | "runtime.module.started" | "runtime.module.stopping" | "runtime.module.stopped" | "runtime.module.failed" | "runtime.shutdown.drain" | "runtime.shutdown.complete" | "runtime.health.changed" | "runtime.readiness.changed";
+export type RuntimeEventType = keyof RuntimeEventMap;
 /**
  * Base payload for all runtime events.
  */
@@ -60,7 +61,7 @@ export interface RuntimeReadinessEventPayload extends RuntimeEventPayload {
 /**
  * Event types carrying a {@link RuntimeModuleEventPayload}.
  */
-export type RuntimeModuleEventType = "runtime.module.initializing" | "runtime.module.initialized" | "runtime.module.starting" | "runtime.module.started" | "runtime.module.stopping" | "runtime.module.stopped" | "runtime.module.failed";
+export type RuntimeModuleEventType = Extract<RuntimeEventType, `runtime.module.${string}`>;
 /**
  * Maps event types to their payload types.
  *

package/dist/signalHandler/signalHandler.core.d.ts

@@ -28,6 +28,12 @@ export interface SignalHandlerOptions {
     readonly fatalExitTimeout?: number;
     /** Exit hook, injected for testing. Defaults to `process.exit`. */
     readonly exit?: (code: number) => void;
+    /**
+     * Exit-code hook, injected for testing. Defaults to setting
+     * `process.exitCode`. Called with `1` when a signal-triggered shutdown
+     * fails; a clean shutdown leaves the exit code alone.
+     */
+    readonly setExitCode?: (code: number) => void;
 }
 /**
  * Signal handler for process lifecycle events.
@@ -39,6 +45,7 @@ export declare class SignalHandler {
     private isShuttingDown;
     private registered;
     private forcedExitTimer;
+    private flushedPendingSignals;
     constructor(logger: Logger, options: SignalHandlerOptions);
     /**
      * Registers signal handlers.
@@ -60,6 +67,11 @@ export declare class SignalHandler {
     get shuttingDown(): boolean;
     private handleTermination;
     private handleInterruption;
+    /**
+     * Gives a signal delivered just before the loop drained one turn to be
+     * dispatched, once per registration so an idle process still exits.
+     */
+    private handleBeforeExit;
     /**
      * Handles uncaught exceptions.
      *
@@ -77,6 +89,9 @@ export declare class SignalHandler {
      *
      * A second termination signal exits immediately: an operator pressing
      * Ctrl-C again on a stuck shutdown is asking for exactly that.
+     *
+     * The event loop is held open until the shutdown settles, and a failed
+     * shutdown sets a non-zero exit code.
      */
     private initiateShutdown;
     private exit;

package/dist/signalHandler/signalHandler.core.js

@@ -1,4 +1,5 @@
 import { RuntimeSignalError } from "../runtimeError/runtimeError.base.js";
+import { flushPendingSignals, holdEventLoop, setProcessExitCode, } from "./signalHandler.keepAlive.js";
 /** Default grace period for a fatal-error shutdown. */
 const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
 /**
@@ -11,6 +12,7 @@ export class SignalHandler {
     isShuttingDown = false;
     registered = false;
     forcedExitTimer = null;
+    flushedPendingSignals = false;
     constructor(logger, options) {
         this.logger = logger;
         this.options = options;
@@ -29,8 +31,10 @@ export class SignalHandler {
         this.registered = true;
         this.isShuttingDown = false;
         if (this.options.handleSignals) {
+            this.flushedPendingSignals = false;
             process.on("SIGTERM", this.handleTermination);
             process.on("SIGINT", this.handleInterruption);
+            process.on("beforeExit", this.handleBeforeExit);
         }
         if (this.options.handleFatalErrors) {
             process.on("uncaughtException", this.handleUncaughtException);
@@ -55,6 +59,7 @@ export class SignalHandler {
         if (this.options.handleSignals) {
             process.off("SIGTERM", this.handleTermination);
             process.off("SIGINT", this.handleInterruption);
+            process.off("beforeExit", this.handleBeforeExit);
         }
         if (this.options.handleFatalErrors) {
             process.off("uncaughtException", this.handleUncaughtException);
@@ -78,6 +83,16 @@ export class SignalHandler {
         this.logger.info("Received SIGINT signal.");
         this.initiateShutdown("SIGINT");
     };
+    /**
+     * Gives a signal delivered just before the loop drained one turn to be
+     * dispatched, once per registration so an idle process still exits.
+     */
+    handleBeforeExit = () => {
+        if (this.flushedPendingSignals || this.isShuttingDown)
+            return;
+        this.flushedPendingSignals = true;
+        flushPendingSignals();
+    };
     /**
      * Handles uncaught exceptions.
      *
@@ -132,6 +147,9 @@ export class SignalHandler {
      *
      * A second termination signal exits immediately: an operator pressing
      * Ctrl-C again on a stuck shutdown is asking for exactly that.
+     *
+     * The event loop is held open until the shutdown settles, and a failed
+     * shutdown sets a non-zero exit code.
      */
     initiateShutdown(source) {
         if (this.isShuttingDown) {
@@ -145,14 +163,19 @@ export class SignalHandler {
             return;
         }
         this.isShuttingDown = true;
-        if (this.shutdownHandler) {
-            return Promise.resolve(this.shutdownHandler()).catch((error) => {
+        const handler = this.shutdownHandler;
+        if (handler) {
+            const release = holdEventLoop();
+            return new Promise((resolve) => resolve(handler()))
+                .catch((error) => {
                 const signalError = new RuntimeSignalError(source, { cause: error });
                 this.logger.error("Shutdown handler failed.", {
                     errorMessage: signalError.message,
                     error: signalError,
                 });
-            });
+                (this.options.setExitCode ?? setProcessExitCode)(1);
+            })
+                .finally(release);
         }
     }
     exit(code) {

package/dist/signalHandler/signalHandler.keepAlive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Keeping the process alive while a signal-triggered shutdown runs.
+ *
+ * Node's signal listeners do not hold the event loop open. A SIGTERM
+ * handled while nothing else was keeping the loop alive — or whose
+ * shutdown closed the last open handle before an `onShutdown` hook had
+ * finished — let the process exit mid-shutdown with code 0, the runtime
+ * still `running` or `stopping`, and the remaining hooks never run.
+ *
+ * @module signalHandler/signalHandler.keepAlive
+ */
+/**
+ * Holds the event loop open until the returned release function is called.
+ *
+ * The handle is a ref'd interval that does nothing, so the process stays
+ * up exactly as long as the shutdown it guards.
+ */
+export declare function holdEventLoop(): () => void;
+/**
+ * Runs one more event-loop turn so a signal that was already delivered,
+ * but not yet dispatched, reaches its listener.
+ *
+ * A process that signals itself (`process.kill(process.pid, "SIGTERM")`)
+ * with nothing else keeping the loop alive otherwise exits without ever
+ * polling for the signal, so the listener never runs.
+ */
+export declare function flushPendingSignals(): void;
+/** Sets the exit code the process ends with once the loop drains. */
+export declare function setProcessExitCode(code: number): void;
+//# sourceMappingURL=signalHandler.keepAlive.d.ts.map

package/dist/signalHandler/signalHandler.keepAlive.js

@@ -0,0 +1,45 @@
+/**
+ * Keeping the process alive while a signal-triggered shutdown runs.
+ *
+ * Node's signal listeners do not hold the event loop open. A SIGTERM
+ * handled while nothing else was keeping the loop alive — or whose
+ * shutdown closed the last open handle before an `onShutdown` hook had
+ * finished — let the process exit mid-shutdown with code 0, the runtime
+ * still `running` or `stopping`, and the remaining hooks never run.
+ *
+ * @module signalHandler/signalHandler.keepAlive
+ */
+/** Longest delay a Node timer accepts; the timer never fires in practice. */
+const KEEP_ALIVE_INTERVAL = 2_147_483_647;
+/**
+ * Holds the event loop open until the returned release function is called.
+ *
+ * The handle is a ref'd interval that does nothing, so the process stays
+ * up exactly as long as the shutdown it guards.
+ */
+export function holdEventLoop() {
+    const handle = setInterval(() => undefined, KEEP_ALIVE_INTERVAL);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(handle);
+    };
+}
+/**
+ * Runs one more event-loop turn so a signal that was already delivered,
+ * but not yet dispatched, reaches its listener.
+ *
+ * A process that signals itself (`process.kill(process.pid, "SIGTERM")`)
+ * with nothing else keeping the loop alive otherwise exits without ever
+ * polling for the signal, so the listener never runs.
+ */
+export function flushPendingSignals() {
+    setImmediate(() => undefined);
+}
+/** Sets the exit code the process ends with once the loop drains. */
+export function setProcessExitCode(code) {
+    process.exitCode = code;
+}
+//# sourceMappingURL=signalHandler.keepAlive.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/runtime",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,11 +28,11 @@
   },
   "dependencies": {
     "@zudojs/constants": "1.1.2",
-    "@zudojs/container": "1.2.0",
+    "@zudojs/container": "1.2.1",
     "@zudojs/core": "1.2.2",
     "@zudojs/errors": "1.3.0",
-    "@zudojs/events": "1.3.0",
-    "@zudojs/logger": "1.4.0"
+    "@zudojs/events": "1.3.1",
+    "@zudojs/logger": "1.4.1"
   },
   "license": "MIT",
   "author": {