immortal-js 1.0.0

package/packages/core/src/config/defaults.ts

@@ -0,0 +1,200 @@
+/**
+ * @file defaults.ts
+ * @description Sensible production-ready defaults for all Immortal.js config options
+ * All defaults are conservative — they protect without being overly aggressive
+ */
+
+import type {
+  ImmortalConfig,
+  RetryConfig,
+  CircuitBreakerConfig,
+  BulkheadConfig,
+  SupervisorConfig,
+  HealthMonitorConfig,
+  MemoryGuardConfig,
+  GracefulShutdownConfig,
+  DashboardConfig,
+  SafeZoneConfig,
+  LoggerConfig,
+} from "../types.js";
+
+export const DEFAULT_SAFE_ZONE: Required<SafeZoneConfig> = {
+  autoWrap: true,
+  defaultFallback: undefined as never,
+  exposeErrors: process.env["NODE_ENV"] !== "production",
+  sanitizeFields: ["password", "token", "secret", "authorization", "cookie", "creditCard", "ssn"],
+};
+
+export const DEFAULT_RETRY: Required<RetryConfig> = {
+  maxAttempts: 3,
+  baseDelayMs: 200,
+  maxDelayMs: 10_000,
+  jitterFactor: 0.3,
+  isRetryable: defaultIsRetryable,
+  retryBudget: 50, // max 50 retries per second across all operations
+};
+
+export const DEFAULT_CIRCUIT_BREAKER: Required<CircuitBreakerConfig> = {
+  threshold: 5,
+  cooldownMs: 15_000,
+  slidingWindowSize: 100,
+  minimumRequests: 10,
+  failureRateThreshold: 50, // 50% failure rate opens circuit
+};
+
+export const DEFAULT_BULKHEAD: Required<BulkheadConfig> = {
+  maxConcurrent: 10,
+  maxQueueSize: 50,
+  queueTimeoutMs: 30_000,
+  enablePriority: false,
+};
+
+export const DEFAULT_SUPERVISOR: Required<SupervisorConfig> = {
+  strategy: "one_for_one",
+  maxRestartsInWindow: 5,
+  windowMs: 60_000,
+  baseRestartDelayMs: 100,
+  clusterMode: false,
+  clusterWorkers: 1,
+};
+
+export const DEFAULT_HEALTH_MONITOR: Required<HealthMonitorConfig> = {
+  intervalMs: 5_000,
+  eventLoopLagMs: 100,
+  criticalLagMs: 500,
+  cpuWarningPercent: 80,
+  cpuCriticalPercent: 95,
+};
+
+export const DEFAULT_MEMORY_GUARD: Required<MemoryGuardConfig> = {
+  checkIntervalMs: 10_000,
+  warningThresholdMb: 1024,
+  restartThresholdMb: 1500,
+  growthWindowCount: 3,
+  enableObjectTracking: false,
+  adaptiveThresholds: true,
+};
+
+export const DEFAULT_GRACEFUL_SHUTDOWN: Required<GracefulShutdownConfig> = {
+  timeoutMs: 20_000,
+  signals: ["SIGTERM", "SIGINT"],
+  onShutdown: [],
+};
+
+export const DEFAULT_DASHBOARD: Required<DashboardConfig> = {
+  enabled: true,
+  port: 9999,
+  path: "/__immortal",
+  enableWebSocket: true,
+  enableSSE: true,
+  enableOTLP: false,
+  otlpEndpoint: "",
+  enablePrometheus: true,
+  auth: undefined as never,
+};
+
+export const DEFAULT_LOGGER: Required<LoggerConfig> = {
+  level: process.env["NODE_ENV"] === "production" ? "warn" : "info",
+  transport: undefined as never,
+  redact: ["password", "token", "secret", "authorization"],
+};
+
+export const IMMORTAL_DEFAULTS: Required<ImmortalConfig> = {
+  safeZone: DEFAULT_SAFE_ZONE,
+  retry: DEFAULT_RETRY,
+  circuitBreaker: DEFAULT_CIRCUIT_BREAKER,
+  bulkhead: { default: DEFAULT_BULKHEAD },
+  supervisor: DEFAULT_SUPERVISOR,
+  healthMonitor: DEFAULT_HEALTH_MONITOR,
+  memoryGuard: DEFAULT_MEMORY_GUARD,
+  gracefulShutdown: DEFAULT_GRACEFUL_SHUTDOWN,
+  dashboard: DEFAULT_DASHBOARD,
+  plugins: [],
+  chaos: { enabled: false },
+  logger: DEFAULT_LOGGER,
+};
+
+/**
+ * Default retryable error classifier
+ * Only retries on transient infrastructure errors, never on business logic errors
+ */
+function defaultIsRetryable(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+
+  const msg = error.message.toLowerCase();
+  const code = (error as NodeJS.ErrnoException).code ?? "";
+
+  // Network/connection errors — always retryable
+  const networkCodes = [
+    "ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT",
+    "EPIPE", "EHOSTUNREACH", "ENETUNREACH", "EAI_AGAIN",
+  ];
+  if (networkCodes.includes(code)) return true;
+
+  // HTTP status codes via error properties
+  const statusCode = (error as { statusCode?: number; status?: number }).statusCode
+    ?? (error as { statusCode?: number; status?: number }).status;
+
+  if (statusCode) {
+    // 429 Too Many Requests — retryable with backoff
+    if (statusCode === 429) return true;
+    // 503 Service Unavailable — retryable
+    if (statusCode === 503) return true;
+    // 504 Gateway Timeout — retryable
+    if (statusCode === 504) return true;
+    // 408 Request Timeout — retryable
+    if (statusCode === 408) return true;
+    // 4xx (except above) — NOT retryable (client errors)
+    if (statusCode >= 400 && statusCode < 500) return false;
+    // 500, 502 — retryable (server errors)
+    if (statusCode === 500 || statusCode === 502) return true;
+    // Other 5xx — retryable
+    if (statusCode >= 500) return true;
+    // 2xx, 3xx — not an error, don't retry
+    return false;
+  }
+
+  // Timeout errors by message pattern
+  if (msg.includes("timeout") || msg.includes("timed out")) return true;
+  if (msg.includes("connection reset") || msg.includes("connection refused")) return true;
+  if (msg.includes("socket hang up")) return true;
+
+  // Default: don't retry unknown errors
+  return false;
+}
+
+/**
+ * Deep merge config with defaults
+ */
+export function mergeWithDefaults(userConfig: ImmortalConfig): Required<ImmortalConfig> {
+  return {
+    safeZone: { ...DEFAULT_SAFE_ZONE, ...userConfig.safeZone },
+    retry: { ...DEFAULT_RETRY, ...userConfig.retry },
+    circuitBreaker: { ...DEFAULT_CIRCUIT_BREAKER, ...userConfig.circuitBreaker },
+    bulkhead: {
+      default: DEFAULT_BULKHEAD,
+      ...Object.fromEntries(
+        Object.entries(userConfig.bulkhead ?? {}).map(([k, v]) => [
+          k,
+          { ...DEFAULT_BULKHEAD, ...v },
+        ])
+      ),
+    },
+    supervisor: { ...DEFAULT_SUPERVISOR, ...userConfig.supervisor },
+    healthMonitor: { ...DEFAULT_HEALTH_MONITOR, ...userConfig.healthMonitor },
+    memoryGuard: { ...DEFAULT_MEMORY_GUARD, ...userConfig.memoryGuard },
+    gracefulShutdown: {
+      ...DEFAULT_GRACEFUL_SHUTDOWN,
+      ...userConfig.gracefulShutdown,
+      signals: userConfig.gracefulShutdown?.signals ?? DEFAULT_GRACEFUL_SHUTDOWN.signals,
+      onShutdown: [
+        ...(DEFAULT_GRACEFUL_SHUTDOWN.onShutdown ?? []),
+        ...(userConfig.gracefulShutdown?.onShutdown ?? []),
+      ],
+    },
+    dashboard: { ...DEFAULT_DASHBOARD, ...userConfig.dashboard },
+    plugins: userConfig.plugins ?? [],
+    chaos: { enabled: false, ...userConfig.chaos },
+    logger: { ...DEFAULT_LOGGER, ...userConfig.logger },
+  };
+}

