immortal-js 1.0.0

package/packages/core/src/types.ts

@@ -0,0 +1,470 @@
+/**
+ * @file types.ts
+ * @description Central type definitions for Immortal.js core
+ * All interfaces, enums, and shared types live here for cross-module consistency
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CORE CONFIGURATION TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ImmortalConfig {
+  /** Safe zone configuration — controls error containment behavior */
+  safeZone?: SafeZoneConfig;
+  /** Retry engine configuration */
+  retry?: RetryConfig;
+  /** Circuit breaker configuration */
+  circuitBreaker?: CircuitBreakerConfig;
+  /** Bulkhead isolation pools */
+  bulkhead?: Record<string, BulkheadConfig>;
+  /** Supervisor configuration */
+  supervisor?: SupervisorConfig;
+  /** Health monitoring configuration */
+  healthMonitor?: HealthMonitorConfig;
+  /** Memory leak guard configuration */
+  memoryGuard?: MemoryGuardConfig;
+  /** Graceful shutdown configuration */
+  gracefulShutdown?: GracefulShutdownConfig;
+  /** Dashboard configuration */
+  dashboard?: DashboardConfig;
+  /** Plugin registry */
+  plugins?: ImmortalPlugin[];
+  /** Chaos testing — only active if NODE_ENV !== 'production' */
+  chaos?: ChaosConfig;
+  /** Logging configuration */
+  logger?: LoggerConfig;
+}
+
+export interface SafeZoneConfig {
+  /** Enable automatic wrapping of all route handlers */
+  autoWrap?: boolean;
+  /** Custom fallback response generator */
+  defaultFallback?: FallbackGenerator;
+  /** Expose error details in response (never in production) */
+  exposeErrors?: boolean;
+  /** Sanitize sensitive fields from error logs */
+  sanitizeFields?: string[];
+}
+
+export interface RetryConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+  /** Base delay in milliseconds for exponential backoff (default: 200) */
+  baseDelayMs?: number;
+  /** Maximum delay cap in milliseconds (default: 10_000) */
+  maxDelayMs?: number;
+  /** Jitter factor 0-1 (default: 0.3) */
+  jitterFactor?: number;
+  /** Custom function to determine if error is retryable */
+  isRetryable?: (error: unknown) => boolean;
+  /** Global retry budget (max retries per second across all calls) */
+  retryBudget?: number;
+}
+
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit (default: 5) */
+  threshold?: number;
+  /** Cooldown period in ms before attempting half-open (default: 15_000) */
+  cooldownMs?: number;
+  /** Sliding window size for failure rate calculation (default: 100) */
+  slidingWindowSize?: number;
+  /** Minimum requests before circuit can open (default: 10) */
+  minimumRequests?: number;
+  /** Failure rate percentage to open circuit (default: 50) */
+  failureRateThreshold?: number;
+}
+
+export interface BulkheadConfig {
+  /** Maximum concurrent operations (default: 10) */
+  maxConcurrent?: number;
+  /** Maximum queue size before rejection (default: 50) */
+  maxQueueSize?: number;
+  /** Timeout for queued operations in ms (default: 30_000) */
+  queueTimeoutMs?: number;
+  /** Priority levels: 'high' | 'medium' | 'low' */
+  enablePriority?: boolean;
+}
+
+export type RestartStrategy = "one_for_one" | "one_for_all" | "rest_for_one";
+
+export interface SupervisorConfig {
+  /** Restart strategy (default: 'one_for_one') */
+  strategy?: RestartStrategy;
+  /** Max restarts within time window (default: 5) */
+  maxRestartsInWindow?: number;
+  /** Time window in ms for restart counting (default: 60_000) */
+  windowMs?: number;
+  /** Base delay before first restart in ms (default: 100) */
+  baseRestartDelayMs?: number;
+  /** Enable cluster mode (multi-process) */
+  clusterMode?: boolean;
+  /** Number of cluster workers (default: os.cpus().length) */
+  clusterWorkers?: number;
+}
+
+export interface HealthMonitorConfig {
+  /** Monitoring interval in ms (default: 5_000) */
+  intervalMs?: number;
+  /** P99 event loop lag threshold in ms before warning (default: 100) */
+  eventLoopLagMs?: number;
+  /** P99 event loop lag threshold for critical action (default: 500) */
+  criticalLagMs?: number;
+  /** CPU usage % threshold for warning (default: 80) */
+  cpuWarningPercent?: number;
+  /** CPU usage % threshold for critical (default: 95) */
+  cpuCriticalPercent?: number;
+}
+
+export interface MemoryGuardConfig {
+  /** Check interval in ms (default: 10_000) */
+  checkIntervalMs?: number;
+  /** Heap usage MB that triggers warning (default: 1024) */
+  warningThresholdMb?: number;
+  /** Heap usage MB that triggers proactive restart (default: 1500) */
+  restartThresholdMb?: number;
+  /** Number of consecutive windows showing growth before action (default: 3) */
+  growthWindowCount?: number;
+  /** Enable WeakRef tracking for specific object types */
+  enableObjectTracking?: boolean;
+  /** Enable adaptive thresholds based on system RAM */
+  adaptiveThresholds?: boolean;
+}
+
+export interface GracefulShutdownConfig {
+  /** Grace period in ms before forced kill (default: 20_000) */
+  timeoutMs?: number;
+  /** Signals to listen for (default: ['SIGTERM', 'SIGINT']) */
+  signals?: NodeJS.Signals[];
+  /** Custom cleanup functions to run during shutdown */
+  onShutdown?: ShutdownHook[];
+}
+
+export interface DashboardConfig {
+  /** Enable dashboard (default: true) */
+  enabled?: boolean;
+  /** Dashboard port (default: 9999) */
+  port?: number;
+  /** Dashboard path prefix (default: '/__immortal') */
+  path?: string;
+  /** Enable WebSocket real-time feed */
+  enableWebSocket?: boolean;
+  /** Enable Server-Sent Events feed */
+  enableSSE?: boolean;
+  /** Enable OpenTelemetry export */
+  enableOTLP?: boolean;
+  /** OTLP endpoint (e.g. Grafana, Datadog) */
+  otlpEndpoint?: string;
+  /** Prometheus metrics endpoint */
+  enablePrometheus?: boolean;
+  /** Basic auth for dashboard */
+  auth?: { username: string; password: string };
+}
+
+export interface ChaosConfig {
+  /** Enable chaos mode (NEVER in production — enforced) */
+  enabled?: boolean;
+  /** Probability 0-1 of injecting latency per request */
+  latencyProbability?: number;
+  /** Latency range in ms [min, max] */
+  latencyRange?: [number, number];
+  /** Probability 0-1 of throwing random errors */
+  errorProbability?: number;
+  /** Probability 0-1 of killing a worker */
+  workerKillProbability?: number;
+  /** Memory pressure simulation MB */
+  memoryPressureMb?: number;
+  /** Specific routes to target (empty = all routes) */
+  targetRoutes?: string[];
+}
+
+export interface LoggerConfig {
+  /** Log level (default: 'info') */
+  level?: "debug" | "info" | "warn" | "error" | "silent";
+  /** Custom log transport */
+  transport?: LogTransport;
+  /** Redact sensitive fields */
+  redact?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EVENTS & METRICS TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ImmortalEventType =
+  | "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";
+
+export interface ImmortalEvent {
+  type: ImmortalEventType;
+  timestamp: number;
+  workerId?: string | number;
+  requestId?: string;
+  route?: string;
+  service?: string;
+  data?: Record<string, unknown>;
+  error?: SerializedError;
+}
+
+export interface SerializedError {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string;
+  statusCode?: number;
+  isOperational?: boolean;
+  context?: Record<string, unknown>;
+}
+
+export interface SystemMetrics {
+  timestamp: number;
+  eventLoopLag: {
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+  };
+  memory: {
+    heapUsedMb: number;
+    heapTotalMb: number;
+    externalMb: number;
+    rssMb: number;
+    heapGrowthRate: number; // MB per minute
+    gcFrequency: number;    // GCs per minute
+  };
+  cpu: {
+    percentUser: number;
+    percentSystem: number;
+  };
+  handles: {
+    active: number;
+  };
+  requests: {
+    total: number;
+    active: number;
+    perSecond: number;
+    errorRate: number; // 0-1
+  };
+  circuits: Record<string, CircuitBreakerStatus>;
+  bulkheads: Record<string, BulkheadStatus>;
+  workers: WorkerStatus[];
+}
+
+export interface CircuitBreakerStatus {
+  name: string;
+  state: "CLOSED" | "OPEN" | "HALF_OPEN";
+  failures: number;
+  successes: number;
+  totalRequests: number;
+  failureRate: number;
+  lastFailureTime: number;
+  lastStateChange: number;
+}
+
+export interface BulkheadStatus {
+  name: string;
+  active: number;
+  queued: number;
+  maxConcurrent: number;
+  maxQueueSize: number;
+  rejected: number;
+  totalExecuted: number;
+}
+
+export interface WorkerStatus {
+  id: string | number;
+  pid?: number;
+  state: "running" | "restarting" | "stopped" | "escalated";
+  restartCount: number;
+  lastRestartTime?: number;
+  uptime: number;
+  memoryMb?: number;
+  cpuPercent?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FUNCTIONAL TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type FallbackGenerator<T = unknown> = (
+  error: unknown,
+  context: RequestContext
+) => T | Promise<T>;
+
+export interface RequestContext {
+  requestId: string;
+  route?: string;
+  method?: string;
+  startedAt: number;
+  attempt?: number;
+  workerId?: string | number;
+  custom?: Record<string, unknown>;
+}
+
+export type ShutdownHook = (signal: string) => Promise<void> | void;
+
+export interface LogTransport {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PLUGIN SYSTEM TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ImmortalPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  /** Called once during immortal initialization */
+  onInit?: (context: PluginContext) => Promise<void> | void;
+  /** Called before each request */
+  onRequest?: (context: RequestContext) => Promise<void> | void;
+  /** Called after successful response */
+  onResponse?: (context: RequestContext, durationMs: number) => Promise<void> | void;
+  /** Called when an error is captured */
+  onError?: (error: unknown, context: RequestContext) => Promise<void> | void;
+  /** Called on every metrics tick */
+  onMetrics?: (metrics: SystemMetrics) => Promise<void> | void;
+  /** Called during graceful shutdown */
+  onShutdown?: ShutdownHook;
+}
+
+export interface PluginContext {
+  config: ImmortalConfig;
+  emit: (event: ImmortalEvent) => void;
+  getMetrics: () => SystemMetrics;
+  logger: LogTransport;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PRIORITY TYPES FOR BULKHEAD
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type Priority = "critical" | "high" | "medium" | "low";
+
+export interface PriorityTask<T> {
+  task: () => Promise<T>;
+  priority: Priority;
+  timeoutMs?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ERROR TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ImmortalError extends Error {
+  public readonly isOperational: boolean;
+  public readonly code: string;
+  public readonly context?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    code: string,
+    isOperational = true,
+    context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "ImmortalError";
+    this.code = code;
+    this.isOperational = isOperational;
+    if (context !== undefined) this.context = context;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class BulkheadRejectedError extends ImmortalError {
+  constructor(poolName: string, reason: "saturated" | "timeout" = "saturated") {
+    super(
+      `Bulkhead pool '${poolName}' rejected request: ${reason}`,
+      "BULKHEAD_REJECTED",
+      true,
+      { poolName, reason }
+    );
+    this.name = "BulkheadRejectedError";
+  }
+}
+
+export class CircuitOpenError extends ImmortalError {
+  constructor(circuitName: string) {
+    super(
+      `Circuit breaker '${circuitName}' is OPEN — request rejected`,
+      "CIRCUIT_OPEN",
+      true,
+      { circuitName }
+    );
+    this.name = "CircuitOpenError";
+  }
+}
+
+export class RetryExhaustedError extends ImmortalError {
+  public readonly attempts: number;
+  public readonly lastError: unknown;
+
+  constructor(attempts: number, lastError: unknown) {
+    super(
+      `Retry exhausted after ${attempts} attempts`,
+      "RETRY_EXHAUSTED",
+      true,
+      { attempts }
+    );
+    this.name = "RetryExhaustedError";
+    this.attempts = attempts;
+    this.lastError = lastError;
+  }
+}
+
+export class WorkerEscalatedError extends ImmortalError {
+  constructor(workerId: string, restartCount: number) {
+    super(
+      `Worker '${workerId}' escalated after ${restartCount} restarts — requires manual intervention`,
+      "WORKER_ESCALATED",
+      false,
+      { workerId, restartCount }
+    );
+    this.name = "WorkerEscalatedError";
+  }
+}
+
+export class TimeoutError extends ImmortalError {
+  constructor(operationName: string, timeoutMs: number) {
+    super(
+      `Operation '${operationName}' timed out after ${timeoutMs}ms`,
+      "OPERATION_TIMEOUT",
+      true,
+      { operationName, timeoutMs }
+    );
+    this.name = "TimeoutError";
+  }
+}