immortal-js 1.0.0

package/packages/core/src/runtime.ts

@@ -0,0 +1,242 @@
+/**
+ * @file runtime.ts
+ * @description ImmortalRuntime — the central orchestrator
+ * Initializes and wires all five layers together
+ */
+
+import type { ImmortalConfig, SystemMetrics, ImmortalPlugin } from "./types.js";
+import { mergeWithDefaults } from "./config/defaults.js";
+import { validateConfig } from "./config/schema.js";
+import { createLogger, getLogger } from "./logger.js";
+import { getEventBus } from "./event-bus.js";
+import type { MetricsCollector } from "./monitoring/MetricsCollector.js";
+import type { HealthMonitor } from "./monitoring/HealthMonitor.js";
+import type { MemoryLeakGuard } from "./monitoring/MemoryLeakGuard.js";
+import type { GracefulShutdown } from "./lifecycle/GracefulShutdown.js";
+import type { ErrorTrap } from "./safe-zone/ErrorTrap.js";
+
+export interface ImmortalRuntimeAPI {
+  config: Required<ImmortalConfig>;
+  getMetrics(): SystemMetrics;
+  shutdown(signal?: string): Promise<void>;
+  addPlugin(plugin: ImmortalPlugin): void;
+  isHealthy(): boolean;
+}
+
+export class ImmortalRuntime implements ImmortalRuntimeAPI {
+  public readonly config: Required<ImmortalConfig>;
+  private _initialized = false;
+  private _healthy = true;
+  private _metricsCollector: MetricsCollector | undefined;
+  private _healthMonitor: HealthMonitor | undefined;
+  private _memoryLeakGuard: MemoryLeakGuard | undefined;
+  private _gracefulShutdown: GracefulShutdown | undefined;
+  private _errorTrap: ErrorTrap | undefined;
+
+  constructor(userConfig: ImmortalConfig = {}) {
+    const validation = validateConfig(userConfig);
+    if (!validation.valid) {
+      throw new Error(
+        `Immortal.js configuration errors:\n${validation.errors.join("\n")}`
+      );
+    }
+    for (const warning of validation.warnings) {
+      console.warn(warning);
+    }
+
+    this.config = mergeWithDefaults(userConfig);
+    createLogger(this.config.logger as Parameters<typeof createLogger>[0]);
+  }
+
+  async initialize(): Promise<this> {
+    if (this._initialized) return this;
+
+    const logger = getLogger();
+    const bus = getEventBus();
+
+    logger.info("Immortal.js Runtime initializing...", {
+      env: process.env["NODE_ENV"],
+      nodeVersion: process.version,
+      pid: process.pid,
+    });
+
+    try {
+      const [
+        MetricsCollectorMod,
+        HealthMonitorMod,
+        MemoryLeakGuardMod,
+        GracefulShutdownMod,
+        ErrorTrapMod,
+      ] = await Promise.all([
+        import("./monitoring/MetricsCollector.js").catch(() => null),
+        import("./monitoring/HealthMonitor.js").catch(() => null),
+        import("./monitoring/MemoryLeakGuard.js").catch(() => null),
+        import("./lifecycle/GracefulShutdown.js").catch(() => null),
+        import("./safe-zone/ErrorTrap.js").catch(() => null),
+      ]);
+
+      if (MetricsCollectorMod) {
+        this._metricsCollector = new MetricsCollectorMod.MetricsCollector();
+      }
+
+      if (HealthMonitorMod && this._metricsCollector) {
+        this._healthMonitor = new HealthMonitorMod.HealthMonitor(
+          this.config.healthMonitor,
+          bus,
+          this._metricsCollector
+        );
+        this._healthMonitor.start();
+      }
+
+      if (MemoryLeakGuardMod) {
+        this._memoryLeakGuard = new MemoryLeakGuardMod.MemoryLeakGuard(
+          this.config.memoryGuard,
+          bus
+        );
+        this._memoryLeakGuard.start();
+      }
+
+      if (GracefulShutdownMod) {
+        this._gracefulShutdown = new GracefulShutdownMod.GracefulShutdown(
+          this.config.gracefulShutdown,
+          bus
+        );
+      }
+
+      if (ErrorTrapMod) {
+        this._errorTrap = new ErrorTrapMod.ErrorTrap(bus);
+        this._errorTrap.install();
+      }
+    } catch (err) {
+      logger.warn("Some Immortal.js layers could not be loaded", {
+        error: (err as Error).message,
+      });
+    }
+
+    // Initialize plugins
+    const pluginContext = {
+      config: this.config,
+      emit: (event: Parameters<typeof bus.emit>[1]) => bus.emit("error:captured", event),
+      getMetrics: () => this.getMetrics(),
+      logger,
+    };
+
+    for (const plugin of this.config.plugins) {
+      try {
+        await plugin.onInit?.(pluginContext);
+        logger.info(`Plugin '${plugin.name}' initialized`);
+      } catch (err) {
+        logger.error(`Plugin '${plugin.name}' failed to initialize`, {
+          error: (err as Error).message,
+        });
+      }
+    }
+
+    if (this.config.chaos?.enabled && process.env["NODE_ENV"] === "production") {
+      logger.error("Chaos mode is BLOCKED in production.");
+      if (this.config.chaos) this.config.chaos.enabled = false;
+    }
+
+    this._initialized = true;
+    logger.info("Immortal.js Runtime ready", {
+      layers: ["SafeZone", "Recovery", "Isolation", "Supervision", "Monitoring"],
+      plugins: this.config.plugins.map((p) => p.name),
+    });
+
+    return this;
+  }
+
+  getMetrics(): SystemMetrics {
+    if (this._metricsCollector) {
+      return this._metricsCollector.getSnapshot();
+    }
+    return this._emptyMetrics();
+  }
+
+  isHealthy(): boolean {
+    return this._healthy;
+  }
+
+  async shutdown(signal = "manual"): Promise<void> {
+    const logger = getLogger();
+    logger.info(`Immortal.js Runtime shutting down (signal: ${signal})`);
+
+    this._healthMonitor?.stop();
+    this._memoryLeakGuard?.stop();
+
+    if (this._gracefulShutdown) {
+      await this._gracefulShutdown.execute(signal);
+    }
+
+    for (const plugin of this.config.plugins) {
+      try {
+        await plugin.onShutdown?.(signal);
+      } catch (err) {
+        logger.error(`Plugin '${plugin.name}' shutdown hook failed`, {
+          error: (err as Error).message,
+        });
+      }
+    }
+
+    logger.info("Immortal.js Runtime shutdown complete");
+  }
+
+  addPlugin(plugin: ImmortalPlugin): void {
+    this.config.plugins.push(plugin);
+    if (this._initialized) {
+      const bus = getEventBus();
+      const logger = getLogger();
+      const ctx = {
+        config: this.config,
+        emit: (e: Parameters<typeof bus.emit>[1]) => bus.emit("error:captured", e),
+        getMetrics: () => this.getMetrics(),
+        logger,
+      };
+      plugin.onInit?.(ctx)?.catch(() => void 0);
+    }
+  }
+
+  private _emptyMetrics(): SystemMetrics {
+    return {
+      timestamp: Date.now(),
+      eventLoopLag: { p50: 0, p95: 0, p99: 0, max: 0 },
+      memory: {
+        heapUsedMb: 0, heapTotalMb: 0, externalMb: 0,
+        rssMb: 0, heapGrowthRate: 0, gcFrequency: 0,
+      },
+      cpu: { percentUser: 0, percentSystem: 0 },
+      handles: { active: 0 },
+      requests: { total: 0, active: 0, perSecond: 0, errorRate: 0 },
+      circuits: {},
+      bulkheads: {},
+      workers: [],
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FACTORY FUNCTION
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _instance: ImmortalRuntime | null = null;
+
+export async function createImmortal(config: ImmortalConfig = {}): Promise<ImmortalRuntime> {
+  if (_instance) {
+    getLogger().warn("createImmortal() called more than once — returning existing instance");
+    return _instance;
+  }
+  _instance = new ImmortalRuntime(config);
+  await _instance.initialize();
+  return _instance;
+}
+
+export function getImmortal(): ImmortalRuntime {
+  if (!_instance) {
+    throw new Error("Immortal.js runtime not initialized. Call createImmortal() first.");
+  }
+  return _instance;
+}
+
+export function _resetImmortal(): void {
+  _instance = null;
+}

package/packages/core/src/safe-zone/AsyncBoundary.ts

@@ -0,0 +1,114 @@
+/**
+ * @file AsyncBoundary.ts
+ * @description AsyncLocalStorage-based request context propagation
+ * Every operation within a request boundary automatically carries its requestId,
+ * timing data, and custom metadata — without passing it explicitly through every function call.
+ *
+ * This is the mechanism that allows Immortal.js to correlate errors, retries, and metrics
+ * back to the exact request that triggered them.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { RequestContext } from "../types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SINGLETON STORAGE
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const asyncLocalStorage = new AsyncLocalStorage<RequestContext>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ASYNC BOUNDARY CLASS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class AsyncBoundary {
+  /**
+   * Run a function within a request context boundary.
+   * All async operations within fn() can access the context via getContext()
+   */
+  static run<T>(context: RequestContext, fn: () => Promise<T>): Promise<T> {
+    return asyncLocalStorage.run(context, fn);
+  }
+
+  /**
+   * Get the current request context from anywhere in the call stack.
+   * Returns undefined if called outside a boundary (e.g., background tasks).
+   */
+  static getContext(): RequestContext | undefined {
+    return asyncLocalStorage.getStore();
+  }
+
+  /**
+   * Get the current requestId safely
+   */
+  static getRequestId(): string | undefined {
+    return asyncLocalStorage.getStore()?.requestId;
+  }
+
+  /**
+   * Enrich the current context with additional custom data.
+   * Mutates the existing context object in-place (safe because it's per-request).
+   */
+  static enrich(data: Partial<RequestContext>): void {
+    const ctx = asyncLocalStorage.getStore();
+    if (ctx) {
+      Object.assign(ctx, data);
+    }
+  }
+
+  /**
+   * Create a new child context (for parallel sub-operations within a request)
+   */
+  static fork<T>(
+    extraData: Partial<RequestContext>,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    const parent = asyncLocalStorage.getStore();
+    const child: RequestContext = {
+      ...(parent ?? { requestId: crypto.randomUUID(), startedAt: Date.now() }),
+      ...extraData,
+      custom: {
+        ...parent?.custom,
+        ...extraData.custom,
+      },
+    };
+    return asyncLocalStorage.run(child, fn);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONVENIENCE FUNCTION API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a function to execute within a new request context boundary
+ * Useful for background jobs, event handlers, queue processors
+ */
+export function asyncBoundary<Args extends unknown[], R>(
+  fn: (...args: Args) => Promise<R>,
+  contextFactory?: (...args: Args) => Partial<RequestContext>
+): (...args: Args) => Promise<R> {
+  return async (...args: Args): Promise<R> => {
+    const baseContext: RequestContext = {
+      requestId: crypto.randomUUID(),
+      startedAt: Date.now(),
+      ...(contextFactory?.(...args) ?? {}),
+    };
+
+    return AsyncBoundary.run(baseContext, () => fn(...args));
+  };
+}
+
+/**
+ * Get current request context — shorthand for AsyncBoundary.getContext()
+ */
+export function getRequestContext(): RequestContext | undefined {
+  return AsyncBoundary.getContext();
+}
+
+/**
+ * Get current requestId — shorthand
+ */
+export function getRequestId(): string {
+  return AsyncBoundary.getRequestId() ?? "unknown";
+}

package/packages/core/src/safe-zone/ErrorTrap.ts

@@ -0,0 +1,347 @@
+/**
+ * @file ErrorTrap.ts
+ * @description Process-level error interception
+ *
+ * Handles uncaughtException and unhandledRejection with engineering honesty:
+ * - Does NOT silently swallow errors and pretend nothing happened
+ * - DOES classify errors as operational vs programming errors
+ * - Operational errors → log + continue (if safe)
+ * - Programming errors → log + request graceful Worker restart via Supervisor
+ *
+ * Critical distinction: An uncaughtException may leave Node's internal state
+ * corrupted. The ONLY safe response to a true programming error is to restart
+ * the process. ErrorTrap ensures this happens in a controlled, supervised way.
+ */
+
+import type { ImmortalEventBus } from "../event-bus.js";
+import type { SerializedError } from "../types.js";
+import { ImmortalError } from "../types.js";
+import { getLogger } from "../logger.js";
+import { AsyncBoundary } from "./AsyncBoundary.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ErrorClassification = "operational" | "programming" | "unknown";
+
+export interface CapturedError {
+  error: unknown;
+  classification: ErrorClassification;
+  context?: ReturnType<typeof AsyncBoundary.getContext>;
+  timestamp: number;
+  processEventType: "uncaughtException" | "unhandledRejection" | "synchronous";
+  serialized: SerializedError;
+}
+
+type RestartCallback = () => void;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ERROR TRAP CLASS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ErrorTrap {
+  private readonly bus: ImmortalEventBus;
+  private installed = false;
+  private restartCallbacks: RestartCallback[] = [];
+  private capturedErrors: CapturedError[] = [];
+  private readonly maxErrorHistory = 200;
+
+  // Track if we're already in a crash-restart cycle to prevent infinite loops
+  private restartInProgress = false;
+
+  constructor(bus: ImmortalEventBus) {
+    this.bus = bus;
+  }
+
+  /**
+   * Install process-level error handlers.
+   * Call once during runtime initialization.
+   */
+  install(): void {
+    if (this.installed) return;
+
+    process.on("uncaughtException", this.handleUncaughtException.bind(this));
+    process.on("unhandledRejection", this.handleUnhandledRejection.bind(this));
+    process.on("uncaughtExceptionMonitor", this.handleMonitor.bind(this));
+
+    this.installed = true;
+    getLogger().info("ErrorTrap installed — process-level error handlers active");
+  }
+
+  /**
+   * Uninstall handlers (for testing only)
+   */
+  uninstall(): void {
+    process.off("uncaughtException", this.handleUncaughtException.bind(this));
+    process.off("unhandledRejection", this.handleUnhandledRejection.bind(this));
+    process.off("uncaughtExceptionMonitor", this.handleMonitor.bind(this));
+    this.installed = false;
+  }
+
+  /**
+   * Register a callback to be invoked when a programming error requires restart
+   */
+  onRestartRequired(callback: RestartCallback): void {
+    this.restartCallbacks.push(callback);
+  }
+
+  /**
+   * Manually capture an error (from SafeWrapper, middleware, etc.)
+   */
+  capture(
+    error: unknown,
+    context?: { requestId?: string; route?: string; [key: string]: unknown }
+  ): CapturedError {
+    const serialized = serializeError(error);
+    const classification = classifyError(error);
+    const requestCtx = AsyncBoundary.getContext();
+
+    const captured: CapturedError = {
+      error,
+      classification,
+      context: requestCtx,
+      timestamp: Date.now(),
+      processEventType: "synchronous",
+      serialized,
+    };
+
+    this.recordError(captured);
+
+    this.bus.emit("error:captured", {
+      requestId: context?.requestId ?? requestCtx?.requestId,
+      route: context?.route ?? requestCtx?.route,
+      error: serialized,
+      data: {
+        classification,
+        ...(context ?? {}),
+      },
+    });
+
+    return captured;
+  }
+
+  /**
+   * Get recent captured error history
+   */
+  getHistory(limit = 50): CapturedError[] {
+    return this.capturedErrors.slice(-limit);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // PRIVATE HANDLERS
+  // ─────────────────────────────────────────────────────────────────────────
+
+  private handleUncaughtException(error: Error, origin: string): void {
+    const logger = getLogger();
+    const serialized = serializeError(error);
+    const classification = classifyError(error);
+
+    const captured: CapturedError = {
+      error,
+      classification,
+      context: AsyncBoundary.getContext(),
+      timestamp: Date.now(),
+      processEventType: "uncaughtException",
+      serialized,
+    };
+
+    this.recordError(captured);
+
+    logger.error("UNCAUGHT EXCEPTION captured", {
+      origin,
+      classification,
+      ...serialized,
+    });
+
+    this.bus.emit("error:captured", {
+      error: serialized,
+      data: { classification, origin, processEvent: "uncaughtException" },
+    });
+
+    if (classification === "programming") {
+      logger.error(
+        "Programming error detected — requesting graceful restart to prevent corrupted state"
+      );
+      this.requestRestart();
+    }
+    // Operational errors: log and continue — state is not expected to be corrupted
+  }
+
+  private handleUnhandledRejection(reason: unknown, promise: Promise<unknown>): void {
+    const logger = getLogger();
+    const serialized = serializeError(reason);
+    const classification = classifyError(reason);
+
+    const captured: CapturedError = {
+      error: reason,
+      classification,
+      context: AsyncBoundary.getContext(),
+      timestamp: Date.now(),
+      processEventType: "unhandledRejection",
+      serialized,
+    };
+
+    this.recordError(captured);
+
+    logger.warn("UNHANDLED REJECTION captured", {
+      classification,
+      promise: String(promise),
+      ...serialized,
+    });
+
+    this.bus.emit("error:captured", {
+      error: serialized,
+      data: {
+        classification,
+        processEvent: "unhandledRejection",
+        promiseString: String(promise),
+      },
+    });
+
+    // Unhandled rejections are less likely to corrupt state than uncaughtException
+    // but programming errors still warrant a restart
+    if (classification === "programming") {
+      logger.error("Programming error in unhandled rejection — requesting graceful restart");
+      this.requestRestart();
+    }
+  }
+
+  private handleMonitor(error: Error, origin: string): void {
+    // uncaughtExceptionMonitor fires BEFORE uncaughtException handlers
+    // Use it for monitoring/telemetry only — don't interfere with error flow
+    getLogger().debug("uncaughtExceptionMonitor fired", {
+      errorName: error.name,
+      origin,
+    });
+  }
+
+  private requestRestart(): void {
+    if (this.restartInProgress) return;
+    this.restartInProgress = true;
+
+    this.bus.emit("error:escalated", {
+      data: { reason: "programming-error", pid: process.pid },
+    });
+
+    for (const callback of this.restartCallbacks) {
+      try {
+        callback();
+      } catch {
+        // Ignore errors in restart callbacks
+      }
+    }
+
+    // If no restart callbacks registered (standalone mode), force exit
+    // so the process manager (PM2, Kubernetes, systemd) restarts us
+    if (this.restartCallbacks.length === 0) {
+      getLogger().error("No restart callbacks — forcing process exit for clean restart");
+      setTimeout(() => process.exit(1), 100).unref();
+    }
+  }
+
+  private recordError(captured: CapturedError): void {
+    this.capturedErrors.push(captured);
+    if (this.capturedErrors.length > this.maxErrorHistory) {
+      this.capturedErrors.shift();
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Classify an error as operational (expected, safe to continue) or
+ * programming (unexpected, may have corrupted state)
+ *
+ * Engineering principle: When in doubt, classify as programming error
+ * (safer to restart than to continue in potentially corrupted state)
+ */
+export function classifyError(error: unknown): ErrorClassification {
+  if (error instanceof ImmortalError) {
+    return error.isOperational ? "operational" : "programming";
+  }
+
+  if (!(error instanceof Error)) return "unknown";
+
+  // Node.js system errors
+  const code = (error as NodeJS.ErrnoException).code;
+  const systemErrorCodes = [
+    "ENOENT", "EACCES", "EADDRINUSE", "ECONNREFUSED", "ECONNRESET",
+    "ETIMEDOUT", "EPIPE", "EHOSTUNREACH", "ENETUNREACH", "ENOMEM",
+  ];
+  if (code && systemErrorCodes.includes(code)) return "operational";
+
+  // HTTP/network operational errors (by status code)
+  const statusCode = (error as { statusCode?: number; status?: number }).statusCode
+    ?? (error as { statusCode?: number; status?: number }).status;
+  if (statusCode && statusCode < 500) return "operational";
+
+  // Explicit operational flag
+  if ((error as { isOperational?: boolean }).isOperational === true) return "operational";
+  if ((error as { isOperational?: boolean }).isOperational === false) return "programming";
+
+  // Well-known programming error types
+  if (
+    error instanceof TypeError ||
+    error instanceof RangeError ||
+    error instanceof SyntaxError ||
+    error instanceof ReferenceError
+  ) {
+    return "programming";
+  }
+
+  // URIError, EvalError, AssertionError — programming errors
+  if (
+    error.name === "AssertionError" ||
+    error.name === "URIError" ||
+    error.name === "EvalError"
+  ) {
+    return "programming";
+  }
+
+  // Default: treat as operational (conservative — avoid unnecessary restarts)
+  return "operational";
+}
+
+/**
+ * Serialize any error into a safe, loggable, JSON-compatible structure
+ */
+export function serializeError(error: unknown): SerializedError {
+  if (error instanceof Error) {
+    const ext = error as Error & {
+      code?: string;
+      statusCode?: number;
+      status?: number;
+      isOperational?: boolean;
+      context?: Record<string, unknown>;
+    };
+    const result: SerializedError = {
+      name: error.name,
+      message: error.message,
+    };
+    const stack = process.env["NODE_ENV"] !== "production" ? error.stack : undefined;
+    if (stack !== undefined) result.stack = stack;
+    if (ext.code !== undefined) result.code = ext.code;
+    const statusCode = ext.statusCode ?? ext.status;
+    if (statusCode !== undefined) result.statusCode = statusCode;
+    if (ext.isOperational !== undefined) result.isOperational = ext.isOperational;
+    if (ext.context !== undefined) result.context = ext.context;
+    return result;
+  }
+
+  if (typeof error === "string") {
+    return { name: "Error", message: error };
+  }
+
+  if (typeof error === "object" && error !== null) {
+    return {
+      name: "UnknownError",
+      message: JSON.stringify(error),
+    };
+  }
+
+  return { name: "UnknownError", message: String(error) };
+}