package/packages/core/src/config/schema.ts

@@ -0,0 +1,199 @@
+/**
+ * @file schema.ts
+ * @description Zod validation schemas for all Immortal.js configuration objects
+ * Provides runtime validation with descriptive error messages
+ */
+
+import { z } from "zod";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PRIMITIVE VALIDATORS
+// ─────────────────────────────────────────────────────────────────────────────
+
+const positiveInt = (name: string) =>
+  z.number().int().positive({ message: `${name} must be a positive integer` });
+
+const positiveMs = (name: string) =>
+  z.number().positive({ message: `${name} must be a positive number (milliseconds)` });
+
+const probability = (name: string) =>
+  z.number().min(0).max(1, { message: `${name} must be between 0 and 1` });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SECTION SCHEMAS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const SafeZoneConfigSchema = z.object({
+  autoWrap: z.boolean().optional(),
+  defaultFallback: z.function().optional(),
+  exposeErrors: z.boolean().optional(),
+  sanitizeFields: z.array(z.string()).optional(),
+}).strict();
+
+export const RetryConfigSchema = z.object({
+  maxAttempts: positiveInt("maxAttempts").max(20).optional(),
+  baseDelayMs: positiveMs("baseDelayMs").optional(),
+  maxDelayMs: positiveMs("maxDelayMs").optional(),
+  jitterFactor: probability("jitterFactor").optional(),
+  isRetryable: z.function().optional(),
+  retryBudget: positiveInt("retryBudget").optional(),
+}).strict().refine(
+  (d) => !d.baseDelayMs || !d.maxDelayMs || d.maxDelayMs >= d.baseDelayMs,
+  { message: "maxDelayMs must be >= baseDelayMs", path: ["maxDelayMs"] }
+);
+
+export const CircuitBreakerConfigSchema = z.object({
+  threshold: positiveInt("threshold").optional(),
+  cooldownMs: positiveMs("cooldownMs").optional(),
+  slidingWindowSize: positiveInt("slidingWindowSize").min(10).optional(),
+  minimumRequests: positiveInt("minimumRequests").optional(),
+  failureRateThreshold: z.number().min(1).max(100).optional(),
+}).strict();
+
+export const BulkheadConfigSchema = z.object({
+  maxConcurrent: positiveInt("maxConcurrent").optional(),
+  maxQueueSize: positiveInt("maxQueueSize").optional(),
+  queueTimeoutMs: positiveMs("queueTimeoutMs").optional(),
+  enablePriority: z.boolean().optional(),
+}).strict();
+
+export const SupervisorConfigSchema = z.object({
+  strategy: z.enum(["one_for_one", "one_for_all", "rest_for_one"]).optional(),
+  maxRestartsInWindow: positiveInt("maxRestartsInWindow").optional(),
+  windowMs: positiveMs("windowMs").optional(),
+  baseRestartDelayMs: positiveMs("baseRestartDelayMs").optional(),
+  clusterMode: z.boolean().optional(),
+  clusterWorkers: positiveInt("clusterWorkers").max(128).optional(),
+}).strict();
+
+export const HealthMonitorConfigSchema = z.object({
+  intervalMs: positiveMs("intervalMs").min(100).optional(),
+  eventLoopLagMs: positiveMs("eventLoopLagMs").optional(),
+  criticalLagMs: positiveMs("criticalLagMs").optional(),
+  cpuWarningPercent: z.number().min(1).max(100).optional(),
+  cpuCriticalPercent: z.number().min(1).max(100).optional(),
+}).strict().refine(
+  (d) => !d.eventLoopLagMs || !d.criticalLagMs || d.criticalLagMs > d.eventLoopLagMs,
+  { message: "criticalLagMs must be > eventLoopLagMs", path: ["criticalLagMs"] }
+);
+
+export const MemoryGuardConfigSchema = z.object({
+  checkIntervalMs: positiveMs("checkIntervalMs").min(1000).optional(),
+  warningThresholdMb: positiveInt("warningThresholdMb").optional(),
+  restartThresholdMb: positiveInt("restartThresholdMb").optional(),
+  growthWindowCount: positiveInt("growthWindowCount").min(2).max(20).optional(),
+  enableObjectTracking: z.boolean().optional(),
+  adaptiveThresholds: z.boolean().optional(),
+}).strict().refine(
+  (d) => !d.warningThresholdMb || !d.restartThresholdMb || d.restartThresholdMb > d.warningThresholdMb,
+  { message: "restartThresholdMb must be > warningThresholdMb", path: ["restartThresholdMb"] }
+);
+
+export const GracefulShutdownConfigSchema = z.object({
+  timeoutMs: positiveMs("timeoutMs").max(120_000).optional(),
+  signals: z.array(z.string()).optional(),
+  onShutdown: z.array(z.function()).optional(),
+}).strict();
+
+export const DashboardConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  port: z.number().int().min(1024).max(65535).optional(),
+  path: z.string().startsWith("/").optional(),
+  enableWebSocket: z.boolean().optional(),
+  enableSSE: z.boolean().optional(),
+  enableOTLP: z.boolean().optional(),
+  otlpEndpoint: z.string().url().optional().or(z.literal("")),
+  enablePrometheus: z.boolean().optional(),
+  auth: z.object({ username: z.string().min(1), password: z.string().min(8) }).optional(),
+}).strict();
+
+export const ChaosConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  latencyProbability: probability("latencyProbability").optional(),
+  latencyRange: z.tuple([z.number().min(0), z.number().max(60_000)]).optional(),
+  errorProbability: probability("errorProbability").optional(),
+  workerKillProbability: probability("workerKillProbability").optional(),
+  memoryPressureMb: positiveInt("memoryPressureMb").max(2048).optional(),
+  targetRoutes: z.array(z.string()).optional(),
+}).strict();
+
+export const LoggerConfigSchema = z.object({
+  level: z.enum(["debug", "info", "warn", "error", "silent"]).optional(),
+  transport: z.any().optional(),
+  redact: z.array(z.string()).optional(),
+}).strict();
+
+export const ImmortalConfigSchema = z.object({
+  safeZone: SafeZoneConfigSchema.optional(),
+  retry: RetryConfigSchema.optional(),
+  circuitBreaker: CircuitBreakerConfigSchema.optional(),
+  bulkhead: z.record(z.string(), BulkheadConfigSchema).optional(),
+  supervisor: SupervisorConfigSchema.optional(),
+  healthMonitor: HealthMonitorConfigSchema.optional(),
+  memoryGuard: MemoryGuardConfigSchema.optional(),
+  gracefulShutdown: GracefulShutdownConfigSchema.optional(),
+  dashboard: DashboardConfigSchema.optional(),
+  plugins: z.array(z.any()).optional(),
+  chaos: ChaosConfigSchema.optional(),
+  logger: LoggerConfigSchema.optional(),
+}).strict();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// VALIDATION FUNCTION
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export function validateConfig(config: unknown): ValidationResult {
+  const result = ImmortalConfigSchema.safeParse(config);
+  const warnings: string[] = [];
+
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map(
+        (i) => `[${i.path.join(".")}] ${i.message}`
+      ),
+      warnings,
+    };
+  }
+
+  // Additional semantic warnings
+  const cfg = result.data;
+
+  if (cfg.chaos?.enabled && process.env["NODE_ENV"] === "production") {
+    warnings.push(
+      "⚠️  Chaos mode is enabled in production! This will cause intentional failures."
+    );
+  }
+
+  if (cfg.safeZone?.exposeErrors && process.env["NODE_ENV"] === "production") {
+    warnings.push(
+      "⚠️  exposeErrors is true in production — internal error details will be exposed to clients."
+    );
+  }
+
+  if (cfg.retry?.maxAttempts && cfg.retry.maxAttempts > 10) {
+    warnings.push(
+      `⚠️  retry.maxAttempts=${cfg.retry.maxAttempts} is very high — consider using retryBudget instead.`
+    );
+  }
+
+  if (cfg.supervisor?.clusterMode && cfg.supervisor?.clusterWorkers === 1) {
+    warnings.push(
+      "ℹ️  clusterMode=true with clusterWorkers=1 has no redundancy benefit."
+    );
+  }
+
+  if (cfg.dashboard?.enabled && !cfg.dashboard?.auth && process.env["NODE_ENV"] === "production") {
+    warnings.push(
+      "⚠️  Dashboard is enabled without authentication in production — expose with caution."
+    );
+  }
+
+  return { valid: true, errors: [], warnings };
+}

