@zudojs/runtime 0.1.0 → 1.1.0

package/dist/readiness/readiness.core.js

@@ -1,14 +1,27 @@
+import { RuntimeStateError } from "../runtimeError/index.js";
+/**
+ * How long a single readiness check may run before it counts as failed.
+ *
+ * Without a bound, one hanging probe hangs the readiness endpoint
+ * indefinitely — a health check that never answers is worse than one
+ * that answers "unhealthy".
+ */
+const DEFAULT_CHECK_TIMEOUT = 5_000;
 /**
  * Tracks runtime readiness state.
  */
 export class ReadinessTracker {
     state = "not_ready";
     checks = new Map();
+    checkFns = new Map();
     autoMarkReady;
+    checkTimeout;
     ready = false;
     reason;
+    running;
     constructor(options = {}) {
         this.autoMarkReady = options.autoMarkReady ?? true;
+        this.checkTimeout = options.checkTimeout ?? DEFAULT_CHECK_TIMEOUT;
         if (options.initialChecks) {
             for (const check of options.initialChecks) {
                 this.registerCheck(check.name, check.check);
@@ -17,37 +30,140 @@ export class ReadinessTracker {
     }
     /**
      * Registers a readiness check.
+     *
+     * The check function is retained so it can be re-evaluated later by
+     * `updateCheck(name)` or `runChecks()`. Registration does not run the
+     * check: it starts out not-ready until it is first evaluated.
      */
     registerCheck(name, check) {
+        this.checkFns.set(name, check);
         this.checks.set(name, {
             name,
             ready: false,
             lastCheckedAt: new Date(),
+            durationMs: 0,
         });
         this.evaluateReadiness();
     }
     /**
-     * Updates a readiness check result.
+     * Removes a readiness check.
+     *
+     * Returns whether a check with that name was registered.
+     */
+    removeCheck(name) {
+        const existed = this.checks.delete(name);
+        this.checkFns.delete(name);
+        if (!existed) {
+            return false;
+        }
+        if (this.autoMarkReady &&
+            this.checks.size === 0 &&
+            this.state === "degraded") {
+            // `degraded` is only ever entered from `ready` because a check
+            // failed. Removing the last check leaves nothing failing, so the
+            // tracker returns to ready — otherwise `evaluateReadiness()` (which
+            // only acts when checks exist) left it stuck at `ready: false` while
+            // the derived health, seeing no checks, reported `healthy`.
+            this.markReady("All readiness checks removed.");
+        }
+        else {
+            this.evaluateReadiness();
+        }
+        return true;
+    }
+    /**
+     * Evaluates a readiness check and records its result.
+     *
+     * Re-runs the function registered under `name` unless a replacement is
+     * supplied, in which case the replacement is stored and used from then on.
      */
     async updateCheck(name, check) {
-        const startTime = Date.now();
+        if (check !== undefined) {
+            this.checkFns.set(name, check);
+        }
+        const fn = this.checkFns.get(name);
+        if (fn === undefined) {
+            throw new RuntimeStateError(`Readiness check "${name}" is not registered.`);
+        }
+        await this.evaluateCheck(name, fn);
+        this.evaluateReadiness();
+    }
+    /**
+     * Re-evaluates every registered check.
+     */
+    async runChecks() {
+        // Overlapping runs would interleave their writes into `checks`;
+        // callers that arrive mid-run join the run already in flight.
+        if (this.running) {
+            return this.running;
+        }
+        this.running = (async () => {
+            try {
+                await Promise.all([...this.checkFns].map(([name, fn]) => this.evaluateCheck(name, fn)));
+                this.evaluateReadiness();
+            }
+            finally {
+                this.running = undefined;
+            }
+        })();
+        return this.running;
+    }
+    /**
+     * Whether any readiness check is registered.
+     */
+    hasChecks() {
+        return this.checkFns.size > 0;
+    }
+    /**
+     * Runs a single check and records its result and duration.
+     */
+    async evaluateCheck(name, fn) {
+        const startedAt = Date.now();
         try {
-            const result = await check();
+            const result = await this.withCheckTimeout(name, fn);
             this.checks.set(name, {
                 name,
                 ready: result,
                 lastCheckedAt: new Date(),
+                durationMs: Date.now() - startedAt,
             });
         }
-        catch {
+        catch (error) {
             this.checks.set(name, {
                 name,
                 ready: false,
                 lastCheckedAt: new Date(),
-                message: "Check threw an error",
+                durationMs: Date.now() - startedAt,
+                message: error instanceof Error
+                    ? `Check threw an error: ${error.message}`
+                    : "Check threw an error",
             });
         }
-        this.evaluateReadiness();
+    }
+    /**
+     * Runs a check under a timeout, clearing the timer either way.
+     */
+    async withCheckTimeout(name, fn) {
+        if (this.checkTimeout <= 0) {
+            return fn();
+        }
+        let timer;
+        try {
+            return await Promise.race([
+                Promise.resolve(fn()),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        reject(new Error(`Readiness check "${name}" did not settle within ${this.checkTimeout}ms.`));
+                    }, this.checkTimeout);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
     }
     /**
      * Marks the runtime as ready.

package/dist/readiness/readiness.type.d.ts

@@ -10,7 +10,16 @@ export interface ReadinessCheck {
     readonly ready: boolean;
     readonly message?: string;
     readonly lastCheckedAt: Date;
+    /**
+     * How long the last evaluation of this check took, in milliseconds.
+     * `0` for a check that has been registered but not yet run.
+     */
+    readonly durationMs: number;
 }
+/**
+ * A readiness check function.
+ */
+export type ReadinessCheckFn = () => boolean | Promise<boolean>;
 /**
  * Readiness tracker state.
  */
@@ -29,12 +38,17 @@ export interface ReadinessOptions {
      */
     readonly initialChecks?: ReadonlyArray<{
         readonly name: string;
-        readonly check: () => boolean | Promise<boolean>;
+        readonly check: ReadinessCheckFn;
     }>;
     /**
      * Whether to automatically mark as ready when all checks pass.
      * @default true
      */
     readonly autoMarkReady?: boolean;
+    /**
+     * How long a single check may run before it is recorded as failed, in
+     * milliseconds. Defaults to 5000; set to `0` to disable the bound.
+     */
+    readonly checkTimeout?: number;
 }
 //# sourceMappingURL=readiness.type.d.ts.map

package/dist/registry/registry.core.d.ts

@@ -21,8 +21,15 @@ export declare class RuntimeRegistry {
     register(id: string, runtime: Runtime): void;
     /**
      * Unregister a runtime instance.
+     *
+     * Dropping the reference does not stop the runtime; use
+     * {@link removeAndStop} when the runtime should also be shut down.
      */
-    unregister(id: string): void;
+    unregister(id: string): boolean;
+    /**
+     * Unregister a runtime and stop it.
+     */
+    removeAndStop(id: string): Promise<boolean>;
     /**
      * Get a runtime by ID.
      */
@@ -50,6 +57,12 @@ export declare class RuntimeRegistry {
     /**
      * Start all registered runtimes.
      */
+    /**
+     * Start all registered runtimes.
+     *
+     * A failure stops whatever already started before rethrowing, so a
+     * partially started process does not linger.
+     */
     startAll(): Promise<void>;
     /**
      * Stop all registered runtimes.

package/dist/registry/registry.core.js

@@ -25,9 +25,24 @@ export class RuntimeRegistry {
     }
     /**
      * Unregister a runtime instance.
+     *
+     * Dropping the reference does not stop the runtime; use
+     * {@link removeAndStop} when the runtime should also be shut down.
      */
     unregister(id) {
+        return this.runtimes.delete(id);
+    }
+    /**
+     * Unregister a runtime and stop it.
+     */
+    async removeAndStop(id) {
+        const runtime = this.runtimes.get(id);
+        if (!runtime) {
+            return false;
+        }
         this.runtimes.delete(id);
+        await runtime.stop();
+        return true;
     }
     /**
      * Get a runtime by ID.
@@ -72,9 +87,30 @@ export class RuntimeRegistry {
     /**
      * Start all registered runtimes.
      */
+    /**
+     * Start all registered runtimes.
+     *
+     * A failure stops whatever already started before rethrowing, so a
+     * partially started process does not linger.
+     */
     async startAll() {
+        const started = [];
         for (const runtime of this.runtimes.values()) {
-            await runtime.start();
+            try {
+                await runtime.start();
+                started.push(runtime);
+            }
+            catch (error) {
+                for (const running of started.reverse()) {
+                    try {
+                        await running.stop();
+                    }
+                    catch {
+                        // Continue unwinding; the original error is what matters.
+                    }
+                }
+                throw error;
+            }
         }
     }
     /**
@@ -107,7 +143,10 @@ export class RuntimeRegistry {
      * Get status of all runtimes.
      */
     getStatus() {
-        const result = {};
+        // Null-prototype: ids come from callers, and assigning a key of
+        // "__proto__" to an object literal reassigns its prototype instead
+        // of adding a property.
+        const result = Object.create(null);
         for (const [id, runtime] of this.runtimes) {
             result[id] = {
                 state: runtime.state,

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

@@ -1,10 +1,11 @@
 import type { Logger } from "@zudojs/logger";
 import type { EventBus } from "@zudojs/events";
 import type { Container } from "@zudojs/container";
-import type { Module } from "@zudojs/core";
-import type { RuntimeState, RuntimeStatus } from "../runtimeState/index.js";
+import type { ConfigurationManager, Module, ModuleContext } from "@zudojs/core";
+import type { RuntimeState, RuntimeStatus, RuntimeHealth } from "../runtimeState/index.js";
 import type { RuntimeOptions } from "../runtimeOptions/index.js";
 import type { RuntimeContext } from "../runtimeContext/index.js";
+import type { ReadinessCheckFn, ReadinessTrackerState } from "../readiness/index.js";
 /**
  * Zudojs runtime interface.
  *
@@ -15,9 +16,30 @@ export interface Runtime {
     readonly state: RuntimeState;
     readonly status: RuntimeStatus;
     readonly context: RuntimeContext;
+    readonly health: RuntimeHealth;
     readonly ready: boolean;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Registers a readiness check.
+     *
+     * A registered check starts out failing until it is first evaluated by
+     * `runReadinessChecks`, so registering one on a running runtime moves it
+     * to `degraded` until the check passes.
+     */
+    registerReadinessCheck(name: string, check: ReadinessCheckFn): void;
+    /**
+     * Removes a readiness check. Returns whether one was registered.
+     */
+    removeReadinessCheck(name: string): boolean;
+    /**
+     * Re-evaluates every registered readiness check.
+     */
+    runReadinessChecks(): Promise<void>;
+    /**
+     * Current readiness state, including per-check results.
+     */
+    readonly readiness: ReadinessTrackerState;
 }
 /**
  * Dependencies required to create a runtime.
@@ -27,19 +49,28 @@ export interface RuntimeDependencies {
     readonly logger: Logger;
     readonly container: Container;
     readonly eventBus: EventBus;
+    /**
+     * Configuration manager exposed to modules through their context.
+     * Defaults to an empty manager loaded at startup.
+     */
+    readonly configuration?: ConfigurationManager;
+    /**
+     * Application context exposed to modules as `context.application`.
+     * Modules that read it without one supplied get a clear error.
+     */
+    readonly application?: ModuleContext["application"];
 }
 /**
  * Default runtime implementation.
  */
 export declare class DefaultRuntime implements Runtime {
     private _state;
-    private _status;
-    private _context;
-    private _ready;
+    private readonly _contextBase;
     private _startedAt?;
     private _stoppedAt?;
     private _failedAt?;
     private _error?;
+    private _shutdownFailures;
     private readonly options;
     private readonly modules;
     private readonly logger;
@@ -61,6 +92,27 @@ export declare class DefaultRuntime implements Runtime {
      * Runtime context.
      */
     get context(): RuntimeContext;
+    /**
+     * Current runtime health, derived from the lifecycle state and the
+     * registered readiness checks.
+     */
+    get health(): RuntimeHealth;
+    /**
+     * Current readiness state, including per-check results.
+     */
+    get readiness(): ReadinessTrackerState;
+    /**
+     * Registers a readiness check.
+     */
+    registerReadinessCheck(name: string, check: ReadinessCheckFn): void;
+    /**
+     * Removes a readiness check.
+     */
+    removeReadinessCheck(name: string): boolean;
+    /**
+     * Re-evaluates every registered readiness check.
+     */
+    runReadinessChecks(): Promise<void>;
     /**
      * Whether the runtime is ready.
      */
@@ -72,6 +124,14 @@ export declare class DefaultRuntime implements Runtime {
     /**
      * Stops the runtime.
      */
+    /**
+     * Stops the runtime.
+     *
+     * A failed runtime is stoppable: startup rollback only reaches modules
+     * that were started, so this is the operator's route to releasing
+     * everything else. It is also idempotent — stopping an already-stopped
+     * runtime is a no-op rather than an error.
+     */
     stop(): Promise<void>;
     /**
      * Performs runtime startup.
@@ -81,10 +141,20 @@ export declare class DefaultRuntime implements Runtime {
      * Performs runtime shutdown.
      */
     private performStop;
+    /**
+     * Runs shutdown in response to a termination signal.
+     */
+    private handleShutdownSignal;
     /**
      * Transitions to a new state.
      */
     private transitionTo;
+    /**
+     * Emits `runtime.health.changed` when the derived health state has moved
+     * away from `previousHealth`. Health is derived rather than stored, so
+     * callers compare against a value captured before the change.
+     */
+    private emitHealthChange;
     /**
      * Emits a runtime event.
      */