@zudojs/core 0.1.0 → 1.0.0

package/dist/runtime/runtimeShutdown/runtimeShutdown.core.js

@@ -1,53 +1,16 @@
-import { Context, createContext } from "../../context/core/context.js";
-import { executeShutdownPipeline } from "./pipeline/index.js";
+import { executeShutdownPipeline, createShutdownPipelineState, createShutdownResult, } from "./pipeline/index.js";
 import { logRuntimeEvent } from "../runtimeLogger.js";
-import { RuntimeError } from "@zudojs/errors";
-export class RuntimeShutdownError extends RuntimeError {
-    name = "RuntimeShutdownError";
-    shutdownCode;
-    constructor(message, code, cause) {
-        super(message, {
-            code: "RUNTIME_SHUTDOWN",
-            phase: "shutdown",
-            cause,
-        });
-        this.shutdownCode = code;
-    }
-}
-export async function withShutdownTimeout(operation, timeoutMs) {
-    if (timeoutMs <= 0) {
-        await operation;
-        return;
-    }
-    let timer;
-    const timeout = new Promise((_resolve, reject) => {
-        timer = setTimeout(() => {
-            reject(new RuntimeShutdownError(`Runtime shutdown exceeded the configured timeout of ${timeoutMs}ms.`, "SHUTDOWN_TIMEOUT"));
-        }, timeoutMs);
-    });
-    try {
-        await Promise.race([operation, timeout]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-export function createShutdownResult(success, phase, stoppedModules, destroyedModules, errors, startedAt, completedAt) {
-    return Object.freeze({
-        success,
-        phase,
-        stoppedModules,
-        destroyedModules,
-        errors: Object.freeze([...errors]),
-        startedAt,
-        completedAt,
-        durationMs: completedAt.getTime() - startedAt.getTime(),
-    });
-}
+import { withRuntimeTimeout } from "../runtimeTimeout.js";
+import { RuntimeError } from "../runtimeError/runtimeError.base.js";
+import { InvalidRuntimeStateError, RuntimeStopError, } from "../runtimeError/runtimeError.lifecycle.js";
+import { RuntimeErrorCode } from "../runtimeError/runtimeError.type.js";
+/**
+ * Default shutdown service: stops and destroys modules according to
+ * the runtime's shutdown options.
+ */
 export class DefaultRuntimeShutdown {
-    _context;
+    _identity;
     _environment;
-    _application;
     _moduleRegistry;
     _moduleLifecycle;
     _logger;
@@ -55,11 +18,9 @@ export class DefaultRuntimeShutdown {
     _running = false;
     _phase = "created";
     _lastResult;
-    _shutdownContext;
     constructor(dependencies, runtimeOptions) {
-        this._context = dependencies.context;
+        this._identity = dependencies.identity;
         this._environment = dependencies.environment;
-        this._application = dependencies.application;
         this._moduleRegistry = dependencies.moduleRegistry;
         this._moduleLifecycle = dependencies.moduleLifecycle;
         this._logger = dependencies.logger;
@@ -73,75 +34,112 @@ export class DefaultRuntimeShutdown {
     }
     async shutdown(options = {}) {
         if (this._running) {
-            throw new RuntimeShutdownError("Runtime shutdown is already running.", "SHUTDOWN_ALREADY_RUNNING");
+            throw new InvalidRuntimeStateError("Runtime shutdown is already running.", this.errorContext({ state: this._phase }));
         }
         if (this._phase === "completed") {
-            throw new RuntimeShutdownError("Runtime has already been shut down.", "SHUTDOWN_ALREADY_COMPLETED");
+            throw new InvalidRuntimeStateError("Runtime has already been shut down.", this.errorContext({ state: this._phase }));
         }
         this._running = true;
         this._phase = "created";
+        const startedAt = new Date();
         const configuration = this.resolveOptions(options);
-        const errors = [];
-        this._shutdownContext = createContext({
-            application: this._application,
-            type: "worker",
-            id: `${this._context.identity.id}-shutdown`,
-        });
+        const state = createShutdownPipelineState();
+        const diagnostics = this._runtimeOptions.diagnostics;
         try {
-            logRuntimeEvent(this._logger, this._context, this._environment, "info", "Runtime shutdown started.");
-            const operation = executeShutdownPipeline(configuration, errors, { incrementStopped: () => { }, incrementDestroyed: () => { } }, this._moduleLifecycle, (phase) => {
+            if (diagnostics.shutdownLogging) {
+                this.log("info", "Runtime shutdown started.", {
+                    ...(diagnostics.includeState && { phase: this._phase }),
+                    ...(diagnostics.includeModules && {
+                        modules: this._moduleRegistry
+                            .getLoadedModules()
+                            .map((module) => module.id),
+                    }),
+                });
+            }
+            await withRuntimeTimeout((signal) => executeShutdownPipeline(configuration, {
+                moduleLifecycle: this._moduleLifecycle,
+                runtimeId: this._identity.id,
+                runtimeName: this._identity.name,
+            }, state, signal, (phase) => {
                 this._phase = phase;
-            }, this.log.bind(this));
-            await withShutdownTimeout(operation, configuration.timeoutMs);
+            }, this.log.bind(this)), configuration.timeoutMs, {
+                message: `Runtime shutdown exceeded the configured timeout of ${configuration.timeoutMs}ms.`,
+                error: this.errorContext({
+                    code: RuntimeErrorCode.SHUTDOWN_TIMEOUT,
+                    operation: "stop",
+                    phase: "stopping",
+                }),
+                onLateRejection: (error) => {
+                    this.log("warn", "Abandoned runtime shutdown failed late.", {
+                        error,
+                    });
+                },
+            });
             this._phase = "completed";
-            const completedAt = new Date();
-            const result = createShutdownResult(true, "completed", 0, 0, [], new Date(), completedAt);
+            const result = createShutdownResult(state.errors.length === 0, "completed", state.counters, state.errors, startedAt, new Date());
             this._lastResult = result;
-            logRuntimeEvent(this._logger, this._context, this._environment, "info", "Runtime shutdown completed.", { durationMs: result.durationMs });
+            if (diagnostics.shutdownLogging) {
+                this.log(result.success ? "info" : "warn", result.success
+                    ? "Runtime shutdown completed."
+                    : "Runtime shutdown completed with errors.", {
+                    durationMs: result.durationMs,
+                    stoppedModules: result.stoppedModules,
+                    destroyedModules: result.destroyedModules,
+                    errors: result.errors.length,
+                    ...(diagnostics.includeState && { phase: result.phase }),
+                });
+            }
             return result;
         }
         catch (error) {
+            const failedPhase = this._phase;
             this._phase = "failed";
-            const shutdownError = error instanceof RuntimeShutdownError
+            const shutdownError = error instanceof RuntimeError
                 ? error
-                : new RuntimeShutdownError("Runtime shutdown failed.", "SHUTDOWN_FAILED", error);
-            const completedAt = new Date();
-            const result = createShutdownResult(false, "failed", 0, 0, [], new Date(), completedAt);
+                : new RuntimeStopError("Runtime shutdown failed.", this.errorContext({ phase: "stopping", cause: error }));
+            state.errors.push({ phase: failedPhase, error: shutdownError });
+            const result = createShutdownResult(false, "failed", state.counters, state.errors, startedAt, new Date());
             this._lastResult = result;
-            logRuntimeEvent(this._logger, this._context, this._environment, "error", "Runtime shutdown failed.", { error: shutdownError });
+            this.log("error", "Runtime shutdown failed.", {
+                error: shutdownError,
+                failedPhase,
+                durationMs: result.durationMs,
+            });
             throw shutdownError;
         }
         finally {
             this._running = false;
         }
     }
-    resolveOptions(options) {
-        return {
-            stopModules: options.stopModules ?? this._runtimeOptions.shutdown.autoStopModules,
-            destroyModules: options.destroyModules ??
-                this._runtimeOptions.shutdown.autoDestroyModules,
-            continueOnStopError: options.continueOnStopError ??
-                this._runtimeOptions.shutdown.continueOnStopError,
-            continueOnDestroyError: options.continueOnDestroyError ??
-                this._runtimeOptions.shutdown.continueOnDestroyError,
-            timeoutMs: options.timeoutMs ?? this._runtimeOptions.shutdown.timeoutMs,
-        };
-    }
     getLastResult() {
         return this._lastResult;
     }
-    getShutdownContext() {
-        return this._shutdownContext;
-    }
     reset() {
         if (this._running) {
-            throw new RuntimeShutdownError("Cannot reset runtime shutdown while it is running.", "SHUTDOWN_RESET_WHILE_RUNNING");
+            throw new InvalidRuntimeStateError("Cannot reset runtime shutdown while it is running.", this.errorContext({ state: this._phase }));
         }
         this._phase = "created";
         this._lastResult = undefined;
     }
+    resolveOptions(options) {
+        const shutdown = this._runtimeOptions.shutdown;
+        return {
+            stopModules: options.stopModules ?? shutdown.autoStopModules,
+            destroyModules: options.destroyModules ?? shutdown.autoDestroyModules,
+            continueOnStopError: options.continueOnStopError ?? shutdown.continueOnStopError,
+            continueOnDestroyError: options.continueOnDestroyError ?? shutdown.continueOnDestroyError,
+            timeoutMs: options.timeoutMs ?? shutdown.timeoutMs,
+        };
+    }
+    errorContext(extra) {
+        return {
+            ...extra,
+            runtimeId: this._identity.id,
+            runtimeName: this._identity.name,
+        };
+    }
     log(level, message, metadata) {
-        logRuntimeEvent(this._logger, this._context, this._environment, level, message, metadata);
+        logRuntimeEvent(this._logger, this._identity, this._environment, level, message, metadata);
     }
 }
 //# sourceMappingURL=runtimeShutdown.core.js.map

package/dist/runtime/runtimeShutdown/runtimeShutdown.type.d.ts

@@ -1,16 +1,15 @@
 import type { Logger } from "../../logging/core/logger.js";
-import type { ApplicationContext } from "../../application/applicationContext.context.js";
 import type { ModuleLifecycleManager } from "../../modules/moduleLifecycle/index.js";
 import type { ModuleRegistry } from "../../modules/moduleRegistry/index.js";
-import type { RuntimeContext } from "../runtimeContext/index.js";
+import type { RuntimeIdentity } from "../runtimeContext/index.js";
 import type { RuntimeEnvironment } from "../runtimeEnvironment/index.js";
 /**
  * Dependencies required by RuntimeShutdown.
  */
 export interface RuntimeShutdownDependencies {
-    readonly context: RuntimeContext;
+    /** Identity attached to errors and log entries. */
+    readonly identity: RuntimeIdentity;
     readonly environment: RuntimeEnvironment;
-    readonly application: ApplicationContext;
     readonly moduleRegistry: ModuleRegistry;
     readonly moduleLifecycle: ModuleLifecycleManager;
     readonly logger: Logger;
@@ -31,6 +30,8 @@ export interface RuntimeShutdownConfig {
 export type RuntimeShutdownPhase = "created" | "stopping" | "stopped" | "destroying" | "destroyed" | "completed" | "failed";
 /**
  * Error captured during shutdown.
+ *
+ * Module-level failures carry the failing module id in `moduleName`.
  */
 export interface RuntimeShutdownErrorInfo {
     readonly phase: RuntimeShutdownPhase;
@@ -39,6 +40,10 @@ export interface RuntimeShutdownErrorInfo {
 }
 /**
  * Result of a shutdown operation.
+ *
+ * `success` is true only when no error was recorded. A shutdown that
+ * continued past module failures (continueOn*Error) resolves with
+ * `success: false` and the failures listed in `errors`.
  */
 export interface RuntimeShutdownResult {
     readonly success: boolean;
@@ -58,7 +63,6 @@ export interface RuntimeShutdown {
     readonly phase: RuntimeShutdownPhase;
     shutdown(options?: RuntimeShutdownConfig): Promise<RuntimeShutdownResult>;
     getLastResult(): RuntimeShutdownResult | undefined;
-    getShutdownContext(): import("../../context/core/context.js").Context | undefined;
     reset(): void;
 }
 /**

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

@@ -0,0 +1,8 @@
+/**
+ * Runtime Signals
+ *
+ * Process signal and exception handling for graceful shutdown.
+ */
+export { RuntimeSignalManager } from "./runtimeSignals.js";
+export type { RuntimeTerminationSignal, RuntimeProcessEvent, RuntimeSignalTarget, RuntimeSignalHandlers, RuntimeSignalManagerOptions, } from "./runtimeSignals.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/runtimeSignals/index.js

@@ -0,0 +1,7 @@
+/**
+ * Runtime Signals
+ *
+ * Process signal and exception handling for graceful shutdown.
+ */
+export { RuntimeSignalManager } from "./runtimeSignals.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,93 @@
+import type { Logger } from "../../logging/core/logger.js";
+import type { RuntimeSignalOptions } from "../runtimeOptions/runtimeOptions.type.js";
+/**
+ * Termination signals the runtime can react to.
+ */
+export type RuntimeTerminationSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
+/**
+ * Process events the signal manager can subscribe to.
+ */
+export type RuntimeProcessEvent = RuntimeTerminationSignal | "uncaughtException" | "unhandledRejection";
+/**
+ * Minimal `process`-like target. Defaults to the global process; tests
+ * inject an EventEmitter so nothing is registered on the real process
+ * and `exit` can be observed instead of executed.
+ */
+export interface RuntimeSignalTarget {
+    on(event: string, listener: (...args: never[]) => void): unknown;
+    off(event: string, listener: (...args: never[]) => void): unknown;
+    exit?(code?: number): void;
+}
+/**
+ * Hooks the runtime supplies to react to process events.
+ */
+export interface RuntimeSignalHandlers {
+    /**
+     * A termination signal arrived; the runtime should stop gracefully.
+     */
+    onSignal(signal: RuntimeTerminationSignal): void | Promise<void>;
+    /**
+     * An uncaught exception reached the process.
+     */
+    onUncaughtException(error: unknown): void | Promise<void>;
+    /**
+     * A promise rejection was never handled.
+     */
+    onUnhandledRejection(reason: unknown): void | Promise<void>;
+}
+/**
+ * Options for the signal manager.
+ */
+export interface RuntimeSignalManagerOptions {
+    readonly signals: Required<RuntimeSignalOptions>;
+    readonly target?: RuntimeSignalTarget;
+    readonly logger?: Logger;
+}
+/**
+ * Registers and removes process signal/exception handlers on behalf
+ * of the runtime.
+ *
+ * Policy:
+ * - Handlers are registered by `register()` and removed by
+ *   `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.
+ * - `process.exit` is never called otherwise.
+ */
+export declare class RuntimeSignalManager {
+    private readonly _signals;
+    private readonly _target;
+    private readonly _logger;
+    private readonly _listeners;
+    private _handlers;
+    private _receivedSignals;
+    private _stopping;
+    constructor(options: RuntimeSignalManagerOptions);
+    /**
+     * Whether handlers are currently attached to the target.
+     */
+    get registered(): boolean;
+    /**
+     * Number of termination signals received since registration.
+     */
+    get receivedSignals(): number;
+    /**
+     * Process events this manager subscribes to given its options.
+     */
+    get events(): readonly RuntimeProcessEvent[];
+    /**
+     * Attaches handlers to the target. No-op when already registered or
+     * when no target is available (non-Node engines).
+     */
+    register(handlers: RuntimeSignalHandlers): void;
+    /**
+     * Detaches all handlers from the target.
+     */
+    unregister(): void;
+    private createListener;
+    private handleSignal;
+    private run;
+}
+//# sourceMappingURL=runtimeSignals.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.js

@@ -0,0 +1,149 @@
+/**
+ * Registers and removes process signal/exception handlers on behalf
+ * of the runtime.
+ *
+ * Policy:
+ * - Handlers are registered by `register()` and removed by
+ *   `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.
+ * - `process.exit` is never called otherwise.
+ */
+export class RuntimeSignalManager {
+    _signals;
+    _target;
+    _logger;
+    _listeners = new Map();
+    _handlers;
+    _receivedSignals = 0;
+    _stopping = false;
+    constructor(options) {
+        this._signals = options.signals;
+        this._target = options.target ?? getGlobalProcess();
+        this._logger = options.logger;
+    }
+    /**
+     * Whether handlers are currently attached to the target.
+     */
+    get registered() {
+        return this._listeners.size > 0;
+    }
+    /**
+     * Number of termination signals received since registration.
+     */
+    get receivedSignals() {
+        return this._receivedSignals;
+    }
+    /**
+     * Process events this manager subscribes to given its options.
+     */
+    get events() {
+        const events = [];
+        if (this._signals.handleSigint)
+            events.push("SIGINT");
+        if (this._signals.handleSigterm)
+            events.push("SIGTERM");
+        if (this._signals.handleSighup)
+            events.push("SIGHUP");
+        if (this._signals.handleUncaughtException)
+            events.push("uncaughtException");
+        if (this._signals.handleUnhandledRejection)
+            events.push("unhandledRejection");
+        return events;
+    }
+    /**
+     * Attaches handlers to the target. No-op when already registered or
+     * when no target is available (non-Node engines).
+     */
+    register(handlers) {
+        if (this.registered || !this._target)
+            return;
+        this._handlers = handlers;
+        this._receivedSignals = 0;
+        this._stopping = false;
+        for (const event of this.events) {
+            const listener = this.createListener(event);
+            this._listeners.set(event, listener);
+            this._target.on(event, listener);
+        }
+    }
+    /**
+     * Detaches all handlers from the target.
+     */
+    unregister() {
+        if (!this._target)
+            return;
+        for (const [event, listener] of this._listeners) {
+            this._target.off(event, listener);
+        }
+        this._listeners.clear();
+        this._handlers = undefined;
+    }
+    createListener(event) {
+        switch (event) {
+            case "SIGINT":
+            case "SIGTERM":
+            case "SIGHUP":
+                return () => {
+                    this.handleSignal(event);
+                };
+            case "uncaughtException":
+                return ((error) => {
+                    this.run(() => this._handlers?.onUncaughtException(error), "uncaughtException");
+                });
+            case "unhandledRejection":
+                return ((reason) => {
+                    this.run(() => this._handlers?.onUnhandledRejection(reason), "unhandledRejection");
+                });
+            default:
+                return () => { };
+        }
+    }
+    handleSignal(signal) {
+        this._receivedSignals += 1;
+        if (this._stopping) {
+            if (this._signals.forceExitOnSecondSignal) {
+                this._logger?.warn(`Received ${signal} during shutdown; forcing process exit.`, { signal, exitCode: this._signals.forceExitCode });
+                this._target?.exit?.(this._signals.forceExitCode);
+                return;
+            }
+            this._logger?.warn(`Received ${signal} while shutdown is already in progress; ignoring.`, { signal });
+            return;
+        }
+        this._stopping = true;
+        this._logger?.info(`Received ${signal}; stopping runtime gracefully.`, {
+            signal,
+        });
+        this.run(() => this._handlers?.onSignal(signal), signal);
+    }
+    run(handler, event) {
+        try {
+            const result = handler();
+            if (result && typeof result.then === "function") {
+                result.catch((error) => {
+                    this._logger?.error(`Runtime ${event} handler failed.`, error, {
+                        event,
+                    });
+                });
+            }
+        }
+        catch (error) {
+            this._logger?.error(`Runtime ${event} handler failed.`, error, {
+                event,
+            });
+        }
+    }
+}
+function getGlobalProcess() {
+    const candidate = globalThis.process;
+    if (typeof candidate === "object" &&
+        candidate !== null &&
+        typeof candidate.on === "function" &&
+        typeof candidate.off === "function") {
+        return candidate;
+    }
+    return undefined;
+}
+//# sourceMappingURL=runtimeSignals.js.map

package/dist/runtime/runtimeState.state.d.ts

@@ -1,4 +1,4 @@
-import { RuntimeStateError } from "@zudojs/errors";
+export { InvalidRuntimeStateError, InvalidRuntimeTransitionError, } from "./runtimeError/runtimeError.lifecycle.js";
 /** Runtime lifecycle states. */
 export declare enum RuntimeState {
     CREATED = "created",
@@ -8,11 +8,16 @@ export declare enum RuntimeState {
     STOPPED = "stopped",
     FAILED = "failed"
 }
-/** Terminal runtime states. */
+/** Terminal runtime states: no further transitions are possible. */
 export declare const TERMINAL_RUNTIME_STATES: readonly RuntimeState[];
 /** Runtime states from which startup is allowed. */
 export declare const STARTABLE_RUNTIME_STATES: readonly RuntimeState[];
-/** Runtime states from which shutdown is allowed. */
+/**
+ * Runtime states from which shutdown is allowed.
+ *
+ * CREATED is included because stopping a runtime that never started
+ * is a valid soft stop (no modules to unwind).
+ */
 export declare const STOPPABLE_RUNTIME_STATES: readonly RuntimeState[];
 /** Runtime states that indicate a lifecycle operation is in progress. */
 export declare const TRANSITIONAL_RUNTIME_STATES: readonly RuntimeState[];
@@ -24,6 +29,19 @@ export interface RuntimeStateSnapshot {
     readonly transitioning: boolean;
     readonly failed: boolean;
 }
+/**
+ * Timestamps recorded by the runtime as it moves through its
+ * states. Owned by the Runtime object (never by the execution
+ * context, which is immutable).
+ */
+export interface RuntimeTiming {
+    readonly createdAt: Date;
+    readonly startupStartedAt?: Date;
+    readonly readyAt?: Date;
+    readonly shutdownStartedAt?: Date;
+    readonly stoppedAt?: Date;
+    readonly failedAt?: Date;
+}
 /** Describes a runtime state transition. */
 export interface RuntimeStateTransition {
     readonly from: RuntimeState;
@@ -31,17 +49,6 @@ export interface RuntimeStateTransition {
     readonly timestamp: Date;
     readonly reason?: string;
 }
-/** Error thrown when an invalid runtime state is encountered. */
-export declare class InvalidRuntimeStateError extends RuntimeStateError {
-    readonly state: string;
-    constructor(message: string);
-}
-/** Error thrown when an invalid runtime state transition is attempted. */
-export declare class InvalidRuntimeTransitionError extends RuntimeStateError {
-    readonly from: RuntimeState;
-    readonly to: RuntimeState;
-    constructor(from: RuntimeState, to: RuntimeState);
-}
 export declare function isRuntimeState(value: unknown): value is RuntimeState;
 export declare function isRuntimeReady(state: RuntimeState): boolean;
 export declare function isRuntimeFailed(state: RuntimeState): boolean;
@@ -49,6 +56,17 @@ export declare function isRuntimeTransitioning(state: RuntimeState): boolean;
 export declare function isRuntimeTerminal(state: RuntimeState): boolean;
 export declare function canStartRuntime(state: RuntimeState): boolean;
 export declare function canStopRuntime(state: RuntimeState): boolean;
+/**
+ * Determines whether a runtime state transition is valid.
+ *
+ * Rules:
+ * - Self transitions are never valid.
+ * - FAILED is reachable from every non-terminal state
+ *   (CREATED, BOOTSTRAPPING, READY, STOPPING).
+ * - CREATED → STOPPED is a valid "soft stop": a runtime that
+ *   never started can be stopped as a no-op.
+ * - STOPPED and FAILED are terminal for transitions.
+ */
 export declare function canTransitionRuntime(from: RuntimeState, to: RuntimeState): boolean;
 export declare function assertRuntimeState(value: unknown): asserts value is RuntimeState;
 export declare function assertRuntimeTransition(from: RuntimeState, to: RuntimeState): void;