package/packages/core/src/event-bus.ts

@@ -0,0 +1,168 @@
+/**
+ * @file event-bus.ts
+ * @description Immortal.js internal event bus
+ * Central nervous system connecting all layers (Monitoring → Supervisor, etc.)
+ * Uses Node.js EventEmitter extended with typed events
+ */
+
+import { EventEmitter } from "node:events";
+import type { ImmortalEvent, ImmortalEventType } from "./types.js";
+import { getLogger } from "./logger.js";
+
+type EventListener = (event: ImmortalEvent) => void;
+
+export class ImmortalEventBus extends EventEmitter {
+  private history: ImmortalEvent[] = [];
+  private readonly maxHistory: number;
+
+  constructor(maxHistory = 1000) {
+    super();
+    this.maxHistory = maxHistory;
+    this.setMaxListeners(100); // Many layers listen to events
+  }
+
+  /**
+   * Emit a typed Immortal event — logs it, stores in history, and notifies listeners
+   */
+  override emit(eventType: ImmortalEventType, data?: Omit<ImmortalEvent, "type" | "timestamp">): boolean;
+  override emit(event: string | symbol, ...args: unknown[]): boolean;
+  override emit(eventOrType: string | symbol | ImmortalEventType, ...args: unknown[]): boolean {
+    // Handle typed Immortal events
+    if (typeof eventOrType === "string" && isImmortalEventType(eventOrType)) {
+      const [data] = args as [Omit<ImmortalEvent, "type" | "timestamp"> | undefined];
+      const event: ImmortalEvent = {
+        type: eventOrType,
+        timestamp: Date.now(),
+        ...data,
+      };
+
+      // Store in history (circular buffer)
+      this.history.push(event);
+      if (this.history.length > this.maxHistory) {
+        this.history.shift();
+      }
+
+      // Log significant events
+      const logger = getLogger();
+      if (event.type.includes("critical") || event.type.includes("escalated") || event.type.includes("crash")) {
+        logger.error(`Event: ${event.type}`, event.data as Record<string, unknown>);
+      } else if (event.type.includes("warning") || event.type.includes("opened") || event.type.includes("rejected")) {
+        logger.warn(`Event: ${event.type}`, event.data as Record<string, unknown>);
+      } else {
+        logger.debug(`Event: ${event.type}`, event.data as Record<string, unknown>);
+      }
+
+      // Emit to listeners on specific type channel
+      super.emit(eventOrType, event);
+      // Also emit to wildcard listeners
+      super.emit("*", event);
+      return true;
+    }
+
+    // Fall through to standard EventEmitter for internal events
+    return super.emit(eventOrType, ...args);
+  }
+
+  /**
+   * Subscribe to a specific event type
+   */
+  override on(eventType: ImmortalEventType, listener: (event: ImmortalEvent) => void): this;
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  override on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override on(eventOrType: string | symbol, listener: ((...args: unknown[]) => void) | ((event: ImmortalEvent) => void)): this {
+    return super.on(eventOrType, listener as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Subscribe to ALL Immortal events (wildcard)
+   */
+  onAny(listener: EventListener): this {
+    return super.on("*", listener);
+  }
+
+  /**
+   * Get recent event history
+   */
+  getHistory(
+    filter?: { type?: ImmortalEventType; since?: number; limit?: number }
+  ): ImmortalEvent[] {
+    let result = [...this.history];
+
+    if (filter?.type) {
+      result = result.filter((e) => e.type === filter.type);
+    }
+
+    if (filter?.since !== undefined) {
+      const since = filter.since;
+      result = result.filter((e) => e.timestamp >= since);
+    }
+
+    if (filter?.limit !== undefined) {
+      result = result.slice(-filter.limit);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get event counts by type for the last N milliseconds
+   */
+  getEventCounts(windowMs = 60_000): Record<string, number> {
+    const since = Date.now() - windowMs;
+    const counts: Record<string, number> = {};
+
+    for (const event of this.history) {
+      if (event.timestamp >= since) {
+        counts[event.type] = (counts[event.type] ?? 0) + 1;
+      }
+    }
+
+    return counts;
+  }
+
+  /**
+   * Clear event history (useful for testing)
+   */
+  clearHistory(): void {
+    this.history = [];
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SINGLETON INSTANCE
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _bus: ImmortalEventBus | null = null;
+
+export function getEventBus(): ImmortalEventBus {
+  if (!_bus) {
+    _bus = new ImmortalEventBus();
+  }
+  return _bus;
+}
+
+export function resetEventBus(): void {
+  _bus = null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPE GUARD
+// ─────────────────────────────────────────────────────────────────────────────
+
+const IMMORTAL_EVENT_TYPES = new Set<string>([
+  "error:captured", "error:escalated",
+  "retry:attempt", "retry:exhausted", "retry:success",
+  "circuit:opened", "circuit:closed", "circuit:half-open", "circuit:rejected",
+  "bulkhead:queued", "bulkhead:rejected", "bulkhead:timeout",
+  "worker:started", "worker:restarted", "worker:escalated", "worker:crashed",
+  "memory:warning", "memory:critical", "memory:leak-detected", "memory:proactive-restart",
+  "eventloop:lag-warning", "eventloop:lag-critical",
+  "cpu:warning", "cpu:critical",
+  "shutdown:initiated", "shutdown:complete", "shutdown:forced",
+  "fallback:cache-hit", "fallback:default-used",
+  "chaos:latency-injected", "chaos:error-injected", "chaos:worker-killed",
+]);
+
+function isImmortalEventType(type: string): type is ImmortalEventType {
+  return IMMORTAL_EVENT_TYPES.has(type);
+}