@zudojs/runtime 0.1.0 → 1.1.0

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

@@ -1,10 +1,11 @@
+import type { RuntimeFailureState, RuntimeState } from "../runtimeState/runtimeState.type.js";
 /**
  * Runtime lifecycle events.
  *
  * These events are emitted through the EventBus when
  * the runtime transitions through its lifecycle.
  */
-export type RuntimeEventType = "runtime.created" | "runtime.initializing" | "runtime.initialized" | "runtime.starting" | "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 = "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";
 /**
  * Base payload for all runtime events.
  */
@@ -26,6 +27,14 @@ export interface RuntimeModuleEventPayload extends RuntimeEventPayload {
  * Payload for runtime failure events.
  */
 export interface RuntimeFailureEventPayload extends RuntimeEventPayload {
+    /**
+     * The state the runtime was in when it failed.
+     *
+     * Narrower than the base payload's `state`: this is where
+     * {@link RuntimeFailureState} is used, naming which phase failed rather
+     * than leaving the reader to parse a free-form string.
+     */
+    readonly state: RuntimeState | RuntimeFailureState;
     readonly error: Error;
     readonly phase: string;
     readonly failedModuleId?: string;
@@ -48,14 +57,20 @@ export interface RuntimeReadinessEventPayload extends RuntimeEventPayload {
     readonly ready: boolean;
     readonly reason?: string;
 }
+/**
+ * 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";
 /**
  * Maps event types to their payload types.
+ *
+ * Every entry here is emitted by the runtime. Entries for events nothing
+ * ever published (`runtime.created`, `runtime.initialized`,
+ * `runtime.starting`) were removed rather than left as names a consumer
+ * could subscribe to and never hear from.
  */
 export interface RuntimeEventMap {
-    "runtime.created": RuntimeEventPayload;
     "runtime.initializing": RuntimeEventPayload;
-    "runtime.initialized": RuntimeEventPayload;
-    "runtime.starting": RuntimeEventPayload;
     "runtime.running": RuntimeEventPayload;
     "runtime.stopping": RuntimeEventPayload;
     "runtime.stopped": RuntimeEventPayload;

package/dist/runtimeOptions/runtimeOptions.core.d.ts

@@ -1,6 +1,11 @@
 import type { ResolvedRuntimeOptions } from "./runtimeOptions.type.js";
 /**
  * Resolves runtime options with defaults applied.
+ *
+ * `runtimeId` is documented as "auto-generated if not provided", but until
+ * this generated one nothing did: `DEFAULT_RUNTIME_OPTIONS` has no entry
+ * for it, so an omitted id reached every event payload, log line and
+ * `runtime.context.runtimeId` as `undefined`.
  */
 export declare function resolveRuntimeOptions(options: ResolvedRuntimeOptions): ResolvedRuntimeOptions;
 /**

package/dist/runtimeOptions/runtimeOptions.core.js

@@ -2,11 +2,21 @@ import { DEFAULT_RUNTIME_OPTIONS } from "./runtimeOptions.type.js";
 import { createRuntimeId } from "../runtimeContext/runtimeContext.factory.js";
 /**
  * Resolves runtime options with defaults applied.
+ *
+ * `runtimeId` is documented as "auto-generated if not provided", but until
+ * this generated one nothing did: `DEFAULT_RUNTIME_OPTIONS` has no entry
+ * for it, so an omitted id reached every event payload, log line and
+ * `runtime.context.runtimeId` as `undefined`.
  */
 export function resolveRuntimeOptions(options) {
+    // Spreading `options` wholesale lets an explicitly-undefined key erase
+    // its default — a common footgun when callers build options with
+    // optional fields. Only defined values override.
+    const provided = Object.fromEntries(Object.entries(options ?? {}).filter(([, value]) => value !== undefined));
     return Object.freeze({
         ...DEFAULT_RUNTIME_OPTIONS,
-        ...options,
+        runtimeId: createRuntimeId(),
+        ...provided,
     });
 }
 /**
@@ -25,6 +35,9 @@ export function validateRuntimeOptions(options) {
     if (options.startupTimeout <= 0) {
         throw new Error("Startup timeout must be positive.");
     }
+    if (options.readinessCheckTimeout < 0) {
+        throw new Error(`Readiness check timeout must be zero or positive, got ${options.readinessCheckTimeout}. Use 0 to run checks without a bound.`);
+    }
 }
 /**
  * Creates a runtime options object with all defaults applied.

package/dist/runtimeOptions/runtimeOptions.type.d.ts

@@ -52,10 +52,33 @@ export interface RuntimeOptions {
      */
     readonly trackReadiness?: boolean;
     /**
-     * Whether to enable health tracking.
+     * Whether health is derived from readiness checks.
+     *
+     * When `false`, `runtime.health` reports `unknown` and no
+     * `runtime.health.changed` events are emitted; readiness checks still
+     * run and `runtime.ready` is unaffected.
+     *
      * @default true
      */
     readonly trackHealth?: boolean;
+    /**
+     * How long a single readiness check may run before it is recorded as
+     * failed, in milliseconds. Set to `0` to remove the bound.
+     *
+     * @default 5000
+     */
+    readonly readinessCheckTimeout?: number;
+    /**
+     * Whether modules at the same dependency depth are initialized
+     * concurrently.
+     *
+     * Modules within a depth group do not depend on one another, so this is
+     * safe by construction — but it surfaces any ordering a module assumed
+     * without declaring, so it is opt-in.
+     *
+     * @default false
+     */
+    readonly parallelInitialization?: boolean;
     /**
      * Additional runtime metadata.
      */
@@ -76,6 +99,8 @@ export interface ResolvedRuntimeOptions {
     readonly emitEvents: boolean;
     readonly trackReadiness: boolean;
     readonly trackHealth: boolean;
+    readonly readinessCheckTimeout: number;
+    readonly parallelInitialization: boolean;
     readonly metadata: Readonly<Record<string, unknown>>;
 }
 /**
@@ -89,6 +114,9 @@ export declare const DEFAULT_RUNTIME_OPTIONS: Readonly<{
     readonly emitEvents: true;
     readonly trackReadiness: true;
     readonly trackHealth: true;
+    readonly readinessCheckTimeout: 5000;
+    readonly parallelInitialization: false;
     readonly applicationVersion: "0.1.0";
+    readonly metadata: Readonly<{}>;
 }>;
 //# sourceMappingURL=runtimeOptions.type.d.ts.map

package/dist/runtimeOptions/runtimeOptions.type.js

@@ -9,6 +9,12 @@ export const DEFAULT_RUNTIME_OPTIONS = Object.freeze({
     emitEvents: true,
     trackReadiness: true,
     trackHealth: true,
+    readinessCheckTimeout: 5_000,
+    parallelInitialization: false,
     applicationVersion: "0.1.0",
+    // `metadata` is required on ResolvedRuntimeOptions, so it needs a
+    // default; without one the resolved options claimed a value the
+    // runtime never had.
+    metadata: Object.freeze({}),
 });
 //# sourceMappingURL=runtimeOptions.type.js.map

package/dist/runtimeState/index.d.ts

@@ -2,5 +2,5 @@
  * Runtime state types and state machine.
  */
 export { RUNTIME_STATE_TRANSITIONS, TERMINAL_STATES, STARTABLE_STATES, STOPPABLE_STATES, canTransition, assertTransition, isTerminalState, canStart, canStop, isRunning, hasFailed, createStatus, } from "./runtimeState.core.js";
-export type { RuntimeState, RuntimeFailureState, RuntimeStateFull, RuntimeId, RuntimeStatus, RuntimeStateTransition, RuntimeStateTransitions, RuntimeHealthState, RuntimeHealth, RuntimeHealthCheck, } from "./runtimeState.type.js";
+export type { RuntimeState, RuntimeFailureState, RuntimeId, RuntimeStatus, RuntimeShutdownFailure, RuntimeHealthState, RuntimeHealth, RuntimeHealthCheck, } from "./runtimeState.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtimeState/runtimeState.core.d.ts

@@ -21,6 +21,10 @@ export declare const STOPPABLE_STATES: readonly RuntimeState[];
 export declare function canTransition(from: RuntimeState, to: RuntimeState): boolean;
 /**
  * Asserts that a state transition is valid.
+ *
+ * Throws {@link RuntimeStateError} rather than a bare `Error`: every other
+ * runtime failure is typed, and a caller that branches on the error type
+ * could not catch this one.
  */
 export declare function assertTransition(from: RuntimeState, to: RuntimeState): void;
 /**

package/dist/runtimeState/runtimeState.core.js

@@ -1,15 +1,20 @@
+import { RuntimeStateError } from "../runtimeError/runtimeError.base.js";
 /**
  * Defines valid runtime state transitions.
  */
 export const RUNTIME_STATE_TRANSITIONS = Object.freeze({
-    created: ["initializing", "failed"],
+    created: ["initializing", "stopped", "failed"],
     initializing: ["initialized", "running", "failed"],
     initialized: ["starting", "running", "failed"],
     starting: ["running", "failed"],
     running: ["stopping", "failed"],
     stopping: ["stopped", "failed"],
     stopped: [],
-    failed: [],
+    // A failed runtime must still be stoppable: startup rollback only
+    // reaches modules that were started, so the operator needs a way to
+    // release everything else. Without this the failure path — the one
+    // most in need of cleanup — is the one with none available.
+    failed: ["stopping", "stopped"],
 });
 /**
  * Terminal runtime states.
@@ -29,20 +34,28 @@ export const STARTABLE_STATES = Object.freeze([
  */
 export const STOPPABLE_STATES = Object.freeze([
     "running",
+    "failed",
 ]);
 /**
  * Checks whether a state transition is valid.
  */
 export function canTransition(from, to) {
     const allowed = RUNTIME_STATE_TRANSITIONS[from];
-    return allowed.includes(to);
+    return allowed?.includes(to) ?? false;
 }
 /**
  * Asserts that a state transition is valid.
+ *
+ * Throws {@link RuntimeStateError} rather than a bare `Error`: every other
+ * runtime failure is typed, and a caller that branches on the error type
+ * could not catch this one.
  */
 export function assertTransition(from, to) {
     if (!canTransition(from, to)) {
-        throw new Error(`Invalid runtime state transition from "${from}" to "${to}".`);
+        throw new RuntimeStateError(`Invalid runtime state transition from "${from}" to "${to}". ` +
+            `Valid transitions from "${from}" are: ${RUNTIME_STATE_TRANSITIONS[from].length > 0
+                ? RUNTIME_STATE_TRANSITIONS[from].map((s) => `"${s}"`).join(", ")
+                : "none — it is a terminal state"}.`);
     }
 }
 /**

package/dist/runtimeState/runtimeState.type.d.ts

@@ -11,10 +11,6 @@ export type RuntimeState = "created" | "initializing" | "initialized" | "startin
  * Failure-specific runtime states.
  */
 export type RuntimeFailureState = "initialization_failed" | "startup_failed" | "shutdown_failed";
-/**
- * All possible runtime states including failure variants.
- */
-export type RuntimeStateFull = RuntimeState | RuntimeFailureState;
 /**
  * Unique runtime identifier.
  */
@@ -30,22 +26,24 @@ export interface RuntimeStatus {
     readonly stoppedAt?: Date;
     readonly failedAt?: Date;
     readonly error?: RuntimeError;
+    /**
+     * Modules that failed to stop or destroy during the last shutdown.
+     *
+     * A non-empty list means the runtime reached `stopped` without fully
+     * releasing its resources — a state that would otherwise be
+     * indistinguishable from a clean shutdown.
+     */
+    readonly shutdownFailures?: readonly RuntimeShutdownFailure[];
 }
 /**
- * A record of a runtime state transition.
+ * A module that failed during shutdown.
  */
-export interface RuntimeStateTransition {
-    readonly from: RuntimeState;
-    readonly to: RuntimeState;
-    readonly timestamp: Date;
-    readonly reason?: string;
+export interface RuntimeShutdownFailure {
+    readonly moduleId: string;
+    readonly phase: string;
+    readonly error: Error;
+    readonly durationMs: number;
 }
-/**
- * Defines valid state transitions.
- */
-export type RuntimeStateTransitions = {
-    [K in RuntimeState]: readonly RuntimeState[];
-};
 /**
  * Runtime health state.
  */
@@ -66,6 +64,5 @@ export interface RuntimeHealthCheck {
     readonly healthy: boolean;
     readonly message?: string;
     readonly durationMs: number;
-    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 //# sourceMappingURL=runtimeState.type.d.ts.map

package/dist/shutdown/shutdown.core.d.ts

@@ -1,8 +1,27 @@
 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";
+/**
+ * Result of a shutdown attempt.
+ */
+export interface ShutdownResult {
+    /** Modules that failed to stop or destroy cleanly. */
+    readonly failures: readonly LifecycleFailure[];
+    /** Whether the shutdown was cut short by the timeout. */
+    readonly timedOut: boolean;
+}
 /**
  * Executes the shutdown sequence with timeout.
+ *
+ * The timeout timer is cleared as soon as the race settles: a timer left
+ * armed after a clean shutdown holds the event loop open for its full
+ * duration, which is why a stopped process could still take 30 seconds
+ * to exit.
+ *
+ * Module failures are surfaced rather than logged and forgotten — a
+ * deployment that failed to release its connections must not look
+ * identical to one that shut down cleanly.
  */
-export declare function executeShutdown(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, shutdownTimeout: number, emitEvents: boolean): Promise<void>;
+export declare function executeShutdown(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, shutdownTimeout: number, emitEvents: boolean): Promise<ShutdownResult>;
 //# sourceMappingURL=shutdown.core.d.ts.map

package/dist/shutdown/shutdown.core.js

@@ -1,70 +1,95 @@
 import { createEvent } from "@zudojs/events";
+import { createFailureEventPayload, createRuntimeEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { LifecycleManager } from "../lifecycle/index.js";
 import { RuntimeStopError, RuntimeTimeoutError, } from "../runtimeError/index.js";
+/** Largest delay a timer can represent. */
+const MAX_TIMER_DELAY = 2_147_483_647;
 /**
  * Executes the shutdown sequence with timeout.
+ *
+ * The timeout timer is cleared as soon as the race settles: a timer left
+ * armed after a clean shutdown holds the event loop open for its full
+ * duration, which is why a stopped process could still take 30 seconds
+ * to exit.
+ *
+ * Module failures are surfaced rather than logged and forgotten — a
+ * deployment that failed to release its connections must not look
+ * identical to one that shut down cleanly.
  */
 export async function executeShutdown(lifecycle, runtimeId, eventBus, logger, shutdownTimeout, emitEvents) {
     if (emitEvents && eventBus) {
-        eventBus.publish(createEvent({
+        publishRuntimeEvent(eventBus, logger, createEvent({
             type: "runtime.shutdown.drain",
-            payload: {
-                runtimeId,
-                timestamp: new Date(),
-                state: "stopping",
-            },
+            payload: createRuntimeEventPayload(runtimeId, "stopping"),
         }));
     }
     logger.info("Initiating graceful shutdown.", { timeoutMs: shutdownTimeout });
     const stopPromise = performShutdown(lifecycle, logger);
+    // The shutdown promise keeps running if the timeout wins; attach a
+    // handler now so its eventual rejection is never unhandled.
+    stopPromise.catch(() => { });
+    let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
+        timer = setTimeout(() => {
             reject(new RuntimeTimeoutError("shutdown", shutdownTimeout));
-        }, shutdownTimeout);
+        }, Math.min(Math.max(0, shutdownTimeout), MAX_TIMER_DELAY));
+        timer.unref?.();
     });
     try {
-        await Promise.race([stopPromise, timeoutPromise]);
+        const failures = await Promise.race([stopPromise, timeoutPromise]);
         if (emitEvents && eventBus) {
-            eventBus.publish(createEvent({
+            publishRuntimeEvent(eventBus, logger, createEvent({
                 type: "runtime.shutdown.complete",
-                payload: {
-                    runtimeId,
-                    timestamp: new Date(),
-                    state: "stopped",
-                },
+                payload: createRuntimeEventPayload(runtimeId, "stopped"),
             }));
         }
-        logger.info("Graceful shutdown complete.");
+        if (failures.length > 0) {
+            logger.warn("Shutdown completed with module failures.", {
+                failedModules: failures.map((failure) => failure.moduleId),
+            });
+        }
+        else {
+            logger.info("Graceful shutdown complete.");
+        }
+        return { failures, timedOut: false };
     }
     catch (error) {
-        if (error instanceof RuntimeTimeoutError) {
-            logger.error("Shutdown timed out, forcing stop.");
+        const timedOut = error instanceof RuntimeTimeoutError;
+        if (timedOut) {
+            logger.error("Shutdown timed out; abandoning remaining module teardown.", { timeoutMs: shutdownTimeout });
         }
         if (emitEvents && eventBus) {
-            eventBus.publish(createEvent({
+            publishRuntimeEvent(eventBus, logger, createEvent({
                 type: "runtime.failed",
-                payload: {
-                    runtimeId,
-                    timestamp: new Date(),
-                    state: "shutdown_failed",
-                    error: error instanceof Error ? error : new Error(String(error)),
-                    phase: "stop",
-                },
+                payload: createFailureEventPayload(runtimeId, "shutdown_failed", error instanceof Error ? error : new Error(String(error)), "stop"),
             }));
         }
-        throw new RuntimeStopError("Runtime shutdown failed.", {
+        throw new RuntimeStopError(timedOut
+            ? `Runtime shutdown exceeded ${shutdownTimeout}ms.`
+            : "Runtime shutdown failed.", {
             phase: "stop",
             cause: error instanceof Error ? error : undefined,
         });
     }
+    finally {
+        // Always clear: leaving this armed is what kept a cleanly stopped
+        // process alive until the timeout elapsed.
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
 }
 /**
  * Performs the actual shutdown operations.
+ *
+ * Returns every module failure so the caller can decide what a partial
+ * teardown means, rather than discarding them at the log line.
  */
 async function performShutdown(lifecycle, logger) {
-    // Stop modules
+    const failures = [];
     const stopResult = await lifecycle.stop();
     if (stopResult.failed.length > 0) {
+        failures.push(...stopResult.failed);
         logger.warn("Some modules failed during shutdown.", {
             failedModules: stopResult.failed.map((f) => f.moduleId),
         });
@@ -73,9 +98,9 @@ async function performShutdown(lifecycle, logger) {
         modules: stopResult.succeeded,
         durationMs: stopResult.durationMs,
     });
-    // Destroy modules
     const destroyResult = await lifecycle.destroy();
     if (destroyResult.failed.length > 0) {
+        failures.push(...destroyResult.failed);
         logger.warn("Some modules failed during destruction.", {
             failedModules: destroyResult.failed.map((f) => f.moduleId),
         });
@@ -83,5 +108,6 @@ async function performShutdown(lifecycle, logger) {
     logger.info("All modules destroyed.", {
         durationMs: destroyResult.durationMs,
     });
+    return failures;
 }
 //# sourceMappingURL=shutdown.core.js.map

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

@@ -1,44 +1,84 @@
 import type { Logger } from "@zudojs/logger";
+/**
+ * Options controlling signal and fatal-error handling.
+ */
+export interface SignalHandlerOptions {
+    readonly handleSignals: boolean;
+    readonly handleFatalErrors: boolean;
+    /**
+     * Whether a second termination signal exits immediately.
+     *
+     * Defaults to `true`. Without it an operator watching a wedged
+     * shutdown has no escape short of SIGKILL.
+     */
+    readonly forceExitOnSecondSignal?: boolean;
+    /**
+     * Whether an uncaught exception exits the process after shutdown.
+     *
+     * Defaults to `true`. Installing an `uncaughtException` handler
+     * suppresses Node's default crash, so without this the process keeps
+     * serving requests on state a fatal error has already made
+     * untrustworthy.
+     */
+    readonly exitOnFatalError?: boolean;
+    /**
+     * How long a fatal-error shutdown may take before the process exits
+     * anyway, in milliseconds. Defaults to 10000.
+     */
+    readonly fatalExitTimeout?: number;
+    /** Exit hook, injected for testing. Defaults to `process.exit`. */
+    readonly exit?: (code: number) => void;
+}
 /**
  * Signal handler for process lifecycle events.
  */
 export declare class SignalHandler {
     private readonly logger;
-    private readonly handleSignals;
-    private readonly handleFatalErrors;
+    private readonly options;
     private shutdownHandler;
     private isShuttingDown;
-    constructor(logger: Logger, options: {
-        readonly handleSignals: boolean;
-        readonly handleFatalErrors: boolean;
-    });
+    private registered;
+    private forcedExitTimer;
+    constructor(logger: Logger, options: SignalHandlerOptions);
     /**
      * 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: () => void): void;
+    register(shutdownHandler: () => void | Promise<void>): void;
     /**
      * 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(): void;
     /**
-     * Handles SIGTERM signal.
+     * Whether a shutdown has been initiated by a signal.
      */
+    get shuttingDown(): boolean;
     private handleTermination;
-    /**
-     * Handles SIGINT signal.
-     */
     private handleInterruption;
     /**
      * 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.
      */
     private handleUncaughtException;
+    private handleUnhandledRejection;
     /**
-     * Handles unhandled promise rejections.
+     * Shuts down after a fatal error and exits non-zero.
      */
-    private handleUnhandledRejection;
+    private initiateFatalShutdown;
     /**
      * Initiates graceful shutdown.
+     *
+     * A second termination signal exits immediately: an operator pressing
+     * Ctrl-C again on a stuck shutdown is asking for exactly that.
      */
     private initiateShutdown;
+    private exit;
 }
 //# sourceMappingURL=signalHandler.core.d.ts.map