immortal-js 1.0.0

package/packages/core/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * @file index.ts
+ * @description Immortal.js Core — Public API Entry Point
+ *
+ * "We don't promise you won't fall — we guarantee you stand back up
+ *  before anyone notices you fell."
+ *
+ * @module @immortal/core
+ * @version 1.0.0
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPE EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export type {
+  ImmortalConfig,
+  SafeZoneConfig,
+  RetryConfig,
+  CircuitBreakerConfig,
+  BulkheadConfig,
+  SupervisorConfig,
+  HealthMonitorConfig,
+  MemoryGuardConfig,
+  GracefulShutdownConfig,
+  DashboardConfig,
+  ChaosConfig,
+  LoggerConfig,
+  ImmortalPlugin,
+  PluginContext,
+  FallbackGenerator,
+  RequestContext,
+  ShutdownHook,
+  LogTransport,
+  ImmortalEvent,
+  ImmortalEventType,
+  SystemMetrics,
+  CircuitBreakerStatus,
+  BulkheadStatus,
+  WorkerStatus,
+  SerializedError,
+  Priority,
+  PriorityTask,
+  RestartStrategy,
+} from "./types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ERROR CLASS EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export {
+  ImmortalError,
+  BulkheadRejectedError,
+  CircuitOpenError,
+  RetryExhaustedError,
+  WorkerEscalatedError,
+  TimeoutError,
+} from "./types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONFIG EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export {
+  mergeWithDefaults,
+  IMMORTAL_DEFAULTS,
+  DEFAULT_RETRY,
+  DEFAULT_CIRCUIT_BREAKER,
+  DEFAULT_BULKHEAD,
+  DEFAULT_SUPERVISOR,
+  DEFAULT_HEALTH_MONITOR,
+  DEFAULT_MEMORY_GUARD,
+  DEFAULT_GRACEFUL_SHUTDOWN,
+} from "./config/defaults.js";
+
+export { validateConfig } from "./config/schema.js";
+export type { ValidationResult } from "./config/schema.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INFRASTRUCTURE EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { createLogger, getLogger } from "./logger.js";
+export { getEventBus, resetEventBus, ImmortalEventBus } from "./event-bus.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SAFE ZONE EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { wrapHandler, createSafeZone } from "./safe-zone/SafeWrapper.js";
+export { ErrorTrap } from "./safe-zone/ErrorTrap.js";
+export { AsyncBoundary, asyncBoundary } from "./safe-zone/AsyncBoundary.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RECOVERY EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { withRetry, RetryEngine } from "./recovery/RetryEngine.js";
+export { CircuitBreaker } from "./recovery/CircuitBreaker.js";
+export { FallbackCache } from "./recovery/FallbackCache.js";
+export { withTimeout } from "./recovery/Timeout.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ISOLATION EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { BulkheadPool } from "./isolation/BulkheadPool.js";
+export { WorkerSandbox } from "./isolation/WorkerSandbox.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SUPERVISION EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { Supervisor } from "./supervision/Supervisor.js";
+export { ClusterManager } from "./supervision/ClusterManager.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MONITORING EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { HealthMonitor } from "./monitoring/HealthMonitor.js";
+export { MemoryLeakGuard } from "./monitoring/MemoryLeakGuard.js";
+export { MetricsCollector } from "./monitoring/MetricsCollector.js";
+export { DiagnosticsChannel } from "./monitoring/DiagnosticsChannel.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// LIFECYCLE EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { GracefulShutdown } from "./lifecycle/GracefulShutdown.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CHAOS ENGINE EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { ChaosEngine } from "./chaos/ChaosEngine.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PLUGIN EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export {
+  ConsoleLogPlugin,
+  RequestTracingPlugin,
+  createAnomalyDetectionPlugin,
+  createSlackAlertPlugin,
+  BUILTIN_PLUGINS,
+} from "./plugins/BuiltinPlugins.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ADDITIONAL RECOVERY EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { CircuitBreakerRegistry } from "./recovery/CircuitBreaker.js";
+export { RouteFallbackCache } from "./recovery/FallbackCache.js";
+export { calculateBackoff } from "./recovery/RetryEngine.js";
+export { withSimpleTimeout } from "./recovery/Timeout.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ADDITIONAL ISOLATION EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { BulkheadRegistry } from "./isolation/BulkheadPool.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ADDITIONAL SUPERVISION EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { computeRestartDecision } from "./supervision/RestartStrategy.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITY EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+export { classifyError, serializeError } from "./safe-zone/ErrorTrap.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL RUNTIME — Main orchestrator class
+// ─────────────────────────────────────────────────────────────────────────────
+export { ImmortalRuntime, createImmortal, getImmortal } from "./runtime.js";

package/packages/core/src/isolation/BulkheadPool.ts

@@ -0,0 +1,279 @@
+/**
+ * @file BulkheadPool.ts
+ * @description Bulkhead isolation — prevents cascade failure between services
+ *
+ * The bulkhead pattern (named after ship compartments) ensures that:
+ * - Each external service gets its own resource pool
+ * - Pool saturation for one service CANNOT affect other services
+ * - Priority queuing allows critical operations to preempt lower-priority ones
+ * - Fail-fast rejection prevents queue buildup from degrading system response time
+ *
+ * Without bulkheads: a slow payment API fills the shared thread pool → search, orders,
+ * notifications all slow down → entire system collapses
+ * With bulkheads: payment pool fills → payments queue/reject → everything else runs fine
+ */
+
+import type { BulkheadConfig, BulkheadStatus, Priority, PriorityTask } from "../types.js";
+import { BulkheadRejectedError } from "../types.js";
+import { DEFAULT_BULKHEAD } from "../config/defaults.js";
+import { getEventBus } from "../event-bus.js";
+import { getLogger } from "../logger.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PRIORITY QUEUE
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PRIORITY_ORDER: Priority[] = ["critical", "high", "medium", "low"];
+
+interface QueuedItem<T> {
+  task: () => Promise<T>;
+  priority: Priority;
+  enqueueTime: number;
+  resolve: (value: T) => void;
+  reject: (reason: unknown) => void;
+  timeoutId?: ReturnType<typeof setTimeout>;
+}
+
+class PriorityQueue<T> {
+  private buckets: Map<Priority, QueuedItem<T>[]>;
+
+  constructor() {
+    this.buckets = new Map();
+    for (const p of PRIORITY_ORDER) {
+      this.buckets.set(p, []);
+    }
+  }
+
+  enqueue(item: QueuedItem<T>): void {
+    this.buckets.get(item.priority)!.push(item);
+  }
+
+  dequeue(): QueuedItem<T> | undefined {
+    for (const priority of PRIORITY_ORDER) {
+      const bucket = this.buckets.get(priority)!;
+      if (bucket.length > 0) {
+        return bucket.shift();
+      }
+    }
+    return undefined;
+  }
+
+  get size(): number {
+    let total = 0;
+    for (const bucket of this.buckets.values()) {
+      total += bucket.length;
+    }
+    return total;
+  }
+
+  clear(): void {
+    for (const p of PRIORITY_ORDER) {
+      this.buckets.set(p, []);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BULKHEAD POOL
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class BulkheadPool {
+  private active = 0;
+  private readonly queue: PriorityQueue<unknown>;
+  private readonly config: Required<BulkheadConfig>;
+  private totalRejected = 0;
+  private totalExecuted = 0;
+
+  constructor(
+    public readonly name: string,
+    config: BulkheadConfig = {}
+  ) {
+    this.config = { ...DEFAULT_BULKHEAD, ...config };
+    this.queue = new PriorityQueue<unknown>();
+  }
+
+  /**
+   * Execute a task through the bulkhead pool.
+   *
+   * If the pool has capacity → execute immediately
+   * If pool is full but queue has space → queue with optional priority
+   * If queue is also full → fail fast with BulkheadRejectedError
+   *
+   * @param task - Async task to execute
+   * @param priority - Task priority (default: 'medium')
+   * @param timeoutMs - Optional per-task timeout override
+   */
+  async run<T>(
+    task: () => Promise<T>,
+    priority: Priority = "medium",
+    timeoutMs?: number
+  ): Promise<T> {
+    const bus = getEventBus();
+
+    // Pool has capacity → execute immediately
+    if (this.active < this.config.maxConcurrent) {
+      return this.executeTask(task);
+    }
+
+    // Pool full → try to queue
+    if (this.queue.size >= this.config.maxQueueSize) {
+      this.totalRejected++;
+
+      bus.emit("bulkhead:rejected", {
+        service: this.name,
+        data: {
+          active: this.active,
+          queued: this.queue.size,
+          maxConcurrent: this.config.maxConcurrent,
+          maxQueueSize: this.config.maxQueueSize,
+          priority,
+        },
+      });
+
+      throw new BulkheadRejectedError(this.name, "saturated");
+    }
+
+    // Queue the task
+    const effectiveTimeout = timeoutMs ?? this.config.queueTimeoutMs;
+
+    bus.emit("bulkhead:queued", {
+      service: this.name,
+      data: { queued: this.queue.size + 1, priority },
+    });
+
+    return new Promise<T>((resolve, reject) => {
+      const item: QueuedItem<T> = {
+        task,
+        priority,
+        enqueueTime: Date.now(),
+        resolve,
+        reject,
+      };
+
+      // Queue timeout
+      item.timeoutId = setTimeout(() => {
+        // Remove from queue by rejecting
+        item.reject(new BulkheadRejectedError(this.name, "timeout"));
+        bus.emit("bulkhead:timeout", {
+          service: this.name,
+          data: { queuedMs: effectiveTimeout, priority },
+        });
+      }, effectiveTimeout);
+
+      this.queue.enqueue(item as QueuedItem<unknown>);
+    });
+  }
+
+  /**
+   * Priority-aware run — convenience wrapper
+   */
+  async runWithPriority<T>(priorityTask: PriorityTask<T>): Promise<T> {
+    return this.run(
+      priorityTask.task,
+      priorityTask.priority,
+      priorityTask.timeoutMs
+    );
+  }
+
+  /**
+   * Get current pool status for monitoring
+   */
+  getStatus(): BulkheadStatus {
+    return {
+      name: this.name,
+      active: this.active,
+      queued: this.queue.size,
+      maxConcurrent: this.config.maxConcurrent,
+      maxQueueSize: this.config.maxQueueSize,
+      rejected: this.totalRejected,
+      totalExecuted: this.totalExecuted,
+    };
+  }
+
+  /**
+   * Drain all queued tasks (for graceful shutdown)
+   */
+  drain(): void {
+    let item = this.queue.dequeue() as QueuedItem<unknown> | undefined;
+    while (item) {
+      if (item.timeoutId) clearTimeout(item.timeoutId);
+      item.reject(new BulkheadRejectedError(this.name, "saturated"));
+      item = this.queue.dequeue() as QueuedItem<unknown> | undefined;
+    }
+  }
+
+  private async executeTask<T>(task: () => Promise<T>): Promise<T> {
+    this.active++;
+    try {
+      const result = await task();
+      this.totalExecuted++;
+      return result;
+    } finally {
+      this.active--;
+      this.processQueue();
+    }
+  }
+
+  private processQueue(): void {
+    if (this.queue.size === 0) return;
+    if (this.active >= this.config.maxConcurrent) return;
+
+    const item = this.queue.dequeue() as QueuedItem<unknown> | undefined;
+    if (!item) return;
+
+    if (item.timeoutId) clearTimeout(item.timeoutId);
+
+    const waitMs = Date.now() - item.enqueueTime;
+    getLogger().debug(`Bulkhead '${this.name}': executing queued task (waited ${waitMs}ms)`);
+
+    this.executeTask(item.task)
+      .then((result) => (item.resolve as (v: unknown) => void)(result))
+      .catch((err) => item.reject(err));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BULKHEAD REGISTRY
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class BulkheadRegistry {
+  private pools = new Map<string, BulkheadPool>();
+  private readonly defaultConfig: BulkheadConfig;
+
+  constructor(defaultConfig: BulkheadConfig = {}) {
+    this.defaultConfig = defaultConfig;
+  }
+
+  /**
+   * Get or create a named bulkhead pool
+   */
+  get(name: string, config?: BulkheadConfig): BulkheadPool {
+    if (!this.pools.has(name)) {
+      this.pools.set(
+        name,
+        new BulkheadPool(name, { ...this.defaultConfig, ...config })
+      );
+    }
+    return this.pools.get(name)!;
+  }
+
+  /**
+   * Get statuses of all registered pools
+   */
+  getAllStatuses(): Record<string, BulkheadStatus> {
+    const result: Record<string, BulkheadStatus> = {};
+    for (const [name, pool] of this.pools) {
+      result[name] = pool.getStatus();
+    }
+    return result;
+  }
+
+  /**
+   * Drain all pools (graceful shutdown)
+   */
+  drainAll(): void {
+    for (const pool of this.pools.values()) {
+      pool.drain();
+    }
+  }
+}